API Reference: Replay Outputs¶

This is the API reference for the functions, classes, and enums in the renderdoc module which represents the underlying interface that the UI is built on top of. For more high-level information and instructions on using the python API, see Python API.

Sections

General
Window Configuration
Texture View
Mesh View

General ¶

class renderdoc.ReplayOutput¶

A stateful output handle that contains the current configuration for one particular view of the capture. This allows multiple outputs to run independently without interfering with each other.

The different types are enumerated in ReplayOutputType.

NoResult¶: No result was found in e.g. PickVertex().

AddThumbnail(window, textureId, sub, typeCast)¶

Sets up a thumbnail for displaying a particular texture with sensible defaults.

The window handle specified will be filled (in an aspect-ratio preserving way) with the texture.

If the window specified has been used for a thumbnail before, then the texture will be updated but otherwise nothing will be created and the existing internal data will be reused. This means that you can call this function multiple times to just change the texture.

Should only be called for texture outputs.

Parameters

window# (WindowingData) – A WindowingData describing the native window.
textureId# (ResourceId) – The texture ID to display in the thumbnail preview.
sub# (Subresource) – The subresource within this texture to use.
typeCast# (CompType) – 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.

Returns

A result indicating if the thumbnail was successfully created.

Return type

ResultDetails

ClearThumbnails()¶: Clear and release all thumbnails associated with this output. See AddThumbnail().

DisablePixelContext()¶: Disable the pixel context view from rendering.

Display()¶

Render to the window handle specified when the output was created.

This will also render any thumbnails and the pixel context, if enabled.

DrawThumbnail(width, height, textureId, sub, typeCast)¶

Draws a thumbnail for a particular texture with sensible defaults and returns an RGBA8 byte buffer for display. This does not render to a window but internally to a texture which is read back from the GPU.

Should only be called for texture outputs.

Parameters

width# (int) – The width of the desired thumbnail.
height# (int) – The height of the desired thumbnail.
textureId# (ResourceId) – The texture ID to display in the thumbnail preview.
sub# (Subresource) – The subresource within this texture to use.
typeCast# (CompType) – 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.

Returns

A buffer with the thumbnail RGBA8 data if successful, or empty if something went wrong.

Return type

bytes

GetCustomShaderTexID()¶

Retrieves the ResourceId containing the contents of the texture after being passed through a custom shader pass.

Should only be called for texture outputs.

Returns: The ResourceId assigned to the texture with the results of the custom shader.
Return type: ResourceId

GetDebugOverlayTexID()¶

Retrieves the ResourceId containing the contents of the debug overlay rendering (if enabled).

Should only be called for texture outputs.

Returns: The ResourceId assigned to the texture with the debug overlay.
Return type: ResourceId

GetDimensions()¶

Retrieve the current dimensions of the output.

Returns: The current width and height of the output.
Return type: Tuple[int,int]

PickVertex(x, y)¶

Retrieves the vertex and instance that is under the cursor location, when viewed relative to the current window with the current mesh display configuration.

Note

X and Y co-ordinates are always considered to be top-left, even on GL, for consistency between APIs and preventing the need for API-specific code in most cases. This means if co-ordinates are fetched from e.g. viewport or scissor data or other GL pipeline state which is perhaps in bottom-left co-ordinates, care must be taken to translate them.

Should only be called for mesh outputs.

Parameters

x# (int) – The x co-ordinate to pick from.
y# (int) – The y co-ordinate to pick from.

Returns

A tuple with the first value being the vertex index in the mesh, and the second value being the instance index. The values are set to NoResult if no vertex was found,

Return type

Tuple[int,int]

ReadbackOutputTexture()¶

Read the output texture back as byte data. Primarily useful for headless outputs where the output data is not displayed anywhere natively.

Returns: The output texture data as tightly packed RGB 3-byte data.
Return type: bytes

SetDimensions(width, height)¶

