vkCmdBeginShaderInstrumentationARM(3)

Name

vkCmdBeginShaderInstrumentationARM - Begin shader instrumentation

C Specification

To begin shader instrumentation, call:

// Provided by VK_ARM_shader_instrumentation
void vkCmdBeginShaderInstrumentationARM(
    VkCommandBuffer                             commandBuffer,
    VkShaderInstrumentationARM                  instrumentation);

Parameters

commandBuffer is the command buffer into which this command will be recorded.
instrumentation is the handle of the shader instrumentation object that will capture the metrics.

Description

After beginning shader instrumentation, shader instrumentation is considered active within the command buffer it was called in until shader instrumentation is ended.

The shader instrumentation object has an implicit result index where the per-shader metrics will be written. The result index is set to 0 when the object is created by calling vkCreateShaderInstrumentationARM, and incremented by 1 for each draw, dispatch, and ray tracing command recorded while the shader instrumentation object is active.

The result index is also incremented by 1 when vkCmdExecuteGeneratedCommandsEXT is recorded.

While shader instrumentation is active, instrumented shaders write to the instrumentation object. These writes must be synchronized using the instrumented shader’s stage with access mask VK_ACCESS_2_SHADER_WRITE_BIT. If no instrumentation object is bound, writes are discarded.

If a command buffer is submitted multiple times, the shader instrumented metrics for all submissions will be aggregated in the instrumentation object, unless the metrics are cleared between submissions.

Valid Usage

VUID-vkCmdBeginShaderInstrumentationARM-commandBuffer-12375
This command must not be recorded while shader instrumentation is active within commandBuffer
VUID-vkCmdBeginShaderInstrumentationARM-commandBuffer-12376
commandBuffer must not be a protected command buffer

Valid Usage (Implicit)

VUID-vkCmdBeginShaderInstrumentationARM-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdBeginShaderInstrumentationARM-instrumentation-parameter
instrumentation must be a valid VkShaderInstrumentationARM handle
VUID-vkCmdBeginShaderInstrumentationARM-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdBeginShaderInstrumentationARM-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, VK_QUEUE_DATA_GRAPH_BIT_ARM, or VK_QUEUE_GRAPHICS_BIT operations
VUID-vkCmdBeginShaderInstrumentationARM-suspended
This command must not be called between suspended render pass instances
VUID-vkCmdBeginShaderInstrumentationARM-videocoding
This command must only be called outside of a video coding scope
VUID-vkCmdBeginShaderInstrumentationARM-commonparent
Both of commandBuffer, and instrumentation must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to instrumentation must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized