API Reference: Replay Analysis¶

Frame and Actions¶

class renderdoc.FrameDescription¶

class renderdoc.FrameDescription(other: FrameDescription)

Contains frame-level global information

NoFrameNumber¶

No frame number is available.

captureTime¶

The time when the capture was created, as a unix timestamp in UTC.

Type:

int

compressedFileSize¶

The total file size of the whole capture in bytes, before decompression.

Type:

int

containsAnnotations¶

Whether or not the capture contains any annotations.

Type:

bool

debugMessages¶

The debug messages that are not associated with any particular event.

Type:

List[DebugMessage]

fileOffset¶

The offset into the file of the start of the frame.

Note

Similarly to APIEvent.fileOffset this should only be used as a relative measure, as it is not a literal number of bytes from the start of the file on disk.

Type:

int

frameNumber¶

Starting from frame #1 defined as the time from application startup to first present, this counts the frame number when the capture was made.

Note

This value is only accurate if the capture was triggered through the default mechanism, if it was triggered from the application API it doesn’t correspond to anything and will be set to NoFrameNumber.

Type:

int

initDataSize¶

The byte size of the section of the file that contains frame-initial contents.

Type:

int

persistentSize¶

The byte size of the section of the file that must be kept in memory persistently.

Type:

int

stats¶

The frame statistics.

Type:

FrameStatistics

uncompressedFileSize¶

The total file size of the whole capture in bytes, after decompression.

Type:

int

class renderdoc.ActionDescription¶

class renderdoc.ActionDescription(other: ActionDescription)

Describes the properties of an action.

An action is a call such as a draw, a compute dispatch, clears, copies, resolves, etc. Any GPU event which may have deliberate visible side-effects to application-visible memory, typically resources such as textures and buffers. It also includes markers, which provide a user-generated annotation of events and actions.

GetName(structuredFile)¶

Returns the name for this action, either from its custom name (see customName) or from the matching chunk in the structured data passed in.

Parameters:

structuredFile# (SDFile) – The structured data file for the capture this action is from.

Returns:

Returns the best available name for this action.

Return type:

str

IsFakeMarker()¶

Returns whether or not this action corresponds to a fake marker added by ReplayController.AddFakeMarkers().

Such actions may break expectations of event IDs and action IDs, so it is recommended to avoid processing them wherever possible.

Returns:

Returns whether or not this action is a fake marker.

Return type:

bool

actionId¶

A 1-based index of this action relative to other actions.

Type:

int

baseVertex¶

For indexed drawcalls, the offset added to each index after fetching.

Type:

int

children¶

The child actions below this one, if it’s a marker region or multi-action.

Type:

List[ActionDescription]

copyDestination¶

The ResourceId identifying the destination object in a copy, resolve or blit operation.

Type:

ResourceId

copyDestinationSubresource¶

Which part of copyDestination is used.

Type:

Subresource

copySource¶

The ResourceId identifying the source object in a copy, resolve or blit operation.

Type:

ResourceId

copySourceSubresource¶

Which part of copySource is used.

Type:

Subresource

customName¶

The custom name of this action.

For markers this will be a user-provided string. In most other cases this will be empty, and the name can be generated using structured data. The last listed event in events will correspond to the event for the overall action, and its chunk will contain a name and any parameters.

Some actions will have a custom name generated for e.g. reading back and directly displaying indirect parameters or render pass parameters.

Type:

str

depthOut¶

The resource used for depth output - see outputs.

Type:

ResourceId

dispatchBase¶

The 3D base offset of the workgroup ID if the call allows an override, or 0 if not.

Type:

Tuple[int,int,int]

dispatchDimension¶

The 3D number of workgroups to dispatch in a dispatch call.

Type:

Tuple[int,int,int]

dispatchThreadsDimension¶

The 3D size of each workgroup in threads if the call allows an override, or 0 if not.

Type:

Tuple[int,int,int]

drawIndex¶

The index of this action in an call with multiple draws, e.g. an indirect action.

0 if not part of a multi-action.

Type:

int

eventId¶

The eventId that actually produced the action.

Type:

int

events¶

The events that happened since the previous action.

Type:

List[APIEvent]

flags¶

A set of ActionFlags properties describing what kind of action this is.

Type:

ActionFlags

indexOffset¶

For indexed drawcalls, the first index to fetch from the index buffer.

Type:

int

instanceOffset¶

For instanced drawcalls, the offset applied before looking up instanced vertex inputs.

Type:

int

markerColor¶

A RGBA color specified by a debug marker call.

Type:

FloatVector

nextAction¶

The next action in the frame, or None if this is the last action in the frame.

Type:

ActionDescription

numIndices¶

The number of indices or vertices as appropriate for a draw action. 0 if not used.

Type:

int

numInstances¶

The number of instances for a draw action. 0 if not used.

Type:

int

outputs¶

An 8-tuple of the ResourceId ids for the color outputs, which can be used for very coarse bucketing of actions into similar passes by their outputs.

Type:

Tuple[ResourceId,…]

parent¶

The parent of this action, or None if there is no parent for this action.

Type:

ActionDescription

previousAction¶

The previous action in the frame, or None if this is the first action in the frame.

Type:

ActionDescription

vertexOffset¶

For non-indexed drawcalls, the offset applied before looking up each vertex input.

Type:

int

class renderdoc.ActionFlags(value)¶

A set of flags describing the properties of a particular action. An action is a call such as a draw, a compute dispatch, clears, copies, resolves, etc. Any GPU event which may have deliberate visible side-effects to application-visible memory, typically resources such as textures and buffers. It also includes markers, which provide a user-generated annotation of events and actions.

NoFlags¶

The action has no special properties.

Clear¶

The action is a clear call. See ClearColor and ClearDepthStencil.

Drawcall¶

The action renders primitives using the graphics pipeline.

Dispatch¶

The action issues a number of compute workgroups.

MeshDispatch¶

The action issues a number of mesh groups for a draw.

CmdList¶

The action calls into a previously recorded child command list.

SetMarker¶

The action inserts a single debugging marker.

PushMarker¶

The action begins a debugging marker region that has children.

PopMarker¶

The action ends a debugging marker region.

Present¶

The action is a presentation call that hands a swapchain image to the presentation engine.

MultiAction¶

The action is a multi-action that contains several specified child actions. Typically a MultiDraw or ExecuteIndirect on D3D12.

Copy¶

The action performs a resource copy operation.

Resolve¶

The action performs a resource resolve or blit operation.

GenMips¶

The action performs a resource mip-generation operation.

PassBoundary¶

The action marks the beginning or end of a render pass. See BeginPass and EndPass.

DispatchRay¶

This action issues a number of rays.

BuildAccStruct¶

This action builds or copies to and implicitly fills an acceleration structure.

Indexed¶

The action uses an index buffer.

Instanced¶

The action uses instancing. This does not mean it renders more than one instanced, simply that it uses the instancing feature.

Auto¶

The action interacts with stream-out to render all vertices previously written. This is a Direct3D 11 specific feature.

Indirect¶

The action uses a buffer on the GPU to source some or all of its parameters in an indirect way.

ClearColor¶

The action clears a color target.

ClearDepthStencil¶

The action clears a depth-stencil target.

BeginPass¶

The action marks the beginning of a render pass.

EndPass¶

The action marks the end of a render pass.

CommandBufferBoundary¶

The action is a virtual marker added to show command buffer boundaries.

class renderdoc.APIEvent¶

class renderdoc.APIEvent(other: APIEvent)

An individual API-level event, generally corresponds one-to-one with an API call.

NoChunk¶

No chunk is available.

annotations¶

An optional set of annotations associated with this event, may be None if annotations are not used.

Type:

SDObject

chunkIndex¶

The chunk index for this function call in the structured file.

If no chunk index is available this will be set to NoChunk. This will only happen for fake markers added to the capture after load.

Type:

int

eventId¶

The API event’s Event ID.

This is a 1-based count of API events in the capture. The eventId is used as a reference point in many places in the API to represent where in the capture the ‘current state’ is, and to perform analysis in reference to the state at a particular point in the frame.

eventIds are generally increasing, positive, and contiguous, with a few exceptions. These are when fake markers are added to a capture with ReplayController.AddFakeMarkers(). Thus if strong eventId guarantees are desired, this function should be avoided.

