# Replay Analysis

Contents

- Replay Analysis

  - Frame and Drawcalls

  - Debug Messages

  - Resource Usage

  - Texture Saving

  - Pixel History

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

  `indexByteWidth`

    The width in bytes of each index.

    Valid values are 1 (depending on API), 2 or 4, or 0 if the drawcall is not an indexed draw.

  `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

  `topology`

    The `Topology` used in this drawcall.

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

  `callstack`

    The addresses in the CPU callstack where this function was called.

    Type

      List[int]

  `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]