Class IQueryManager

Defined in File query-manager.h

Class Documentation

class IQueryManager

Interface used to accurately query all metrics for a graphics API call or range of calls.

Note

Graphics API specific objects provided to this interface's functions (such as an ID3D12Device/VkDevice and ID3D12CommandQueue/VkQueue), must remain alive/usable until after a paired function (if available, such as Unsubscribe) has been called and/or the query manager has been destroyed.

Note

The underlying implementation used to collect the metrics is based on the QueryManagerType specified when CreateQueryManager was called, and platform specific selection logic also if it was kUnspecified or kDefault.

Note

High-level usage and typical function call flow:

//!         <APPLICATION STARTUP>
//!             LinkAndPrepareForGpuSpecificMdApiSourceUsage (if Intel MD library based query provider will be used)
//!         <WORKLOAD STARTUP>
//!             GetQueryManagerRequiredGraphicsApiExtensions
//!             CreateQueryManager
//!             RegisterCallback
//!             AreRangeQueriesSupported
//!             AreRangeQueriesAcrossCommandBuffersSupported
//!         <WORKLOAD FRAME (iterate as needed)>
//!             <WORKLOAD COLLECTION RANGE with QUEUE CHANGE (iterate based on ranges split by queue changes)>
//!                 OnCreateCommandQueue
//!                 OnCreateCommandList
//!                 AreMultipleSubscribesSupported
//!                 Subscribe
//!                 <WORKLOAD CALL / COLLECTION RANGE without QUEUE CHANGE (iterate based on queries subscribed/needed)>
//!                     BeginQuery
//!                     <WORKLOAD GRAPHICS API CALL / CALLS>
//!                     EndQuery
//!                     <WORKLOAD BeginRenderPass CALL>
//!                         OnBeginRenderPass
//!                         BeginQuery
//!                         <WORKLOAD GRAPHICS API CALL / CALLS>
//!                         EndQuery
//!                     <WORKLOAD EndRenderPass CALL>
//!                         OnEndRenderPass
//!                 OnExecuteCommandLists
//!                 <WORKLOAD FRAME RENDER / SUBMIT>
//!                 <WORKLOAD COMMAND QUEUES CPU SYNC>
//!                 Unsubscribe
//!         <WORKLOAD SHUTDOWN>
//!             DestroyQueryManager
//!         <APPLICATION SHUTDOWN>
//!             UnlinkGpuSpecificMdApiSourceUsage (if Intel MD library based query provider was used)
//!

Note

This interface is NOT thread-safe.

Public Functions

virtual char const *GetInformation() = 0

Obtain information about the metrics implementation that would be used.

Returns: Pointer to null-terminated buffer containing the name and version of the implementation.

virtual QueryManagerType Type() const = 0: Returns the type of QueryManager instantiated.

virtual IMetricsSource const *MetricsSource() const = 0: Return an interface describing the source of data for this QueryManager.

virtual Result RegisterCallback(QueryResultAvailableCallback callback, void *userData) = 0

Used to register a callback function that will be called when metrics are available from the query implementation and Unsubscribe is called.

Note

The results returned to the callback are always returned in the order queried from the CPU. This means that if two back-to-back queries happen on two different command buffers, the results will be returned in the order that BeginQuery and EndQuery were called, not the order the command buffers were executed in.

Note

If multiple subscribes were performed (thus multiple command queues were queried), the results returned to the callback function for each metric may be provided in multiple calls. Thus, one call might provide a portion of the values collected and subsequent calls would provide the other values. For each metric value, the callback can check the associated query index to determine if the value is a valid query result or not.

Parameters

callback -- [in] Callback function pointer that will receive the results.
userData -- [in] Opaque user data value that is provided to the callback function when it is invoked.

virtual Result GetMaximumQueriesSupported(uint32_t metricGroup, uint32_t *pMaximumQueries) const = 0

Obtain the maximum number of queries that can collected per metrics collection pass or Subscribe call, that are supported for a specific group by the query provider.

Note

As of 2022-10-13, the currently known query provider maximums supported are:

//!         kD3d11StatisticsAndTimeStamp    UINT32_MAX / sizeof(QueryData)
//!         kD3d12StatisticsAndTimeStamp    UINT32_MAX, or UINT32_MAX / 2 if
//!                                         timestamp metrics are included
//!         kMetricsDiscoveryApi
//!             D3D11                       50000
//!             D3D12 & Vulkan              UINT32_MAX / group report size
//!         kVulkanStatisticsAndTimeStamp   UINT32_MAX, or UINT32_MAX / 2 if
//!                                         timestamp metrics are included
//!

Parameters

