API Reference: Replay Control¶

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

Initialisation and Shutdown
Capture File Access
GPU Enumeration
Replay Controller
Device Protocols
Remote Servers

Initialisation and Shutdown ¶

renderdoc.InitialiseReplay(globalEnv, args)¶

Initialises RenderDoc for replay. Replay API functions should not be called before this has been called. It should be called exactly once, and before shutdown you must call ShutdownReplay().

Parameters

globalEnv# (GlobalEnvironment) – The path to the new log file.
args# (List[str]) – Any extra command-line arguments.

renderdoc.ShutdownReplay()¶: Shutdown RenderDoc for replay. Replay API functions should not be called after this has been called. It is not safe to re-initialise replay after this function has been called so it should only be called at program shutdown. This function must only be called if InitialiseReplay() was previously called.

class renderdoc.GlobalEnvironment¶

Structure used for initialising environment in a replay application.

enumerateGPUs¶: Whether to enumerate available GPUs. If the replay program is only being used for internal operation where enumerating GPUs would be too expensive or problematic, it can be disabled here.

waylandDisplay¶: The handle to the wayland display to use internally. If left NULL, wayland cannot be used.

xlibDisplay¶: The handle to the X display to use internally. If left NULL, one will be opened.

class renderdoc.ResultCode(value)¶

The result from a replay operation such as opening a capture or connecting to a remote server.

Succeeded¶: The operation succeeded.

UnknownError¶: An unknown error occurred.

InternalError¶: An internal error occurred indicating a bug or unexpected condition.

FileNotFound¶: The specified file was not found.

InjectionFailed¶: Injection or hooking into the target process failed.

IncompatibleProcess¶: An incompatible process was found, e.g. a 32-bit process with 32-bit support not available.

NetworkIOFailed¶: A network I/O operation failed.

NetworkRemoteBusy¶: The remote side of the network connection was busy.

NetworkVersionMismatch¶: The other side of the network connection was not at a compatible version.

FileIOFailed¶: A filesystem I/O operation failed.

FileIncompatibleVersion¶: The capture file had an incompatible version.

FileCorrupted¶: The capture file is corrupted or otherwise unrecognisable.

FileUnrecognised¶: The file was not recognised as any supported file type.

ImageUnsupported¶: The image file or format is unrecognised or not supported in this form.

APIUnsupported¶: The API used in the capture is not supported.

APIInitFailed¶: The API used in the capture failed to initialise.

APIIncompatibleVersion¶: The API data in the capture had an incompatible version.

APIHardwareUnsupported¶: Current replaying hardware unsupported or incompatible with captured hardware.

APIDataCorrupted¶: While loading the capture for replay, the driver encountered corrupted or invalid serialised data.

APIReplayFailed¶: The API failed to replay the capture, with some runtime error that couldn’t be determined until the replay began.

JDWPFailure¶: Use of JDWP to launch and inject into the application failed, this most often indicates that some other JDWP-using program such as Android Studio is interfering.

AndroidGrantPermissionsFailed¶: Failed to grant runtime permissions when installing Android remote server.

AndroidABINotFound¶: Couldn’t determine supported ABIs when installing Android remote server.

AndroidAPKFolderNotFound¶: Couldn’t find the folder which contains the Android remote server APK.

AndroidAPKInstallFailed¶: Failed to install Android remote server for unknown reasons.

AndroidAPKVerifyFailed¶: Failed to install Android remote server.

RemoteServerConnectionLost¶: While replaying on a remote server, the connection was lost.

OutOfMemory¶: An out of memory error was encountered.

DeviceLost¶: A device lost fatal error was encountered.

DataNotAvailable¶: Data was requested through RenderDoc’s API which is not available.

InvalidParameter¶: An invalid parameter was passed to RenderDoc’s API.

CompressionFailed¶: Compression or decompression failed.

class renderdoc.ResultDetails¶

A general result from an operation with optional string information for failures.

This struct can be compared directly to a ResultCode for simple checks of status, and when converted to a string it includes the formatted result code and message as appropriate.

Note

The string information is only valid until ShutdownReplay() is called. After that point, accessing the string information is invalid and may crash. Care should be taken if ShutdownReplay() is called in response to an error, that the error code is read and saved.

Copying the ResultDetails instance is not sufficient to preserve the string information. It should be copied to e.g. a Tuple[ResultCode, str] instead.

Message()¶

For error codes, this will contain the stringified error code as well as any optional extra information that is available about the error.

Note

It’s not necessary to also display the stringified version of code as that is automatically included in the message.

Returns: A formatted message for failure codes, including the code itself.
Return type: str

OK()¶

A simple helper function to check if this result is successful.

Returns: Whether or not this result is successful
Return type: bool

code¶: The ResultDetails resulting from the operation, indicating success or failure.

Capture File Access ¶

renderdoc.OpenCaptureFile()¶

Create a handle for a capture file.

This function returns a new handle to a capture file. Once initialised by opening a file the handle can only be shut-down, it is not re-usable.

Returns: A handle to the specified path.
Return type: CaptureFile

class renderdoc.CaptureAccess¶

An interface for accessing a capture, possibly over a network connection. This is a subset of the functionality provided in CaptureFile which only supports import/export and construction of files.

DriverName()¶

Retrieves the name of the driver that was used to create this capture.

Returns: A simple string identifying the driver used to make the capture.
Return type: str

FindSectionByName(name)¶

Locate the index of a section by its name. Returns -1 if the section is not found.

This index should not be cached, as writing sections could re-order the indices.

Parameters: name# (str) – The name of the section to search for.
Returns: The index of the section, or -1 if not found.
Return type: int

FindSectionByType(type)¶

Locate the index of a section by its type. Returns -1 if the section is not found.

This index should not be cached, as writing sections could re-order the indices.

Parameters: type# (SectionType) – The type of the section to search for.
Returns: The index of the section, or -1 if not found.
Return type: int

GetAvailableGPUs()¶

Returns the list of available GPUs, that can be used in combination with ReplayOptions to force replay on a particular GPU.

Returns: The list of GPUs available.
Return type: List[GPUDevice]

GetResolve(callstack)¶

Retrieve the details of each stackframe in the provided callstack.

Must only be called after InitResolver() has returned True.

Parameters: callstack# (List[int]) – The integer addresses in the original callstack.
Returns: The list of resolved callstack entries as strings.
Return type: List[str]

GetSectionContents(index)¶

Get the raw byte contents of the specified section.

Parameters: index# (int) – The index of the section.
Returns: The raw contents of the section, if the index is valid.
Return type: bytes

GetSectionCount()¶

Retrieve the total number of available sections.

Returns: The number of sections in the capture
Return type: int

GetSectionProperties(index)¶

Get the describing properties of the specified section.

Parameters: index# (int) – The index of the section.
Returns: The properties of the section, if the index is valid.
Return type: SectionProperties

HasCallstacks()¶

Query if callstacks are available.

Returns: True if any callstacks are available, False otherwise.
Return type: bool

InitResolver(interactive, progress)¶

Begin initialising a callstack resolver, looking up symbol files and caching as necessary.

This function blocks while trying to initialise callstack resolving, so it should be called on a separate thread.

Parameters

interactive# (bool) – True if missing symbols or other prompts should be resolved interactively. If this is False, the function will not interact or block forever on user interaction and will always assume the input is effectively ‘cancel’ or empty. This may cause the symbol resolution to fail.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the resolver process. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

The result of the operation.

Return type

ResultDetails

WriteSection(props, contents)¶

Writes a new section with specified properties and contents. If an existing section already has the same type or name, it will be overwritten (two sections cannot share the same type or name).

Parameters

props# (SectionProperties) – The properties of the section to be written.
contents# (bytes) – The raw contents of the section.

Returns

The result of the operation.

Return type

ResultDetails

class renderdoc.CaptureFile¶

A handle to a capture file. Used for simple cheap processing and meta-data fetching without opening the capture for analysis.

Convert(filename, filetype, file, progress)¶

Converts the currently loaded file to a given format and saves it to disk.

This allows converting a native RDC to another representation, or vice-versa converting another representation back to native RDC.

Parameters

filename# (str) – The filename to save to.
filetype# (str) – The format to convert to.
file# (SDFile) – An optional SDFile with the structured data to source from. This is useful in case the format specifies that it doesn’t need buffers, and you already have a ReplayController open with the structured data. This saves the need to load the file again. If None then structured data will be fetched if not already present and used.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the conversion. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

The result of the operation.

Return type

ResultDetails

CopyFileTo(filename)¶

When a capture file is opened, an exclusive lock is held on the file on disk. This makes it impossible to copy the file to another location at the user’s request. Calling this function will copy the file on disk to a new location but otherwise won’t affect the capture handle. The new file will be locked, the old file will be unlocked - to allow deleting if necessary.

It is invalid to call this function if OpenFile() has not previously been called to open the file.

Parameters: filename# (str) – The filename to copy to.
Returns: The result of the file copy operation.
Return type: ResultDetails

GetCaptureFileFormats()¶

Returns the list of capture file formats.

Returns: The list of capture file formats available.
Return type: List[CaptureFileFormat]

GetStructuredData()¶

Returns the structured data for this capture.

The lifetime of this data is scoped to the lifetime of the capture handle, so it cannot be used after the handle is destroyed.

Returns: The structured data representing the file.
Return type: SDFile

GetThumbnail(type, maxsize)¶

Retrieves the embedded thumbnail from the capture.

Note

The only supported values for GetThumbnail.type are FileType.JPG, FileType.PNG, FileType.TGA, and FileType.BMP.

Parameters

type# (FileType) – The image format to convert the thumbnail to.
maxsize# (int) – The largest width or height allowed. If the thumbnail is larger, it’s resized.

Returns

The raw contents of the thumbnail, converted to the desired type at the desired max resolution.

Return type

Thumbnail

LocalReplaySupport()¶

Queries for how well a particular capture is supported on the local machine.

If the file was opened with a format other than native rdc this will always return no replay support.

Returns: How much support for replay exists locally.
Return type: ReplaySupport

OpenBuffer(buffer, filetype, progress)¶

Initialises the file handle from a raw memory buffer.

This may be useful if you don’t want to parse the whole file or already have the file in memory.

For the OpenBuffer.filetype parameter, see OpenFile().

Parameters

buffer# (bytes) – The buffer containing the data to process.
filetype# (str) – The format of the given file.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

The result of the operation.

Return type

ResultDetails

OpenCapture(opts, progress)¶

Opens a capture for replay locally and returns a handle to the capture. Only supported for handles opened with a native rdc capture, otherwise this will fail.

This function will block until the capture is fully loaded and ready.

Once the replay is created, this CaptureFile can be shut down, there is no dependency on it by the ReplayController.

Parameters

opts# (ReplayOptions) – The options controlling how the capture should be replayed.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the opening. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

A tuple containing the status of opening the capture, whether success or failure, and the resulting ReplayController handle if successful.

Return type

Tuple[ResultDetails,ReplayController]

OpenFile(filename, filetype, progress)¶

Initialises the capture handle from a file.

This method supports converting from non-native representations via structured data, by specifying the input format in the OpenFile.filetype parameter. The list of supported formats can be retrieved by calling GetCaptureFileFormats().

rdc is guaranteed to always be a supported filetype, and will be assumed if the filetype is empty or unrecognised.

Parameters

filename# (str) – The filename of the file to open.
filetype# (str) – The format of the given file.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

The result of the operation.

Return type

ResultDetails

RecordedMachineIdent()¶

Retrieves the identifying string describing what type of machine created this capture.

Returns: A string identifying the machine ident used to make the capture.
Return type: str

SetMetadata(driverName, machineIdent, thumbType, thumbWidth, thumbHeight, thumbData, timeBase, timeFreq)¶

Sets the matadata for this capture handle.

This function may only be called if the handle is ‘empty’ - i.e. no file has been opened with OpenFile() or OpenBuffer().

Note

The only supported values for SetMetadata.thumbType are FileType.JPG, FileType.PNG, FileType.TGA, and FileType.BMP.

Parameters

driverName# (str) – The name of the driver. Must be a recognised driver name (even if replay support for that driver is not compiled in locally.
machineIdent# (int) – The encoded machine identity value. Optional value and can be left to 0, as the bits to set are internally defined, so only generally useful if copying a machine ident from an existing capture.
thumbType# (FileType) – The file type of the thumbnail. Ignored if SetMetadata.thumbData is empty.
thumbWidth# (int) – The width of the thumbnail. Ignored if SetMetadata.thumbData is empty.
thumbHeight# (int) – The height of the thumbnail. Ignored if SetMetadata.thumbData is empty.
thumbData# (bytes) – The raw data of the thumbnail. If empty, no thumbnail is set.
timeBase# (int) – The base value for timestamps in the capture. Can be set to 0 to indicate that timestamps are already capture relative.
timeFreq# (float) – The frequency for timestamps and durations to be divided by to convert to microseconds. Can be set to 1.0 to indicate that timestamps and durations are already in microseconds.

SetStructuredData(file)¶

Sets the structured data for this capture.

This allows calling code to populate a capture out of generated structured data. In combination with SetMetadata() this allows a purely in-memory creation of a file to be saved out with Convert().

The data is copied internally so it can be destroyed after calling this function.

Parameters: file# (SDFile) – The structured data representing the file.

Shutdown()¶: Closes the file handle.

TimestampBase()¶

Retrieves the timestamp basis that all timestamps in the capture are relative to. May be 0 if all timestamps are already absolute.

Returns: The timestamp base value
Return type: int

TimestampFrequency()¶

Retrieves frequency for timestamps and durations to be divided by to convert to microseconds. May be 1.0 if all timestamps and durations are already in microseconds.

Returns: The timestamp frequency
Return type: float

