Replay Analysis

Frame and Drawcalls

class renderdoc.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.

compressedFileSize

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

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.

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.

initDataSize

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

persistentSize

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

stats

The frame statistics.

Type

FrameStatistics

uncompressedFileSize

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

class renderdoc.DrawcallDescription

Describes the properties of a drawcall, dispatch, debug marker, or similar event.

Reset()

Resets the drawcall back to a default/empty state.

baseVertex

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

children

The child drawcalls below this one, if it’s a marker region or multidraw type draw.

Type

List[DrawcallDescription]

copyDestination

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

copyDestinationSubresource

Which part of copyDestination is used.

Type

Subresource

copySource

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

copySourceSubresource

Which part of copySource is used.

Type

Subresource

depthOut

The resource used for depth output - see outputs.

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 draw in an call with multiple draws, e.g. an indirect draw.

0 if not part of a multi-draw.

drawcallId

A 1-based index of this drawcall relative to other drawcalls.

eventId

The eventId that actually produced the drawcall.

events

The events that happened since the previous drawcall.

Type

List[APIEvent]

flags

A set of DrawFlags properties describing what kind of drawcall this is.

indexOffset

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

instanceOffset

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

markerColor

A RGBA color specified by a debug marker call.

Type

FloatVector

name

The name of this drawcall. Typically a summarised/concise list of parameters.

Note

For drawcalls, the convention is to list primary parameters (vertex/index count, instance count) and omit secondary parameters (vertex offset, instance offset).

next

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

Type

DrawcallDescription

numIndices

The number of indices or vertices as appropriate for the drawcall. 0 if not used.

numInstances

The number of instances for the drawcall. 0 if not used.

outputs

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

Type

Tuple[ResourceId,…]

parent

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

Type

DrawcallDescription

previous

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

Type

DrawcallDescription

vertexOffset

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

class renderdoc.DrawFlags(value)

A set of flags describing the properties of a particular drawcall.

NoFlags

The drawcall has no special properties.

Clear

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

Drawcall

The drawcall renders primitives using the graphics pipeline.

Dispatch

The drawcall issues a number of compute workgroups.

CmdList

The drawcall calls into a previously recorded child command list.

SetMarker

The drawcall inserts a single debugging marker.

PushMarker

The drawcall begins a debugging marker region that has children.

PopMarker

The drawcall ends a debugging marker region.

Note

Drawcalls with this flag will not be exposed and it is only used internally for tracking markers.

Present

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

MultiDraw

The drawcall is a multi-draw that contains several specified child draws.

Copy

The drawcall performs a resource copy operation.

Resolve

The drawcall performs a resource resolve or blit operation.

GenMips

The drawcall performs a resource mip-generation operation.

PassBoundary

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

UseIBuffer

The drawcall uses an index buffer.

Instanced

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

Auto

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

Indirect

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

ClearColor

The drawcall clears a color target.

ClearDepthStencil

The drawcall clears a depth-stencil target.

BeginPass

The drawcall marks the beginning of a render pass.

EndPass

The drawcall marks the end of a render pass.

APICalls

The drawcall does not contain any work directly, but is a ‘virtual’ draw inserted to encompass non-draw API calls that happened within a region, so they are included within the region where they occurred and not grouped into the next drawcall outside that region.

class renderdoc.APIEvent

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

chunkIndex

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

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 always increasing and positive, but they may not be contiguous - in some circumstances there may be gaps if some events are consumed entirely internally, such as debug marker pops which only modify the internal drawcall tree structures.

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

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.

Debug Messages

class renderdoc.DebugMessage

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

category

The category of this debug message.

description

The string contents of the message.

eventId

The eventId where this debug message was found.

messageID

An ID that identifies this particular debug message uniquely.

severity

The severity of this debug message.

source

The source of this debug message.

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

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

eventId

The eventId where this usage happened.

usage

The ResourceUsage in question.

view

An optional ResourceId identifying the view through which the use happened.

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 used.

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.

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.

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.

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.

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

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.

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.

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.

jpegQuality

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

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

resourceId

The ResourceId of the texture to save.

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.

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

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

blackPoint

The value that should be mapped to 0

whitePoint

The value that should be mapped to 255

class renderdoc.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.

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.

class renderdoc.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.

sliceGridWidth

The width of a grid if slicesAsGrid is True.

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.

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.

Pixel History

class renderdoc.PixelModification

An attempt to modify a pixel by a particular event.

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.

depthBoundsFailed

True if depth bounds clipping eliminated this fragment.

depthClipped

True if depth near/far clipping eliminated this fragment.

depthTestFailed

True if depth testing eliminated this fragment.

directShaderWrite

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

eventId

The eventId where the modification happened.

fragIndex

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

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.

primitiveID

The primitive that generated this fragment.

sampleMasked

True if the sample mask eliminated this fragment.

scissorClipped

True if scissor clipping eliminated this fragment.

shaderDiscarded

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

shaderOut

The value that this fragment wrote from the pixel shader.

Type

ModificationValue

stencilTestFailed

True if stencil testing eliminated this fragment.

unboundPS

True if no pixel shader was bound at this event.

viewClipped

True if viewport clipping eliminated this fragment.

class renderdoc.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.

Type

PixelValue

depth

The depth output, as a float.

stencil

The stencil output, or -1 if not available.

class renderdoc.PixelValue

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]