vkCreateQueryPool - Create a new query pool object

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid QueryPoolCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pQueryPool must be a valid pointer to a QueryPool handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

AllocationCallbacks, Device, QueryPool, QueryPoolCreateInfo

A convenience wrapper to make a compatible pair of calls to createQueryPool and destroyQueryPool

To ensure that destroyQueryPool is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass (,) as the first argument.

vkDestroyQueryPool - Destroy a query pool object

Valid Usage

• All submitted commands that refer to queryPool must have completed execution

• If AllocationCallbacks were provided when queryPool was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when queryPool was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If queryPool is not NULL_HANDLE, queryPool must be a valid QueryPool handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If queryPool is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to queryPool must be externally synchronized

See Also

AllocationCallbacks, Device, QueryPool

vkGetQueryPoolResults - Copy results of queries in a query pool to a host memory region

Description

The range of queries read is defined by [firstQuery, firstQuery + queryCount - 1]. For pipeline statistics queries, each query index in the pool contains one integer value for each bit that is enabled in QueryPoolCreateInfo::pipelineStatistics when the pool is created.

If no bits are set in flags, and all requested queries are in the available state, results are written as an array of 32-bit unsigned integer values. The behavior when not all queries are available, is described below.

If QUERY_RESULT_64_BIT is not set and the result overflows a 32-bit value, the value may either wrap or saturate. Similarly, if QUERY_RESULT_64_BIT is set and the result overflows a 64-bit value, the value may either wrap or saturate.

If QUERY_RESULT_WAIT_BIT is set, Vulkan will wait for each query to be in the available state before retrieving the numerical results for that query. In this case, getQueryPoolResults is guaranteed to succeed and return SUCCESS if the queries become available in a finite time (i.e. if they have been issued and not reset). If queries will never finish (e.g. due to being reset but not issued), then getQueryPoolResults may not return in finite time.

If QUERY_RESULT_WAIT_BIT and QUERY_RESULT_PARTIAL_BIT are both not set then no result values are written to pData for queries that are in the unavailable state at the time of the call, and getQueryPoolResults returns NOT_READY. However, availability state is still written to pData for those queries if QUERY_RESULT_WITH_AVAILABILITY_BIT is set.

Note

Applications must take care to ensure that use of the QUERY_RESULT_WAIT_BIT bit has the desired effect.

For example, if a query has been used previously and a command buffer records the commands cmdResetQueryPool, cmdBeginQuery, and cmdEndQuery for that query, then the query will remain in the available state until resetQueryPool is called or the cmdResetQueryPool command executes on a queue. Applications can use fences or events to ensure that a query has already been reset before checking for its results or availability status. Otherwise, a stale value could be returned from a previous use of the query.

The above also applies when QUERY_RESULT_WAIT_BIT is used in combination with QUERY_RESULT_WITH_AVAILABILITY_BIT. In this case, the returned availability status may reflect the result of a previous use of the query unless resetQueryPool is called or the cmdResetQueryPool command has been executed since the last use of the query.

Note

Applications can double-buffer query pool usage, with a pool per frame, and reset queries at the end of the frame in which they are read.

If QUERY_RESULT_PARTIAL_BIT is set, QUERY_RESULT_WAIT_BIT is not set, and the query’s status is unavailable, an intermediate result value between zero and the final result value is written to pData for that query.

If QUERY_RESULT_WITH_AVAILABILITY_BIT is set, the final integer value written for each query is non-zero if the query’s status was available or zero if the status was unavailable. When QUERY_RESULT_WITH_AVAILABILITY_BIT is used, implementations must guarantee that if they return a non-zero availability value then the numerical results must be valid, assuming the results are not reset by a subsequent command.

Note

Satisfying this guarantee may require careful ordering by the application, e.g. to read the availability status before reading the results.

Valid Usage

• firstQuery must be less than the number of queries in queryPool

• If QUERY_RESULT_64_BIT is not set in flags, then pData and stride must be multiples of 4
• If QUERY_RESULT_64_BIT is not set in flags and the queryType used to create queryPool was not QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pData and stride must be multiples of 4
• If QUERY_RESULT_64_BIT is set in flags then pData and stride must be multiples of 8
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pData and stride must be multiples of the size of PerformanceCounterResultKHR
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, then stride must be large enough to contain QueryPoolPerformanceCreateInfoKHR::counterIndexCount used to create queryPool times the size of PerformanceCounterResultKHR.
• The sum of firstQuery and queryCount must be less than or equal to the number of queries in queryPool
• dataSize must be large enough to contain the result of each query, as described here
• If the queryType used to create queryPool was QUERY_TYPE_TIMESTAMP, flags must not contain QUERY_RESULT_PARTIAL_BIT
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, flags must not contain QUERY_RESULT_WITH_AVAILABILITY_BIT, QUERY_RESULT_PARTIAL_BIT or QUERY_RESULT_64_BIT
• If the queryType used to create queryPool was QUERY_TYPE_PERFORMANCE_QUERY_KHR, the queryPool must have been recorded once for each pass as retrieved via a call to getPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR

Valid Usage (Implicit)

• device must be a valid Device handle

• queryPool must be a valid QueryPool handle
• pData must be a valid pointer to an array of dataSize bytes
• flags must be a valid combination of QueryResultFlagBits values
• dataSize must be greater than 0
• queryPool must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• NOT_READY

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST

See Also

Device, DeviceSize, QueryPool, QueryResultFlags

VkQueryPoolCreateInfo - Structure specifying parameters of a newly created query pool

Description

pipelineStatistics is ignored if queryType is not QUERY_TYPE_PIPELINE_STATISTICS.

Valid Usage

• If the pipeline statistics queries feature is not enabled, queryType must not be QUERY_TYPE_PIPELINE_STATISTICS

• If queryType is QUERY_TYPE_PIPELINE_STATISTICS, pipelineStatistics must be a valid combination of QueryPipelineStatisticFlagBits values
• If queryType is QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pNext chain must include a structure of type QueryPoolPerformanceCreateInfoKHR
• queryCount must be greater than 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of QueryPoolPerformanceCreateInfoKHR or QueryPoolPerformanceQueryCreateInfoINTEL
• The sType value of each struct in the pNext chain must be unique
• flags must be 0
• queryType must be a valid QueryType value

See Also

QueryPipelineStatisticFlags, QueryPoolCreateFlags, QueryType, StructureType, createQueryPool

VkQueryPool - Opaque handle to a query pool object

See Also

cmdBeginQuery, cmdBeginQueryIndexedEXT, cmdCopyQueryPoolResults, cmdEndQuery, cmdEndQueryIndexedEXT, cmdResetQueryPool, cmdWriteAccelerationStructuresPropertiesKHR, cmdWriteAccelerationStructuresPropertiesNV, cmdWriteTimestamp, createQueryPool, destroyQueryPool, getQueryPoolResults, resetQueryPool, resetQueryPoolEXT

VkQueryPoolCreateFlags - Reserved for future use

Description

QueryPoolCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

QueryPoolCreateInfo

VkQueryType - Specify the type of queries managed by a query pool

See Also

QueryPoolCreateInfo, cmdWriteAccelerationStructuresPropertiesKHR, cmdWriteAccelerationStructuresPropertiesNV, writeAccelerationStructuresPropertiesKHR

VkQueryResultFlagBits - Bitmask specifying how and when query results are returned

See Also

QueryResultFlags

VkQueryPipelineStatisticFlagBits - Bitmask specifying queried pipeline statistics

Description

These values are intended to measure relative statistics on one implementation. Various device architectures will count these values differently. Any or all counters may be affected by the issues described in Query Operation.

Note

For example, tile-based rendering devices may need to replay the scene multiple times, affecting some of the counts.

If a pipeline has rasterizerDiscardEnable enabled, implementations may discard primitives after the final vertex processing stage. As a result, if rasterizerDiscardEnable is enabled, the clipping input and output primitives counters may not be incremented.

When a pipeline statistics query finishes, the result for that query is marked as available. The application can copy the result to a buffer (via cmdCopyQueryPoolResults), or request it be put into host memory (via getQueryPoolResults).

See Also

QueryPipelineStatisticFlags