Shaders

Bindpoints

class renderdoc.ShaderBindpointMapping

This structure goes hand in hand with ShaderReflection to determine how to map from bindpoint indices in the resource lists there to API-specific binding points. The bindPoint member in ShaderResource or ConstantBlock refers to an index in these associated lists, which then map potentially sparsely and potentially in different orders to the appropriate API registers, indices, or slots.

API specific details:

  • Direct3D11 - All Bindpoint.bindset values are 0 as D3D11 has no notion of sets, and the only namespacing that exists is by shader stage and object type. Mostly this already exists with the constant block, read only and read write resource lists.

    Bindpoint.arraySize is likewise unused as D3D11 doesn’t have arrayed resource bindings.

    Bindpoint.bind refers to the register/slot binding within the appropriate type (SRVs for read-only resources, UAV for read-write resources, samplers/constant buffers in each type).

  • OpenGL - Similarly to D3D11, Bindpoint.bindset and Bindpoint.arraySize are unused as OpenGL does not have true binding sets or array resource binds.

    For OpenGL there may be many more duplicate Bindpoint objects as the Bindpoint.bind refers to the index in the type-specific list, which is much more granular on OpenGL. E.g. 0 may refer to images, storage buffers, and atomic buffers all within the readWriteResources list. The index is the uniform value of the binding. Since no objects are namespaced by shader stage, the same value in two shaders refers to the same binding.

  • Direct3D12 - Since D3D12 doesn’t have true resource arrays (they are linearised into sequential registers) Bindpoint.arraySize is not used.

    Bindpoint.bindset corresponds to register spaces, with Bindpoint.bind then mapping to the register within that space. The root signature then maps these registers to descriptors.

  • Vulkan - For Vulkan Bindpoint.bindset corresponds to the index of the descriptor set, and Bindpoint.bind refers to the index of the descriptor within that set. Bindpoint.arraySize also is used as descriptors in Vulkan can be true arrays, bound all at once to a single binding.

constantBlocks

Provides a list of Bindpoint entries for remapping the ShaderReflection.constantBlocks list.

Type:

List[Bindpoint]

inputAttributes

This maps input attributes as a simple swizzle on the ShaderReflection.inputSignature indices for APIs where this mapping is mutable at runtime.

Type:

List[int]

readOnlyResources

Provides a list of Bindpoint entries for remapping the ShaderReflection.readOnlyResources list.

Type:

List[Bindpoint]

readWriteResources

Provides a list of Bindpoint entries for remapping the ShaderReflection.readWriteResources list.

Type:

List[Bindpoint]

samplers

Provides a list of Bindpoint entries for remapping the ShaderReflection.samplers list.

Type:

List[Bindpoint]

class renderdoc.Bindpoint

Declares the binding information for a single resource binding.

See ShaderBindpointMapping for how this mapping works in detail.

arraySize

If this is an arrayed binding, the number of elements in the array.

bind

The binding index.

bindset

The binding set.

used

True if the shader actually uses this resource, otherwise it’s declared but unused.

class renderdoc.BindpointIndex

References a particular element in a Bindpoint.

arrayIndex

If this is an arrayed binding, the element in the array being referenced.

bind

The binding index.

bindset

The binding set.

Reflection

class renderdoc.ShaderReflection

The reflection and metadata fully describing a shader.

The information in this structure is API agnostic, and is matched up against a ShaderBindpointMapping instance to map the information here to the API’s binding points and resource binding scheme.

constantBlocks

The constant block bindings.

Type:

List[ConstantBlock]

debugInfo

The embedded debugging information.

Type:

ShaderDebugInfo

dispatchThreadsDimension

The 3D dimensions of a compute workgroup, for compute shaders.

Type:

Tuple[int,int,int]

encoding

The ShaderEncoding of this shader. See rawBytes.

entryPoint

The entry point in the shader for this reflection, if multiple entry points exist.

inputSignature

The input signature.

Type:

List[SigParameter]

interfaces

The list of strings with the shader’s interfaces. Largely an unused API feature.

Type:

List[str]

outputSignature

The output signature.

Type:

List[SigParameter]

outputTopology

The output topology for geometry, tessellation and mesh shaders.

Type:

Topology

pointerTypes

The list of pointer types referred to in this shader.

Type:

List[ShaderConstantType]

rawBytes

A raw bytes dump of the original shader, encoded in the form denoted by encoding.

readOnlyResources

The read-only resource bindings.

Type:

List[ShaderResource]

readWriteResources

The read-write resource bindings.

Type:

List[ShaderResource]

resourceId

The ResourceId of this shader.

samplers

The sampler bindings.

Type:

List[ShaderSampler]

stage

The ShaderStage that this shader corresponds to, if multiple entry points exist.

taskPayload

The block layout of the task-mesh communication payload.

Only relevant for task or mesh shaders, this gives the output payload (for task shaders) or the input payload (for mesh shaders)

Type:

ConstantBlock

