Capturing

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.

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.

status

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

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

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

True if the hook is active, False if something went wrong. The hook must be closed with StopGlobalHook() before the application is closed.

Return type

bool

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.

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.

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.

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

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.