Functions

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

Target Control

renderdoc.EnumerateRemoteTargets(host, 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:
  • host# (str) – The hostname to connect to. If blank, the local machine is used.
  • 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(host, 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:
  • host# (str) – The hostname to connect to. If blank, the local machine is used.
  • 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

Remote Servers

renderdoc.CreateRemoteServerConnection(host, port, rend)

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

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

Parameters:
  • host# (str) – The hostname to connect to, if blank then localhost is used.
  • port# (int) – The port to connect to, or the default port if 0.
  • rend# (RemoteServer) – A reference to a RemoteServer where the connection handle will be stored.
Returns:

The status of opening the capture, whether success or failure.

Return type:

ReplayStatus

renderdoc.GetDefaultRemoteServerPort()

Retrieves the default ports where remote servers listen.

Returns:The port where remote servers listen by default.
Return type:int
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:
  • host# (str) – The name of the interface to listen on.
  • port# (int) – The port to listen on, or the default port if 0.
  • killReplay# (KillCallback) – A callback that returns a bool indicating if the server should be shut down or not.
  • previewWindow# (PreviewWindowCallback) – A callback that returns information for a preview window when the server wants to display some preview of the ongoing replay.

Local Execution & Injection

renderdoc.GetDefaultCaptureOptions(opts)

Retrieve the default and recommended set of capture options.

Parameters:opts# (CaptureOptions) – A reference to a CaptureOptions where the options will be stored.
renderdoc.ExecuteAndInject(app, workingDir, cmdLine, env, logfile, 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) – Any EnvironmentModification that should be made when running the program.
  • 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, logfile, 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) – Any EnvironmentModification that should be made when running the program.
  • 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.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

Logging & Versioning

renderdoc.SetDebugLogFile(filename)

Sets the location for the diagnostic log output, shared by captured programs and the analysis program.

Parameters:filename# (str) – The path to the new log file.
renderdoc.GetLogFile()

Gets the location for the diagnostic log output, shared by captured programs and the analysis program.

Returns:The path to the current log file.
Return type:str
renderdoc.GetVersionString()

Retrieves the version string.

This will be in the form “MAJOR.MINOR”

Returns:The version string.
Return type:str

Maths & Utilities

renderdoc.CreateWin32WindowingData(window)

Create a WindowingData for a Win32 HWND handle.

Parameters:window# (HWND) – The native HWND handle for this window.
Returns:A WindowingData corresponding to the given window.
Return type:WindowingData
renderdoc.CreateXlibWindowingData(display, window)

Create a WindowingData for an Xlib Drawable handle.

Parameters:
  • display# (Display) – The Display connection used for this window.
  • window# (Drawable) – The native Drawable handle for this window.
Returns:

A WindowingData corresponding to the given window.

Return type:

WindowingData

renderdoc.CreateXCBWindowingData(connection, window)

Create a WindowingData for an XCB xcb_window_t handle.

Parameters:
  • connection# (xcb_connection_t) – The xcb_connection_t connection used for this window.
  • window# (xcb_window_t) – The native xcb_window_t handle for this window.
Returns:

A WindowingData corresponding to the given window.

Return type:

WindowingData

renderdoc.CreateAndroidWindowingData(window)

Create a WindowingData for an Android ANativeWindow handle.

Parameters:window# (ANativeWindow) – The native ANativeWindow handle for this window.
Returns:A WindowingData corresponding to the given window.
Return type:WindowingData
renderdoc.InitCamera(type)

Create a new camera of a given type.

Parameters:type# (CameraType) – The type of controls to use
Returns:The handle to the new camera.
Return type:Camera
renderdoc.HalfToFloat(half)

A utility function that converts a half (stored in a 16-bit unsigned integer) to a float.

Parameters:half# (int) – The half stored as an int.
Returns:The floating point equivalent.
Return type:float
renderdoc.FloatToHalf(flt)

A utility function that converts a float to a half (stored in a 16-bit unsigned integer).

Parameters:f# (float) – The floating point value.
Returns:The nearest half-float equivalent stored as an int.
Return type:int
renderdoc.NumVerticesPerPrimitive(topology)

A utility function that returns the number of vertices in a primitive of a given topology.

Note

In strip topologies vertices are re-used.

Parameters:topology# (Topology) – The topology to query about.
Returns:The number of vertices in a single primitive.
Return type:int
renderdoc.VertexOffset(topology, primitive)

A utility function that returns the offset in the list of vertices of the first vertex in a particular primitive of a given topology. This calculation is simple but not trivial for the case of strip topologies.

Parameters:
  • topology# (Topology) – The topology to query about.
  • primitive# (int) – The primitive to query about.
Returns:

The vertex offset where the primitive starts.

Return type:

int

renderdoc.PatchList_Count(topology)

Return the number of control points in a patch list Topology

t must be a patch list topology, the return value will be between 1 and 32 inclusive

Parameters:t# (Topology) – The patch list topology
Returns:The number of control points in the specified topology
Return type:int
renderdoc.PatchList_Topology(N)

Return the patch list Topology with N control points

N must be between 1 and 32 inclusive.

Parameters:N# (int) – The number of control points in the patch list
Returns:The patchlist topology with that number of control points
Return type:Topology
renderdoc.IsStrip(topology)

Check whether or not this is a strip-type topology.

Parameters:t# (Topology) – The topology to check.
Returns:True if it describes a strip topology, False for a list.
Return type:int
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
renderdoc.MaskForStage(stage)

Calculate the corresponding flag for a shader stage

Parameters:stage# (ShaderStage) – The shader stage
Returns:The flag that corresponds to the input shader stage
Return type:ShaderStageMask
renderdoc.StartSelfHostCapture(dllname)

When debugging RenderDoc it can be useful to capture itself by doing a side-build with a temporary name. This function wraps up the use of the in-application API to start a capture.

Parameters:dllname# (str) – The name of the self-hosted capture module.
renderdoc.EndSelfHostCapture(dllname)

When debugging RenderDoc it can be useful to capture itself by doing a side-build with a temporary name. This function wraps up the use of the in-application API to end a capture.

Parameters:dllname# (str) – The name of the self-hosted capture module.