registry/vulkan/chapters/VK_AMD_shader_info.txt

// This section is included inside the Pipelines chapter (pipelines.txt)

[[pipelines-shader-information]]
== Pipeline Shader Information

[open,refpage='vkGetShaderInfoAMD',desc='Get information about a shader in a pipeline',type='protos']
--

Information about a particular shader that has been compiled as part of a
pipeline object can be extracted by calling:

include::../api/protos/vkGetShaderInfoAMD.txt[]

  * pname:device is the device that created pname:pipeline.
  * pname:pipeline is the target of the query.
  * pname:shaderStage identifies the particular shader within the pipeline
    about which information is being queried.
  * pname:infoType describes what kind of information is being queried.
  * pname:pInfoSize is a pointer to a value related to the amount of data
    the query returns, as described below.
  * pname:pInfo is either NULL or a pointer to a buffer.

If pname:pInfo is `NULL`, then the maximum size of the information that can:
be retrieved about the shader, in bytes, is returned in pname:pInfoSize.
Otherwise, pname:pInfoSize must: point to a variable set by the user to the
size of the buffer, in bytes, pointed to by pname:pInfo, and on return the
variable is overwritten with the amount of data actually written to
pname:pInfo.

If pname:pInfoSize is less than the maximum size that can: be retrieved by
the pipeline cache, then at most pname:pInfoSize bytes will be written to
pname:pInfo, and fname:vkGetShaderInfoAMD will return ename:VK_INCOMPLETE.

Not all information is available for every shader and implementations may
not support all kinds of information for any shader.
When a certain type of information is unavailable, the function returns
ename:VK_ERROR_FEATURE_NOT_PRESENT.

If information is successfully and fully queried, the function will return
ename:VK_SUCCESS.

For ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD, an instance of
sname:VkShaderStatisticsInfoAMD will be written to the buffer pointed to by
pname:pInfo.
This structure will be populated with statistics regarding the physical
device resources used by that shader along with other miscellaneous
information and is described in further detail below.

For ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD, pname:pInfo points to a UTF-8
null-terminated string containing human-readable disassembly.
The exact formatting and contents of the disassembly string are
vendor-specific.

The formatting and contents of all other types of information, including
ename:VK_SHADER_INFO_TYPE_BINARY_AMD, are left to the vendor and are not
further specified by this extension.

include::../validity/protos/vkGetShaderInfoAMD.txt[]
--

[open,refpage='VkShaderStatisticsInfoAMD',desc='Statistical information about a particular shader within a pipeline',type='structs']
--

The sname:VkShaderStatisticsInfoAMD structure is defined as:

include::../api/structs/VkShaderStatisticsInfoAMD.txt[]

  * pname:shaderStageMask are the combination of logical shader stages
    contained within this shader.
  * pname:resourceUsage is an instance of slink:VkShaderResourceUsageAMD
    describing internal physical device resources used by this shader.
  * pname:numPhysicalVgprs is the maximum number of vector instruction
    general-purpose registers (VGPRs) available to the physical device.
  * pname:numPhysicalSgprs is the maximum number of scalar instruction
    general-purpose registers (SGPRs) available to the physical device.
  * pname:numAvailableVgprs is the maximum limit of VGPRs made available to
    the shader compiler.
  * pname:numAvailableSgprs is the maximum limit of SGPRs made available to
    the shader compiler.
  * pname:computeWorkGroupSize is the local workgroup size of this shader in
    { X, Y, Z } dimensions.

Some implementations may merge multiple logical shader stages together in a
single shader.
In such cases, pname:shaderStageMask will contain a bitmask of all of the
stages that are active within that shader.
Consequently, if specifying those stages as input to
flink:vkGetShaderInfoAMD, the same output information may: be returned for
all such shader stage queries.

The number of available VGPRs and SGPRs (pname:numAvailableVgprs and
pname:numAvailableSgprs respectively) are the shader-addressable subset of
physical registers that is given as a limit to the compiler for register
assignment.
These values may: further be limited by implementations due to performance
optimizations where register pressure is a bottleneck.

include::../validity/structs/VkShaderStatisticsInfoAMD.txt[]
--

[open,refpage='VkShaderResourceUsageAMD',desc='Resource usage information about a particular shader within a pipeline',type='structs']
--

The sname:VkShaderResourceUsageAMD structure is defined as:

include::../api/structs/VkShaderResourceUsageAMD.txt[]

  * pname:numUsedVgprs is the number of vector instruction general-purpose
    registers used by this shader.
  * pname:numUsedSgprs is the number of scalar instruction general-purpose
    registers used by this shader.
  * pname:ldsSizePerLocalWorkGroup is the maximum local data store size per
    work group in bytes.
  * pname:ldsUsageSizeInBytes is the LDS usage size in bytes per work group
    by this shader.
  * pname:scratchMemUsageInBytes is the scratch memory usage in bytes by
    this shader.

include::../validity/structs/VkShaderResourceUsageAMD.txt[]
--