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:
- 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:
- 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:
- 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:
- 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.
- 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, seeSetPixelContextLocation()
.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:
- SetPixelContextLocation(x, y)¶
Sets the pixel that the pixel context should be centred on.
Should only be called for texture outputs.
- 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:
- Returns:
A
WindowingData
corresponding to an ‘empty’ backing window.- Return type:
- renderdoc.CreateWin32WindowingData(window)¶
Create a
WindowingData
for a Win32HWND
handle.- Parameters:
window# (HWND) – The native
HWND
handle for this window.- Returns:
A
WindowingData
corresponding to the given window.- Return type:
- renderdoc.CreateXlibWindowingData(display, window)¶
Create a
WindowingData
for an XlibDrawable
handle.- Parameters:
- Returns:
A
WindowingData
corresponding to the given window.- Return type:
- renderdoc.CreateXCBWindowingData(connection, window)¶
Create a
WindowingData
for an XCBxcb_window_t
handle.- Parameters:
- Returns:
A
WindowingData
corresponding to the given window.- Return type:
- renderdoc.CreateWaylandWindowingData(display, window)¶
Create a
WindowingData
for an Waylandwl_surface
handle.- Parameters:
- Returns:
A
WindowingData
corresponding to the given window.- Return type:
- renderdoc.CreateGgpWindowingData()¶
Create a
WindowingData
for a GGP application.- Returns:
A
WindowingData
corresponding to the given system.- Return type:
- renderdoc.CreateAndroidWindowingData(window)¶
Create a
WindowingData
for an AndroidANativeWindow
handle.- Parameters:
window# (ANativeWindow) – The native
ANativeWindow
handle for this window.- Returns:
A
WindowingData
corresponding to the given window.- Return type:
- renderdoc.CreateMacOSWindowingData(view, layer)¶
Create a
WindowingData
for an metal/opengl-compatible macOSCALayer
handle andNSView
handle (as void pointers).- Parameters:
- Returns:
A
WindowingData
corresponding to the given window.- Return type:
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:
- 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 to100%
- subresource¶
The subresource of the texture to display.
If the
Subresource.sample
member is set toResolveSamples
then a default resolve will be performed that averages all samples.- Type:
- 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 area0.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:
- 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:
- minBounds¶
The minimum co-ordinates in each axis of the mesh bounding box.
- Type:
- 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:
- second¶
The configuration for the primary mesh’s secondary data, if used for solid shading.
- Type:
- 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:
- 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.
- instanced¶
True
if this mesh element comes from instanced data. SeeinstStepRate
.
- meshColor¶
The color to use for rendering the wireframe of this mesh element.
- Type:
- 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
- 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:
- GetPosition()¶
Retrieves the position of the camera
- Returns:
The position vector of the camera. W is set to 1
- Return type:
- 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:
- 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:
- 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.
- 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.
- 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.
- 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:
- yAxis¶
The mapping of the y axis.
- Type:
- zAxis¶
The mapping of the z axis.
- Type:
- 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: