Chains of graphs

Requirements

Requirement: Ordered execution of compiled graphs REQ_GRAPH_CHAIN_ORDER
status: implemented
is implemented by: SPEC_GRAPH_CHAIN_SUBMIT
is verified by: TEST_GRAPH_CHAIN_ORDER

The engine shall support an ordered chain of already compiled graphs. Each link shall see the results of the preceding links, without CPU submissions or waits between links.

Requirement: Repeated graphs REQ_GRAPH_CHAIN_REPEAT
status: implemented
is implemented by: SPEC_GRAPH_CHAIN_REPEAT

A chain shall support executing the same graph path more than once. Every occurrence shall execute, using the results of the preceding links.

Requirement: Reusable chains REQ_GRAPH_CHAIN_REUSE
status: implemented
is implemented by: SPEC_GRAPH_CHAIN_SUBMIT
is verified by: TEST_GRAPH_CHAIN_REUSE

A chain shall be reusable after its previous submission has finished, using updated inputs without recompiling its graphs or recording new command buffers.

Requirement: Data shared between graphs REQ_GRAPH_CHAIN_SHARED_DATA
status: implemented

Graphs in a chain shall be able to share buffers, so that a result produced by one graph can be used by a later graph without copying it through the CPU. Compiling a later graph shall preserve the shared buffers and their contents.

Requirement: Separate paths in flight REQ_GRAPH_CHAIN_PATHS
status: implemented

Chains using different paths of the same graphs shall be able to have submissions in flight at the same time. Each path shall use its own per-path buffers without overwriting another path’s data.

Specifications

Specification: Submit the chain as one batch SPEC_GRAPH_CHAIN_SUBMIT

GraphChain stores a sequence of graph and path pairs. It submits their recorded command buffers in one vkQueueSubmit, with a semaphore between consecutive links and a fence for completion of the whole chain. wait() waits for that fence. Submitting the same chain again waits for its previous submission before reusing its synchronization objects.

Specification: Simultaneous use for repeated graph paths SPEC_GRAPH_CHAIN_REPEAT

A graph path that occurs more than once in a chain must have been compiled after enableSimultaneousUse(), which records its command buffer with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT. GraphChain::add() rejects a repeated graph path without this flag.

Specification: Reuse shared buffer allocations SPEC_GRAPH_CHAIN_BUFFERS

A BufferElement shared by several graphs is allocated by the first graph that compiles it. Later graphs reuse those allocations and must have the same number of paths. Each path keeps its own allocation, and a chain link selects which path of its graph runs.

Tests

Test: Repeated graph paths require simultaneous use TEST_GRAPH_CHAIN_REPEAT_GUARD
status: verified
gtest: GraphChain.repeatedGraphNeedsSimultaneousUse

Adding the same graph path twice throws unless the graph was compiled after enableSimultaneousUse().

Test: Every occurrence of a graph executes TEST_GRAPH_CHAIN_REPEAT_EXECUTES
status: verified
gtest: GraphChain.repeatedGraphRunsEveryTime

Runs a graph that doubles a buffer four times in one chain and checks that the result is sixteen times the input.

Test: Links execute in chain order TEST_GRAPH_CHAIN_ORDER
status: verified
gtest: GraphChain.linksRunInChainOrder

Chains graphs that double a shared buffer or add one to it. Changing their order changes the result as expected.

Test: Reuse a chain across frames TEST_GRAPH_CHAIN_REUSE
status: verified
gtest: GraphChain.chainRunsEveryFrame

Submits the same chain for several frames, replacing its input between submissions, and checks the result of each frame.

Test: Shared buffers are allocated once TEST_GRAPH_CHAIN_SHARED_BUFFERS
status: verified
gtest: GraphChain.sharedBufferElementAllocatedOnce

Compiles two graphs sharing a per-path BufferElement and checks that the second graph preserves the first graph’s buffer handles. Compiling another graph with a different number of paths throws.

Test: Paths in flight keep separate data TEST_GRAPH_CHAIN_PATHS
status: verified
gtest: GraphChain.pathsInFlightStaySeparate

Submits two chains over different paths of the same graphs before waiting for either chain. Both paths compute the expected result from their own input buffers.