Getting started

State object creation

Creating the work graph state object with mesh nodes is in large parts the same as before and we’ll skip over most of the steps here and only focus on mesh node specific changes.

CD3DX12_STATE_OBJECT_DESC stateObjectDesc(D3D12_STATE_OBJECT_TYPE_EXECUTABLE);

We can use the IncludeAllAvailableNodes() function or D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES flag to enable auto-population of all available nodes into our work graph. We’ll see later on how this auto-population interacts with the new mesh nodes.

CD3DX12_WORK_GRAPH_SUBOBJECT* workGraphDesc = stateObjectDesc.CreateSubobject<CD3DX12_WORK_GRAPH_SUBOBJECT>();
workGraphDesc->IncludeAllAvailableNodes();
workGraphDesc->SetProgramName(ProgramName);

A DirectX® 12 command list tracks resource bindings to shaders separately for compute pipelines (i.e., commandList->SetComputeRoot*(...)) and graphics pipelines (i.e., commandList->SetGraphicsRoot*(...)) with two separate root signatures. Up until now, work graphs only consisted of compute nodes (i.e., compute shaders) and thus resource bindings were set through the compute root signature. With the addition of mesh nodes, a work graph can now also contain graphics nodes, and thus when this is the case, the entire work graph must use the graphics root arguments for its global root signature and not the compute root arguments. This is indicated by setting the WORK_GRAPHS_USE_GRAPHICS_STATE_FOR_GLOBAL_ROOT_SIGNATURE state object flag.

auto configSubobject = stateObjectDesc.CreateSubobject<CD3DX12_STATE_OBJECT_CONFIG_SUBOBJECT>();
configSubobject->SetFlags(D3D12_STATE_OBJECT_FLAG_WORK_GRAPHS_USE_GRAPHICS_STATE_FOR_GLOBAL_ROOT_SIGNATURE);

Of course, mesh nodes can – in contrast to regular mesh shaders – also use local root signatures in addition to the global root signature of the work graph. The process of setting the local root arguments (for compute and mesh nodes) through the D3D12_SET_WORK_GRAPH_DESC and binding them to nodes through [NodeLocalRootArgumentsTableIndex()] remains unchanged.

Shader libraries

Next, we can add the two binary shader blobs we compiled earlier to our work graph. For the work graph library, i.e., the one compiled with lib_6_9, everything remains the same. This will add all the regular compute nodes and the mesh nodes in our shader source to the state object.

{
    CD3DX12_DXIL_LIBRARY_SUBOBJECT* libraryDesc = stateObjectDesc.CreateSubobject<CD3DX12_DXIL_LIBRARY_SUBOBJECT>();
    CD3DX12_SHADER_BYTECODE libraryCode(workGraphBlob);
    libraryDesc->SetDXILLibrary(&libraryCode);
}

Next, we can add the pixel shader library in the same way. This will add the MeshNodePixelShader pixel shader to our state object.

{
    CD3DX12_DXIL_LIBRARY_SUBOBJECT* libraryDesc = stateObjectDesc.CreateSubobject<CD3DX12_DXIL_LIBRARY_SUBOBJECT>();
    CD3DX12_SHADER_BYTECODE libraryCode(pixelShaderBlob);
    libraryDesc->SetDXILLibrary(&libraryCode);
}

Generic programs

Graphics pipelines do not only define the combination of shaders to be executed in the various pipeline stages, but also define additional state, such as render targets, rasterizer state, or blend state.

For mesh shaders, this state is set in the D3DX12_MESH_SHADER_PIPELINE_STATE_DESC description.

For mesh nodes, the process of setting both the mesh and pixel shader, as well as all the additional graphics pipeline state is done through generic programs.

Unlike the pipeline state description structs for graphics pipelines, which define the entire pipeline state in one struct, generic programs offer a modular approach to defining a graphics pipeline. Each generic program in our work graph is defined by a CD3DX12_GENERIC_PROGRAM_SUBOBJECT in our state object description, to which we’ll add different shaders through exports and describe the pipeline state through a collection of other subobjects.

By default, each generic program subobject will auto-populate to a single mesh node in our work graph, if D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES is set, but we can also use explicit node overrides to define multiple mesh nodes from the same generic program.

