API Reference: Capturing¶

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

Execution & Injection
Global Hooking
Target Control

Execution & Injection ¶

renderdoc.ExecuteAndInject(app, workingDir, cmdLine, env, capturefile, opts, waitForExit)¶

Launch an application and inject into it to allow capturing.

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.
capturefile# (str) – The capture file path template, or blank to use a default location.
opts# (CaptureOptions) – The capture options to use when injecting into the program.
waitForExit# (bool) – If True this function will block until the process exits.

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

renderdoc.InjectIntoProcess(pid, env, capturefile, opts, waitForExit)¶

Where supported by operating system and permissions, inject into a running process.

Parameters

pid# (int) – The Process ID (PID) to inject into.
env# (List[EnvironmentModification]) – Any environment changes that should be made when running the program.
capturefile# (str) – The capture file path template, or blank to use a default location.
opts# (CaptureOptions) – The capture options to use when injecting into the program.
waitForExit# (bool) – If True this function will block until the process exits.

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

class renderdoc.CaptureOptions¶

Sets up configuration and options for optional features either at capture time or at API initialisation time that the user can enable or disable at will.

DecodeFromString(encoded)¶

Decode the options from a string, as returned by EncodeAsString(). Updates this object in place.

Parameters: encoded# (str) – The encoded string, as returned by EncodeAsString().

EncodeAsString()¶

Encode the current options to a string suitable for passing around between processes.

Returns: The encoded string, suitable for passing to DecodeFromString().
Return type: str

allowFullscreen¶

Allow the application to enable fullscreen.

Default - enabled

True - The application can enable or disable fullscreen at will.

False - fullscreen is force disabled.

allowVSync¶

Allow the application to enable vsync.

Default - enabled

True - The application can enable or disable vsync at will.

False - vsync is force disabled.

apiValidation¶

Record API debugging events and messages

Default - disabled

True - Enable built-in API debugging features and records the results into the capture logfile, which is matched up with events on replay.

False - no API debugging is forcibly enabled.

captureAllCmdLists¶

In APIs that allow for the recording of command lists to be replayed later, RenderDoc may choose to not capture command lists before a frame capture is triggered, to reduce overheads. This means any command lists recorded once and replayed many times will not be available and may cause a failure to capture.

Note

This is only true for APIs where multithreading is difficult or discouraged. Newer APIs like Vulkan and D3D12 will ignore this option and always capture all command lists since the API is heavily oriented around it and the overheads have been reduced by API design.

True - All command lists are captured from the start of the application.

False - Command lists are only captured if their recording begins during the period when a frame capture is in progress.

captureCallstacks¶

Capture CPU callstacks for API events

Default - disabled

True - Enables capturing of callstacks.

False - no callstacks are captured.

captureCallstacksOnlyActions¶

When capturing CPU callstacks, only capture them from actions. This option does nothing if captureCallstacks is not enabled.

Default - disabled

True - Only captures callstacks for actions.

False - Callstacks, if enabled, are captured for every event.

debugOutputMute¶

Mute API debugging output when the API validation mode option is enabled.

Default - enabled

True - Mute any API debug messages from being displayed or passed through.

False - API debugging is displayed as normal.

delayForDebugger¶

Specify a delay in seconds to wait for a debugger to attach, after creating or injecting into a process, before continuing to allow it to run.

0 indicates no delay, and the process will run immediately after injection.

Default - 0 seconds

hookIntoChildren¶

Hooks any system API calls that create child processes, and injects RenderDoc into them recursively with the same options.

Default - disabled

True - Hooks into spawned child processes.

False - Child processes are not hooked by RenderDoc.

refAllResources¶

By default RenderDoc only includes resources in the final logfile necessary for that frame, this allows you to override that behaviour.

Default - disabled

True - all live resources at the time of capture are included in the log and available for inspection.

False - only the resources referenced by the captured frame are included.

softMemoryLimit¶

Define a soft memory limit which some APIs may aim to keep overhead under where possible. Anything above this limit will where possible be saved directly to disk during capture. This will cause increased disk space use (which may cause a capture to fail if disk space is exhausted) as well as slower capture times.

Not all memory allocations may be deferred like this so it is not a guarantee of a memory limit.

Units are in MBs, suggested values would range from 200MB to 1000MB.

Default - 0 Megabytes

verifyBufferAccess¶

Verify buffer access. This includes checking the memory returned by a Map() call to detect any out-of-bounds modification, as well as initialising buffers with undefined contents to a marker value to catch use of uninitialised memory.

Note

This option is only valid for OpenGL and D3D11. Explicit APIs such as D3D12 and Vulkan do not do the same kind of interception & checking and undefined contents are really undefined.

Default - disabled

True - Verify buffer access.

