1// Copyright 2019-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[queries-performance]]
6== Performance Queries
7
8_Performance queries_ provide applications with a mechanism for getting
9performance counter information about the execution of command buffers,
10render passes, and commands.
11
12Each queue family advertises the performance counters that can: be queried
13on a queue of that family via a call to
14flink:vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR.
15Implementations may: limit access to performance counters based on platform
16requirements or only to specialized drivers for development purposes.
17
18[NOTE]
19.Note
20====
21This may include no performance counters being enumerated, or a reduced set.
22Please refer to platform-specific documentation for guidance on any such
23restrictions.
24====
25
26Performance queries use the existing flink:vkCmdBeginQuery and
27flink:vkCmdEndQuery to control what command buffers, render passes, or
28commands to get performance information for.
29
30Implementations may: require multiple passes where the command buffer,
31render passes, or commands being recorded are the same and are executed on
32the same queue to record performance counter data.
33This is achieved by submitting the same batch and providing a
34slink:VkPerformanceQuerySubmitInfoKHR structure containing a counter pass
35index.
36The number of passes required for a given performance query pool can: be
37queried via a call to
38flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR.
39
40[NOTE]
41.Note
42====
43Command buffers created with
44ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT must: not be re-submitted.
45Changing command buffer usage bits may: affect performance.
46To avoid this, the application should: re-record any command buffers with
47the ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT when multiple counter
48passes are required.
49====
50
51Performance counter results from a performance query pool can: be obtained
52with the command flink:vkGetQueryPoolResults.
53
54[open,refpage='VkPerformanceCounterResultKHR',desc='Union containing a performance counter result',type='structs']
55--
56The sname:VkPerformanceCounterResultKHR union is defined as:
57
58include::{generated}/api/structs/VkPerformanceCounterResultKHR.adoc[]
59
60  * pname:int32 is a 32-bit signed integer value.
61  * pname:int64 is a 64-bit signed integer value.
62  * pname:uint32 is a 32-bit unsigned integer value.
63  * pname:uint64 is a 64-bit unsigned integer value.
64  * pname:float32 is a 32-bit floating-point value.
65  * pname:float64 is a 64-bit floating-point value.
66
67Performance query results are returned in an array of
68sname:VkPerformanceCounterResultKHR unions containing the data associated
69with each counter in the query, stored in the same order as the counters
70supplied in pname:pCounterIndices when creating the performance query.
71slink:VkPerformanceCounterKHR::pname:storage specifies how to parse the
72counter data.
73
74include::{generated}/validity/structs/VkPerformanceCounterResultKHR.adoc[]
75--
76
77
78[[profiling-lock]]
79=== Profiling Lock
80
81[open,refpage='vkAcquireProfilingLockKHR',desc='Acquires the profiling lock',type='protos']
82--
83:refpage: vkAcquireProfilingLockKHR
84
85To record and submit a command buffer containing a performance query pool
86the profiling lock must: be held.
87The profiling lock must: be acquired prior to any call to
88flink:vkBeginCommandBuffer that will be using a performance query pool.
89The profiling lock must: be held while any command buffer containing a
90performance query pool is in the _recording_, _executable_, or _pending
91state_.
92To acquire the profiling lock, call:
93
94include::{generated}/api/protos/vkAcquireProfilingLockKHR.adoc[]
95
96  * pname:device is the logical device to profile.
97  * pname:pInfo is a pointer to a sname:VkAcquireProfilingLockInfoKHR
98    structure containing information about how the profiling is to be
99    acquired.
100
101Implementations may: allow multiple actors to hold the profiling lock
102concurrently.
103
104include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]
105
106include::{generated}/validity/protos/vkAcquireProfilingLockKHR.adoc[]
107--
108
109[open,refpage='VkAcquireProfilingLockInfoKHR',desc='Structure specifying parameters to acquire the profiling lock',type='structs']
110--
111The sname:VkAcquireProfilingLockInfoKHR structure is defined as:
112
113include::{generated}/api/structs/VkAcquireProfilingLockInfoKHR.adoc[]
114
115  * pname:sType is a elink:VkStructureType value identifying this structure.
116  * pname:pNext is `NULL` or a pointer to a structure extending this
117    structure.
118  * pname:flags is reserved for future use.
119  * pname:timeout indicates how long the function waits, in nanoseconds, if
120    the profiling lock is not available.
121
122include::{generated}/validity/structs/VkAcquireProfilingLockInfoKHR.adoc[]
123
124If pname:timeout is 0, fname:vkAcquireProfilingLockKHR will not block while
125attempting to acquire the profiling lock.
126If pname:timeout is code:UINT64_MAX, the function will not return until the
127profiling lock was acquired.
128--
129
130[open,refpage='VkAcquireProfilingLockFlagBitsKHR',desc='Reserved for future use',type='enums']
131--
132include::{generated}/api/enums/VkAcquireProfilingLockFlagBitsKHR.adoc[]
133--
134
135[open,refpage='VkAcquireProfilingLockFlagsKHR',desc='Reserved for future use',type='flags']
136--
137include::{generated}/api/flags/VkAcquireProfilingLockFlagsKHR.adoc[]
138
139tlink:VkAcquireProfilingLockFlagsKHR is a bitmask type for setting a mask,
140but is currently reserved for future use.
141--
142
143[open,refpage='vkReleaseProfilingLockKHR',desc='Releases the profiling lock',type='protos']
144--
145To release the profiling lock, call:
146
147include::{generated}/api/protos/vkReleaseProfilingLockKHR.adoc[]
148
149  * pname:device is the logical device to cease profiling on.
150
151.Valid Usage
152****
153  * [[VUID-vkReleaseProfilingLockKHR-device-03235]]
154    The profiling lock of pname:device must: have been held via a previous
155    successful call to flink:vkAcquireProfilingLockKHR
156****
157
158include::{generated}/validity/protos/vkReleaseProfilingLockKHR.adoc[]
159--
160