Sets the dimensions of the output, useful only for headless outputs that don’t have a backing window which don’t have any implicit dimensions. This allows configuring a virtual viewport which is useful for operations like picking vertices that depends on the output dimensions.

Note

For outputs with backing windows, this will be ignored.

Parameters

width# (int) – The width to use.
height# (int) – The height to use.

SetMeshDisplay(config)¶

Sets the configuration for a mesh output.

Parameters: config# (MeshDisplay) – The configuration.

SetPixelContext(window)¶

Sets up a zoomed in pixel context view around a particular pixel selection.

The texture rendering uses the configuration specified in SetTextureDisplay() except with a fixed high zoom value and a fixed position, see SetPixelContextLocation().

Should only be called for texture outputs.

Parameters: window# (WindowingData) – A WindowingData describing the native window.
Returns: A result indicating if the pixel context was successfully configured.
Return type: ResultDetails

SetPixelContextLocation(x, y)¶

Sets the pixel that the pixel context should be centred on.

Should only be called for texture outputs.

Parameters

x# (int) – The X co-ordinate to highlight.
y# (int) – The Y co-ordinate to highlight.

SetTextureDisplay(config)¶

Sets the configuration for a texture output.

Parameters: config# (TextureDisplay) – The configuration.

Shutdown()¶

Shutdown this output.

It’s optional to call this, as calling ReplayController.Shutdown() will shut down all of its outputs.

class renderdoc.ReplayOutputType(value)¶

The type of ReplayOutput to create

Headless¶: A headless output that does nothing to display to windows but can still be controlled and queried the same way

Texture¶: An output that is used for displaying textures, thumbnails and pixel context

Mesh¶: An output that will display mesh data previews

renderdoc.SetColors(darkChecker, lightChecker, darkTheme)¶

Configure the default colours used for checkerboards, this can broadly speaking help match the replay rendering to the overall theme of the replay application.

Parameters

darkChecker# (FloatVector) – The color of dark squares in checkerboard patterns.
lightChecker# (FloatVector) – The color of light squares in checkerboard patterns.
darkTheme# (bool) – True if the theme is a ‘dark’ theme, used to pick different contrasting colors. False if the theme is ‘light’ and normal colors are used.

Window Configuration ¶

class renderdoc.WindowingData¶: An opaque structure created to hold windowing setup data

class renderdoc.WindowingSystem(value)¶

Specifies a windowing system to use for creating an output window.

Unknown¶: Unknown window type, no windowing data is passed and no native window is described.

Headless¶: The windowing data doesn’t describe a real window but a virtual area, allowing all normal output rendering to happen off-screen. See CreateHeadlessWindowingData().

Win32¶: The windowing data refers to a Win32 window. See CreateWin32WindowingData().

Xlib¶: The windowing data refers to an Xlib window. See CreateXLibWindowingData().

XCB¶: The windowing data refers to an XCB window. See CreateXCBWindowingData().

Android¶: The windowing data refers to an Android window. See CreateAndroidWindowingData().

MacOS¶: The windowing data refers to a MacOS / OS X NSView & CALayer that is Metal/GL compatible. See CreateMacOSWindowingData().

Wayland¶: The windowing data refers to an Wayland window. See CreateWaylandWindowingData().

renderdoc.CreateHeadlessWindowingData(width, height)¶

Create a WindowingData for no backing window, it will be headless.

Parameters

width# (int) – The initial width for this virtual window.
height# (int) – The initial height for this virtual window.

Returns

A WindowingData corresponding to an ‘empty’ backing window.

Return type

WindowingData

renderdoc.CreateWin32WindowingData(window)¶

Create a WindowingData for a Win32 HWND handle.

Parameters: window# (HWND) – The native HWND handle for this window.
Returns: A WindowingData corresponding to the given window.
Return type: WindowingData

renderdoc.CreateXlibWindowingData(display, window)¶

Create a WindowingData for an Xlib Drawable handle.

Parameters

display# (Display) – The Display connection used for this window.
window# (Drawable) – The native Drawable handle for this window.

Returns