class renderdoc.ReplaySupport(value)¶

How supported a given API is on a particular replay instance.

Unsupported¶: The API is not supported.

Supported¶: The API is fully supported.

SuggestRemote¶: The API is supported locally but the capture indicates it was made on a different type of machine so remote replay might be desired.

class renderdoc.CaptureFileFormat¶

The format for a capture file either supported to read from, or export to

convertSupported¶: Indicates whether captures or structured data can be saved out in this format.

description¶: A human readable long-form description of the file format.

extension¶: The file of the format as a single minimal string, e.g. rdc.

name¶: A human readable short phrase naming the file format.

openSupported¶: Indicates whether or not files in this format can be opened and processed as structured data.

requiresBuffers¶: Indicates whether exporting to this format requires buffers or just structured data. If it doesn’t require buffers then it can be exported directly from an opened capture, which by default has structured data but no buffers available.

class renderdoc.SectionProperties¶

Properties of a section in a renderdoc capture file.

compressedSize¶: The number of bytes of data in this section when compressed on disk.

flags¶: The flags describing how this section is stored.

name¶: The name of this section.

type¶: The type of this section, if it is a known pre-defined section.

uncompressedSize¶: The number of bytes of data contained in this section, once uncompressed.

version¶: The version of this section - the meaning of which is up to the type.

class renderdoc.SectionType(value)¶

The types of several pre-defined and known sections. This allows consumers of the API to recognise and understand the contents of the section.

Note that sections above the highest value here may be encountered if they were written in a new version of RenderDoc that addes a new section type. They should be considered equal to Unknown by any processing.

Unknown¶: An unknown section - any custom or non-predefined section will have this type.

FrameCapture¶

This section contains the actual captured frame, in RenderDoc’s internal chunked representation. The contents can be fetched as structured data with or without replaying the frame.

The name for this section will be “renderdoc/internal/framecapture”.

ResolveDatabase¶

This section contains platform-specific data used to resolve callstacks.

The name for this section will be “renderdoc/internal/resolvedb”.

Bookmarks¶

This section contains a JSON document with bookmarks added to the capture to highlight important events.

The name for this section will be “renderdoc/ui/bookmarks”.

Notes¶

This section contains a JSON document with free-form information added for human consumption, e.g. details about how the capture was obtained with repro steps in the original program, or with driver and machine info.

The name for this section will be “renderdoc/ui/notes”.

ResourceRenames¶

This section contains a JSON document with custom names applied to resources in the UI, over and above any friendly names specified in the capture itself.

The name for this section will be “renderdoc/ui/resrenames”.

AMDRGPProfile¶

This section contains a .rgp profile from AMD’s RGP tool, which can be extracted and loaded.

The name for this section will be “amd/rgp/profile”.

ExtendedThumbnail¶

This section contains a thumbnail in format other than JPEG. For example, when it needs to be lossless.

The name for this section will be “renderdoc/internal/exthumb”.

EmbeddedLogfile¶

This section contains the log file at the time of capture, for debugging.

The name for this section will be “renderdoc/internal/logfile”.

EditedShaders¶

This section contains any edited shaders.

The name for this section will be “renderdoc/ui/edits”.

D3D12Core¶

This section contains an internal copy of D3D12Core for replaying.

The name for this section will be “renderdoc/internal/d3d12core”.

D3D12SDKLayers¶

This section contains an internal copy of D3D12SDKLayers for replaying.

The name for this section will be “renderdoc/internal/d3d12sdklayers”.

class renderdoc.SectionFlags(value)¶

A set of flags describing the properties of a section in a renderdoc capture.

NoFlags¶: No special section properties.

ASCIIStored¶: This section was stored as pure ASCII. This can be useful since it is possible to generate an ASCII section in a text editor by hand or with any simple printf style script, and then concatenate it to a .rdc and have a valid section.

LZ4Compressed¶: This section is compressed with LZ4 on disk.

ZstdCompressed¶: This section is compressed with Zstd on disk.

class renderdoc.Thumbnail¶

Contains the bytes and metadata describing a thumbnail.

data¶: The bytes byte array containing the raw data.

height¶: The height of the thumbnail image.

type¶: The FileType of the data in the thumbnail.

width¶: The width of the thumbnail image.

GPU Enumeration ¶

class renderdoc.GPUDevice¶

Describes a single GPU at replay time.

apis¶

The APIs that this device supports.

Type: List[GraphicsAPI]

deviceID¶: The PCI deviceID of this GPU.

driver¶: The name of the driver of this GPU, if multiple drivers are available for it.

name¶: The human-readable name of this GPU.

vendor¶: The GPUVendor of this GPU.

class renderdoc.GPUVendor(value)¶

Identifies a GPU vendor.

Unknown¶: A GPU from an unknown vendor

ARM¶: An ARM GPU

AMD¶: An AMD GPU

Broadcom¶: A Broadcom GPU

Imagination¶: An Imagination GPU

Intel¶: An Intel GPU

nVidia¶: An nVidia GPU

Qualcomm¶: A Qualcomm GPU

Verisilicon¶: A Verisilicon or Vivante GPU

Software¶: A software-rendering emulated GPU

Samsung¶: A Samsung GPU

renderdoc.GPUVendorFromPCIVendor(vendorID)¶

Get the GPUVendor for a given PCI Vendor ID.

Parameters: vendorID# (int) – The PCI Vendor ID
Returns: The vendor identified
Return type: GPUVendor

class renderdoc.GraphicsAPI(value)¶

Identifies a Graphics API.

D3D11¶: Direct3D 11.

D3D12¶: Direct3D 12.

OpenGL¶: OpenGL.

Vulkan¶: Vulkan.

renderdoc.IsD3D(api)¶

Check if an API is D3D or not

Parameters: api# (GraphicsAPI) – The graphics API in question
Returns: True if api is a D3D-based API, False otherwise
Return type: bool

renderdoc.GetDriverInformation(api)¶

Retrieves the driver information (if available) for a given graphics API.

Parameters: api# (GraphicsAPI) – The API to get driver information for.
Returns: A DriverInformation containing the driver information.
Return type: DriverInformation

class renderdoc.DriverInformation¶

Gives information about the driver for this API.

vendor¶: The GPUVendor that provides this driver

version¶: The version string for the driver

Replay Controller ¶

class renderdoc.ReplayController¶

The primary interface to access the information in a capture and the current state, as well as control the replay and analysis functionality available.

KillCallback()¶

Not an actual member function - the signature for any KillCallback callbacks.

Called whenever some on-going blocking process needs to determine if it should close.

Returns: Whether or not the process should be killed.
Return type: bool

ProgressCallback()¶

Not an actual member function - the signature for any ProgressCallback callbacks.

Called by an on-going blocking process to update a progress bar or similar user feedback.

The progress value will go from 0.0 to 1.0 as the process completes. Any other value will indicate that the process has completed

Parameters: progress (float) – The latest progress amount.

PreviewWindowCallback()¶

Not an actual member function - the signature for any PreviewWindowCallback callbacks.

Called when a preview window could optionally be opened to display some information. It will be called repeatedly with active set to True to allow any platform-specific message pumping.

Parameters: active (bool) – True if a preview window is active/opened, False if it has closed.
Returns: The windowing data for a preview window, or empty/default values if no window should be created.
Return type: WindowingData

NoPreference¶: No preference for a particular value, see ReplayController.DebugPixel().

AddFakeMarkers()¶: Add fake marker regions to the list of actions in the capture, based on which textures are bound as outputs. Will not do anything if the capture already contains user marker regions.

Warning

This must be called immediately after capture load, calling it at a later time will cause corruption. No other functions should be called between load and this one.

Note

The event IDs for fake marker pushes and pops will not be contiguous with the surrounding actions and will be set to values above the last real event in the capture. This also means they break the typical rules that event IDs always increase. It’s recommended that these events are not referenced directly in other calls such as SetFrameEvent, and fake markers should be used sparingly at all compared to proper application-provided markers.

BuildCustomShader(entry, sourceEncoding, source, compileFlags, type)¶

Builds a shader suitable for running on the local replay instance as a custom shader.

System-level include directories can be set up via SetCustomShaderIncludes.

See TextureDisplay.customShaderId.

Parameters

entry# (str) – The entry point to use when compiling.
sourceEncoding# (ShaderEncoding) – The encoding of the source data.
source# (bytes) – The source data itself.
compileFlags# (ShaderCompileFlags) – API-specific compilation flags.
type# (ShaderStage) – The stage that this shader will be executed at.

Returns

A tuple with the id of the new shader if compilation was successful, ResourceId.Null() otherwise, and a str with any warnings/errors from compilation.

Return type

Tuple[ResourceId,str]

BuildTargetShader(entry, sourceEncoding, source, compileFlags, type)¶

Builds a shader suitable for running in the capture’s API as a replacement shader.

Parameters

entry# (str) – The entry point to use when compiling.
sourceEncoding# (ShaderEncoding) – The encoding of the source data.
source# (bytes) – The source data itself.
compileFlags# (ShaderCompileFlags) – API-specific compilation flags.
type# (ShaderStage) – The stage that this shader will be executed at.

Returns

A tuple with the id of the new shader if compilation was successful, ResourceId.Null() otherwise, and a str with any warnings/errors from compilation.

Return type

Tuple[ResourceId,str]

CancelReplayLoop()¶: Cancels a replay loop begun in ReplayLoop(). Does nothing if no loop is active.

ContinueDebug(debugger)¶

Continue a shader’s debugging with a given shader debugger instance. This will run an implementation defined number of steps and then return those steps in a list. This may be a fixed number of steps or it may run for a fixed length of time and return as many steps as can be calculated in that time.

This will always perform at least one step. If the list is empty, the debugging process has completed, further calls will return an empty list.

Parameters: debugger# (ShaderDebugger) – The shader debugger to continue running.
Returns: A number of subsequent states.
Return type: List[ShaderDebugState]

CreateOutput(window, type)¶

Creates a replay output of the given type to the given native window

Parameters

window# (WindowingData) – A WindowingData describing the native window.
type# (ReplayOutputType) – What type of output to create

Returns

A handle to the created output, or None on failure

Return type

ReplayOutput

CreateRGPProfile(window)¶

Uses the given output window to create an RGP Profile.

Parameters: window# (WindowingData) – A WindowingData describing the native window.
Returns: The path to the created RGP profile, or empty on failure
Return type: str

DebugMeshThread(groupid, threadid)¶

Retrieve a debugging trace from running a mesh shader.

Parameters

groupid# (Tuple[int,int,int]) – A list containing the 3D workgroup index.
threadid# (Tuple[int,int,int]) – A list containing the 3D thread index within the workgroup.

Returns

The resulting trace resulting from debugging. Destroy with FreeTrace().

Return type

ShaderDebugTrace

DebugPixel(x, y, inputs)¶

Retrieve a debugging trace from running a pixel shader.

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.

Parameters

x# (int) – The x co-ordinate.
y# (int) – The y co-ordinate.
inputs# (DebugPixelInputs) – Specific properties to select which fragment to debug e.g. sample: The multi-sampled sample. Ignored if non-multisampled texture. primitive: Debug the pixel from this primitive if there’s ambiguity. If set to NoPreference then a random fragment writing to the given co-ordinate is debugged. view: Debug the fragment writing to this view for layered or multiview rendering, ignored if set to NoPreference.

Returns

The resulting trace resulting from debugging. Destroy with FreeTrace().

Return type

ShaderDebugTrace

DebugThread(groupid, threadid)¶

Retrieve a debugging trace from running a compute thread.

Parameters

groupid# (Tuple[int,int,int]) – A list containing the 3D workgroup index.
threadid# (Tuple[int,int,int]) – A list containing the 3D thread index within the workgroup.

Returns

The resulting trace resulting from debugging. Destroy with FreeTrace().

Return type

ShaderDebugTrace

DebugVertex(vertid, instid, idx, view)¶

Retrieve a debugging trace from running a vertex shader.

Parameters

vertid# (int) – The vertex ID as a 0-based index up to the number of vertices in the draw.
instid# (int) – The instance ID as a 0-based index up to the number of instances in the draw.
idx# (int) – The actual index used to look up vertex inputs, either from the vertex ID for non- indexed draws or drawn from the index buffer. This must have all drawcall offsets applied.
view# (int) – The index of the multiview viewport to use, or 0 if multiview is not in use.

Returns

The resulting trace resulting from debugging. Destroy with FreeTrace().

Return type

ShaderDebugTrace

DescribeCounter(counter)¶

Get information about what a counter actually represents, in terms of a human-readable understanding as well as the type and unit of the resulting information.

Parameters: counter# (GPUCounter) – The counter to query about.
Returns: The description of the counter.
Return type: CounterDescription

DisassembleShader(pipeline, refl, target)¶

Retrieve the disassembly for a given shader, for the given disassembly target.

Parameters

pipeline# (ResourceId) – The pipeline state object, if applicable, that this shader is bound to.
refl# (ShaderReflection) – The shader reflection details of the shader to disassemble
target# (str) – The name of the disassembly target to generate for. Must be one of the values returned by GetDisassemblyTargets(), or empty to use the default generation.

Returns

The disassembly text, or an error message if something went wrong.

Return type

str

EnumerateCounters()¶

Retrieve a list of which counters are available in the current capture analysis implementation.

Returns: The list of counters available.
Return type: List[GPUCounter]

FetchCounters(counters)¶

Retrieve the values of a specified set of counters.

Parameters: counters# (List[GPUCounter]) – The list of counters to fetch results for.
Returns: The list of counter results generated.
Return type: List[CounterResult]

FileChanged()¶: Notify the interface that the file it has open has been changed on disk.

FreeCustomShader(id)¶

Free a previously created custom shader.

See BuildCustomShader().

Parameters: id# (ResourceId) – The id of the custom shader to free.

FreeTargetResource(id)¶

Free a previously created target shader.

See BuildTargetShader().

Parameters: id# (ResourceId) – The id of the target shader to free.

FreeTrace(trace)¶

Free a debugging trace from running a shader invocation debug.

Parameters: trace# (ShaderDebugTrace) – The shader debugging trace to free.

GetAPIProperties()¶

Retrieve a APIProperties object describing the current capture.

Returns: The properties of the current capture.
Return type: APIProperties

GetBufferData(buff, offset, len)¶

Retrieve the contents of a range of a buffer as a bytes.

Parameters

buff# (ResourceId) – The id of the buffer to retrieve data from.
offset# (int) – The byte offset to the start of the range.
len# (int) – The length of the range, or 0 to retrieve the rest of the bytes in the buffer.

Returns

The requested buffer contents.

Return type

bytes

GetBuffers()¶

Retrieve the list of buffers alive in the capture.

Returns: The list of buffers in the capture.
Return type: List[BufferDescription]

GetCBufferVariableContents(pipeline, shader, stage, entryPoint, cbufslot, buffer, offset, length)¶

Retrieve the contents of a constant block by reading from memory or their source otherwise.

Parameters

pipeline# (ResourceId) – The pipeline state object, if applicable, that this shader is bound to.
shader# (ResourceId) – The id of the shader to use for metadata.
stage# (ShaderStage) – The shader stage to fetch variables from.
entryPoint# (str) – The entry point of the shader being used. In some APIs, this is ignored.
cbufslot# (int) – The index in the ShaderReflection.constantBlocks list to look up.
buffer# (ResourceId) – The id of the buffer to use for data. If ConstantBlock.bufferBacked is False this is ignored.
offset# (int) – Retrieve buffer contents starting at this byte offset.
length# (int) – Retrieve this many bytes after offset. May be 0 to fetch the rest of the buffer.

Returns

The shader variables with their contents.

Return type

List[ShaderVariable]

GetCustomShaderEncodings()¶

Retrieve the list of supported ShaderEncoding which can be build using BuildCustomShader().

The list is sorted in priority order, so if the caller has a shader in a form but could compile/translate it to another, prefer to satisfy the first encoding before later encodings.

This typically means the ‘native’ encoding is listed first, and then subsequent encodings are compiled internally - so compiling externally could be preferable as it allows better customisation of the compile process or using alternate/updated tools.

Returns: The list of target shader encodings available.
Return type: List[ShaderEncoding]

GetCustomShaderSourcePrefixes()¶

Retrieve a list of source prefixes that should be applied to custom shaders of each ShaderEncoding before custom compilation prior to calling BuildCustomShader().

This list provides source code prefixes which should be applied to a given custom shader in a ShaderEncoding if and only if that shader is being compiled in a custom step to a different encoding, prior to being passed to BuildCustomShader(). This allows source compatibility even when doing custom compilation.

For example a shader written in ShaderEncoding.HLSL may be custom compiled to ShaderEncoding.SPIRV before being passed to BuildCustomShader(). In this case any prefix for ShaderEncoding.HLSL should be prepended to the source before custom compilation, to allow for defines and other helpers to be made available, since otherwise the shader may not compile.

If a shader encoding is not in the list, no prefix is required. This may be possible even for a high level language such as ShaderEncoding.GLSL.

Returns: A list of pairs, listing a prefix for each shader encoding referenced.
Return type: List[ShaderSourcePrefix]

GetD3D11PipelineState()¶

Retrieve the current D3D11State pipeline state.

The return value will be None if the capture is not using the D3D11 API. You should use GetAPIProperties() to determine the API of the capture.

See also GetPipelineState().

Returns: The current D3D11 pipeline state.
Return type: D3D11State

GetD3D12PipelineState()¶

Retrieve the current D3D12State pipeline state.

The return value will be None if the capture is not using the D3D12 API. You should use GetAPIProperties() to determine the API of the capture.

See also GetPipelineState().

Returns: The current D3D12 pipeline state.
Return type: D3D12State

GetDebugMessages()¶

Retrieve a list of any newly generated diagnostic messages.

Every time this function is called, any debug messages returned will not be returned again. Only newly generated messages will be returned after that.

Returns: The list of the DebugMessage messages.
Return type: List[DebugMessage]

GetDescriptorAccess()¶

Retrieve the descriptor accesses that happened at the current event.

Returns: The descriptor accesses.
Return type: List[DescriptorAccess]

GetDescriptorLocations(descriptorStore, ranges)¶

Retrieve the logical locations for descriptors in a given descriptor store.

Parameters

descriptorStore# (ResourceId) – The descriptor store to be queried from.
ranges# (List[DescriptorRange]) – The descriptor ranges to query.

Returns

The descriptor logical locations.

Return type

List[DescriptorLogicalLocation]

GetDescriptorStores()¶

Retrieve the list of descriptor storage objects alive in the capture.

Returns: The list of descriptor storage objects in the capture.
Return type: List[DescriptorStoreDescription]

GetDescriptors(descriptorStore, ranges)¶

Retrieve the contents of a number of descriptors in a descriptor store. Multiple ranges within the store can be queried at once, and are returned in a contiguous array.

Parameters

descriptorStore# (ResourceId) – The descriptor store to be queried from.
ranges# (List[DescriptorRange]) – The descriptor ranges to query.

Returns

The contents of the descriptors specified.

Return type

List[Descriptor]

GetDisassemblyTargets(withPipeline)¶

Retrieve the list of possible disassembly targets for DisassembleShader(). The values are implementation dependent but will always include a default target first which is the native disassembly of the shader. Further options may be available for additional diassembly views or hardware-specific ISA formats.

Parameters: withPipeline# (bool) – More disassembly may be available when a pipeline is specified.
Returns: The list of disassembly targets available.
Return type: List[str]

GetFatalErrorStatus()¶

Poll for the current status of the replay.

This function can be used to monitor to see if a fatal error has been encountered and react appropriately, such as by displaying a message to the user. The replay controller interface should remain stable and return null/empty data for the most part, but it’s recommended for maximum stability to stop using the controller when a fatal error is encountered.

If there has been no error, this will return ResultCode.Succeeded. If there has been an error this will return the error code every time, it will not be ‘consumed’ so it’s safe to have multiple things checking it.

Returns: The current fatal error status.
Return type: ResultDetails

GetFrameInfo()¶

Retrieve the information about the frame contained in the capture.

Returns: The frame information.
Return type: FrameDescription

GetGLPipelineState()¶

Retrieve the current GLState pipeline state.

The return value will be None if the capture is not using the OpenGL API. You should use GetAPIProperties() to determine the API of the capture.

See also GetPipelineState().

Returns: The current OpenGL pipeline state.
Return type: GLState

GetHistogram(textureId, sub, typeCast, minval, maxval, channels)¶

Retrieve a list of values that can be used to show a histogram of values for the specified texture.

The output list contains N buckets, and each bucket has the number of pixels that falls in each bucket when the pixel values are divided between minval and maxval.

Parameters

textureId# (ResourceId) – The texture to get the histogram from.
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.
minval# (float) – The lower end of the smallest bucket. If any values are below this, they are not added to any bucket.
maxval# (float) – The upper end of the largest bucket. If any values are above this, they are not added to any bucket.
channels# (Tuple[bool,bool,bool,bool]) – A set of four flags indicating whether each of RGBA respectively should be included in the count.

Returns

A list of the unnormalised bucket values.

Return type

List[int]

GetMinMax(textureId, sub, typeCast)¶

Retrieves the minimum and maximum values in the specified texture.

Parameters

textureId# (ResourceId) – The texture to get the values from.
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 tuple with the minimum and maximum pixel values respectively.

Return type

Tuple[PixelValue,PixelValue]

GetPipelineState()¶

Retrieve the current PipeState pipeline state abstraction.

This pipeline state will always be valid, and allows queries that will work regardless of the capture’s API.

Returns: The current pipeline state abstraction.
Return type: PipeState

GetPostVSData(instance, view, stage)¶

Retrieve the generated data from one of the geometry processing shader stages.

Parameters

instance# (int) – The index of the instance to retrieve data for, or 0 for non-instanced draws.
view# (int) – The index of the multiview view to retrieve data for, or 0 if multiview is disabled.
stage# (MeshDataStage) – The stage of the geometry processing pipeline to retrieve data from.

Returns

The information describing where the post-transform data is stored.

Return type

MeshFormat

GetResources()¶

Retrieve the list of all resources in the capture.

This includes any object allocated a ResourceId, that don’t have any other state or are only used as intermediary elements.

Returns: The list of resources in the capture.
Return type: List[ResourceDescription]

GetRootActions()¶

Retrieve the list of root-level actions in the capture.

Returns: The list of root-level actions in the capture.
Return type: List[ActionDescription]

GetSamplerDescriptors(descriptorStore, ranges)¶

Retrieve the contents of a number of sampler descriptors in a descriptor store. Multiple ranges within the store can be queried at once, and are returned in a contiguous array.

Parameters

descriptorStore# (ResourceId) – The descriptor store to be queried from.
ranges# (List[DescriptorRange]) – The descriptor ranges to query.

Returns

The contents of the descriptors specified.

Return type

List[SamplerDescriptor]

GetShader(pipeline, shader, entry)¶

Retrieve the information about the frame contained in the capture.

Parameters

pipeline# (ResourceId) – The pipeline state object, if applicable, that this shader is bound to.
shader# (ResourceId) – The shader to get reflection data for.
entry# (ShaderEntryPoint) – The entry point within the shader to reflect. May be ignored on some APIs

Returns

The frame information.

Return type

ShaderReflection

GetShaderEntryPoints(shader)¶

Retrieve a list of entry points for a shader.

If the given ID doesn’t specify a shader, an empty list will be return. On some APIs, the list will only ever have one result (only one entry point per shader).

Parameters: shader# (ResourceId) – The shader to look up entry points for.
Returns: The list of the ShaderEntryPoint messages.
Return type: List[ShaderEntryPoint]

GetStructuredFile()¶

Fetch the structured data representation of the capture loaded.

Returns: The structured file.
Return type: SDFile

GetSupportedWindowSystems()¶

Retrieves the supported WindowingSystem systems by the local system.

Returns: The list of supported systems.
Return type: List[WindowingSystem]

GetTargetShaderEncodings()¶

Retrieve the list of supported ShaderEncoding which can be build using BuildTargetShader().

The list is sorted in priority order, so if the caller has a shader in a form but could compile/translate it to another, prefer to satisfy the first encoding before later encodings.

This typically means the ‘native’ encoding is listed first, and then subsequent encodings are compiled internally - so compiling externally could be preferable as it allows better customisation of the compile process or using alternate/updated tools.

Returns: The list of target shader encodings available.
Return type: List[ShaderEncoding]

GetTextureData(tex, sub)¶

Retrieve the contents of one subresource of a texture as a bytes.

Parameters

tex# (ResourceId) – The id of the texture to retrieve data from.
sub# (Subresource) – The subresource within this texture to use.

Returns

The requested texture contents.

Return type

bytes

GetTextures()¶

Retrieve the list of textures alive in the capture.

Returns: The list of textures in the capture.
Return type: List[TextureDescription]

GetUsage(id)¶

Retrieve a list of ways a given resource is used.

Parameters: id# (ResourceId) – The id of the texture or buffer resource to be queried.
Returns: The list of usages of the resource.
Return type: List[EventUsage]

GetVulkanPipelineState()¶

Retrieve the current VKState pipeline state.

The return value will be None if the capture is not using the Vulkan API. You should use GetAPIProperties() to determine the API of the capture.

See also GetPipelineState().

Returns: The current Vulkan pipeline state.
Return type: VKState

PickPixel(textureId, x, y, sub, typeCast)¶

Retrieve the contents of a particular pixel in a texture.

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.

Parameters

textureId# (ResourceId) – The texture to pick the pixel from.
x# (int) – The x co-ordinate to pick from.
y# (int) – The y co-ordinate to pick from.
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

The contents of the pixel.

Return type

PixelValue

PixelHistory(texture, x, y, sub, typeCast)¶

Retrieve the history of modifications to the selected pixel on the selected texture.

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.

Parameters

texture# (ResourceId) – The texture to search for modifications.
x# (int) – The x co-ordinate.
y# (int) – The y co-ordinate.
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

The list of pixel history events.

Return type

List[PixelModification]

RemoveReplacement(id)¶

Remove any previously specified replacement for an object.

See ReplaceResource().

Parameters: id# (ResourceId) – The id of the original resource that was previously being substituted.

ReplaceResource(original, replacement)¶

Replace one resource with another for subsequent replay and analysis work.

This is commonly used for modifying the capture by selectively replacing resources with newly created resources.

See BuildTargetShader(), RemoveReplacement().

Parameters

original# (ResourceId) – The id of the original resource that should be substituted.
replacement# (ResourceId) – The id of the new resource that should be used instead.

ReplayLoop(window, texid)¶

Goes into a blocking loop, repeatedly replaying the open capture as fast as possible, displaying the selected texture in a default unscaled manner to the given output window.

The function won’t return until CancelReplayLoop() is called. Since this function is blocking, that function must be called from another thread.

Parameters

window# (WindowingData) – A WindowingData describing the native window.
texid# (ResourceId) – The id of the texture to display.

SaveTexture(saveData, path)¶

Save a texture to a file on disk, with possible transformation to map a complex texture to something compatible with the target file format.

Parameters

saveData# (TextureSave) – The configuration settings of which texture to save, and how
path# (str) – The path to save to on disk.

Returns

The result of the operation.

Return type

ResultDetails

SetCustomShaderIncludes(directories)¶

Sets a list of directories to search for include files when compiling custom shaders with the internal shader compiler.

Note

This is currently only supported for D3D11 and D3D12. For Vulkan includes can be supported via configuring an external compiler to SPIR-V which is ingested.

Parameters: directories# (List[str]) – The absolute paths of the directories.

SetFrameEvent(eventId, force)¶

Move the replay to reflect the state immediately after the given eventId.

Parameters

eventId# (int) – The eventId to move to.
force# (bool) – True if the internal replay should refresh even if the eventId is already current. This can be useful if external factors might cause the replay to vary.

Shutdown()¶: Shutdown and destroy the current interface and all outputs that have been created.

class renderdoc.ReplayOptions¶

The options controlling how replay of a capture should be performed

apiValidation¶

Replay with API validation enabled and use debug messages from there, ignoring any that may be contained in the capture.

The default is not to do any validation.

Note

RenderDoc does not handle invalid API use in the general case so validation should still be performed at runtime in your program for ground truth results.

forceGPUDeviceID¶

Force the selection of a GPU by device ID. This allows overriding which GPU is used to replay on.

When set to 0, specifies no particular device.

See forceGPUDeviceID for a full explanation of GPU selection override.

forceGPUDriverName¶

Force the selection of a GPU by driver name. This allows overriding which GPU is used to replay on.

When set to an empty string, specifies no particular driver.

See forceGPUDeviceID for a full explanation of GPU selection override.

forceGPUVendor¶

Force the selection of a GPU by vendor ID. This allows overriding which GPU is used to replay on, even if a different GPU would be the best match for the capture.

When set to GPUVendor.Unknown, specifies no particular vendor.

See also forceGPUDeviceID and forceGPUDriverName. Available GPUs can be enumerated using CaptureAccess.GetAvailableGPUs().

The default is not to do any override. The capture contains information about what GPU was used, and the closest matching GPU is used on replay.

Note

If a GPU is forced that is not available or not supported for a given capture, such as when GPUs are only available for some APIs and not others, the default GPU selection will be used. If a GPU is available for a capture but fails to open however then there is no fallback to a default GPU.

OpenGL does not support GPU selection so the default method (which effectively does nothing) will always be used.

optimisation¶

How much optimisation should be done, potentially at the cost of correctness.

The default is ReplayOptimisationLevel.Balanced.

class renderdoc.ReplayOptimisationLevel(value)¶

The level of optimisation used in

NoOptimisation¶: Completely disabled, no optimisation will be used at all.

Conservative¶: Optimisation is used when it doesn’t interfere with replay correctness.

Balanced¶: Optimisation is used when it has minimal impact on replay correctness. This could include e.g. resources appearing cleared instead of containing contents from prior frames where those resources are written to before being read.

Fastest¶: All possible optimisations are enabled as long as they do not cause invalid/incorrect replay. This could result in side-effects like data from one replay being visible early in another replay, if it’s known that the data will be overwritten before being used.

class renderdoc.APIProperties¶

Gives some API-specific information about the capture.

degraded¶: True if the capture was loaded successfully but running in a degraded mode - e.g. with software rendering, or with some functionality disabled due to lack of support.

localRenderer¶: The GraphicsAPI used to render the log. For remote replay this could be different to the above, and lets the UI make decisions e.g. to flip rendering of images.

pipelineType¶: The GraphicsAPI of the actual log/capture.

