1  // This section is included inside the Pipelines chapter (pipelines.txt)
  2  
  3  [[pipelines-shader-information]]
  4  == Pipeline Shader Information
  5  
  6  [open,refpage='vkGetShaderInfoAMD',desc='Get information about a shader in a pipeline',type='protos']
  7  --
  8  
  9  Information about a particular shader that has been compiled as part of a
 10  pipeline object can be extracted by calling:
 11  
 12  include::{generated}/api/protos/vkGetShaderInfoAMD.txt[]
 13  
 14    * pname:device is the device that created pname:pipeline.
 15    * pname:pipeline is the target of the query.
 16    * pname:shaderStage identifies the particular shader within the pipeline
 17      about which information is being queried.
 18    * pname:infoType describes what kind of information is being queried.
 19    * pname:pInfoSize is a pointer to a value related to the amount of data
 20      the query returns, as described below.
 21    * pname:pInfo is either NULL or a pointer to a buffer.
 22  
 23  If pname:pInfo is `NULL`, then the maximum size of the information that can:
 24  be retrieved about the shader, in bytes, is returned in pname:pInfoSize.
 25  Otherwise, pname:pInfoSize must: point to a variable set by the user to the
 26  size of the buffer, in bytes, pointed to by pname:pInfo, and on return the
 27  variable is overwritten with the amount of data actually written to
 28  pname:pInfo.
 29  
 30  If pname:pInfoSize is less than the maximum size that can: be retrieved by
 31  the pipeline cache, then at most pname:pInfoSize bytes will be written to
 32  pname:pInfo, and fname:vkGetShaderInfoAMD will return ename:VK_INCOMPLETE.
 33  
 34  Not all information is available for every shader and implementations may
 35  not support all kinds of information for any shader.
 36  When a certain type of information is unavailable, the function returns
 37  ename:VK_ERROR_FEATURE_NOT_PRESENT.
 38  
 39  If information is successfully and fully queried, the function will return
 40  ename:VK_SUCCESS.
 41  
 42  For pname:infoType ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD, an instance of
 43  sname:VkShaderStatisticsInfoAMD will be written to the buffer pointed to by
 44  pname:pInfo.
 45  This structure will be populated with statistics regarding the physical
 46  device resources used by that shader along with other miscellaneous
 47  information and is described in further detail below.
 48  
 49  For pname:infoType ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD, pname:pInfo
 50  points to a UTF-8 null-terminated string containing human-readable
 51  disassembly.
 52  The exact formatting and contents of the disassembly string are
 53  vendor-specific.
 54  
 55  The formatting and contents of all other types of information, including
 56  pname:infoType ename:VK_SHADER_INFO_TYPE_BINARY_AMD, are left to the vendor
 57  and are not further specified by this extension.
 58  
 59  include::{generated}/validity/protos/vkGetShaderInfoAMD.txt[]
 60  --
 61  
 62  [open,refpage='VkShaderInfoTypeAMD',desc='Enum specifying which type of shader info to query',type='enums']
 63  --
 64  Possible values of flink:vkGetShaderInfoAMD::pname:infoType, specifying the
 65  information being queried from a shader, are:
 66  
 67  include::{generated}/api/enums/VkShaderInfoTypeAMD.txt[]
 68  
 69    * ename:VK_SHADER_INFO_TYPE_STATISTICS_AMD specifies that device resources
 70      used by a shader will be queried.
 71    * ename:VK_SHADER_INFO_TYPE_BINARY_AMD specifies that
 72      implementation-specific information will be queried.
 73    * ename:VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD specifies that human-readable
 74      dissassembly of a shader.
 75  --
 76  
 77  [open,refpage='VkShaderStatisticsInfoAMD',desc='Statistical information about a particular shader within a pipeline',type='structs']
 78  --
 79  
 80  The sname:VkShaderStatisticsInfoAMD structure is defined as:
 81  
 82  include::{generated}/api/structs/VkShaderStatisticsInfoAMD.txt[]
 83  
 84    * pname:shaderStageMask are the combination of logical shader stages
 85      contained within this shader.
 86    * pname:resourceUsage is an instance of slink:VkShaderResourceUsageAMD
 87      describing internal physical device resources used by this shader.
 88    * pname:numPhysicalVgprs is the maximum number of vector instruction
 89      general-purpose registers (VGPRs) available to the physical device.
 90    * pname:numPhysicalSgprs is the maximum number of scalar instruction
 91      general-purpose registers (SGPRs) available to the physical device.
 92    * pname:numAvailableVgprs is the maximum limit of VGPRs made available to
 93      the shader compiler.
 94    * pname:numAvailableSgprs is the maximum limit of SGPRs made available to
 95      the shader compiler.
 96    * pname:computeWorkGroupSize is the local workgroup size of this shader in
 97      { X, Y, Z } dimensions.
 98  
 99  Some implementations may merge multiple logical shader stages together in a
100  single shader.
101  In such cases, pname:shaderStageMask will contain a bitmask of all of the
102  stages that are active within that shader.
103  Consequently, if specifying those stages as input to
104  flink:vkGetShaderInfoAMD, the same output information may: be returned for
105  all such shader stage queries.
106  
107  The number of available VGPRs and SGPRs (pname:numAvailableVgprs and
108  pname:numAvailableSgprs respectively) are the shader-addressable subset of
109  physical registers that is given as a limit to the compiler for register
110  assignment.
111  These values may: further be limited by implementations due to performance
112  optimizations where register pressure is a bottleneck.
113  
114  include::{generated}/validity/structs/VkShaderStatisticsInfoAMD.txt[]
115  --
116  
117  [open,refpage='VkShaderResourceUsageAMD',desc='Resource usage information about a particular shader within a pipeline',type='structs']
118  --
119  
120  The sname:VkShaderResourceUsageAMD structure is defined as:
121  
122  include::{generated}/api/structs/VkShaderResourceUsageAMD.txt[]
123  
124    * pname:numUsedVgprs is the number of vector instruction general-purpose
125      registers used by this shader.
126    * pname:numUsedSgprs is the number of scalar instruction general-purpose
127      registers used by this shader.
128    * pname:ldsSizePerLocalWorkGroup is the maximum local data store size per
129      work group in bytes.
130    * pname:ldsUsageSizeInBytes is the LDS usage size in bytes per work group
131      by this shader.
132    * pname:scratchMemUsageInBytes is the scratch memory usage in bytes by
133      this shader.
134  
135  include::{generated}/validity/structs/VkShaderResourceUsageAMD.txt[]
136  --