auto genericProgramSubobject = stateObjectDesc.CreateSubobject<CD3DX12_GENERIC_PROGRAM_SUBOBJECT>();

As we’ve already added the binary shader code for both the mesh and pixel shader above, we can reference them by their export names and add them to the generic program subobject. In both cases, the export name is the function name of the respective shader. Each mesh or pixel shader can be referenced multiple times to build different mesh shader pipelines.

genericProgramSubobject->AddExport(L"LineMeshShader");
genericProgramSubobject->AddExport(L"MeshNodePixelShader");

To define the rest of the graphics pipeline state, such as render targets, rasterizer state, or blend state, we can add different subobjects to our generic program through genericProgramSubobject->AddSubobject(...);. Each of these state-defining subobjects must also be contained within the state object description for our work graph.

As an example, we’ll add a CD3DX12_RENDER_TARGET_FORMATS_SUBOBJECT and define the render target format state based on our swapchain.

auto renderTargetFormatSubobject = stateObjectDesc.CreateSubobject<CD3DX12_RENDER_TARGET_FORMATS_SUBOBJECT>();
renderTargetFormatSubobject->SetNumRenderTargets(1);
renderTargetFormatSubobject->SetRenderTargetFormat(0, DXGI_FORMAT_R8G8B8A8_UNORM);

Similar to the mesh and pixel shaders, these subobjects can be added to multiple different generic program subobjects within the same state object description. You can think of these as modular building blocks, with which you can assemble different graphics pipelines based on your needs.

Other “building blocks”, such as rasterizer-, blend-, or depth-stencil state can be created and configured in the same way. You can find a full list of the supported subobjects in generic programs here. If a generic program does not contain a subobject – or “building block” – for a particular part of the pipeline state, a default value is used instead.

Once we created all the “building blocks” for our generic program, we can add them as follows:

// Add "building blocks" to define the graphics pipeline state for our mesh node
genericProgramSubobject->AddSubobject(*rasterizerSubobject);
genericProgramSubobject->AddSubobject(*depthStencilSubobject);
genericProgramSubobject->AddSubobject(*depthStencilFormatSubobject);
genericProgramSubobject->AddSubobject(*renderTargetFormatSubobject);
...

With this, we successfully created a generic program for our mesh node. As we set the D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES through workGraphDesc->IncludeAllAvailableNodes();, this generic program will be automatically added to the work graph. The node identifier for this node is defined by the [NodeId(...)] attribute of our mesh shader, or, if this attribute is not set, by the name of our mesh shader function. Alternatively, we can also override the mesh node id, which we’ll look at in the next section.

If D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES is not used, we have to explicitly add our mesh node to the work graph. For mesh nodes, this is done with workGraphDesc->CreateProgramNode(...) and not workGraphDesc->CreateShaderNode(...), which is used for regular compute nodes.

In order to add our mesh node, we first need to name our generic program subobject. This name is purely for identification purposes and must be unique inside the state object description.

genericProgramSubobject->SetProgramName(L"TriangleMeshNodeGenericProgram");
workGraphDesc->CreateProgramNode(L"TriangleMeshNodeGenericProgram");

Alternatively, we can also specify a mesh node override, to add the mesh node to the graph.

Mesh node overrides

Even if D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES is used, mesh nodes can still be modified and renamed through mesh node overrides when creating the work graph. This can be useful, if, e.g., the same mesh shader is used in multiple mesh nodes, and thus the auto-populated node id (either the function name or the [NodeId(...)] attribute) are no longer unique in the graph.

Similar to the explicit mesh nodes created through CreateProgramNode, we first need to give our generic program a unique name. We can then create a mesh node override in the work graph description for that name. With this override, we can set the node id and/or change other node attributes, such as the dispatch grid or input record sharing.

genericProgramSubobject->SetProgramName(L"TriangleMeshNodeGenericProgram");

auto nodeOverride = workGraphDesc->CreateMeshLaunchNodeOverrides(L"TriangleMeshNodeGenericProgram");
nodeOverride->NewName({ L"TriangleMeshNode", 0 });

With the Agility SDK version 1.715.0-preview as well as version 1.614.1, the behavior of node overrides in combination with D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES has changed slightly. If a node override specifies a new node id through nodeOverride->NewName(...), the original auto-populated node is removed from the graph. This applies to both mesh nodes and compute nodes.

