Work Graph Playground

The Work Graph Playground is a DirectX12-based C++-application that allows graphics programmers to learn and experiment with the new Work Graphs feature using HLSL shaders. It runs on Windows 10 and Windows 11 systems.

Work Graphs

Work Graphs is a Graphics-API feature released in March 2024 for DirectX12. In a nutshell, with Work Graphs, shaders can dynamically schedule new workloads at runtime directly from the GPU. Prior to Work Graphs, all GPU workloads had to be scheduled by the CPU. Therefore, Work Graphs can reduce memory requirements, improve caching behavior, better utilize compute resources, reduce communication-needs between CPU-and-GPU, and simplify synchronization.

From a programmer's perspective, Work Graphs extend the host-side of the API, but for most of the time, programmers deal with the shader-code part introduced with Work Graphs.

Tutorials

We provide several tutorials to walk you through the HLSL-usage of Work Graphs. As most of the power of Work Graphs is unleashed through HLSL, our tutorials focus on the HLSL aspects of Work Graphs. Our Work Graph Playground frees you from dealing with the host-side of Work Graphs. However, you can use our host-side code as a reference for integrating Work Graphs in your own projects.

In each tutorial, we cover one aspect of Work Graphs. The tutorials build upon each other, so we recommend taking them one-by-one. You need just a few prerequisites to run the tutorials.

By the end of the tutorials, if not even earlier, you should be inspired to create your own Work Graphs samples and grow from there! If you want to experiment with Work Graphs, check out Adding new tutorials below on how to add your own samples or tutorials to the playground application. Be sure to check out the additional resources and samples linked below if you wish to learn more about Work Graphs.

Prerequisites

As a person taking this tutorial, you need to know HLSL, C++, Direct3D12, and have a basic understanding of how GPU compute shaders work.

Besides a computer, you need:

A text/code editor of your choice
A Windows version that supports the Microsoft Agility SDK
Optional: Graphics diagnostic tools for debugging.

To run the sample directly, you'll also need a GPU and driver with D3D12 Work Graphs 1.0 support. You can learn more about D3D12 Work Graphs 1.0 and driver availability on Microsoft's blog post or on our own blog post on GPUOpen.com.

Running on GPUs without Work Graphs support

If your GPU does not support Work Graphs, you can download and install the DirectX WARP adapter by running the DownloadWarpAdapter.bat, which is included in the pre-built binaries. The script performs the following steps:

Download the Microsoft.Direct3D.WARP 1.0.14.2 NuGet package. If you wish to use the mesh nodes feature, download version 1.0.14.1-preview instead.

BY INSTALLING THE THIRD-PARTY SOFTWARE, YOU AGREE TO BE BOUND BY THE LICENSE AGREEMENT(S) APPLICABLE TO SUCH SOFTWARE and you agree to carefully review and abide by the terms and conditions of all license(s) that govern such software.
Change the file extension to .zip, such that the full filename is microsoft.direct3d.warp.1.0.14.2.zip or microsoft.direct3d.warp.1.0.14.1-preview.zip if you downloaded the version for mesh nodes.
Open or extract the zip file, locate the d3d10warp.dll in build/native/bin/x64, and copy it next to the WorkGraphPlayground.exe.

If you're building the application from source, the steps above are automated by the CMake build script.

Running Tutorials

Download the latest release from here or follow the instructions for building the application from source. Start the WorkGraphPlayground.exe either directly or from the command line.

You can pass the following options to WorkGraphPlayground.exe:

--forceWarpAdapter uses the WARP adapter, even if your GPU does support Work Graphs. If you're using pre-built binaries, you'll need to download and install the WARP adapter first. See instructions above.
--enableDebugLayer to enable the D3D12 Debug Layer (recommended).
--enableGpuValidationLayer to turn on D3D12 GPU validation.

You should see the following application window:

The tutorials only consist of HLSL shader code and are located in the tutorials folder. The shader files are automatically reloaded at runtime whenever any changes are detected, meaning you don't have to restart the application whenever you modify the shader source code. You will see this in action in the first tutorial.

If the shader compilation fails, the previous (successfully) compiled shader code is used. Any error messages or other output from the shader compiler are displayed in the application output log.

We recommend running the app with the --enableDebugLayer command-line argument to also see any further error messages from the D3D12 debug layer. Note that Graphics diagnostic tools must be installed in order to enable the debug layer.

0. Hello Work Graphs

Tutorial file

Description: This is a minimal introductory tutorial. You get acquainted with our tutorial playground and two very simple Work Graphs nodes. Your task is to launch one worker node from the entry node and print your name from the worker node. You can directly edit the shader file in an editor of your choice. Upon saving, you experience that our playground will automatically reload and recompile your changes made in the shader file.

Learning Outcome: You get a feeling for our playground application, shader hot reloading, and reassure that our tutorials run on your device. You learn how to

mark HLSL functions as Work Graphs nodes with Shader("node")
add further attributes to shader functions, and
get a first glimpse on how to invoke other nodes

References to Specification:

Shader Target
Shader Function Attributes
See EmptyNodeOutput in Node output declaration

1. Records

Tutorial file | Sample Solution

Description: Work Graphs use records to model data-flow. Records serve as inputs and outputs of nodes. In this tutorial, you emit records at a producer node and receive it at different consumer nodes. Your producer node issues multiple consumer nodes that render different things. You parameterize the nodes with records.

Learning Outcome: Besides getting a better understanding of how EmptyNodeOutput works, you learn how to

declare non-empty records with NodeOutput at a producer node;
use the MaxRecords attribute to cap the number of record outputs at compile time;
identify situations when to use GroupNodeOutputRecords and ThreadNodeOutputRecords to output records;
output records during runtime with GroupIncrementOutputCount;ThreadIncrementOutputCount, and OutputComplete;
obtain zero or one output record with GetThreadNodeOutputRecords (per thread) GetGroupNodeOutputRecords (per thread-group);
obtain records at a receiving node with ThreadNodeInputRecord; and
read and write data to records with the Get()-method or the []-operator.