include::meta/VK_INTEL_performance_query.txt[]

*Last Modified Date*::
    2018-05-16
*IP Status*::
    No known IP claims.
*Contributors*::
  - Lionel Landwerlin, Intel
  - Piotr Maciejewski, Intel

This extension allows an application to capture performance data to be
interpreted by a external application or library.

Such a library is available at : https://github.com/intel/metrics-discovery

Performance analysis tools such as GPA
(https://software.intel.com/en-us/gpa) make use of this extension and the
metrics-discovery library to present the data in a human readable way.

=== New Object Types

  * slink:VkPerformanceConfigurationINTEL

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL
  ** ename:VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL
  ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL
  ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL
  ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL
  ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL

  * Extending elink:VkQueryType:
  ** ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL

=== New Enums

  * elink:VkPerformanceConfigurationTypeINTEL
  * elink:VkQueryPoolSamplingModeINTEL
  * elink:VkPerformanceOverrideTypeINTEL
  * elink:VkPerformanceParameterTypeINTEL
  * elink:VkPerformanceValueTypeINTEL

=== New Structures

  * slink:VkPerformanceValueINTEL
  * slink:VkInitializePerformanceApiInfoINTEL
  * slink:VkQueryPoolCreateInfoINTEL
  * slink:VkPerformanceMarkerInfoINTEL
  * slink:VkPerformanceStreamMarkerInfoINTEL
  * slink:VkPerformanceOverrideInfoINTEL
  * slink:VkPerformanceConfigurationAcquireInfoINTEL

=== New Functions

  * flink:vkInitializePerformanceApiINTEL
  * flink:vkUninitializePerformanceApiINTEL
  * flink:vkCmdSetPerformanceMarkerINTEL
  * flink:vkCmdSetPerformanceOverrideINTEL
  * flink:vkCmdSetPerformanceStreamMarkerINTEL
  * flink:vkAcquirePerformanceConfigurationINTEL
  * flink:vkReleasePerformanceConfigurationINTEL
  * flink:vkQueueSetPerformanceConfigurationINTEL
  * flink:vkGetPerformanceParameterINTEL

=== Issues

None.

=== Example Code

[source,c]
---------------------------------------------------

// A previously created device
VkDevice device;

// A queue from from device
VkQueue queue;

VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = {
  VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL,
  NULL,
  NULL
};

vkInitializePerformanceApiINTEL(
  device,
  &performanceApiInfoIntel);

VkQueryPoolCreateInfoINTEL queryPoolIntel = {
  VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL,
  NULL,
  VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL,
};

VkQueryPoolCreateInfo queryPoolCreateInfo = {
  VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
  &queryPoolIntel,
  0,
  VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL,
  1,
  0
};

VkQueryPool queryPool;

VkResult result = vkCreateQueryPool(
  device,
  &queryPoolCreateInfo,
  NULL,
  &queryPool);

assert(VK_SUCCESS == result);

// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;

VkCommandBufferBeginInfo commandBufferBeginInfo = {
  VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
  NULL,
  VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
  NULL
};

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);

VkPerformanceConfigurationAcquireInfoINTEL performanceConfigurationAcquireInfo = {
  VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL,
  NULL,
  VK_PERFORMANCE_CONFIGURATION_TYPE_COMMAND_QUEUE_METRICS_DISCOVERY_ACTIVATED_INTEL
};

VkPerformanceConfigurationINTEL performanceConfigurationIntel;

result = vkAcquirePerformanceConfigurationINTEL(
  device,
  &performanceConfigurationAcquireInfo,
  &performanceConfigurationIntel);

vkQueueSetPerformanceConfigurationINTEL(queue, performanceConfigurationIntel);

assert(VK_SUCCESS == result);

// Submit the command buffer and wait for its completion
// ...

result = vkReleasePerformanceConfigurationINTEL(
  device,
  performanceConfigurationIntel);

assert(VK_SUCCESS == result);

// Get the report size from metrics-discovery's QueryReportSize

result = vkGetQueryPoolResults(
  device,
  queryPool,
  0, 1, QueryReportSize,
  data, QueryReportSize, 0);

assert(VK_SUCCESS == result);

// The data can then be passed back to metrics-discovery from which
// human readable values can be queried.

---------------------------------------------------

=== Version History

 * Revision 1, 2018-05-16 (Lionel Landwerlin)
   - Initial revision