pixelHistory¶: (True if the API supports viewing pixel history.

remoteReplay¶: True if the capture is being replayed over a remote connection.

rgpCapture¶: True if the driver and system are configured to allow creating RGP captures.

shaderDebugging¶: (True if the API supports shader debugging.

vendor¶: The GPUVendor of the active GPU being used.

Device Protocols ¶

class renderdoc.DeviceProtocolController¶

An interface for enumerating and controlling remote devices.

GetDevices()¶

Returns a list of devices currently available through the given protocol.

Until a device is enumerated through this function it may not be available for connection through other methods such as target control or remote server access, even if the device is physically connected, due to initialisation happening only when enumerated.

The returned string is the hostname of the device, which can be connected via protocol://hostname with interfaces that take a hostname.

Returns: A list of the devices currently available.
Return type: List[str]

GetFriendlyName(URL)¶

Retrieves the user friendly name of the given device. This may be easier for a user to correlate to a device than the hostname which may be only a programmatic identifier.

Parameters: URL# (str) – The URL of the device in the form protocol://host, with protocol as returned by GetProtocolName() and host as returned by GetDevices().
Returns: A string identifying the device.
Return type: str

GetProtocolName()¶

Retrieves the name of this protocol as passed to GetDeviceProtocolController().

Returns: A string identifying the protocol.
Return type: str

IsSupported(URL)¶

Query if the device supports RenderDoc capture and replay.

Parameters: URL# (str) – The URL of the device in the form protocol://host, with protocol as returned by GetProtocolName() and host as returned by GetDevices().
Returns: True if any the device is supported, False otherwise.
Return type: bool

StartRemoteServer(URL)¶

Start the remote server running on the given device.

Parameters: URL# (str) – The URL of the device in the form protocol://host, with protocol as returned by GetProtocolName() and host as returned by GetDevices().
Returns: The status of starting the server, whether success or failure.
Return type: ResultDetails

SupportsMultiplePrograms(URL)¶

Query if the device supports multiple programs running and being captured. If not, the user can be prompted to close an existing program before a new one is launched.

Parameters: URL# (str) – The URL of the device in the form protocol://host, with protocol as returned by GetProtocolName() and host as returned by GetDevices().
Returns: True if the device supports multiple programs, False otherwise.
Return type: bool

renderdoc.GetSupportedDeviceProtocols()¶

Retrieve the set of device protocols supported (see GetDeviceProtocolController()).

Returns: The supported device protocols.
Return type: List[str]

renderdoc.GetDeviceProtocolController(protocol)¶

Creates a DeviceProtocolController that provides device-specific controls.

This interface is intended to allow closer integration with remote devices.

Note

Note that the use of scripting with Android is explicitly not supported due to the inherent fragility and unreliability of the Android platform. This interface is designed primarily for internal use and no support will be provided for Android-specific problems encountered using this.

This function will not block, however the protocol may still be initialising when it is returned so immediate use of it may block.

Parameters: protocol# (str) – The protocol to fetch a controller for.
Returns: A handle to the protocol controller, or None if something went wrong such as an unsupported protocol being specified.
Return type: DeviceProtocolController

Remote Servers ¶

class renderdoc.RemoteServer¶

A connection to a running remote RenderDoc server on another machine. This allows the transfer of captures to and from the local machine, as well as remotely replaying a capture with a local proxy renderer, so that captures that are not supported locally can still be debugged with as much work as possible happening on the local machine.

NoPreference¶: No preference for a particular value, see ReplayController.DebugPixel().

CloseCapture(rend)¶

Close a capture analysis handle previously opened by OpenCapture().

Parameters: rend# (ReplayController) – The ReplayController that is to be closed.

CopyCaptureFromRemote(remotepath, localpath, progress)¶

Copy a capture file that is stored on the remote system to the local system.

This function will block until the copy is fully complete, or an error has occurred.

Parameters

remotepath# (str) – The remote path where the file should be copied from.
localpath# (str) – The local path where the file should be saved.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the copy. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

CopyCaptureToRemote(filename, progress)¶

Copy a capture file that is stored on the local system to the remote system.

This function will block until the copy is fully complete, or an error has occurred.

This is primarily useful for when a capture is only stored locally and must be replayed remotely, as the capture must be available on the machine where the replay happens.

Parameters

filename# (str) – The path to the file on the local system.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the copy. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

The path on the remote system where the capture was saved temporarily.

Return type

str

ExecuteAndInject(app, workingDir, cmdLine, env, opts)¶

Launch an application and inject into it to allow capturing.

This happens on the remote system, so all paths are relative to the remote filesystem.

Parameters

app# (str) – The path to the application to run.
workingDir# (str) – The working directory to use when running the application. If blank, the directory containing the application is used.
cmdLine# (str) – The command line to use when running the application, it will be processed in a platform specific way to generate arguments.
env# (List[EnvironmentModification]) – Any environment changes that should be made when running the program.
opts# (CaptureOptions) – The capture options to use when injecting into the program.

Returns

The ExecuteResult indicating both the status of the operation (success or failure) and any reason for failure, or else the ident where the new application is listening for target control if everything succeeded.

Return type

ExecuteResult

GetHomeFolder()¶

Retrieve the path on the remote system where browsing can begin.

Returns: The ‘home’ path where browsing for files or folders can begin.
Return type: str

ListFolder(path)¶

Retrieve the contents of a folder path on the remote system.

If an error occurs, a single PathEntry will be returned with appropriate error flags.

Parameters: path# (str) – The remote path to list.
Returns: The contents of the specified folder.
Return type: List[PathEntry]

LocalProxies()¶

Retrieve a list of renderers available for local proxying.

These will be strings like “D3D11” or “OpenGL”.

Returns: A list of names of the local proxies.
Return type: List[str]

OpenCapture(proxyid, logfile, opts, progress)¶

Open a capture file for remote capture and replay. The capture will be opened and replayed on the remote system, and proxied to the local system with a given renderer. As much work as possible will happen locally to save on bandwidth, processing and latency.

This function will block until the capture is fully opened on the remote system and ready for use, or an error has occurred.

Note

You must close the resulting ReplayController with the CloseCapture() function to ensure the local proxy is correctly tidied up, instead of using ReplayController.Shutdown().

Parameters

proxyid# (int) – The index in the array returned by LocalProxies() to use as a local proxy, or NoPreference to indicate no preference for any proxy.
logfile# (str) – The path on the remote system where the file is. If the file is only available locally you can use CopyCaptureToRemote() to transfer it over the remote connection.
opts# (ReplayOptions) – The options controlling how the capture should be replayed.
progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the opening. Can be None if no progress is desired. Callback function signature must match ProgressCallback().

Returns

A tuple containing the status of opening the capture, whether success or failure, and the resulting ReplayController handle if successful.

Return type

Tuple[ResultDetails,ReplayController]

Ping()¶

Pings the remote server to ensure the connection is still alive.

Returns: The result of the operation - if a failure occurred the connection is no longer alive.
Return type: ResultDetails

RemoteSupportedReplays()¶

Retrieve a list of renderers supported by the remote server.

These will be strings like “D3D11” or “OpenGL”.

Returns: A list of names of the remote renderers.
Return type: List[str]

ShutdownConnection()¶: Closes the connection without affecting the running server.

ShutdownServerAndConnection()¶: Closes the connection and also tells the running server to close.

TakeOwnershipCapture(filename)¶

Take ownership over a capture file.

Initially when a capture is made, it is owned by the injected library in the application. It passes ownership to any program that is connected via target control that is notified about the capture, which is then responsible for either saving the file or deleting it if it’s unwanted.

Passing ownership of a file to the remote server means that it will be kept around for future use until the server closes, at which point it will delete any files it owns.

Parameters: filename# (str) – The remote path to take ownership of.

renderdoc.CreateRemoteServerConnection(URL)¶

Create a connection to a remote server running on given hostname.

Parameters: URL# (str) – The hostname to connect to, if blank then localhost is used. If no protocol is specified then default TCP enumeration happens.
Returns: The status of opening the connection, whether success or failure, and a RemoteServer instance if it were successful
Return type: Tuple[ResultDetails,RemoteServer]

renderdoc.CheckRemoteServerConnection(URL)¶

Check the connection to a remote server running on given hostname.

This should be preferred to CreateRemoteServerConnection() when no connection is desired, as the status can be checked without interfering with making connections.

Parameters: URL# (str) – The hostname to connect to, if blank then localhost is used. If no protocol is specified then default TCP enumeration happens.
Returns: The status of the server.
Return type: ResultDetails

renderdoc.BecomeRemoteServer(listenhost, port, killReplay, previewWindow)¶

This launches a remote server which will continually run in a loop to server requests from external sources.

This function will block until a remote connection tells the server to shut down, or the killReplay callback returns True.

Parameters

listenhost# (str) – The name of the interface to listen on.
port# (int) – The port to listen on, or 0 to listen on the default port.
killReplay# (KillCallback) – A callback that returns a bool indicating if the server should be shut down or not. Callback function signature must match KillCallback().
previewWindow# (PreviewWindowCallback) – A callback that returns information for a preview window when the server wants to display some preview of the ongoing replay. Callback function signature must match PreviewWindowCallback().

class renderdoc.PathEntry¶

Properties of a path on a remote filesystem.

filename¶: The filename of this path. This contains only the filename, not the full path.

flags¶: The PathProperty flags for this path.

lastmod¶: The last modified date of this path, as a unix timestamp in UTC.

size¶: The size of the path in bytes.

class renderdoc.PathProperty(value)¶

A set of flags describing the properties of a path on a remote filesystem.

NoFlags¶: No special file properties.

Directory¶: This file is a directory or folder.

Hidden¶: This file is considered hidden by the filesystem.

Executable¶: This file has been identified as an executable program or script.

ErrorUnknown¶: A special flag indicating that a query for this file failed, but for unknown reasons.

ErrorAccessDenied¶: A special flag indicating that a query for this file failed because access to the path was denied.

ErrorInvalidPath¶: A special flag indicating that a query for this file failed because the path was invalid.

API Reference: Replay Control¶

Initialisation and Shutdown¶

Capture File Access¶

GPU Enumeration¶

Replay Controller¶

Device Protocols¶

Remote Servers¶

Initialisation and Shutdown ¶

Capture File Access ¶

GPU Enumeration ¶

Replay Controller ¶

Device Protocols ¶

Remote Servers ¶