VK_INTEL_performance_query(3)

# VK_INTEL_performance_query(3) Manual Page

## Name

VK_INTEL_performance_query - device extension

Loading… please wait.

## Registered Extension Number

211

## Revision

2

## Extension and Version Dependencies

- Requires Vulkan 1.0

## Special Use

- Developer tools

### Other Extension Metadata

Last Modified Date

  2018-05-16

IP Status

  No known IP claims.

Contributors

  - Lionel Landwerlin, Intel

  - Piotr Maciejewski, Intel

### Description

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 Graphics Performance Analyzers make use of this extension and the metrics-discovery library to present the data in a human readable way.

### New Object Types

- VkPerformanceConfigurationINTEL

### New Commands

- vkAcquirePerformanceConfigurationINTEL

- vkCmdSetPerformanceMarkerINTEL

- vkCmdSetPerformanceOverrideINTEL

- vkCmdSetPerformanceStreamMarkerINTEL

- vkGetPerformanceParameterINTEL

- vkInitializePerformanceApiINTEL

- vkQueueSetPerformanceConfigurationINTEL

- vkReleasePerformanceConfigurationINTEL

- vkUninitializePerformanceApiINTEL

### New Structures

- VkInitializePerformanceApiInfoINTEL

- VkPerformanceConfigurationAcquireInfoINTEL

- VkPerformanceMarkerInfoINTEL

- VkPerformanceOverrideInfoINTEL

- VkPerformanceStreamMarkerInfoINTEL

- VkPerformanceValueINTEL

- Extending VkQueryPoolCreateInfo:

  - VkQueryPoolPerformanceQueryCreateInfoINTEL

### New Unions

- VkPerformanceValueDataINTEL

### New Enums

- VkPerformanceConfigurationTypeINTEL

- VkPerformanceOverrideTypeINTEL

- VkPerformanceParameterTypeINTEL

- VkPerformanceValueTypeINTEL

- VkQueryPoolSamplingModeINTEL

### New Enum Constants

- `VK_INTEL_PERFORMANCE_QUERY_EXTENSION_NAME`

- `VK_INTEL_PERFORMANCE_QUERY_SPEC_VERSION`

- Extending VkObjectType:

  - `VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL`

- Extending VkQueryType:

  - `VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL`

  - `VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL`

  - `VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL`

  - `VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL`

  - `VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL`

  - `VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL`

### Example Code

    // A previously created device
    VkDevice device;

    // A queue derived from the device
    VkQueue queue;

    VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = {
      VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL,
      NULL,
      NULL
    };

    vkInitializePerformanceApiINTEL(
      device,
      &performanceApiInfoIntel);

    VkQueryPoolPerformanceQueryCreateInfoINTEL 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 2, 2020-03-06 (Lionel Landwerlin)

  - Rename VkQueryPoolCreateInfoINTEL in VkQueryPoolPerformanceQueryCreateInfoINTEL

- Revision 1, 2018-05-16 (Lionel Landwerlin)

  - Initial revision

## See Also

VkInitializePerformanceApiInfoINTEL, VkPerformanceConfigurationAcquireInfoINTEL, VkPerformanceConfigurationINTEL, VkPerformanceConfigurationTypeINTEL, VkPerformanceMarkerInfoINTEL, VkPerformanceOverrideInfoINTEL, VkPerformanceOverrideTypeINTEL, VkPerformanceParameterTypeINTEL, VkPerformanceStreamMarkerInfoINTEL, VkPerformanceValueDataINTEL, VkPerformanceValueINTEL, VkPerformanceValueTypeINTEL, VkQueryPoolCreateInfoINTEL, VkQueryPoolPerformanceQueryCreateInfoINTEL, VkQueryPoolSamplingModeINTEL, vkAcquirePerformanceConfigurationINTEL, vkCmdSetPerformanceMarkerINTEL, vkCmdSetPerformanceOverrideINTEL, vkCmdSetPerformanceStreamMarkerINTEL, vkGetPerformanceParameterINTEL, vkInitializePerformanceApiINTEL, vkQueueSetPerformanceConfigurationINTEL, vkReleasePerformanceConfigurationINTEL, vkUninitializePerformanceApiINTEL

## Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

## Copyright

Copyright 2014-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0