class renderdoc.ShaderStage(value)

The stage in a pipeline where a shader runs

Vertex

The vertex shader.

Hull

The hull shader. See also Tess_Control.

Tess_Control

The tessellation control shader. See also Hull.

Domain

The domain shader. See also Tess_Eval.

Tess_Eval

The tessellation evaluation shader. See also Domain.

Geometry

The geometry shader.

Pixel

The pixel shader. See also Fragment.

Fragment

The fragment shader. See also Pixel.

Compute

The compute shader.

Amplification

The amplification shader. See also Task.

Task

The task shader. See also Amplification.

Mesh

The mesh shader.

class renderdoc.ShaderStageMask(value)

A set of flags for ShaderStage stages

Unknown

No flags set for any shader stages.

Vertex

The flag for ShaderStage.Vertex.

Hull

The flag for ShaderStage.Hull.

Tess_Control

The flag for ShaderStage.Tess_Control.

Domain

The flag for ShaderStage.Domain.

Tess_Eval

The flag for ShaderStage.Tess_Eval.

Geometry

The flag for ShaderStage.Geometry.

Pixel

The flag for ShaderStage.Pixel.

Fragment

The flag for ShaderStage.Fragment.

Compute

The flag for ShaderStage.Compute.

Task

The flag for ShaderStage.Task.

Amplification

The flag for ShaderStage.Amplification.

Mesh

The flag for ShaderStage.Mesh.

All

A shorthand version with flags set for all stages together.

renderdoc.MaskForStage(stage)

Calculate the corresponding flag for a shader stage

Parameters:

stage# (ShaderStage) – The shader stage

Returns:

The flag that corresponds to the input shader stage

Return type:

ShaderStageMask

class renderdoc.SigParameter

The information describing an input or output signature element describing the interface between shader stages.

NoIndex

Value for an index that means it is invalid or not applicable for this parameter.

channelUsedMask

A bitmask indicating which components in the shader register are actually used by the shader itself, for APIs that pack signatures together.

compCount

The number of components used to store this element. See varType.

needSemanticIndex

A convenience flag - True if the semantic name is unique and no index is needed.

perPrimitiveRate

A flag indicating if this parameter is output at per-primitive rate rather than per-vertex.

regChannelMask

A bitmask indicating which components in the shader register are stored, for APIs that pack signatures together.

regIndex

The index of the shader register/binding used to store this signature element.

This may be NoIndex if the element is system-generated and not consumed by another shader stage. See systemValue.

semanticIdxName

The combined semantic name and index.

semanticIndex

The semantic index of this variable - see semanticName.

semanticName

The semantic name of this variable, if the API uses semantic matching for bindings.

stream

Selects a stream for APIs that provide multiple output streams for the same named output.

systemValue

The ShaderBuiltin value that this element contains.

varName

The name of this variable - may not be present in the metadata for all APIs.

varType

The variable type of data that this element stores.

class renderdoc.ShaderBuiltin(value)

Annotates a particular built-in input or output from a shader with a special meaning to the hardware or API.

Some of the built-in inputs or outputs can be declared multiple times in arrays or otherwise indexed to apply to multiple related things - see ClipDistance, CullDistance and ColorOutput.

Undefined

Undefined built-in or no built-in is attached to this shader variable.

Position

As an output from the final vertex processing shader stage, this feeds the vertex position to the rasterized. As an input to the pixel shader stage this receives the position from the rasterizer.

PointSize

An output that controls the size of point primitives.

ClipDistance

An output for the distance to a user-defined clipping plane. Any pixel with an interpolated value that is negative will not be rasterized. Typically there can be more than one such output.

CullDistance

An output for the distance to a user-defined culling plane. Any primitive with all vertices having negative values will not be rasterized. Typically there can be more than one such output.

RTIndex

An output for selecting the render target index in an array to render to. Available in geometry shaders and possibly earlier stages depending on hardware/API capability.

ViewportIndex

An output for selecting the viewport index to render to. Available in geometry shaders and possibly earlier stages depending on hardware/API capability.

VertexIndex

An input to the vertex shader listing the vertex index. The exact meaning of this index can vary by API but generally it refers to either a 0-based counter for non-indexed draws, or the index value for indexed draws. It may or may not be affected by offsets, depending on API semantics.

PrimitiveIndex

A built-in indicating which primitive is being processed. This can be read by all primitive stages after the vertex shader, and written by the geometry shader.

InstanceIndex

This built-in is defined similar to VertexIndex but for instances within an instanced drawcall. It counts from 0 and as with VertexIndex it may or may not be affected by drawcall offsets.

DispatchSize

An input in compute shaders that gives the number of workgroups executed by the dispatch call.

DispatchThreadIndex

An input in compute shaders giving a 3D shared index across all workgroups, such that the index varies across each thread in the workgroup up to its size, then the indices for workgroup (0,0,1) begin adjacent to where workgroup (0,0,0) ended.

This is related to GroupThreadIndex and GroupIndex.

