Top Description Fields Constructors Methods
org.lwjgl.vulkan

public Class KHRPerformanceQuery

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.system.*
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 = {
  .sType = VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
  .pNext = NULL,

  // Specify the queue family that this performance query is performed on
  .queueFamilyIndex = queueFamilyIndex,

  // The number of counters to enable
  .counterIndexCount = enabledCounterCount,

  // The array of indices of counters to enable
  .pCounterIndices = enabledCounters
};


// Get the number of passes our counters will require.
uint32_t numPasses;

vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
  physicalDevice,
  &performanceQueryCreateInfo,
  &numPasses);

VkQueryPoolCreateInfo queryPoolCreateInfo = {
  .sType = VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
  .pNext = &performanceQueryCreateInfo,
  .flags = 0,
  // Using our new query type here
  .queryType = VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,
  .queryCount = 1,
  .pipelineStatistics = 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 = {
  .sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
  .pNext = NULL,
  .flags = 0,
  .pInheritanceInfo = NULL
};

VkAcquireProfilingLockInfoKHR lockInfo = {
  .sType = VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
  .pNext = NULL,
  .flags = 0,
  .timeout = 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
VK_KHR_get_physical_device_properties2 or Version 1.1
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

Field Summary

Modifier and TypeField and Description
public static final String
VK_KHR_PERFORMANCE_QUERY_EXTENSION_NAME

The extension name.

public static final int
VK_KHR_PERFORMANCE_QUERY_SPEC_VERSION

The extension specification version.

public static final int
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR

VkPerformanceCounterDescriptionFlagBitsKHR - Bitmask specifying usage behavior for a counter Description

public static final int
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR

VkPerformanceCounterDescriptionFlagBitsKHR - Bitmask specifying usage behavior for a counter Description

public static final int
VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR

VkPerformanceCounterDescriptionFlagBitsKHR - Bitmask specifying usage behavior for a counter Description

public static final int
VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_KHR

VkPerformanceCounterDescriptionFlagBitsKHR - Bitmask specifying usage behavior for a counter Description

public static final int
VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR

VkPerformanceCounterScopeKHR - Supported counter scope types Description

public static final int
VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR

VkPerformanceCounterScopeKHR - Supported counter scope types Description

public static final int
VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR

VkPerformanceCounterScopeKHR - Supported counter scope types Description

public static final int
VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32_KHR

VkPerformanceCounterStorageKHR - Supported counter storage types Description

public static final int
VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64_KHR

VkPerformanceCounterStorageKHR - Supported counter storage types Description

public static final int
VK_PERFORMANCE_COUNTER_STORAGE_INT32_KHR

VkPerformanceCounterStorageKHR - Supported counter storage types Description

public static final int
VK_PERFORMANCE_COUNTER_STORAGE_INT64_KHR

VkPerformanceCounterStorageKHR - Supported counter storage types Description

public static final int
VK_PERFORMANCE_COUNTER_STORAGE_UINT32_KHR

VkPerformanceCounterStorageKHR - Supported counter storage types Description

public static final int
VK_PERFORMANCE_COUNTER_STORAGE_UINT64_KHR

VkPerformanceCounterStorageKHR - Supported counter storage types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_AMPS_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_BYTES_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_BYTES_PER_SECOND_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_CYCLES_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_GENERIC_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_HERTZ_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_KELVIN_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_NANOSECONDS_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_PERCENTAGE_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_VOLTS_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_PERFORMANCE_COUNTER_UNIT_WATTS_KHR

VkPerformanceCounterUnitKHR - Supported counter unit types Description

public static final int
VK_QUERY_SCOPE_COMMAND_BUFFER_KHR

VkPerformanceCounterScopeKHR - Supported counter scope types Description

public static final int
VK_QUERY_SCOPE_COMMAND_KHR

VkPerformanceCounterScopeKHR - Supported counter scope types Description

public static final int
VK_QUERY_SCOPE_RENDER_PASS_KHR

VkPerformanceCounterScopeKHR - Supported counter scope types Description

public static final int
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR

Extends VkQueryType.

public static final int
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR

Extends VkStructureType.

Constructor Summary

AccessConstructor and Description
protected
KHRPerformanceQuery()

Method Summary

Modifier and TypeMethod and Description
public static int
nvkAcquireProfilingLockKHR(VkDevice device, long pInfo)

Unsafe version of: AcquireProfilingLockKHR

public static int
nvkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(VkPhysicalDevice physicalDevice, int queueFamilyIndex, long
a pointer to an integer related to the number of counters available or queried, as described below.
pCounterCount, long pCounters, long pCounterDescriptions)

Unsafe version of: EnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR

public static void
nvkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(VkPhysicalDevice physicalDevice, long pPerformanceQueryCreateInfo, long pNumPasses)

Unsafe version of: GetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR

public static int
vkAcquireProfilingLockKHR(VkDevice
the logical device to profile.
device, VkAcquireProfilingLockInfoKHR
a pointer to a VkAcquireProfilingLockInfoKHR structure containing information about how the profiling is to be acquired.
pInfo)

Acquires the profiling lock.

public static int
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(VkPhysicalDevice
the handle to the physical device whose queue family performance query counter properties will be queried.
physicalDevice, int
the index into the queue family of the physical device we want to get properties for.
queueFamilyIndex, IntBuffer
a pointer to an integer related to the number of counters available or queried, as described below.
pCounterCount, VkPerformanceCounterKHR.Buffer
either NULL or a pointer to an array of VkPerformanceCounterKHR structures.
pCounters, VkPerformanceCounterDescriptionKHR.Buffer
either NULL or a pointer to an array of VkPerformanceCounterDescriptionKHR structures.
pCounterDescriptions)

Reports properties of the performance query counters available on a queue family of a device.

public static int
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(VkPhysicalDevice physicalDevice, int queueFamilyIndex, int[] pCounterCount, VkPerformanceCounterKHR.Buffer pCounters, VkPerformanceCounterDescriptionKHR.Buffer pCounterDescriptions)

Array version of: EnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR

public static void
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(VkPhysicalDevice
the handle to the physical device whose queue family performance query counter properties will be queried.
physicalDevice, VkQueryPoolPerformanceCreateInfoKHR
a pointer to a VkQueryPoolPerformanceCreateInfoKHR of the performance query that is to be created.
pPerformanceQueryCreateInfo, IntBuffer
a pointer to an integer related to the number of passes required to query the performance query pool, as described below.
pNumPasses)

Reports the number of passes require for a performance query pool type.

public static void
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(VkPhysicalDevice physicalDevice, VkQueryPoolPerformanceCreateInfoKHR pPerformanceQueryCreateInfo, int[] pNumPasses)

Array version of: GetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR

public static void
vkReleaseProfilingLockKHR(VkDevice
the logical device to cease profiling on.
device)

Releases the profiling lock.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait