Vulkan.Extensions.VK_ARM_shader_instrumentation

vkEnumeratePhysicalDeviceShaderInstrumentationMetricsARM - Returns properties describing what shader instrumentation metrics are supported

Description

If pDescriptions is NULL, then the number of shader instrumentation metrics available is returned in pDescriptionCount. Otherwise, pDescriptionCount must point to a variable set by the application to the number of elements in the pDescriptions array, and on return the variable is overwritten with the number of structures actually written to pDescriptions. If pDescriptionCount is less than the number shader instrumentation metrics available, at most pDescriptionCount structures will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available shader instrumentation metrics were returned.

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pDescriptionCount must be a valid pointer to a uint32_t value

• If the value referenced by pDescriptionCount is not 0, and pDescriptions is not NULL, pDescriptions must be a valid pointer to an array of pDescriptionCount ShaderInstrumentationMetricDescriptionARM structures

Return Codes

Success

• INCOMPLETE

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_ARM_shader_instrumentation, PhysicalDevice, ShaderInstrumentationMetricDescriptionARM

vkCreateShaderInstrumentationARM - Create a new shader instrumentation object

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid ShaderInstrumentationCreateInfoARM structure

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• pInstrumentation must be a valid pointer to a ShaderInstrumentationARM handle

• The device must have been created with at least 1 queue

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_ARM_shader_instrumentation, AllocationCallbacks, Device, ShaderInstrumentationARM, ShaderInstrumentationCreateInfoARM

A convenience wrapper to make a compatible pair of calls to createShaderInstrumentationARM and destroyShaderInstrumentationARM

To ensure that destroyShaderInstrumentationARM is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkDestroyShaderInstrumentationARM - Destroy a shader instrumentation object

Valid Usage

• All submitted commands that refer to instrumentation must have completed execution

Valid Usage (Implicit)

• device must be a valid Device handle

• If instrumentation is not NULL_HANDLE, instrumentation must be a valid ShaderInstrumentationARM handle

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• If instrumentation is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to instrumentation must be externally synchronized

See Also

VK_ARM_shader_instrumentation, AllocationCallbacks, Device, ShaderInstrumentationARM

vkCmdBeginShaderInstrumentationARM - Begin shader instrumentation

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 createShaderInstrumentationARM, 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 cmdExecuteGeneratedCommandsEXT 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 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

• This command must not be recorded while shader instrumentation is active within commandBuffer

• commandBuffer must not be a protected command buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• instrumentation must be a valid ShaderInstrumentationARM handle

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, QUEUE_DATA_GRAPH_BIT_ARM, or QUEUE_GRAPHICS_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

• Both of commandBuffer, and instrumentation must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to instrumentation must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdBeginShaderInstrumentationARM is not affected by conditional rendering

See Also

VK_ARM_shader_instrumentation, CommandBuffer, ShaderInstrumentationARM

vkCmdEndShaderInstrumentationARM - End shader instrumentation

Description

Once recorded, shader instrumentation is no longer considered active within the command buffer.

Valid Usage

• Shader instrumentation must be active within commandBuffer

• commandBuffer must not be a protected command buffer

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• commandBuffer must be in the recording state

• The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT, QUEUE_DATA_GRAPH_BIT_ARM, or QUEUE_GRAPHICS_BIT operations

• This command must not be called between suspended render pass instances

• This command must only be called outside of a video coding scope

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Conditional Rendering

vkCmdEndShaderInstrumentationARM is not affected by conditional rendering

See Also

VK_ARM_shader_instrumentation, CommandBuffer

vkGetShaderInstrumentationValuesARM - Retrieve shader instrumentation data

Description

If pMetricValues is NULL, then the number of metric blocks available is returned in pMetricBlockCount. Otherwise, pMetricBlockCount must point to a variable set by the application to the number of elements in the pMetricValues array, and on return the variable is overwritten with the number of metric blocks actually written to pMetricValues. If pMetricBlockCount is less than the number of metric blocks available, at most pMetricBlockCount elements will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available metric blocks were returned.

Metrics are written to pMetricValues as a tightly packed array of metric blocks, where each block consists of a ShaderInstrumentationMetricDataHeaderARM header followed by PhysicalDeviceShaderInstrumentationPropertiesARM::numMetrics unsigned 64-bit values. The order of the metrics matches the order in which they are enumerated by enumeratePhysicalDeviceShaderInstrumentationMetricsARM.

Return Codes

Success

• INCOMPLETE

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_ARM_shader_instrumentation, Device, ShaderInstrumentationARM, ShaderInstrumentationValuesFlagsARM

vkClearShaderInstrumentationMetricsARM - Clear shader instrumentation metrics to zero

Valid Usage (Implicit)

See Also

VK_ARM_shader_instrumentation, Device, ShaderInstrumentationARM

VkPhysicalDeviceShaderInstrumentationFeaturesARM - Structure describing support for shader instrumentation

Description

If the PhysicalDeviceShaderInstrumentationFeaturesARM structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDeviceShaderInstrumentationFeaturesARM, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_ARM_shader_instrumentation, Bool32, StructureType

VkPhysicalDeviceShaderInstrumentationPropertiesARM - Structure describing shader instrumentation properties for a physical device

Members

The members of the PhysicalDeviceShaderInstrumentationPropertiesARM structure describe the following:

Description

If the PhysicalDeviceShaderInstrumentationPropertiesARM structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

• PhysicalDeviceProperties2

See Also

VK_ARM_shader_instrumentation, Bool32, StructureType

VkShaderInstrumentationCreateInfoARM - Structure specifying parameters of a newly created shader instrumentation

Valid Usage (Implicit)

See Also

VK_ARM_shader_instrumentation, StructureType, createShaderInstrumentationARM

VkShaderInstrumentationMetricDescriptionARM - Structure specifying shader instrumentation metric properties

Valid Usage (Implicit)

See Also

VK_ARM_shader_instrumentation, StructureType, enumeratePhysicalDeviceShaderInstrumentationMetricsARM

VkShaderInstrumentationMetricDataHeaderARM - Structure describing the header of a metric block

Valid Usage (Implicit)

See Also

VK_ARM_shader_instrumentation, ShaderStageFlags

VkShaderInstrumentationValuesFlagsARM - Reserved for future use

Description

ShaderInstrumentationValuesFlagsARM is a bitmask type for parameters to the retrieval, but is currently reserved for future use.

See Also

VK_ARM_shader_instrumentation, Flags, getShaderInstrumentationValuesARM

VkShaderInstrumentationARM - Opaque handle to a shader instrumentation object

See Also

VK_ARM_shader_instrumentation, VK_DEFINE_NON_DISPATCHABLE_HANDLE, clearShaderInstrumentationMetricsARM, cmdBeginShaderInstrumentationARM, createShaderInstrumentationARM, destroyShaderInstrumentationARM, getShaderInstrumentationValuesARM

VkShaderCreateFlagBitsEXT - Bitmask controlling how a shader object is created

Description

• SHADER_CREATE_LINK_STAGE_BIT_EXT specifies that a shader is linked to all other shaders created in the same createShadersEXT call whose ShaderCreateInfoEXT structures' flags include SHADER_CREATE_LINK_STAGE_BIT_EXT.

• SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT specifies that the SubgroupSize may vary in a task, mesh, or compute shader.

• SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT specifies that the subgroup sizes must be launched with all invocations active in a task, mesh, or compute shader.

• SHADER_CREATE_NO_TASK_SHADER_BIT_EXT specifies that a mesh shader must only be used without a task shader. Otherwise, the mesh shader must only be used with a task shader.

• SHADER_CREATE_DISPATCH_BASE_BIT_EXT specifies that a compute shader can be used with cmdDispatchBase with a non-zero base workgroup.

• SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT specifies that a fragment shader can be used with a fragment shading rate attachment.

• SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies that a fragment shader can be used with a fragment density map attachment.

• SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT specifies that the shader can be used in combination with https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#device-generated-commands.

• SHADER_CREATE_OPACITY_MICROMAP_DISALLOW_MIXED_SPECIAL_INDEX_BIT_EXT specifies that shader objects cannot be used with acceleration structures which are built with geometry that have an index buffer including both special indices and indices pointing to an associated micromap array. Geometry which has an index buffer using only special indices without an associated micromap array can be used with this flag.

• SHADER_CREATE_INDEPENDENT_SETS_BIT_KHR specifies that implementations must ensure that the properties and/or absence of a particular descriptor set do not influence any other descriptor sets for the shader. This allows shader objects to be created with a subset of the total descriptor sets.

• SHADER_CREATE_64_BIT_INDEXING_BIT_EXT specifies that the shader enables 64-bit indexing.

• SHADER_CREATE_DESCRIPTOR_HEAP_BIT_EXT specifies that the shader will use descriptor heap mappings instead of descriptor set layouts.

See Also

VK_EXT_shader_object, ShaderCreateFlagsEXT