metricGroup -- [in] Metric group index to obtain the maximum queries supported for.
pMaximumQueries -- [inout] Pointer to a value that upon success will be initialized with the maximum number of queries that can be requested in a call to Subscribe.

virtual Result Subscribe(void *commandQueue, uint32_t metricGroup, uint32_t numQueries, bool enableGpuFrequencyOverride = false, float gpuFrequencyOverrideValue = 1.0f) = 0

Subscribe to a group of metrics to be measured for a queue and the maximum number of query measurements that will be performed (for D3D11 an immediate context is used instead of a queue).

Allocates numQueries number of queries indexed in range [0,numQueries). The indices are to be used in BeginQuery and EndQuery.

Multiple active subscriptions to the same metric set for different command queues are supported by some query providers for some graphics APIs (such subscriptions do not have an Unsubscribe call made between calls to Subscribe). To dynamically determine if a Query Manager supports multiple subscriptions use the AreMultipleSubscribesSupported function.

Note

In the multiple Subscribe usage scenario (in which there is not a matched Unsubscribe call between each call to Subscribe), all Subscribe calls after the first one must specify the same metric group index and different command queues.

Note

Each subscrition can have a different maximum number of queries.

Note

Multiple subscribes are supported by the following query providers: kD3d12StatisticsAndTimeStamp and kVulkanStatisticsAndTimeStamp. For kMetricsDiscoveryApi (D3D12 & Vulkan) multiple queues are supported too. Subscribe needs to be called once, commandQueue argument ignored, but it is allowed to call Begin/End query for different queues.

Parameters

commandQueue -- [in] Command queue to collect metrics from. The OnCreateCommandQueue function must have been previously called for the queue. For D3D12, provide a ID3D12CommandQueue pointer. For Vulkan, provide a VkQueue. In the case of D3D11, provide an immediate ID3D11DeviceContext pointer since there is no queue.
metricGroup -- [in] Metric group index to use in range [0, NumMetricGroups()).
numQueries -- [in] Maximum number of queries desired. Must be in range [0, GetMaximumQueriesSupported()].
enableGpuFrequencyOverride -- [in] State of GPU Frequency override.
gpuFrequencyOverrideValue -- [in] GPU Frequency override value - percent of the maximum GPU frequency to be used. Must be in range [0.1, 1.0].

virtual Result Unsubscribe(void *commandQueue, uint32_t *pQueryReportPointerCount = nullptr, QueryReport const **pQueryReportPointerArray = nullptr, QueryReportOfInterestEvaluationCallback *pCallback = nullptr, void *userData = nullptr) = 0

Unsubscribe from the current group of previously subscribed metrics and get all of the resulting metrics collected, as well as optionally getting query reports for the queries peformed that failed and are not useful to recollect, have questionable results for some reason and should be re-collected, or just those of interest.

Note

The metrics are returned using the callback function previously provided in an earlier call to RegisterCallback.

Note

Ensure that all GPU work on subscribed queues is complete before calling.

Note

For kD3d12StatisticsAndTimeStamp and kVulkanStatisticsAndTimeStamp all subscribed queues will be unsubscribed.

Note

All QueryReport struct pointers returned will remain valid until the next time Subscribe is called or the QueryManager instance is destroyed.

Parameters

commandQueue -- [in] Command queue metrics were collected metrics from. Must match the one specified in the previous call to Subscribe.
[in/out] -- pQueryReportPointerCount Optional pointer to a uint32_t that contains the number of QueryReport pointer elements in the pQueryReportPointerArray array. Upon success, the number will be updated to reflect how many elements in the array were initialized (it is possible that none are). Ignored if it is nullptr.
[in/out] -- pQueryReportPointerArray Pointer to a QueryReport pointer array that will contains the *pQueryReportPointerCount elements. Upon success, the quantity of elements actually initialized will be the number of queries performed that completely failed (thus the associated metrics have nan values) or have untrusted/questionable result values, or it will be based upon which queries were identified to be of interest by the optional evaluation callback function. It is Ignored if pQueryReportPointerCount is nullptr.
pCallback -- [in] Optional pointer to a callback function that can be used to evaluate a QueryReport to determine if it is represents a failed query and if a pointer to the QueryReport should be handed back to the caller in the provided array because it is of interest (for example failed or is untrusted). Ignored if it is nullptr.
userData -- [in] Optional user defined value passed to the provided callback function whenever it is called.

virtual Result BeginQuery(CommandBufferData const &bufferData, uint32_t queryId) = 0

Begin a query.

Identifies the start of a query using the specified command buffer data for a specific query index.

Note

There must be an unspecified/available query of those requested in an earlier call to Subscribe.

Note

Currently, only one query is allowed to be open/active at a time thus nested queries within the same command buffer are not supported. After calling BeginQuery, EndQuery must be called before BeginQuery is called again.

Note

For kMetricsDiscoveryApi (D3D12 & Vulkan) command queues other than the one subscribed can be provided.

Parameters

bufferData -- [in] Graphics command queue (or immediate context for D3D11) and command buffer (ignored for D3D11) state to begin the query with. The Subscribe function must have been previously called for the queue (or in the case of D3D11, for the immediate context). For Vulkan, the VkCommandBuffer must be in the recording state.
queryId -- [in] Query index to associate the query with [0, numQueries) where numQueries was specified earlier in Subscribe. Query indices are not required to be used sequentially.

virtual Result EndQuery(CommandBufferData const &bufferData, uint32_t queryId) = 0

End a query.

Identifies the end of a query using the specified command buffer data for the specified query index.

Note

For kMetricsDiscoveryApi (D3D12 & Vulkan) command queues other than the one subscribed can be provided, as long as it matches the one used in BeginQuery.

Parameters

bufferData -- [in] Graphics command queue (or immediate context for D3D11) and command buffer (ignored for D3D11) state to end the query with. The queue must match the one provided in the prior Subscribe and BeginQuery calls. For Vulkan, the VkCommandBuffer must be in the recording state.
queryId -- [in] Index of query to end that must match the one provided in the prior BeginQuery call.

virtual Result OnCreateCommandQueue(void const *commandQueue) = 0

Creates graphics command queue based resources needed by the QueryManager (for D3D11 an immediate context is used instead of a queue).

Must be called after creating any graphics command queue and before calling Subscribe.

Note

Resources created by calling this function are automatically released when the QueryManager implementation is destroyed.

Parameters: commandQueue -- [in] Graphics command queue that will be used to collect metrics from (or an immediate ID3D11DeviceContext pointer for D3D11).

virtual Result OnCreateCommandList(CommandBufferData const &bufferData) = 0

Creates graphics command buffer based resources needed by the QueryManager.

Must be called after creating any graphics command buffer and before calling OnExecuteCommandLists.

Note

Resources created by calling this function are automatically released when the QueryManager implementation is destroyed.

Note

Command lists are not currently supported for D3D11, thus calling it is essentially a NOP.

Parameters: commandList -- [in] Graphics command queue and command buffer. The OnCreateCommandQueue function must have been previously called for the queue.

virtual Result OnExecuteCommandLists(void const *commandQueue) = 0

Perform implementation specific logic, such as setting the metric group/list configuration metrics will be collected for.

Must be called right before executing/submitting/committing the queue or command buffer(s) to the GPU to be rendered.

Note

Command lists are not currently supported for D3D11, thus calling it with an immediate ID3D11DeviceContext pointer is essentially a NOP.

Parameters: commandQueue -- [in] Graphics command queue associated with the work about to be submitted to the GPU. An earlier call to the OnCreateCommandList function must have included the specified queue, as well as a prior call to the Subscribe function.

virtual Result OnBeginRenderPass(CommandBufferData const &bufferData) = 0

Mark begin of the render pass.

Must be called before or after BeginRenderPass call.

Note

Currently calling this function is required only for D3D12. Command lists are not currently supported for D3D11, thus calling it with an immediate ID3D11DeviceContext pointer is essentially a NOP. It is essentially a NOP for Vulkan.

Parameters: commandList -- [in] Graphics command list/buffer used in a call to BeginRenderPass.

virtual Result OnEndRenderPass(CommandBufferData const &bufferData) = 0

Mark end of the render pass

Must be called after EndRenderPass call

Note

Currently calling this function is required only for D3D12. Command lists are not currently supported for D3D11, thus calling it with an immediate ID3D11DeviceContext pointer is essentially a NOP. It is essentially a NOP for Vulkan.

Parameters: commandList -- [in] Graphics command list (command buffer) which calls EndRenderPass

virtual bool AreRangeQueriesSupported() = 0: Returns whether or not the query provider supports querying a region (consecutive graphics API calls).

virtual bool AreRangeQueriesAcrossCommandBuffersSupported() = 0: Return whether or not the query provider supports querying a region (consecutive graphics API calls) that spans more than one graphics command buffer (begin query is in one grapics command buffer and the end query is in a different one).

virtual bool AreMultipleSubscribesSupported() const = 0: Returns whether or not the query provider supports multiple subscribes.

virtual bool AreQueriesWithDifferentQueuesSupported() const = 0: Returns the state of the ability to call BeginQuery and EndQuery with different command queues.

virtual ~IQueryManager()