Queries
In Direct3D 12, queries are grouped into arrays of queries called a query heap. A query heap has a type which defines the valid types of queries that can be used with that heap.
- Differences in Queries from Direct3D 11 to Direct3D 12
- Query Heaps
- Creating Query heaps
- Extracting data from a query
- Related topics
Differences in Queries from Direct3D 11 to Direct3D 12
The following query types are no longer present in Direct3D 12, their functionality being incorporated into other processes:
- Event queries - event functionally is now handled by fences.
- Disjoint timestamp queries - GPU clocks can be set to a stable state in Direct3D 12 (see the Timing section). GPU clock comparisons are not meaningful if the GPU idled at all between the timestamps (known as a disjoint query). With stable power two timestamp queries issued from different command lists are reliably comparable. Two timestamps within the same command list are always reliably comparable.
- Steam output statistics queries - in Direct3D 12 there is no single stream output (SO) overflow query for all the output streams. Apps need to issue multiple single-stream queries, and then correlate the results.
- Stream output statistics predicate and occlusion predicate queries - queries (which write to memory) and Predication (which reads from memory) are no longer coupled, and so these query types are not needed.
A new binary occlusion query type has been added to Direct3D 12.
Query Heaps
Queries can be one from a number of types (D3D12_QUERY_HEAP_TYPE), and are grouped into query heaps before being submitted to the GPU.
A new query type D3D12_QUERY_TYPE_BINARY_OCCLUSION is available and acts like D3D12_QUERY_TYPE_OCCLUSION except that it returns a binary 0/1 result: 0 indicates that no samples passed depth and stencil testing, 1 indicates that at least one sample passed depth and stencil testing. This enables occlusion queries to not interfere with any GPU performance optimization associated with depth/stencil testing.
Creating Query heaps
The APIs relevant to creating query heaps are the enum D3D12_QUERY_HEAP_TYPE, the struct D3D12_QUERY_HEAP_DESC, and the method CreateQueryHeap.
The core runtime will validate that the query heap type is a valid member of the D3D12_HEAP_TYPE enumeration, and that the count is greater than 0.
Each individual query element within a query heap can be started and stopped separately.
The APIs for using the query heaps are the enum D3D12_QUERY_TYPE, and the methods BeginQuery and EndQuery.
D3D12_QUERY_TYPE_TIMESTAMP is the only query that supports EndQuery only. All other query types require BeginQuery and EndQuery.
The debug layer will validate the following:
- It is illegal to begin a query twice without ending it (for a given element). For queries which require both begin and end, it is illegal to end a query before the corresponding begin (for a given element).
- The query type passed to BeginQuery must match the query type passed to EndQuery.
The core runtime will validate the following:
- BeginQuery cannot be called on a timestamp query.
- For the query types which support both BeginQuery and EndQuery (all except for timestamp), a query for a given element must not span command list boundaries.
- ElementIndex must be within range.
- The query type is a valid member of the D3D12_QUERY_TYPE enum.
-
The query type must be compatible with the query heap. The following table shows the query heap type required for each query type:
Query Type Query Heap type D3D12_QUERY_TYPE_OCCLUSION D3D12_QUERY_TYPE_HEAP_TYPE_OCCLUSION D3D12_QUERY_TYPE_BINARY_OCCLUSION D3D12_QUERY_TYPE_HEAP_TYPE_OCCLUSION D3D12_QUERY_TYPE_TIMESTAMP D3D12_QUERY_TYPE_HEAP_TYPE_TIMESTAMP D3D12_QUERY_TYPE_PIPELINE_STATISTICS D3D12_QUERY_TYPE_HEAP_TYPE_PIPELINE_STATISTICS D3D12_QUERY_TYPE_SO_STATISTICS_STREAM0 D3D12_QUERY_TYPE_HEAP_TYPE_SO_STATISTICS D3D12_QUERY_TYPE_SO_STATISTICS_STREAM1 D3D12_QUERY_TYPE_HEAP_TYPE_SO_STATISTICS D3D12_QUERY_TYPE_SO_STATISTICS_STREAM2 D3D12_QUERY_TYPE_HEAP_TYPE_SO_STATISTICS D3D12_QUERY_TYPE_SO_STATISTICS_STREAM3 D3D12_QUERY_TYPE_HEAP_TYPE_SO_STATISTICS -
The query type is supported by the command list type. The following table shows which queries are supported on which command list types.
Query Type Supported Command List Types D3D12_QUERY_TYPE_OCCLUSION Direct D3D12_QUERY_TYPE_BINARY_OCCLUSION Direct D3D12_QUERY_TYPE_TIMESTAMP Direct and Compute D3D12_QUERY_TYPE_PIPELINE_STATISTICS Direct D3D12_QUERY_TYPE_SO_STATISTICS_STREAM0 Direct D3D12_QUERY_TYPE_SO_STATISTICS_STREAM1 Direct D3D12_QUERY_TYPE_SO_STATISTICS_STREAM2 Direct D3D12_QUERY_TYPE_SO_STATISTICS_STREAM3 Direct
Extracting data from a query
The way to extract data from a query is to use the ResolveQueryData method. ResolveQueryData works with all heap types (default, upload, and readback).
Related topics