Package org.lwjgl.vulkan

Class KHRPerformanceQuery

  • public class KHRPerformanceQuery
extends java.lang.Object
    The VK_KHR_performance_query extension adds a mechanism to allow querying of performance counters for use in applications and by profiling tools.

    Each queue family may expose counters that can be enabled on a queue of that family. We extend VkQueryType to add a new query type for performance queries, and chain a structure on VkQueryPoolCreateInfo to specify the performance queries to enable.

    Examples

    The following example shows how to find what performance counters a queue family supports, setup a query pool to record these performance counters, how to add the query pool to the command buffer to record information, and how to get the results from the query pool.

    
 // A previously created physical device
 VkPhysicalDevice physicalDevice;
 
 // One of the queue families our device supports
 uint32_t queueFamilyIndex;
 
 uint32_t counterCount;
 
 // Get the count of counters supported
 vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
   physicalDevice,
   queueFamilyIndex,
   &counterCount,
   NULL,
   NULL);
 
 VkPerformanceCounterKHR* counters =
   malloc(sizeof(VkPerformanceCounterKHR) * counterCount);
 VkPerformanceCounterDescriptionKHR* counterDescriptions =
   malloc(sizeof(VkPerformanceCounterDescriptionKHR) * counterCount);
 
 // Get the counters supported
 vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
   physicalDevice,
   queueFamilyIndex,
   &counterCount,
   counters,
   counterDescriptions);
 
 // Try to enable the first 8 counters
 uint32_t enabledCounters[8];
 
 const uint32_t enabledCounterCount = min(counterCount, 8));
 
 for (uint32_t i = 0; i < enabledCounterCount; i++) {
   enabledCounters[i] = i;
 }
 
 // A previously created device that had the performanceCounterQueryPools feature
 // set to VK_TRUE
 VkDevice device;
 
 VkQueryPoolPerformanceCreateInfoKHR performanceQueryCreateInfo = {
   VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
   NULL,
 
   // Specify the queue family that this performance query is performed on
   queueFamilyIndex,
 
   // The number of counters to enable
   enabledCounterCount,
 
   // The array of indices of counters to enable
   enabledCounters
 };
 
 
 // Get the number of passes our counters will require.
 uint32_t numPasses;
 
 vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
   physicalDevice,
   &performanceQueryCreateInfo,
   &numPasses);
 
 VkQueryPoolCreateInfo queryPoolCreateInfo = {
   VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
   &performanceQueryCreateInfo,
   0,
 
   // Using our new query type here
   VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,
 
   1,
 
   0
 };
 
 VkQueryPool queryPool;
 
 VkResult result = vkCreateQueryPool(
   device,
   &queryPoolCreateInfo,
   NULL,
   &queryPool);
 
 assert(VK_SUCCESS == result);
 
 // A queue from queueFamilyIndex
 VkQueue queue;
 
 // A command buffer we want to record counters on
 VkCommandBuffer commandBuffer;
 
 VkCommandBufferBeginInfo commandBufferBeginInfo = {
   VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
   NULL,
   0,
   NULL
 };
 
 VkAcquireProfilingLockInfoKHR lockInfo = {
   VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
   NULL,
   0,
   UINT64_MAX // Wait forever for the lock
 };
 
 // Acquire the profiling lock before we record command buffers
 // that will use performance queries
 
 result = vkAcquireProfilingLockKHR(device, &lockInfo);
 
 assert(VK_SUCCESS == result);
 
 result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
 
 assert(VK_SUCCESS == result);
 
 vkCmdResetQueryPool(
   commandBuffer,
   queryPool,
   0,
   1);
 
 vkCmdBeginQuery(
   commandBuffer,
   queryPool,
   0,
   0);
 
 // Perform the commands you want to get performance information on
 // ...
 
 // Perform a barrier to ensure all previous commands were complete before
 // ending the query
 vkCmdPipelineBarrier(commandBuffer,
   VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
   VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
   0,
   0,
   NULL,
   0,
   NULL,
   0,
   NULL);
 
 vkCmdEndQuery(
   commandBuffer,
   queryPool,
   0);
 
 result = vkEndCommandBuffer(commandBuffer);
 
 assert(VK_SUCCESS == result);
 
 for (uint32_t counterPass = 0; counterPass < numPasses; counterPass++) {
 
   VkPerformanceQuerySubmitInfoKHR performanceQuerySubmitInfo = {
     VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR,
     NULL,
     counterPass
   };
 
 
   // Submit the command buffer and wait for its completion
   // ...
 }
 
 // Release the profiling lock after the command buffer is no longer in the
 // pending state.
 vkReleaseProfilingLockKHR(device);
 
 result = vkResetCommandBuffer(commandBuffer, 0);
 
 assert(VK_SUCCESS == result);
 
 // Create an array to hold the results of all counters
 VkPerformanceCounterResultKHR* recordedCounters = malloc(
   sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount);
 
 result = vkGetQueryPoolResults(
   device,
   queryPool,
   0,
   1,
   sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount,
   recordedCounters,
   sizeof(VkPerformanceCounterResultKHR),
   NULL);
 
 // recordedCounters is filled with our counters, we will look at one for posterity
 switch (counters[0].storage) {
   case VK_PERFORMANCE_COUNTER_STORAGE_INT32:
     // use recordCounters[0].int32 to get at the counter result!
     break;
   case VK_PERFORMANCE_COUNTER_STORAGE_INT64:
     // use recordCounters[0].int64 to get at the counter result!
     break;
   case VK_PERFORMANCE_COUNTER_STORAGE_UINT32:
     // use recordCounters[0].uint32 to get at the counter result!
     break;
   case VK_PERFORMANCE_COUNTER_STORAGE_UINT64:
     // use recordCounters[0].uint64 to get at the counter result!
     break;
   case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32:
     // use recordCounters[0].float32 to get at the counter result!
     break;
   case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64:
     // use recordCounters[0].float64 to get at the counter result!
     break;
 }
    VK_KHR_performance_query
    Name String
    VK_KHR_performance_query
    Extension Type
    Device extension
    Registered Extension Number
    117
    Revision
    1
    Extension and Version Dependencies
    Special Use
    Contact
    Other Extension Metadata
    Last Modified Date
    2019-10-08
    IP Status
    No known IP claims.
    Contributors
    • Jesse Barker, Unity Technologies
    • Kenneth Benzie, Codeplay
    • Jan-Harald Fredriksen, ARM
    • Jeff Leger, Qualcomm
    • Jesse Hall, Google
    • Tobias Hector, AMD
    • Neil Henning, Codeplay
    • Baldur Karlsson
    • Lionel Landwerlin, Intel
    • Peter Lohrmann, AMD
    • Alon Or-bach, Samsung
    • Daniel Rakos, AMD
    • Niklas Smedberg, Unity Technologies
    • Igor Ostrowski, Intel