Also eventIds may not correspond directly to an actual function call - sometimes a function such as a multi action indirect will be one function call that expands to multiple events to allow inspection of results part way through the multi action.

Type:

int

fileOffset¶

A byte offset in the data stream where this event happens.

Note

This should only be used as a relative measure, it is not a literal number of bytes from the start of the file on disk.

Type:

int

Debug Messages¶

class renderdoc.DebugMessage¶

class renderdoc.DebugMessage(other: DebugMessage)

A debugging message from the API validation or internal analysis and error detection.

category¶

The category of this debug message.

Type:

MessageCategory

description¶

The string contents of the message.

Type:

str

eventId¶

The eventId where this debug message was found.

Type:

int

messageID¶

An ID that identifies this particular debug message uniquely.

Type:

int

severity¶

The severity of this debug message.

Type:

MessageSeverity

source¶

The source of this debug message.

Type:

MessageSource

class renderdoc.MessageCategory(value)¶

The type of issue that a debug message is about.

Application_Defined¶

This message was generated by the application.

Miscellaneous¶

This message doesn’t fall into any other pre-defined category.

Initialization¶

This message is about initialisation or creation of objects.

Cleanup¶

This message is about cleanup, destruction or shutdown of objects.

Compilation¶

This message is about compilation of shaders.

State_Creation¶

This message is about creating unified state objects.

State_Setting¶

This message is about changing current pipeline state.

State_Getting¶

This message is about fetching or retrieving current pipeline state.

Resource_Manipulation¶

This message is about updating or changing a resource’s properties or contents.

Execution¶

This message is about performing work.

Shaders¶

This message is about the use, syntax, binding or linkage of shaders.

Deprecated¶

This message is about the use of deprecated functionality.

Undefined¶

This message is about the use of undefined behaviour.

Portability¶

This message is about behaviour that could be or is not portable between different environments.

Performance¶

This message is about performance problems or pitfalls.

class renderdoc.MessageSeverity(value)¶

How serious a debug message is

High¶

This message is very serious, indicating a guaranteed problem or major flaw.

Medium¶

This message is somewhat serious, indicating a problem that should be addressed or investigated.

Low¶

This message is not very serious. This indicates something that might indicate a problem.

Info¶

This message is not about a problem but is purely informational.

class renderdoc.MessageSource(value)¶

Where a debug message was reported from

API¶

This message comes from the API’s debugging or validation layers.

RedundantAPIUse¶

This message comes from detecting redundant API calls - calls with no side-effect or purpose, e.g. setting state that is already set.

IncorrectAPIUse¶

This message comes from detecting incorrect use of the API.

GeneralPerformance¶

This message comes from detecting general performance problems that are not hardware or platform specific.

GCNPerformance¶

This message comes from detecting patterns that will cause performance problems on GCN-based hardware.

RuntimeWarning¶

This message comes not from inspecting the log but something detected at runtime while in use, for example exceptions generated during shader debugging.

UnsupportedConfiguration¶

This message comes from replaying a capture in an environment with insufficient capability to accurately reproduce the API work. Either this means the replay will be wrong, or it may be that depending on the exact API work some inaccuracies might happen.

Resource Usage¶

class renderdoc.EventUsage¶

class renderdoc.EventUsage(other: EventUsage)

class renderdoc.EventUsage(eventId: int, usage: ResourceUsage)

Describes a particular use of a resource at a specific eventId.

eventId¶

The eventId where this usage happened.

Type:

int

usage¶

The ResourceUsage in question.

Type:

ResourceUsage

class renderdoc.ResourceUsage(value)¶

How a resource is being used in the pipeline at a particular point.

Note that a resource may be used for more than one thing in one event, see EventUsage.

Unused¶

The resource is not being tracked for usage at any event.

VertexBuffer¶

The resource is being used as a fixed-function vertex buffer input.

IndexBuffer¶

The resource is being used as an index buffer.

VS_Constants¶

The resource is being used for constants in the vertex shader.

HS_Constants¶

The resource is being used for constants in the tessellation control or hull shader.

DS_Constants¶

The resource is being used for constants in the tessellation evaluation or domain shader.

GS_Constants¶

