1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[queries]] 6= Queries 7 8_Queries_ provide a mechanism to return information about the processing of 9a sequence of Vulkan commands. 10Query operations are asynchronous, and as such, their results are not 11returned immediately. 12Instead, their results, and their availability status are stored in a 13<<queries-pools, Query Pool>>. 14The state of these queries can: be read back on the host, or copied to a 15buffer object on the device. 16 17The supported query types are <<queries-occlusion,Occlusion Queries>>, 18<<queries-pipestats,Pipeline Statistics Queries>>, 19ifdef::VK_KHR_video_queue[] 20<<queries-result-status-only, Result Status Queries>>, 21endif::VK_KHR_video_queue[] 22ifdef::VK_KHR_video_encode_queue[] 23<<queries-video-encode-feedback, Video Encode Feedback Queries>> 24endif::VK_KHR_video_encode_queue[] 25and <<queries-timestamps, Timestamp Queries>>. 26ifdef::VK_KHR_performance_query[] 27<<queries-performance, Performance Queries>> are supported if the associated 28extension is available. 29endif::VK_KHR_performance_query[] 30ifdef::VK_EXT_transform_feedback[] 31<<queries-transform-feedback, Transform Feedback Queries>> are supported if 32the associated extension is available. 33endif::VK_EXT_transform_feedback[] 34ifdef::VK_INTEL_performance_query[] 35<<queries-performance-intel>> are supported if the associated extension is 36available. 37endif::VK_INTEL_performance_query[] 38ifdef::VK_EXT_mesh_shader[] 39<<queries-mesh-shader, Mesh Shader Queries>> are supported if the associated 40extension is available. 41endif::VK_EXT_mesh_shader[] 42 43ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 44Several additional queries with specific purposes associated with ray 45tracing are available if the corresponding extensions are supported, as 46described for elink:VkQueryType. 47endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 48 49 50[[queries-pools]] 51== Query Pools 52 53[open,refpage='VkQueryPool',desc='Opaque handle to a query pool object',type='handles'] 54-- 55Queries are managed using _query pool_ objects. 56Each query pool is a collection of a specific number of queries of a 57particular type. 58 59Query pools are represented by sname:VkQueryPool handles: 60 61include::{generated}/api/handles/VkQueryPool.adoc[] 62-- 63 64[open,refpage='vkCreateQueryPool',desc='Create a new query pool object',type='protos'] 65-- 66:refpage: vkCreateQueryPool 67:objectnameplural: query pools 68:objectnamecamelcase: queryPool 69:objectcount: 1 70 71To create a query pool, call: 72 73include::{generated}/api/protos/vkCreateQueryPool.adoc[] 74 75 * pname:device is the logical device that creates the query pool. 76 * pname:pCreateInfo is a pointer to a slink:VkQueryPoolCreateInfo 77 structure containing the number and type of queries to be managed by the 78 pool. 79 * pname:pAllocator controls host memory allocation as described in the 80 <<memory-allocation, Memory Allocation>> chapter. 81 * pname:pQueryPool is a pointer to a slink:VkQueryPool handle in which the 82 resulting query pool object is returned. 83 84include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 85 86ifdef::VKSC_VERSION_1_0[] 87.Valid Usage 88**** 89include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 90**** 91endif::VKSC_VERSION_1_0[] 92 93include::{generated}/validity/protos/vkCreateQueryPool.adoc[] 94-- 95 96[open,refpage='VkQueryPoolCreateInfo',desc='Structure specifying parameters of a newly created query pool',type='structs'] 97-- 98The sname:VkQueryPoolCreateInfo structure is defined as: 99 100include::{generated}/api/structs/VkQueryPoolCreateInfo.adoc[] 101 102 * pname:sType is a elink:VkStructureType value identifying this structure. 103 * pname:pNext is `NULL` or a pointer to a structure extending this 104 structure. 105 * pname:flags is reserved for future use. 106 * pname:queryType is a elink:VkQueryType value specifying the type of 107 queries managed by the pool. 108 * pname:queryCount is the number of queries managed by the pool. 109 * pname:pipelineStatistics is a bitmask of 110 elink:VkQueryPipelineStatisticFlagBits specifying which counters will be 111 returned in queries on the new pool, as described below in 112 <<queries-pipestats>>. 113 114pname:pipelineStatistics is ignored if pname:queryType is not 115ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. 116 117.Valid Usage 118**** 119 * [[VUID-VkQueryPoolCreateInfo-queryType-00791]] 120 If the <<features-pipelineStatisticsQuery, 121 pname:pipelineStatisticsQuery>> feature is not enabled, pname:queryType 122 must: not be ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 123ifdef::VK_EXT_mesh_shader[] 124 * [[VUID-VkQueryPoolCreateInfo-meshShaderQueries-07068]] 125 If the <<features-meshShaderQueries, pname:meshShaderQueries>> feature 126 is not enabled, pname:queryType must: not be 127 ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT 128 * [[VUID-VkQueryPoolCreateInfo-meshShaderQueries-07069]] 129 If the <<features-meshShaderQueries, pname:meshShaderQueries>> feature 130 is not enabled, and pname:queryType is 131 ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, pname:pipelineStatistics must: 132 not contain 133 ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT or 134 ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT 135endif::VK_EXT_mesh_shader[] 136 * [[VUID-VkQueryPoolCreateInfo-queryType-00792]] 137 If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, 138 pname:pipelineStatistics must: be a valid combination of 139 elink:VkQueryPipelineStatisticFlagBits values 140ifdef::VK_KHR_performance_query[] 141 * [[VUID-VkQueryPoolCreateInfo-queryType-03222]] 142 If pname:queryType is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 143 pname:pNext chain must: include a 144 slink:VkQueryPoolPerformanceCreateInfoKHR structure 145endif::VK_KHR_performance_query[] 146 * [[VUID-VkQueryPoolCreateInfo-queryCount-02763]] 147 pname:queryCount must: be greater than 0 148ifdef::VKSC_VERSION_1_0[] 149 * [[VUID-VkQueryPoolCreateInfo-queryType-05046]] 150 If pname:queryType is ename:VK_QUERY_TYPE_OCCLUSION then 151 pname:queryCount must: be less than or equal to the maximum of all 152 slink:VkDeviceObjectReservationCreateInfo::pname:maxOcclusionQueriesPerPool 153 values specified when pname:device was created 154 * [[VUID-VkQueryPoolCreateInfo-queryType-05047]] 155 If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS then 156 pname:queryCount must: be less than or equal to the maximum of all 157 slink:VkDeviceObjectReservationCreateInfo::pname:maxPipelineStatisticsQueriesPerPool 158 values specified when pname:device was created 159 * [[VUID-VkQueryPoolCreateInfo-queryType-05048]] 160 If pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP then 161 pname:queryCount must: be less than or equal to the maximum of all 162 slink:VkDeviceObjectReservationCreateInfo::pname:maxTimestampQueriesPerPool 163 values specified when pname:device was created 164ifdef::VK_KHR_performance_query[] 165 * [[VUID-VkQueryPoolCreateInfo-queryType-05049]] 166 If pname:queryType is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR then 167 pname:queryCount must: be less than or equal to the maximum of all 168 slink:VkPerformanceQueryReservationInfoKHR::pname:maxPerformanceQueriesPerPool 169 values specified when pname:device was created 170endif::VK_KHR_performance_query[] 171endif::VKSC_VERSION_1_0[] 172ifdef::VK_KHR_video_encode_queue[] 173 * [[VUID-VkQueryPoolCreateInfo-queryType-07133]] 174 If pname:queryType is ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, 175 then the pname:pNext chain must: include a slink:VkVideoProfileInfoKHR 176 structure with pname:videoCodecOperation specifying an encode operation 177 * [[VUID-VkQueryPoolCreateInfo-queryType-07906]] 178 If pname:queryType is ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, 179 then the pname:pNext chain must: include a 180 slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure 181 * [[VUID-VkQueryPoolCreateInfo-queryType-07907]] 182 If pname:queryType is ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, and 183 the pname:pNext chain includes a slink:VkVideoProfileInfoKHR structure 184 and a slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure, then 185 slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::pname:encodeFeedbackFlags 186 must: not contain any bits that are not set in 187 slink:VkVideoEncodeCapabilitiesKHR::pname:supportedEncodeFeedbackFlags, 188 as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the 189 <<video-profiles,video profile>> described by 190 slink:VkVideoProfileInfoKHR and its pname:pNext chain 191endif::VK_KHR_video_encode_queue[] 192**** 193 194include::{generated}/validity/structs/VkQueryPoolCreateInfo.adoc[] 195-- 196 197[open,refpage='VkQueryPoolCreateFlags',desc='Reserved for future use',type='flags'] 198-- 199include::{generated}/api/flags/VkQueryPoolCreateFlags.adoc[] 200 201tname:VkQueryPoolCreateFlags is a bitmask type for setting a mask, but is 202currently reserved for future use. 203-- 204 205ifdef::VK_KHR_performance_query[] 206include::{chapters}/VK_KHR_performance_query/querycreateinfo.adoc[] 207endif::VK_KHR_performance_query[] 208 209ifdef::VKSC_VERSION_1_0[] 210ifdef::hidden[] 211// tag::scremoved[] 212 * fname:vkDestroyQueryPool <<SCID-4>> 213// end::scremoved[] 214endif::hidden[] 215 216Query pools cannot: be destroyed <<SCID-4>>. 217If 218slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,pname:deviceDestroyFreesMemory>> 219is ename:VK_TRUE, the memory is returned to the system when the device is 220destroyed. 221 222endif::VKSC_VERSION_1_0[] 223ifndef::VKSC_VERSION_1_0[] 224 225[open,refpage='vkDestroyQueryPool',desc='Destroy a query pool object',type='protos'] 226-- 227To destroy a query pool, call: 228 229include::{generated}/api/protos/vkDestroyQueryPool.adoc[] 230 231 * pname:device is the logical device that destroys the query pool. 232 * pname:queryPool is the query pool to destroy. 233 * pname:pAllocator controls host memory allocation as described in the 234 <<memory-allocation, Memory Allocation>> chapter. 235 236.Valid Usage 237**** 238 * [[VUID-vkDestroyQueryPool-queryPool-00793]] 239 All submitted commands that refer to pname:queryPool must: have 240 completed execution 241 * [[VUID-vkDestroyQueryPool-queryPool-00794]] 242 If sname:VkAllocationCallbacks were provided when pname:queryPool was 243 created, a compatible set of callbacks must: be provided here 244 * [[VUID-vkDestroyQueryPool-queryPool-00795]] 245 If no sname:VkAllocationCallbacks were provided when pname:queryPool was 246 created, pname:pAllocator must: be `NULL` 247**** 248 249[NOTE] 250.Note 251==== 252Applications can: verify that pname:queryPool can: be destroyed by checking 253that fname:vkGetQueryPoolResults() without the 254ename:VK_QUERY_RESULT_PARTIAL_BIT flag returns ename:VK_SUCCESS for all 255queries that are used in command buffers submitted for execution. 256==== 257 258include::{generated}/validity/protos/vkDestroyQueryPool.adoc[] 259-- 260 261endif::VKSC_VERSION_1_0[] 262 263[open,refpage='VkQueryType',desc='Specify the type of queries managed by a query pool',type='enums'] 264-- 265Possible values of slink:VkQueryPoolCreateInfo::pname:queryType, specifying 266the type of queries managed by the pool, are: 267 268include::{generated}/api/enums/VkQueryType.adoc[] 269 270 * ename:VK_QUERY_TYPE_OCCLUSION specifies an <<queries-occlusion, 271 occlusion query>>. 272 * ename:VK_QUERY_TYPE_PIPELINE_STATISTICS specifies a <<queries-pipestats, 273 pipeline statistics query>>. 274 * ename:VK_QUERY_TYPE_TIMESTAMP specifies a <<queries-timestamps, 275 timestamp query>>. 276ifdef::VK_KHR_performance_query[] 277 * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR specifies a 278 <<queries-performance, performance query>>. 279endif::VK_KHR_performance_query[] 280ifdef::VK_EXT_transform_feedback[] 281 * ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT specifies a 282 <<queries-transform-feedback, transform feedback query>>. 283endif::VK_EXT_transform_feedback[] 284ifdef::VK_EXT_primitives_generated_query[] 285 * ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT specifies a 286 <<queries-primitives-generated, primitives generated query>>. 287endif::VK_EXT_primitives_generated_query[] 288ifdef::VK_KHR_acceleration_structure[] 289 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR specifies 290 a <<acceleration-structure-copying, acceleration structure size query>> 291 for use with flink:vkCmdWriteAccelerationStructuresPropertiesKHR or 292 flink:vkWriteAccelerationStructuresPropertiesKHR. 293 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR 294 specifies a <<acceleration-structure-copying, serialization acceleration 295 structure size query>>. 296endif::VK_KHR_acceleration_structure[] 297ifdef::VK_KHR_ray_tracing_maintenance1[] 298 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR specifies an 299 <<acceleration-structure-copying, acceleration structure size query>> 300 for use with flink:vkCmdWriteAccelerationStructuresPropertiesKHR or 301 flink:vkWriteAccelerationStructuresPropertiesKHR. 302 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR 303 specifies a <<serialized-as-header, serialization acceleration structure 304 pointer count query>>. 305endif::VK_KHR_ray_tracing_maintenance1[] 306ifdef::VK_NV_ray_tracing[] 307 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV specifies 308 an <<acceleration-structure-copying, acceleration structure size query>> 309 for use with flink:vkCmdWriteAccelerationStructuresPropertiesNV. 310endif::VK_NV_ray_tracing[] 311ifdef::VK_INTEL_performance_query[] 312 * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL specifies a 313 <<queries-performance-intel, Intel performance query>>. 314endif::VK_INTEL_performance_query[] 315ifdef::VK_KHR_video_queue[] 316 * ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR specifies a 317 <<queries-result-status-only, result status query>>. 318endif::VK_KHR_video_queue[] 319ifdef::VK_KHR_video_encode_queue[] 320 * ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR specifies a 321 <<queries-video-encode-feedback, video encode feedback query>>. 322endif::VK_KHR_video_encode_queue[] 323ifdef::VK_EXT_mesh_shader[] 324 * ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT specifies a 325 <<queries-mesh-shader, generated mesh primitives query>>. 326endif::VK_EXT_mesh_shader[] 327-- 328 329 330[[queries-operation]] 331== Query Operation 332 333The operation of queries is controlled by the commands 334flink:vkCmdBeginQuery, flink:vkCmdEndQuery, 335ifdef::VK_EXT_transform_feedback[] 336flink:vkCmdBeginQueryIndexedEXT, flink:vkCmdEndQueryIndexedEXT, 337endif::VK_EXT_transform_feedback[] 338flink:vkCmdResetQueryPool, flink:vkCmdCopyQueryPoolResults, 339ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 340flink:vkCmdWriteTimestamp2, 341endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 342and flink:vkCmdWriteTimestamp. 343 344In order for a sname:VkCommandBuffer to record query management commands, 345the queue family for which its sname:VkCommandPool was created must: support 346the appropriate type of operations (graphics, compute) suitable for the 347query type of a given query pool. 348 349Each query in a query pool has a status that is either _unavailable_ or 350_available_, and also has state to store the numerical results of a query 351operation of the type requested when the query pool was created. 352Resetting a query via flink:vkCmdResetQueryPool 353ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 354or flink:vkResetQueryPool 355endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 356sets the status to unavailable and makes the numerical results undefined:. 357A query is made available by the operation of flink:vkCmdEndQuery, 358ifdef::VK_EXT_transform_feedback[] 359flink:vkCmdEndQueryIndexedEXT, 360endif::VK_EXT_transform_feedback[] 361ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 362flink:vkCmdWriteTimestamp2, 363endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 364or flink:vkCmdWriteTimestamp. 365Both the availability status and numerical results can: be retrieved by 366calling either flink:vkGetQueryPoolResults or 367flink:vkCmdCopyQueryPoolResults. 368 369After query pool creation, each query is in an uninitialized state and must: 370be reset before it is used. 371Queries must: also be reset between uses. 372 373ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 374 375If a logical device includes multiple physical devices, then each command 376that writes a query must: execute on a single physical device, and any call 377to flink:vkCmdBeginQuery must: execute the corresponding flink:vkCmdEndQuery 378command on the same physical device. 379 380endif::VK_VERSION_1_1,VK_KHR_device_group[] 381 382[open,refpage='vkCmdResetQueryPool',desc='Reset queries in a query pool',type='protos'] 383-- 384To reset a range of queries in a query pool on a queue, call: 385 386include::{generated}/api/protos/vkCmdResetQueryPool.adoc[] 387 388 * pname:commandBuffer is the command buffer into which this command will 389 be recorded. 390 * pname:queryPool is the handle of the query pool managing the queries 391 being reset. 392 * pname:firstQuery is the initial query index to reset. 393 * pname:queryCount is the number of queries to reset. 394 395When executed on a queue, this command sets the status of query indices 396[eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to 397unavailable. 398 399This command defines an execution dependency between other query commands 400that reference the same query. 401 402The first <<synchronization-dependencies-scopes, synchronization scope>> 403includes all commands which reference the queries in pname:queryPool 404indicated by pname:firstQuery and pname:queryCount that occur earlier in 405<<synchronization-submission-order,submission order>>. 406 407The second <<synchronization-dependencies-scopes, synchronization scope>> 408includes all commands which reference the queries in pname:queryPool 409indicated by pname:firstQuery and pname:queryCount that occur later in 410<<synchronization-submission-order,submission order>>. 411 412The operation of this command happens after the first scope and happens 413before the second scope. 414 415ifdef::VK_KHR_performance_query[] 416If the pname:queryType used to create pname:queryPool was 417ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command sets the status of 418query indices [eq]#[pname:firstQuery, pname:firstQuery {plus} 419pname:queryCount - 1]# to unavailable for each pass of pname:queryPool, as 420indicated by a call to 421flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. 422 423[NOTE] 424.Note 425==== 426Because fname:vkCmdResetQueryPool resets all the passes of the indicated 427queries, applications must not record a fname:vkCmdResetQueryPool command 428for a pname:queryPool created with ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR 429in a command buffer that needs to be submitted multiple times as indicated 430by a call to flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. 431Otherwise applications will never be able to complete the recorded queries. 432==== 433endif::VK_KHR_performance_query[] 434 435 436.Valid Usage 437**** 438 * [[VUID-vkCmdResetQueryPool-firstQuery-00796]] 439 pname:firstQuery must: be less than the number of queries in 440 pname:queryPool 441 * [[VUID-vkCmdResetQueryPool-firstQuery-00797]] 442 The sum of pname:firstQuery and pname:queryCount must: be less than or 443 equal to the number of queries in pname:queryPool 444 * [[VUID-vkCmdResetQueryPool-None-02841]] 445 All queries used by the command must: not be active 446ifdef::VK_KHR_performance_query[] 447 * [[VUID-vkCmdResetQueryPool-firstQuery-02862]] 448 If pname:queryPool was created with 449 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command must: not be 450 recorded in a command buffer that, either directly or through secondary 451 command buffers, also contains begin commands for a query from the set 452 of queries [eq]#[pname:firstQuery, pname:firstQuery {plus} 453 pname:queryCount - 1]# 454endif::VK_KHR_performance_query[] 455**** 456 457include::{generated}/validity/protos/vkCmdResetQueryPool.adoc[] 458-- 459 460ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 461[open,refpage='vkResetQueryPool',desc='Reset queries in a query pool',type='protos',alias='vkResetQueryPoolEXT'] 462-- 463To reset a range of queries in a query pool on the host, call: 464 465ifdef::VK_VERSION_1_2[] 466include::{generated}/api/protos/vkResetQueryPool.adoc[] 467endif::VK_VERSION_1_2[] 468 469ifdef::VK_VERSION_1_2+VK_EXT_host_query_reset[or the equivalent command] 470 471ifdef::VK_EXT_host_query_reset[] 472include::{generated}/api/protos/vkResetQueryPoolEXT.adoc[] 473endif::VK_EXT_host_query_reset[] 474 475 * pname:device is the logical device that owns the query pool. 476 * pname:queryPool is the handle of the query pool managing the queries 477 being reset. 478 * pname:firstQuery is the initial query index to reset. 479 * pname:queryCount is the number of queries to reset. 480 481This command sets the status of query indices [eq]#[pname:firstQuery, 482pname:firstQuery {plus} pname:queryCount - 1]# to unavailable. 483 484ifdef::VK_KHR_performance_query[] 485If pname:queryPool is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR this command 486sets the status of query indices [eq]#[pname:firstQuery, pname:firstQuery 487{plus} pname:queryCount - 1]# to unavailable for each pass. 488endif::VK_KHR_performance_query[] 489 490.Valid Usage 491**** 492 * [[VUID-vkResetQueryPool-None-02665]] 493 The <<features-hostQueryReset, pname:hostQueryReset>> feature must: be 494 enabled 495 * [[VUID-vkResetQueryPool-firstQuery-02666]] 496 pname:firstQuery must: be less than the number of queries in 497 pname:queryPool 498 * [[VUID-vkResetQueryPool-firstQuery-02667]] 499 The sum of pname:firstQuery and pname:queryCount must: be less than or 500 equal to the number of queries in pname:queryPool 501 * [[VUID-vkResetQueryPool-firstQuery-02741]] 502 Submitted commands that refer to the range specified by pname:firstQuery 503 and pname:queryCount in pname:queryPool must: have completed execution 504 * [[VUID-vkResetQueryPool-firstQuery-02742]] 505 The range of queries specified by pname:firstQuery and pname:queryCount 506 in pname:queryPool must: not be in use by calls to 507 flink:vkGetQueryPoolResults or fname:vkResetQueryPool in other threads 508**** 509 510include::{generated}/validity/protos/vkResetQueryPool.adoc[] 511-- 512endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 513 514Once queries are reset and ready for use, query commands can: be issued to a 515command buffer. 516Occlusion queries and pipeline statistics queries count events - drawn 517samples and pipeline stage invocations, respectively - resulting from 518commands that are recorded between a flink:vkCmdBeginQuery command and a 519flink:vkCmdEndQuery command within a specified command buffer, effectively 520scoping a set of drawing and/or dispatching commands. 521Timestamp queries write timestamps to a query pool. 522ifdef::VK_KHR_performance_query[] 523Performance queries record performance counters to a query pool. 524endif::VK_KHR_performance_query[] 525 526A query must: begin and end in the same command buffer, although if it is a 527primary command buffer, and the <<features-inheritedQueries, 528pname:inheritedQueries>> feature is enabled, it can: execute secondary 529command buffers during the query operation. 530For a secondary command buffer to be executed while a query is active, it 531must: set the pname:occlusionQueryEnable, pname:queryFlags, and/or 532pname:pipelineStatistics members of slink:VkCommandBufferInheritanceInfo to 533conservative values, as described in the <<commandbuffers-recording, Command 534Buffer Recording>> section. 535A query must: either begin and end inside the same subpass of a render pass 536instance, or must: both begin and end outside of a render pass instance 537(i.e. contain entire render pass instances). 538 539ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 540 541If queries are used while executing a render pass instance that has 542multiview enabled, the query uses [eq]#N# consecutive query indices in the 543query pool (starting at pname:query) where [eq]#N# is the number of bits set 544in the view mask in the subpass the query is used in. 545How the numerical results of the query are distributed among the queries is 546implementation-dependent. 547For example, some implementations may: write each view's results to a 548distinct query, while other implementations may: write the total result to 549the first query and write zero to the other queries. 550However, the sum of the results in all the queries must: accurately reflect 551the total result of the query summed over all views. 552Applications can: sum the results from all the queries to compute the total 553result. 554 555Queries used with multiview rendering must: not span subpasses, i.e. they 556must: begin and end in the same subpass. 557 558endif::VK_VERSION_1_1,VK_KHR_multiview[] 559 560ifdef::VK_KHR_video_queue[] 561A query must: either begin and end inside the same video coding scope, or 562must: both begin and end outside of a video coding scope and must: not 563contain entire video coding scopes. 564endif::VK_KHR_video_queue[] 565 566[open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos',xrefs='vkCmdEndQuery vkCmdBeginQueryIndexedEXT vkCmdEndQueryIndexedEXT'] 567-- 568:refpage: vkCmdBeginQuery 569 570To begin a query, call: 571 572include::{generated}/api/protos/vkCmdBeginQuery.adoc[] 573 574 * pname:commandBuffer is the command buffer into which this command will 575 be recorded. 576 * pname:queryPool is the query pool that will manage the results of the 577 query. 578 * pname:query is the query index within the query pool that will contain 579 the results. 580 * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying 581 constraints on the types of queries that can: be performed. 582 583If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and 584pname:flags contains ename:VK_QUERY_CONTROL_PRECISE_BIT, an implementation 585must: return a result that matches the actual number of samples passed. 586This is described in more detail in <<queries-occlusion,Occlusion Queries>>. 587 588ifdef::VK_EXT_transform_feedback[] 589Calling fname:vkCmdBeginQuery is equivalent to calling 590flink:vkCmdBeginQueryIndexedEXT with the pname:index parameter set to zero. 591endif::VK_EXT_transform_feedback[] 592 593[[queries-operation-active]] 594After beginning a query, that query is considered _active_ within the 595command buffer it was called in until that same query is ended. 596Queries active in a primary command buffer when secondary command buffers 597are executed are considered active for those secondary command buffers. 598 599ifdef::VK_KHR_video_queue[] 600Furthermore, if the query is started within a video coding scope, the 601following command buffer states are initialized for the query type: 602 603 * [[queries-operation-active-query-index]] The _active_query_index_ is set 604 to the value specified by pname:query. 605 * [[queries-operation-last-activatable-query-index]] The _last activatable 606 query index_ is also set to the value specified by pname:query. 607 608Each <<video-coding,video coding operation>> stores a result to the query 609corresponding to the current active query index, followed by incrementing 610the active query index. 611If the active query index gets incremented past the last activatable query 612index, issuing any further video coding operations results in undefined: 613behavior. 614 615[NOTE] 616.Note 617==== 618In practice, this means that currently no more than a single video coding 619operation must: be issued between a begin and end query pair. 620==== 621 622endif::VK_KHR_video_queue[] 623 624This command defines an execution dependency between other query commands 625that reference the same query. 626 627The first <<synchronization-dependencies-scopes, synchronization scope>> 628includes all commands which reference the queries in pname:queryPool 629indicated by pname:query that occur earlier in 630<<synchronization-submission-order,submission order>>. 631 632The second <<synchronization-dependencies-scopes, synchronization scope>> 633includes all commands which reference the queries in pname:queryPool 634indicated by pname:query that occur later in 635<<synchronization-submission-order,submission order>>. 636 637The operation of this command happens after the first scope and happens 638before the second scope. 639 640.Valid Usage 641**** 642include::{chapters}/commonvalidity/query_begin_common.adoc[] 643 * [[VUID-vkCmdBeginQuery-queryPool-01922]] 644 pname:queryPool must: have been created with a pname:queryType that 645 differs from that of any queries that are 646 <<queries-operation-active,active>> within pname:commandBuffer 647ifdef::VK_EXT_mesh_shader[] 648 * [[VUID-vkCmdBeginQuery-queryType-07070]] 649 If the pname:queryType used to create pname:queryPool was 650 ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT the 651 sname:VkCommandPool that pname:commandBuffer was allocated from must: 652 support graphics operations 653endif::VK_EXT_mesh_shader[] 654ifdef::VK_EXT_transform_feedback[] 655 * [[VUID-vkCmdBeginQuery-queryType-02327]] 656 If the pname:queryType used to create pname:queryPool was 657 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the 658 sname:VkCommandPool that pname:commandBuffer was allocated from must: 659 support graphics operations 660 * [[VUID-vkCmdBeginQuery-queryType-02328]] 661 If the pname:queryType used to create pname:queryPool was 662 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then 663 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries 664 must: be supported 665endif::VK_EXT_transform_feedback[] 666ifdef::VK_EXT_primitives_generated_query[] 667 * [[VUID-vkCmdBeginQuery-queryType-06687]] 668 If the pname:queryType used to create pname:queryPool was 669 ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the sname:VkCommandPool 670 that pname:commandBuffer was allocated from must: support graphics 671 operations 672 * [[VUID-vkCmdBeginQuery-queryType-06688]] 673 If the pname:queryType used to create pname:queryPool was 674 ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT then 675 <<features-primitivesGeneratedQuery, pname:primitivesGeneratedQuery>> 676 must: be enabled 677endif::VK_EXT_primitives_generated_query[] 678include::{chapters}/commonvalidity/performance_query_begin_common.adoc[] 679**** 680 681include::{generated}/validity/protos/vkCmdBeginQuery.adoc[] 682-- 683 684ifdef::VK_EXT_transform_feedback[] 685[open,refpage='vkCmdBeginQueryIndexedEXT',desc='Begin an indexed query',type='protos',xrefs='vkCmdBeginQuery vkCmdEndQuery vkCmdEndQueryIndexedEXT'] 686-- 687:refpage: vkCmdBeginQueryIndexedEXT 688 689To begin an indexed query, call: 690 691include::{generated}/api/protos/vkCmdBeginQueryIndexedEXT.adoc[] 692 693 * pname:commandBuffer is the command buffer into which this command will 694 be recorded. 695 * pname:queryPool is the query pool that will manage the results of the 696 query. 697 * pname:query is the query index within the query pool that will contain 698 the results. 699 * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying 700 constraints on the types of queries that can: be performed. 701 * pname:index is the query type specific index. 702 When the query type is ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 703ifdef::VK_EXT_primitives_generated_query[] 704 or ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, 705endif::VK_EXT_primitives_generated_query[] 706 the index represents the vertex stream. 707 708The fname:vkCmdBeginQueryIndexedEXT command operates the same as the 709flink:vkCmdBeginQuery command, except that it also accepts a query type 710specific pname:index parameter. 711 712This command defines an execution dependency between other query commands 713that reference the same query index. 714 715The first <<synchronization-dependencies-scopes, synchronization scope>> 716includes all commands which reference the queries in pname:queryPool 717indicated by pname:query and pname:index that occur earlier in 718<<synchronization-submission-order,submission order>>. 719 720The second <<synchronization-dependencies-scopes, synchronization scope>> 721includes all commands which reference the queries in pname:queryPool 722indicated by pname:query and pname:index that occur later in 723<<synchronization-submission-order,submission order>>. 724 725The operation of this command happens after the first scope and happens 726before the second scope. 727 728.Valid Usage 729**** 730include::{chapters}/commonvalidity/query_begin_common.adoc[] 731 * [[VUID-vkCmdBeginQueryIndexedEXT-queryPool-04753]] 732 If the pname:queryPool was created with the same pname:queryType as that 733 of another <<queries-operation-active,active>> query within 734 pname:commandBuffer, then pname:index must: not match the index used for 735 the active query 736 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02338]] 737 If the pname:queryType used to create pname:queryPool was 738 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the 739 sname:VkCommandPool that pname:commandBuffer was allocated from must: 740 support graphics operations 741 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02339]] 742 If the pname:queryType used to create pname:queryPool was 743 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index 744 parameter must: be less than 745 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 746 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06692]] 747 If the pname:queryType used to create pname:queryPool was not 748 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 749ifdef::VK_EXT_primitives_generated_query[] 750 and not ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, 751endif::VK_EXT_primitives_generated_query[] 752 the pname:index must: be zero 753ifdef::VK_EXT_primitives_generated_query[] 754 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06689]] 755 If the pname:queryType used to create pname:queryPool was 756 ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the sname:VkCommandPool 757 that pname:commandBuffer was allocated from must: support graphics 758 operations 759 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06690]] 760 If the pname:queryType used to create pname:queryPool was 761 ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the pname:index parameter 762 must: be less than 763 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 764 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06691]] 765 If the pname:queryType used to create pname:queryPool was 766 ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT and the 767 <<features-primitivesGeneratedQueryWithNonZeroStreams, 768 pname:primitivesGeneratedQueryWithNonZeroStreams>> feature is not 769 enabled, the pname:index parameter must: be zero 770 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-06693]] 771 If the pname:queryType used to create pname:queryPool was 772 ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT then 773 <<features-primitivesGeneratedQuery, pname:primitivesGeneratedQuery>> 774 must: be enabled 775endif::VK_EXT_primitives_generated_query[] 776 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02341]] 777 If the pname:queryType used to create pname:queryPool was 778 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then 779 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries 780 must: be supported 781ifdef::VK_EXT_mesh_shader[] 782 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-07071]] 783 The pname:queryType used to create pname:queryPool must: not be 784 ename:VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT 785endif::VK_EXT_mesh_shader[] 786include::{chapters}/commonvalidity/performance_query_begin_common.adoc[] 787**** 788 789include::{generated}/validity/protos/vkCmdBeginQueryIndexedEXT.adoc[] 790-- 791endif::VK_EXT_transform_feedback[] 792 793[open,refpage='VkQueryControlFlagBits',desc='Bitmask specifying constraints on a query',type='enums'] 794-- 795Bits which can: be set in flink:vkCmdBeginQuery::pname:flags, specifying 796constraints on the types of queries that can: be performed, are: 797 798include::{generated}/api/enums/VkQueryControlFlagBits.adoc[] 799 800 * ename:VK_QUERY_CONTROL_PRECISE_BIT specifies the precision of 801 <<queries-occlusion, occlusion queries>>. 802-- 803 804[open,refpage='VkQueryControlFlags',desc='Bitmask of VkQueryControlFlagBits',type='flags'] 805-- 806include::{generated}/api/flags/VkQueryControlFlags.adoc[] 807 808tname:VkQueryControlFlags is a bitmask type for setting a mask of zero or 809more elink:VkQueryControlFlagBits. 810-- 811 812[open,refpage='vkCmdEndQuery',desc='Ends a query',type='protos',xrefs='vkCmdBeginQuery vkCmdBeginQueryIndexedEXT vkCmdEndQueryIndexedEXT'] 813-- 814:refpage: vkCmdEndQuery 815 816To end a query after the set of desired drawing or dispatching commands is 817executed, call: 818 819include::{generated}/api/protos/vkCmdEndQuery.adoc[] 820 821 * pname:commandBuffer is the command buffer into which this command will 822 be recorded. 823 * pname:queryPool is the query pool that is managing the results of the 824 query. 825 * pname:query is the query index within the query pool where the result is 826 stored. 827 828The command completes the query in pname:queryPool identified by 829pname:query, and marks it as available. 830 831This command defines an execution dependency between other query commands 832that reference the same query. 833 834The first <<synchronization-dependencies-scopes, synchronization scope>> 835includes all commands which reference the queries in pname:queryPool 836indicated by pname:query that occur earlier in 837<<synchronization-submission-order,submission order>>. 838 839The second <<synchronization-dependencies-scopes, synchronization scope>> 840includes only the operation of this command. 841 842ifdef::VK_EXT_transform_feedback[] 843Calling fname:vkCmdEndQuery is equivalent to calling 844flink:vkCmdEndQueryIndexedEXT with the pname:index parameter set to zero. 845endif::VK_EXT_transform_feedback[] 846 847 848.Valid Usage 849**** 850 * [[VUID-vkCmdEndQuery-None-01923]] 851 All queries used by the command must: be 852 <<queries-operation-active,active>> 853 * [[VUID-vkCmdEndQuery-query-00810]] 854 pname:query must: be less than the number of queries in pname:queryPool 855ifdef::VK_VERSION_1_1[] 856 * [[VUID-vkCmdEndQuery-commandBuffer-01886]] 857 pname:commandBuffer must: not be a protected command buffer 858endif::VK_VERSION_1_1[] 859ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 860 * [[VUID-vkCmdEndQuery-query-00812]] 861 If fname:vkCmdEndQuery is called within a render pass instance, the sum 862 of pname:query and the number of bits set in the current subpass's view 863 mask must: be less than or equal to the number of queries in 864 pname:queryPool 865endif::VK_VERSION_1_1,VK_KHR_multiview[] 866ifdef::VK_KHR_performance_query[] 867 * [[VUID-vkCmdEndQuery-queryPool-03227]] 868 If pname:queryPool was created with a pname:queryType of 869 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the 870 counters used to create pname:queryPool was 871 ename:VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the 872 flink:vkCmdEndQuery must: be the last recorded command in 873 pname:commandBuffer 874 * [[VUID-vkCmdEndQuery-queryPool-03228]] 875 If pname:queryPool was created with a pname:queryType of 876 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the 877 counters used to create pname:queryPool was 878 ename:VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the 879 flink:vkCmdEndQuery must: not be recorded within a render pass instance 880endif::VK_KHR_performance_query[] 881include::{chapters}/commonvalidity/query_end_common.adoc[] 882**** 883 884include::{generated}/validity/protos/vkCmdEndQuery.adoc[] 885-- 886 887ifdef::VK_EXT_transform_feedback[] 888[open,refpage='vkCmdEndQueryIndexedEXT',desc='Ends a query',type='protos',xrefs='vkCmdBeginQuery vkCmdEndQuery vkCmdBeginQueryIndexedEXT'] 889-- 890:refpage: vkCmdEndQueryIndexedEXT 891 892To end an indexed query after the set of desired drawing or dispatching 893commands is recorded, call: 894 895include::{generated}/api/protos/vkCmdEndQueryIndexedEXT.adoc[] 896 897 * pname:commandBuffer is the command buffer into which this command will 898 be recorded. 899 * pname:queryPool is the query pool that is managing the results of the 900 query. 901 * pname:query is the query index within the query pool where the result is 902 stored. 903 * pname:index is the query type specific index. 904 905The command completes the query in pname:queryPool identified by pname:query 906and pname:index, and marks it as available. 907 908The fname:vkCmdEndQueryIndexedEXT command operates the same as the 909flink:vkCmdEndQuery command, except that it also accepts a query type 910specific pname:index parameter. 911 912This command defines an execution dependency between other query commands 913that reference the same query index. 914 915The first <<synchronization-dependencies-scopes, synchronization scope>> 916includes all commands which reference the queries in pname:queryPool 917indicated by pname:query that occur earlier in 918<<synchronization-submission-order,submission order>>. 919 920The second <<synchronization-dependencies-scopes, synchronization scope>> 921includes only the operation of this command. 922 923.Valid Usage 924**** 925 * [[VUID-vkCmdEndQueryIndexedEXT-None-02342]] 926 All queries used by the command must: be 927 <<queries-operation-active,active>> 928 * [[VUID-vkCmdEndQueryIndexedEXT-query-02343]] 929 pname:query must: be less than the number of queries in pname:queryPool 930ifdef::VK_VERSION_1_1[] 931 * [[VUID-vkCmdEndQueryIndexedEXT-commandBuffer-02344]] 932 pname:commandBuffer must: not be a protected command buffer 933endif::VK_VERSION_1_1[] 934ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 935 * [[VUID-vkCmdEndQueryIndexedEXT-query-02345]] 936 If fname:vkCmdEndQueryIndexedEXT is called within a render pass 937 instance, the sum of pname:query and the number of bits set in the 938 current subpass's view mask must: be less than or equal to the number of 939 queries in pname:queryPool 940endif::VK_VERSION_1_1,VK_KHR_multiview[] 941 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-06694]] 942 If the pname:queryType used to create pname:queryPool was 943 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 944ifdef::VK_EXT_primitives_generated_query[] 945 or ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, 946endif::VK_EXT_primitives_generated_query[] 947 the pname:index parameter must: be less than 948 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 949 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-06695]] 950 If the pname:queryType used to create pname:queryPool was not 951 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 952ifdef::VK_EXT_primitives_generated_query[] 953 and not ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, 954endif::VK_EXT_primitives_generated_query[] 955 the pname:index must: be zero 956 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-06696]] 957 If the pname:queryType used to create pname:queryPool was 958 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 959ifdef::VK_EXT_primitives_generated_query[] 960 or ename:VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, 961endif::VK_EXT_primitives_generated_query[] 962 pname:index must: equal the pname:index used to begin the query 963include::{chapters}/commonvalidity/query_end_common.adoc[] 964**** 965 966include::{generated}/validity/protos/vkCmdEndQueryIndexedEXT.adoc[] 967-- 968endif::VK_EXT_transform_feedback[] 969 970[[queries-operation-memorylayout]] 971An application can: retrieve results either by requesting they be written 972into application-provided memory, or by requesting they be copied into a 973sname:VkBuffer. 974In either case, the layout in memory is defined as follows: 975 976 * The first query's result is written starting at the first byte requested 977 by the command, and each subsequent query's result begins pname:stride 978 bytes later. 979 * Occlusion queries, pipeline statistics queries, 980ifdef::VK_EXT_transform_feedback[] 981 transform feedback queries, 982endif::VK_EXT_transform_feedback[] 983ifdef::VK_EXT_primitives_generated_query[] 984 primitives generated queries, 985endif::VK_EXT_primitives_generated_query[] 986ifdef::VK_EXT_mesh_shader[] 987 mesh shader queries, 988endif::VK_EXT_mesh_shader[] 989ifdef::VK_KHR_video_encode_queue[] 990 video encode feedback queries, 991endif::VK_KHR_video_encode_queue[] 992 and timestamp queries store results in a tightly packed array of 993 unsigned integers, either 32- or 64-bits as requested by the command, 994 storing the numerical results and, if requested, the availability 995 status. 996ifdef::VK_KHR_performance_query[] 997 * Performance queries store results in a tightly packed array whose type 998 is determined by the pname:unit member of the corresponding 999 slink:VkPerformanceCounterKHR. 1000endif::VK_KHR_performance_query[] 1001 * If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, the final 1002 element of each query's result is an integer indicating whether the 1003 query's result is available, with any non-zero value indicating that it 1004 is available. 1005ifdef::VK_KHR_video_queue[] 1006 * If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is used, the final element 1007 of each query's result is an integer value indicating that status of the 1008 query result. 1009 Positive values indicate success, negative values indicate failure, and 1010 0 indicates that the result is not yet available. 1011 Specific error codes are encoded in the elink:VkQueryResultStatusKHR 1012 enumeration. 1013endif::VK_KHR_video_queue[] 1014 * Occlusion queries write one integer value - the number of samples 1015 passed. 1016 Pipeline statistics queries write one integer value for each bit that is 1017 enabled in the pname:pipelineStatistics when the pool is created, and 1018 the statistics values are written in bit order starting from the least 1019 significant bit. 1020 Timestamp queries write one integer value. 1021ifdef::VK_KHR_performance_query[] 1022 Performance queries write one slink:VkPerformanceCounterResultKHR value 1023 for each slink:VkPerformanceCounterKHR in the query. 1024endif::VK_KHR_performance_query[] 1025ifdef::VK_EXT_transform_feedback[] 1026 Transform feedback queries write two integers; the first integer is the 1027 number of primitives successfully written to the corresponding transform 1028 feedback buffer and the second is the number of primitives output to the 1029 vertex stream, regardless of whether they were successfully captured or 1030 not. 1031 In other words, if the transform feedback buffer was sized too small for 1032 the number of primitives output by the vertex stream, the first integer 1033 represents the number of primitives actually written and the second is 1034 the number that would have been written if all the transform feedback 1035 buffers associated with that vertex stream were large enough. 1036endif::VK_EXT_transform_feedback[] 1037ifdef::VK_EXT_primitives_generated_query[] 1038 Primitives generated queries write the number of primitives output to 1039 the vertex stream, regardless of whether transform feedback is active or 1040 not, or whether they were successfully captured by transform feedback or 1041 not. 1042 This is identical to the second integer of the transform feedback 1043 queries if transform feedback is active. 1044endif::VK_EXT_primitives_generated_query[] 1045ifdef::VK_EXT_mesh_shader[] 1046 Mesh shader queries write a single integer. 1047endif::VK_EXT_mesh_shader[] 1048ifdef::VK_KHR_video_encode_queue[] 1049 Video encode feedback queries write one or more integer values for each 1050 bit that is enabled in 1051 slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::pname:encodeFeedbackFlags 1052 when the pool is created, and the feedback values are written in bit 1053 order starting from the least significant bit, as described 1054 <<queries-video-encode-feedback,here>>. 1055endif::VK_KHR_video_encode_queue[] 1056 * If more than one query is retrieved and pname:stride is not at least as 1057 large as the size of the array of values corresponding to a single 1058 query, the values written to memory are undefined:. 1059 1060[open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos'] 1061-- 1062:refpage: vkGetQueryPoolResults 1063 1064To retrieve status and results for a set of queries, call: 1065 1066include::{generated}/api/protos/vkGetQueryPoolResults.adoc[] 1067 1068 * pname:device is the logical device that owns the query pool. 1069 * pname:queryPool is the query pool managing the queries containing the 1070 desired results. 1071 * pname:firstQuery is the initial query index. 1072 * pname:queryCount is the number of queries to read. 1073 * pname:dataSize is the size in bytes of the buffer pointed to by 1074 pname:pData. 1075 * pname:pData is a pointer to a user-allocated buffer where the results 1076 will be written 1077 * pname:stride is the stride in bytes between results for individual 1078 queries within pname:pData. 1079 * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how 1080 and when results are returned. 1081 1082Any results written for a query are written according to 1083<<queries-operation-memorylayout,a layout dependent on the query type>>. 1084 1085If no bits are set in pname:flags, and all requested queries are in the 1086available state, results are written as an array of 32-bit unsigned integer 1087values. 1088Behavior when not all queries are available is described 1089<<queries-wait-bit-not-set, below>>. 1090 1091If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all 1092queries in pname:queryPool identified by pname:firstQuery and 1093pname:queryCount are copied to pname:pData, along with an extra availability 1094ifdef::VK_KHR_video_queue[or status] 1095value written directly after the results of each query and interpreted as an 1096unsigned integer. 1097A value of zero indicates that the results are not yet available, otherwise 1098the query is complete and results are available. 1099The size of the availability 1100ifdef::VK_KHR_video_queue[or status] 1101values is 64 bits if ename:VK_QUERY_RESULT_64_BIT is set in pname:flags. 1102Otherwise, it is 32 bits. 1103 1104ifdef::VK_KHR_video_queue[] 1105If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries 1106in pname:queryPool identified by pname:firstQuery and pname:queryCount are 1107copied to pname:pData, along with an extra status value written directly 1108after the results of each query and interpreted as a signed integer. 1109A value of zero indicates that the results are not yet available. 1110Positive values indicate that the operations within the query completed 1111successfully, and the query results are valid. 1112Negative values indicate that the operations within the query completed 1113unsuccessfully. 1114 1115elink:VkQueryResultStatusKHR defines specific meaning for values returned 1116here, though implementations are free to return other values. 1117endif::VK_KHR_video_queue[] 1118 1119[NOTE] 1120.Note 1121==== 1122If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT 1123ifdef::VK_KHR_video_queue[or ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR] 1124is set, the layout of data in the buffer is a __(result,availability)__ 1125ifdef::VK_KHR_video_queue[or __(result,status)__] 1126pair for each query returned, and pname:stride is the stride between each 1127pair. 1128==== 1129 1130Results for any available query written by this command are final and 1131represent the final result of the query. 1132If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, then for any query that is 1133unavailable, an intermediate result between zero and the final result value 1134is written for that query. 1135Otherwise, any result written by this command is undefined:. 1136 1137If ename:VK_QUERY_RESULT_64_BIT is set, results and, if returned, 1138availability 1139ifdef::VK_KHR_video_queue[or status] 1140values for all queries are written as an array of 64-bit values. 1141ifdef::VK_KHR_performance_query[] 1142If the pname:queryPool was created with 1143ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are 1144written as an array of the type indicated by 1145slink:VkPerformanceCounterKHR::pname:storage for the counter being queried. 1146endif::VK_KHR_performance_query[] 1147Otherwise, results and availability 1148ifdef::VK_KHR_video_queue[or status] 1149values are written as an array of 32-bit values. 1150If an unsigned integer query's value overflows the result type, the value 1151may: either wrap or saturate. 1152ifdef::VK_KHR_performance_query[] 1153If a signed integer query's value overflows the result type, the value is 1154undefined:. 1155If a floating point query's value is not representable as the result type, 1156the value is undefined:. 1157endif::VK_KHR_performance_query[] 1158 1159If ename:VK_QUERY_RESULT_WAIT_BIT is set, this command defines an execution 1160dependency with any earlier commands that writes one of the identified 1161queries. 1162The first <<synchronization-dependencies-scopes, synchronization scope>> 1163includes all instances of flink:vkCmdEndQuery, 1164ifdef::VK_EXT_transform_feedback[] 1165flink:vkCmdEndQueryIndexedEXT, 1166endif::VK_EXT_transform_feedback[] 1167ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1168flink:vkCmdWriteTimestamp2, 1169endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1170and flink:vkCmdWriteTimestamp that reference any query in pname:queryPool 1171indicated by pname:firstQuery and pname:queryCount. 1172The second <<synchronization-dependencies-scopes, synchronization scope>> 1173includes the host operations of this command. 1174 1175[[queries-wait-bit-not-set]] 1176If ename:VK_QUERY_RESULT_WAIT_BIT is not set, fname:vkGetQueryPoolResults 1177may: return ename:VK_NOT_READY if there are queries in the unavailable 1178state. 1179 1180[NOTE] 1181.Note 1182==== 1183Applications must: take care to ensure that use of the 1184ename:VK_QUERY_RESULT_WAIT_BIT bit has the desired effect. 1185 1186For example, if a query has been used previously and a command buffer 1187records the commands fname:vkCmdResetQueryPool, fname:vkCmdBeginQuery, and 1188fname:vkCmdEndQuery for that query, then the query will remain in the 1189available state until 1190ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 1191fname:vkResetQueryPool is called or 1192endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 1193the fname:vkCmdResetQueryPool command executes on a queue. 1194Applications can: use fences or events to ensure that a query has already 1195been reset before checking for its results or availability status. 1196Otherwise, a stale value could be returned from a previous use of the query. 1197 1198The above also applies when ename:VK_QUERY_RESULT_WAIT_BIT is used in 1199combination with ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT. 1200In this case, the returned availability status may: reflect the result of a 1201previous use of the query unless 1202ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 1203fname:vkResetQueryPool is called or 1204endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 1205the fname:vkCmdResetQueryPool command has been executed since the last use 1206of the query. 1207 1208ifdef::VK_KHR_video_queue[] 1209A similar situation can arise with the 1210ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag. 1211endif::VK_KHR_video_queue[] 1212==== 1213 1214[NOTE] 1215.Note 1216==== 1217Applications can: double-buffer query pool usage, with a pool per frame, and 1218reset queries at the end of the frame in which they are read. 1219==== 1220 1221include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1222 1223.Valid Usage 1224**** 1225 * [[VUID-vkGetQueryPoolResults-None-09401]] 1226 All queries used by the command must: not be uninitialized 1227 * [[VUID-vkGetQueryPoolResults-firstQuery-00813]] 1228 pname:firstQuery must: be less than the number of queries in 1229 pname:queryPool 1230 * [[VUID-vkGetQueryPoolResults-flags-02828]] 1231 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags 1232ifdef::VK_KHR_performance_query[] 1233 and the pname:queryType used to create pname:queryPool was not 1234 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, 1235endif::VK_KHR_performance_query[] 1236 then pname:pData and pname:stride must: be multiples of `4` 1237 * [[VUID-vkGetQueryPoolResults-flags-00815]] 1238 If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then pname:pData 1239 and pname:stride must: be multiples of `8` 1240 * [[VUID-vkGetQueryPoolResults-stride-08993]] 1241 If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, pname:stride 1242 must: be large enough to contain the unsigned integer representing 1243 availability 1244ifdef::VK_KHR_video_queue[or status] 1245 in addition to the query result. 1246ifdef::VK_KHR_performance_query[] 1247 * [[VUID-vkGetQueryPoolResults-queryType-03229]] 1248 If the pname:queryType used to create pname:queryPool was 1249 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:pData and 1250 pname:stride must: be multiples of the size of 1251 slink:VkPerformanceCounterResultKHR 1252 * [[VUID-vkGetQueryPoolResults-queryType-04519]] 1253 If the pname:queryType used to create pname:queryPool was 1254 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:stride must: be 1255 large enough to contain the 1256 slink:VkQueryPoolPerformanceCreateInfoKHR::pname:counterIndexCount used 1257 to create pname:queryPool times the size of 1258 slink:VkPerformanceCounterResultKHR 1259endif::VK_KHR_performance_query[] 1260 * [[VUID-vkGetQueryPoolResults-firstQuery-00816]] 1261 The sum of pname:firstQuery and pname:queryCount must: be less than or 1262 equal to the number of queries in pname:queryPool 1263 * [[VUID-vkGetQueryPoolResults-dataSize-00817]] 1264 pname:dataSize must: be large enough to contain the result of each 1265 query, as described <<queries-operation-memorylayout,here>> 1266 * [[VUID-vkGetQueryPoolResults-queryType-00818]] 1267 If the pname:queryType used to create pname:queryPool was 1268 ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain 1269 ename:VK_QUERY_RESULT_PARTIAL_BIT 1270ifdef::VK_KHR_performance_query[] 1271 * [[VUID-vkGetQueryPoolResults-queryType-03230]] 1272 If the pname:queryType used to create pname:queryPool was 1273 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, pname:flags must: not contain 1274 ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT, 1275ifdef::VK_KHR_video_queue[] 1276 ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, 1277endif::VK_KHR_video_queue[] 1278 ename:VK_QUERY_RESULT_PARTIAL_BIT, or ename:VK_QUERY_RESULT_64_BIT 1279 * [[VUID-vkGetQueryPoolResults-queryType-03231]] 1280 If the pname:queryType used to create pname:queryPool was 1281 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:queryPool must: 1282 have been recorded once for each pass as retrieved via a call to 1283 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 1284endif::VK_KHR_performance_query[] 1285ifdef::VK_KHR_video_queue[] 1286 * [[VUID-vkGetQueryPoolResults-queryType-04810]] 1287 If the pname:queryType used to create pname:queryPool was 1288 ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, then pname:flags must: 1289 include ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR 1290 * [[VUID-vkGetQueryPoolResults-flags-04811]] 1291 If pname:flags includes ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, then 1292 it must: not include ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT 1293endif::VK_KHR_video_queue[] 1294**** 1295 1296include::{generated}/validity/protos/vkGetQueryPoolResults.adoc[] 1297-- 1298 1299[open,refpage='VkQueryResultFlagBits',desc='Bitmask specifying how and when query results are returned',type='enums'] 1300-- 1301Bits which can: be set in flink:vkGetQueryPoolResults::pname:flags and 1302flink:vkCmdCopyQueryPoolResults::pname:flags, specifying how and when 1303results are returned, are: 1304 1305include::{generated}/api/enums/VkQueryResultFlagBits.adoc[] 1306 1307 * ename:VK_QUERY_RESULT_64_BIT specifies the results will be written as an 1308 array of 64-bit unsigned integer values. 1309 If this bit is not set, the results will be written as an array of 1310 32-bit unsigned integer values. 1311 * ename:VK_QUERY_RESULT_WAIT_BIT specifies that Vulkan will wait for each 1312 query's status to become available before retrieving its results. 1313 * ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT specifies that the 1314 availability status accompanies the results. 1315 * ename:VK_QUERY_RESULT_PARTIAL_BIT specifies that returning partial 1316 results is acceptable. 1317ifdef::VK_KHR_video_queue[] 1318 * ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR specifies that the last value 1319 returned in the query is a elink:VkQueryResultStatusKHR value. 1320 See <<queries-result-status-only, result status query>> for information 1321 on how an application can determine whether the use of this flag bit is 1322 supported. 1323endif::VK_KHR_video_queue[] 1324-- 1325 1326[open,refpage='VkQueryResultFlags',desc='Bitmask of VkQueryResultFlagBits',type='flags'] 1327-- 1328include::{generated}/api/flags/VkQueryResultFlags.adoc[] 1329 1330tname:VkQueryResultFlags is a bitmask type for setting a mask of zero or 1331more elink:VkQueryResultFlagBits. 1332-- 1333 1334ifdef::VK_KHR_video_queue[] 1335[open,refpage='VkQueryResultStatusKHR',desc='Specific status codes for operations',type='enums'] 1336-- 1337[[query-result-status-codes]] 1338Specific status codes that can: be returned from a query are: 1339 1340include::{generated}/api/enums/VkQueryResultStatusKHR.adoc[] 1341 1342 * ename:VK_QUERY_RESULT_STATUS_NOT_READY_KHR specifies that the query 1343 result is not yet available. 1344 * ename:VK_QUERY_RESULT_STATUS_ERROR_KHR specifies that operations did not 1345 complete successfully. 1346 * ename:VK_QUERY_RESULT_STATUS_COMPLETE_KHR specifies that operations 1347 completed successfully and the query result is available. 1348ifdef::VK_KHR_video_encode_queue[] 1349 * ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR 1350 indicates that a video encode operation did not complete successfully 1351 due to the destination video bitstream buffer range not being 1352 sufficiently large to fit the encoded bitstream data. 1353endif::VK_KHR_video_encode_queue[] 1354-- 1355endif::VK_KHR_video_queue[] 1356 1357[open,refpage='vkCmdCopyQueryPoolResults',desc='Copy the results of queries in a query pool to a buffer object',type='protos'] 1358-- 1359To copy query statuses and numerical results directly to buffer memory, 1360call: 1361 1362include::{generated}/api/protos/vkCmdCopyQueryPoolResults.adoc[] 1363 1364 * pname:commandBuffer is the command buffer into which this command will 1365 be recorded. 1366 * pname:queryPool is the query pool managing the queries containing the 1367 desired results. 1368 * pname:firstQuery is the initial query index. 1369 * pname:queryCount is the number of queries. 1370 pname:firstQuery and pname:queryCount together define a range of 1371 queries. 1372 * pname:dstBuffer is a slink:VkBuffer object that will receive the results 1373 of the copy command. 1374 * pname:dstOffset is an offset into pname:dstBuffer. 1375 * pname:stride is the stride in bytes between results for individual 1376 queries within pname:dstBuffer. 1377 The required size of the backing memory for pname:dstBuffer is 1378 determined as described above for flink:vkGetQueryPoolResults. 1379 * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how 1380 and when results are returned. 1381 1382Any results written for a query are written according to 1383<<queries-operation-memorylayout,a layout dependent on the query type>>. 1384 1385Results for any query in pname:queryPool identified by pname:firstQuery and 1386pname:queryCount that is available are copied to pname:dstBuffer. 1387 1388If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all 1389queries in pname:queryPool identified by pname:firstQuery and 1390pname:queryCount are copied to pname:dstBuffer, along with an extra 1391availability value written directly after the results of each query and 1392interpreted as an unsigned integer. 1393A value of zero indicates that the results are not yet available, otherwise 1394the query is complete and results are available. 1395 1396ifdef::VK_KHR_video_queue[] 1397If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries 1398in pname:queryPool identified by pname:firstQuery and pname:queryCount are 1399copied to pname:dstBuffer, along with an extra status value written directly 1400after the results of each query and interpreted as a signed integer. 1401A value of zero indicates that the results are not yet available. 1402Positive values indicate that the operations within the query completed 1403successfully, and the query results are valid. 1404Negative values indicate that the operations within the query completed 1405unsuccessfully. 1406 1407elink:VkQueryResultStatusKHR defines specific meaning for values returned 1408here, though implementations are free to return other values. 1409endif::VK_KHR_video_queue[] 1410 1411Results for any available query written by this command are final and 1412represent the final result of the query. 1413If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, then for any query that is 1414unavailable, an intermediate result between zero and the final result value 1415is written for that query. 1416Otherwise, any result written by this command is undefined:. 1417 1418If ename:VK_QUERY_RESULT_64_BIT is set, results and availability 1419ifdef::VK_KHR_video_queue[or status] 1420values for all queries are written as an array of 64-bit values. 1421ifdef::VK_KHR_performance_query[] 1422If the pname:queryPool was created with 1423ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are 1424written as an array of the type indicated by 1425slink:VkPerformanceCounterKHR::pname:storage for the counter being queried. 1426endif::VK_KHR_performance_query[] 1427Otherwise, results and availability 1428ifdef::VK_KHR_video_queue[or status] 1429values are written as an array of 32-bit values. 1430If an unsigned integer query's value overflows the result type, the value 1431may: either wrap or saturate. 1432ifdef::VK_KHR_performance_query[] 1433If a signed integer query's value overflows the result type, the value is 1434undefined:. 1435If a floating point query's value is not representable as the result type, 1436the value is undefined:. 1437endif::VK_KHR_performance_query[] 1438 1439This command defines an execution dependency between other query commands 1440that reference the same query. 1441 1442The first <<synchronization-dependencies-scopes, synchronization scope>> 1443includes all commands which reference the queries in pname:queryPool 1444indicated by pname:query that occur earlier in 1445<<synchronization-submission-order,submission order>>. 1446If pname:flags does not include ename:VK_QUERY_RESULT_WAIT_BIT, 1447ifdef::VK_EXT_transform_feedback[] 1448flink:vkCmdEndQueryIndexedEXT, 1449endif::VK_EXT_transform_feedback[] 1450ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1451flink:vkCmdWriteTimestamp2, 1452endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1453flink:vkCmdEndQuery, and flink:vkCmdWriteTimestamp are excluded from this 1454scope. 1455 1456The second <<synchronization-dependencies-scopes, synchronization scope>> 1457includes all commands which reference the queries in pname:queryPool 1458indicated by pname:query that occur later in 1459<<synchronization-submission-order,submission order>>. 1460 1461The operation of this command happens after the first scope and happens 1462before the second scope. 1463 1464fname:vkCmdCopyQueryPoolResults is considered to be a transfer operation, 1465and its writes to buffer memory must: be synchronized using 1466ename:VK_PIPELINE_STAGE_TRANSFER_BIT and ename:VK_ACCESS_TRANSFER_WRITE_BIT 1467before using the results. 1468 1469.Valid Usage 1470**** 1471 * [[VUID-vkCmdCopyQueryPoolResults-None-09402]] 1472 All queries used by the command must: not be uninitialized when the 1473 command is executed 1474 * [[VUID-vkCmdCopyQueryPoolResults-dstOffset-00819]] 1475 pname:dstOffset must: be less than the size of pname:dstBuffer 1476 * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00820]] 1477 pname:firstQuery must: be less than the number of queries in 1478 pname:queryPool 1479 * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00821]] 1480 The sum of pname:firstQuery and pname:queryCount must: be less than or 1481 equal to the number of queries in pname:queryPool 1482 * [[VUID-vkCmdCopyQueryPoolResults-flags-00822]] 1483 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags then 1484 pname:dstOffset and pname:stride must: be multiples of `4` 1485 * [[VUID-vkCmdCopyQueryPoolResults-flags-00823]] 1486 If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then 1487 pname:dstOffset and pname:stride must: be multiples of `8` 1488 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00824]] 1489 pname:dstBuffer must: have enough storage, from pname:dstOffset, to 1490 contain the result of each query, as described 1491 <<queries-operation-memorylayout,here>> 1492 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00825]] 1493 pname:dstBuffer must: have been created with 1494 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 1495 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00826]] 1496 If pname:dstBuffer is non-sparse then it must: be bound completely and 1497 contiguously to a single sname:VkDeviceMemory object 1498 * [[VUID-vkCmdCopyQueryPoolResults-queryType-00827]] 1499 If the pname:queryType used to create pname:queryPool was 1500 ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain 1501 ename:VK_QUERY_RESULT_PARTIAL_BIT 1502ifdef::VK_KHR_performance_query[] 1503 * [[VUID-vkCmdCopyQueryPoolResults-queryType-03232]] 1504 If the pname:queryType used to create pname:queryPool was 1505 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, 1506 slink:VkPhysicalDevicePerformanceQueryPropertiesKHR::pname:allowCommandBufferQueryCopies 1507 must: be ename:VK_TRUE 1508 * [[VUID-vkCmdCopyQueryPoolResults-queryType-03233]] 1509 If the pname:queryType used to create pname:queryPool was 1510 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, pname:flags must: not contain 1511 ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT, 1512ifdef::VK_KHR_video_queue[] 1513 ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, 1514endif::VK_KHR_video_queue[] 1515 ename:VK_QUERY_RESULT_PARTIAL_BIT, or ename:VK_QUERY_RESULT_64_BIT 1516 * [[VUID-vkCmdCopyQueryPoolResults-queryType-03234]] 1517 If the pname:queryType used to create pname:queryPool was 1518 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:queryPool must: 1519 have been submitted once for each pass as retrieved via a call to 1520 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 1521endif::VK_KHR_performance_query[] 1522ifdef::VK_INTEL_performance_query[] 1523 * [[VUID-vkCmdCopyQueryPoolResults-queryType-02734]] 1524 flink:vkCmdCopyQueryPoolResults must: not be called if the 1525 pname:queryType used to create pname:queryPool was 1526 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL 1527endif::VK_INTEL_performance_query[] 1528ifdef::VK_KHR_video_queue[] 1529 * [[VUID-vkCmdCopyQueryPoolResults-queryType-06901]] 1530 If the pname:queryType used to create pname:queryPool was 1531 ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, then pname:flags must: 1532 include ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR 1533 * [[VUID-vkCmdCopyQueryPoolResults-flags-06902]] 1534 If pname:flags includes ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, then 1535 it must: not include ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT 1536endif::VK_KHR_video_queue[] 1537 * [[VUID-vkCmdCopyQueryPoolResults-None-07429]] 1538 All queries used by the command must: not be active 1539 * [[VUID-vkCmdCopyQueryPoolResults-None-08752]] 1540 All queries used by the command must: have been made _available_ by 1541 prior executed commands 1542**** 1543 1544include::{generated}/validity/protos/vkCmdCopyQueryPoolResults.adoc[] 1545-- 1546 1547[[queries-operation-undefined]] 1548Rendering operations such as clears, MSAA resolves, attachment load/store 1549operations, and blits may: count towards the results of queries. 1550This behavior is implementation-dependent and may: vary depending on the 1551path used within an implementation. 1552For example, some implementations have several types of clears, some of 1553which may: include vertices and some not. 1554 1555 1556[[queries-occlusion]] 1557== Occlusion Queries 1558 1559Occlusion queries track the number of samples that pass the per-fragment 1560tests for a set of drawing commands. 1561As such, occlusion queries are only available on queue families supporting 1562graphics operations. 1563The application can: then use these results to inform future rendering 1564decisions. 1565An occlusion query is begun and ended by calling fname:vkCmdBeginQuery and 1566fname:vkCmdEndQuery, respectively. 1567When an occlusion query begins, the count of passing samples always starts 1568at zero. 1569For each drawing command, the count is incremented as described in 1570<<fragops-samplecount,Sample Counting>>. 1571If pname:flags does not contain ename:VK_QUERY_CONTROL_PRECISE_BIT an 1572implementation may: generate any non-zero result value for the query if the 1573count of passing samples is non-zero. 1574 1575[NOTE] 1576.Note 1577==== 1578Not setting ename:VK_QUERY_CONTROL_PRECISE_BIT mode may: be more efficient 1579on some implementations, and should: be used where it is sufficient to know 1580a boolean result on whether any samples passed the per-fragment tests. 1581In this case, some implementations may: only return zero or one, indifferent 1582to the actual number of samples passing the per-fragment tests. 1583 1584Setting ename:VK_QUERY_CONTROL_PRECISE_BIT does not guarantee that different 1585implementations return the same number of samples in an occlusion query. 1586Some implementations may kill fragments in the 1587<<pipelines-graphics-subsets-pre-rasterization, pre-rasterization shader 1588stage>>, and these killed fragments do not contribute to the final result of 1589the query. 1590It is possible that some implementations generate a zero result value for 1591the query, while others generate a non-zero value. 1592==== 1593 1594When an occlusion query finishes, the result for that query is marked as 1595available. 1596The application can: then either copy the result to a buffer (via 1597fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 1598fname:vkGetQueryPoolResults). 1599 1600[NOTE] 1601.Note 1602==== 1603If occluding geometry is not drawn first, samples can: pass the depth test, 1604but still not be visible in a final image. 1605==== 1606 1607 1608[[queries-pipestats]] 1609== Pipeline Statistics Queries 1610 1611Pipeline statistics queries allow the application to sample a specified set 1612of sname:VkPipeline counters. 1613These counters are accumulated by Vulkan for a set of either drawing or 1614dispatching commands while a pipeline statistics query is active. 1615As such, pipeline statistics queries are available on queue families 1616supporting either graphics or compute operations. 1617The availability of pipeline statistics queries is indicated by the 1618pname:pipelineStatisticsQuery member of the sname:VkPhysicalDeviceFeatures 1619object (see fname:vkGetPhysicalDeviceFeatures and fname:vkCreateDevice for 1620detecting and requesting this query type on a sname:VkDevice). 1621 1622A pipeline statistics query is begun and ended by calling 1623fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively. 1624When a pipeline statistics query begins, all statistics counters are set to 1625zero. 1626While the query is active, the pipeline type determines which set of 1627statistics are available, but these must: be configured on the query pool 1628when it is created. 1629If a statistic counter is issued on a command buffer that does not support 1630the corresponding operation, the value of that counter is undefined: after 1631the query has been made available. 1632At least one statistic counter relevant to the operations supported on the 1633recording command buffer must: be enabled. 1634 1635[open,refpage='VkQueryPipelineStatisticFlagBits',desc='Bitmask specifying queried pipeline statistics',type='enums'] 1636-- 1637Bits which can: be set in 1638slink:VkQueryPoolCreateInfo::pname:pipelineStatistics for query pools and in 1639slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics for secondary 1640command buffers, individually enabling pipeline statistics counters, are: 1641 1642include::{generated}/api/enums/VkQueryPipelineStatisticFlagBits.adoc[] 1643 1644 * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT specifies 1645 that queries managed by the pool will count the number of vertices 1646 processed by the <<drawing,input assembly>> stage. 1647 Vertices corresponding to incomplete primitives may: contribute to the 1648 count. 1649 * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT 1650 specifies that queries managed by the pool will count the number of 1651 primitives processed by the <<drawing,input assembly>> stage. 1652 If primitive restart is enabled, restarting the primitive topology has 1653 no effect on the count. 1654 Incomplete primitives may: be counted. 1655 * ename:VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT 1656 specifies that queries managed by the pool will count the number of 1657 vertex shader invocations. 1658 This counter's value is incremented each time a vertex shader is 1659 <<shaders-vertex-execution,invoked>>. 1660 * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT 1661 specifies that queries managed by the pool will count the number of 1662 geometry shader invocations. 1663 This counter's value is incremented each time a geometry shader is 1664 <<shaders-geometry-execution,invoked>>. 1665 In the case of <<geometry-invocations,instanced geometry shaders>>, the 1666 geometry shader invocations count is incremented for each separate 1667 instanced invocation. 1668 * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT 1669 specifies that queries managed by the pool will count the number of 1670 primitives generated by geometry shader invocations. 1671 The counter's value is incremented each time the geometry shader emits a 1672 primitive. 1673 Restarting primitive topology using the SPIR-V instructions 1674 code:OpEndPrimitive or code:OpEndStreamPrimitive has no effect on the 1675 geometry shader output primitives count. 1676 * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT specifies 1677 that queries managed by the pool will count the number of primitives 1678 processed by the <<vertexpostproc-clipping,Primitive Clipping>> stage of 1679 the pipeline. 1680 The counter's value is incremented each time a primitive reaches the 1681 primitive clipping stage. 1682 * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT specifies that 1683 queries managed by the pool will count the number of primitives output 1684 by the <<vertexpostproc-clipping,Primitive Clipping>> stage of the 1685 pipeline. 1686 The counter's value is incremented each time a primitive passes the 1687 primitive clipping stage. 1688 The actual number of primitives output by the primitive clipping stage 1689 for a particular input primitive is implementation-dependent but must: 1690 satisfy the following conditions: 1691 ** If at least one vertex of the input primitive lies inside the clipping 1692 volume, the counter is incremented by one or more. 1693 ** Otherwise, the counter is incremented by zero or more. 1694 * ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT 1695 specifies that queries managed by the pool will count the number of 1696 fragment shader invocations. 1697 The counter's value is incremented each time the fragment shader is 1698 <<fragops-shader,invoked>>. 1699 * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT 1700 specifies that queries managed by the pool will count the number of 1701 patches processed by the tessellation control shader. 1702 The counter's value is incremented once for each patch for which a 1703 tessellation control shader is 1704 <<shaders-tessellation-control-execution,invoked>>. 1705 * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT 1706 specifies that queries managed by the pool will count the number of 1707 invocations of the tessellation evaluation shader. 1708 The counter's value is incremented each time the tessellation evaluation 1709 shader is <<shaders-tessellation-evaluation-execution,invoked>>. 1710 * ename:VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT 1711 specifies that queries managed by the pool will count the number of 1712 compute shader invocations. 1713 The counter's value is incremented every time the compute shader is 1714 invoked. 1715 Implementations may: skip the execution of certain compute shader 1716 invocations or execute additional compute shader invocations for 1717 implementation-dependent reasons as long as the results of rendering 1718 otherwise remain unchanged. 1719ifdef::VK_EXT_mesh_shader[] 1720 * ename:VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT 1721 specifies that queries managed by the pool will count the number of task 1722 shader invocations. 1723 The counter's value is incremented every time the task shader is 1724 invoked. 1725 * ename:VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT 1726 specifies that queries managed by the pool will count the number of mesh 1727 shader invocations. 1728 The counter's value is incremented every time the mesh shader is 1729 invoked. 1730endif::VK_EXT_mesh_shader[] 1731 1732These values are intended to measure relative statistics on one 1733implementation. 1734Various device architectures will count these values differently. 1735Any or all counters may: be affected by the issues described in 1736<<queries-operation-undefined,Query Operation>>. 1737 1738ifdef::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 1739This counting difference is especially true if the pipeline contains mesh or 1740task shaders, which may affect several of the counters in unexpected ways. 1741endif::VK_EXT_mesh_shader,VK_NV_mesh_shader[] 1742 1743[NOTE] 1744.Note 1745==== 1746For example, tile-based rendering devices may: need to replay the scene 1747multiple times, affecting some of the counts. 1748==== 1749 1750If a pipeline has pname:rasterizerDiscardEnable enabled, implementations 1751may: discard primitives after the final 1752<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader 1753stage>>. 1754As a result, if pname:rasterizerDiscardEnable is enabled, the clipping input 1755and output primitives counters may: not be incremented. 1756 1757When a pipeline statistics query finishes, the result for that query is 1758marked as available. 1759The application can: copy the result to a buffer (via 1760fname:vkCmdCopyQueryPoolResults), or request it be put into host memory (via 1761fname:vkGetQueryPoolResults). 1762-- 1763 1764[open,refpage='VkQueryPipelineStatisticFlags',desc='Bitmask of VkQueryPipelineStatisticFlagBits',type='flags'] 1765-- 1766include::{generated}/api/flags/VkQueryPipelineStatisticFlags.adoc[] 1767 1768tname:VkQueryPipelineStatisticFlags is a bitmask type for setting a mask of 1769zero or more elink:VkQueryPipelineStatisticFlagBits. 1770-- 1771 1772 1773[[queries-timestamps]] 1774== Timestamp Queries 1775 1776_Timestamps_ provide applications with a mechanism for timing the execution 1777of commands. 1778A timestamp is an integer value generated by the sname:VkPhysicalDevice. 1779Unlike other queries, timestamps do not operate over a range, and so do not 1780use flink:vkCmdBeginQuery or flink:vkCmdEndQuery. 1781The mechanism is built around a set of commands that allow the application 1782to tell the sname:VkPhysicalDevice to write timestamp values to a 1783<<queries-pools,query pool>> and then either read timestamp values on the 1784host (using flink:vkGetQueryPoolResults) or copy timestamp values to a 1785sname:VkBuffer (using flink:vkCmdCopyQueryPoolResults). 1786The application can: then compute differences between timestamps to 1787determine execution time. 1788 1789The number of valid bits in a timestamp value is determined by the 1790sname:VkQueueFamilyProperties::pname:timestampValidBits property of the 1791queue on which the timestamp is written. 1792Timestamps are supported on any queue which reports a non-zero value for 1793pname:timestampValidBits via flink:vkGetPhysicalDeviceQueueFamilyProperties. 1794If the <<limits-timestampComputeAndGraphics, 1795pname:timestampComputeAndGraphics>> limit is ename:VK_TRUE, timestamps are 1796supported by every queue family that supports either graphics or compute 1797operations (see slink:VkQueueFamilyProperties). 1798 1799The number of nanoseconds it takes for a timestamp value to be incremented 1800by 1 can: be obtained from 1801sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to 1802fname:vkGetPhysicalDeviceProperties. 1803 1804ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1805[open,refpage='vkCmdWriteTimestamp2',desc='Write a device timestamp into a query object',type='protos',alias='vkCmdWriteTimestamp2KHR'] 1806-- 1807:refpage: vkCmdWriteTimestamp2 1808 1809To request a timestamp and write the value to memory, call: 1810 1811ifdef::VK_VERSION_1_3[] 1812include::{generated}/api/protos/vkCmdWriteTimestamp2.adoc[] 1813endif::VK_VERSION_1_3[] 1814 1815ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] 1816 1817ifdef::VK_KHR_synchronization2[] 1818include::{generated}/api/protos/vkCmdWriteTimestamp2KHR.adoc[] 1819endif::VK_KHR_synchronization2[] 1820 1821 * pname:commandBuffer is the command buffer into which the command will be 1822 recorded. 1823 * pname:stage specifies a stage of the pipeline. 1824 * pname:queryPool is the query pool that will manage the timestamp. 1825 * pname:query is the query within the query pool that will contain the 1826 timestamp. 1827 1828When fname:vkCmdWriteTimestamp2 is submitted to a queue, it defines an 1829execution dependency on commands that were submitted before it, and writes a 1830timestamp to a query pool. 1831 1832The first <<synchronization-dependencies-scopes, synchronization scope>> 1833includes all commands that occur earlier in 1834<<synchronization-submission-order,submission order>>. 1835The synchronization scope is limited to operations on the pipeline stage 1836specified by pname:stage. 1837 1838The second <<synchronization-dependencies-scopes, synchronization scope>> 1839includes only the timestamp write operation. 1840 1841[NOTE] 1842.Note 1843==== 1844Implementations may write the timestamp at any stage that is 1845<<synchronization-pipeline-stages-order, logically later>> than pname:stage. 1846==== 1847 1848Any timestamp write that <<synchronization-dependencies-execution, 1849happens-after>> another timestamp write in the same submission must: not 1850have a lower value unless its value overflows the maximum supported integer 1851bit width of the query. 1852ifdef::VK_EXT_calibrated_timestamps[] 1853If `apiext:VK_EXT_calibrated_timestamps` is enabled, this extends to 1854timestamp writes across all submissions on the same logical device: any 1855timestamp write that <<synchronization-dependencies-execution, 1856happens-after>> another must: not have a lower value unless its value 1857overflows the maximum supported integer bit width of the query. 1858Timestamps written by this command must: be in the 1859ename:VK_TIME_DOMAIN_DEVICE_EXT <<VkTimeDomainEXT, time domain>>. 1860endif::VK_EXT_calibrated_timestamps[] 1861If an overflow occurs, the timestamp value must: wrap back to zero. 1862 1863[NOTE] 1864.Note 1865==== 1866Comparisons between timestamps should be done between timestamps where they 1867are guaranteed to not decrease. 1868For example, subtracting an older timestamp from a newer one to determine 1869the execution time of a sequence of commands is only a reliable measurement 1870if the two timestamp writes were performed in the same 1871ifdef::VK_EXT_calibrated_timestamps[] 1872submission, or if the writes were performed on the same logical device and 1873`apiext:VK_EXT_calibrated_timestamps` is enabled. 1874endif::VK_EXT_calibrated_timestamps[] 1875ifndef::VK_EXT_calibrated_timestamps[] 1876submission. 1877endif::VK_EXT_calibrated_timestamps[] 1878==== 1879 1880ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1881 1882If fname:vkCmdWriteTimestamp2 is called while executing a render pass 1883instance that has multiview enabled, the timestamp uses [eq]#N# consecutive 1884query indices in the query pool (starting at pname:query) where [eq]#N# is 1885the number of bits set in the view mask of the subpass the command is 1886executed in. 1887The resulting query values are determined by an implementation-dependent 1888choice of one of the following behaviors: 1889 1890 * The first query is a timestamp value and (if more than one bit is set in 1891 the view mask) zero is written to the remaining queries. 1892 If two timestamps are written in the same subpass, the sum of the 1893 execution time of all views between those commands is the difference 1894 between the first query written by each command. 1895 * All [eq]#N# queries are timestamp values. 1896 If two timestamps are written in the same subpass, the sum of the 1897 execution time of all views between those commands is the sum of the 1898 difference between corresponding queries written by each command. 1899 The difference between corresponding queries may: be the execution time 1900 of a single view. 1901 1902In either case, the application can: sum the differences between all [eq]#N# 1903queries to determine the total execution time. 1904 1905endif::VK_VERSION_1_1,VK_KHR_multiview[] 1906 1907.Valid Usage 1908**** 1909:stageMaskName: stage 1910include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 1911 * [[VUID-vkCmdWriteTimestamp2-synchronization2-03858]] 1912 The <<features-synchronization2, pname:synchronization2>> feature must: 1913 be enabled 1914 * [[VUID-vkCmdWriteTimestamp2-stage-03859]] 1915 pname:stage must: only include a single pipeline stage 1916 * [[VUID-vkCmdWriteTimestamp2-stage-03860]] 1917 pname:stage must: only include stages valid for the queue family that 1918 was used to create the command pool that pname:commandBuffer was 1919 allocated from 1920 * [[VUID-vkCmdWriteTimestamp2-queryPool-03861]] 1921 pname:queryPool must: have been created with a pname:queryType of 1922 ename:VK_QUERY_TYPE_TIMESTAMP 1923 * [[VUID-vkCmdWriteTimestamp2-timestampValidBits-03863]] 1924 The command pool's queue family must: support a non-zero 1925 pname:timestampValidBits 1926 * [[VUID-vkCmdWriteTimestamp2-query-04903]] 1927 pname:query must: be less than the number of queries in pname:queryPool 1928 * [[VUID-vkCmdWriteTimestamp2-None-03864]] 1929 All queries used by the command must: be _unavailable_ 1930ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1931 * [[VUID-vkCmdWriteTimestamp2-query-03865]] 1932 If fname:vkCmdWriteTimestamp2 is called within a render pass instance, 1933 the sum of pname:query and the number of bits set in the current 1934 subpass's view mask must: be less than or equal to the number of queries 1935 in pname:queryPool 1936endif::VK_VERSION_1_1,VK_KHR_multiview[] 1937**** 1938 1939include::{generated}/validity/protos/vkCmdWriteTimestamp2.adoc[] 1940-- 1941endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1942 1943[open,refpage='vkCmdWriteTimestamp',desc='Write a device timestamp into a query object',type='protos'] 1944-- 1945:refpage: vkCmdWriteTimestamp 1946 1947To request a timestamp and write the value to memory, call: 1948 1949include::{generated}/api/protos/vkCmdWriteTimestamp.adoc[] 1950 1951 * pname:commandBuffer is the command buffer into which the command will be 1952 recorded. 1953 * pname:pipelineStage is a elink:VkPipelineStageFlagBits value, specifying 1954 a stage of the pipeline. 1955 * pname:queryPool is the query pool that will manage the timestamp. 1956 * pname:query is the query within the query pool that will contain the 1957 timestamp. 1958 1959When fname:vkCmdWriteTimestamp is submitted to a queue, it defines an 1960execution dependency on commands that were submitted before it, and writes a 1961timestamp to a query pool. 1962 1963The first <<synchronization-dependencies-scopes, synchronization scope>> 1964includes all commands that occur earlier in 1965<<synchronization-submission-order,submission order>>. 1966The synchronization scope is limited to operations on the pipeline stage 1967specified by pname:pipelineStage. 1968 1969The second <<synchronization-dependencies-scopes, synchronization scope>> 1970includes only the timestamp write operation. 1971 1972[NOTE] 1973.Note 1974==== 1975Implementations may write the timestamp at any stage that is 1976<<synchronization-pipeline-stages-order, logically later>> than pname:stage. 1977==== 1978 1979Any timestamp write that <<synchronization-dependencies-execution, 1980happens-after>> another timestamp write in the same submission must: not 1981have a lower value unless its value overflows the maximum supported integer 1982bit width of the query. 1983ifdef::VK_EXT_calibrated_timestamps[] 1984If `apiext:VK_EXT_calibrated_timestamps` is enabled, this extends to 1985timestamp writes across all submissions on the same logical device: any 1986timestamp write that <<synchronization-dependencies-execution, 1987happens-after>> another must: not have a lower value unless its value 1988overflows the maximum supported integer bit width of the query. 1989Timestamps written by this command must: be in the 1990ename:VK_TIME_DOMAIN_DEVICE_EXT <<VkTimeDomainEXT, time domain>>. 1991endif::VK_EXT_calibrated_timestamps[] 1992If an overflow occurs, the timestamp value must: wrap back to zero. 1993 1994[NOTE] 1995.Note 1996==== 1997Comparisons between timestamps should be done between timestamps where they 1998are guaranteed to not decrease. 1999For example, subtracting an older timestamp from a newer one to determine 2000the execution time of a sequence of commands is only a reliable measurement 2001if the two timestamp writes were performed in the same 2002ifdef::VK_EXT_calibrated_timestamps[] 2003submission, or if the writes were performed on the same logical device and 2004`apiext:VK_EXT_calibrated_timestamps` is enabled. 2005endif::VK_EXT_calibrated_timestamps[] 2006ifndef::VK_EXT_calibrated_timestamps[] 2007submission. 2008endif::VK_EXT_calibrated_timestamps[] 2009==== 2010 2011 2012ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2013 2014If fname:vkCmdWriteTimestamp is called while executing a render pass 2015instance that has multiview enabled, the timestamp uses [eq]#N# consecutive 2016query indices in the query pool (starting at pname:query) where [eq]#N# is 2017the number of bits set in the view mask of the subpass the command is 2018executed in. 2019The resulting query values are determined by an implementation-dependent 2020choice of one of the following behaviors: 2021 2022 * The first query is a timestamp value and (if more than one bit is set in 2023 the view mask) zero is written to the remaining queries. 2024 If two timestamps are written in the same subpass, the sum of the 2025 execution time of all views between those commands is the difference 2026 between the first query written by each command. 2027 * All [eq]#N# queries are timestamp values. 2028 If two timestamps are written in the same subpass, the sum of the 2029 execution time of all views between those commands is the sum of the 2030 difference between corresponding queries written by each command. 2031 The difference between corresponding queries may: be the execution time 2032 of a single view. 2033 2034In either case, the application can: sum the differences between all [eq]#N# 2035queries to determine the total execution time. 2036 2037endif::VK_VERSION_1_1,VK_KHR_multiview[] 2038 2039.Valid Usage 2040**** 2041include::{chapters}/commonvalidity/pipeline_stage_common.adoc[] 2042 * [[VUID-vkCmdWriteTimestamp-queryPool-01416]] 2043 pname:queryPool must: have been created with a pname:queryType of 2044 ename:VK_QUERY_TYPE_TIMESTAMP 2045 * [[VUID-vkCmdWriteTimestamp-timestampValidBits-00829]] 2046 The command pool's queue family must: support a non-zero 2047 pname:timestampValidBits 2048 * [[VUID-vkCmdWriteTimestamp-query-04904]] 2049 pname:query must: be less than the number of queries in pname:queryPool 2050 * [[VUID-vkCmdWriteTimestamp-None-00830]] 2051 All queries used by the command must: be _unavailable_ 2052ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2053 * [[VUID-vkCmdWriteTimestamp-query-00831]] 2054 If fname:vkCmdWriteTimestamp is called within a render pass instance, 2055 the sum of pname:query and the number of bits set in the current 2056 subpass's view mask must: be less than or equal to the number of queries 2057 in pname:queryPool 2058endif::VK_VERSION_1_1,VK_KHR_multiview[] 2059**** 2060 2061include::{generated}/validity/protos/vkCmdWriteTimestamp.adoc[] 2062-- 2063 2064ifdef::VK_KHR_performance_query[] 2065include::{chapters}/VK_KHR_performance_query/queriesperformance.adoc[] 2066endif::VK_KHR_performance_query[] 2067 2068 2069ifdef::VK_EXT_transform_feedback[] 2070[[queries-transform-feedback]] 2071== Transform Feedback Queries 2072 2073Transform feedback queries track the number of primitives attempted to be 2074written and actually written, by the vertex stream being captured, to a 2075transform feedback buffer. 2076This query is updated during drawing commands while transform feedback is 2077active. 2078The number of primitives actually written will be less than the number 2079attempted to be written if the bound transform feedback buffer size was too 2080small for the number of primitives actually drawn. 2081Primitives are not written beyond the bound range of the transform feedback 2082buffer. 2083A transform feedback query is begun and ended by calling 2084fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively to query for 2085vertex stream zero. 2086fname:vkCmdBeginQueryIndexedEXT and fname:vkCmdEndQueryIndexedEXT can: be 2087used to begin and end transform feedback queries for any supported vertex 2088stream. 2089When a transform feedback query begins, the count of primitives written and 2090primitives needed starts from zero. 2091For each drawing command, the count is incremented as vertex attribute 2092outputs are captured to the transform feedback buffers while transform 2093feedback is active. 2094 2095When a transform feedback query finishes, the result for that query is 2096marked as available. 2097The application can: then either copy the result to a buffer (via 2098fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 2099fname:vkGetQueryPoolResults). 2100endif::VK_EXT_transform_feedback[] 2101 2102 2103ifdef::VK_EXT_primitives_generated_query[] 2104[[queries-primitives-generated]] 2105== Primitives Generated Queries 2106 2107When a generated primitive query for a vertex stream is active, the 2108primitives-generated count is incremented every time a primitive emitted to 2109that stream reaches the transform feedback stage, whether or not transform 2110feedback is active. 2111A primitives generated query is begun and ended by calling 2112fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively to query for 2113vertex stream zero. 2114fname:vkCmdBeginQueryIndexedEXT and fname:vkCmdEndQueryIndexedEXT can: be 2115used to begin and end primitives generated queries for any supported vertex 2116stream. 2117When a primitives generated query begins, the count of primitives generated 2118starts from zero. 2119 2120When a primitives generated query finishes, the result for that query is 2121marked as available. 2122The application can: then either copy the result to a buffer (via 2123fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 2124fname:vkGetQueryPoolResults). 2125 2126[NOTE] 2127.Note 2128==== 2129The result of this query is typically identical to 2130ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT, but the 2131primitives generated query is deterministic, i.e. it must be identical to 2132the number of primitives processed. 2133ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT may vary for 2134implementation-dependent reasons, e.g. the same primitive may be processed 2135multiple times for purposes of clipping. 2136==== 2137endif::VK_EXT_primitives_generated_query[] 2138 2139 2140ifdef::VK_EXT_mesh_shader[] 2141[[queries-mesh-shader]] 2142== Mesh Shader Queries 2143 2144When a generated mesh primitives query is active, the 2145mesh-primitives-generated count is incremented every time a primitive 2146emitted from the mesh shader stage reaches the fragment shader stage. 2147When a generated mesh primitives query begins, the mesh-primitives-generated 2148count starts from zero. 2149 2150Mesh and task shader pipeline statistics queries function the same way that 2151invocation queries work for other shader stages, counting the number of 2152times the respective shader stage has been run. 2153When the statistics query begins, the invocation counters start from zero. 2154endif::VK_EXT_mesh_shader[] 2155 2156ifdef::VK_INTEL_performance_query[] 2157include::{chapters}/VK_INTEL_performance_query/queries.adoc[] 2158endif::VK_INTEL_performance_query[] 2159 2160 2161ifdef::VK_KHR_video_queue[] 2162[[queries-result-status-only]] 2163== Result Status Queries 2164 2165Result status queries serve a single purpose: allowing the application to 2166determine whether a set of operations have completed successfully or not, as 2167indicated by the elink:VkQueryResultStatusKHR value written when retrieving 2168the result of a query using the ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR 2169flag. 2170 2171Unlike other query types, result status queries do not track or maintain any 2172other data beyond the completion status, thus no other data is written when 2173retrieving their results. 2174 2175Support for result status queries is indicated by 2176slink:VkQueueFamilyQueryResultStatusPropertiesKHR::pname:queryResultStatusSupport 2177, as returned by flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the 2178queue family in question. 2179endif::VK_KHR_video_queue[] 2180 2181 2182ifdef::VK_KHR_video_encode_queue[] 2183[[queries-video-encode-feedback]] 2184== Video Encode Feedback Queries 2185 2186Video encode feedback queries allow the application to capture feedback 2187values generated by video encode operations. 2188As such, video encode feedback queries are available on queue families 2189supporting video encode operations. 2190The availability of individual video encode feedback values is indicated by 2191the bits of 2192slink:VkVideoEncodeCapabilitiesKHR::pname:supportedEncodeFeedbackFlags, as 2193returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the 2194<<video-profiles,video profile>> the queries are intended to be used with. 2195 2196The set of enabled video encode feedback values must: be configured on the 2197query pool when it is created using the pname:encodeFeedbackFlags member of 2198the slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR included in the 2199pname:pNext chain of slink:VkQueryPoolCreateInfo. 2200 2201[open,refpage='VkQueryPoolVideoEncodeFeedbackCreateInfoKHR',desc='Structure specifying enabled video encode feedback values',type='structs'] 2202-- 2203The sname:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure is defined 2204as: 2205 2206include::{generated}/api/structs/VkQueryPoolVideoEncodeFeedbackCreateInfoKHR.adoc[] 2207 2208 * pname:sType is a elink:VkStructureType value identifying this structure. 2209 * pname:pNext is `NULL` or a pointer to a structure extending this 2210 structure. 2211 * pname:encodeFeedbackFlags is a bitmask of 2212 elink:VkVideoEncodeFeedbackFlagBitsKHR values specifying the set of 2213 enabled video encode feedback values captured by queries of the new 2214 pool. 2215 2216include::{generated}/validity/structs/VkQueryPoolVideoEncodeFeedbackCreateInfoKHR.adoc[] 2217-- 2218 2219[open,refpage='VkVideoEncodeFeedbackFlagBitsKHR',desc='Bits specifying queried video encode feedback values',type='enums'] 2220-- 2221Bits which can: be set in 2222slink:VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::pname:encodeFeedbackFlags 2223for video encode feedback query pools are: 2224 2225include::{generated}/api/enums/VkVideoEncodeFeedbackFlagBitsKHR.adoc[] 2226 2227 * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR specifies 2228 that queries managed by the pool will capture the byte offset of the 2229 bitstream data written by the video encode operation to the bitstream 2230 buffer specified in slink:VkVideoEncodeInfoKHR::pname:dstBuffer relative 2231 to the offset specified in 2232 slink:VkVideoEncodeInfoKHR::pname:dstBufferOffset. 2233 * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR specifies 2234 that queries managed by the pool will capture the number of bytes 2235 written by the video encode operation to the bitstream buffer specified 2236 in slink:VkVideoEncodeInfoKHR::pname:dstBuffer. 2237 * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR specifies 2238 that queries managed by the pool will capture a boolean value indicating 2239 that the data written to the bitstream buffer specified in 2240 slink:VkVideoEncodeInfoKHR::pname:dstBuffer contains overridden 2241 parameters. 2242 2243When retrieving the results of video encode feedback queries, the values 2244corresponding to each enabled video encode feedback are written in the order 2245of the bits defined above, followed by an optional value indicating 2246availability or result status if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT 2247or ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is specified, respectively. 2248-- 2249 2250[open,refpage='VkVideoEncodeFeedbackFlagsKHR',desc='Bitmask of VkVideoEncodeFeedbackFlagBitsKHR',type='flags'] 2251-- 2252include::{generated}/api/flags/VkVideoEncodeFeedbackFlagsKHR.adoc[] 2253 2254tname:VkVideoEncodeFeedbackFlagsKHR is a bitmask type for setting a mask of 2255zero or more elink:VkVideoEncodeFeedbackFlagBitsKHR. 2256-- 2257endif::VK_KHR_video_encode_queue[] 2258