GroupIndex

An input in compute shaders giving a 3D index of this current workgroup amongst all workgroups, up to the dispatch size.

The index is constant across all threads in the workgroup.

This is related to GroupThreadIndex and DispatchThreadIndex.

GroupSize

The size of a workgroup, giving the number of threads in each dimension.

GroupFlatIndex

An input in compute shaders giving a flat 1D index of the thread within the current workgroup. This index increments first in the X dimension, then in the Y dimension, then in the Z dimension.

GroupThreadIndex

An input in compute shaders giving a 3D index of this thread within its workgroup, up to the workgroup size.

The input does not vary between one thread in a workgroup and the same thread in another workgroup.

This is related to GroupIndex and DispatchThreadIndex.

GSInstanceIndex

An input to the geometry shader giving the instance being run, if the geometry shader was setup to be invoked multiple times for each input primitive.

OutputControlPointIndex

An input to the tessellation control or hull shader giving the output control point index or patch vertex being operated on.

DomainLocation

An input to the tessellation evaluation or domain shader, giving the normalised location on the output patch where evaluation is occuring. E.g. for triangle output this is the barycentric co-ordinates of the output vertex.

IsFrontFace

An input to the pixel shader indicating whether or not the contributing triangle was considered front-facing or not according to the API setup for winding order and backface orientation.

MSAACoverage

An input or an output from the pixel shader. As an input, it specifies a bitmask of which samples in a pixel were covered by the rasterizer. As an output, it specifies which samples in the destination target should be updated.

MSAASamplePosition

An input to the pixel shader that contains the location of the current sample relative to the pixel, when running the pixel shader at sample frequency.

MSAASampleIndex

An input to the pixel shader that indicates which sample in the range 0 .. N-1 is currently being processed.

PatchNumVertices

An input to the tessellation stages, this gives the number of vertices in each patch.

OuterTessFactor

An output from the tessellation control or hull shader, this determines the level to which the outer edge of each primitive is tessellated by the fixed-function tessellator.

It is also available for reading in the tessellation evaluation or domain shader.

InsideTessFactor

Related to OuterTessFactor this functions in the same way to determine the tessellation level inside the primitive.

ColorOutput

An output from the pixel shader, this determines the color value written to the corresponding target. There will be as many color output built-ins as there are targets bound.

DepthOutput

An output from the pixel shader, writes the depth of this pixel with no restrictions.

Related to DepthOutputGreaterEqual and DepthOutputLessEqual.

DepthOutputGreaterEqual

An output from the pixel shader, writes the depth of this pixel with the restriction that it will be greater than or equal to the original depth produced by the rasterizer.

Related to DepthOutput and DepthOutputLessEqual.

DepthOutputLessEqual

An output from the pixel shader, writes the depth of this pixel with the restriction that it will be less than or equal to the original depth produced by the rasterizer.

Related to DepthOutputGreaterEqual and DepthOutput.

BaseVertex

The first vertex processed in this draw, as specified by the firstVertex / baseVertex parameter to the draw call.

BaseInstance

The first instance processed in this draw call, as specified by the firstInstance parameter.

DrawIndex

For indirect or multi-draw commands, the index of this draw call within the overall draw command.

StencilReference

The stencil reference to be used for stenciling operations on this fragment.

PointCoord

The fragments co-ordinates within a point primitive being rasterized.

IsHelper

Indicates if the current invocation is a helper invocation.

SubgroupSize

The number of invocations in a subgroup.

NumSubgroups

The number of subgroups in the local workgroup.

SubgroupIndexInWorkgroup

The index of the current subgroup within all subgroups in the workgroup, up to NumSubgroups - 1.

IndexInSubgroup

The index of the current thread in the current subgroup, up to SubgroupSize - 1.

SubgroupEqualMask

A bitmask where the bit corresponding to IndexInSubgroup is set.

SubgroupGreaterEqualMask

A bitmask where all bits greater or equal to the one corresponding to IndexInSubgroup are set.

SubgroupGreaterMask

A bitmask where all bits greater than the one corresponding to IndexInSubgroup are set.

SubgroupLessEqualMask

A bitmask where all bits less or equal to the one corresponding to IndexInSubgroup are set.

SubgroupLessMask

A bitmask where all bits less than the one corresponding to IndexInSubgroup are set.

DeviceIndex

The device index executing the shader, relative to the current device group.

IsFullyCovered

Indicates if the current fragment area is fully covered by the generating primitive.

FragAreaSize

Gives the dimensions of the area that the fragment covers.

FragInvocationCount

Gives the maximum number of invocations for the fragment being covered.

PackedFragRate

Contains the packed shading rate, with an API specific packing of X and Y. For example:

1x being 0, 2x being 1, 4x being 2. Then the lower two bits being the Y rate and the next 2 bits being the X rate.

Barycentrics

Contains the barycentric co-ordinates.

CullPrimitive

An output to indicate whether or not a primitive should be culled.

OutputIndices