False - No verification is performed, and overwriting bounds may cause crashes or corruption in RenderDoc.

renderdoc.GetDefaultCaptureOptions()¶

Retrieve the default and recommended set of capture options.

Returns: The default capture options.
Return type: CaptureOptions

class renderdoc.EnvironmentModification¶

A modification to a single environment variable.

mod¶: The modification to use.

name¶: The name of the environment variable.

sep¶: The separator to use if needed.

value¶: The value to use with the modification specified in mod.

class renderdoc.EnvMod(value)¶

How to modify an environment variable.

Set¶: Set the variable to the given value.

Append¶: Add the given value to the end of the variable, using the separator.

Prepend¶: Add the given value to the start of the variable, using the separator.

class renderdoc.EnvSep(value)¶

The separator to use if needed when modifying an environment variable.

Platform¶

Use the character appropriate for separating items on the platform.

On Windows this means the semi-colon ; character will be used, on posix systems the colon : character will be used.

SemiColon¶: Use a semi-colon ; character.

Colon¶: Use a colon : character.

NoSep¶: No separator will be used.

class renderdoc.ExecuteResult¶

The result of executing or injecting into a program.

ident¶: The ident where the new application is listening for target control, or 0 if something went wrong.

result¶

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

Type: ResultDetails

Global Hooking ¶

renderdoc.StartGlobalHook(pathmatch, logfile, opts)¶

Begin injecting speculatively into all new processes started on the system. Where supported by platform, configuration, and setup begin injecting speculatively into all new processes started on the system.

This function can only be called if global hooking is supported (see CanGlobalHook()) and if global hooking is not active (see IsGlobalHookActive()).

The hook must be closed with StopGlobalHook() before the application is closed.

This function must be called when the process is running with administrator/superuser permissions.

Parameters

pathmatch# (str) – A string to match against each new process’s executable path to determine which corresponds to the program we actually want to capture.
logfile# (str) – Where to store any captures.
opts# (CaptureOptions) – The capture options to use when injecting into the program.

Returns

The result of the operation, if the result succeeded the hook is now active.

Return type

ResultDetails

renderdoc.StopGlobalHook()¶

Stop the global hook that was activated by StartGlobalHook().

This function can only be called if global hooking is supported (see CanGlobalHook()) and if global hooking is active (see IsGlobalHookActive()).

renderdoc.IsGlobalHookActive()¶

Determines if the global hook is active or not.

This function can only be called if global hooking is supported (see CanGlobalHook()).

Returns: True if the hook is active, or False if the hook is inactive.
Return type: bool

renderdoc.CanGlobalHook()¶

Determines if the global hook is supported on the current platform and configuration.

Returns: True if global hooking can be used on the platform, False if not.
Return type: bool

Target Control ¶

renderdoc.EnumerateRemoteTargets(URL, nextIdent)¶

Repeatedly query to enumerate which targets are active on a given machine and their idents.

Initially this should be called with nextIdent being 0, to retrieve the first target active. After that it can be called again and again with the previous return value to enumerate more targets.

This function will block for a variable timeout depending on how many targets are scanned.

Parameters

URL# (str) – The URL to connect to. If blank, the local machine is used. If no protocol is specified then default TCP enumeration happens.
nextIdent# (int) – The next ident to scan.

Returns

The ident of the next active target, or 0 if no other targets exist.

Return type

int

renderdoc.CreateTargetControl(URL, ident, clientName, forceConnection)¶

Creates a TargetControl connection to a given hostname and ident.

This function will block until the control connection is ready, or an error occurs.

Parameters

URL# (str) – The URL to connect to. If blank, the local machine is used. If no protocol is specified then default TCP enumeration happens.
ident# (int) – The ident for the particular target to connect to on that machine.
clientName# (str) – The client name to use when connecting. See TargetControl.GetBusyClient().
forceConnection# (bool) – Force the connection and kick off any existing client that is currently connected.

Returns

A handle to the target control connection, or None if something went wrong.

Return type

TargetControl

class renderdoc.TargetControl¶

A connection to a running application with RenderDoc injected, which allows limited control over the capture process as well as querying the current status.

Connected()¶

Determines if the connection is still alive.

Returns: True if the connection still appears to be working, False if it has been closed.
Return type: bool

CopyCapture(captureId, localpath)¶

Begin copying a given capture stored on a remote machine to the local machine over the target control connection.

Parameters

captureId# (int) – The identifier of the remote capture.
localpath# (str) – The absolute path on the local system where the file should be saved.

CycleActiveWindow()¶: Cycle the currently active window if there are more windows to capture.

DeleteCapture(captureId)¶

Delete a capture from the remote machine.

Parameters: captureId# (int) – The identifier of the remote capture.