A WindowingData corresponding to the given window.

Return type

WindowingData

renderdoc.CreateXCBWindowingData(connection, window)¶

Create a WindowingData for an XCB xcb_window_t handle.

Parameters

connection# (xcb_connection_t) – The xcb_connection_t connection used for this window.
window# (xcb_window_t) – The native xcb_window_t handle for this window.

Returns

A WindowingData corresponding to the given window.

Return type

WindowingData

renderdoc.CreateWaylandWindowingData(display, window)¶

Create a WindowingData for an Wayland wl_surface handle.

Parameters

display# (wl_display) – The wl_display connection used for this window.
window# (wl_surface) – The native wl_surface handle for this window.

Returns

A WindowingData corresponding to the given window.

Return type

WindowingData

renderdoc.CreateAndroidWindowingData(window)¶

Create a WindowingData for an Android ANativeWindow handle.

Parameters: window# (ANativeWindow) – The native ANativeWindow handle for this window.
Returns: A WindowingData corresponding to the given window.
Return type: WindowingData

renderdoc.CreateMacOSWindowingData(view, layer)¶

Create a WindowingData for an metal/opengl-compatible macOS CALayer handle and NSView handle (as void pointers).

Parameters

view# (NSView) – The native NSView handle for this window.
layer# (CALayer) – The native CALayer handle for this window.

Returns

A WindowingData corresponding to the given window.

Return type

WindowingData

Texture View ¶

class renderdoc.TextureDisplay¶

Describes how to render a texture preview of an image. Describes the zoom and pan settings for the texture when rendering on a particular output, as well as the modification and selection of a particular subresource (such as array slice, mip or multi-sampled sample).

Note

X and Y co-ordinates are always considered to be top-left, even on GL, for consistency between APIs and preventing the need for API-specific code in most cases. This means if co-ordinates are fetched from e.g. viewport or scissor data or other GL pipeline state which is perhaps in bottom-left co-ordinates, care must be taken to translate them.

ResolveSamples¶: Value for sampleIdx if the samples should be averaged.

alpha¶

True if the alpha channel should be visible. If enabled with any of RGB, the texture will be blended to the background color or checkerboard.

If only one channel is selected, it will be rendered in grayscale

backgroundColor¶

The background color to use behind the texture display.

If set to (0, 0, 0, 0) the global checkerboard colors are used.

Type: FloatVector

blue¶

True if the blue channel should be visible.

If only one channel is selected, it will be rendered in grayscale

customShaderId¶

The ResourceId of a custom shader to use when rendering.

See ReplayController.BuildCustomShader() for creating an appropriate custom shader.

decodeYUV¶: True if the texture should be decoded as if it contains YUV data.

flipY¶: True if the texture should be flipped vertically when rendering.

green¶

True if the green channel should be visible.

If only one channel is selected, it will be rendered in grayscale

hdrMultiplier¶: If >= 0.0 the RGBA values will be viewed as HDRM with this as the multiplier.

linearDisplayAsGamma¶

True if the texture should be interpreted as gamma.

See the FAQ entry.

overlay¶: Selects a DebugOverlay to draw over the top of the texture.

rangeMax¶: The value in each channel to map to the white point.

rangeMin¶: The value in each channel to map to the black point.

rawOutput¶

True if the rendered image should be as close as possible in value to the input.

This is primarily useful when rendering to a floating point target for retrieving pixel data from the input texture in cases where it isn’t easy to directly fetch the input texture data.

red¶

True if the red channel should be visible.

If only one channel is selected, it will be rendered in grayscale

resourceId¶: The ResourceId of the texture to display.

scale¶

The scale to apply to the texture when rendering as a floating point value.

1.0 corresponds to 100%

subresource¶

The subresource of the texture to display.

If the Subresource.sample member is set to ResolveSamples then a default resolve will be performed that averages all samples.

Type: Subresource

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.

xOffset¶: The offset to pan in the X axis.

yOffset¶: The offset to pan in the Y axis.

