// Copyright 2015-2021 The Khronos Group, Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[queries]] = Queries _Queries_ provide a mechanism to return information about the processing of a sequence of Vulkan commands. Query operations are asynchronous, and as such, their results are not returned immediately. Instead, their results, and their availability status are stored in a <>. The state of these queries can: be read back on the host, or copied to a buffer object on the device. The supported query types are <>, <>, ifdef::VK_KHR_video_queue[] <>, endif::VK_KHR_video_queue[] ifdef::VK_KHR_video_encode_queue[] <>, endif::VK_KHR_video_encode_queue[] and <>. ifdef::VK_KHR_performance_query[] <> are supported if the associated extension is available. endif::VK_KHR_performance_query[] ifdef::VK_EXT_transform_feedback[] <> are supported if the associated extension is available. endif::VK_EXT_transform_feedback[] ifdef::VK_INTEL_performance_query[] <> are supported if the associated extension is available. endif::VK_INTEL_performance_query[] ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] Several additional queries with specific purposes associated with ray tracing are available if the corresponding extensions are supported, as described for elink:VkQueryType. endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] [[queries-pools]] == Query Pools [open,refpage='VkQueryPool',desc='Opaque handle to a query pool object',type='handles'] -- Queries are managed using _query pool_ objects. Each query pool is a collection of a specific number of queries of a particular type. Query pools are represented by sname:VkQueryPool handles: include::{generated}/api/handles/VkQueryPool.txt[] -- [open,refpage='vkCreateQueryPool',desc='Create a new query pool object',type='protos'] -- To create a query pool, call: include::{generated}/api/protos/vkCreateQueryPool.txt[] * pname:device is the logical device that creates the query pool. * pname:pCreateInfo is a pointer to a slink:VkQueryPoolCreateInfo structure containing the number and type of queries to be managed by the pool. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pQueryPool is a pointer to a slink:VkQueryPool handle in which the resulting query pool object is returned. include::{generated}/validity/protos/vkCreateQueryPool.txt[] -- [open,refpage='VkQueryPoolCreateInfo',desc='Structure specifying parameters of a newly created query pool',type='structs'] -- The sname:VkQueryPoolCreateInfo structure is defined as: include::{generated}/api/structs/VkQueryPoolCreateInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:queryType is a elink:VkQueryType value specifying the type of queries managed by the pool. * pname:queryCount is the number of queries managed by the pool. * pname:pipelineStatistics is a bitmask of elink:VkQueryPipelineStatisticFlagBits specifying which counters will be returned in queries on the new pool, as described below in <>. pname:pipelineStatistics is ignored if pname:queryType is not ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. .Valid Usage **** * [[VUID-VkQueryPoolCreateInfo-queryType-00791]] If the <> feature is not enabled, pname:queryType must: not be ename:VK_QUERY_TYPE_PIPELINE_STATISTICS * [[VUID-VkQueryPoolCreateInfo-queryType-00792]] If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, pname:pipelineStatistics must: be a valid combination of elink:VkQueryPipelineStatisticFlagBits values ifdef::VK_KHR_performance_query[] * [[VUID-VkQueryPoolCreateInfo-queryType-03222]] If pname:queryType is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:pNext chain must: include a slink:VkQueryPoolPerformanceCreateInfoKHR structure endif::VK_KHR_performance_query[] * [[VUID-VkQueryPoolCreateInfo-queryCount-02763]] pname:queryCount must: be greater than 0 **** include::{generated}/validity/structs/VkQueryPoolCreateInfo.txt[] -- [open,refpage='VkQueryPoolCreateFlags',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkQueryPoolCreateFlags.txt[] tname:VkQueryPoolCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use. -- ifdef::VK_KHR_performance_query[] include::{chapters}/VK_KHR_performance_query/querycreateinfo.txt[] endif::VK_KHR_performance_query[] [open,refpage='vkDestroyQueryPool',desc='Destroy a query pool object',type='protos'] -- To destroy a query pool, call: include::{generated}/api/protos/vkDestroyQueryPool.txt[] * pname:device is the logical device that destroys the query pool. * pname:queryPool is the query pool to destroy. * pname:pAllocator controls host memory allocation as described in the <> chapter. .Valid Usage **** * [[VUID-vkDestroyQueryPool-queryPool-00793]] All submitted commands that refer to pname:queryPool must: have completed execution * [[VUID-vkDestroyQueryPool-queryPool-00794]] If sname:VkAllocationCallbacks were provided when pname:queryPool was created, a compatible set of callbacks must: be provided here * [[VUID-vkDestroyQueryPool-queryPool-00795]] If no sname:VkAllocationCallbacks were provided when pname:queryPool was created, pname:pAllocator must: be `NULL` **** [NOTE] .Note ==== Applications can: verify that pname:queryPool can: be destroyed by checking that fname:vkGetQueryPoolResults() without the ename:VK_QUERY_RESULT_PARTIAL_BIT flag returns ename:VK_SUCCESS for all queries that are used in command buffers submitted for execution. ==== include::{generated}/validity/protos/vkDestroyQueryPool.txt[] -- [open,refpage='VkQueryType',desc='Specify the type of queries managed by a query pool',type='enums'] -- Possible values of slink:VkQueryPoolCreateInfo::pname:queryType, specifying the type of queries managed by the pool, are: include::{generated}/api/enums/VkQueryType.txt[] * ename:VK_QUERY_TYPE_OCCLUSION specifies an <>. * ename:VK_QUERY_TYPE_PIPELINE_STATISTICS specifies a <>. * ename:VK_QUERY_TYPE_TIMESTAMP specifies a <>. ifdef::VK_KHR_performance_query[] * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR specifies a <>. endif::VK_KHR_performance_query[] ifdef::VK_EXT_transform_feedback[] * ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT specifies a <>. endif::VK_EXT_transform_feedback[] ifdef::VK_KHR_acceleration_structure[] * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR specifies a <> for use with flink:vkCmdWriteAccelerationStructuresPropertiesKHR or flink:vkWriteAccelerationStructuresPropertiesKHR. * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR specifies a <> endif::VK_KHR_acceleration_structure[] ifdef::VK_NV_ray_tracing[] * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV specifies a <> for use with flink:vkCmdWriteAccelerationStructuresPropertiesNV. endif::VK_NV_ray_tracing[] ifdef::VK_INTEL_performance_query[] * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL specifies a <>. endif::VK_INTEL_performance_query[] ifdef::VK_KHR_video_queue[] * ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR specifies a <>. endif::VK_KHR_video_queue[] ifdef::VK_KHR_video_encode_queue[] * ename:VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHR specifies a <>. endif::VK_KHR_video_encode_queue[] -- [[queries-operation]] == Query Operation The operation of queries is controlled by the commands flink:vkCmdBeginQuery, flink:vkCmdEndQuery, ifdef::VK_EXT_transform_feedback[] flink:vkCmdBeginQueryIndexedEXT, flink:vkCmdEndQueryIndexedEXT, endif::VK_EXT_transform_feedback[] flink:vkCmdResetQueryPool, flink:vkCmdCopyQueryPoolResults, ifdef::VK_KHR_synchronization2[] flink:vkCmdWriteTimestamp2KHR, endif::VK_KHR_synchronization2[] and flink:vkCmdWriteTimestamp. In order for a sname:VkCommandBuffer to record query management commands, the queue family for which its sname:VkCommandPool was created must: support the appropriate type of operations (graphics, compute) suitable for the query type of a given query pool. Each query in a query pool has a status that is either _unavailable_ or _available_, and also has state to store the numerical results of a query operation of the type requested when the query pool was created. Resetting a query via flink:vkCmdResetQueryPool ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] or flink:vkResetQueryPool endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] sets the status to unavailable and makes the numerical results undefined:. Performing a query operation with flink:vkCmdBeginQuery and flink:vkCmdEndQuery changes the status to available when the query <>, and updates the numerical results. Both the availability status and numerical results are retrieved by calling either flink:vkGetQueryPoolResults or flink:vkCmdCopyQueryPoolResults. [[queries-order]] Query commands, for the same query and submitted to the same queue, execute in their entirety in <>, relative to each other. In effect there is an implicit execution dependency from each such query command to all query commands previously submitted to the same queue. There is one significant exception to this; if the pname:flags parameter of flink:vkCmdCopyQueryPoolResults does not include ename:VK_QUERY_RESULT_WAIT_BIT, execution of flink:vkCmdCopyQueryPoolResults may: happen-before the results of flink:vkCmdEndQuery are available. After query pool creation, each query must: be reset before it is used. Queries must: also be reset between uses. ifdef::VK_VERSION_1_1,VK_KHR_device_group[] If a logical device includes multiple physical devices, then each command that writes a query must: execute on a single physical device, and any call to flink:vkCmdBeginQuery must: execute the corresponding flink:vkCmdEndQuery command on the same physical device. endif::VK_VERSION_1_1,VK_KHR_device_group[] [open,refpage='vkCmdResetQueryPool',desc='Reset queries in a query pool',type='protos'] -- To reset a range of queries in a query pool on a queue, call: include::{generated}/api/protos/vkCmdResetQueryPool.txt[] * pname:commandBuffer is the command buffer into which this command will be recorded. * pname:queryPool is the handle of the query pool managing the queries being reset. * pname:firstQuery is the initial query index to reset. * pname:queryCount is the number of queries to reset. When executed on a queue, this command sets the status of query indices [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to unavailable. ifdef::VK_KHR_performance_query[] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command sets the status of query indices [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to unavailable for each pass of pname:queryPool, as indicated by a call to flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. [NOTE] .Note ==== Because fname:vkCmdResetQueryPool resets all the passes of the indicated queries, applications must not record a fname:vkCmdResetQueryPool command for a pname:queryPool created with ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR in a command buffer that needs to be submitted multiple times as indicated by a call to flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. Otherwise applications will never be able to complete the recorded queries. ==== endif::VK_KHR_performance_query[] .Valid Usage **** * [[VUID-vkCmdResetQueryPool-firstQuery-00796]] pname:firstQuery must: be less than the number of queries in pname:queryPool * [[VUID-vkCmdResetQueryPool-firstQuery-00797]] The sum of pname:firstQuery and pname:queryCount must: be less than or equal to the number of queries in pname:queryPool * [[VUID-vkCmdResetQueryPool-None-02841]] All queries used by the command must: not be active ifdef::VK_KHR_performance_query[] * [[VUID-vkCmdResetQueryPool-firstQuery-02862]] If pname:queryPool was created with ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command must: not be recorded in a command buffer that, either directly or through secondary command buffers, also contains begin commands for a query from the set of queries [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# endif::VK_KHR_performance_query[] **** include::{generated}/validity/protos/vkCmdResetQueryPool.txt[] -- ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] [open,refpage='vkResetQueryPool',desc='Reset queries in a query pool',type='protos',alias='vkResetQueryPoolEXT'] -- To reset a range of queries in a query pool on the host, call: ifdef::VK_VERSION_1_2[] include::{generated}/api/protos/vkResetQueryPool.txt[] endif::VK_VERSION_1_2[] ifdef::VK_VERSION_1_2+VK_EXT_host_query_reset[or the equivalent command] ifdef::VK_EXT_host_query_reset[] include::{generated}/api/protos/vkResetQueryPoolEXT.txt[] endif::VK_EXT_host_query_reset[] * pname:device is the logical device that owns the query pool. * pname:queryPool is the handle of the query pool managing the queries being reset. * pname:firstQuery is the initial query index to reset. * pname:queryCount is the number of queries to reset. This command sets the status of query indices [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to unavailable. ifdef::VK_KHR_performance_query[] If pname:queryPool is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR this command sets the status of query indices [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to unavailable for each pass. endif::VK_KHR_performance_query[] .Valid Usage **** * [[VUID-vkResetQueryPool-None-02665]] The <> feature must: be enabled * [[VUID-vkResetQueryPool-firstQuery-02666]] pname:firstQuery must: be less than the number of queries in pname:queryPool * [[VUID-vkResetQueryPool-firstQuery-02667]] The sum of pname:firstQuery and pname:queryCount must: be less than or equal to the number of queries in pname:queryPool * [[VUID-vkResetQueryPool-firstQuery-02741]] Submitted commands that refer to the range specified by pname:firstQuery and pname:queryCount in pname:queryPool must: have completed execution * [[VUID-vkResetQueryPool-firstQuery-02742]] The range of queries specified by pname:firstQuery and pname:queryCount in pname:queryPool must: not be in use by calls to flink:vkGetQueryPoolResults or fname:vkResetQueryPool in other threads **** include::{generated}/validity/protos/vkResetQueryPool.txt[] -- endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] Once queries are reset and ready for use, query commands can: be issued to a command buffer. Occlusion queries and pipeline statistics queries count events - drawn samples and pipeline stage invocations, respectively - resulting from commands that are recorded between a flink:vkCmdBeginQuery command and a flink:vkCmdEndQuery command within a specified command buffer, effectively scoping a set of drawing and/or dispatching commands. Timestamp queries write timestamps to a query pool. ifdef::VK_KHR_performance_query[] Performance queries record performance counters to a query pool. endif::VK_KHR_performance_query[] A query must: begin and end in the same command buffer, although if it is a primary command buffer, and the <> feature is enabled, it can: execute secondary command buffers during the query operation. For a secondary command buffer to be executed while a query is active, it must: set the pname:occlusionQueryEnable, pname:queryFlags, and/or pname:pipelineStatistics members of slink:VkCommandBufferInheritanceInfo to conservative values, as described in the <> section. A query must: either begin and end inside the same subpass of a render pass instance, or must: both begin and end outside of a render pass instance (i.e. contain entire render pass instances). ifdef::VK_VERSION_1_1,VK_KHR_multiview[] If queries are used while executing a render pass instance that has multiview enabled, the query uses [eq]#N# consecutive query indices in the query pool (starting at pname:query) where [eq]#N# is the number of bits set in the view mask in the subpass the query is used in. How the numerical results of the query are distributed among the queries is implementation-dependent. For example, some implementations may: write each view's results to a distinct query, while other implementations may: write the total result to the first query and write zero to the other queries. However, the sum of the results in all the queries must: accurately reflect the total result of the query summed over all views. Applications can: sum the results from all the queries to compute the total result. Queries used with multiview rendering must: not span subpasses, i.e. they must: begin and end in the same subpass. endif::VK_VERSION_1_1,VK_KHR_multiview[] [open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos'] -- :refpage: vkCmdBeginQuery To begin a query, call: include::{generated}/api/protos/vkCmdBeginQuery.txt[] * pname:commandBuffer is the command buffer into which this command will be recorded. * pname:queryPool is the query pool that will manage the results of the query. * pname:query is the query index within the query pool that will contain the results. * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying constraints on the types of queries that can: be performed. If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and pname:flags contains ename:VK_QUERY_CONTROL_PRECISE_BIT, an implementation must: return a result that matches the actual number of samples passed. This is described in more detail in <>. ifdef::VK_EXT_transform_feedback[] Calling fname:vkCmdBeginQuery is equivalent to calling flink:vkCmdBeginQueryIndexedEXT with the pname:index parameter set to zero. endif::VK_EXT_transform_feedback[] [[queries-operation-active]] After beginning a query, that query is considered _active_ within the command buffer it was called in until that same query is ended. Queries active in a primary command buffer when secondary command buffers are executed are considered active for those secondary command buffers. .Valid Usage **** include::{chapters}/commonvalidity/query_begin_common.txt[] * [[VUID-vkCmdBeginQuery-queryPool-01922]] pname:queryPool must: have been created with a pname:queryType that differs from that of any queries that are <> within pname:commandBuffer ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdBeginQuery-queryType-02327]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations * [[VUID-vkCmdBeginQuery-queryType-02328]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries must: be supported endif::VK_EXT_transform_feedback[] include::{chapters}/commonvalidity/performance_query_begin_common.txt[] **** include::{generated}/validity/protos/vkCmdBeginQuery.txt[] -- ifdef::VK_EXT_transform_feedback[] [open,refpage='vkCmdBeginQueryIndexedEXT',desc='Begin an indexed query',type='protos'] -- :refpage: vkCmdBeginQueryIndexedEXT To begin an indexed query, call: include::{generated}/api/protos/vkCmdBeginQueryIndexedEXT.txt[] * pname:commandBuffer is the command buffer into which this command will be recorded. * pname:queryPool is the query pool that will manage the results of the query. * pname:query is the query index within the query pool that will contain the results. * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying constraints on the types of queries that can: be performed. * pname:index is the query type specific index. When the query type is ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the index represents the vertex stream. The fname:vkCmdBeginQueryIndexedEXT command operates the same as the flink:vkCmdBeginQuery command, except that it also accepts a query type specific pname:index parameter. .Valid Usage **** include::{chapters}/commonvalidity/query_begin_common.txt[] * [[VUID-vkCmdBeginQueryIndexedEXT-queryPool-04753]] If the pname:queryPool was created with the same pname:queryType as that of another <> query within pname:commandBuffer, then pname:index must: not match the index used for the active query * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02338]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02339]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index parameter must: be less than sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02340]] If the pname:queryType used to create pname:queryPool was not ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index must: be zero * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02341]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries must: be supported include::{chapters}/commonvalidity/performance_query_begin_common.txt[] **** include::{generated}/validity/protos/vkCmdBeginQueryIndexedEXT.txt[] -- endif::VK_EXT_transform_feedback[] [open,refpage='VkQueryControlFlagBits',desc='Bitmask specifying constraints on a query',type='enums'] -- Bits which can: be set in flink:vkCmdBeginQuery::pname:flags, specifying constraints on the types of queries that can: be performed, are: include::{generated}/api/enums/VkQueryControlFlagBits.txt[] * ename:VK_QUERY_CONTROL_PRECISE_BIT specifies the precision of <>. -- [open,refpage='VkQueryControlFlags',desc='Bitmask of VkQueryControlFlagBits',type='flags'] -- include::{generated}/api/flags/VkQueryControlFlags.txt[] tname:VkQueryControlFlags is a bitmask type for setting a mask of zero or more elink:VkQueryControlFlagBits. -- [open,refpage='vkCmdEndQuery',desc='Ends a query',type='protos'] -- To end a query after the set of desired drawing or dispatching commands is executed, call: include::{generated}/api/protos/vkCmdEndQuery.txt[] * pname:commandBuffer is the command buffer into which this command will be recorded. * pname:queryPool is the query pool that is managing the results of the query. * pname:query is the query index within the query pool where the result is stored. ifdef::VK_EXT_transform_feedback[] Calling fname:vkCmdEndQuery is equivalent to calling flink:vkCmdEndQueryIndexedEXT with the pname:index parameter set to zero. endif::VK_EXT_transform_feedback[] [[queries-operation-finished]] As queries operate asynchronously, ending a query does not immediately set the query's status to available. A query is considered _finished_ when the final results of the query are ready to be retrieved by flink:vkGetQueryPoolResults and flink:vkCmdCopyQueryPoolResults, and this is when the query's status is set to available. Once a query is ended the query must: finish in finite time, unless the state of the query is changed using other commands, e.g. by issuing a reset of the query. .Valid Usage **** * [[VUID-vkCmdEndQuery-None-01923]] All queries used by the command must: be <> * [[VUID-vkCmdEndQuery-query-00810]] pname:query must: be less than the number of queries in pname:queryPool ifdef::VK_VERSION_1_1[] * [[VUID-vkCmdEndQuery-commandBuffer-01886]] pname:commandBuffer must: not be a protected command buffer endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-vkCmdEndQuery-query-00812]] If fname:vkCmdEndQuery is called within a render pass instance, the sum of pname:query and the number of bits set in the current subpass's view mask must: be less than or equal to the number of queries in pname:queryPool endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_KHR_performance_query[] * [[VUID-vkCmdEndQuery-queryPool-03227]] If pname:queryPool was created with a pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the counters used to create pname:queryPool was ename:VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the flink:vkCmdEndQuery must: be the last recorded command in pname:commandBuffer * [[VUID-vkCmdEndQuery-queryPool-03228]] If pname:queryPool was created with a pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the counters used to create pname:queryPool was ename:VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the flink:vkCmdEndQuery must: not be recorded within a render pass instance endif::VK_KHR_performance_query[] **** include::{generated}/validity/protos/vkCmdEndQuery.txt[] -- ifdef::VK_EXT_transform_feedback[] [open,refpage='vkCmdEndQueryIndexedEXT',desc='Ends a query',type='protos'] -- To end an indexed query after the set of desired drawing or dispatching commands is recorded, call: include::{generated}/api/protos/vkCmdEndQueryIndexedEXT.txt[] * pname:commandBuffer is the command buffer into which this command will be recorded. * pname:queryPool is the query pool that is managing the results of the query. * pname:query is the query index within the query pool where the result is stored. * pname:index is the query type specific index. The fname:vkCmdEndQueryIndexedEXT command operates the same as the flink:vkCmdEndQuery command, except that it also accepts a query type specific pname:index parameter. .Valid Usage **** * [[VUID-vkCmdEndQueryIndexedEXT-None-02342]] All queries used by the command must: be <> * [[VUID-vkCmdEndQueryIndexedEXT-query-02343]] pname:query must: be less than the number of queries in pname:queryPool ifdef::VK_VERSION_1_1[] * [[VUID-vkCmdEndQueryIndexedEXT-commandBuffer-02344]] pname:commandBuffer must: not be a protected command buffer endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-vkCmdEndQueryIndexedEXT-query-02345]] If fname:vkCmdEndQueryIndexedEXT is called within a render pass instance, the sum of pname:query and the number of bits set in the current subpass's view mask must: be less than or equal to the number of queries in pname:queryPool endif::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02346]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index parameter must: be less than sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02347]] If the pname:queryType used to create pname:queryPool was not ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index must: be zero * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02723]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT pname:index must: equal the pname:index used to begin the query **** include::{generated}/validity/protos/vkCmdEndQueryIndexedEXT.txt[] -- endif::VK_EXT_transform_feedback[] [[queries-operation-memorylayout]] An application can: retrieve results either by requesting they be written into application-provided memory, or by requesting they be copied into a sname:VkBuffer. In either case, the layout in memory is defined as follows: * The first query's result is written starting at the first byte requested by the command, and each subsequent query's result begins pname:stride bytes later. * Occlusion queries, pipeline statistics queries, ifdef::VK_EXT_transform_feedback[] transform feedback queries, endif::VK_EXT_transform_feedback[] and timestamp queries store results in a tightly packed array of unsigned integers, either 32- or 64-bits as requested by the command, storing the numerical results and, if requested, the availability status. ifdef::VK_KHR_performance_query[] * Performance queries store results in a tightly packed array whose type is determined by the pname:unit member of the corresponding slink:VkPerformanceCounterKHR. endif::VK_KHR_performance_query[] * If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, the final element of each query's result is an integer indicating whether the query's result is available, with any non-zero value indicating that it is available. ifdef::VK_KHR_video_queue[] * If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is used, the final element of each query's result is an integer value indicating that status of the query result. Positive values indicate success, negative values indicate failure, and 0 indicates that the result is not yet available. Specific error codes are encoded in the elink:VkQueryResultStatusKHR enumeration. endif::VK_KHR_video_queue[] * Occlusion queries write one integer value - the number of samples passed. Pipeline statistics queries write one integer value for each bit that is enabled in the pname:pipelineStatistics when the pool is created, and the statistics values are written in bit order starting from the least significant bit. Timestamp queries write one integer value. ifdef::VK_KHR_performance_query[] Performance queries write one slink:VkPerformanceCounterResultKHR value for each slink:VkPerformanceCounterKHR in the query. endif::VK_KHR_performance_query[] ifdef::VK_EXT_transform_feedback[] Transform feedback queries write two integers; the first integer is the number of primitives successfully written to the corresponding transform feedback buffer and the second is the number of primitives output to the vertex stream, regardless of whether they were successfully captured or not. In other words, if the transform feedback buffer was sized too small for the number of primitives output by the vertex stream, the first integer represents the number of primitives actually written and the second is the number that would have been written if all the transform feedback buffers associated with that vertex stream were large enough. endif::VK_EXT_transform_feedback[] * If more than one query is retrieved and pname:stride is not at least as large as the size of the array of values corresponding to a single query, the values written to memory are undefined:. [open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos'] -- To retrieve status and results for a set of queries, call: include::{generated}/api/protos/vkGetQueryPoolResults.txt[] * pname:device is the logical device that owns the query pool. * pname:queryPool is the query pool managing the queries containing the desired results. * pname:firstQuery is the initial query index. * pname:queryCount is the number of queries to read. * pname:dataSize is the size in bytes of the buffer pointed to by pname:pData. * pname:pData is a pointer to a user-allocated buffer where the results will be written * pname:stride is the stride in bytes between results for individual queries within pname:pData. * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how and when results are returned. The range of queries read is defined by [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]#. For pipeline statistics queries, each query index in the pool contains one integer value for each bit that is enabled in slink:VkQueryPoolCreateInfo::pname:pipelineStatistics when the pool is created. If no bits are set in pname: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 <>. If ename:VK_QUERY_RESULT_64_BIT is not set and the result overflows a 32-bit value, the value may: either wrap or saturate. Similarly, if ename:VK_QUERY_RESULT_64_BIT is set and the result overflows a 64-bit value, the value may: either wrap or saturate. If ename:VK_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, fname:vkGetQueryPoolResults is guaranteed to succeed and return ename:VK_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 fname:vkGetQueryPoolResults may: not return in finite time. [[queries-wait-bit-not-set]] If ename:VK_QUERY_RESULT_WAIT_BIT and ename:VK_QUERY_RESULT_PARTIAL_BIT are both not set then no result values are written to pname:pData for queries that are in the unavailable state at the time of the call, and fname:vkGetQueryPoolResults returns ename:VK_NOT_READY. However, availability state is still written to pname:pData for those queries if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set. ifdef::VK_KHR_video_queue[] Similarly, the status is still written to pname:pData for those queries if ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set. endif::VK_KHR_video_queue[] If ename:VK_QUERY_RESULT_WAIT_BIT is not set, fname:vkGetQueryPoolResults may: return ename:VK_NOT_READY if there are queries in the unavailable state. [NOTE] .Note ==== Applications must: take care to ensure that use of the ename:VK_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 fname:vkCmdResetQueryPool, fname:vkCmdBeginQuery, and fname:vkCmdEndQuery for that query, then the query will remain in the available state until ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] fname:vkResetQueryPool is called or endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] the fname:vkCmdResetQueryPool 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 ename:VK_QUERY_RESULT_WAIT_BIT is used in combination with ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT. In this case, the returned availability status may: reflect the result of a previous use of the query unless ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] fname:vkResetQueryPool is called or endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] the fname:vkCmdResetQueryPool command has been executed since the last use of the query. ifdef::VK_KHR_video_queue[] A similar situation can arise with the ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag. endif::VK_KHR_video_queue[] ==== [NOTE] .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 ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_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 pname:pData for that query. If ename:VK_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 ename:VK_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] .Note ==== Satisfying this guarantee may: require careful ordering by the application, e.g. to read the availability status before reading the results. ==== ifdef::VK_KHR_video_queue[] If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, the final integer value written for each query indicates whether the result is available or not, and whether an error occurred. A value of zero indicates that the results are not yet available. Positive values indicate that the operations within the query completed successfully, and the query results are valid. Negative values indicate that the operations within the query completed unsuccessfully. Specific result codes are defined by the elink:VkQueryResultStatusKHR enumeration. endif::VK_KHR_video_queue[] .Valid Usage **** * [[VUID-vkGetQueryPoolResults-firstQuery-00813]] pname:firstQuery must: be less than the number of queries in pname:queryPool ifndef::VK_KHR_performance_query[] * [[VUID-vkGetQueryPoolResults-flags-02827]] If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags, then pname:pData and pname:stride must: be multiples of `4` endif::VK_KHR_performance_query[] ifdef::VK_KHR_performance_query[] * [[VUID-vkGetQueryPoolResults-flags-02828]] If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags and the pname:queryType used to create pname:queryPool was not ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:pData and pname:stride must: be multiples of `4` endif::VK_KHR_performance_query[] * [[VUID-vkGetQueryPoolResults-flags-00815]] If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then pname:pData and pname:stride must: be multiples of `8` ifdef::VK_KHR_performance_query[] * [[VUID-vkGetQueryPoolResults-queryType-03229]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:pData and pname:stride must: be multiples of the size of slink:VkPerformanceCounterResultKHR * [[VUID-vkGetQueryPoolResults-queryType-04519]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:stride must: be large enough to contain sname:VkQueryPoolPerformanceCreateInfoKHR::pname:counterIndexCount used to create pname:queryPool times the size of slink:VkPerformanceCounterResultKHR endif::VK_KHR_performance_query[] * [[VUID-vkGetQueryPoolResults-firstQuery-00816]] The sum of pname:firstQuery and pname:queryCount must: be less than or equal to the number of queries in pname:queryPool * [[VUID-vkGetQueryPoolResults-dataSize-00817]] pname:dataSize must: be large enough to contain the result of each query, as described <> * [[VUID-vkGetQueryPoolResults-queryType-00818]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain ename:VK_QUERY_RESULT_PARTIAL_BIT ifdef::VK_KHR_performance_query[] * [[VUID-vkGetQueryPoolResults-queryType-03230]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, pname:flags must: not contain ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT, ename:VK_QUERY_RESULT_PARTIAL_BIT or ename:VK_QUERY_RESULT_64_BIT * [[VUID-vkGetQueryPoolResults-queryType-03231]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:queryPool must: have been recorded once for each pass as retrieved via a call to flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR endif::VK_KHR_performance_query[] ifdef::VK_KHR_video_queue[] * [[VUID-vkGetQueryPoolResults-queryType-04810]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, pname:flags must: include ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR * [[VUID-vkGetQueryPoolResults-flags-04811]] If pname:flags includes ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, it must: not include ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT endif::VK_KHR_video_queue[] **** include::{generated}/validity/protos/vkGetQueryPoolResults.txt[] -- [open,refpage='VkQueryResultFlagBits',desc='Bitmask specifying how and when query results are returned',type='enums'] -- Bits which can: be set in flink:vkGetQueryPoolResults::pname:flags and flink:vkCmdCopyQueryPoolResults::pname:flags, specifying how and when results are returned, are: include::{generated}/api/enums/VkQueryResultFlagBits.txt[] * ename:VK_QUERY_RESULT_64_BIT specifies the results will be written as an array of 64-bit unsigned integer values. If this bit is not set, the results will be written as an array of 32-bit unsigned integer values. * ename:VK_QUERY_RESULT_WAIT_BIT specifies that Vulkan will wait for each query's status to become available before retrieving its results. * ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT specifies that the availability status accompanies the results. * ename:VK_QUERY_RESULT_PARTIAL_BIT specifies that returning partial results is acceptable. ifdef::VK_KHR_video_queue[] * ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR specifies that the last value returned in the query is a elink:VkQueryResultStatusKHR value. endif::VK_KHR_video_queue[] -- [open,refpage='VkQueryResultFlags',desc='Bitmask of VkQueryResultFlagBits',type='flags'] -- include::{generated}/api/flags/VkQueryResultFlags.txt[] tname:VkQueryResultFlags is a bitmask type for setting a mask of zero or more elink:VkQueryResultFlagBits. -- ifdef::VK_KHR_video_queue[] [open,refpage='VkQueryResultStatusKHR',desc='Specific status codes for operations',type='enums'] -- Specific status codes that can: be returned from a query are: include::{generated}/api/enums/VkQueryResultStatusKHR.txt[] * ename:VK_QUERY_RESULT_STATUS_NOT_READY_KHR specifies that the query result is not yet available. * ename:VK_QUERY_RESULT_STATUS_ERROR_KHR specifies that operations did not complete successfully. * ename:VK_QUERY_RESULT_STATUS_COMPLETE_KHR specifies that operations completed successfully and the query result is available. -- endif::VK_KHR_video_queue[] [open,refpage='vkCmdCopyQueryPoolResults',desc='Copy the results of queries in a query pool to a buffer object',type='protos'] -- To copy query statuses and numerical results directly to buffer memory, call: include::{generated}/api/protos/vkCmdCopyQueryPoolResults.txt[] * pname:commandBuffer is the command buffer into which this command will be recorded. * pname:queryPool is the query pool managing the queries containing the desired results. * pname:firstQuery is the initial query index. * pname:queryCount is the number of queries. pname:firstQuery and pname:queryCount together define a range of queries. * pname:dstBuffer is a slink:VkBuffer object that will receive the results of the copy command. * pname:dstOffset is an offset into pname:dstBuffer. * pname:stride is the stride in bytes between results for individual queries within pname:dstBuffer. The required size of the backing memory for pname:dstBuffer is determined as described above for flink:vkGetQueryPoolResults. * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how and when results are returned. fname:vkCmdCopyQueryPoolResults is guaranteed to see the effect of previous uses of fname:vkCmdResetQueryPool in the same queue, without any additional synchronization. Thus, the results will always reflect the most recent use of the query. pname:flags has the same possible values described above for the pname:flags parameter of flink:vkGetQueryPoolResults, but the different style of execution causes some subtle behavioral differences. Because fname:vkCmdCopyQueryPoolResults executes in order with respect to other query commands, there is less ambiguity about which use of a query is being requested. Results for all requested occlusion queries, pipeline statistics queries, ifdef::VK_EXT_transform_feedback[] transform feedback queries, endif::VK_EXT_transform_feedback[] and timestamp queries are written as 64-bit unsigned integer values if ename:VK_QUERY_RESULT_64_BIT is set or 32-bit unsigned integer values otherwise. ifdef::VK_KHR_performance_query[] Performance queries store results in a tightly packed array whose type is determined by the pname:unit member of the corresponding slink:VkPerformanceCounterKHR. endif::VK_KHR_performance_query[] If neither of ename:VK_QUERY_RESULT_WAIT_BIT and ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT are set, results are only written out for queries in the available state. If ename:VK_QUERY_RESULT_WAIT_BIT is set, the implementation will wait for each query's status to be in the available state before retrieving the numerical results for that query. This is guaranteed to reflect the most recent use of the query on the same queue, assuming that the query is not being simultaneously used by other queues. If the query does not become available in a finite amount of time (e.g. due to not issuing a query since the last reset), a ename:VK_ERROR_DEVICE_LOST error may: occur. Similarly, if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set and ename:VK_QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to reflect the most recent use of the query on the same queue, assuming that the query is not being simultaneously used by other queues. As with fname:vkGetQueryPoolResults, implementations must: guarantee that if they return a non-zero availability value, then the numerical results are valid. If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_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 for that query. ename:VK_QUERY_RESULT_PARTIAL_BIT must: not be used if the pool's pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP. fname:vkCmdCopyQueryPoolResults is considered to be a transfer operation, and its writes to buffer memory must: be synchronized using ename:VK_PIPELINE_STAGE_TRANSFER_BIT and ename:VK_ACCESS_TRANSFER_WRITE_BIT before using the results. .Valid Usage **** * [[VUID-vkCmdCopyQueryPoolResults-dstOffset-00819]] pname:dstOffset must: be less than the size of pname:dstBuffer * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00820]] pname:firstQuery must: be less than the number of queries in pname:queryPool * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00821]] The sum of pname:firstQuery and pname:queryCount must: be less than or equal to the number of queries in pname:queryPool * [[VUID-vkCmdCopyQueryPoolResults-flags-00822]] If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags then pname:dstOffset and pname:stride must: be multiples of `4` * [[VUID-vkCmdCopyQueryPoolResults-flags-00823]] If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then pname:dstOffset and pname:stride must: be multiples of `8` * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00824]] pname:dstBuffer must: have enough storage, from pname:dstOffset, to contain the result of each query, as described <> * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00825]] pname:dstBuffer must: have been created with ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00826]] If pname:dstBuffer is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object * [[VUID-vkCmdCopyQueryPoolResults-queryType-00827]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain ename:VK_QUERY_RESULT_PARTIAL_BIT ifdef::VK_KHR_performance_query[] * [[VUID-vkCmdCopyQueryPoolResults-queryType-03232]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, slink:VkPhysicalDevicePerformanceQueryPropertiesKHR::pname:allowCommandBufferQueryCopies must: be ename:VK_TRUE * [[VUID-vkCmdCopyQueryPoolResults-queryType-03233]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, pname:flags must: not contain ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT, ename:VK_QUERY_RESULT_PARTIAL_BIT or ename:VK_QUERY_RESULT_64_BIT * [[VUID-vkCmdCopyQueryPoolResults-queryType-03234]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:queryPool must: have been submitted once for each pass as retrieved via a call to flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR endif::VK_KHR_performance_query[] ifdef::VK_INTEL_performance_query[] * [[VUID-vkCmdCopyQueryPoolResults-queryType-02734]] flink:vkCmdCopyQueryPoolResults must: not be called if the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL endif::VK_INTEL_performance_query[] ifdef::VK_KHR_video_queue[] * [[VUID-vkCmdCopyQueryPoolResults-queryType-04812]] flink:vkCmdCopyQueryPoolResults must: not be called if the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHR or ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR endif::VK_KHR_video_queue[] **** include::{generated}/validity/protos/vkCmdCopyQueryPoolResults.txt[] -- [[queries-operation-undefined]] Rendering operations such as clears, MSAA resolves, attachment load/store operations, and blits may: count towards the results of queries. This behavior is implementation-dependent and may: vary depending on the path used within an implementation. For example, some implementations have several types of clears, some of which may: include vertices and some not. [[queries-occlusion]] == Occlusion Queries Occlusion queries track the number of samples that pass the per-fragment tests for a set of drawing commands. As such, occlusion queries are only available on queue families supporting graphics operations. The application can: then use these results to inform future rendering decisions. An occlusion query is begun and ended by calling fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively. When an occlusion query begins, the count of passing samples always starts at zero. For each drawing command, the count is incremented as described in <>. If pname:flags does not contain ename:VK_QUERY_CONTROL_PRECISE_BIT an implementation may: generate any non-zero result value for the query if the count of passing samples is non-zero. [NOTE] .Note ==== Not setting ename:VK_QUERY_CONTROL_PRECISE_BIT mode may: be more efficient on some implementations, and should: be used where it is sufficient to know a boolean result on whether any samples passed the per-fragment tests. In this case, some implementations may: only return zero or one, indifferent to the actual number of samples passing the per-fragment tests. ==== When an occlusion query finishes, the result for that query is marked as available. The application can: then either copy the result to a buffer (via fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via fname:vkGetQueryPoolResults). [NOTE] .Note ==== If occluding geometry is not drawn first, samples can: pass the depth test, but still not be visible in a final image. ==== [[queries-pipestats]] == Pipeline Statistics Queries Pipeline statistics queries allow the application to sample a specified set of sname:VkPipeline counters. These counters are accumulated by Vulkan for a set of either drawing or dispatching commands while a pipeline statistics query is active. As such, pipeline statistics queries are available on queue families supporting either graphics or compute operations. The availability of pipeline statistics queries is indicated by the pname:pipelineStatisticsQuery member of the sname:VkPhysicalDeviceFeatures object (see fname:vkGetPhysicalDeviceFeatures and fname:vkCreateDevice for detecting and requesting this query type on a sname:VkDevice). A pipeline statistics query is begun and ended by calling fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively. When a pipeline statistics query begins, all statistics counters are set to zero. While the query is active, the pipeline type determines which set of statistics are available, but these must: be configured on the query pool when it is created. If a statistic counter is issued on a command buffer that does not support the corresponding operation, the value of that counter is undefined: after the query has finished. At least one statistic counter relevant to the operations supported on the recording command buffer must: be enabled. [open,refpage='VkQueryPipelineStatisticFlagBits',desc='Bitmask specifying queried pipeline statistics',type='enums'] -- Bits which can: be set to individually enable pipeline statistics counters for query pools with slink:VkQueryPoolCreateInfo::pname:pipelineStatistics, and for secondary command buffers with slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics, are: include::{generated}/api/enums/VkQueryPipelineStatisticFlagBits.txt[] * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT specifies that queries managed by the pool will count the number of vertices processed by the <> stage. Vertices corresponding to incomplete primitives may: contribute to the count. * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT specifies that queries managed by the pool will count the number of primitives processed by the <> stage. If primitive restart is enabled, restarting the primitive topology has no effect on the count. Incomplete primitives may: be counted. * ename:VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT specifies that queries managed by the pool will count the number of vertex shader invocations. This counter's value is incremented each time a vertex shader is <>. * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT specifies that queries managed by the pool will count the number of geometry shader invocations. This counter's value is incremented each time a geometry shader is <>. In the case of <>, the geometry shader invocations count is incremented for each separate instanced invocation. * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT specifies that queries managed by the pool will count the number of primitives generated by geometry shader invocations. The counter's value is incremented each time the geometry shader emits a primitive. Restarting primitive topology using the SPIR-V instructions code:OpEndPrimitive or code:OpEndStreamPrimitive has no effect on the geometry shader output primitives count. * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT specifies that queries managed by the pool will count the number of primitives processed by the <> stage of the pipeline. The counter's value is incremented each time a primitive reaches the primitive clipping stage. * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT specifies that queries managed by the pool will count the number of primitives output by the <> stage of the pipeline. The counter's value is incremented each time a primitive passes the primitive clipping stage. The actual number of primitives output by the primitive clipping stage for a particular input primitive is implementation-dependent but must: satisfy the following conditions: ** If at least one vertex of the input primitive lies inside the clipping volume, the counter is incremented by one or more. ** Otherwise, the counter is incremented by zero or more. * ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT specifies that queries managed by the pool will count the number of fragment shader invocations. The counter's value is incremented each time the fragment shader is <>. * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT specifies that queries managed by the pool will count the number of patches processed by the tessellation control shader. The counter's value is incremented once for each patch for which a tessellation control shader is <>. * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT specifies that queries managed by the pool will count the number of invocations of the tessellation evaluation shader. The counter's value is incremented each time the tessellation evaluation shader is <>. * ename:VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT specifies that queries managed by the pool will count the number of compute shader invocations. The counter's value is incremented every time the compute shader is invoked. Implementations may: skip the execution of certain compute shader invocations or execute additional compute shader invocations for implementation-dependent reasons as long as the results of rendering otherwise remain unchanged. 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 <>. [NOTE] .Note ==== For example, tile-based rendering devices may: need to replay the scene multiple times, affecting some of the counts. ==== If a pipeline has pname:rasterizerDiscardEnable enabled, implementations may: discard primitives after the final <>. As a result, if pname: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 fname:vkCmdCopyQueryPoolResults), or request it be put into host memory (via fname:vkGetQueryPoolResults). -- [open,refpage='VkQueryPipelineStatisticFlags',desc='Bitmask of VkQueryPipelineStatisticFlagBits',type='flags'] -- include::{generated}/api/flags/VkQueryPipelineStatisticFlags.txt[] tname:VkQueryPipelineStatisticFlags is a bitmask type for setting a mask of zero or more elink:VkQueryPipelineStatisticFlagBits. -- [[queries-timestamps]] == Timestamp Queries _Timestamps_ provide applications with a mechanism for timing the execution of commands. A timestamp is an integer value generated by the sname:VkPhysicalDevice. Unlike other queries, timestamps do not operate over a range, and so do not use flink:vkCmdBeginQuery or flink:vkCmdEndQuery. The mechanism is built around a set of commands that allow the application to tell the sname:VkPhysicalDevice to write timestamp values to a <> and then either read timestamp values on the host (using flink:vkGetQueryPoolResults) or copy timestamp values to a sname:VkBuffer (using flink:vkCmdCopyQueryPoolResults). The application can: then compute differences between timestamps to determine execution time. The number of valid bits in a timestamp value is determined by the sname:VkQueueFamilyProperties::pname:timestampValidBits property of the queue on which the timestamp is written. Timestamps are supported on any queue which reports a non-zero value for pname:timestampValidBits via flink:vkGetPhysicalDeviceQueueFamilyProperties. If the <> limit is ename:VK_TRUE, timestamps are supported by every queue family that supports either graphics or compute operations (see slink:VkQueueFamilyProperties). The number of nanoseconds it takes for a timestamp value to be incremented by 1 can: be obtained from sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to fname:vkGetPhysicalDeviceProperties. ifdef::VK_KHR_synchronization2[] [open,refpage='vkCmdWriteTimestamp2KHR',desc='Write a device timestamp into a query object',type='protos'] -- :refpage: vkCmdWriteTimestamp2KHR To request a timestamp, call: include::{generated}/api/protos/vkCmdWriteTimestamp2KHR.txt[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:stage specifies a stage of the pipeline. * pname:queryPool is the query pool that will manage the timestamp. * pname:query is the query within the query pool that will contain the timestamp. When fname:vkCmdWriteTimestamp2KHR is submitted to a queue, it defines an execution dependency on commands that were submitted before it, and writes a timestamp to a query pool. The first <> includes all commands that occur earlier in <>. The synchronization scope is limited to operations on the pipeline stage specified by pname:stage. The second <> includes only the timestamp write operation. When the timestamp value is written, the availability status of the query is set to available. [NOTE] .Note ==== If an implementation is unable to detect completion and latch the timer at any specific stage of the pipeline, it may: instead do so at any logically later stage. ==== Comparisons between timestamps are not meaningful if the timestamps are written by commands submitted to different queues. [NOTE] .Note ==== An example of such a comparison is subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands. ==== ifdef::VK_VERSION_1_1,VK_KHR_multiview[] If fname:vkCmdWriteTimestamp2KHR is called while executing a render pass instance that has multiview enabled, the timestamp uses [eq]#N# consecutive query indices in the query pool (starting at pname:query) where [eq]#N# is the number of bits set in the view mask of the subpass the command is executed in. The resulting query values are determined by an implementation-dependent choice of one of the following behaviors: * The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command. * All [eq]#N# queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may: be the execution time of a single view. In either case, the application can: sum the differences between all [eq]#N# queries to determine the total execution time. endif::VK_VERSION_1_1,VK_KHR_multiview[] .Valid Usage **** :stageMaskName: stage include::{chapters}/commonvalidity/stage_mask_2_common.txt[] * [[VUID-vkCmdWriteTimestamp2KHR-synchronization2-03858]] The <> feature must: be enabled * [[VUID-vkCmdWriteTimestamp2KHR-stage-03859]] pname:stage must: only include a single pipeline stage * [[VUID-vkCmdWriteTimestamp2KHR-stage-03860]] pname:stage must: only include stages valid for the queue family that was used to create the command pool that pname:commandBuffer was allocated from * [[VUID-vkCmdWriteTimestamp2KHR-queryPool-03861]] pname:queryPool must: have been created with a pname:queryType of ename:VK_QUERY_TYPE_TIMESTAMP * [[VUID-vkCmdWriteTimestamp2KHR-queryPool-03862]] The query identified by pname:queryPool and pname:query must: be _unavailable_ * [[VUID-vkCmdWriteTimestamp2KHR-timestampValidBits-03863]] The command pool's queue family must: support a non-zero pname:timestampValidBits * [[VUID-vkCmdWriteTimestamp2KHR-query-04903]] pname:query must: be less than the number of queries in pname:queryPool ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-vkCmdWriteTimestamp2KHR-None-03864]] All queries used by the command must: be unavailable * [[VUID-vkCmdWriteTimestamp2KHR-query-03865]] If fname:vkCmdWriteTimestamp2KHR is called within a render pass instance, the sum of pname:query and the number of bits set in the current subpass's view mask must: be less than or equal to the number of queries in pname:queryPool endif::VK_VERSION_1_1,VK_KHR_multiview[] **** include::{generated}/validity/protos/vkCmdWriteTimestamp2KHR.txt[] -- endif::VK_KHR_synchronization2[] [open,refpage='vkCmdWriteTimestamp',desc='Write a device timestamp into a query object',type='protos'] -- :refpage: vkCmdWriteTimestamp To request a timestamp, call: include::{generated}/api/protos/vkCmdWriteTimestamp.txt[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:pipelineStage is a elink:VkPipelineStageFlagBits value, specifying a stage of the pipeline. * pname:queryPool is the query pool that will manage the timestamp. * pname:query is the query within the query pool that will contain the timestamp. fname:vkCmdWriteTimestamp latches the value of the timer when all previous commands have completed executing as far as the specified pipeline stage, and writes the timestamp value to memory. When the timestamp value is written, the availability status of the query is set to available. [NOTE] .Note ==== If an implementation is unable to detect completion and latch the timer at any specific stage of the pipeline, it may: instead do so at any logically later stage. ==== Comparisons between timestamps are not meaningful if the timestamps are written by commands submitted to different queues. [NOTE] .Note ==== An example of such a comparison is subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands. ==== ifdef::VK_VERSION_1_1,VK_KHR_multiview[] If fname:vkCmdWriteTimestamp is called while executing a render pass instance that has multiview enabled, the timestamp uses [eq]#N# consecutive query indices in the query pool (starting at pname:query) where [eq]#N# is the number of bits set in the view mask of the subpass the command is executed in. The resulting query values are determined by an implementation-dependent choice of one of the following behaviors: * The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command. * All [eq]#N# queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may: be the execution time of a single view. In either case, the application can: sum the differences between all [eq]#N# queries to determine the total execution time. endif::VK_VERSION_1_1,VK_KHR_multiview[] .Valid Usage **** include::{chapters}/commonvalidity/pipeline_stage_common.txt[] * [[VUID-vkCmdWriteTimestamp-queryPool-01416]] pname:queryPool must: have been created with a pname:queryType of ename:VK_QUERY_TYPE_TIMESTAMP * [[VUID-vkCmdWriteTimestamp-queryPool-00828]] The query identified by pname:queryPool and pname:query must: be _unavailable_ * [[VUID-vkCmdWriteTimestamp-timestampValidBits-00829]] The command pool's queue family must: support a non-zero pname:timestampValidBits * [[VUID-vkCmdWriteTimestamp-query-04904]] pname:query must: be less than the number of queries in pname:queryPool ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-vkCmdWriteTimestamp-None-00830]] All queries used by the command must: be unavailable * [[VUID-vkCmdWriteTimestamp-query-00831]] If fname:vkCmdWriteTimestamp is called within a render pass instance, the sum of pname:query and the number of bits set in the current subpass's view mask must: be less than or equal to the number of queries in pname:queryPool endif::VK_VERSION_1_1,VK_KHR_multiview[] **** include::{generated}/validity/protos/vkCmdWriteTimestamp.txt[] -- ifdef::VK_KHR_performance_query[] include::{chapters}/VK_KHR_performance_query/queriesperformance.txt[] endif::VK_KHR_performance_query[] ifdef::VK_EXT_transform_feedback[] [[queries-transform-feedback]] == Transform Feedback Queries Transform feedback queries track the number of primitives attempted to be written and actually written, by the vertex stream being captured, to a transform feedback buffer. This query is updated during drawing commands while transform feedback is active. The number of primitives actually written will be less than the number attempted to be written if the bound transform feedback buffer size was too small for the number of primitives actually drawn. Primitives are not written beyond the bound range of the transform feedback buffer. A transform feedback query is begun and ended by calling fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively to query for vertex stream zero. fname:vkCmdBeginQueryIndexedEXT and fname:vkCmdEndQueryIndexedEXT can: be used to begin and end transform feedback queries for any supported vertex stream. When a transform feedback query begins, the count of primitives written and primitives needed starts from zero. For each drawing command, the count is incremented as vertex attribute outputs are captured to the transform feedback buffers while transform feedback is active. When a transform feedback query finishes, the result for that query is marked as available. The application can: then either copy the result to a buffer (via fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via fname:vkGetQueryPoolResults). endif::VK_EXT_transform_feedback[] ifdef::VK_INTEL_performance_query[] include::{chapters}/VK_INTEL_performance_query/queries.txt[] endif::VK_INTEL_performance_query[] ifdef::VK_KHR_video_queue[] [[queries-result-status-only]] == Result Status Queries Result status queries are used for a single purpose - to check whether a set of operations has completed successfully or not, using the ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag. No other data is written to such a query. endif::VK_KHR_video_queue[] ifdef::VK_KHR_video_encode_queue[] [[queries-video-encode-bitstream-buffer-range]] == Video Encode Bitstream Buffer Range Bitstream buffer range queries describe the range of bytes written in the bitstream buffer by video encode commands. When an encode command is recorded within a bitstream buffer range query, two values are written to the query slot. The first value is an offset into the bitstream buffer where the encoded video data was written. This offset is an additional offset from the start of the range specified by the application. The second value is a size value describing the number of bytes written to the bitstream buffer beyond the offset. One slot is consumed for each slice in each command recorded between a begin and end query pair. endif::VK_KHR_video_encode_queue[]