GetAPI()¶

Retrieves the API currently in use by the target.

Returns: The API name, or empty if no API is initialised yet.
Return type: str

GetBusyClient()¶

If a busy message was received, determine the client keeping the target busy.

Returns: The name of the client currently connected to the target.
Return type: str

GetPID()¶

Retrieves the Process ID (PID) of the target on its local system.

Returns: The Process ID, or 0 if that’s not applicable on the target platform.
Return type: int

GetTarget()¶

Retrieves the target’s name or identifier - typically the name of the executable.

Returns: The target name.
Return type: str

QueueCapture(frameNumber, numFrames)¶

Queue up a capture to happen on a particular frame number. When this frame is about to begin a capture is begun, and it ends when this frame number ends.

Note

Frame 0 is defined as starting when the device is created, up to the first swapchain present defined frame boundary.

Parameters

frameNumber# (int) – The number of the frame to capture on.
numFrames# (int) – How many frames to capture. These will be captured sequentially and independently to separate files.

ReceiveMessage(progress)¶

Query to see if a message has been received from the remote system.

The details of the types of messages that can be received are listed under TargetControlMessage.

Note

If no message has been received, this function will pump the connection. You are expected to continually call this function and process any messages to kee pthe connection alive.

This function will block but only to a limited degree. If no message is waiting after a small time it will return with a No-op message to allow further processing.

Parameters: progress# (ProgressCallback) – A callback that will be repeatedly called with an updated progress value when a long blocking message is coming through, e.g. a capture copy. Can be None if no progress is desired. Callback function signature must match ProgressCallback().
Returns: The message that was received.
Return type: TargetControlMessage

Shutdown()¶: Closes the connection without affecting the running application.

TriggerCapture(numFrames)¶

Trigger a capture on the target, with the same semantics as if the capture key had been pressed - from the next presentation call after this message is processed on the target to the next after that.

Parameters: numFrames# (int) – How many frames to capture. These will be captured sequentially and independently to separate files.

class renderdoc.TargetControlMessage¶

A message from a target control connection.

apiUse¶

The API use data.

Type: APIUseData

busy¶

The busy signal data.

Type: BusyData

capProgress¶

The progress of an on-going capture.

When valid, will be in the range of 0.0 to 1.0 (0 - 100%). If not valid when a capture isn’t going or has finished, it will be -1.0

capturableWindowCount¶: The number of the capturable windows

newCapture¶

The new capture data.

Type: NewCaptureData

newChild¶

The new child process data.

Type: NewChildData

type¶: The type of message received

class renderdoc.TargetControlMessageType(value)¶

The type of message received from or sent to an application target control connection.

Unknown¶: No message or an unknown message type.

Disconnected¶: The other end of the connection disconnected.

Busy¶: The other end of the connection was busy.

Noop¶: Nothing happened, the connection is being kept alive.

NewCapture¶: A new capture was made.

CaptureCopied¶: A capture was successfully copied across the connection.

RegisterAPI¶: The target has initialised a graphics API.

NewChild¶: The target has created a child process.

CaptureProgress¶: Progress update on an on-going frame capture.

CapturableWindowCount¶: The number of capturable windows has changed.

RequestShow¶: The client has requested that the controller show itself (raise its window to the top).

class renderdoc.NewCaptureData¶

Information about the a new capture created by the target.

api¶: The API used for this capture, if available.

Note

May be empty if running with an older version of RenderDoc

byteSize¶: The size of the capture, in bytes.

captureId¶: An identifier to use to refer to this capture.

frameNumber¶: The frame number that this capture came from.

local¶: True if the target is running on the local system.

path¶: The local path on the target system where the capture is saved.

thumbHeight¶: The height of the image contained in thumbnail.

thumbWidth¶: The width of the image contained in thumbnail.

thumbnail¶: The raw bytes that contain the capture thumbnail, as RGB8 data.

timestamp¶: The time the capture was created, as a unix timestamp in UTC.

title¶: The custom title for this capture, if empty a default title can be used.

class renderdoc.APIUseData¶

Information about the API that the target is using.

name¶: The name of the API.

presenting¶: True if the API is presenting to a swapchain

supportMessage¶

A string message if the API is unsupported explaining why.

Type: str

supported¶: True if the API can be captured.

class renderdoc.BusyData¶

Information about why the target is busy.

clientName¶: The name of the client currently connected to the target.

class renderdoc.NewChildData¶

Information about a new child process spawned by the target.

ident¶: The ident where the new child’s target control is active.

processId¶: The PID (Process ID) of the new child.

API Reference: Capturing¶

Execution & Injection¶

Global Hooking¶

Target Control¶

Execution & Injection ¶

Global Hooking ¶

Target Control ¶