The resource is being used for constants in the geometry shader.

PS_Constants¶

The resource is being used for constants in the pixel shader.

CS_Constants¶

The resource is being used for constants in the compute shader.

TS_Constants¶

The resource is being used as a constants in the amplification or task shader.

MS_Constants¶

The resource is being used as a constants in the mesh shader.

All_Constants¶

The resource is being used for constants in all shader stages.

StreamOut¶

The resource is being used for stream out/transform feedback storage after geometry processing.

VS_Resource¶

The resource is being used as a read-only resource in the vertex shader.

HS_Resource¶

The resource is being used as a read-only resource in the tessellation control or hull shader.

DS_Resource¶

The resource is being used as a read-only resource in the tessellation evaluation or domain shader.

GS_Resource¶

The resource is being used as a read-only resource in the geometry shader.

PS_Resource¶

The resource is being used as a read-only resource in the pixel shader.

CS_Resource¶

The resource is being used as a read-only resource in the compute shader.

TS_Resource¶

The resource is being used as a read-only resource in the amplification or task shader.

MS_Resource¶

The resource is being used as a read-only resource in the mesh shader.

All_Resource¶

The resource is being used as a read-only resource in all shader stages.

VS_RWResource¶

The resource is being used as a read-write resource in the vertex shader.

HS_RWResource¶

The resource is being used as a read-write resource in the tessellation control or hull shader.

DS_RWResource¶

The resource is being used as a read-write resource in the tessellation evaluation or domain shader.

GS_RWResource¶

The resource is being used as a read-write resource in the geometry shader.

PS_RWResource¶

The resource is being used as a read-write resource in the pixel shader.

CS_RWResource¶

The resource is being used as a read-write resource in the compute shader.

TS_RWResource¶

The resource is being used as a read-write resource in the amplification or task shader.

MS_RWResource¶

The resource is being used as a read-write resource in the mesh shader.

All_RWResource¶

The resource is being used as a read-write resource in all shader stages.

InputTarget¶

The resource is being read as an input target for reading from the target currently being written.

ColorTarget¶

The resource is being written to as a color output.

DepthStencilTarget¶

The resource is being written to and tested against as a depth-stencil output.

Indirect¶

The resource is being used for indirect arguments.

Clear¶

The resource is being cleared.

Discard¶

The resource contents are discarded explicitly or implicitly.

GenMips¶

The resource is having mips generated for it.

Resolve¶

The resource is being resolved or blitted, as both source and destination.

ResolveSrc¶

The resource is being resolved or blitted from.

ResolveDst¶

The resource is being resolved or blitted to.

Copy¶

The resource is being copied, as both source and destination.

CopySrc¶

The resource is being copied from.

CopyDst¶

The resource is being copied to.

Barrier¶

The resource is being specified in a barrier, as defined in Vulkan or Direct3D 12.

CPUWrite¶

The resource is written from the CPU, either directly as mapped memory or indirectly via a synchronous update.

renderdoc.ResUsage(stage)¶

Calculate the ResourceUsage value for read-only resource use at a given shader stage.

Parameters:

stage# (ShaderStage) – The shader stage.

Returns:

The value for read-only resource usage at a given shader stage.

Return type:

ResourceUsage

renderdoc.RWResUsage(stage)¶

Calculate the ResourceUsage value for read-write resource use at a given shader stage.

Parameters:

stage# (ShaderStage) – The shader stage.

Returns:

The value for read-write resource usage at a given shader stage.

Return type:

ResourceUsage

renderdoc.CBUsage(stage)¶

Calculate the ResourceUsage value for constant buffer use at a given shader stage.

Parameters:

stage# (ShaderStage) – The shader stage.

Returns:

The value for constant buffer usage at a given shader stage.

Return type:

ResourceUsage

Texture Saving¶

class renderdoc.TextureSave¶

class renderdoc.TextureSave(other: TextureSave)

Describes a texture to save and how to map it to the destination file format.

alpha¶

Controls handling of alpha channel, only relevant for file formats that don’t have alpha.

It is an AlphaMapping that controls what behaviour to use.

Type:

AlphaMapping

alphaCol¶

The background color if alpha is set to AlphaMapping.BlendToColor.

