| // Copyright 2015-2023 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 |
| <<queries-pools, Query Pool>>. |
| 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 <<queries-occlusion,Occlusion Queries>>, |
| <<queries-pipestats,Pipeline Statistics Queries>>, |
| ifdef::VK_KHR_video_queue[] |
| <<queries-result-status-only, Result Status Queries>>, |
| endif::VK_KHR_video_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| <<queries-video-encode-feedback, Video Encode Feedback Queries>> |
| endif::VK_KHR_video_encode_queue[] |
| and <<queries-timestamps, Timestamp Queries>>. |
| ifdef::VK_KHR_performance_query[] |
| <<queries-performance, Performance Queries>> are supported if the associated |
| extension is available. |
| endif::VK_KHR_performance_query[] |
| ifdef::VK_EXT_transform_feedback[] |
| <<queries-transform-feedback, Transform Feedback Queries>> are supported if |
| the associated extension is available. |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_INTEL_performance_query[] |
| <<queries-performance-intel>> are supported if the associated extension is |
| available. |
| endif::VK_INTEL_performance_query[] |
| ifdef::VK_EXT_mesh_shader[] |
| <<queries-mesh-shader, Mesh Shader Queries>> are supported if the associated |
| extension is available. |
| endif::VK_EXT_mesh_shader[] |
| |
| 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.adoc[] |
| -- |
| |
| [open,refpage='vkCreateQueryPool',desc='Create a new query pool object',type='protos'] |
| -- |
| :refpage: vkCreateQueryPool |
| :objectnameplural: query pools |
| :objectnamecamelcase: queryPool |
| :objectcount: 1 |
| |
| To create a query pool, call: |
| |
| include::{generated}/api/protos/vkCreateQueryPool.adoc[] |
| |
| * 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 |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pQueryPool is a pointer to a slink:VkQueryPool handle in which the |
| resulting query pool object is returned. |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| ifdef::VKSC_VERSION_1_0[] |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] |
| **** |
| endif::VKSC_VERSION_1_0[] |
| |
| include::{generated}/validity/protos/vkCreateQueryPool.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying 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 |
| <<queries-pipestats>>. |
| |
| pname:pipelineStatistics is ignored if pname:queryType is not |
| ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkQueryPoolCreateInfo-queryType-00791]] |
| If the <<features-pipelineStatisticsQuery, |
| pname:pipelineStatisticsQuery>> feature is not enabled, pname:queryType |
| must: not be ename:VK_QUERY_TYPE_PIPELINE_STATISTICS |
| ifdef::VK_EXT_mesh_shader[] |
| * [[VUID-VkQueryPoolCreateInfo-meshShaderQueries-07068]] |
| If the <<features-meshShaderQueries, pname:meshShaderQueries>> feature |
| is not enabled, pname:queryType must: not be |
| ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT |
| * [[VUID-VkQueryPoolCreateInfo-meshShaderQueries-07069]] |
| If the <<features-meshShaderQueries, pname:meshShaderQueries>> feature |
| is not enabled, and pname:queryType is |
| ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, pname:pipelineStatistics must: |
| not contain |
| ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT or |
| ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT |
| endif::VK_EXT_mesh_shader[] |
| * [[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 |
| ifdef::VKSC_VERSION_1_0[] |
| * [[VUID-VkQueryPoolCreateInfo-queryType-05046]] |
| If pname:queryType is ename:VK_QUERY_TYPE_OCCLUSION then |
| pname:queryCount must: be less than or equal to the maximum of all |
| slink:VkDeviceObjectReservationCreateInfo::pname:maxOcclusionQueriesPerPool |
| values specified when pname:device was created |
| * [[VUID-VkQueryPoolCreateInfo-queryType-05047]] |
| If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS then |
| pname:queryCount must: be less than or equal to the maximum of all |
| slink:VkDeviceObjectReservationCreateInfo::pname:maxPipelineStatisticsQueriesPerPool |
| values specified when pname:device was created |
| * [[VUID-VkQueryPoolCreateInfo-queryType-05048]] |
| If pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP then |
| pname:queryCount must: be less than or equal to the maximum of all |
| slink:VkDeviceObjectReservationCreateInfo::pname:maxTimestampQueriesPerPool |
| values specified when pname:device was created |
| ifdef::VK_KHR_performance_query[] |
| * [[VUID-VkQueryPoolCreateInfo-queryType-05049]] |
| If pname:queryType is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR then |
| pname:queryCount must: be less than or equal to the maximum of all |
| slink:VkPerformanceQueryReservationInfoKHR::pname:maxPerformanceQueriesPerPool |
| values specified when pname:device was created |
| endif::VK_KHR_performance_query[] |
| endif::VKSC_VERSION_1_0[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * [[VUID-VkQueryPoolCreateInfo-queryType-07133]] |
| If pname:queryType is ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, |
| then the pname:pNext chain must: include a slink:VkVideoProfileInfoKHR |
| structure with pname:videoCodecOperation specifying an encode operation |
| * [[VUID-VkQueryPoolCreateInfo-queryType-07906]] |
| If pname:queryType is ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, |
| then the pname:pNext chain must: include a |
| slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure |
| * [[VUID-VkQueryPoolCreateInfo-queryType-07907]] |
| If pname:queryType is ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, and |
| the pname:pNext chain includes a slink:VkVideoProfileInfoKHR structure |
| and a slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure, then |
| slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::pname:encodeFeedbackFlags |
| must: not contain any bits that are not set in |
| slink:VkVideoEncodeCapabilitiesKHR::pname:supportedEncodeFeedbackFlags, |
| as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the |
| <<video-profiles,video profile>> described by |
| slink:VkVideoProfileInfoKHR and its pname:pNext chain |
| endif::VK_KHR_video_encode_queue[] |
| **** |
| |
| include::{generated}/validity/structs/VkQueryPoolCreateInfo.adoc[] |
| -- |
| |
| [open,refpage='VkQueryPoolCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkQueryPoolCreateFlags.adoc[] |
| |
| 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.adoc[] |
| endif::VK_KHR_performance_query[] |
| |
| ifdef::VKSC_VERSION_1_0[] |
| ifdef::hidden[] |
| // tag::scremoved[] |
| * fname:vkDestroyQueryPool <<SCID-4>> |
| // end::scremoved[] |
| endif::hidden[] |
| |
| Query pools cannot: be destroyed <<SCID-4>>. |
| If |
| slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,pname:deviceDestroyFreesMemory>> |
| is ename:VK_TRUE, the memory is returned to the system when the device is |
| destroyed. |
| |
| endif::VKSC_VERSION_1_0[] |
| ifndef::VKSC_VERSION_1_0[] |
| |
| [open,refpage='vkDestroyQueryPool',desc='Destroy a query pool object',type='protos'] |
| -- |
| To destroy a query pool, call: |
| |
| include::{generated}/api/protos/vkDestroyQueryPool.adoc[] |
| |
| * 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 |
| <<memory-allocation, Memory Allocation>> 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.adoc[] |
| -- |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| [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.adoc[] |
| |
| * ename:VK_QUERY_TYPE_OCCLUSION specifies an <<queries-occlusion, |
| occlusion query>>. |
| * ename:VK_QUERY_TYPE_PIPELINE_STATISTICS specifies a <<queries-pipestats, |
| pipeline statistics query>>. |
| * ename:VK_QUERY_TYPE_TIMESTAMP specifies a <<queries-timestamps, |
| timestamp query>>. |
| ifdef::VK_KHR_performance_query[] |
| * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR specifies a |
| <<queries-performance, performance query>>. |
| endif::VK_KHR_performance_query[] |
| ifdef::VK_EXT_transform_feedback[] |
| * ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT specifies a |
| <<queries-transform-feedback, transform feedback query>>. |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_EXT_primitives_generated_query[] |
| * ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT specifies a |
| <<queries-primitives-generated, primitives generated query>>. |
| endif::VK_EXT_primitives_generated_query[] |
| ifdef::VK_KHR_acceleration_structure[] |
| * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR specifies |
| a <<acceleration-structure-copying, acceleration structure size query>> |
| for use with flink:vkCmdWriteAccelerationStructuresPropertiesKHR or |
| flink:vkWriteAccelerationStructuresPropertiesKHR. |
| * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR |
| specifies a <<acceleration-structure-copying, serialization acceleration |
| structure size query>>. |
| endif::VK_KHR_acceleration_structure[] |
| ifdef::VK_KHR_ray_tracing_maintenance1[] |
| * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR specifies an |
| <<acceleration-structure-copying, acceleration structure size query>> |
| for use with flink:vkCmdWriteAccelerationStructuresPropertiesKHR or |
| flink:vkWriteAccelerationStructuresPropertiesKHR. |
| * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR |
| specifies a <<serialized-as-header, serialization acceleration structure |
| pointer count query>>. |
| endif::VK_KHR_ray_tracing_maintenance1[] |
| ifdef::VK_NV_ray_tracing[] |
| * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV specifies |
| an <<acceleration-structure-copying, acceleration structure size query>> |
| for use with flink:vkCmdWriteAccelerationStructuresPropertiesNV. |
| endif::VK_NV_ray_tracing[] |
| ifdef::VK_INTEL_performance_query[] |
| * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL specifies a |
| <<queries-performance-intel, Intel performance query>>. |
| endif::VK_INTEL_performance_query[] |
| ifdef::VK_KHR_video_queue[] |
| * ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR specifies a |
| <<queries-result-status-only, result status query>>. |
| endif::VK_KHR_video_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR specifies a |
| <<queries-video-encode-feedback, video encode feedback query>>. |
| endif::VK_KHR_video_encode_queue[] |
| ifdef::VK_EXT_mesh_shader[] |
| * ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT specifies a |
| <<queries-mesh-shader, generated mesh primitives query>>. |
| endif::VK_EXT_mesh_shader[] |
| -- |
| |
| |
| [[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_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdWriteTimestamp2, |
| endif::VK_VERSION_1_3,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:. |
| A query is made available by the operation of flink:vkCmdEndQuery, |
| ifdef::VK_EXT_transform_feedback[] |
| flink:vkCmdEndQueryIndexedEXT, |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdWriteTimestamp2, |
| endif::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| or flink:vkCmdWriteTimestamp. |
| Both the availability status and numerical results can: be retrieved by |
| calling either flink:vkGetQueryPoolResults or |
| flink:vkCmdCopyQueryPoolResults. |
| |
| After query pool creation, each query is in an uninitialized state and 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.adoc[] |
| |
| * 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. |
| |
| This command defines an execution dependency between other query commands |
| that reference the same query. |
| |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:firstQuery and pname:queryCount that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:firstQuery and pname:queryCount that occur later in |
| <<synchronization-submission-order,submission order>>. |
| |
| The operation of this command happens after the first scope and happens |
| before the second scope. |
| |
| 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.adoc[] |
| -- |
| |
| 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.adoc[] |
| 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.adoc[] |
| 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 <<features-hostQueryReset, pname:hostQueryReset>> 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.adoc[] |
| -- |
| 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 <<features-inheritedQueries, |
| pname:inheritedQueries>> 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 <<commandbuffers-recording, Command |
| Buffer Recording>> 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[] |
| |
| ifdef::VK_KHR_video_queue[] |
| A query must: either begin and end inside the same video coding scope, or |
| must: both begin and end outside of a video coding scope and must: not |
| contain entire video coding scopes. |
| endif::VK_KHR_video_queue[] |
| |
| [open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos',xrefs='vkCmdEndQuery vkCmdBeginQueryIndexedEXT vkCmdEndQueryIndexedEXT'] |
| -- |
| :refpage: vkCmdBeginQuery |
| |
| To begin a query, call: |
| |
| include::{generated}/api/protos/vkCmdBeginQuery.adoc[] |
| |
| * 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 <<queries-occlusion,Occlusion Queries>>. |
| |
| 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. |
| |
| ifdef::VK_KHR_video_queue[] |
| Furthermore, if the query is started within a video coding scope, the |
| following command buffer states are initialized for the query type: |
| |
| * [[queries-operation-active-query-index]] The _active_query_index_ is set |
| to the value specified by pname:query. |
| * [[queries-operation-last-activatable-query-index]] The _last activatable |
| query index_ is also set to the value specified by pname:query. |
| |
| Each <<video-coding,video coding operation>> stores a result to the query |
| corresponding to the current active query index, followed by incrementing |
| the active query index. |
| If the active query index gets incremented past the last activatable query |
| index, issuing any further video coding operations results in undefined: |
| behavior. |
| |
| [NOTE] |
| .Note |
| ==== |
| In practice, this means that currently no more than a single video coding |
| operation must: be issued between a begin and end query pair. |
| ==== |
| |
| endif::VK_KHR_video_queue[] |
| |
| This command defines an execution dependency between other query commands |
| that reference the same query. |
| |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query that occur later in |
| <<synchronization-submission-order,submission order>>. |
| |
| The operation of this command happens after the first scope and happens |
| before the second scope. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/query_begin_common.adoc[] |
| * [[VUID-vkCmdBeginQuery-queryPool-01922]] |
| pname:queryPool must: have been created with a pname:queryType that |
| differs from that of any queries that are |
| <<queries-operation-active,active>> within pname:commandBuffer |
| ifdef::VK_EXT_mesh_shader[] |
| * [[VUID-vkCmdBeginQuery-queryType-07070]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT the |
| sname:VkCommandPool that pname:commandBuffer was allocated from must: |
| support graphics operations |
| endif::VK_EXT_mesh_shader[] |
| 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[] |
| ifdef::VK_EXT_primitives_generated_query[] |
| * [[VUID-vkCmdBeginQuery-queryType-06687]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the sname:VkCommandPool |
| that pname:commandBuffer was allocated from must: support graphics |
| operations |
| * [[VUID-vkCmdBeginQuery-queryType-06688]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT then |
| <<features-primitivesGeneratedQuery, pname:primitivesGeneratedQuery>> |
| must: be enabled |
| endif::VK_EXT_primitives_generated_query[] |
| include::{chapters}/commonvalidity/performance_query_begin_common.adoc[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdBeginQuery.adoc[] |
| -- |
| |
| ifdef::VK_EXT_transform_feedback[] |
| [open,refpage='vkCmdBeginQueryIndexedEXT',desc='Begin an indexed query',type='protos',xrefs='vkCmdBeginQuery vkCmdEndQuery vkCmdEndQueryIndexedEXT'] |
| -- |
| :refpage: vkCmdBeginQueryIndexedEXT |
| |
| To begin an indexed query, call: |
| |
| include::{generated}/api/protos/vkCmdBeginQueryIndexedEXT.adoc[] |
| |
| * 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 |
| ifdef::VK_EXT_primitives_generated_query[] |
| or ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, |
| endif::VK_EXT_primitives_generated_query[] |
| 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. |
| |
| This command defines an execution dependency between other query commands |
| that reference the same query index. |
| |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query and pname:index that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query and pname:index that occur later in |
| <<synchronization-submission-order,submission order>>. |
| |
| The operation of this command happens after the first scope and happens |
| before the second scope. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/query_begin_common.adoc[] |
| * [[VUID-vkCmdBeginQueryIndexedEXT-queryPool-04753]] |
| If the pname:queryPool was created with the same pname:queryType as that |
| of another <<queries-operation-active,active>> 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-06692]] |
| If the pname:queryType used to create pname:queryPool was not |
| ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT |
| ifdef::VK_EXT_primitives_generated_query[] |
| and not ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, |
| endif::VK_EXT_primitives_generated_query[] |
| the pname:index must: be zero |
| ifdef::VK_EXT_primitives_generated_query[] |
| * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06689]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the sname:VkCommandPool |
| that pname:commandBuffer was allocated from must: support graphics |
| operations |
| * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06690]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the pname:index parameter |
| must: be less than |
| sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams |
| * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06691]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT and the |
| <<features-primitivesGeneratedQueryWithNonZeroStreams, |
| pname:primitivesGeneratedQueryWithNonZeroStreams>> feature is not |
| enabled, the pname:index parameter must: be zero |
| * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06693]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT then |
| <<features-primitivesGeneratedQuery, pname:primitivesGeneratedQuery>> |
| must: be enabled |
| endif::VK_EXT_primitives_generated_query[] |
| * [[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 |
| ifdef::VK_EXT_mesh_shader[] |
| * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-07071]] |
| The pname:queryType used to create pname:queryPool must: not be |
| ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT |
| endif::VK_EXT_mesh_shader[] |
| include::{chapters}/commonvalidity/performance_query_begin_common.adoc[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdBeginQueryIndexedEXT.adoc[] |
| -- |
| 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.adoc[] |
| |
| * ename:VK_QUERY_CONTROL_PRECISE_BIT specifies the precision of |
| <<queries-occlusion, occlusion queries>>. |
| -- |
| |
| [open,refpage='VkQueryControlFlags',desc='Bitmask of VkQueryControlFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkQueryControlFlags.adoc[] |
| |
| 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',xrefs='vkCmdBeginQuery vkCmdBeginQueryIndexedEXT vkCmdEndQueryIndexedEXT'] |
| -- |
| :refpage: vkCmdEndQuery |
| |
| To end a query after the set of desired drawing or dispatching commands is |
| executed, call: |
| |
| include::{generated}/api/protos/vkCmdEndQuery.adoc[] |
| |
| * 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. |
| |
| The command completes the query in pname:queryPool identified by |
| pname:query, and marks it as available. |
| |
| This command defines an execution dependency between other query commands |
| that reference the same query. |
| |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes only the operation of this command. |
| |
| 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[] |
| |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdEndQuery-None-01923]] |
| All queries used by the command must: be |
| <<queries-operation-active,active>> |
| * [[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::{chapters}/commonvalidity/query_end_common.adoc[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdEndQuery.adoc[] |
| -- |
| |
| ifdef::VK_EXT_transform_feedback[] |
| [open,refpage='vkCmdEndQueryIndexedEXT',desc='Ends a query',type='protos',xrefs='vkCmdBeginQuery vkCmdEndQuery vkCmdBeginQueryIndexedEXT'] |
| -- |
| :refpage: vkCmdEndQueryIndexedEXT |
| |
| To end an indexed query after the set of desired drawing or dispatching |
| commands is recorded, call: |
| |
| include::{generated}/api/protos/vkCmdEndQueryIndexedEXT.adoc[] |
| |
| * 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 command completes the query in pname:queryPool identified by pname:query |
| and pname:index, and marks it as available. |
| |
| The fname:vkCmdEndQueryIndexedEXT command operates the same as the |
| flink:vkCmdEndQuery command, except that it also accepts a query type |
| specific pname:index parameter. |
| |
| This command defines an execution dependency between other query commands |
| that reference the same query index. |
| |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes only the operation of this command. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdEndQueryIndexedEXT-None-02342]] |
| All queries used by the command must: be |
| <<queries-operation-active,active>> |
| * [[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-06694]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT |
| ifdef::VK_EXT_primitives_generated_query[] |
| or ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, |
| endif::VK_EXT_primitives_generated_query[] |
| the pname:index parameter must: be less than |
| sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams |
| * [[VUID-vkCmdEndQueryIndexedEXT-queryType-06695]] |
| If the pname:queryType used to create pname:queryPool was not |
| ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT |
| ifdef::VK_EXT_primitives_generated_query[] |
| and not ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, |
| endif::VK_EXT_primitives_generated_query[] |
| the pname:index must: be zero |
| * [[VUID-vkCmdEndQueryIndexedEXT-queryType-06696]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT |
| ifdef::VK_EXT_primitives_generated_query[] |
| or ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, |
| endif::VK_EXT_primitives_generated_query[] |
| pname:index must: equal the pname:index used to begin the query |
| include::{chapters}/commonvalidity/query_end_common.adoc[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdEndQueryIndexedEXT.adoc[] |
| -- |
| 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[] |
| ifdef::VK_EXT_primitives_generated_query[] |
| primitives generated queries, |
| endif::VK_EXT_primitives_generated_query[] |
| ifdef::VK_EXT_mesh_shader[] |
| mesh shader queries, |
| endif::VK_EXT_mesh_shader[] |
| ifdef::VK_KHR_video_encode_queue[] |
| video encode feedback queries, |
| endif::VK_KHR_video_encode_queue[] |
| 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[] |
| ifdef::VK_EXT_primitives_generated_query[] |
| Primitives generated queries write the number of primitives output to |
| the vertex stream, regardless of whether transform feedback is active or |
| not, or whether they were successfully captured by transform feedback or |
| not. |
| This is identical to the second integer of the transform feedback |
| queries if transform feedback is active. |
| endif::VK_EXT_primitives_generated_query[] |
| ifdef::VK_EXT_mesh_shader[] |
| Mesh shader queries write a single integer. |
| endif::VK_EXT_mesh_shader[] |
| ifdef::VK_KHR_video_encode_queue[] |
| Video encode feedback queries write one or more integer values for each |
| bit that is enabled in |
| slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::pname:encodeFeedbackFlags |
| when the pool is created, and the feedback values are written in bit |
| order starting from the least significant bit, as described |
| <<queries-video-encode-feedback,here>>. |
| endif::VK_KHR_video_encode_queue[] |
| * 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'] |
| -- |
| :refpage: vkGetQueryPoolResults |
| |
| To retrieve status and results for a set of queries, call: |
| |
| include::{generated}/api/protos/vkGetQueryPoolResults.adoc[] |
| |
| * 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. |
| |
| Any results written for a query are written according to |
| <<queries-operation-memorylayout,a layout dependent on the query type>>. |
| |
| 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. |
| Behavior when not all queries are available is described |
| <<queries-wait-bit-not-set, below>>. |
| |
| If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all |
| queries in pname:queryPool identified by pname:firstQuery and |
| pname:queryCount are copied to pname:pData, along with an extra availability |
| ifdef::VK_KHR_video_queue[or status] |
| value written directly after the results of each query and interpreted as an |
| unsigned integer. |
| A value of zero indicates that the results are not yet available, otherwise |
| the query is complete and results are available. |
| The size of the availability |
| ifdef::VK_KHR_video_queue[or status] |
| values is 64 bits if ename:VK_QUERY_RESULT_64_BIT is set in pname:flags. |
| Otherwise, it is 32 bits. |
| |
| ifdef::VK_KHR_video_queue[] |
| If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries |
| in pname:queryPool identified by pname:firstQuery and pname:queryCount are |
| copied to pname:pData, along with an extra status value written directly |
| after the results of each query and interpreted as a signed integer. |
| 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. |
| |
| elink:VkQueryResultStatusKHR defines specific meaning for values returned |
| here, though implementations are free to return other values. |
| endif::VK_KHR_video_queue[] |
| |
| [NOTE] |
| .Note |
| ==== |
| If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT |
| ifdef::VK_KHR_video_queue[or ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR] |
| is set, the layout of data in the buffer is a __(result,availability)__ |
| ifdef::VK_KHR_video_queue[or __(result,status)__] |
| pair for each query returned, and pname:stride is the stride between each |
| pair. |
| ==== |
| |
| Results for any available query written by this command are final and |
| represent the final result of the query. |
| If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, then for any query that is |
| unavailable, an intermediate result between zero and the final result value |
| is written for that query. |
| Otherwise, any result written by this command is undefined:. |
| |
| If ename:VK_QUERY_RESULT_64_BIT is set, results and, if returned, |
| availability |
| ifdef::VK_KHR_video_queue[or status] |
| values for all queries are written as an array of 64-bit values. |
| ifdef::VK_KHR_performance_query[] |
| If the pname:queryPool was created with |
| ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are |
| written as an array of the type indicated by |
| slink:VkPerformanceCounterKHR::pname:storage for the counter being queried. |
| endif::VK_KHR_performance_query[] |
| Otherwise, results and availability |
| ifdef::VK_KHR_video_queue[or status] |
| values are written as an array of 32-bit values. |
| If an unsigned integer query's value overflows the result type, the value |
| may: either wrap or saturate. |
| ifdef::VK_KHR_performance_query[] |
| If a signed integer query's value overflows the result type, the value is |
| undefined:. |
| If a floating point query's value is not representable as the result type, |
| the value is undefined:. |
| endif::VK_KHR_performance_query[] |
| |
| If ename:VK_QUERY_RESULT_WAIT_BIT is set, this command defines an execution |
| dependency with any earlier commands that writes one of the identified |
| queries. |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all instances of flink:vkCmdEndQuery, |
| ifdef::VK_EXT_transform_feedback[] |
| flink:vkCmdEndQueryIndexedEXT, |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdWriteTimestamp2, |
| endif::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| and flink:vkCmdWriteTimestamp that reference any query in pname:queryPool |
| indicated by pname:firstQuery and pname:queryCount. |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes the host operations of this command. |
| |
| [[queries-wait-bit-not-set]] |
| 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. |
| ==== |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetQueryPoolResults-None-09401]] |
| All queries used by the command must: not be uninitialized |
| * [[VUID-vkGetQueryPoolResults-firstQuery-00813]] |
| pname:firstQuery must: be less than the number of queries in |
| pname:queryPool |
| * [[VUID-vkGetQueryPoolResults-flags-02828]] |
| If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags |
| ifdef::VK_KHR_performance_query[] |
| and the pname:queryType used to create pname:queryPool was not |
| ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, |
| endif::VK_KHR_performance_query[] |
| then pname:pData and pname:stride must: be multiples of `4` |
| * [[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` |
| * [[VUID-vkGetQueryPoolResults-stride-08993]] |
| If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, pname:stride |
| must: be large enough to contain the unsigned integer representing |
| availability |
| ifdef::VK_KHR_video_queue[or status] |
| in addition to the query result. |
| 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 the |
| slink: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 <<queries-operation-memorylayout,here>> |
| * [[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, |
| ifdef::VK_KHR_video_queue[] |
| ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, |
| endif::VK_KHR_video_queue[] |
| 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, then 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, then |
| it must: not include ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT |
| endif::VK_KHR_video_queue[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetQueryPoolResults.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * 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. |
| See <<queries-result-status-only, result status query>> for information |
| on how an application can determine whether the use of this flag bit is |
| supported. |
| endif::VK_KHR_video_queue[] |
| -- |
| |
| [open,refpage='VkQueryResultFlags',desc='Bitmask of VkQueryResultFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkQueryResultFlags.adoc[] |
| |
| 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'] |
| -- |
| [[query-result-status-codes]] |
| Specific status codes that can: be returned from a query are: |
| |
| include::{generated}/api/enums/VkQueryResultStatusKHR.adoc[] |
| |
| * 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. |
| ifdef::VK_KHR_video_encode_queue[] |
| * ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR |
| indicates that a video encode operation did not complete successfully |
| due to the destination video bitstream buffer range not being |
| sufficiently large to fit the encoded bitstream data. |
| endif::VK_KHR_video_encode_queue[] |
| -- |
| 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.adoc[] |
| |
| * 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. |
| |
| Any results written for a query are written according to |
| <<queries-operation-memorylayout,a layout dependent on the query type>>. |
| |
| Results for any query in pname:queryPool identified by pname:firstQuery and |
| pname:queryCount that is available are copied to pname:dstBuffer. |
| |
| If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all |
| queries in pname:queryPool identified by pname:firstQuery and |
| pname:queryCount are copied to pname:dstBuffer, along with an extra |
| availability value written directly after the results of each query and |
| interpreted as an unsigned integer. |
| A value of zero indicates that the results are not yet available, otherwise |
| the query is complete and results are available. |
| |
| ifdef::VK_KHR_video_queue[] |
| If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries |
| in pname:queryPool identified by pname:firstQuery and pname:queryCount are |
| copied to pname:dstBuffer, along with an extra status value written directly |
| after the results of each query and interpreted as a signed integer. |
| 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. |
| |
| elink:VkQueryResultStatusKHR defines specific meaning for values returned |
| here, though implementations are free to return other values. |
| endif::VK_KHR_video_queue[] |
| |
| Results for any available query written by this command are final and |
| represent the final result of the query. |
| If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, then for any query that is |
| unavailable, an intermediate result between zero and the final result value |
| is written for that query. |
| Otherwise, any result written by this command is undefined:. |
| |
| If ename:VK_QUERY_RESULT_64_BIT is set, results and availability |
| ifdef::VK_KHR_video_queue[or status] |
| values for all queries are written as an array of 64-bit values. |
| ifdef::VK_KHR_performance_query[] |
| If the pname:queryPool was created with |
| ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are |
| written as an array of the type indicated by |
| slink:VkPerformanceCounterKHR::pname:storage for the counter being queried. |
| endif::VK_KHR_performance_query[] |
| Otherwise, results and availability |
| ifdef::VK_KHR_video_queue[or status] |
| values are written as an array of 32-bit values. |
| If an unsigned integer query's value overflows the result type, the value |
| may: either wrap or saturate. |
| ifdef::VK_KHR_performance_query[] |
| If a signed integer query's value overflows the result type, the value is |
| undefined:. |
| If a floating point query's value is not representable as the result type, |
| the value is undefined:. |
| endif::VK_KHR_performance_query[] |
| |
| This command defines an execution dependency between other query commands |
| that reference the same query. |
| |
| The first <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| If pname:flags does not include ename:VK_QUERY_RESULT_WAIT_BIT, |
| ifdef::VK_EXT_transform_feedback[] |
| flink:vkCmdEndQueryIndexedEXT, |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdWriteTimestamp2, |
| endif::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdEndQuery, and flink:vkCmdWriteTimestamp are excluded from this |
| scope. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands which reference the queries in pname:queryPool |
| indicated by pname:query that occur later in |
| <<synchronization-submission-order,submission order>>. |
| |
| The operation of this command happens after the first scope and happens |
| before the second scope. |
| |
| 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-None-09402]] |
| All queries used by the command must: not be uninitialized when the |
| command is executed |
| * [[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 |
| <<queries-operation-memorylayout,here>> |
| * [[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, |
| ifdef::VK_KHR_video_queue[] |
| ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, |
| endif::VK_KHR_video_queue[] |
| 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-06901]] |
| If the pname:queryType used to create pname:queryPool was |
| ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, then pname:flags must: |
| include ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR |
| * [[VUID-vkCmdCopyQueryPoolResults-flags-06902]] |
| If pname:flags includes ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, then |
| it must: not include ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT |
| endif::VK_KHR_video_queue[] |
| * [[VUID-vkCmdCopyQueryPoolResults-None-07429]] |
| All queries used by the command must: not be active |
| * [[VUID-vkCmdCopyQueryPoolResults-None-08752]] |
| All queries used by the command must: have been made _available_ by |
| prior executed commands |
| **** |
| |
| include::{generated}/validity/protos/vkCmdCopyQueryPoolResults.adoc[] |
| -- |
| |
| [[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 |
| <<fragops-samplecount,Sample Counting>>. |
| 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. |
| |
| Setting ename:VK_QUERY_CONTROL_PRECISE_BIT does not guarantee that different |
| implementations return the same number of samples in an occlusion query. |
| Some implementations may kill fragments in the |
| <<pipelines-graphics-subsets-pre-rasterization, pre-rasterization shader |
| stage>>, and these killed fragments do not contribute to the final result of |
| the query. |
| It is possible that some implementations generate a zero result value for |
| the query, while others generate a non-zero value. |
| ==== |
| |
| 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 been made available. |
| 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 in |
| slink:VkQueryPoolCreateInfo::pname:pipelineStatistics for query pools and in |
| slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics for secondary |
| command buffers, individually enabling pipeline statistics counters, are: |
| |
| include::{generated}/api/enums/VkQueryPipelineStatisticFlagBits.adoc[] |
| |
| * 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 <<drawing,input assembly>> 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 <<drawing,input assembly>> 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 |
| <<shaders-vertex-execution,invoked>>. |
| * 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 |
| <<shaders-geometry-execution,invoked>>. |
| In the case of <<geometry-invocations,instanced geometry shaders>>, 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 <<vertexpostproc-clipping,Primitive Clipping>> 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 <<vertexpostproc-clipping,Primitive Clipping>> 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 |
| <<fragops-shader,invoked>>. |
| * 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 |
| <<shaders-tessellation-control-execution,invoked>>. |
| * 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 <<shaders-tessellation-evaluation-execution,invoked>>. |
| * 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. |
| ifdef::VK_EXT_mesh_shader[] |
| * ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT |
| specifies that queries managed by the pool will count the number of task |
| shader invocations. |
| The counter's value is incremented every time the task shader is |
| invoked. |
| * ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT |
| specifies that queries managed by the pool will count the number of mesh |
| shader invocations. |
| The counter's value is incremented every time the mesh shader is |
| invoked. |
| endif::VK_EXT_mesh_shader[] |
| |
| 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 |
| <<queries-operation-undefined,Query Operation>>. |
| |
| ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] |
| This counting difference is especially true if the pipeline contains mesh or |
| task shaders, which may affect several of the counters in unexpected ways. |
| endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] |
| |
| [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 |
| <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>>. |
| 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.adoc[] |
| |
| 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 |
| <<queries-pools,query pool>> 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 <<limits-timestampComputeAndGraphics, |
| pname:timestampComputeAndGraphics>> 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_VERSION_1_3,VK_KHR_synchronization2[] |
| [open,refpage='vkCmdWriteTimestamp2',desc='Write a device timestamp into a query object',type='protos',alias='vkCmdWriteTimestamp2KHR'] |
| -- |
| :refpage: vkCmdWriteTimestamp2 |
| |
| To request a timestamp and write the value to memory, call: |
| |
| ifdef::VK_VERSION_1_3[] |
| include::{generated}/api/protos/vkCmdWriteTimestamp2.adoc[] |
| endif::VK_VERSION_1_3[] |
| |
| ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] |
| |
| ifdef::VK_KHR_synchronization2[] |
| include::{generated}/api/protos/vkCmdWriteTimestamp2KHR.adoc[] |
| endif::VK_KHR_synchronization2[] |
| |
| * 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:vkCmdWriteTimestamp2 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 <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| The synchronization scope is limited to operations on the pipeline stage |
| specified by pname:stage. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes only the timestamp write operation. |
| |
| [NOTE] |
| .Note |
| ==== |
| Implementations may write the timestamp at any stage that is |
| <<synchronization-pipeline-stages-order, logically later>> than pname:stage. |
| ==== |
| |
| Any timestamp write that <<synchronization-dependencies-execution, |
| happens-after>> another timestamp write in the same submission must: not |
| have a lower value unless its value overflows the maximum supported integer |
| bit width of the query. |
| ifdef::VK_EXT_calibrated_timestamps[] |
| If `apiext:VK_EXT_calibrated_timestamps` is enabled, this extends to |
| timestamp writes across all submissions on the same logical device: any |
| timestamp write that <<synchronization-dependencies-execution, |
| happens-after>> another must: not have a lower value unless its value |
| overflows the maximum supported integer bit width of the query. |
| Timestamps written by this command must: be in the |
| ename:VK_TIME_DOMAIN_DEVICE_EXT <<VkTimeDomainEXT, time domain>>. |
| endif::VK_EXT_calibrated_timestamps[] |
| If an overflow occurs, the timestamp value must: wrap back to zero. |
| |
| [NOTE] |
| .Note |
| ==== |
| Comparisons between timestamps should be done between timestamps where they |
| are guaranteed to not decrease. |
| For example, subtracting an older timestamp from a newer one to determine |
| the execution time of a sequence of commands is only a reliable measurement |
| if the two timestamp writes were performed in the same |
| ifdef::VK_EXT_calibrated_timestamps[] |
| submission, or if the writes were performed on the same logical device and |
| `apiext:VK_EXT_calibrated_timestamps` is enabled. |
| endif::VK_EXT_calibrated_timestamps[] |
| ifndef::VK_EXT_calibrated_timestamps[] |
| submission. |
| endif::VK_EXT_calibrated_timestamps[] |
| ==== |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| |
| If fname:vkCmdWriteTimestamp2 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.adoc[] |
| * [[VUID-vkCmdWriteTimestamp2-synchronization2-03858]] |
| The <<features-synchronization2, pname:synchronization2>> feature must: |
| be enabled |
| * [[VUID-vkCmdWriteTimestamp2-stage-03859]] |
| pname:stage must: only include a single pipeline stage |
| * [[VUID-vkCmdWriteTimestamp2-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-vkCmdWriteTimestamp2-queryPool-03861]] |
| pname:queryPool must: have been created with a pname:queryType of |
| ename:VK_QUERY_TYPE_TIMESTAMP |
| * [[VUID-vkCmdWriteTimestamp2-timestampValidBits-03863]] |
| The command pool's queue family must: support a non-zero |
| pname:timestampValidBits |
| * [[VUID-vkCmdWriteTimestamp2-query-04903]] |
| pname:query must: be less than the number of queries in pname:queryPool |
| * [[VUID-vkCmdWriteTimestamp2-None-03864]] |
| All queries used by the command must: be _unavailable_ |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * [[VUID-vkCmdWriteTimestamp2-query-03865]] |
| If fname:vkCmdWriteTimestamp2 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/vkCmdWriteTimestamp2.adoc[] |
| -- |
| endif::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| |
| [open,refpage='vkCmdWriteTimestamp',desc='Write a device timestamp into a query object',type='protos'] |
| -- |
| :refpage: vkCmdWriteTimestamp |
| |
| To request a timestamp and write the value to memory, call: |
| |
| include::{generated}/api/protos/vkCmdWriteTimestamp.adoc[] |
| |
| * 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. |
| |
| When fname:vkCmdWriteTimestamp 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 <<synchronization-dependencies-scopes, synchronization scope>> |
| includes all commands that occur earlier in |
| <<synchronization-submission-order,submission order>>. |
| The synchronization scope is limited to operations on the pipeline stage |
| specified by pname:pipelineStage. |
| |
| The second <<synchronization-dependencies-scopes, synchronization scope>> |
| includes only the timestamp write operation. |
| |
| [NOTE] |
| .Note |
| ==== |
| Implementations may write the timestamp at any stage that is |
| <<synchronization-pipeline-stages-order, logically later>> than pname:stage. |
| ==== |
| |
| Any timestamp write that <<synchronization-dependencies-execution, |
| happens-after>> another timestamp write in the same submission must: not |
| have a lower value unless its value overflows the maximum supported integer |
| bit width of the query. |
| ifdef::VK_EXT_calibrated_timestamps[] |
| If `apiext:VK_EXT_calibrated_timestamps` is enabled, this extends to |
| timestamp writes across all submissions on the same logical device: any |
| timestamp write that <<synchronization-dependencies-execution, |
| happens-after>> another must: not have a lower value unless its value |
| overflows the maximum supported integer bit width of the query. |
| Timestamps written by this command must: be in the |
| ename:VK_TIME_DOMAIN_DEVICE_EXT <<VkTimeDomainEXT, time domain>>. |
| endif::VK_EXT_calibrated_timestamps[] |
| If an overflow occurs, the timestamp value must: wrap back to zero. |
| |
| [NOTE] |
| .Note |
| ==== |
| Comparisons between timestamps should be done between timestamps where they |
| are guaranteed to not decrease. |
| For example, subtracting an older timestamp from a newer one to determine |
| the execution time of a sequence of commands is only a reliable measurement |
| if the two timestamp writes were performed in the same |
| ifdef::VK_EXT_calibrated_timestamps[] |
| submission, or if the writes were performed on the same logical device and |
| `apiext:VK_EXT_calibrated_timestamps` is enabled. |
| endif::VK_EXT_calibrated_timestamps[] |
| ifndef::VK_EXT_calibrated_timestamps[] |
| submission. |
| endif::VK_EXT_calibrated_timestamps[] |
| ==== |
| |
| |
| 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.adoc[] |
| * [[VUID-vkCmdWriteTimestamp-queryPool-01416]] |
| pname:queryPool must: have been created with a pname:queryType of |
| ename:VK_QUERY_TYPE_TIMESTAMP |
| * [[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 |
| * [[VUID-vkCmdWriteTimestamp-None-00830]] |
| All queries used by the command must: be _unavailable_ |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * [[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.adoc[] |
| -- |
| |
| ifdef::VK_KHR_performance_query[] |
| include::{chapters}/VK_KHR_performance_query/queriesperformance.adoc[] |
| 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_EXT_primitives_generated_query[] |
| [[queries-primitives-generated]] |
| == Primitives Generated Queries |
| |
| When a generated primitive query for a vertex stream is active, the |
| primitives-generated count is incremented every time a primitive emitted to |
| that stream reaches the transform feedback stage, whether or not transform |
| feedback is active. |
| A primitives generated 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 primitives generated queries for any supported vertex |
| stream. |
| When a primitives generated query begins, the count of primitives generated |
| starts from zero. |
| |
| When a primitives generated 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 |
| ==== |
| The result of this query is typically identical to |
| ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT, but the |
| primitives generated query is deterministic, i.e. it must be identical to |
| the number of primitives processed. |
| ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT may vary for |
| implementation-dependent reasons, e.g. the same primitive may be processed |
| multiple times for purposes of clipping. |
| ==== |
| endif::VK_EXT_primitives_generated_query[] |
| |
| |
| ifdef::VK_EXT_mesh_shader[] |
| [[queries-mesh-shader]] |
| == Mesh Shader Queries |
| |
| When a generated mesh primitives query is active, the |
| mesh-primitives-generated count is incremented every time a primitive |
| emitted from the mesh shader stage reaches the fragment shader stage. |
| When a generated mesh primitives query begins, the mesh-primitives-generated |
| count starts from zero. |
| |
| Mesh and task shader pipeline statistics queries function the same way that |
| invocation queries work for other shader stages, counting the number of |
| times the respective shader stage has been run. |
| When the statistics query begins, the invocation counters start from zero. |
| endif::VK_EXT_mesh_shader[] |
| |
| ifdef::VK_INTEL_performance_query[] |
| include::{chapters}/VK_INTEL_performance_query/queries.adoc[] |
| endif::VK_INTEL_performance_query[] |
| |
| |
| ifdef::VK_KHR_video_queue[] |
| [[queries-result-status-only]] |
| == Result Status Queries |
| |
| Result status queries serve a single purpose: allowing the application to |
| determine whether a set of operations have completed successfully or not, as |
| indicated by the elink:VkQueryResultStatusKHR value written when retrieving |
| the result of a query using the ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR |
| flag. |
| |
| Unlike other query types, result status queries do not track or maintain any |
| other data beyond the completion status, thus no other data is written when |
| retrieving their results. |
| |
| Support for result status queries is indicated by |
| slink:VkQueueFamilyQueryResultStatusPropertiesKHR::pname:queryResultStatusSupport |
| , as returned by flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the |
| queue family in question. |
| endif::VK_KHR_video_queue[] |
| |
| |
| ifdef::VK_KHR_video_encode_queue[] |
| [[queries-video-encode-feedback]] |
| == Video Encode Feedback Queries |
| |
| Video encode feedback queries allow the application to capture feedback |
| values generated by video encode operations. |
| As such, video encode feedback queries are available on queue families |
| supporting video encode operations. |
| The availability of individual video encode feedback values is indicated by |
| the bits of |
| slink:VkVideoEncodeCapabilitiesKHR::pname:supportedEncodeFeedbackFlags, as |
| returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the |
| <<video-profiles,video profile>> the queries are intended to be used with. |
| |
| The set of enabled video encode feedback values must: be configured on the |
| query pool when it is created using the pname:encodeFeedbackFlags member of |
| the slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR included in the |
| pname:pNext chain of slink:VkQueryPoolCreateInfo. |
| |
| [open,refpage='VkQueryPoolVideoEncodeFeedbackCreateInfoKHR',desc='Structure specifying enabled video encode feedback values',type='structs'] |
| -- |
| The sname:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkQueryPoolVideoEncodeFeedbackCreateInfoKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:encodeFeedbackFlags is a bitmask of |
| elink:VkVideoEncodeFeedbackFlagBitsKHR values specifying the set of |
| enabled video encode feedback values captured by queries of the new |
| pool. |
| |
| include::{generated}/validity/structs/VkQueryPoolVideoEncodeFeedbackCreateInfoKHR.adoc[] |
| -- |
| |
| [open,refpage='VkVideoEncodeFeedbackFlagBitsKHR',desc='Bits specifying queried video encode feedback values',type='enums'] |
| -- |
| Bits which can: be set in |
| slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::pname:encodeFeedbackFlags |
| for video encode feedback query pools are: |
| |
| include::{generated}/api/enums/VkVideoEncodeFeedbackFlagBitsKHR.adoc[] |
| |
| * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR specifies |
| that queries managed by the pool will capture the byte offset of the |
| bitstream data written by the video encode operation to the bitstream |
| buffer specified in slink:VkVideoEncodeInfoKHR::pname:dstBuffer relative |
| to the offset specified in |
| slink:VkVideoEncodeInfoKHR::pname:dstBufferOffset. |
| * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR specifies |
| that queries managed by the pool will capture the number of bytes |
| written by the video encode operation to the bitstream buffer specified |
| in slink:VkVideoEncodeInfoKHR::pname:dstBuffer. |
| * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR specifies |
| that queries managed by the pool will capture a boolean value indicating |
| that the data written to the bitstream buffer specified in |
| slink:VkVideoEncodeInfoKHR::pname:dstBuffer contains overridden |
| parameters. |
| |
| When retrieving the results of video encode feedback queries, the values |
| corresponding to each enabled video encode feedback are written in the order |
| of the bits defined above, followed by an optional value indicating |
| availability or result status if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT |
| or ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is specified, respectively. |
| -- |
| |
| [open,refpage='VkVideoEncodeFeedbackFlagsKHR',desc='Bitmask of VkVideoEncodeFeedbackFlagBitsKHR',type='flags'] |
| -- |
| include::{generated}/api/flags/VkVideoEncodeFeedbackFlagsKHR.adoc[] |
| |
| tname:VkVideoEncodeFeedbackFlagsKHR is a bitmask type for setting a mask of |
| zero or more elink:VkVideoEncodeFeedbackFlagBitsKHR. |
| -- |
| endif::VK_KHR_video_encode_queue[] |