class renderdoc.DebugOverlay(value)¶

The type of overlay image to render on top of an existing texture view, for debugging purposes.

In overlays that refer to the ‘current pass’, for any API that does not have an explicit notion of a render pass, it is defined as all previous drawcalls that render to the same set of render targets. Note that this is defined independently from any marker regions.

See the documentation for this feature.

NoOverlay¶: No overlay should be rendered.

Drawcall¶

An overlay highlighting the area rasterized by the drawcall on screen, no matter what tests or processes may be discarding the pixels actually rendered.

The rest of the image should be dimmed slightly to make the draw on screen clearer.

Wireframe¶: Similar to the Drawcall overlay, this should render over the top of the image, but showing the wireframe of the object instead of a solid render.

Depth¶

This overlay shows pixels from the object that passed all depth tests in green, and pixels that failed any depth test in red.

If some pixel is overwritten more than once by the object, if any of the samples passed the result will be green (i.e. the failure overlay is conservative).

Stencil¶

This overlay shows pixels from the object that passed all stencil tests in green, and pixels that failed any stencil test in red.

If some pixel is overwritten more than once by the object, if any of the samples passed the result will be green (i.e. the failure overlay is conservative).

BackfaceCull¶

This overlay shows pixels from the object that passed backface culling in green, and pixels that were backface culled in red.

If some pixel is overwritten more than once by the object, if any of the samples passed the result will be green (i.e. the failure overlay is conservative).

ViewportScissor¶: This overlay shows a rectangle on screen corresponding to both the current viewport, and if enabled the current scissor as well.

NaN¶: This overlay renders the image in greyscale using a simple luminosity calculation, then highlights any pixels that are NaN in red, any that are positive or negative infinity in green, and any that are negative in blue.

Clipping¶

This overlay renders the image in greyscale using a simple luminosity calculation, then highlights any pixels that are currently above the white point in green and any pixels that are below the black point in red.

This is relative to the current black and white points used to display the texture.

ClearBeforePass¶

This overlay clears the bound render targets before the current pass, allowing you to see only the contribution from the current pass.

Note only color targets are cleared, depth-stencil targets are unchanged so any depth or stencil tests will still pass or fail in the same way.

ClearBeforeDraw¶: This is the same as the ClearBeforePass overlay, except it clears before the current drawcall, not the current pass.

QuadOverdrawPass¶

This overlay shows pixel overdraw using 2x2 rasterized quad granularity instead of single-pixel overdraw. This represents the number of times the pixel shader was invoked along triangle edges even if each pixel is only overdrawn once.

The overlay accounts for all draws in the current pass.

QuadOverdrawDraw¶: This is the same as the QuadOverdrawPass overlay, except it only shows the overdraw for the current drawcall, not the current pass.

TriangleSizePass¶

This overlay shows the size of each triangle, starting from triangles with area 16 (4x4) and above at the lower end to triangles with area 0.125 (1/8th pixel) at the upper end.

The overlay accounts for all draws in the current pass.

TriangleSizeDraw¶: This is similar to the TriangleSizePass overlay, except it only shows the triangle size for the current drawcall, not the current pass.

Mesh View ¶

class renderdoc.MeshDisplay¶

Describes how to render a mesh preview of one or more meshes. Describes the camera configuration as well as what options to use when rendering both the current mesh, and any other auxilliary meshes.

NoHighlight¶: Value for highlightVert if no vertex should be highlighted.

aspect¶: The aspect ratio to use when calculating a perspective projection matrix.

axisMapping¶

The axis mapping to apply to the mesh.

Type: AxisMapping

cam¶

The camera to use when rendering all of the meshes.

Type: Camera

curInstance¶: The index of the currently selected instance in the drawcall.

curView¶: The index of the currently selected multiview view in the drawcall.

exploderScale¶: Scales the exploded vertex displacement.

fov¶: The field of view to use when calculating a perspective projection matrix.

highlightVert¶: The index of the vertex to highlight, or NoHighlight to select no vertex.

