# Replay Analysis

Contents

- Replay Analysis

  - Frame and Actions

  - Debug Messages

  - Resource Usage

  - Texture Saving

  - Pixel History

  - Shader Debuging

## Frame and Actions

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

  baseVertex

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

  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.

  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

  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.

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

    0 if not part of a multi-action.

  eventId

    The `eventId` that actually produced the action.

  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.

  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

  next

    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.

  numInstances

    The number of instances for a draw action. 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 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

  previous

    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.

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 the 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

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

  NoChunk

    No chunk is available.

  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.

  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.

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

  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

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

## Shader Debuging

class renderdoc.DebugPixelInputs

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

  primitive

    The primitive index.

  sample

    The multi-sampled sample.

  view

    The layered or multiview rendering view index.