Type:

FloatVector

channelExtract¶

Selects a single component out of a texture to save as grayscale, or -1 to save all.

Type:

int

comp¶

Controls black/white point mapping for output formats that are normal 8-bit SRGB, values are truncated so that values below the black point and above the white point are clamped, and the values in between are evenly distributed.

Type:

TextureComponentMapping

destType¶

The FileType to use when saving to the destination file.

Type:

FileType

jpegQuality¶

The quality to use when saving to a JPG file. Valid values are between 1 and 100.

Type:

int

mip¶

Selects the mip to be written out.

If set to -1 then all mips are written, where allowed by file format. If not allowed, mip 0 is written

Type:

int

resourceId¶

The ResourceId of the texture to save.

Type:

ResourceId

sample¶

Controls mapping for multisampled textures (ignored if texture is not multisampled)

Type:

TextureSampleMapping

slice¶

Controls mapping for arrayed textures (ignored if texture is not arrayed)

Type:

TextureSliceMapping

typeCast¶

If possible interpret the texture with this type instead of its normal type.

If set to CompType.Typeless then no cast is applied, otherwise where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values.

Type:

CompType

class renderdoc.FileType(value)¶

The format of an image file

DDS¶

A DDS file

PNG¶

A PNG file

JPG¶

A JPG file

BMP¶

A BMP file

TGA¶

A TGA file

HDR¶

An HDR file

EXR¶

An EXR file

Raw¶

Raw data, just the bytes of the image tightly packed with no metadata or compression/encoding

class renderdoc.AlphaMapping(value)¶

What to do with the alpha channel from a texture while saving out to a file.

Discard¶

Completely discard the alpha channel and only write RGB to the file.

BlendToColor¶

Blend to the primary background color using alpha.

BlendToCheckerboard¶

Blend to a checkerboard pattern with the primary and secondary background colors.

Preserve¶

Preserve the alpha channel and save it to the file by itself.

This is only valid for file formats that support alpha channels.

class renderdoc.TextureComponentMapping¶

class renderdoc.TextureComponentMapping(other: TextureComponentMapping)

How to map components to normalised [0, 255] for saving to 8-bit file formats.

blackPoint¶

The value that should be mapped to 0

Type:

float

whitePoint¶

The value that should be mapped to 255

Type:

float

class renderdoc.TextureSampleMapping¶

class renderdoc.TextureSampleMapping(other: TextureSampleMapping)

How to map multisampled textures for saving to non-multisampled file formats.

ResolveSamples¶

Value for sampleIndex if the samples should be averaged.

mapToArray¶

True if the samples should be mapped to array slices. A multisampled array expands each slice in-place, so it would be slice 0: sample 0, slice 0: sample 1, slice 1: sample 0, etc.

This then follows the mapping for array slices as with any other array texture. sampleIndex is ignored.

Type:

bool

sampleIndex¶

If mapToArray is False this selects which sample should be extracted to treat as a normal 2D image. If set to ResolveSamples then instead there’s a default average resolve.

Type:

int

class renderdoc.TextureSliceMapping¶

class renderdoc.TextureSliceMapping(other: TextureSliceMapping)

How to map array textures for saving to non-arrayed file formats.

If sliceIndex is -1, cubeCruciform == slicesAsGrid == False and the file format doesn’t support saving all slices, only slice 0 is saved.

cubeCruciform¶

Write out 6 slices in a cruciform pattern:

     +----+
     | +y |
     |    |
+----+----+----+----+
| -x | +z | +x | -z |
|    |    |    |    |
+----+----+----+----+
     | -y |
     |    |
     +----+

With the gaps filled in with transparent black.

Type:

bool

sliceGridWidth¶

The width of a grid if slicesAsGrid is True.

Type:

int

sliceIndex¶

Selects the (depth/array) slice to save.

If this is -1, then all slices are written out as detailed below. This is only supported in formats that don’t support slices natively, and will be done in RGBA8.

Type:

int

slicesAsGrid¶

If True, write out the slices as a 2D grid with the width given in sliceGridWidth. Any empty slices in the grid are written as transparent black.

Type:

bool

Pixel History¶

class renderdoc.PixelModification¶

