Skip to content

Commit

Permalink
minor API documentation fix to match actual headers
Browse files Browse the repository at this point in the history
  • Loading branch information
Amar Patel committed Oct 5, 2023
1 parent 6a5d371 commit 3d93724
Showing 1 changed file with 10 additions and 3 deletions.
13 changes: 10 additions & 3 deletions d3d/WorkGraphs.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<h1>D3D12 Work Graphs</h1>
v0.45 9/22/2023
v0.46 10/5/2023

> To see the state the spec was in for the June 2023 Work Graphs preview, see the archived v0.43 spec [here](https://github.com/microsoft/DirectX-Specs/blob/preview-2023-06/d3d/WorkGraphs.md).
> The [Change log](#change-log) in this document shows changes since then on the path to future final (non-preview) release.
Expand Down Expand Up @@ -1550,7 +1550,7 @@ Memory in individual records is only initialized when a shader writes to it as p

### Discovering backing memory size requirements

The system looks at the work graph configuration and gives the app a range of backing memory sizes that will work for it, communicated as a min, max and increment size. The minimum size the system reports will guarantee that work submitted to the work graph will complete. The exception is misbehaved app, such as having an infinite loop in a shader or a shader violating its promises and trying to output more than it declared. If an app can afford to allocate a backing store that is larger than the minimum, the work graph may be able to execute more efficiently.
The system looks at the work graph configuration and gives the app a range of backing memory sizes that will work for it. This is communicated as a min, max and size granularity (meaning sizes larger than min are larger by a multiple of this value). The minimum size the system reports will guarantee that work submitted to the work graph will complete. The exception is misbehaved app, such as having an infinite loop in a shader or a shader violating its promises and trying to output more than it declared. If an app can afford to allocate a backing store that is larger than the minimum, the work graph may be able to execute more efficiently.

See [GetWorkGraphMemoryRequirements()](#getworkgraphmemoryrequirements).

Expand Down Expand Up @@ -3194,10 +3194,16 @@ typedef struct D3D12_WORK_GRAPH_MEMORY_REQUIREMENTS
{
UINT64 MinSizeInBytes;
UINT64 MaxSizeInBytes;
UINT SizeAlignmentInBytes;
UINT SizeGranularityInBytes;
} D3D12_WORK_GRAPH_MEMORY_REQUIREMENTS;
```

Member | Definition
--------- | ----------
`MinSizeInBytes` | Minimum size the driver needs for backing memory.
`MaxSizeInBytes` | Maximum size the driver would be able to make use of for backing memory.
`SizeGranularityInBytes` | Sizes that the driver can use that are larger than `MinSizeInBytes` are larger by a multiple of `SizeGranularityInBytes`. The application can provide sizes for backing memory that are larger than `MinSizeInBytes` + an integer multiple of `SizeGranularityInBytes`, or larger than `MaxSizeInBytes`, but it simply wastes memory as the driver won't touch memory beyond the size range and granularity specifications here.

Referenced by [GetWorkGraphMemoryRequirements](#getworkgraphmemoryrequirements).

---
Expand Down Expand Up @@ -6158,3 +6164,4 @@ v0.42|6/12/2023|<li>In [Shader function attributes](#shader-function-attributes)
v0.43|6/25/2023|<li>In [Shader target](#shader-target) and [Shader function attributes](#shader-function-attributes) sections fixed the case sensitivity to match expected final compiler behavior: For attributes like `Shader("node")` and `NodeLaunch("mode")` (`"mode"` is `"coalescing"` etc.), the attribute name is case insensitive, while the string is case sensitive. And for these two attributes, the strings also must be lowercase. The current preview compiler is incorrectly case insensitive for the string in `NodeLaunch("mode")`. Updated samples to match.</li><li>Linked to [Thread visibility in wave operations](#thread-visibility-in-wave-operations) from the launch mode sections such as [Coalescing launch nodes](#coalescing-launch-nodes) for discoverability.</li>
v0.44|9/7/2023|<li>Added [Producer - consumer dataflow through UAVs](#producer---consumer-dataflow-through-uavs), summarizing the rules for how to make sure data written to UAVs in a producer node ends up visible to a consumer.</li><li> Added example code for a couple of barrier scenarios:<ul><li>[Dispatch grid writing to UAV for consumer node to read](#dispatch-grid-writing-to-uav-for-consumer-node-to-read)</li><li>[Single thread writing to UAV for consumer node to read](#single-thread-writing-to-uav-for-consumer-node-to-read)</li></ul></li><li>Joined the ACCESS_FLAGS and SYNC_FLAGS field in [Barrier](#barrier) into a single flags field: BARRIER_SEMANTIC_FLAGS for simplicity. Matching change to DXIL in [Lowering barrier](#lowering-barrier).</li><li>In [Node input declaration](#node-input-declaration) and [Node input atttributes](#node-input-attributes), added a `globallycoherent` option to `RWDispatchNodeInputRecord` for cases loads/stores will be used on the input record for cross-group communication. Matching change to DXIL in [NodeIOFlags and NodeIOKind encoding](#nodeioflags-and-nodeiokind-encoding)</li><li>Added [Quad and derivative operation semantics](#quad-and-derivative-operation-semantics) and [NonUniformResourceIndex semantics](#nonuniformresourceindex-semantics) sections to clarify how these operate in work graphs.</li><li>Added [Support for WaveSize shader function attribute](#support-for-wavesize-shader-function-attribute) section to clarify that the HLSL `WaveSize(N)` shader function attribute works for shaders node shaders of all launch types.</li><li>Refined behavior for [AddToStateObject()](#addtostateobject) with more specifics and more flexibility than the initial proposal. Will need more refinement with feedback.</li><li>Along with the [AddToStateObject()](#addtostateobject) refinement, changed various work graphs creation DDIs so that nodes identify their connections to other nodes with lists of pointers rather than by index. This way when additions are made, existing node definitons can be updated in-place by appending pointers to lists when a node points to a newly added node, or is targetted by a newly added node. The addition lists all nodes, with new ones at the start of the list. All affected existing node definitions from previous DDIs are modified in-place to point to each other appropriately. Each node definition includes a versionAdded number so that with a single DDI memory representation of the full work graph, drivers can see what the structure at any given version looked like if needed. See [D3D12DDI_WORK_GRAPH_DESC_0108](#d3d12ddi_work_graph_desc_0108)(added flags, version, and changed node arrays to lists), [D3D12DDI_WORK_GRAPH_FLAGS_0108](#d3d12ddi_work_graph_flags_0108)(new addition flag), [D3D12DDI_NODE_LIST_ENTRY_0108](#d3d12ddi_node_list_entry_0108)(new, used for lists of nodes), [D3D12DDI_NODE_0108](#d3d12ddi_node_0108)(updated with `VersionAdded` instead of `NodeIndex`), [D3D12DDI_NODE_OUTPUT_0108](#d3d12ddi_node_output_0108)(updated with node list instead of array), [D3D12DDI_BROADCASTING_LAUNCH_NODE_PROPERTIES_0108](#d3d12ddi_broadcasting_launch_node_properties_0108)(updated with input node list instead of arrays), [D3D12DDI_COALESCING_LAUNCH_NODE_PROPERTIES_0108](#d3d12ddi_coalescing_launch_node_properties_0108)(updated with input node list instead of arrays), [D3D12DDI_THREAD_LAUNCH_NODE_PROPERTIES_0108](#d3d12ddi_thread_launch_node_properties_0108)(updated with input node list instead of arrays)</li><li>In [Node output attributes](#node-output-attributes) added `[UnboundedSparseNodes]` option, which is equivalent to setting `[AllowSparseNodes]` and `[NodeArraySize(0xffffffff)]`. In DXIL [Node input and output metadata table](#node-input-and-output-metadata-table), noted that for `NodeOutputArraySize`, `0xffffffff` means unbounded array size and `NodeAllowSparseNodes` must be `true`.</li><li>Removed changes to allow multiple conflicting `shader` attributes on entry points. Replaced **Repurposing plain compute shader code** with [Reusing shader entries](#reusing-shader-entries). Removed references to default or implicit node inputs throughout.</li><li>In [D3D12_WORK_GRAPHS_TIER](#d3d12_work_graphs_tier) added `D3D12_WORK_GRAPHS_TIER_1_0` (and same at DDI) to get ready for first full release.</li>
v0.45|9/22/2023|<li>Added new option for overriding node properties at the API, a new [D3D12_NODE_OVERRIDES_TYPE](#d3d12_node_overrides_type), [D3D12_NODE_OVERRIDES_TYPE_COMMON_COMPUTE](#d3d12_node_overrides_type). This allows overriding common properties agnostic to launch mode, like renaming a node or its outputs, without having to know the launch mode of the node/shader. Previously any override required the app to know the launch mode to pick the matching override type for the shader.</li><li>In [Interactions with other d3d12 features](#interactions-with-other-d3d12-features), noted that - Pipeline statistics report invocations of nodes against the corresponding shader type. So compute-based node shader invocations increment `CSInvocations`.</li>
v0.46|10/5/2023|<li>In [D3D12_WORK_GRAPH_MEMORY_REQUIREMENTS](#d3d12_work_graph_memory_requirements) renamed `SizeAlignmentInBytes` to `SizeGranularityInBytes` to be more clear. It turns out the codebase already used this name. Users were confusing `SizeAlignmentInBytes` in the spec for the alignment of the base address, when actually it defines that usable backing memory sizes larger than the minimum stated by the driver must be larger than the minimum by a multiple of `SizeGranularityInBytes`. Added documentation describing the meaning more clearly, and clarified: The application can provide sizes for backing memory that are larger than `MinSizeInBytes` + an integer multiple of `SizeGranularityInBytes`, or larger than `MaxSizeInBytes`, but it simply wastes memory as the driver won't touch memory beyond the size range and granularity specifications here.</li>

0 comments on commit 3d93724

Please sign in to comment.