An output containing the indices for a meshlet.

class renderdoc.ConstantBlock

Contains the information for a block of constant values. The values are not present, only the metadata about how the variables are stored in memory itself and their type/name information.

bindPoint

The bindpoint for this block. This is an index in the ShaderBindpointMapping.constantBlocks list.

bufferBacked

True if the contents are stored in a buffer of memory. If not then they are set by some other API-specific method, such as direct function calls or they may be compile-time specialisation constants.

byteSize

The total number of bytes consumed by all of the constants contained in this block.

compileConstants

True if this is a virtual buffer listing compile-time specialisation constants.

inlineDataBytes

True if this is backed by in-line data bytes rather than a specific buffer.

name

The name of this constant block, may be empty on some APIs.

variables

The constants contained within this block.

Type:

List[ShaderConstant]

class renderdoc.ShaderSampler

Contains the information for a separate sampler in a shader. If the API doesn’t have the concept of separate samplers, this struct will be unused and only ShaderResource is relevant.

Note

that constant blocks will not have a shader resource entry, see ConstantBlock.

bindPoint

The bindpoint for this block. This is an index in either the ShaderBindpointMapping.samplers list.

name

The name of this sampler.

class renderdoc.ShaderResource

Contains the information for a shader resource that is made accessible to shaders directly by means of the API resource binding system.

Note

that constant blocks and samplers will not have a shader resource entry, see ConstantBlock and ShaderSampler.

bindPoint

The bindpoint for this block. This is an index in either the ShaderBindpointMapping.readOnlyResources list or ShaderBindpointMapping.readWriteResources list as appropriate (see isReadOnly).

isReadOnly

True if this resource is available to the shader for reading only, otherwise it is able to be read from and written to arbitrarily.

isTexture

True if this resource is a texture, otherwise it is a buffer.

name

The name of this resource.

resType

The TextureType that describes the type of this resource.

variableType

The type of each element of this resource.

Type:

ShaderConstantType

Debug Info

class renderdoc.ShaderDebugInfo

Contains the information about a shader contained within API-specific debugging information attached to the shader.

Primarily this means the embedded original source files.

compileFlags

The flags used to compile this shader.

Type:

ShaderCompileFlags

compiler

The KnownShaderTool of the compiling tool.

Type:

KnownShaderTool

debugStatus

If debuggable is false then this contains a simple explanation of why the shader is not supported for debugging

debuggable

Indicates whether this particular shader can be debugged. In some cases even if the API can debug shaders in general, specific shaders cannot be debugged because they use unsupported functionality

editBaseFile

The index of the file which should be used for re-editing this shader’s entry point.

This is an optional value, and if set to -1 you should fall back to using the file specified in entryLocation, and if no file is specified there then use the first file listed.

encoding

The ShaderEncoding of the source. See files.

Type:

ShaderEncoding

entryLocation

The source location of the first executable line or the entry point.

Note

The information is not guaranteed to be available depending on the underlying shader format, so all of the elements are optional.

Type:

LineColumnInfo

files

The shader files encoded in the form denoted by encoding.

The first entry in the list is always the file where the entry point is.

Type:

List[ShaderSourceFile]

sourceDebugInformation

Indicates whether this shader has debug information to allow source-level debugging.

class renderdoc.ShaderEncoding(value)

Identifies a shader encoding used to pass shader code to an API.

Unknown

Unknown or unprocessable format.

DXBC

DXBC binary shader, used by D3D11 and D3D12.

GLSL

GLSL in string format, used by OpenGL.

SPIRV

SPIR-V binary shader, as used by Vulkan. This format is technically not distinct from OpenGLSPIRV but is considered unique here since it really should have been a different format, and introducing a separation allows better selection of tools automatically.

SPIRVAsm

Canonical SPIR-V assembly form, used (indirectly via SPIRV) by Vulkan. See SPIRV.

OpenGLSPIRV

SPIR-V binary shader, as used by OpenGL. This format is technically not distinct from VulkanSPIRV but is considered unique here since it really should have been a different format, and introducing a separation allows better selection of tools automatically.

OpenGLSPIRVAsm

Canonical SPIR-V assembly form, used (indirectly via OpenGLSPIRV) by OpenGL. See OpenGLSPIRV and note that it’s artificially differentiated from SPIRVAsm.

HLSL

HLSL in string format, used by D3D11, D3D12, and Vulkan/GL via compilation to SPIR-V.

DXIL

DXIL binary shader, used by D3D12. Note that although the container is still DXBC format this is used to distinguish from DXBC for compiler I/O matching.

class renderdoc.KnownShaderTool(value)

Identifies a particular known tool used for shader processing.

Unknown

Corresponds to no known tool.

SPIRV_Cross
SPIRV-Cross

targetting normal Vulkan flavoured SPIR-V.

SPIRV_Cross_OpenGL
SPIRV-Cross

targetting OpenGL extension flavoured SPIR-V.