maxBounds¶

The maximum co-ordinates in each axis of the mesh bounding box.

Type: FloatVector

minBounds¶

The minimum co-ordinates in each axis of the mesh bounding box.

Type: FloatVector

ortho¶: True if the projection matrix to use when unprojecting vertex positions is orthographic.

position¶

The configuration for the primary mesh’s position data.

Type: MeshFormat

second¶

The configuration for the primary mesh’s secondary data, if used for solid shading.

Type: MeshFormat

showAllInstances¶: True if all instances in the drawcall should be drawn as secondary meshes.

showBBox¶: True if the bounding box around the mesh should be rendered.

showPrevInstances¶: True if all previous instances in the drawcall should be drawn as secondary meshes.

showWholePass¶: True if all draws in the current pass up to the current draw should be drawn as secondary meshes.

type¶: The MeshDataStage where this mesh data comes from.

visualisationMode¶: The visualisation mode to use when rendering the current mesh.

vtxExploderSliderSNorm¶: Displace/explode vertices to help visualise vertex reuse vs disjointedness.

wireframeDraw¶: True if the wireframe of the mesh should be rendered as well as solid shading.

class renderdoc.MeshDataStage(value)¶

Describes a particular stage in the geometry transformation pipeline.

VSIn¶: The inputs to the vertex shader described by the explicit API vertex input bindings.

VSOut¶: The outputs from the vertex shader corresponding one-to-one to the input elements.

GSOut¶

The final output from the last stage in the pipeline, be that tessellation or geometry shader.

This has possibly been expanded/multiplied from the inputs

TaskOut¶: Data from a task/amplification shader.

AmpOut¶: Data from an amplification shader (alias for TaskOut).

MeshOut¶: Data from a mesh shader.

class renderdoc.MeshletSize¶

The size information for a meshlet.

numIndices¶: The number of indices in the meshlet.

numVertices¶: The number of vertices in this meshlet. This may be larger or smaller than the number of indices.

class renderdoc.TaskGroupSize¶

The size information for a task group.

x¶: The size in the x dimension.

y¶: The size in the y dimension.

z¶: The size in the z dimension.

class renderdoc.MeshFormat¶

Contains the details of a single element of data (such as position or texture co-ordinates) within a mesh.

allowRestart¶: True if the primitive restart index feature should be used.

baseVertex¶: For indexed meshes, a value added to each index before using it to read the vertex.

dispatchSize¶

The size of the dispatch that launched a meshlet based draw.

Only valid for the task stage if task shaders are used.

Note

This is present because the dispatch size at the time of the mesh output fetch may not match the ActionDescription.dispatchDimension due to non-determinism in the capture. Being present here allows the replay to process the mesh output validly in itself without seeing a mismatch.

Type: Tuple[int,int,int]

farPlane¶: The far plane for the projection matrix.

flipY¶: True if there is an implicit Y-flip to account for in the projection.

format¶

The format description of this mesh components elements.

Type: ResourceFormat

indexByteOffset¶: The offset in bytes where the indices start in idxbuf.

indexByteSize¶: The number of bytes to use from the index buffer. Only valid on APIs that allow it.

indexByteStride¶: The width in bytes of each index. Valid values are 1 (depending on API), 2 or 4.

indexResourceId¶: The ResourceId of the index buffer that goes with this mesh element.

instStepRate¶: The number of instances to render with the same value. See instanced.

instanced¶: True if this mesh element comes from instanced data. See instStepRate.

meshColor¶

The color to use for rendering the wireframe of this mesh element.

Type: FloatVector

meshletIndexOffset¶

If showing a set of meshlets that don’t start from index 0, this is the number of vertices to consider skipped before meshletSizes - equivalent to baseVertex.

Primarily useful for keeping a consistent colouring of meshlets when filtering to a subset

API Reference: Replay Outputs¶

General¶

Window Configuration¶

Texture View¶

Mesh View¶

General ¶

Window Configuration ¶

Texture View ¶

Mesh View ¶