class renderdoc.PixelModification(other: PixelModification)

An attempt to modify a pixel by a particular event.

CheckDepthTestQuantised(depthBits, depthFunc)¶

Update the depth-test failure state based on known shader output depth value and preMod reference value, quantised to a certain number of depth bits with epsilon.

This is primarily used internally and should not be needed to be called externally.

Parameters:

• depthBits# (int) – How many bits are in the depth buffer: 16, 24 or 32.

• depthFunc# (CompareFunction) – The comparison function active for the depth test

Passed()¶

Determine if this fragment passed all tests and wrote to the texture.

Returns:

True if it passed all tests, False if it failed any.

Return type:

bool

backfaceCulled¶

True if the backface culling test eliminated this fragment.

Type:

bool

depthBoundsFailed¶

True if depth bounds clipping eliminated this fragment.

Type:

bool

depthClipped¶

True if depth near/far clipping eliminated this fragment.

Type:

bool

depthTestFailed¶

True if depth testing eliminated this fragment.

Type:

bool

directShaderWrite¶

True if this event came as part of an arbitrary shader write.

Type:

bool

eventId¶

The eventId where the modification happened.

Type:

int

fragIndex¶

A 0-based index of which fragment this modification corresponds to, in the case that multiple fragments from a single action wrote to a pixel.

Type:

int

postMod¶

The value of the texture after this fragment ran.

Type:

ModificationValue

preMod¶

The value of the texture before this fragment ran.

This is valid only for the first fragment if multiple fragments in the same event write to the same pixel.

Type:

ModificationValue

predicationSkipped¶

True if predicated rendering skipped this call.

Type:

bool

primitiveID¶

The primitive that generated this fragment.

Type:

int

sampleMasked¶

True if the sample mask eliminated this fragment.

Type:

bool

scissorClipped¶

True if scissor clipping eliminated this fragment.

Type:

bool

shaderDiscarded¶

True if the pixel shader executed a discard on this fragment.

Type:

bool

shaderOut¶

The value that this fragment wrote from the pixel shader.

Type:

ModificationValue

stencilTestFailed¶

True if stencil testing eliminated this fragment.

Type:

bool

unboundPS¶

True if no pixel shader was bound at this event. On D3D APIs this may also mean a pixel shader exists but declares no output for the corresponding target and so is skipped.

On other APIs this is only reported if the pixel shader is entirely unbound but this means the output may have undefined values.

Type:

bool

viewClipped¶

True if viewport clipping eliminated this fragment.

Type:

bool

class renderdoc.ModificationValue¶

class renderdoc.ModificationValue(other: ModificationValue)

The value of pixel output at a particular event.

IsValid()¶

Returns:

Returns whether or not this modification value is valid.

Return type:

bool

SetInvalid()¶

Sets this modification value to be invalid.

col¶

The color value.

If the modifications are for a color target, the contents will all be 0.

Type:

PixelValue

depth¶

The depth value.

If depth is not available/in-use for this modification, it will be -1.0.

Type:

float

stencil¶

The stencil value.

If stencil is not available for this modification, it will be negative. If stencil is not available at all and not in use then the stencil value will be -1. If stencil was in use but can’t be determined due to the pixel history implementation using stencil for its own purposes, the value will be -2. This will only happen when looking at multiple modifications from the same event.

Type:

int

class renderdoc.PixelValue¶

class renderdoc.PixelValue(other: CounterValue)

The contents of an RGBA pixel.

floatValue¶

The RGBA value interpreted as float.

Type:

Tuple[float, float, float, float]

intValue¶

The RGBA value interpreted as 32-bit signed integer.

Type:

Tuple[int, int, int, int]

uintValue¶

The RGBA value interpreted as 32-bit unsigned integer.

Type:

Tuple[int, int, int, int]

Shader Debugging¶

class renderdoc.DebugPixelInputs¶

class renderdoc.DebugPixelInputs(other: DebugPixelInputs)

Contains the properties used to select which fragment to debug, used as an input to ReplayController.DebugPixel().

primitive¶

The primitive index.

Type:

int

sample¶

The multi-sampled sample.

Type:

int

view¶

The layered or multiview rendering view index.

Type:

int