spirv_dis
spirv-dis from SPIRV-Tools

targetting normal Vulkan flavoured SPIR-V.

spirv_dis_OpenGL
spirv-dis from SPIRV-Tools

targetting OpenGL extension flavoured SPIR-V.

glslangValidatorGLSL
glslang compiler (GLSL)

targetting normal Vulkan flavoured SPIR-V.

glslangValidatorGLSL_OpenGL
glslang compiler (GLSL)

targetting OpenGL extension flavoured SPIR-V.

glslangValidatorHLSL

glslang compiler (HLSL).

spirv_as
spirv-as from SPIRV-Tools

targetting normal Vulkan flavoured SPIR-V.

spirv_as_OpenGL
spirv-as from SPIRV-Tools

targetting OpenGL extension flavoured SPIR-V.

dxcSPIRV
DirectX Shader Compiler with Vulkan SPIR-V

output.

dxcDXIL

DirectX Shader Compiler with DXIL output.

fxc

fxc Shader Compiler with DXBC output.

renderdoc.ToolExecutable(tool)

Returns the default executable name with no suffix for a given KnownShaderTool.

Note

The executable name is returned with no suffix, e.g. foobar which may need a platform specific suffix like .exe appended.

Parameters:

tool# (KnownShaderTool) – The tool to get the executable name for.

Returns:

The default executable name for this tool, or an empty string if the tool is unrecognised.

Return type:

str

renderdoc.ToolInput(tool)

Returns the expected default input ShaderEncoding that a KnownShaderTool expects. This may not be accurate and may be configurable depending on the tool.

Parameters:

tool# (KnownShaderTool) – The tool to get the input encoding for.

Returns:

The encoding that this tool expects as an input by default.

Return type:

renderdoc.ShaderEncoding

renderdoc.ToolOutput(tool)

Returns the expected default output ShaderEncoding that a KnownShaderTool produces. This may not be accurate and may be configurable depending on the tool.

Parameters:

tool# (KnownShaderTool) – The tool to get the output encoding for.

Returns:

The encoding that this tool produces as an output by default.

Return type:

renderdoc.ShaderEncoding

renderdoc.IsTextRepresentation(encoding)

Check whether or not this is a human readable text representation.

Parameters:

encoding# (ShaderEncoding) – The encoding to check.

Returns:

True if it describes a text representation, False for a bytecode representation.

Return type:

bool

class renderdoc.ShaderEntryPoint

Describes an entry point in a shader.

name

The name of the entry point.

stage

The ShaderStage for this entry point .

class renderdoc.ShaderSourceFile

Contains a source file available in a debug-compiled shader.

contents

The actual contents of the file.

filename

The filename of this source file.

class renderdoc.ShaderCompileFlags

Contains the information about the compilation environment of a shader

flags

The API or compiler specific flags used to compile this shader originally.

Type:

List[ShaderCompileFlag]

class renderdoc.ShaderCompileFlag

Contains a single flag used at compile-time on a shader.

name

The name of the compile flag.

value

The value of the compile flag.

class renderdoc.ShaderSourcePrefix

Contains the source prefix to add to a given type of shader source

encoding

The encoding of the language this prefix applies to.

prefix

The source prefix to add.

Shader Constants

class renderdoc.ShaderConstant

Contains the detail of a constant within a struct, such as a ConstantBlock, with its type and relative location in memory.

bitFieldOffset

If the variable is bitfield packed, the bit offset from byteOffset above where this variable starts.

If the variable is not a bitfield, this value will be 0. Only integer scalars will have bitfield packing.

Note

Although the offset specified in byteOffset is in bytes, this bitfield offset may be larger than 0 depending on the surrounding values and their types and packing. However it is guaranteed that the offset and the size (from bitFieldSize) will be contained within the normal bit size for the variable type. For example if the variable type is a 32-bit integer, the offsets may range from 0 to 31 and the sum of offset and size will be no more than 32. If the variable is an 8-bit integer, similarly the offset will be 0 to 7 and the sum will be no more than 8.

bitFieldSize

If the variable is bitfield packed, the number of bits this variable spans starting from bitFieldOffset into memory.

If the variable is not a bitfield, this value will be 0. Only integer scalars will have bitfield packing.

byteOffset

The byte offset of this constant relative to the parent structure

defaultValue

If this constant is no larger than a 64-bit constant, gives a default value for it.

name

The name of this constant

type

The type information for this constant.

Type:

ShaderConstantType

class renderdoc.ShaderConstantType

Describes the type and members of a ShaderConstant.

ColMajor()

Helper function for checking if flags does not have ShaderVariableFlags.RowMajorMatrix set. This is entirely equivalent to checking that flag manually, but since it is common this helper is provided.

Note

Vectors and scalars will be marked as row-major by convention for convenience.

Returns:

If the storage is column-major order in memory

Return type:

bool

RowMajor()

Helper function for checking if flags has ShaderVariableFlags.RowMajorMatrix set. This is entirely equivalent to checking that flag manually, but since it is common this helper is provided.

