Replay Outputs

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

GGP

The windowing data refers to an GGP surface. See CreateGgpWindowingData().

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.CreateGgpWindowingData()

Create a WindowingData for a GGP application.

Returns:

A WindowingData corresponding to the given system.

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.

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.

solidShadeMode

The solid shading mode to use when rendering the current mesh.

type

The MeshDataStage where this mesh data comes from.

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.

Unknown

Unknown or invalid stage.

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

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.

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

nearPlane

The near plane for the projection matrix.

numIndices

The number of vertices in the mesh.

restartIndex

The primitive restart index to use, if possible. See allowRestart.

showAlpha

True if the alpha component of this element should be used.

status

A string with the status of this mesh format - only used when a mesh format is returned to the application detailing e.g. vertex output data.

An empty string indicates no errors/problems.

Type:

str

topology

The Topology that describes the primitives in this mesh.

unproject

True if this mesh element contains post-projection positional data.

vertexByteOffset

The offset in bytes to the start of the vertex data.

vertexByteSize

The number of bytes to use from the vertex buffer. Only valid on APIs that allow it.

vertexByteStride

The stride in bytes between the start of one vertex and the start of another.

vertexResourceId

The ResourceId of the vertex buffer containing this mesh element.

class renderdoc.SolidShade(value)

What kind of solid shading to use when rendering a mesh.

NoSolid

No solid shading should be done.

Solid

The mesh should be rendered in a single flat unshaded color.

Lit

The mesh should be rendered with face normals generated on the primitives and used for lighting.

Secondary

The mesh should be rendered using the secondary element as color.

class renderdoc.Camera

A handle to a camera controller, used for user interaction and controlling a view of a 3D scene.

GetForward()

Retrieves the forward vector of the camera, in the positive Z direction.

Returns:

The forward vector of the camera. W is set to 1

Return type:

FloatVector

GetPosition()

Retrieves the position of the camera

Returns:

The position vector of the camera. W is set to 1

Return type:

FloatVector

GetRight()

Retrieves the right vector of the camera, in the positive X direction.

Returns:

The right vector of the camera. W is set to 1

Return type:

FloatVector

GetUp()

Retrieves the up vector of the camera, in the positive Y direction.

Returns:

The up vector of the camera. W is set to 1

Return type:

FloatVector

ResetArcball()

Reset the arcball to defaults.

RotateArcball(ax, ay, bx, by)

Rotates the arcball based on relative window co-ordinates.

The co-ordinates are in pixels and represent the old/new co-ordinates of the mouse cursor over the drag.

Parameters:

• ax (float) – The X co-ordinate of the previous mouse position.

• ay (float) – The Y co-ordinate of the previous mouse position.

• bx (float) – The X co-ordinate of the new mouse position.

• by (float) – The Y co-ordinate of the new mouse position.

SetArcballDistance(dist)

Sets the distance in units the arcball camera sits away from the lookat position.

Parameters:

dist (float) – The distance of the camera from the lookat position.

SetFPSRotation(x, y, z)

Sets the rotation for an FPS camera.

It is invalid to call this function for arcball cameras.

Parameters:

• x (float) – The rotation around the X axis (pitch).

• y (float) – The rotation around the Y axis (yaw).

• z (float) – The rotation around the Z axis (roll).

SetPosition(x, y, z)

Sets the position for the camera, either arcball or FPS.

For arcball cameras, this sets the lookat position at the centre of the arcball.

For FPS look cameras, this sets the position of the camera in space.

Parameters:

• x (float) – The X co-ordinate of the position.

• y (float) – The Y co-ordinate of the position.

• z (float) – The Z co-ordinate of the position.

Shutdown()

Closes the camera handle.

class renderdoc.CameraType(value)

The type of camera controls for an Camera.

Arcball

Arcball controls that rotate and zoom around the origin point.

FPSLook

Traditional FPS style controls with movement in each axis relative to the current look direction.

class renderdoc.AxisMapping

A transform to map the x, y, and z axes to new directions.

xAxis

The mapping of the x axis.

Type:

FloatVector

yAxis

The mapping of the y axis.

Type:

FloatVector

zAxis

The mapping of the z axis.

Type:

FloatVector

renderdoc.InitCamera(type)

Create a new camera of a given type.

Parameters:

type (CameraType) – The type of controls to use

Returns:

The handle to the new camera.

Return type:

Camera