| // Copyright 2019-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[queries-performance]] |
| == Performance Queries |
| |
| _Performance queries_ provide applications with a mechanism for getting |
| performance counter information about the execution of command buffers, |
| render passes, and commands. |
| |
| Each queue family advertises the performance counters that can: be queried |
| on a queue of that family via a call to |
| flink:vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR. |
| Implementations may: limit access to performance counters based on platform |
| requirements or only to specialized drivers for development purposes. |
| |
| [NOTE] |
| .Note |
| ==== |
| This may include no performance counters being enumerated, or a reduced set. |
| Please refer to platform-specific documentation for guidance on any such |
| restrictions. |
| ==== |
| |
| Performance queries use the existing flink:vkCmdBeginQuery and |
| flink:vkCmdEndQuery to control what command buffers, render passes, or |
| commands to get performance information for. |
| |
| Implementations may: require multiple passes where the command buffer, |
| render passes, or commands being recorded are the same and are executed on |
| the same queue to record performance counter data. |
| This is achieved by submitting the same batch and providing a |
| slink:VkPerformanceQuerySubmitInfoKHR structure containing a counter pass |
| index. |
| The number of passes required for a given performance query pool can: be |
| queried via a call to |
| flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR. |
| |
| [NOTE] |
| .Note |
| ==== |
| Command buffers created with |
| ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT must: not be re-submitted. |
| Changing command buffer usage bits may: affect performance. |
| To avoid this, the application should: re-record any command buffers with |
| the ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT when multiple counter |
| passes are required. |
| ==== |
| |
| Performance counter results from a performance query pool can: be obtained |
| with the command flink:vkGetQueryPoolResults. |
| |
| [open,refpage='VkPerformanceCounterResultKHR',desc='Union containing a performance counter result',type='structs'] |
| -- |
| Performance query results are returned in an array of |
| sname:VkPerformanceCounterResultKHR unions containing the data associated |
| with each counter in the query, stored in the same order as the counters |
| supplied in pname:pCounterIndices when creating the performance query. |
| The slink:VkPerformanceCounterKHR::pname:unit enumeration specifies how to |
| parse the counter data. |
| |
| include::{generated}/api/structs/VkPerformanceCounterResultKHR.txt[] |
| -- |
| |
| |
| [[profiling-lock]] |
| === Profiling Lock |
| |
| [open,refpage='vkAcquireProfilingLockKHR',desc='Acquires the profiling lock',type='protos'] |
| -- |
| To record and submit a command buffer that contains a performance query pool |
| the profiling lock must: be held. |
| The profiling lock must: be acquired prior to any call to |
| flink:vkBeginCommandBuffer that will be using a performance query pool. |
| The profiling lock must: be held while any command buffer that contains a |
| performance query pool is in the _recording_, _executable_, or _pending |
| state_. |
| To acquire the profiling lock, call: |
| |
| include::{generated}/api/protos/vkAcquireProfilingLockKHR.txt[] |
| |
| * pname:device is the logical device to profile. |
| * pname:pInfo is a pointer to a sname:VkAcquireProfilingLockInfoKHR |
| structure which contains information about how the profiling is to be |
| acquired. |
| |
| Implementations may: allow multiple actors to hold the profiling lock |
| concurrently. |
| |
| include::{generated}/validity/protos/vkAcquireProfilingLockKHR.txt[] |
| -- |
| |
| [open,refpage='VkAcquireProfilingLockInfoKHR',desc='Structure specifying parameters to acquire the profiling lock',type='structs'] |
| -- |
| The sname:VkAcquireProfilingLockInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkAcquireProfilingLockInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * pname:timeout indicates how long the function waits, in nanoseconds, if |
| the profiling lock is not available. |
| |
| include::{generated}/validity/structs/VkAcquireProfilingLockInfoKHR.txt[] |
| |
| If pname:timeout is 0, fname:vkAcquireProfilingLockKHR will not block while |
| attempting to acquire the profling lock. |
| If pname:timeout is code:UINT64_MAX, the function will not return until the |
| profiling lock was acquired. |
| -- |
| |
| [open,refpage='VkAcquireProfilingLockFlagBitsKHR',desc='Reserved for future use',type='enums'] |
| -- |
| include::{generated}/api/enums/VkAcquireProfilingLockFlagBitsKHR.txt[] |
| -- |
| |
| [open,refpage='VkAcquireProfilingLockFlagsKHR',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkAcquireProfilingLockFlagsKHR.txt[] |
| |
| tlink:VkAcquireProfilingLockFlagsKHR is a bitmask type for setting a mask, |
| but is currently reserved for future use. |
| -- |
| |
| [open,refpage='vkReleaseProfilingLockKHR',desc='Releases the profiling lock',type='protos'] |
| -- |
| To release the profiling lock, call: |
| |
| include::{generated}/api/protos/vkReleaseProfilingLockKHR.txt[] |
| |
| * pname:device is the logical device to cease profiling on. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkReleaseProfilingLockKHR-device-03235]] |
| The profiling lock of pname:device must: have been held via a previous |
| successful call to flink:vkAcquireProfilingLockKHR |
| **** |
| |
| include::{generated}/validity/protos/vkReleaseProfilingLockKHR.txt[] |
| -- |
