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