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