In the case of the HelloMeshNodes sample, the TriangleMeshShader does not have a [NodeId(...)] attribute and the work graph is using the D3D12_WORK_GRAPH_FLAG_INCLUDE_ALL_AVAILABLE_NODES flag. Defining a generic program with this mesh shader will auto-populate a node with node id {L"TriangleMeshShader", 0}. As the same generic program is part of a mesh node override with name override, this node is removed from the graph and the explicitly defined node with node id {L"TriangleMeshNode", 0} is added.

Mesh node draw order

As work graphs enable fully dynamic scheduling of GPU work on the GPU, without any barriers, the execution order of this scheduled work is not deterministic and may change from one execution to another. For mesh nodes, this means that there is also no guaranteed order in which the different mesh nodes and their records are executed.

For some use-cases, mesh nodes can also be used as ExecuteIndirect++. This means that a subset of the mesh nodes are entry nodes to the work graph and receive their records from either CPU or GPU input. In this case, the application can set the D3D12_WORK_GRAPH_FLAG_ENTRYPOINT_GRAPHICS_NODES_RASTERIZE_IN_ORDER flag to enable deterministic ordering of entry mesh nodes.

// Sets D3D12_WORK_GRAPH_FLAG_ENTRYPOINT_GRAPHICS_NODES_RASTERIZE_IN_ORDER
workGraphDesc->EntrypointGraphicsNodesRasterizeInOrder();

This way, applications can use mesh nodes in an ExecuteIndirect-like way – but with pipeline state object switching – and they can also dispatch other compute nodes to be scheduled in parallel to the mesh nodes. However, any draws resulting from those compute nodes will not have any guaranteed ordering.

If you do not require a deterministic rasterization order for your entry mesh nodes, we recommend to not set this flag. Omitting this flag can enable certain optimizations for entry node scheduling.

Runtime hints

On some vendor-specific mesh node implementations, the switch between the compute context for regular nodes and the graphics context for mesh nodes might be quite expensive. To minimize the number of such transitions, the runtime may choose to reduce back-pressure from mesh nodes and queue up a larger amount of mesh node records at a time. To accurately calculate the required memory for these queues, the runtime needs additional information about the work graph through the newly introduced SetMaximumInputRecords function and [NodeMaxInputRecordsPerGraphEntryRecord(...)] attribute.

Note: These runtime hints are not required by AMD GPUs. Ideally, these hints will not be needed long-term and be removed by the end of the preview phase. That said, if you intend to run your mesh nodes on GPUs of other vendors, we still recommend you to set accurate limits here, and we outline some tips for determining these values in the tips, tricks & best practices section.

Here, we’ll only focus on the SetMaximumInputRecords function, as this is actually mandatory for work graphs that use mesh nodes. The optional [NodeMaxInputRecordsPerGraphEntryRecord(...)] will be covered in the tips, tricks & best practices section. SetMaximumInputRecords is available though the ID3D12WorkGraphProperties1 interface, which replaces the ID3D12WorkGraphProperties interfaces that was previously used to query the backing memory size.

CComPtr<ID3D12WorkGraphProperties1> workGraphProperties;
stateObject->QueryInterface(IID_PPV_ARGS(&workGraphProperties));

SetMaximumInputRecords sets limits for both the maximum number of node inputs, i.e., how many (different) nodes will be invoked when using D3D12_DISPATCH_MODE_MULTI_NODE_CPU_INPUT as the graph dispatch mode, as well as the maximum number of records that will be passed to the graph, totalled across all nodes. This function must be called before calling workGraphProperties->GetWorkGraphMemoryRequirements(...). In the case of the HelloMeshNodes sample, we only have one entry node with only one record.

const auto workGraphIndex = workGraphProperties->GetWorkGraphIndex(ProgramName);
workGraphProperties->SetMaximumInputRecords(workGraphIndex, /* MaxRecords */ 1, /* MaxNodeInputs */ 1);

As this function only affects the backing memory and not the actual compiled graph, we can update these limits later during run-time, if, e.g., more input records are required. Changing these limits will require querying the backing memory size and re-allocating backing memory. Changes to backing memory also requires re-initializing the backing memory using the D3D12_SET_WORK_GRAPH_FLAG_INITIALIZE flag.