Note

Vectors and scalars will be marked as row-major by convention for convenience.

Returns:

If the storage is row-major order in memory

Return type:

bool

arrayByteStride

The number of bytes between the start of one element in the array and the next.

baseType

The base VarType of this constant.

columns

The number of columns in this matrix.

elements

The number of elements in the array, or 1 if it’s not an array.

flags

The flags controlling how this constant is interpreted and displayed.

Type:

ShaderVariableFlags

matrixByteStride

The number of bytes between the start of one column/row in a matrix and the next.

members

Any members that this constant may contain.

Type:

List[ShaderConstant]

name

The name of the type of this constant, e.g. a struct name.

pointerTypeID

The index in ShaderReflection.pointerTypes of the pointee type.

rows

The number of rows in this matrix.

class renderdoc.ShaderVariableFlags(value)

A set of flags for events that control how a shader/buffer value is interpreted and displayed

NoFlags

No flags are specified.

RowMajorMatrix

This matrix is stored in row-major order in memory, instead of column-major. In RenderDoc values are always provided row-major regardless, for consistency of access, but if this flag is not present then the original values were in column order in memory, so the data has been transposed.

HexDisplay

This value should be displayed using hexadecimal where possible.

BinaryDisplay

This value should be displayed using binary where possible.

RGBDisplay

This value should be interpreted as an RGB colour for display where possible.

R11G11B10

This value should be decoded from a 32-bit integer in R11G11B10 packing format.

R10G10B10A2

This value should be decoded from a 32-bit integer in R10G10B10A2 packing format.

UNorm

This value should be treated as unsigned normalised floating point values when interpreting.

SNorm

This value should be treated as signed normalised floating point values when interpreting.

Truncated

This value was truncated when reading - the available range was exhausted.

class renderdoc.VarType(value)

Represents the base type of a shader variable in debugging or constant blocks.

Float

A single-precision (32-bit) floating point value.

Double

A double-precision (64-bit) floating point value.

Half

A half-precision (16-bit) floating point value.

SInt

A signed 32-bit integer value.

UInt

An unsigned 32-bit integer value.

SShort

A signed 16-bit integer value.

UShort

An unsigned 16-bit integer value.

SLong

A signed 64-bit integer value.

ULong

An unsigned 64-bit integer value.

SByte

A signed 8-bit integer value.

UByte

An unsigned 8-bit integer value.

Bool

A boolean value.

Enum

An enum - each member gives a named value, and the type itself is stored as an integer.

Struct

A structure with some number of members.

GPUPointer

A 64-bit pointer into GPU-addressable memory. Variables with this type are stored with opaque contents and should be decoded with ShaderVariable.GetPointer().

ConstantBlock

A reference to a constant block bound to the shader. Variables with this type are stored with opaque contents and should be decoded with ShaderVariable.GetBinding().

ReadOnlyResource

A reference to a read only resource bound to the shader. Variables with this type are stored with opaque contents and should be decoded with ShaderVariable.GetBinding().

ReadWriteResource

A reference to a read/write resource bound to the shader. Variables with this type are stored with opaque contents and should be decoded with ShaderVariable.GetBinding().

Sampler

A reference to a sampler bound to the shader. Variables with this type are stored with opaque contents and should be decoded with ShaderVariable.GetBinding().

Unknown

An unknown type.

renderdoc.VarTypeByteSize(type)

Get the byte size of a variable type.

Parameters:

type# (VarType) – The variable type

Returns:

The size in bytes of this type

Return type:

int

renderdoc.VarTypeCompType(type)

Get the component type of a variable type.

Parameters:

type# (VarType) – The variable type

Returns:

The base component type of this variable type

Return type:

CompType

Shader Debugging

class renderdoc.ShaderDebugTrace

This stores the whole state of a shader’s execution from start to finish, with each individual debugging step along the way, as well as the immutable global constant values that do not change with shader execution.

constantBlocks

Constant buffer backed variables for this shader.

Each entry in this list corresponds to a constant block with the same index in the ShaderBindpointMapping.constantBlocks list, which can be used to look up the metadata.

Depending on the underlying shader representation, the constant block may retain any structure or it may have been vectorised and flattened.

Type:

List[ShaderVariable]

debugger

An opaque handle identifying by the underlying debugger, which is used to simulate the shader and generate new debug states.

If this is None then the trace is invalid.

Type:

ShaderDebugger

inputs

The input variables for this shader.

Type:

List[ShaderVariable]

instInfo

An array of the same size as the number of instructions in the shader, with per-instruction information such as source line mapping, and source variables.

Warning

