queries.txt
1 // Copyright (c) 2015-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 [[queries]] 6 = Queries 7 8 _Queries_ provide a mechanism to return information about the processing of 9 a sequence of Vulkan commands. 10 Query operations are asynchronous, and as such, their results are not 11 returned immediately. 12 Instead, their results, and their availability status are stored in a 13 <<queries-pools, Query Pool>>. 14 The state of these queries can: be read back on the host, or copied to a 15 buffer object on the device. 16 17 The supported query types are <<queries-occlusion,Occlusion Queries>>, 18 <<queries-pipestats,Pipeline Statistics Queries>>, and <<queries-timestamps, 19 Timestamp Queries>>. 20 ifdef::VK_INTEL_performance_query[] 21 <<queries-performance-intel>> are also supported if the associated extension 22 is available. 23 endif::VK_INTEL_performance_query[] 24 25 [[queries-pools]] 26 == Query Pools 27 28 [open,refpage='VkQueryPool',desc='Opaque handle to a query pool object',type='handles'] 29 -- 30 31 Queries are managed using _query pool_ objects. 32 Each query pool is a collection of a specific number of queries of a 33 particular type. 34 35 Query pools are represented by sname:VkQueryPool handles: 36 37 include::{generated}/api/handles/VkQueryPool.txt[] 38 39 -- 40 41 [open,refpage='vkCreateQueryPool',desc='Create a new query pool object',type='protos'] 42 -- 43 44 To create a query pool, call: 45 46 include::{generated}/api/protos/vkCreateQueryPool.txt[] 47 48 * pname:device is the logical device that creates the query pool. 49 * pname:pCreateInfo is a pointer to an instance of the 50 sname:VkQueryPoolCreateInfo structure containing the number and type of 51 queries to be managed by the pool. 52 * pname:pAllocator controls host memory allocation as described in the 53 <<memory-allocation, Memory Allocation>> chapter. 54 * pname:pQueryPool is a pointer to a slink:VkQueryPool handle in which the 55 resulting query pool object is returned. 56 57 include::{generated}/validity/protos/vkCreateQueryPool.txt[] 58 -- 59 60 [open,refpage='VkQueryPoolCreateInfo',desc='Structure specifying parameters of a newly created query pool',type='structs'] 61 -- 62 63 The sname:VkQueryPoolCreateInfo structure is defined as: 64 65 include::{generated}/api/structs/VkQueryPoolCreateInfo.txt[] 66 67 * pname:sType is the type of this structure. 68 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 69 * pname:flags is reserved for future use. 70 * pname:queryType is a elink:VkQueryType value specifying the type of 71 queries managed by the pool. 72 * pname:queryCount is the number of queries managed by the pool. 73 * pname:pipelineStatistics is a bitmask of 74 elink:VkQueryPipelineStatisticFlagBits specifying which counters will be 75 returned in queries on the new pool, as described below in 76 <<queries-pipestats>>. 77 78 pname:pipelineStatistics is ignored if pname:queryType is not 79 ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. 80 81 .Valid Usage 82 **** 83 * [[VUID-VkQueryPoolCreateInfo-queryType-00791]] 84 If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> 85 feature is not enabled, pname:queryType must: not be 86 ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 87 * [[VUID-VkQueryPoolCreateInfo-queryType-00792]] 88 If pname:queryType is ename:VK_QUERY_TYPE_PIPELINE_STATISTICS, 89 pname:pipelineStatistics must: be a valid combination of 90 elink:VkQueryPipelineStatisticFlagBits values 91 **** 92 93 include::{generated}/validity/structs/VkQueryPoolCreateInfo.txt[] 94 -- 95 96 [open,refpage='VkQueryPoolCreateFlags',desc='Reserved for future use',type='flags'] 97 -- 98 include::{generated}/api/flags/VkQueryPoolCreateFlags.txt[] 99 100 tname:VkQueryPoolCreateFlags is a bitmask type for setting a mask, but is 101 currently reserved for future use. 102 -- 103 104 [open,refpage='vkDestroyQueryPool',desc='Destroy a query pool object',type='protos'] 105 -- 106 107 To destroy a query pool, call: 108 109 include::{generated}/api/protos/vkDestroyQueryPool.txt[] 110 111 * pname:device is the logical device that destroys the query pool. 112 * pname:queryPool is the query pool to destroy. 113 * pname:pAllocator controls host memory allocation as described in the 114 <<memory-allocation, Memory Allocation>> chapter. 115 116 .Valid Usage 117 **** 118 * [[VUID-vkDestroyQueryPool-queryPool-00793]] 119 All submitted commands that refer to pname:queryPool must: have 120 completed execution 121 * [[VUID-vkDestroyQueryPool-queryPool-00794]] 122 If sname:VkAllocationCallbacks were provided when pname:queryPool was 123 created, a compatible set of callbacks must: be provided here 124 * [[VUID-vkDestroyQueryPool-queryPool-00795]] 125 If no sname:VkAllocationCallbacks were provided when pname:queryPool was 126 created, pname:pAllocator must: be `NULL` 127 **** 128 129 include::{generated}/validity/protos/vkDestroyQueryPool.txt[] 130 -- 131 132 [open,refpage='VkQueryType',desc='Specify the type of queries managed by a query pool',type='enums'] 133 -- 134 135 Possible values of slink:VkQueryPoolCreateInfo::pname:queryType, specifying 136 the type of queries managed by the pool, are: 137 138 include::{generated}/api/enums/VkQueryType.txt[] 139 140 * ename:VK_QUERY_TYPE_OCCLUSION specifies an <<queries-occlusion, 141 occlusion query>>. 142 * ename:VK_QUERY_TYPE_PIPELINE_STATISTICS specifies a <<queries-pipestats, 143 pipeline statistics query>>. 144 * ename:VK_QUERY_TYPE_TIMESTAMP specifies a <<queries-timestamps, 145 timestamp query>>. 146 ifdef::VK_EXT_transform_feedback[] 147 * ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT specifies a 148 <<queries-transform-feedback, transform feedback query>>. 149 endif::VK_EXT_transform_feedback[] 150 ifdef::VK_INTEL_performance_query[] 151 * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL specifies a 152 <<queries-performance-intel, Intel performance query>>. 153 endif::VK_INTEL_performance_query[] 154 155 -- 156 157 158 159 [[queries-operation]] 160 == Query Operation 161 162 The operation of queries is controlled by the commands 163 flink:vkCmdBeginQuery, flink:vkCmdEndQuery, 164 ifdef::VK_EXT_transform_feedback[] 165 flink:vkCmdBeginQueryIndexedEXT, flink:vkCmdEndQueryIndexedEXT, 166 endif::VK_EXT_transform_feedback[] 167 flink:vkCmdResetQueryPool, flink:vkCmdCopyQueryPoolResults, and 168 flink:vkCmdWriteTimestamp. 169 170 In order for a sname:VkCommandBuffer to record query management commands, 171 the queue family for which its sname:VkCommandPool was created must: support 172 the appropriate type of operations (graphics, compute) suitable for the 173 query type of a given query pool. 174 175 Each query in a query pool has a status that is either _unavailable_ or 176 _available_, and also has state to store the numerical results of a query 177 operation of the type requested when the query pool was created. 178 Resetting a query via flink:vkCmdResetQueryPool 179 ifdef::VK_EXT_host_query_reset[] 180 or flink:vkResetQueryPoolEXT 181 endif::VK_EXT_host_query_reset[] 182 sets the status to unavailable and makes the numerical results undefined:. 183 Performing a query operation with flink:vkCmdBeginQuery and 184 flink:vkCmdEndQuery changes the status to available when the query 185 <<queries-operation-finished,finishes>>, and updates the numerical results. 186 Both the availability status and numerical results are retrieved by calling 187 either flink:vkGetQueryPoolResults or flink:vkCmdCopyQueryPoolResults. 188 189 [[queries-order]] 190 Query commands, for the same query and submitted to the same queue, execute 191 in their entirety in <<synchronization-submission-order, submission order>>, 192 relative to each other. 193 In effect there is an implicit execution dependency from each such query 194 command to all query command previously submitted to the same queue. 195 There is one significant exception to this; if the pname:flags parameter of 196 flink:vkCmdCopyQueryPoolResults does not include 197 ename:VK_QUERY_RESULT_WAIT_BIT, execution of flink:vkCmdCopyQueryPoolResults 198 may: happen-before the results of flink:vkCmdEndQuery are available. 199 200 After query pool creation, each query must: be reset before it is used. 201 Queries must: also be reset between uses. 202 203 ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 204 205 If a logical device includes multiple physical devices, then each command 206 that writes a query must: execute on a single physical device, and any call 207 to flink:vkCmdBeginQuery must: execute the corresponding flink:vkCmdEndQuery 208 command on the same physical device. 209 210 endif::VK_VERSION_1_1,VK_KHR_device_group[] 211 212 [open,refpage='vkCmdResetQueryPool',desc='Reset queries in a query pool',type='protos'] 213 -- 214 215 To reset a range of queries in a query pool on a queue, call: 216 217 include::{generated}/api/protos/vkCmdResetQueryPool.txt[] 218 219 * pname:commandBuffer is the command buffer into which this command will 220 be recorded. 221 * pname:queryPool is the handle of the query pool managing the queries 222 being reset. 223 * pname:firstQuery is the initial query index to reset. 224 * pname:queryCount is the number of queries to reset. 225 226 When executed on a queue, this command sets the status of query indices 227 [eq]#[pname:firstQuery, pname:firstQuery {plus} pname:queryCount - 1]# to 228 unavailable. 229 230 .Valid Usage 231 **** 232 * [[VUID-vkCmdResetQueryPool-firstQuery-00796]] 233 pname:firstQuery must: be less than the number of queries in 234 pname:queryPool 235 * [[VUID-vkCmdResetQueryPool-firstQuery-00797]] 236 The sum of pname:firstQuery and pname:queryCount must: be less than or 237 equal to the number of queries in pname:queryPool 238 **** 239 240 include::{generated}/validity/protos/vkCmdResetQueryPool.txt[] 241 -- 242 243 ifdef::VK_EXT_host_query_reset[] 244 245 [open,refpage='vkResetQueryPoolEXT',desc='Reset queries in a query pool',type='protos'] 246 -- 247 248 To reset a range of queries in a query pool on the host, call: 249 250 include::{generated}/api/protos/vkResetQueryPoolEXT.txt[] 251 252 * pname:device is the logical device that owns the query pool. 253 * pname:queryPool is the handle of the query pool managing the queries 254 being reset. 255 * pname:firstQuery is the initial query index to reset. 256 * pname:queryCount is the number of queries to reset. 257 258 This command sets the status of query indices [eq]#[pname:firstQuery, 259 pname:firstQuery {plus} pname:queryCount - 1]# to unavailable. 260 261 .Valid Usage 262 **** 263 * [[VUID-vkResetQueryPoolEXT-None-02665]] 264 The <<features-hostQueryReset,hostQueryReset>> feature must: be enabled 265 * [[VUID-vkResetQueryPoolEXT-firstQuery-02666]] 266 pname:firstQuery must: be less than the number of queries in 267 pname:queryPool 268 * [[VUID-vkResetQueryPoolEXT-firstQuery-02667]] 269 The sum of pname:firstQuery and pname:queryCount must: be less than or 270 equal to the number of queries in pname:queryPool 271 * [[VUID-vkResetQueryPoolEXT-firstQuery-02741]] 272 Submitted commands that refer to the range specified by pname:firstQuery 273 and pname:queryCount in pname:queryPool must: have completed execution 274 * [[VUID-vkResetQueryPoolEXT-firstQuery-02742]] 275 The range of queries specified by pname:firstQuery and pname:queryCount 276 in pname:queryPool must: not be in use by calls to 277 flink:vkGetQueryPoolResults or fname:vkResetQueryPoolEXT in other 278 threads 279 **** 280 281 include::{generated}/validity/protos/vkResetQueryPoolEXT.txt[] 282 -- 283 284 endif::VK_EXT_host_query_reset[] 285 286 Once queries are reset and ready for use, query commands can: be issued to a 287 command buffer. 288 Occlusion queries and pipeline statistics queries count events - drawn 289 samples and pipeline stage invocations, respectively - resulting from 290 commands that are recorded between a flink:vkCmdBeginQuery command and a 291 flink:vkCmdEndQuery command within a specified command buffer, effectively 292 scoping a set of drawing and/or compute commands. 293 Timestamp queries write timestamps to a query pool. 294 295 A query must: begin and end in the same command buffer, although if it is a 296 primary command buffer, and the <<features-inheritedQueries,inherited 297 queries>> feature is enabled, it can: execute secondary command buffers 298 during the query operation. 299 For a secondary command buffer to be executed while a query is active, it 300 must: set the pname:occlusionQueryEnable, pname:queryFlags, and/or 301 pname:pipelineStatistics members of slink:VkCommandBufferInheritanceInfo to 302 conservative values, as described in the <<commandbuffers-recording, Command 303 Buffer Recording>> section. 304 A query must: either begin and end inside the same subpass of a render pass 305 instance, or must: both begin and end outside of a render pass instance 306 (i.e. contain entire render pass instances). 307 308 ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 309 310 If queries are used while executing a render pass instance that has 311 multiview enabled, the query uses [eq]#N# consecutive query indices in the 312 query pool (starting at pname:query) where [eq]#N# is the number of bits set 313 in the view mask in the subpass the query is used in. 314 How the numerical results of the query are distributed among the queries is 315 implementation-dependent. 316 For example, some implementations may: write each view's results to a 317 distinct query, while other implementations may: write the total result to 318 the first query and write zero to the other queries. 319 However, the sum of the results in all the queries must: accurately reflect 320 the total result of the query summed over all views. 321 Applications can: sum the results from all the queries to compute the total 322 result. 323 324 Queries used with multiview rendering must: not span subpasses, i.e. they 325 must: begin and end in the same subpass. 326 327 endif::VK_VERSION_1_1,VK_KHR_multiview[] 328 329 [open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos'] 330 -- 331 :refpage: vkCmdBeginQuery 332 333 To begin a query, call: 334 335 include::{generated}/api/protos/vkCmdBeginQuery.txt[] 336 337 * pname:commandBuffer is the command buffer into which this command will 338 be recorded. 339 * pname:queryPool is the query pool that will manage the results of the 340 query. 341 * pname:query is the query index within the query pool that will contain 342 the results. 343 * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying 344 constraints on the types of queries that can: be performed. 345 346 If the pname:queryType of the pool is ename:VK_QUERY_TYPE_OCCLUSION and 347 pname:flags contains ename:VK_QUERY_CONTROL_PRECISE_BIT, an implementation 348 must: return a result that matches the actual number of samples passed. 349 This is described in more detail in <<queries-occlusion,Occlusion Queries>>. 350 351 [[queries-operation-active]] 352 After beginning a query, that query is considered _active_ within the 353 command buffer it was called in until that same query is ended. 354 Queries active in a primary command buffer when secondary command buffers 355 are executed are considered active for those secondary command buffers. 356 357 .Valid Usage 358 **** 359 include::{chapters}/commonvalidity/query_begin_common.txt[] 360 ifdef::VK_EXT_transform_feedback[] 361 * [[VUID-vkCmdBeginQuery-queryType-02327]] 362 If the pname:queryType used to create pname:queryPool was 363 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the 364 sname:VkCommandPool that pname:commandBuffer was allocated from must: 365 support graphics operations 366 * [[VUID-vkCmdBeginQuery-queryType-02328]] 367 If the pname:queryType used to create pname:queryPool was 368 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then 369 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries 370 must: be supported 371 endif::VK_EXT_transform_feedback[] 372 **** 373 374 include::{generated}/validity/protos/vkCmdBeginQuery.txt[] 375 -- 376 377 ifdef::VK_EXT_transform_feedback[] 378 379 [open,refpage='vkCmdBeginQueryIndexedEXT',desc='Begin an indexed query',type='protos'] 380 -- 381 :refpage: vkCmdBeginQueryIndexedEXT 382 383 To begin an indexed query, call: 384 385 include::{generated}/api/protos/vkCmdBeginQueryIndexedEXT.txt[] 386 387 * pname:commandBuffer is the command buffer into which this command will 388 be recorded. 389 * pname:queryPool is the query pool that will manage the results of the 390 query. 391 * pname:query is the query index within the query pool that will contain 392 the results. 393 * pname:flags is a bitmask of elink:VkQueryControlFlagBits specifying 394 constraints on the types of queries that can: be performed. 395 * pname:index is the query type specific index. 396 When the query type is ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT 397 the index represents the vertex stream. 398 399 The fname:vkCmdBeginQueryIndexedEXT command operates the same as the 400 flink:vkCmdBeginQuery command, except that it also accepts a query type 401 specific pname:index parameter. 402 403 .Valid Usage 404 **** 405 include::{chapters}/commonvalidity/query_begin_common.txt[] 406 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02338]] 407 If the pname:queryType used to create pname:queryPool was 408 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the 409 sname:VkCommandPool that pname:commandBuffer was allocated from must: 410 support graphics operations 411 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02339]] 412 If the pname:queryType used to create pname:queryPool was 413 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index 414 parameter must: be less than 415 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 416 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02340]] 417 If the pname:queryType used to create pname:queryPool was not 418 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index must: 419 be zero 420 * [[VUID-vkCmdBeginQueryIndexedEXT-queryType-02341]] 421 If the pname:queryType used to create pname:queryPool was 422 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then 423 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackQueries 424 must: be supported 425 **** 426 427 include::{generated}/validity/protos/vkCmdBeginQueryIndexedEXT.txt[] 428 -- 429 endif::VK_EXT_transform_feedback[] 430 431 432 [open,refpage='VkQueryControlFlagBits',desc='Bitmask specifying constraints on a query',type='enums'] 433 -- 434 435 Bits which can: be set in flink:vkCmdBeginQuery::pname:flags, specifying 436 constraints on the types of queries that can: be performed, are: 437 438 include::{generated}/api/enums/VkQueryControlFlagBits.txt[] 439 440 * ename:VK_QUERY_CONTROL_PRECISE_BIT specifies the precision of 441 <<queries-occlusion, occlusion queries>>. 442 443 -- 444 445 [open,refpage='VkQueryControlFlags',desc='Bitmask of VkQueryControlFlagBits',type='flags'] 446 -- 447 include::{generated}/api/flags/VkQueryControlFlags.txt[] 448 449 tname:VkQueryControlFlags is a bitmask type for setting a mask of zero or 450 more elink:VkQueryControlFlagBits. 451 -- 452 453 [open,refpage='vkCmdEndQuery',desc='Ends a query',type='protos'] 454 -- 455 456 To end a query after the set of desired draw or dispatch commands is 457 executed, call: 458 459 include::{generated}/api/protos/vkCmdEndQuery.txt[] 460 461 * pname:commandBuffer is the command buffer into which this command will 462 be recorded. 463 * pname:queryPool is the query pool that is managing the results of the 464 query. 465 * pname:query is the query index within the query pool where the result is 466 stored. 467 468 [[queries-operation-finished]] 469 As queries operate asynchronously, ending a query does not immediately set 470 the query's status to available. 471 A query is considered _finished_ when the final results of the query are 472 ready to be retrieved by flink:vkGetQueryPoolResults and 473 flink:vkCmdCopyQueryPoolResults, and this is when the query's status is set 474 to available. 475 476 Once a query is ended the query must: finish in finite time, unless the 477 state of the query is changed using other commands, e.g. by issuing a reset 478 of the query. 479 480 .Valid Usage 481 **** 482 * [[VUID-vkCmdEndQuery-None-01923]] 483 All queries used by the command must: be 484 <<queries-operation-active,active>> 485 * [[VUID-vkCmdEndQuery-query-00810]] 486 pname:query must: be less than the number of queries in pname:queryPool 487 ifdef::VK_VERSION_1_1[] 488 * [[VUID-vkCmdEndQuery-commandBuffer-01886]] 489 pname:commandBuffer must: not be a protected command buffer 490 endif::VK_VERSION_1_1[] 491 ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 492 * [[VUID-vkCmdEndQuery-query-00812]] 493 If fname:vkCmdEndQuery is called within a render pass instance, the sum 494 of pname:query and the number of bits set in the current subpass's view 495 mask must: be less than or equal to the number of queries in 496 pname:queryPool 497 endif::VK_VERSION_1_1,VK_KHR_multiview[] 498 **** 499 500 include::{generated}/validity/protos/vkCmdEndQuery.txt[] 501 -- 502 503 ifdef::VK_EXT_transform_feedback[] 504 [open,refpage='vkCmdEndQueryIndexedEXT',desc='Ends a query',type='protos'] 505 -- 506 507 To end an indexed query after the set of desired draw or dispatch commands 508 is recorded, call: 509 510 include::{generated}/api/protos/vkCmdEndQueryIndexedEXT.txt[] 511 512 * pname:commandBuffer is the command buffer into which this command will 513 be recorded. 514 * pname:queryPool is the query pool that is managing the results of the 515 query. 516 * pname:query is the query index within the query pool where the result is 517 stored. 518 * pname:index is the query type specific index. 519 520 The fname:vkCmdEndQueryIndexedEXT command operates the same as the 521 flink:vkCmdEndQuery command, except that it also accepts a query type 522 specific pname:index parameter. 523 524 .Valid Usage 525 **** 526 * [[VUID-vkCmdEndQueryIndexedEXT-None-02342]] 527 All queries used by the command must: be 528 <<queries-operation-active,active>> 529 * [[VUID-vkCmdEndQueryIndexedEXT-query-02343]] 530 pname:query must: be less than the number of queries in pname:queryPool 531 ifdef::VK_VERSION_1_1[] 532 * [[VUID-vkCmdEndQueryIndexedEXT-commandBuffer-02344]] 533 pname:commandBuffer must: not be a protected command buffer 534 endif::VK_VERSION_1_1[] 535 ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 536 * [[VUID-vkCmdEndQueryIndexedEXT-query-02345]] 537 If fname:vkCmdEndQueryIndexedEXT is called within a render pass 538 instance, the sum of pname:query and the number of bits set in the 539 current subpass's view mask must: be less than or equal to the number of 540 queries in pname:queryPool 541 endif::VK_VERSION_1_1,VK_KHR_multiview[] 542 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02346]] 543 If the pname:queryType used to create pname:queryPool was 544 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index 545 parameter must: be less than 546 sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams 547 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02347]] 548 If the pname:queryType used to create pname:queryPool was not 549 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the pname:index must: 550 be zero 551 * [[VUID-vkCmdEndQueryIndexedEXT-queryType-02723]] 552 If the pname:queryType used to create pname:queryPool was 553 ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT pname:index must: 554 equal the pname:index used to begin the query 555 556 **** 557 558 include::{generated}/validity/protos/vkCmdEndQueryIndexedEXT.txt[] 559 -- 560 endif::VK_EXT_transform_feedback[] 561 562 [[queries-operation-memorylayout]] 563 An application can: retrieve results either by requesting they be written 564 into application-provided memory, or by requesting they be copied into a 565 sname:VkBuffer. 566 In either case, the layout in memory is defined as follows: 567 568 * The first query's result is written starting at the first byte requested 569 by the command, and each subsequent query's result begins pname:stride 570 bytes later. 571 * Each query's result is a tightly packed array of unsigned integers, 572 either 32- or 64-bits as requested by the command, storing the numerical 573 results and, if requested, the availability status. 574 * If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, the final 575 element of each query's result is an integer indicating whether the 576 query's result is available, with any non-zero value indicating that it 577 is available. 578 * Occlusion queries write one integer value - the number of samples 579 passed. 580 Pipeline statistics queries write one integer value for each bit that is 581 enabled in the pname:pipelineStatistics when the pool is created, and 582 the statistics values are written in bit order starting from the least 583 significant bit. 584 Timestamps write one integer value. 585 ifdef::VK_EXT_transform_feedback[] 586 Transform feedback queries write two integers; the first integer is the 587 number of primitives successfully written to the corresponding transform 588 feedback buffer and the second is the number of primitives output to the 589 vertex stream, regardless of whether they were successfully captured or 590 not. 591 In other words, if the transform feedback buffer was sized too small for 592 the number of primitives output by the vertex stream, the first integer 593 represents the number of primitives actually written and the second is 594 the number that would have been written if all the transform feedback 595 buffers associated with that vertex stream were large enough. 596 endif::VK_EXT_transform_feedback[] 597 * If more than one query is retrieved and pname:stride is not at least as 598 large as the size of the array of integers corresponding to a single 599 query, the values written to memory are undefined:. 600 601 [open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos'] 602 -- 603 604 To retrieve status and results for a set of queries, call: 605 606 include::{generated}/api/protos/vkGetQueryPoolResults.txt[] 607 608 * pname:device is the logical device that owns the query pool. 609 * pname:queryPool is the query pool managing the queries containing the 610 desired results. 611 * pname:firstQuery is the initial query index. 612 * pname:queryCount is the number of queries to read. 613 * pname:dataSize is the size in bytes of the buffer pointed to by 614 pname:pData. 615 * pname:pData is a pointer to a user-allocated buffer where the results 616 will be written 617 * pname:stride is the stride in bytes between results for individual 618 queries within pname:pData. 619 * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how 620 and when results are returned. 621 622 The range of queries read is defined by [eq]#[pname:firstQuery, 623 pname:firstQuery {plus} pname:queryCount - 1]#. 624 For pipeline statistics queries, each query index in the pool contains one 625 integer value for each bit that is enabled in 626 slink:VkQueryPoolCreateInfo::pname pipelineStatistics when the pool is 627 created. 628 629 If no bits are set in pname:flags, and all requested queries are in the 630 available state, results are written as an array of 32-bit unsigned integer 631 values. 632 The behavior when not all queries are available, is described 633 <<queries-wait-bit-not-set, below>>. 634 635 If ename:VK_QUERY_RESULT_64_BIT is not set and the result overflows a 32-bit 636 value, the value may: either wrap or saturate. 637 Similarly, if ename:VK_QUERY_RESULT_64_BIT is set and the result overflows a 638 64-bit value, the value may: either wrap or saturate. 639 640 If ename:VK_QUERY_RESULT_WAIT_BIT is set, Vulkan will wait for each query to 641 be in the available state before retrieving the numerical results for that 642 query. 643 In this case, fname:vkGetQueryPoolResults is guaranteed to succeed and 644 return ename:VK_SUCCESS if the queries become available in a finite time 645 (i.e. if they have been issued and not reset). 646 If queries will never finish (e.g. due to being reset but not issued), then 647 fname:vkGetQueryPoolResults may: not return in finite time. 648 649 [[queries-wait-bit-not-set]] 650 If ename:VK_QUERY_RESULT_WAIT_BIT and ename:VK_QUERY_RESULT_PARTIAL_BIT are 651 both not set then no result values are written to pname:pData for queries 652 that are in the unavailable state at the time of the call, and 653 fname:vkGetQueryPoolResults returns ename:VK_NOT_READY. 654 However, availability state is still written to pname:pData for those 655 queries if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set. 656 657 [NOTE] 658 .Note 659 ==== 660 Applications must: take care to ensure that use of the 661 ename:VK_QUERY_RESULT_WAIT_BIT bit has the desired effect. 662 663 For example, if a query has been used previously and a command buffer 664 records the commands fname:vkCmdResetQueryPool, fname:vkCmdBeginQuery, and 665 fname:vkCmdEndQuery for that query, then the query will remain in the 666 available state until 667 ifdef::VK_EXT_host_query_reset[] 668 fname:vkResetQueryPoolEXT is called or 669 endif::VK_EXT_host_query_reset[] 670 the fname:vkCmdResetQueryPool command executes on a queue. 671 Applications can: use fences or events to ensure that a query has already 672 been reset before checking for its results or availability status. 673 Otherwise, a stale value could be returned from a previous use of the query. 674 675 The above also applies when ename:VK_QUERY_RESULT_WAIT_BIT is used in 676 combination with ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT. 677 In this case, the returned availability status may: reflect the result of a 678 previous use of the query unless 679 ifdef::VK_EXT_host_query_reset[] 680 fname:vkResetQueryPoolEXT is called or 681 endif::VK_EXT_host_query_reset[] 682 the fname:vkCmdResetQueryPool command has been executed since the last use 683 of the query. 684 ==== 685 686 [NOTE] 687 .Note 688 ==== 689 Applications can: double-buffer query pool usage, with a pool per frame, and 690 reset queries at the end of the frame in which they are read. 691 ==== 692 693 If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT 694 is not set, and the query's status is unavailable, an intermediate result 695 value between zero and the final result value is written to pname:pData for 696 that query. 697 698 ename:VK_QUERY_RESULT_PARTIAL_BIT must: not be used if the pool's 699 pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP. 700 701 If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, the final integer 702 value written for each query is non-zero if the query's status was available 703 or zero if the status was unavailable. 704 When ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, implementations 705 must: guarantee that if they return a non-zero availability value then the 706 numerical results must: be valid, assuming the results are not reset by a 707 subsequent command. 708 709 [NOTE] 710 .Note 711 ==== 712 Satisfying this guarantee may: require careful ordering by the application, 713 e.g. to read the availability status before reading the results. 714 ==== 715 716 .Valid Usage 717 **** 718 * [[VUID-vkGetQueryPoolResults-firstQuery-00813]] 719 pname:firstQuery must: be less than the number of queries in 720 pname:queryPool 721 * [[VUID-vkGetQueryPoolResults-flags-00814]] 722 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags then 723 pname:pData and pname:stride must: be multiples of `4` 724 * [[VUID-vkGetQueryPoolResults-flags-00815]] 725 If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then pname:pData 726 and pname:stride must: be multiples of `8` 727 * [[VUID-vkGetQueryPoolResults-firstQuery-00816]] 728 The sum of pname:firstQuery and pname:queryCount must: be less than or 729 equal to the number of queries in pname:queryPool 730 * [[VUID-vkGetQueryPoolResults-dataSize-00817]] 731 pname:dataSize must: be large enough to contain the result of each 732 query, as described <<queries-operation-memorylayout,here>> 733 * [[VUID-vkGetQueryPoolResults-queryType-00818]] 734 If the pname:queryType used to create pname:queryPool was 735 ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain 736 ename:VK_QUERY_RESULT_PARTIAL_BIT 737 **** 738 739 include::{generated}/validity/protos/vkGetQueryPoolResults.txt[] 740 -- 741 742 [open,refpage='VkQueryResultFlagBits',desc='Bitmask specifying how and when query results are returned',type='enums'] 743 -- 744 745 Bits which can: be set in flink:vkGetQueryPoolResults::pname:flags and 746 flink:vkCmdCopyQueryPoolResults::pname:flags, specifying how and when 747 results are returned, are: 748 749 include::{generated}/api/enums/VkQueryResultFlagBits.txt[] 750 751 * ename:VK_QUERY_RESULT_64_BIT specifies the results will be written as an 752 array of 64-bit unsigned integer values. 753 If this bit is not set, the results will be written as an array of 754 32-bit unsigned integer values. 755 * ename:VK_QUERY_RESULT_WAIT_BIT specifies that Vulkan will wait for each 756 query's status to become available before retrieving its results. 757 * ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT specifies that the 758 availability status accompanies the results. 759 * ename:VK_QUERY_RESULT_PARTIAL_BIT specifies that returning partial 760 results is acceptable. 761 762 -- 763 764 [open,refpage='VkQueryResultFlags',desc='Bitmask of VkQueryResultFlagBits',type='flags'] 765 -- 766 include::{generated}/api/flags/VkQueryResultFlags.txt[] 767 768 tname:VkQueryResultFlags is a bitmask type for setting a mask of zero or 769 more elink:VkQueryResultFlagBits. 770 -- 771 772 [open,refpage='vkCmdCopyQueryPoolResults',desc='Copy the results of queries in a query pool to a buffer object',type='protos'] 773 -- 774 775 To copy query statuses and numerical results directly to buffer memory, 776 call: 777 778 include::{generated}/api/protos/vkCmdCopyQueryPoolResults.txt[] 779 780 * pname:commandBuffer is the command buffer into which this command will 781 be recorded. 782 * pname:queryPool is the query pool managing the queries containing the 783 desired results. 784 * pname:firstQuery is the initial query index. 785 * pname:queryCount is the number of queries. 786 pname:firstQuery and pname:queryCount together define a range of 787 queries. 788 * pname:dstBuffer is a slink:VkBuffer object that will receive the results 789 of the copy command. 790 * pname:dstOffset is an offset into pname:dstBuffer. 791 * pname:stride is the stride in bytes between results for individual 792 queries within pname:dstBuffer. 793 The required size of the backing memory for pname:dstBuffer is 794 determined as described above for flink:vkGetQueryPoolResults. 795 * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how 796 and when results are returned. 797 798 fname:vkCmdCopyQueryPoolResults is guaranteed to see the effect of previous 799 uses of fname:vkCmdResetQueryPool in the same queue, without any additional 800 synchronization. 801 Thus, the results will always reflect the most recent use of the query. 802 803 pname:flags has the same possible values described above for the pname:flags 804 parameter of flink:vkGetQueryPoolResults, but the different style of 805 execution causes some subtle behavioral differences. 806 Because fname:vkCmdCopyQueryPoolResults executes in order with respect to 807 other query commands, there is less ambiguity about which use of a query is 808 being requested. 809 810 If no bits are set in pname:flags, results for all requested queries in the 811 available state are written as 32-bit unsigned integer values, and nothing 812 is written for queries in the unavailable state. 813 814 If ename:VK_QUERY_RESULT_64_BIT is set, the results are written as an array 815 of 64-bit unsigned integer values as described for 816 flink:vkGetQueryPoolResults. 817 818 If ename:VK_QUERY_RESULT_WAIT_BIT is set, the implementation will wait for 819 each query's status to be in the available state before retrieving the 820 numerical results for that query. 821 This is guaranteed to reflect the most recent use of the query on the same 822 queue, assuming that the query is not being simultaneously used by other 823 queues. 824 If the query does not become available in a finite amount of time (e.g. due 825 to not issuing a query since the last reset), a ename:VK_ERROR_DEVICE_LOST 826 error may: occur. 827 828 Similarly, if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set and 829 ename:VK_QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to 830 reflect the most recent use of the query on the same queue, assuming that 831 the query is not being simultaneously used by other queues. 832 As with fname:vkGetQueryPoolResults, implementations must: guarantee that if 833 they return a non-zero availability value, then the numerical results are 834 valid. 835 836 If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT 837 is not set, and the query's status is unavailable, an intermediate result 838 value between zero and the final result value is written for that query. 839 840 ename:VK_QUERY_RESULT_PARTIAL_BIT must: not be used if the pool's 841 pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP. 842 843 fname:vkCmdCopyQueryPoolResults is considered to be a transfer operation, 844 and its writes to buffer memory must: be synchronized using 845 ename:VK_PIPELINE_STAGE_TRANSFER_BIT and ename:VK_ACCESS_TRANSFER_WRITE_BIT 846 before using the results. 847 848 .Valid Usage 849 **** 850 * [[VUID-vkCmdCopyQueryPoolResults-dstOffset-00819]] 851 pname:dstOffset must: be less than the size of pname:dstBuffer 852 * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00820]] 853 pname:firstQuery must: be less than the number of queries in 854 pname:queryPool 855 * [[VUID-vkCmdCopyQueryPoolResults-firstQuery-00821]] 856 The sum of pname:firstQuery and pname:queryCount must: be less than or 857 equal to the number of queries in pname:queryPool 858 * [[VUID-vkCmdCopyQueryPoolResults-flags-00822]] 859 If ename:VK_QUERY_RESULT_64_BIT is not set in pname:flags then 860 pname:dstOffset and pname:stride must: be multiples of `4` 861 * [[VUID-vkCmdCopyQueryPoolResults-flags-00823]] 862 If ename:VK_QUERY_RESULT_64_BIT is set in pname:flags then 863 pname:dstOffset and pname:stride must: be multiples of `8` 864 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00824]] 865 pname:dstBuffer must: have enough storage, from pname:dstOffset, to 866 contain the result of each query, as described 867 <<queries-operation-memorylayout,here>> 868 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00825]] 869 pname:dstBuffer must: have been created with 870 ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag 871 * [[VUID-vkCmdCopyQueryPoolResults-dstBuffer-00826]] 872 If pname:dstBuffer is non-sparse then it must: be bound completely and 873 contiguously to a single sname:VkDeviceMemory object 874 * [[VUID-vkCmdCopyQueryPoolResults-queryType-00827]] 875 If the pname:queryType used to create pname:queryPool was 876 ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain 877 ename:VK_QUERY_RESULT_PARTIAL_BIT 878 ifdef::VK_INTEL_performance_query[] 879 * [[VUID-vkCmdCopyQueryPoolResults-queryType-02734]] 880 flink:vkCmdCopyQueryPoolResults must: not be called if the 881 pname:queryType used to create pname:queryPool was 882 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL. 883 endif::VK_INTEL_performance_query[] 884 **** 885 886 include::{generated}/validity/protos/vkCmdCopyQueryPoolResults.txt[] 887 -- 888 889 890 [[queries-operation-undefined]] 891 Rendering operations such as clears, MSAA resolves, attachment load/store 892 operations, and blits may: count towards the results of queries. 893 This behavior is implementation-dependent and may: vary depending on the 894 path used within an implementation. 895 For example, some implementations have several types of clears, some of 896 which may: include vertices and some not. 897 898 899 [[queries-occlusion]] 900 == Occlusion Queries 901 902 Occlusion queries track the number of samples that pass the per-fragment 903 tests for a set of drawing commands. 904 As such, occlusion queries are only available on queue families supporting 905 graphics operations. 906 The application can: then use these results to inform future rendering 907 decisions. 908 An occlusion query is begun and ended by calling fname:vkCmdBeginQuery and 909 fname:vkCmdEndQuery, respectively. 910 When an occlusion query begins, the count of passing samples always starts 911 at zero. 912 For each drawing command, the count is incremented as described in 913 <<fragops-samplecount,Sample Counting>>. 914 If pname:flags does not contain ename:VK_QUERY_CONTROL_PRECISE_BIT an 915 implementation may: generate any non-zero result value for the query if the 916 count of passing samples is non-zero. 917 918 [NOTE] 919 .Note 920 ==== 921 Not setting ename:VK_QUERY_CONTROL_PRECISE_BIT mode may: be more efficient 922 on some implementations, and should: be used where it is sufficient to know 923 a boolean result on whether any samples passed the per-fragment tests. 924 In this case, some implementations may: only return zero or one, indifferent 925 to the actual number of samples passing the per-fragment tests. 926 ==== 927 928 When an occlusion query finishes, the result for that query is marked as 929 available. 930 The application can: then either copy the result to a buffer (via 931 fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 932 fname:vkGetQueryPoolResults). 933 934 [NOTE] 935 .Note 936 ==== 937 If occluding geometry is not drawn first, samples can: pass the depth test, 938 but still not be visible in a final image. 939 ==== 940 941 942 [[queries-pipestats]] 943 == Pipeline Statistics Queries 944 945 Pipeline statistics queries allow the application to sample a specified set 946 of sname:VkPipeline counters. 947 These counters are accumulated by Vulkan for a set of either draw or 948 dispatch commands while a pipeline statistics query is active. 949 As such, pipeline statistics queries are available on queue families 950 supporting either graphics or compute operations. 951 Further, the availability of pipeline statistics queries is indicated by the 952 pname:pipelineStatisticsQuery member of the sname:VkPhysicalDeviceFeatures 953 object (see fname:vkGetPhysicalDeviceFeatures and fname:vkCreateDevice for 954 detecting and requesting this query type on a sname:VkDevice). 955 956 A pipeline statistics query is begun and ended by calling 957 fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively. 958 When a pipeline statistics query begins, all statistics counters are set to 959 zero. 960 While the query is active, the pipeline type determines which set of 961 statistics are available, but these must: be configured on the query pool 962 when it is created. 963 If a statistic counter is issued on a command buffer that does not support 964 the corresponding operation, the value of that counter is undefined: after 965 the query has finished. 966 At least one statistic counter relevant to the operations supported on the 967 recording command buffer must: be enabled. 968 969 [open,refpage='VkQueryPipelineStatisticFlagBits',desc='Bitmask specifying queried pipeline statistics',type='enums'] 970 -- 971 972 Bits which can: be set to individually enable pipeline statistics counters 973 for query pools with slink:VkQueryPoolCreateInfo::pname:pipelineStatistics, 974 and for secondary command buffers with 975 slink:VkCommandBufferInheritanceInfo::pname:pipelineStatistics, are: 976 977 include::{generated}/api/enums/VkQueryPipelineStatisticFlagBits.txt[] 978 979 * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT specifies 980 that queries managed by the pool will count the number of vertices 981 processed by the <<drawing,input assembly>> stage. 982 Vertices corresponding to incomplete primitives may: contribute to the 983 count. 984 * ename:VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT 985 specifies that queries managed by the pool will count the number of 986 primitives processed by the <<drawing,input assembly>> stage. 987 If primitive restart is enabled, restarting the primitive topology has 988 no effect on the count. 989 Incomplete primitives may: be counted. 990 * ename:VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT 991 specifies that queries managed by the pool will count the number of 992 vertex shader invocations. 993 This counter's value is incremented each time a vertex shader is 994 <<shaders-vertex-execution,invoked>>. 995 * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT 996 specifies that queries managed by the pool will count the number of 997 geometry shader invocations. 998 This counter's value is incremented each time a geometry shader is 999 <<shaders-geometry-execution,invoked>>. 1000 In the case of <<geometry-invocations,instanced geometry shaders>>, the 1001 geometry shader invocations count is incremented for each separate 1002 instanced invocation. 1003 * ename:VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT 1004 specifies that queries managed by the pool will count the number of 1005 primitives generated by geometry shader invocations. 1006 The counter's value is incremented each time the geometry shader emits a 1007 primitive. 1008 Restarting primitive topology using the SPIR-V instructions 1009 code:OpEndPrimitive or code:OpEndStreamPrimitive has no effect on the 1010 geometry shader output primitives count. 1011 * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT specifies 1012 that queries managed by the pool will count the number of primitives 1013 processed by the <<vertexpostproc-clipping,Primitive Clipping>> stage of 1014 the pipeline. 1015 The counter's value is incremented each time a primitive reaches the 1016 primitive clipping stage. 1017 * ename:VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT specifies that 1018 queries managed by the pool will count the number of primitives output 1019 by the <<vertexpostproc-clipping,Primitive Clipping>> stage of the 1020 pipeline. 1021 The counter's value is incremented each time a primitive passes the 1022 primitive clipping stage. 1023 The actual number of primitives output by the primitive clipping stage 1024 for a particular input primitive is implementation-dependent but must: 1025 satisfy the following conditions: 1026 ** If at least one vertex of the input primitive lies inside the clipping 1027 volume, the counter is incremented by one or more. 1028 ** Otherwise, the counter is incremented by zero or more. 1029 * ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT 1030 specifies that queries managed by the pool will count the number of 1031 fragment shader invocations. 1032 The counter's value is incremented each time the fragment shader is 1033 <<shaders-fragment-execution,invoked>>. 1034 * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT 1035 specifies that queries managed by the pool will count the number of 1036 patches processed by the tessellation control shader. 1037 The counter's value is incremented once for each patch for which a 1038 tessellation control shader is 1039 <<shaders-tessellation-control-execution,invoked>>. 1040 * ename:VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT 1041 specifies that queries managed by the pool will count the number of 1042 invocations of the tessellation evaluation shader. 1043 The counter's value is incremented each time the tessellation evaluation 1044 shader is <<shaders-tessellation-evaluation-execution,invoked>>. 1045 * ename:VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT 1046 specifies that queries managed by the pool will count the number of 1047 compute shader invocations. 1048 The counter's value is incremented every time the compute shader is 1049 invoked. 1050 Implementations may: skip the execution of certain compute shader 1051 invocations or execute additional compute shader invocations for 1052 implementation-dependent reasons as long as the results of rendering 1053 otherwise remain unchanged. 1054 1055 These values are intended to measure relative statistics on one 1056 implementation. 1057 Various device architectures will count these values differently. 1058 Any or all counters may: be affected by the issues described in 1059 <<queries-operation-undefined,Query Operation>>. 1060 1061 [NOTE] 1062 .Note 1063 ==== 1064 For example, tile-based rendering devices may: need to replay the scene 1065 multiple times, affecting some of the counts. 1066 ==== 1067 1068 If a pipeline has pname:rasterizerDiscardEnable enabled, implementations 1069 may: discard primitives after the final vertex processing stage. 1070 As a result, if pname:rasterizerDiscardEnable is enabled, the clipping input 1071 and output primitives counters may: not be incremented. 1072 1073 When a pipeline statistics query finishes, the result for that query is 1074 marked as available. 1075 The application can: copy the result to a buffer (via 1076 fname:vkCmdCopyQueryPoolResults), or request it be put into host memory (via 1077 fname:vkGetQueryPoolResults). 1078 1079 -- 1080 1081 [open,refpage='VkQueryPipelineStatisticFlags',desc='Bitmask of VkQueryPipelineStatisticFlagBits',type='flags'] 1082 -- 1083 include::{generated}/api/flags/VkQueryPipelineStatisticFlags.txt[] 1084 1085 tname:VkQueryPipelineStatisticFlags is a bitmask type for setting a mask of 1086 zero or more elink:VkQueryPipelineStatisticFlagBits. 1087 -- 1088 1089 1090 [[queries-timestamps]] 1091 == Timestamp Queries 1092 1093 _Timestamps_ provide applications with a mechanism for timing the execution 1094 of commands. 1095 A timestamp is an integer value generated by the sname:VkPhysicalDevice. 1096 Unlike other queries, timestamps do not operate over a range, and so do not 1097 use flink:vkCmdBeginQuery or flink:vkCmdEndQuery. 1098 The mechanism is built around a set of commands that allow the application 1099 to tell the sname:VkPhysicalDevice to write timestamp values to a 1100 <<queries-pools,query pool>> and then either read timestamp values on the 1101 host (using flink:vkGetQueryPoolResults) or copy timestamp values to a 1102 sname:VkBuffer (using flink:vkCmdCopyQueryPoolResults). 1103 The application can: then compute differences between timestamps to 1104 determine execution time. 1105 1106 The number of valid bits in a timestamp value is determined by the 1107 sname:VkQueueFamilyProperties::pname:timestampValidBits property of the 1108 queue on which the timestamp is written. 1109 Timestamps are supported on any queue which reports a non-zero value for 1110 pname:timestampValidBits via flink:vkGetPhysicalDeviceQueueFamilyProperties. 1111 If the <<limits-timestampComputeAndGraphics, 1112 pname:timestampComputeAndGraphics>> limit is ename:VK_TRUE, timestamps are 1113 supported by every queue family that supports either graphics or compute 1114 operations (see slink:VkQueueFamilyProperties). 1115 1116 The number of nanoseconds it takes for a timestamp value to be incremented 1117 by 1 can: be obtained from 1118 sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to 1119 fname:vkGetPhysicalDeviceProperties. 1120 1121 [open,refpage='vkCmdWriteTimestamp',desc='Write a device timestamp into a query object',type='protos'] 1122 -- 1123 1124 To request a timestamp, call: 1125 1126 include::{generated}/api/protos/vkCmdWriteTimestamp.txt[] 1127 1128 * pname:commandBuffer is the command buffer into which the command will be 1129 recorded. 1130 * pname:pipelineStage is one of the elink:VkPipelineStageFlagBits, 1131 specifying a stage of the pipeline. 1132 * pname:queryPool is the query pool that will manage the timestamp. 1133 * pname:query is the query within the query pool that will contain the 1134 timestamp. 1135 1136 fname:vkCmdWriteTimestamp latches the value of the timer when all previous 1137 commands have completed executing as far as the specified pipeline stage, 1138 and writes the timestamp value to memory. 1139 When the timestamp value is written, the availability status of the query is 1140 set to available. 1141 1142 [NOTE] 1143 .Note 1144 ==== 1145 If an implementation is unable to detect completion and latch the timer at 1146 any specific stage of the pipeline, it may: instead do so at any logically 1147 later stage. 1148 ==== 1149 1150 flink:vkCmdCopyQueryPoolResults can: then be called to copy the timestamp 1151 value from the query pool into buffer memory, with ordering and 1152 synchronization behavior equivalent to how other queries operate. 1153 Timestamp values can: also be retrieved from the query pool using 1154 flink:vkGetQueryPoolResults. 1155 As with other queries, the query must: be reset using 1156 flink:vkCmdResetQueryPool 1157 ifdef::VK_EXT_host_query_reset[] 1158 or flink:vkResetQueryPoolEXT 1159 endif::VK_EXT_host_query_reset[] 1160 before requesting the timestamp value be written to it. 1161 1162 While fname:vkCmdWriteTimestamp can: be called inside or outside of a render 1163 pass instance, flink:vkCmdCopyQueryPoolResults must: only be called outside 1164 of a render pass instance. 1165 1166 Timestamps may: only be meaningfully compared if they are written by 1167 commands submitted to the same queue. 1168 1169 [NOTE] 1170 .Note 1171 ==== 1172 An example of such a comparison is determining the execution time of a 1173 sequence of commands. 1174 ==== 1175 1176 ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1177 1178 If fname:vkCmdWriteTimestamp is called while executing a render pass 1179 instance that has multiview enabled, the timestamp uses [eq]#N# consecutive 1180 query indices in the query pool (starting at pname:query) where [eq]#N# is 1181 the number of bits set in the view mask of the subpass the command is 1182 executed in. 1183 The resulting query values are determined by an implementation-dependent 1184 choice of one of the following behaviors: 1185 1186 * The first query is a timestamp value and (if more than one bit is set in 1187 the view mask) zero is written to the remaining queries. 1188 If two timestamps are written in the same subpass, the sum of the 1189 execution time of all views between those commands is the difference 1190 between the first query written by each command. 1191 * All [eq]#N# queries are timestamp values. 1192 If two timestamps are written in the same subpass, the sum of the 1193 execution time of all views between those commands is the sum of the 1194 difference between corresponding queries written by each command. 1195 The difference between corresponding queries may: be the execution time 1196 of a single view. 1197 1198 In either case, the application can: sum the differences between all [eq]#N# 1199 queries to determine the total execution time. 1200 1201 endif::VK_VERSION_1_1,VK_KHR_multiview[] 1202 1203 .Valid Usage 1204 **** 1205 * [[VUID-vkCmdWriteTimestamp-queryPool-01416]] 1206 pname:queryPool must: have been created with a pname:queryType of 1207 ename:VK_QUERY_TYPE_TIMESTAMP 1208 * [[VUID-vkCmdWriteTimestamp-queryPool-00828]] 1209 The query identified by pname:queryPool and pname:query must: be 1210 _unavailable_ 1211 * [[VUID-vkCmdWriteTimestamp-timestampValidBits-00829]] 1212 The command pool's queue family must: support a non-zero 1213 pname:timestampValidBits 1214 ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1215 * [[VUID-vkCmdWriteTimestamp-None-00830]] 1216 All queries used by the command must: be unavailable 1217 * [[VUID-vkCmdWriteTimestamp-query-00831]] 1218 If fname:vkCmdWriteTimestamp is called within a render pass instance, 1219 the sum of pname:query and the number of bits set in the current 1220 subpass's view mask must: be less than or equal to the number of queries 1221 in pname:queryPool 1222 endif::VK_VERSION_1_1,VK_KHR_multiview[] 1223 **** 1224 1225 include::{generated}/validity/protos/vkCmdWriteTimestamp.txt[] 1226 -- 1227 1228 ifdef::VK_EXT_transform_feedback[] 1229 1230 [[queries-transform-feedback]] 1231 == Transform Feedback Queries 1232 1233 Transform feedback queries track the number of primitives attempted to be 1234 written and actually written, by the vertex stream being captured, to a 1235 transform feedback buffer. 1236 This query is updated during draw commands while transform feedback is 1237 active. 1238 The number of primitives actually written will be less than the number 1239 attempted to be written if the bound transform feedback buffer size was too 1240 small for the number of primitives actually drawn. 1241 Primitives are not written beyond the bound range of the transform feedback 1242 buffer. 1243 A transform feedback query is begun and ended by calling 1244 fname:vkCmdBeginQuery and fname:vkCmdEndQuery, respectively to query for 1245 vertex stream zero. 1246 fname:vkCmdBeginQueryIndexedEXT and fname:vkCmdEndQueryIndexedEXT can: be 1247 used to begin and end transform feedback queries for any supported vertex 1248 stream. 1249 When a transform feedback query begins, the count of primitives written and 1250 primitives needed starts from zero. 1251 For each drawing command, the count is incremented as vertex attribute 1252 outputs are captured to the transform feedback buffers while transform 1253 feedback is active. 1254 1255 When a transform feedback query finishes, the result for that query is 1256 marked as available. 1257 The application can: then either copy the result to a buffer (via 1258 fname:vkCmdCopyQueryPoolResults) or request it be put into host memory (via 1259 fname:vkGetQueryPoolResults). 1260 1261 1262 endif::VK_EXT_transform_feedback[] 1263 1264 ifdef::VK_INTEL_performance_query[] 1265 include::VK_INTEL_performance_query/queries.txt[] 1266 endif::VK_INTEL_performance_query[]