1// Copyright 2015-2021 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-bitstream-buffer-range, Video Encode Bitstream 24Queries>>, 25endif::VK_KHR_video_encode_queue[] 26and <<queries-timestamps, Timestamp Queries>>. 27ifdef::VK_KHR_performance_query[] 28<<queries-performance, Performance Queries>> are supported if the associated 29extension is available. 30endif::VK_KHR_performance_query[] 31ifdef::VK_EXT_transform_feedback[] 32<<queries-transform-feedback, Transform Feedback Queries>> are supported if 33the associated extension is available. 34endif::VK_EXT_transform_feedback[] 35ifdef::VK_INTEL_performance_query[] 36<<queries-performance-intel>> are supported if the associated extension is 37available. 38endif::VK_INTEL_performance_query[] 39 40ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 41Several additional queries with specific purposes associated with ray 42tracing are available if the corresponding extensions are supported, as 43described for elink:VkQueryType. 44endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 45 46 47[[queries-pools]] 48== Query Pools 49 50[open,refpage='VkQueryPool',desc='Opaque handle to a query pool object',type='handles'] 51-- 52Queries are managed using _query pool_ objects. 53Each query pool is a collection of a specific number of queries of a 54particular type. 55 56Query pools are represented by sname:VkQueryPool handles: 57 58include::{generated}/api/handles/VkQueryPool.txt[] 59-- 60 61[open,refpage='vkCreateQueryPool',desc='Create a new query pool object',type='protos'] 62-- 63To create a query pool, call: 64 65include::{generated}/api/protos/vkCreateQueryPool.txt[] 66 67 * pname:device is the logical device that creates the query pool. 68 * pname:pCreateInfo is a pointer to a slink:VkQueryPoolCreateInfo 69 structure containing the number and type of queries to be managed by the 70 pool. 71 * pname:pAllocator controls host memory allocation as described in the 72 <<memory-allocation, Memory Allocation>> chapter. 73 * pname:pQueryPool is a pointer to a slink:VkQueryPool handle in which the 74 resulting query pool object is returned. 75 76include::{generated}/validity/protos/vkCreateQueryPool.txt[] 77-- 78 79[open,refpage='VkQueryPoolCreateInfo',desc='Structure specifying parameters of a newly created query pool',type='structs'] 80-- 81The sname:VkQueryPoolCreateInfo structure is defined as: 82 83include::{generated}/api/structs/VkQueryPoolCreateInfo.txt[] 84 85 * pname:sType is the type of this structure. 86 * pname:pNext is `NULL` or a pointer to a structure extending this 87 structure. 88 * pname:flags is reserved for future use. 89 * pname:queryType is a elink:VkQueryType value specifying the type of 90 queries managed by the pool. 91 * pname:queryCount is the number of queries managed by the pool. 92 * pname:pipelineStatistics is a bitmask of 93 elink:VkQueryPipelineStatisticFlagBits specifying which counters will be 94 returned in queries on the new pool, as described below in 95 <<queries-pipestats>>. 96 97pname:pipelineStatistics is ignored if pname:queryType is not 98ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. 99 100.Valid Usage 101**** 102 * [[VUID-VkQueryPoolCreateInfo-queryType-00791]] 103 If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> 104 feature is not enabled, pname:queryType must: not be 105 ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 106 * [[VUID-VkQueryPoolCreateInfo-queryType-00792]] 107 If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, 108 pname:pipelineStatistics must: be a valid combination of 109 elink:VkQueryPipelineStatisticFlagBits values 110ifdef::VK_KHR_performance_query[] 111 * [[VUID-VkQueryPoolCreateInfo-queryType-03222]] 112 If pname:queryType is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 113 pname:pNext chain must: include a 114 slink:VkQueryPoolPerformanceCreateInfoKHR structure 115endif::VK_KHR_performance_query[] 116 * [[VUID-VkQueryPoolCreateInfo-queryCount-02763]] 117 pname:queryCount must: be greater than 0 118**** 119 120include::{generated}/validity/structs/VkQueryPoolCreateInfo.txt[] 121-- 122 123[open,refpage='VkQueryPoolCreateFlags',desc='Reserved for future use',type='flags'] 124-- 125include::{generated}/api/flags/VkQueryPoolCreateFlags.txt[] 126 127tname:VkQueryPoolCreateFlags is a bitmask type for setting a mask, but is 128currently reserved for future use. 129-- 130 131ifdef::VK_KHR_performance_query[] 132include::{chapters}/VK_KHR_performance_query/querycreateinfo.txt[] 133endif::VK_KHR_performance_query[] 134 135[open,refpage='vkDestroyQueryPool',desc='Destroy a query pool object',type='protos'] 136-- 137To destroy a query pool, call: 138 139include::{generated}/api/protos/vkDestroyQueryPool.txt[] 140 141 * pname:device is the logical device that destroys the query pool. 142 * pname:queryPool is the query pool to destroy. 143 * pname:pAllocator controls host memory allocation as described in the 144 <<memory-allocation, Memory Allocation>> chapter. 145 146.Valid Usage 147**** 148 * [[VUID-vkDestroyQueryPool-queryPool-00793]] 149 All submitted commands that refer to pname:queryPool must: have 150 completed execution 151 * [[VUID-vkDestroyQueryPool-queryPool-00794]] 152 If sname:VkAllocationCallbacks were provided when pname:queryPool was 153 created, a compatible set of callbacks must: be provided here 154 * [[VUID-vkDestroyQueryPool-queryPool-00795]] 155 If no sname:VkAllocationCallbacks were provided when pname:queryPool was 156 created, pname:pAllocator must: be `NULL` 157**** 158 159[NOTE] 160.Note 161==== 162Applications can: verify that pname:queryPool can: be destroyed by checking 163that fname:vkGetQueryPoolResults() without the 164ename:VK_QUERY_RESULT_PARTIAL_BIT flag returns ename:VK_SUCCESS for all 165queries that are used in command buffers submitted for execution. 166==== 167 168include::{generated}/validity/protos/vkDestroyQueryPool.txt[] 169-- 170 171[open,refpage='VkQueryType',desc='Specify the type of queries managed by a query pool',type='enums'] 172-- 173Possible values of slink:VkQueryPoolCreateInfo::pname:queryType, specifying 174the type of queries managed by the pool, are: 175 176include::{generated}/api/enums/VkQueryType.txt[] 177 178 * ename:VK_QUERY_TYPE_OCCLUSION specifies an <<queries-occlusion, 179 occlusion query>>. 180 * ename:VK_QUERY_TYPE_PIPELINE_STATISTICS specifies a <<queries-pipestats, 181 pipeline statistics query>>. 182 * ename:VK_QUERY_TYPE_TIMESTAMP specifies a <<queries-timestamps, 183 timestamp query>>. 184ifdef::VK_KHR_performance_query[] 185 * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR specifies a 186 <<queries-performance, performance query>>. 187endif::VK_KHR_performance_query[] 188ifdef::VK_EXT_transform_feedback[] 189 * ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT specifies a 190 <<queries-transform-feedback, transform feedback query>>. 191endif::VK_EXT_transform_feedback[] 192ifdef::VK_KHR_acceleration_structure[] 193 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR specifies 194 a <<acceleration-structure-copying, acceleration structure size query>> 195 for use with flink:vkCmdWriteAccelerationStructuresPropertiesKHR or 196 flink:vkWriteAccelerationStructuresPropertiesKHR. 197 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR 198 specifies a <<acceleration-structure-copying, serialization acceleration 199 structure size query>> 200endif::VK_KHR_acceleration_structure[] 201ifdef::VK_NV_ray_tracing[] 202 * ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV specifies a 203 <<acceleration-structure-copying, acceleration structure size query>> 204 for use with flink:vkCmdWriteAccelerationStructuresPropertiesNV. 205endif::VK_NV_ray_tracing[] 206ifdef::VK_INTEL_performance_query[] 207 * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL specifies a 208 <<queries-performance-intel, Intel performance query>>. 209endif::VK_INTEL_performance_query[] 210ifdef::VK_KHR_video_queue[] 211 * ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR specifies a 212 <<queries-result-status-only, result status query>>. 213endif::VK_KHR_video_queue[] 214ifdef::VK_KHR_video_encode_queue[] 215 * ename:VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHR specifies a 216 <<queries-video-encode-bitstream-buffer-range, video encode bitstream 217 range query>>. 218endif::VK_KHR_video_encode_queue[] 219-- 220 221 222[[queries-operation]] 223== Query Operation 224 225The operation of queries is controlled by the commands 226flink:vkCmdBeginQuery, flink:vkCmdEndQuery, 227ifdef::VK_EXT_transform_feedback[] 228flink:vkCmdBeginQueryIndexedEXT, flink:vkCmdEndQueryIndexedEXT, 229endif::VK_EXT_transform_feedback[] 230flink:vkCmdResetQueryPool, flink:vkCmdCopyQueryPoolResults, 231ifdef::VK_KHR_synchronization2[] 232flink:vkCmdWriteTimestamp2KHR, 233endif::VK_KHR_synchronization2[] 234and flink:vkCmdWriteTimestamp. 235 236In order for a sname:VkCommandBuffer to record query management commands, 237the queue family for which its sname:VkCommandPool was created must: support 238the appropriate type of operations (graphics, compute) suitable for the 239query type of a given query pool. 240 241Each query in a query pool has a status that is either _unavailable_ or 242_available_, and also has state to store the numerical results of a query 243operation of the type requested when the query pool was created. 244Resetting a query via flink:vkCmdResetQueryPool 245ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 246or flink:vkResetQueryPool 247endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 248sets the status to unavailable and makes the numerical results undefined:. 249Performing a query operation with flink:vkCmdBeginQuery and 250flink:vkCmdEndQuery changes the status to available when the query 251<<queries-operation-finished,finishes>>, and updates the numerical results. 252Both the availability status and numerical results are retrieved by calling 253either flink:vkGetQueryPoolResults or flink:vkCmdCopyQueryPoolResults. 254 255[[queries-order]] 256Query commands, for the same query and submitted to the same queue, execute 257in their entirety in <<synchronization-submission-order, submission order>>, 258relative to each other. 259In effect there is an implicit execution dependency from each such query 260command to all query commands previously submitted to the same queue. 261There is one significant exception to this; if the pname:flags parameter of 262flink:vkCmdCopyQueryPoolResults does not include 263ename:VK_QUERY_RESULT_WAIT_BIT, execution of flink:vkCmdCopyQueryPoolResults 264may: happen-before the results of flink:vkCmdEndQuery are available. 265 266After query pool creation, each query must: be reset before it is used. 267Queries must: also be reset between uses. 268 269ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 270 271If a logical device includes multiple physical devices, then each command 272that writes a query must: execute on a single physical device, and any call 273to flink:vkCmdBeginQuery must: execute the corresponding flink:vkCmdEndQuery 274command on the same physical device. 275 276endif::VK_VERSION_1_1,VK_KHR_device_group[] 277 278[open,refpage='vkCmdResetQueryPool',desc='Reset queries in a query pool',type='protos'] 279-- 280To reset a range of queries in a query pool on a queue, call: 281 282include::{generated}/api/protos/vkCmdResetQueryPool.txt[] 283 284 * pname:commandBuffer is the command buffer into which this command will 285 be recorded. 286 * pname:queryPool is the handle of the query pool managing the queries 287 being reset. 288 * pname:firstQuery is the initial query index to reset. 289 * pname:queryCount is the number of queries to reset. 290 291When executed on a queue, this command sets the status of query indices 292[eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to 293unavailable. 294 295ifdef::VK_KHR_performance_query[] 296If the pname:queryType used to create pname:queryPool was 297ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command sets the status of 298query indices [eq]#[pname:firstQuery, pname:firstQuery {plus} 299pname:queryCount - 1]# to unavailable for each pass of pname:queryPool, as 300indicated by a call to 301flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. 302 303[NOTE] 304.Note 305==== 306Because fname:vkCmdResetQueryPool resets all the passes of the indicated 307queries, applications must not record a fname:vkCmdResetQueryPool command 308for a pname:queryPool created with ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR 309in a command buffer that needs to be submitted multiple times as indicated 310by a call to flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. 311Otherwise applications will never be able to complete the recorded queries. 312==== 313endif::VK_KHR_performance_query[] 314 315 316.Valid Usage 317**** 318 * [[VUID-vkCmdResetQueryPool-firstQuery-00796]] 319 pname:firstQuery must: be less than the number of queries in 320 pname:queryPool 321 * [[VUID-vkCmdResetQueryPool-firstQuery-00797]] 322 The sum of pname:firstQuery and pname:queryCount must: be less than or 323 equal to the number of queries in pname:queryPool 324 * [[VUID-vkCmdResetQueryPool-None-02841]] 325 All queries used by the command must: not be active 326ifdef::VK_KHR_performance_query[] 327 * [[VUID-vkCmdResetQueryPool-firstQuery-02862]] 328 If pname:queryPool was created with 329 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command must: not be 330 recorded in a command buffer that, either directly or through secondary 331 command buffers, also contains begin commands for a query from the set 332 of queries [eq]#[pname:firstQuery, pname:firstQuery {plus} 333 pname:queryCount - 1]# 334endif::VK_KHR_performance_query[] 335**** 336 337include::{generated}/validity/protos/vkCmdResetQueryPool.txt[] 338-- 339 340ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 341[open,refpage='vkResetQueryPool',desc='Reset queries in a query pool',type='protos',alias='vkResetQueryPoolEXT'] 342-- 343To reset a range of queries in a query pool on the host, call: 344 345ifdef::VK_VERSION_1_2[] 346include::{generated}/api/protos/vkResetQueryPool.txt[] 347endif::VK_VERSION_1_2[] 348 349ifdef::VK_VERSION_1_2+VK_EXT_host_query_reset[or the equivalent command] 350 351ifdef::VK_EXT_host_query_reset[] 352include::{generated}/api/protos/vkResetQueryPoolEXT.txt[] 353endif::VK_EXT_host_query_reset[] 354 355 * pname:device is the logical device that owns the query pool. 356 * pname:queryPool is the handle of the query pool managing the queries 357 being reset. 358 * pname:firstQuery is the initial query index to reset. 359 * pname:queryCount is the number of queries to reset. 360 361This command sets the status of query indices [eq]#[pname:firstQuery, 362pname:firstQuery {plus} pname:queryCount - 1]# to unavailable. 363 364ifdef::VK_KHR_performance_query[] 365If pname:queryPool is ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR this command 366sets the status of query indices [eq]#[pname:firstQuery, pname:firstQuery 367{plus} pname:queryCount - 1]# to unavailable for each pass. 368endif::VK_KHR_performance_query[] 369 370.Valid Usage 371**** 372 * [[VUID-vkResetQueryPool-None-02665]] 373 The <<features-hostQueryReset,hostQueryReset>> feature must: be enabled 374 * [[VUID-vkResetQueryPool-firstQuery-02666]] 375 pname:firstQuery must: be less than the number of queries in 376 pname:queryPool 377 * [[VUID-vkResetQueryPool-firstQuery-02667]] 378 The sum of pname:firstQuery and pname:queryCount must: be less than or 379 equal to the number of queries in pname:queryPool 380 * [[VUID-vkResetQueryPool-firstQuery-02741]] 381 Submitted commands that refer to the range specified by pname:firstQuery 382 and pname:queryCount in pname:queryPool must: have completed execution 383 * [[VUID-vkResetQueryPool-firstQuery-02742]] 384 The range of queries specified by pname:firstQuery and pname:queryCount 385 in pname:queryPool must: not be in use by calls to 386 flink:vkGetQueryPoolResults or fname:vkResetQueryPool in other threads 387**** 388 389include::{generated}/validity/protos/vkResetQueryPool.txt[] 390-- 391endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 392 393Once queries are reset and ready for use, query commands can: be issued to a 394command buffer. 395Occlusion queries and pipeline statistics queries count events - drawn 396samples and pipeline stage invocations, respectively - resulting from 397commands that are recorded between a flink:vkCmdBeginQuery command and a 398flink:vkCmdEndQuery command within a specified command buffer, effectively 399scoping a set of drawing and/or dispatching commands. 400Timestamp queries write timestamps to a query pool. 401ifdef::VK_KHR_performance_query[] 402Performance queries record performance counters to a query pool. 403endif::VK_KHR_performance_query[] 404 405A query must: begin and end in the same command buffer, although if it is a 406primary command buffer, and the <<features-inheritedQueries,inherited 407queries>> feature is enabled, it can: execute secondary command buffers 408during the query operation. 409For a secondary command buffer to be executed while a query is active, it 410must: set the pname:occlusionQueryEnable, pname:queryFlags, and/or 411pname:pipelineStatistics members of slink:VkCommandBufferInheritanceInfo to 412conservative values, as described in the <<commandbuffers-recording, Command 413Buffer Recording>> section. 414A query must: either begin and end inside the same subpass of a render pass 415instance, or must: both begin and end outside of a render pass instance 416(i.e. contain entire render pass instances). 417 418ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 419 420If queries are used while executing a render pass instance that has 421multiview enabled, the query uses [eq]#N# consecutive query indices in the 422query pool (starting at pname:query) where [eq]#N# is the number of bits set 423in the view mask in the subpass the query is used in. 424How the numerical results of the query are distributed among the queries is 425implementation-dependent. 426For example, some implementations may: write each view's results to a 427distinct query, while other implementations may: write the total result to 428the first query and write zero to the other queries. 429However, the sum of the results in all the queries must: accurately reflect 430the total result of the query summed over all views. 431Applications can: sum the results from all the queries to compute the total 432result. 433 434Queries used with multiview rendering must: not span subpasses, i.e. they 435must: begin and end in the same subpass. 436 437endif::VK_VERSION_1_1,VK_KHR_multiview[] 438 439[open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos'] 440-- 441:refpage: vkCmdBeginQuery 442 443To begin a query, call: 444 445include::{generated}/api/protos/vkCmdBeginQuery.txt[] 446 447 * pname:commandBuffer is the command buffer into which this command will 448 be recorded. 449 * pname:queryPool is the query pool that will manage the results of the 450 query. 451 * pname:query is the query index within the query pool that will contain 452 the results. 453 * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying 454 constraints on the types of queries that can: be performed. 455 456If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and 457pname:flags contains ename:VK_QUERY_CONTROL_PRECISE_BIT, an implementation 458must: return a result that matches the actual number of samples passed. 459This is described in more detail in <<queries-occlusion,Occlusion Queries>>. 460 461ifdef::VK_EXT_transform_feedback[] 462Calling fname:vkCmdBeginQuery is equivalent to calling 463flink:vkCmdBeginQueryIndexedEXT with the pname:index parameter set to zero. 464endif::VK_EXT_transform_feedback[] 465 466[[queries-operation-active]] 467After beginning a query, that query is considered _active_ within the 468command buffer it was called in until that same query is ended. 469Queries active in a primary command buffer when secondary command buffers 470are executed are considered active for those secondary command buffers. 471 472.Valid Usage 473**** 474include::{chapters}/commonvalidity/query_begin_common.txt[] 475 * [[VUID-vkCmdBeginQuery-queryPool-01922]] 476 pname:queryPool must: have been created with a pname:queryType that 477 differs from that of any queries that are 478 <<queries-operation-active,active>> within pname:commandBuffer 479ifdef::VK_EXT_transform_feedback[] 480 * [[VUID-vkCmdBeginQuery-queryType-02327]] 481 If the pname:queryType used to create pname:queryPool was 482 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the 483 sname:VkCommandPool that pname:commandBuffer was allocated from must: 484 support graphics operations 485 * [[VUID-vkCmdBeginQuery-queryType-02328]] 486 If the pname:queryType used to create pname:queryPool was 487 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then 488 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries 489 must: be supported 490endif::VK_EXT_transform_feedback[] 491include::{chapters}/commonvalidity/performance_query_begin_common.txt[] 492**** 493 494include::{generated}/validity/protos/vkCmdBeginQuery.txt[] 495-- 496 497ifdef::VK_EXT_transform_feedback[] 498[open,refpage='vkCmdBeginQueryIndexedEXT',desc='Begin an indexed query',type='protos'] 499-- 500:refpage: vkCmdBeginQueryIndexedEXT 501 502To begin an indexed query, call: 503 504include::{generated}/api/protos/vkCmdBeginQueryIndexedEXT.txt[] 505 506 * pname:commandBuffer is the command buffer into which this command will 507 be recorded. 508 * pname:queryPool is the query pool that will manage the results of the 509 query. 510 * pname:query is the query index within the query pool that will contain 511 the results. 512 * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying 513 constraints on the types of queries that can: be performed. 514 * pname:index is the query type specific index. 515 When the query type is ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 516 the index represents the vertex stream. 517 518The fname:vkCmdBeginQueryIndexedEXT command operates the same as the 519flink:vkCmdBeginQuery command, except that it also accepts a query type 520specific pname:index parameter. 521 522.Valid Usage 523**** 524include::{chapters}/commonvalidity/query_begin_common.txt[] 525 * [[VUID-vkCmdBeginQueryIndexedEXT-queryPool-04753]] 526 If the pname:queryPool was created with the same pname:queryType as that 527 of another <<queries-operation-active,active>> query within 528 pname:commandBuffer, then pname:index must: not match the index used for 529 the active query 530 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02338]] 531 If the pname:queryType used to create pname:queryPool was 532 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the 533 sname:VkCommandPool that pname:commandBuffer was allocated from must: 534 support graphics operations 535 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02339]] 536 If the pname:queryType used to create pname:queryPool was 537 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index 538 parameter must: be less than 539 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 540 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02340]] 541 If the pname:queryType used to create pname:queryPool was not 542 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index must: 543 be zero 544 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02341]] 545 If the pname:queryType used to create pname:queryPool was 546 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then 547 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries 548 must: be supported 549include::{chapters}/commonvalidity/performance_query_begin_common.txt[] 550**** 551 552include::{generated}/validity/protos/vkCmdBeginQueryIndexedEXT.txt[] 553-- 554endif::VK_EXT_transform_feedback[] 555 556[open,refpage='VkQueryControlFlagBits',desc='Bitmask specifying constraints on a query',type='enums'] 557-- 558Bits which can: be set in flink:vkCmdBeginQuery::pname:flags, specifying 559constraints on the types of queries that can: be performed, are: 560 561include::{generated}/api/enums/VkQueryControlFlagBits.txt[] 562 563 * ename:VK_QUERY_CONTROL_PRECISE_BIT specifies the precision of 564 <<queries-occlusion, occlusion queries>>. 565-- 566 567[open,refpage='VkQueryControlFlags',desc='Bitmask of VkQueryControlFlagBits',type='flags'] 568-- 569include::{generated}/api/flags/VkQueryControlFlags.txt[] 570 571tname:VkQueryControlFlags is a bitmask type for setting a mask of zero or 572more elink:VkQueryControlFlagBits. 573-- 574 575[open,refpage='vkCmdEndQuery',desc='Ends a query',type='protos'] 576-- 577To end a query after the set of desired drawing or dispatching commands is 578executed, call: 579 580include::{generated}/api/protos/vkCmdEndQuery.txt[] 581 582 * pname:commandBuffer is the command buffer into which this command will 583 be recorded. 584 * pname:queryPool is the query pool that is managing the results of the 585 query. 586 * pname:query is the query index within the query pool where the result is 587 stored. 588 589ifdef::VK_EXT_transform_feedback[] 590Calling fname:vkCmdEndQuery is equivalent to calling 591flink:vkCmdEndQueryIndexedEXT with the pname:index parameter set to zero. 592endif::VK_EXT_transform_feedback[] 593 594[[queries-operation-finished]] 595As queries operate asynchronously, ending a query does not immediately set 596the query's status to available. 597A query is considered _finished_ when the final results of the query are 598ready to be retrieved by flink:vkGetQueryPoolResults and 599flink:vkCmdCopyQueryPoolResults, and this is when the query's status is set 600to available. 601 602Once a query is ended the query must: finish in finite time, unless the 603state of the query is changed using other commands, e.g. by issuing a reset 604of the query. 605 606.Valid Usage 607**** 608 * [[VUID-vkCmdEndQuery-None-01923]] 609 All queries used by the command must: be 610 <<queries-operation-active,active>> 611 * [[VUID-vkCmdEndQuery-query-00810]] 612 pname:query must: be less than the number of queries in pname:queryPool 613ifdef::VK_VERSION_1_1[] 614 * [[VUID-vkCmdEndQuery-commandBuffer-01886]] 615 pname:commandBuffer must: not be a protected command buffer 616endif::VK_VERSION_1_1[] 617ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 618 * [[VUID-vkCmdEndQuery-query-00812]] 619 If fname:vkCmdEndQuery is called within a render pass instance, the sum 620 of pname:query and the number of bits set in the current subpass's view 621 mask must: be less than or equal to the number of queries in 622 pname:queryPool 623endif::VK_VERSION_1_1,VK_KHR_multiview[] 624ifdef::VK_KHR_performance_query[] 625 * [[VUID-vkCmdEndQuery-queryPool-03227]] 626 If pname:queryPool was created with a pname:queryType of 627 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the 628 counters used to create pname:queryPool was 629 ename:VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the 630 flink:vkCmdEndQuery must: be the last recorded command in 631 pname:commandBuffer 632 * [[VUID-vkCmdEndQuery-queryPool-03228]] 633 If pname:queryPool was created with a pname:queryType of 634 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the 635 counters used to create pname:queryPool was 636 ename:VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the 637 flink:vkCmdEndQuery must: not be recorded within a render pass instance 638endif::VK_KHR_performance_query[] 639**** 640 641include::{generated}/validity/protos/vkCmdEndQuery.txt[] 642-- 643 644ifdef::VK_EXT_transform_feedback[] 645[open,refpage='vkCmdEndQueryIndexedEXT',desc='Ends a query',type='protos'] 646-- 647To end an indexed query after the set of desired drawing or dispatching 648commands is recorded, call: 649 650include::{generated}/api/protos/vkCmdEndQueryIndexedEXT.txt[] 651 652 * pname:commandBuffer is the command buffer into which this command will 653 be recorded. 654 * pname:queryPool is the query pool that is managing the results of the 655 query. 656 * pname:query is the query index within the query pool where the result is 657 stored. 658 * pname:index is the query type specific index. 659 660The fname:vkCmdEndQueryIndexedEXT command operates the same as the 661flink:vkCmdEndQuery command, except that it also accepts a query type 662specific pname:index parameter. 663 664.Valid Usage 665**** 666 * [[VUID-vkCmdEndQueryIndexedEXT-None-02342]] 667 All queries used by the command must: be 668 <<queries-operation-active,active>> 669 * [[VUID-vkCmdEndQueryIndexedEXT-query-02343]] 670 pname:query must: be less than the number of queries in pname:queryPool 671ifdef::VK_VERSION_1_1[] 672 * [[VUID-vkCmdEndQueryIndexedEXT-commandBuffer-02344]] 673 pname:commandBuffer must: not be a protected command buffer 674endif::VK_VERSION_1_1[] 675ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 676 * [[VUID-vkCmdEndQueryIndexedEXT-query-02345]] 677 If fname:vkCmdEndQueryIndexedEXT is called within a render pass 678 instance, the sum of pname:query and the number of bits set in the 679 current subpass's view mask must: be less than or equal to the number of 680 queries in pname:queryPool 681endif::VK_VERSION_1_1,VK_KHR_multiview[] 682 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02346]] 683 If the pname:queryType used to create pname:queryPool was 684 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index 685 parameter must: be less than 686 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 687 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02347]] 688 If the pname:queryType used to create pname:queryPool was not 689 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index must: 690 be zero 691 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02723]] 692 If the pname:queryType used to create pname:queryPool was 693 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT pname:index must: 694 equal the pname:index used to begin the query 695 696**** 697 698include::{generated}/validity/protos/vkCmdEndQueryIndexedEXT.txt[] 699-- 700endif::VK_EXT_transform_feedback[] 701 702[[queries-operation-memorylayout]] 703An application can: retrieve results either by requesting they be written 704into application-provided memory, or by requesting they be copied into a 705sname:VkBuffer. 706In either case, the layout in memory is defined as follows: 707 708 * The first query's result is written starting at the first byte requested 709 by the command, and each subsequent query's result begins pname:stride 710 bytes later. 711 * Occlusion queries, pipeline statistics queries, 712ifdef::VK_EXT_transform_feedback[] 713 transform feedback queries, 714endif::VK_EXT_transform_feedback[] 715 and timestamp queries store results in a tightly packed array of 716 unsigned integers, either 32- or 64-bits as requested by the command, 717 storing the numerical results and, if requested, the availability 718 status. 719ifdef::VK_KHR_performance_query[] 720 * Performance queries store results in a tightly packed array whose type 721 is determined by the pname:unit member of the corresponding 722 slink:VkPerformanceCounterKHR. 723endif::VK_KHR_performance_query[] 724 * If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, the final 725 element of each query's result is an integer indicating whether the 726 query's result is available, with any non-zero value indicating that it 727 is available. 728ifdef::VK_KHR_video_queue[] 729 * If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is used, the final element 730 of each query's result is an integer value indicating that status of the 731 query result. 732 Positive values indicate success, negative values indicate failure, and 733 0 indicates that the result is not yet available. 734 Specific error codes are encoded in the elink:VkQueryResultStatusKHR 735 enumeration. 736endif::VK_KHR_video_queue[] 737 * Occlusion queries write one integer value - the number of samples 738 passed. 739 Pipeline statistics queries write one integer value for each bit that is 740 enabled in the pname:pipelineStatistics when the pool is created, and 741 the statistics values are written in bit order starting from the least 742 significant bit. 743 Timestamp queries write one integer value. 744ifdef::VK_KHR_performance_query[] 745 Performance queries write one slink:VkPerformanceCounterResultKHR value 746 for each slink:VkPerformanceCounterKHR in the query. 747endif::VK_KHR_performance_query[] 748ifdef::VK_EXT_transform_feedback[] 749 Transform feedback queries write two integers; the first integer is the 750 number of primitives successfully written to the corresponding transform 751 feedback buffer and the second is the number of primitives output to the 752 vertex stream, regardless of whether they were successfully captured or 753 not. 754 In other words, if the transform feedback buffer was sized too small for 755 the number of primitives output by the vertex stream, the first integer 756 represents the number of primitives actually written and the second is 757 the number that would have been written if all the transform feedback 758 buffers associated with that vertex stream were large enough. 759endif::VK_EXT_transform_feedback[] 760 * If more than one query is retrieved and pname:stride is not at least as 761 large as the size of the array of values corresponding to a single 762 query, the values written to memory are undefined:. 763 764[open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos'] 765-- 766To retrieve status and results for a set of queries, call: 767 768include::{generated}/api/protos/vkGetQueryPoolResults.txt[] 769 770 * pname:device is the logical device that owns the query pool. 771 * pname:queryPool is the query pool managing the queries containing the 772 desired results. 773 * pname:firstQuery is the initial query index. 774 * pname:queryCount is the number of queries to read. 775 * pname:dataSize is the size in bytes of the buffer pointed to by 776 pname:pData. 777 * pname:pData is a pointer to a user-allocated buffer where the results 778 will be written 779 * pname:stride is the stride in bytes between results for individual 780 queries within pname:pData. 781 * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how 782 and when results are returned. 783 784The range of queries read is defined by [eq]#[pname:firstQuery, 785pname:firstQuery {plus} pname:queryCount - 1]#. 786For pipeline statistics queries, each query index in the pool contains one 787integer value for each bit that is enabled in 788slink:VkQueryPoolCreateInfo::pname:pipelineStatistics when the pool is 789created. 790 791If no bits are set in pname:flags, and all requested queries are in the 792available state, results are written as an array of 32-bit unsigned integer 793values. 794The behavior when not all queries are available, is described 795<<queries-wait-bit-not-set, below>>. 796 797If ename:VK_QUERY_RESULT_64_BIT is not set and the result overflows a 32-bit 798value, the value may: either wrap or saturate. 799Similarly, if ename:VK_QUERY_RESULT_64_BIT is set and the result overflows a 80064-bit value, the value may: either wrap or saturate. 801 802If ename:VK_QUERY_RESULT_WAIT_BIT is set, Vulkan will wait for each query to 803be in the available state before retrieving the numerical results for that 804query. 805In this case, fname:vkGetQueryPoolResults is guaranteed to succeed and 806return ename:VK_SUCCESS if the queries become available in a finite time 807(i.e. if they have been issued and not reset). 808If queries will never finish (e.g. due to being reset but not issued), then 809fname:vkGetQueryPoolResults may: not return in finite time. 810 811[[queries-wait-bit-not-set]] 812If ename:VK_QUERY_RESULT_WAIT_BIT and ename:VK_QUERY_RESULT_PARTIAL_BIT are 813both not set then no result values are written to pname:pData for queries 814that are in the unavailable state at the time of the call, and 815fname:vkGetQueryPoolResults returns ename:VK_NOT_READY. 816However, availability state is still written to pname:pData for those 817queries if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set. 818ifdef::VK_KHR_video_queue[] 819Similarly, the status is still written to pname:pData for those queries if 820ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set. 821endif::VK_KHR_video_queue[] 822 823If ename:VK_QUERY_RESULT_WAIT_BIT is not set, fname:vkGetQueryPoolResults 824may: return ename:VK_NOT_READY if there are queries in the unavailable 825state. 826 827[NOTE] 828.Note 829==== 830Applications must: take care to ensure that use of the 831ename:VK_QUERY_RESULT_WAIT_BIT bit has the desired effect. 832 833For example, if a query has been used previously and a command buffer 834records the commands fname:vkCmdResetQueryPool, fname:vkCmdBeginQuery, and 835fname:vkCmdEndQuery for that query, then the query will remain in the 836available state until 837ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 838fname:vkResetQueryPool is called or 839endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 840the fname:vkCmdResetQueryPool command executes on a queue. 841Applications can: use fences or events to ensure that a query has already 842been reset before checking for its results or availability status. 843Otherwise, a stale value could be returned from a previous use of the query. 844 845The above also applies when ename:VK_QUERY_RESULT_WAIT_BIT is used in 846combination with ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT. 847In this case, the returned availability status may: reflect the result of a 848previous use of the query unless 849ifdef::VK_VERSION_1_2,VK_EXT_host_query_reset[] 850fname:vkResetQueryPool is called or 851endif::VK_VERSION_1_2,VK_EXT_host_query_reset[] 852the fname:vkCmdResetQueryPool command has been executed since the last use 853of the query. 854 855ifdef::VK_KHR_video_queue[] 856A similar situation can arise with the 857ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag. 858endif::VK_KHR_video_queue[] 859==== 860 861[NOTE] 862.Note 863==== 864Applications can: double-buffer query pool usage, with a pool per frame, and 865reset queries at the end of the frame in which they are read. 866==== 867 868If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT 869is not set, and the query's status is unavailable, an intermediate result 870value between zero and the final result value is written to pname:pData for 871that query. 872 873If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, the final integer 874value written for each query is non-zero if the query's status was available 875or zero if the status was unavailable. 876When ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, implementations 877must: guarantee that if they return a non-zero availability value then the 878numerical results must: be valid, assuming the results are not reset by a 879subsequent command. 880 881[NOTE] 882.Note 883==== 884Satisfying this guarantee may: require careful ordering by the application, 885e.g. to read the availability status before reading the results. 886==== 887 888ifdef::VK_KHR_video_queue[] 889If ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, the final integer value 890written for each query indicates whether the result is available or not, and 891whether an error occurred. 892A value of zero indicates that the results are not yet available. 893Positive values indicate that the operations within the query completed 894successfully, and the query results are valid. 895Negative values indicate that the operations within the query completed 896unsuccessfully. 897 898Specific result codes are defined by the elink:VkQueryResultStatusKHR 899enumeration. 900endif::VK_KHR_video_queue[] 901 902.Valid Usage 903**** 904 * [[VUID-vkGetQueryPoolResults-firstQuery-00813]] 905 pname:firstQuery must: be less than the number of queries in 906 pname:queryPool 907ifndef::VK_KHR_performance_query[] 908 * [[VUID-vkGetQueryPoolResults-flags-02827]] 909 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags, then 910 pname:pData and pname:stride must: be multiples of `4` 911endif::VK_KHR_performance_query[] 912ifdef::VK_KHR_performance_query[] 913 * [[VUID-vkGetQueryPoolResults-flags-02828]] 914 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags and the 915 pname:queryType used to create pname:queryPool was not 916 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:pData and 917 pname:stride must: be multiples of `4` 918endif::VK_KHR_performance_query[] 919 * [[VUID-vkGetQueryPoolResults-flags-00815]] 920 If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then pname:pData 921 and pname:stride must: be multiples of `8` 922ifdef::VK_KHR_performance_query[] 923 * [[VUID-vkGetQueryPoolResults-queryType-03229]] 924 If the pname:queryType used to create pname:queryPool was 925 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:pData and 926 pname:stride must: be multiples of the size of 927 slink:VkPerformanceCounterResultKHR 928 * [[VUID-vkGetQueryPoolResults-queryType-04519]] 929 If the pname:queryType used to create pname:queryPool was 930 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then pname:stride must: be 931 large enough to contain 932 sname:VkQueryPoolPerformanceCreateInfoKHR::pname:counterIndexCount used 933 to create pname:queryPool times the size of 934 slink:VkPerformanceCounterResultKHR 935endif::VK_KHR_performance_query[] 936 * [[VUID-vkGetQueryPoolResults-firstQuery-00816]] 937 The sum of pname:firstQuery and pname:queryCount must: be less than or 938 equal to the number of queries in pname:queryPool 939 * [[VUID-vkGetQueryPoolResults-dataSize-00817]] 940 pname:dataSize must: be large enough to contain the result of each 941 query, as described <<queries-operation-memorylayout,here>> 942 * [[VUID-vkGetQueryPoolResults-queryType-00818]] 943 If the pname:queryType used to create pname:queryPool was 944 ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain 945 ename:VK_QUERY_RESULT_PARTIAL_BIT 946ifdef::VK_KHR_performance_query[] 947 * [[VUID-vkGetQueryPoolResults-queryType-03230]] 948 If the pname:queryType used to create pname:queryPool was 949 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, pname:flags must: not contain 950 ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT, 951 ename:VK_QUERY_RESULT_PARTIAL_BIT or ename:VK_QUERY_RESULT_64_BIT 952 * [[VUID-vkGetQueryPoolResults-queryType-03231]] 953 If the pname:queryType used to create pname:queryPool was 954 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:queryPool must: 955 have been recorded once for each pass as retrieved via a call to 956 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 957endif::VK_KHR_performance_query[] 958ifdef::VK_KHR_video_queue[] 959 * [[VUID-vkGetQueryPoolResults-queryType-04810]] 960 If the pname:queryType used to create pname:queryPool was 961 ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, pname:flags must: include 962 ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR 963 * [[VUID-vkGetQueryPoolResults-flags-04811]] 964 If pname:flags includes ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR, it 965 must: not include ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT 966endif::VK_KHR_video_queue[] 967**** 968 969include::{generated}/validity/protos/vkGetQueryPoolResults.txt[] 970-- 971 972[open,refpage='VkQueryResultFlagBits',desc='Bitmask specifying how and when query results are returned',type='enums'] 973-- 974Bits which can: be set in flink:vkGetQueryPoolResults::pname:flags and 975flink:vkCmdCopyQueryPoolResults::pname:flags, specifying how and when 976results are returned, are: 977 978include::{generated}/api/enums/VkQueryResultFlagBits.txt[] 979 980 * ename:VK_QUERY_RESULT_64_BIT specifies the results will be written as an 981 array of 64-bit unsigned integer values. 982 If this bit is not set, the results will be written as an array of 983 32-bit unsigned integer values. 984 * ename:VK_QUERY_RESULT_WAIT_BIT specifies that Vulkan will wait for each 985 query's status to become available before retrieving its results. 986 * ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT specifies that the 987 availability status accompanies the results. 988 * ename:VK_QUERY_RESULT_PARTIAL_BIT specifies that returning partial 989 results is acceptable. 990ifdef::VK_KHR_video_queue[] 991 * ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR specifies that the last value 992 returned in the query is a elink:VkQueryResultStatusKHR value. 993endif::VK_KHR_video_queue[] 994-- 995 996[open,refpage='VkQueryResultFlags',desc='Bitmask of VkQueryResultFlagBits',type='flags'] 997-- 998include::{generated}/api/flags/VkQueryResultFlags.txt[] 999 1000tname:VkQueryResultFlags is a bitmask type for setting a mask of zero or 1001more elink:VkQueryResultFlagBits. 1002-- 1003 1004ifdef::VK_KHR_video_queue[] 1005[open,refpage='VkQueryResultStatusKHR',desc='Specific status codes for operations',type='enums'] 1006-- 1007Specific status codes that can: be returned from a query are: 1008 1009include::{generated}/api/enums/VkQueryResultStatusKHR.txt[] 1010 1011 * ename:VK_QUERY_RESULT_STATUS_NOT_READY_KHR specifies that the query 1012 result is not yet available. 1013 * ename:VK_QUERY_RESULT_STATUS_ERROR_KHR specifies that operations did not 1014 complete successfully. 1015 * ename:VK_QUERY_RESULT_STATUS_COMPLETE_KHR specifies that operations 1016 completed successfully and the query result is available. 1017-- 1018endif::VK_KHR_video_queue[] 1019 1020[open,refpage='vkCmdCopyQueryPoolResults',desc='Copy the results of queries in a query pool to a buffer object',type='protos'] 1021-- 1022To copy query statuses and numerical results directly to buffer memory, 1023call: 1024 1025include::{generated}/api/protos/vkCmdCopyQueryPoolResults.txt[] 1026 1027 * pname:commandBuffer is the command buffer into which this command will 1028 be recorded. 1029 * pname:queryPool is the query pool managing the queries containing the 1030 desired results. 1031 * pname:firstQuery is the initial query index. 1032 * pname:queryCount is the number of queries. 1033 pname:firstQuery and pname:queryCount together define a range of 1034 queries. 1035 * pname:dstBuffer is a slink:VkBuffer object that will receive the results 1036 of the copy command. 1037 * pname:dstOffset is an offset into pname:dstBuffer. 1038 * pname:stride is the stride in bytes between results for individual 1039 queries within pname:dstBuffer. 1040 The required size of the backing memory for pname:dstBuffer is 1041 determined as described above for flink:vkGetQueryPoolResults. 1042 * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how 1043 and when results are returned. 1044 1045fname:vkCmdCopyQueryPoolResults is guaranteed to see the effect of previous 1046uses of fname:vkCmdResetQueryPool in the same queue, without any additional 1047synchronization. 1048Thus, the results will always reflect the most recent use of the query. 1049 1050pname:flags has the same possible values described above for the pname:flags 1051parameter of flink:vkGetQueryPoolResults, but the different style of 1052execution causes some subtle behavioral differences. 1053Because fname:vkCmdCopyQueryPoolResults executes in order with respect to 1054other query commands, there is less ambiguity about which use of a query is 1055being requested. 1056 1057Results for all requested occlusion queries, pipeline statistics queries, 1058ifdef::VK_EXT_transform_feedback[] 1059transform feedback queries, 1060endif::VK_EXT_transform_feedback[] 1061and timestamp queries are written as 64-bit unsigned integer values if 1062ename:VK_QUERY_RESULT_64_BIT is set or 32-bit unsigned integer values 1063otherwise. 1064ifdef::VK_KHR_performance_query[] 1065Performance queries store results in a tightly packed array whose type is 1066determined by the pname:unit member of the corresponding 1067slink:VkPerformanceCounterKHR. 1068endif::VK_KHR_performance_query[] 1069 1070If neither of ename:VK_QUERY_RESULT_WAIT_BIT and 1071ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT are set, results are only 1072written out for queries in the available state. 1073 1074If ename:VK_QUERY_RESULT_WAIT_BIT is set, the implementation will wait for 1075each query's status to be in the available state before retrieving the 1076numerical results for that query. 1077This is guaranteed to reflect the most recent use of the query on the same 1078queue, assuming that the query is not being simultaneously used by other 1079queues. 1080If the query does not become available in a finite amount of time (e.g. due 1081to not issuing a query since the last reset), a ename:VK_ERROR_DEVICE_LOST 1082error may: occur. 1083 1084Similarly, if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set and 1085ename:VK_QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to 1086reflect the most recent use of the query on the same queue, assuming that 1087the query is not being simultaneously used by other queues. 1088As with fname:vkGetQueryPoolResults, implementations must: guarantee that if 1089they return a non-zero availability value, then the numerical results are 1090valid. 1091 1092If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT 1093is not set, and the query's status is unavailable, an intermediate result 1094value between zero and the final result value is written for that query. 1095 1096ename:VK_QUERY_RESULT_PARTIAL_BIT must: not be used if the pool's 1097pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP. 1098 1099fname:vkCmdCopyQueryPoolResults is considered to be a transfer operation, 1100and its writes to buffer memory must: be synchronized using 1101ename:VK_PIPELINE_STAGE_TRANSFER_BIT and ename:VK_ACCESS_TRANSFER_WRITE_BIT 1102before using the results. 1103 1104.Valid Usage 1105**** 1106 * [[VUID-vkCmdCopyQueryPoolResults-dstOffset-00819]] 1107 pname:dstOffset must: be less than the size of pname:dstBuffer 1108 * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00820]] 1109 pname:firstQuery must: be less than the number of queries in 1110 pname:queryPool 1111 * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00821]] 1112 The sum of pname:firstQuery and pname:queryCount must: be less than or 1113 equal to the number of queries in pname:queryPool 1114 * [[VUID-vkCmdCopyQueryPoolResults-flags-00822]] 1115 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags then 1116 pname:dstOffset and pname:stride must: be multiples of `4` 1117 * [[VUID-vkCmdCopyQueryPoolResults-flags-00823]] 1118 If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then 1119 pname:dstOffset and pname:stride must: be multiples of `8` 1120 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00824]] 1121 pname:dstBuffer must: have enough storage, from pname:dstOffset, to 1122 contain the result of each query, as described 1123 <<queries-operation-memorylayout,here>> 1124 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00825]] 1125 pname:dstBuffer must: have been created with 1126 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 1127 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00826]] 1128 If pname:dstBuffer is non-sparse then it must: be bound completely and 1129 contiguously to a single sname:VkDeviceMemory object 1130 * [[VUID-vkCmdCopyQueryPoolResults-queryType-00827]] 1131 If the pname:queryType used to create pname:queryPool was 1132 ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain 1133 ename:VK_QUERY_RESULT_PARTIAL_BIT 1134ifdef::VK_KHR_performance_query[] 1135 * [[VUID-vkCmdCopyQueryPoolResults-queryType-03232]] 1136 If the pname:queryType used to create pname:queryPool was 1137 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, 1138 slink:VkPhysicalDevicePerformanceQueryPropertiesKHR::pname:allowCommandBufferQueryCopies 1139 must: be ename:VK_TRUE 1140 * [[VUID-vkCmdCopyQueryPoolResults-queryType-03233]] 1141 If the pname:queryType used to create pname:queryPool was 1142 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, pname:flags must: not contain 1143 ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT, 1144 ename:VK_QUERY_RESULT_PARTIAL_BIT or ename:VK_QUERY_RESULT_64_BIT 1145 * [[VUID-vkCmdCopyQueryPoolResults-queryType-03234]] 1146 If the pname:queryType used to create pname:queryPool was 1147 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the pname:queryPool must: 1148 have been submitted once for each pass as retrieved via a call to 1149 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 1150endif::VK_KHR_performance_query[] 1151ifdef::VK_INTEL_performance_query[] 1152 * [[VUID-vkCmdCopyQueryPoolResults-queryType-02734]] 1153 flink:vkCmdCopyQueryPoolResults must: not be called if the 1154 pname:queryType used to create pname:queryPool was 1155 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL 1156endif::VK_INTEL_performance_query[] 1157ifdef::VK_KHR_video_queue[] 1158 * [[VUID-vkCmdCopyQueryPoolResults-queryType-04812]] 1159 flink:vkCmdCopyQueryPoolResults must: not be called if the 1160 pname:queryType used to create pname:queryPool was 1161 ename:VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHR or 1162 ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR 1163endif::VK_KHR_video_queue[] 1164**** 1165 1166include::{generated}/validity/protos/vkCmdCopyQueryPoolResults.txt[] 1167-- 1168 1169[[queries-operation-undefined]] 1170Rendering operations such as clears, MSAA resolves, attachment load/store 1171operations, and blits may: count towards the results of queries. 1172This behavior is implementation-dependent and may: vary depending on the 1173path used within an implementation. 1174For example, some implementations have several types of clears, some of 1175which may: include vertices and some not. 1176 1177 1178[[queries-occlusion]] 1179== Occlusion Queries 1180 1181Occlusion queries track the number of samples that pass the per-fragment 1182tests for a set of drawing commands. 1183As such, occlusion queries are only available on queue families supporting 1184graphics operations. 1185The application can: then use these results to inform future rendering 1186decisions. 1187An occlusion query is begun and ended by calling fname:vkCmdBeginQuery and 1188fname:vkCmdEndQuery, respectively. 1189When an occlusion query begins, the count of passing samples always starts 1190at zero. 1191For each drawing command, the count is incremented as described in 1192<<fragops-samplecount,Sample Counting>>. 1193If pname:flags does not contain ename:VK_QUERY_CONTROL_PRECISE_BIT an 1194implementation may: generate any non-zero result value for the query if the 1195count of passing samples is non-zero. 1196 1197[NOTE] 1198.Note 1199==== 1200Not setting ename:VK_QUERY_CONTROL_PRECISE_BIT mode may: be more efficient 1201on some implementations, and should: be used where it is sufficient to know 1202a boolean result on whether any samples passed the per-fragment tests. 1203In this case, some implementations may: only return zero or one, indifferent 1204to the actual number of samples passing the per-fragment tests. 1205==== 1206 1207When an occlusion query finishes, the result for that query is marked as 1208available. 1209The application can: then either copy the result to a buffer (via 1210fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 1211fname:vkGetQueryPoolResults). 1212 1213[NOTE] 1214.Note 1215==== 1216If occluding geometry is not drawn first, samples can: pass the depth test, 1217but still not be visible in a final image. 1218==== 1219 1220 1221[[queries-pipestats]] 1222== Pipeline Statistics Queries 1223 1224Pipeline statistics queries allow the application to sample a specified set 1225of sname:VkPipeline counters. 1226These counters are accumulated by Vulkan for a set of either drawing or 1227dispatching commands while a pipeline statistics query is active. 1228As such, pipeline statistics queries are available on queue families 1229supporting either graphics or compute operations. 1230The availability of pipeline statistics queries is indicated by the 1231pname:pipelineStatisticsQuery member of the sname:VkPhysicalDeviceFeatures 1232object (see fname:vkGetPhysicalDeviceFeatures and fname:vkCreateDevice for 1233detecting and requesting this query type on a sname:VkDevice). 1234 1235A pipeline statistics query is begun and ended by calling 1236fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively. 1237When a pipeline statistics query begins, all statistics counters are set to 1238zero. 1239While the query is active, the pipeline type determines which set of 1240statistics are available, but these must: be configured on the query pool 1241when it is created. 1242If a statistic counter is issued on a command buffer that does not support 1243the corresponding operation, the value of that counter is undefined: after 1244the query has finished. 1245At least one statistic counter relevant to the operations supported on the 1246recording command buffer must: be enabled. 1247 1248[open,refpage='VkQueryPipelineStatisticFlagBits',desc='Bitmask specifying queried pipeline statistics',type='enums'] 1249-- 1250Bits which can: be set to individually enable pipeline statistics counters 1251for query pools with slink:VkQueryPoolCreateInfo::pname:pipelineStatistics, 1252and for secondary command buffers with 1253slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics, are: 1254 1255include::{generated}/api/enums/VkQueryPipelineStatisticFlagBits.txt[] 1256 1257 * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT specifies 1258 that queries managed by the pool will count the number of vertices 1259 processed by the <<drawing,input assembly>> stage. 1260 Vertices corresponding to incomplete primitives may: contribute to the 1261 count. 1262 * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT 1263 specifies that queries managed by the pool will count the number of 1264 primitives processed by the <<drawing,input assembly>> stage. 1265 If primitive restart is enabled, restarting the primitive topology has 1266 no effect on the count. 1267 Incomplete primitives may: be counted. 1268 * ename:VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT 1269 specifies that queries managed by the pool will count the number of 1270 vertex shader invocations. 1271 This counter's value is incremented each time a vertex shader is 1272 <<shaders-vertex-execution,invoked>>. 1273 * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT 1274 specifies that queries managed by the pool will count the number of 1275 geometry shader invocations. 1276 This counter's value is incremented each time a geometry shader is 1277 <<shaders-geometry-execution,invoked>>. 1278 In the case of <<geometry-invocations,instanced geometry shaders>>, the 1279 geometry shader invocations count is incremented for each separate 1280 instanced invocation. 1281 * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT 1282 specifies that queries managed by the pool will count the number of 1283 primitives generated by geometry shader invocations. 1284 The counter's value is incremented each time the geometry shader emits a 1285 primitive. 1286 Restarting primitive topology using the SPIR-V instructions 1287 code:OpEndPrimitive or code:OpEndStreamPrimitive has no effect on the 1288 geometry shader output primitives count. 1289 * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT specifies 1290 that queries managed by the pool will count the number of primitives 1291 processed by the <<vertexpostproc-clipping,Primitive Clipping>> stage of 1292 the pipeline. 1293 The counter's value is incremented each time a primitive reaches the 1294 primitive clipping stage. 1295 * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT specifies that 1296 queries managed by the pool will count the number of primitives output 1297 by the <<vertexpostproc-clipping,Primitive Clipping>> stage of the 1298 pipeline. 1299 The counter's value is incremented each time a primitive passes the 1300 primitive clipping stage. 1301 The actual number of primitives output by the primitive clipping stage 1302 for a particular input primitive is implementation-dependent but must: 1303 satisfy the following conditions: 1304 ** If at least one vertex of the input primitive lies inside the clipping 1305 volume, the counter is incremented by one or more. 1306 ** Otherwise, the counter is incremented by zero or more. 1307 * ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT 1308 specifies that queries managed by the pool will count the number of 1309 fragment shader invocations. 1310 The counter's value is incremented each time the fragment shader is 1311 <<fragops-shader,invoked>>. 1312 * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT 1313 specifies that queries managed by the pool will count the number of 1314 patches processed by the tessellation control shader. 1315 The counter's value is incremented once for each patch for which a 1316 tessellation control shader is 1317 <<shaders-tessellation-control-execution,invoked>>. 1318 * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT 1319 specifies that queries managed by the pool will count the number of 1320 invocations of the tessellation evaluation shader. 1321 The counter's value is incremented each time the tessellation evaluation 1322 shader is <<shaders-tessellation-evaluation-execution,invoked>>. 1323 * ename:VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT 1324 specifies that queries managed by the pool will count the number of 1325 compute shader invocations. 1326 The counter's value is incremented every time the compute shader is 1327 invoked. 1328 Implementations may: skip the execution of certain compute shader 1329 invocations or execute additional compute shader invocations for 1330 implementation-dependent reasons as long as the results of rendering 1331 otherwise remain unchanged. 1332 1333These values are intended to measure relative statistics on one 1334implementation. 1335Various device architectures will count these values differently. 1336Any or all counters may: be affected by the issues described in 1337<<queries-operation-undefined,Query Operation>>. 1338 1339[NOTE] 1340.Note 1341==== 1342For example, tile-based rendering devices may: need to replay the scene 1343multiple times, affecting some of the counts. 1344==== 1345 1346If a pipeline has pname:rasterizerDiscardEnable enabled, implementations 1347may: discard primitives after the final 1348<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 1349stage>>. 1350As a result, if pname:rasterizerDiscardEnable is enabled, the clipping input 1351and output primitives counters may: not be incremented. 1352 1353When a pipeline statistics query finishes, the result for that query is 1354marked as available. 1355The application can: copy the result to a buffer (via 1356fname:vkCmdCopyQueryPoolResults), or request it be put into host memory (via 1357fname:vkGetQueryPoolResults). 1358-- 1359 1360[open,refpage='VkQueryPipelineStatisticFlags',desc='Bitmask of VkQueryPipelineStatisticFlagBits',type='flags'] 1361-- 1362include::{generated}/api/flags/VkQueryPipelineStatisticFlags.txt[] 1363 1364tname:VkQueryPipelineStatisticFlags is a bitmask type for setting a mask of 1365zero or more elink:VkQueryPipelineStatisticFlagBits. 1366-- 1367 1368 1369[[queries-timestamps]] 1370== Timestamp Queries 1371 1372_Timestamps_ provide applications with a mechanism for timing the execution 1373of commands. 1374A timestamp is an integer value generated by the sname:VkPhysicalDevice. 1375Unlike other queries, timestamps do not operate over a range, and so do not 1376use flink:vkCmdBeginQuery or flink:vkCmdEndQuery. 1377The mechanism is built around a set of commands that allow the application 1378to tell the sname:VkPhysicalDevice to write timestamp values to a 1379<<queries-pools,query pool>> and then either read timestamp values on the 1380host (using flink:vkGetQueryPoolResults) or copy timestamp values to a 1381sname:VkBuffer (using flink:vkCmdCopyQueryPoolResults). 1382The application can: then compute differences between timestamps to 1383determine execution time. 1384 1385The number of valid bits in a timestamp value is determined by the 1386sname:VkQueueFamilyProperties::pname:timestampValidBits property of the 1387queue on which the timestamp is written. 1388Timestamps are supported on any queue which reports a non-zero value for 1389pname:timestampValidBits via flink:vkGetPhysicalDeviceQueueFamilyProperties. 1390If the <<limits-timestampComputeAndGraphics, 1391pname:timestampComputeAndGraphics>> limit is ename:VK_TRUE, timestamps are 1392supported by every queue family that supports either graphics or compute 1393operations (see slink:VkQueueFamilyProperties). 1394 1395The number of nanoseconds it takes for a timestamp value to be incremented 1396by 1 can: be obtained from 1397sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to 1398fname:vkGetPhysicalDeviceProperties. 1399 1400ifdef::VK_KHR_synchronization2[] 1401 1402[open,refpage='vkCmdWriteTimestamp2KHR',desc='Write a device timestamp into a query object',type='protos'] 1403-- 1404:refpage: vkCmdWriteTimestamp2KHR 1405 1406To request a timestamp, call: 1407 1408include::{generated}/api/protos/vkCmdWriteTimestamp2KHR.txt[] 1409 1410 * pname:commandBuffer is the command buffer into which the command will be 1411 recorded. 1412 * pname:stage specifies a stage of the pipeline. 1413 * pname:queryPool is the query pool that will manage the timestamp. 1414 * pname:query is the query within the query pool that will contain the 1415 timestamp. 1416 1417When fname:vkCmdWriteTimestamp2KHR is submitted to a queue, it defines an 1418execution dependency on commands that were submitted before it, and writes a 1419timestamp to a query pool. 1420 1421The first <<synchronization-dependencies-scopes, synchronization scope>> 1422includes all commands that occur earlier in 1423<<synchronization-submission-order,submission order>>. 1424The synchronization scope is limited to operations on the pipeline stage 1425specified by pname:stage. 1426 1427The second <<synchronization-dependencies-scopes, synchronization scope>> 1428includes only the timestamp write operation. 1429 1430When the timestamp value is written, the availability status of the query is 1431set to available. 1432 1433[NOTE] 1434.Note 1435==== 1436If an implementation is unable to detect completion and latch the timer at 1437any specific stage of the pipeline, it may: instead do so at any logically 1438later stage. 1439==== 1440 1441Comparisons between timestamps are not meaningful if the timestamps are 1442written by commands submitted to different queues. 1443 1444[NOTE] 1445.Note 1446==== 1447An example of such a comparison is subtracting an older timestamp from a 1448newer one to determine the execution time of a sequence of commands. 1449==== 1450 1451ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1452 1453If fname:vkCmdWriteTimestamp2KHR is called while executing a render pass 1454instance that has multiview enabled, the timestamp uses [eq]#N# consecutive 1455query indices in the query pool (starting at pname:query) where [eq]#N# is 1456the number of bits set in the view mask of the subpass the command is 1457executed in. 1458The resulting query values are determined by an implementation-dependent 1459choice of one of the following behaviors: 1460 1461 * The first query is a timestamp value and (if more than one bit is set in 1462 the view mask) zero is written to the remaining queries. 1463 If two timestamps are written in the same subpass, the sum of the 1464 execution time of all views between those commands is the difference 1465 between the first query written by each command. 1466 * All [eq]#N# queries are timestamp values. 1467 If two timestamps are written in the same subpass, the sum of the 1468 execution time of all views between those commands is the sum of the 1469 difference between corresponding queries written by each command. 1470 The difference between corresponding queries may: be the execution time 1471 of a single view. 1472 1473In either case, the application can: sum the differences between all [eq]#N# 1474queries to determine the total execution time. 1475 1476endif::VK_VERSION_1_1,VK_KHR_multiview[] 1477 1478.Valid Usage 1479**** 1480:stageMaskName: stage 1481include::{chapters}/commonvalidity/stage_mask_2_common.txt[] 1482 * [[VUID-vkCmdWriteTimestamp2KHR-synchronization2-03858]] 1483 The <<features-synchronization2, pname:synchronization2>> feature must: 1484 be enabled 1485 * [[VUID-vkCmdWriteTimestamp2KHR-stage-03859]] 1486 pname:stage must: only include a single pipeline stage 1487 * [[VUID-vkCmdWriteTimestamp2KHR-stage-03860]] 1488 pname:stage must: only include stages valid for the queue family that 1489 was used to create the command pool that pname:commandBuffer was 1490 allocated from 1491 * [[VUID-vkCmdWriteTimestamp2KHR-queryPool-03861]] 1492 pname:queryPool must: have been created with a pname:queryType of 1493 ename:VK_QUERY_TYPE_TIMESTAMP 1494 * [[VUID-vkCmdWriteTimestamp2KHR-queryPool-03862]] 1495 The query identified by pname:queryPool and pname:query must: be 1496 _unavailable_ 1497 * [[VUID-vkCmdWriteTimestamp2KHR-timestampValidBits-03863]] 1498 The command pool's queue family must: support a non-zero 1499 pname:timestampValidBits 1500 * [[VUID-vkCmdWriteTimestamp2KHR-query-04903]] 1501 pname:query must: be less than the number of queries in pname:queryPool 1502ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1503 * [[VUID-vkCmdWriteTimestamp2KHR-None-03864]] 1504 All queries used by the command must: be unavailable 1505 * [[VUID-vkCmdWriteTimestamp2KHR-query-03865]] 1506 If fname:vkCmdWriteTimestamp2KHR is called within a render pass 1507 instance, the sum of pname:query and the number of bits set in the 1508 current subpass's view mask must: be less than or equal to the number of 1509 queries in pname:queryPool 1510endif::VK_VERSION_1_1,VK_KHR_multiview[] 1511**** 1512 1513include::{generated}/validity/protos/vkCmdWriteTimestamp2KHR.txt[] 1514-- 1515endif::VK_KHR_synchronization2[] 1516 1517[open,refpage='vkCmdWriteTimestamp',desc='Write a device timestamp into a query object',type='protos'] 1518-- 1519:refpage: vkCmdWriteTimestamp 1520 1521To request a timestamp, call: 1522 1523include::{generated}/api/protos/vkCmdWriteTimestamp.txt[] 1524 1525 * pname:commandBuffer is the command buffer into which the command will be 1526 recorded. 1527 * pname:pipelineStage is a elink:VkPipelineStageFlagBits value, specifying 1528 a stage of the pipeline. 1529 * pname:queryPool is the query pool that will manage the timestamp. 1530 * pname:query is the query within the query pool that will contain the 1531 timestamp. 1532 1533fname:vkCmdWriteTimestamp latches the value of the timer when all previous 1534commands have completed executing as far as the specified pipeline stage, 1535and writes the timestamp value to memory. 1536When the timestamp value is written, the availability status of the query is 1537set to available. 1538 1539[NOTE] 1540.Note 1541==== 1542If an implementation is unable to detect completion and latch the timer at 1543any specific stage of the pipeline, it may: instead do so at any logically 1544later stage. 1545==== 1546 1547Comparisons between timestamps are not meaningful if the timestamps are 1548written by commands submitted to different queues. 1549 1550[NOTE] 1551.Note 1552==== 1553An example of such a comparison is subtracting an older timestamp from a 1554newer one to determine the execution time of a sequence of commands. 1555==== 1556 1557ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1558 1559If fname:vkCmdWriteTimestamp is called while executing a render pass 1560instance that has multiview enabled, the timestamp uses [eq]#N# consecutive 1561query indices in the query pool (starting at pname:query) where [eq]#N# is 1562the number of bits set in the view mask of the subpass the command is 1563executed in. 1564The resulting query values are determined by an implementation-dependent 1565choice of one of the following behaviors: 1566 1567 * The first query is a timestamp value and (if more than one bit is set in 1568 the view mask) zero is written to the remaining queries. 1569 If two timestamps are written in the same subpass, the sum of the 1570 execution time of all views between those commands is the difference 1571 between the first query written by each command. 1572 * All [eq]#N# queries are timestamp values. 1573 If two timestamps are written in the same subpass, the sum of the 1574 execution time of all views between those commands is the sum of the 1575 difference between corresponding queries written by each command. 1576 The difference between corresponding queries may: be the execution time 1577 of a single view. 1578 1579In either case, the application can: sum the differences between all [eq]#N# 1580queries to determine the total execution time. 1581 1582endif::VK_VERSION_1_1,VK_KHR_multiview[] 1583 1584.Valid Usage 1585**** 1586include::{chapters}/commonvalidity/pipeline_stage_common.txt[] 1587 * [[VUID-vkCmdWriteTimestamp-queryPool-01416]] 1588 pname:queryPool must: have been created with a pname:queryType of 1589 ename:VK_QUERY_TYPE_TIMESTAMP 1590 * [[VUID-vkCmdWriteTimestamp-queryPool-00828]] 1591 The query identified by pname:queryPool and pname:query must: be 1592 _unavailable_ 1593 * [[VUID-vkCmdWriteTimestamp-timestampValidBits-00829]] 1594 The command pool's queue family must: support a non-zero 1595 pname:timestampValidBits 1596 * [[VUID-vkCmdWriteTimestamp-query-04904]] 1597 pname:query must: be less than the number of queries in pname:queryPool 1598ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1599 * [[VUID-vkCmdWriteTimestamp-None-00830]] 1600 All queries used by the command must: be unavailable 1601 * [[VUID-vkCmdWriteTimestamp-query-00831]] 1602 If fname:vkCmdWriteTimestamp is called within a render pass instance, 1603 the sum of pname:query and the number of bits set in the current 1604 subpass's view mask must: be less than or equal to the number of queries 1605 in pname:queryPool 1606endif::VK_VERSION_1_1,VK_KHR_multiview[] 1607**** 1608 1609include::{generated}/validity/protos/vkCmdWriteTimestamp.txt[] 1610-- 1611 1612ifdef::VK_KHR_performance_query[] 1613include::{chapters}/VK_KHR_performance_query/queriesperformance.txt[] 1614endif::VK_KHR_performance_query[] 1615 1616 1617ifdef::VK_EXT_transform_feedback[] 1618[[queries-transform-feedback]] 1619== Transform Feedback Queries 1620 1621Transform feedback queries track the number of primitives attempted to be 1622written and actually written, by the vertex stream being captured, to a 1623transform feedback buffer. 1624This query is updated during drawing commands while transform feedback is 1625active. 1626The number of primitives actually written will be less than the number 1627attempted to be written if the bound transform feedback buffer size was too 1628small for the number of primitives actually drawn. 1629Primitives are not written beyond the bound range of the transform feedback 1630buffer. 1631A transform feedback query is begun and ended by calling 1632fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively to query for 1633vertex stream zero. 1634fname:vkCmdBeginQueryIndexedEXT and fname:vkCmdEndQueryIndexedEXT can: be 1635used to begin and end transform feedback queries for any supported vertex 1636stream. 1637When a transform feedback query begins, the count of primitives written and 1638primitives needed starts from zero. 1639For each drawing command, the count is incremented as vertex attribute 1640outputs are captured to the transform feedback buffers while transform 1641feedback is active. 1642 1643When a transform feedback query finishes, the result for that query is 1644marked as available. 1645The application can: then either copy the result to a buffer (via 1646fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 1647fname:vkGetQueryPoolResults). 1648 1649endif::VK_EXT_transform_feedback[] 1650 1651ifdef::VK_INTEL_performance_query[] 1652include::{chapters}/VK_INTEL_performance_query/queries.txt[] 1653endif::VK_INTEL_performance_query[] 1654 1655 1656ifdef::VK_KHR_video_queue[] 1657[[queries-result-status-only]] 1658== Result Status Queries 1659 1660Result status queries are used for a single purpose - to check whether a set 1661of operations has completed successfully or not, using the 1662ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag. 1663 1664No other data is written to such a query. 1665endif::VK_KHR_video_queue[] 1666 1667 1668ifdef::VK_KHR_video_encode_queue[] 1669[[queries-video-encode-bitstream-buffer-range]] 1670== Video Encode Bitstream Buffer Range 1671 1672Bitstream buffer range queries describe the range of bytes written in the 1673bitstream buffer by video encode commands. 1674 1675When an encode command is recorded within a bitstream buffer range query, 1676two values are written to the query slot. 1677The first value is an offset into the bitstream buffer where the encoded 1678video data was written. 1679This offset is an additional offset from the start of the range specified by 1680the application. 1681The second value is a size value describing the number of bytes written to 1682the bitstream buffer beyond the offset. 1683 1684One slot is consumed for each slice in each command recorded between a begin 1685and end query pair. 1686endif::VK_KHR_video_encode_queue[] 1687