This array is not indexed by instruction. Since it is common for adjacent instructions to have effectively identical source information, this array only stores unique information ordered by instruction. On some internal representations this may be one entry per instruction, and on others it may be sparse and require a binary lookup to locate the corresponding information for an instruction. If no direct match is found, the lower bound match is valid (i.e. the data for instruction A before the data for instruction B is valid for all instructions in range [A, B).

Type:

List[InstructionSourceInfo]

readOnlyResources

The read-only resource variables for this shader.

The ‘value’ of the variable is always a single unsigned integer, which is the bindpoint - an index into the ShaderBindpointMapping.readOnlyResources list, which can be used to look up the other metadata as well as find the binding from the pipeline state.

Type:

List[ShaderVariable]

readWriteResources

The read-write resource variables for this shader.

The ‘value’ of the variable is always a single unsigned integer, which is the bindpoint - an index into the ShaderBindpointMapping.readWriteResources list, which can be used to look up the other metadata as well as find the binding from the pipeline state.

Type:

List[ShaderVariable]

samplers

The sampler variables for this shader.

The ‘value’ of the variable is always a single unsigned integer, which is the bindpoint - an index into the ShaderBindpointMapping.samplers list, which can be used to look up the other metadata as well as find the binding from the pipeline state.

Type:

List[ShaderVariable]

sourceVars

An optional mapping from high-level source variables to which debug variables and includes extra type information.

This list contains source variable mapping that is valid for the lifetime of a debug trace. It may be empty if there is no source variable mapping that extends to the life of the debug trace.

Type:

List[SourceVariableMapping]

stage

The shader stage being debugged in this trace

class renderdoc.ShaderDebugger

An opaque structure that has internal state for shader debugging

class renderdoc.SourceVariableMapping

Maps the contents of a high-level source variable to one or more shader variables in a ShaderDebugState, with type information.

A single high-level variable may be represented by multiple mappings but only along regular boundaries, typically whole vectors. For example an array may have each element in a different mapping, or a matrix may have a mapping per row. The properties such as rows and elements reflect the parent object.

Note

There is not necessarily a 1:1 mapping from source variable to debug variable, so this can change over time.

columns

The number of columns in this variable.

name

The name and member of this source variable that’s being mapped from.

offset

The offset in the parent source variable, for struct members. Useful for sorting.

rows

The number of rows in this variable - 1 for vectors, >1 for matrices.

signatureIndex

The index in the input or output signature of the shader that this variable represents.

The type of signature can be disambiguated by the debug variables referenced - inputs are stored separately.

This will be set to -1 if the variable is not part of either signature.

type

The variable type of the source being mapped from, if the debug variable is untyped.

variables

The debug variables that the components of this high level variable map to. Multiple ranges could refer to the same variable if a contiguous range is mapped to - the mapping is component-by-component to greatly simplify algorithms at the expense of a small amount of storage space.

Type:

List[DebugVariableReference]

class renderdoc.DebugVariableReference

A particular component of a debugging variable that a high-level variable component maps to

component

The component within the variable.

name

The name of the base debug variable.

type

The type of variable this is referring to.

class renderdoc.DebugVariableType(value)

Represents the category of debugging variable that a source variable maps to.

Undefined

Undefined type.

Input

A constant input value, stored globally.

Constant

A constant buffer value, stored globally.

Sampler

A sampler, stored globally.

ReadOnlyResource

A read-only resource, stored globally.

ReadWriteResource

A read-write resource, stored globally.

Variable

A mutable variable, stored per state.

class renderdoc.LineColumnInfo

Details the current region of code that an instruction maps to

SourceEqual(o)
Parameters:

o# (LineColumnInfo) – The object to compare against.

Returns:

True if this object is equal to the parameter, disregarding disassemblyLine.

Return type:

bool

colEnd

The column number (starting from 1) of the end of the code on the line specified by lineEnd. If set to 0, no column information is available and the whole lines should be treated as covering the code.

colStart

The column number (starting from 1) of the start of the code on the line specified by lineStart. If set to 0, no column information is available and the whole lines should be treated as covering the code.

disassemblyLine

The line (starting from 1) in the disassembly where this instruction is located.

fileIndex

The current file, as an index into the list of files for this shader.

If this is negative, no source mapping is available and only disassemblyLine is valid.

lineEnd

The ending line-number (starting from 1) of the source code.

lineStart

The starting line-number (starting from 1) of the source code.

class renderdoc.InstructionSourceInfo

Gives per-instruction source code mapping information, including what line(s) correspond to this instruction and which source variables exist

instruction

The instruction that this information is for.

lineInfo

The source location that this instruction corresponds to

Type:

LineColumnInfo

sourceVars

An optional mapping of which high-level source variables map to which debug variables and including extra type information.

This list contains source variable mapping that is only valid at this instruction, and is fully complete & redundant including all previous source variables that are still valid at this instruction.

Type:

List[SourceVariableMapping]

class renderdoc.ShaderDebugState

This stores the current state of shader debugging at one particular step in the shader, with all mutable variable contents.

callstack

The function names in the current callstack at this instruction.

The oldest/outer function is first in the list, the newest/inner function is last.

Type:

List[str]

changes

The changes in mutable variables for this shader. The change documents the bidirectional change of variables, so that a single state can be updated either forwards or backwards using the information.

Type:

List[ShaderVariableChange]

flags

A set of ShaderEvents flags that indicate what events happened on this step.

nextInstruction

The next instruction to be executed after this state. The initial state before any shader execution happened will have nextInstruction == 0.

stepIndex

The program counter within the debug trace. The initial state will be index 0, and it will increment linearly after that regardless of loops or branching.

class renderdoc.ShaderEvents(value)

A set of flags for events that may occur while debugging a shader

NoEvent

No event has occurred.

SampleLoadGather

A texture was sampled, loaded or gathered.

GeneratedNanOrInf

A floating point operation generated a NaN or infinity result.

class renderdoc.ShaderVariableChange

This stores the before and after state of a ShaderVariable.

after

The value of the variable after the change. If this variable is uninitialised that means the variable stopped existing on this step.

Type:

ShaderVariable

before

The value of the variable before the change. If this variable is uninitialised that means the variable came into existance on this step.

Type:

ShaderVariable

Shader Variables

class renderdoc.ShaderVariable

Holds a single named shader variable. It contains either a primitive type (up to a 4x4 matrix of a basic type) or a list of members, which can either be struct or array members of this parent variable.

Matrices are always stored row-major. If necessary they are transposed when retrieving from the raw data bytes when they are specified to be column-major in the API/shader metadata.

ColMajor()

Helper function for checking if flags does not have ShaderVariableFlags.RowMajorMatrix set. This is entirely equivalent to checking that flag manually, but since it is common this helper is provided.

Note

Vectors and scalars will be marked as row-major by convention for convenience.

Returns:

If the storage is column-major order in memory

Return type:

bool

GetBinding()

Utility function for getting the bindpoint referenced by this variable.

Note

The return value is undefined if this variable is not a binding reference.

Returns:

A BindpointIndex with the binding referenced.

Return type:

BindpointIndex

GetPointer()

Utility function for getting a pointer value, with optional type information.

Note

The return value is undefined if this variable is not a pointer.

Returns:

A PointerVal with the pointer value.

Return type:

PointerVal

RowMajor()

Helper function for checking if flags has ShaderVariableFlags.RowMajorMatrix set. This is entirely equivalent to checking that flag manually, but since it is common this helper is provided.

Note

Vectors and scalars will be marked as row-major by convention for convenience.

Returns:

If the storage is row-major order in memory

Return type:

bool

SetBinding(bindset, bind, arrayIndex)

Utility function for setting a bindpoint reference.

See ShaderBindpointMapping for the details of how bindpoints are interpreted. The type of binding is given by the type member.

Parameters:
  • bindset# (int) – The bind set.

  • bind# (int) – The bind itself.

  • arrayIndex# (int) – The array index, if the bind is an array. If it isn’t an array this should be set to 0.

SetTypedPointer(pointer, shader, pointerTypeID)

Utility function for setting a pointer value with type information.

Parameters:
  • pointer# (int) – The actual pointer value.

  • shader# (ResourceId) – The shader containing the type information.

  • pointerTypeID# (int) – The type’s index in the shader’s ShaderReflection.pointerTypes list.

SetTypelessPointer(pointer)

Utility function for setting a pointer value with no type information.

Parameters:

pointer# (int) – The actual pointer value.

columns

The number of columns in this matrix.

flags

The flags controlling how this constant is interpreted and displayed.

Type:

ShaderVariableFlags

members

The members of this variable.

Type:

List[ShaderVariable]

name

The name of this variable.

rows

The number of rows in this matrix.

type

The basic type of this variable.

value

The contents of this variable if it has no members.

Type:

ShaderValue

class renderdoc.ShaderValue

A C union that holds 16 values, with each different basic variable type.

f16v

16-tuple of 16-bit half-precision float values.

Type:

Tuple[int,…]

f32v

16-tuple of float values.

Type:

Tuple[float,…]

f64v

16-tuple of double values.

Type:

Tuple[float,…]

s16v

16-tuple of 16-bit signed integer values.

Type:

Tuple[int,…]

s32v

16-tuple of 32-bit signed integer values.

Type:

Tuple[int,…]

s64v

16-tuple of 64-bit signed integer values.

Type:

Tuple[int,…]

s8v

16-tuple of 8-bit signed integer values.

Type:

Tuple[int,…]

u16v

16-tuple of 16-bit unsigned integer values.

Type:

Tuple[int,…]

u32v

16-tuple of 32-bit unsigned integer values.

Type:

Tuple[int,…]

u64v

16-tuple of 64-bit unsigned integer values.

Type:

Tuple[int,…]

u8v

16-tuple of 8-bit unsigned integer values.

Type:

Tuple[int,…]

class renderdoc.PointerVal

A 64-bit pointer value with optional type information.

pointer

The actual pointer value itself.

pointerTypeID

The index into ShaderReflection.pointerTypes of the pointed type.

shader

An optional ResourceId identifying the shader containing the type info.