Functions¶
Contents
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
(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: 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:
Remote Servers¶
-
renderdoc.
CreateRemoteServerConnection
(URL)¶ Create a connection to a remote server running on given hostname and port.
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 capture, whether success or failure, and a RemoteServer
instance if it were successfulReturn type: pair
of ReplayStatus and RemoteServer
-
renderdoc.
BecomeRemoteServer
(listenhost, 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 returnsTrue
.Parameters: - host# (str) – The name of the interface to listen on.
- 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.
Device Protocols¶
-
renderdoc.
GetSupportedDeviceProtocols
()¶ Retrieve the set of device protocols supported (see
GetDeviceProtocolController()
).Returns: The supported device protocols. Return type: list
ofstr
-
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
Local Execution & Injection¶
-
renderdoc.
GetDefaultCaptureOptions
()¶ Retrieve the default and recommended set of capture options.
Returns: The default capture options. Return type: CaptureOptions
-
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) – Any
EnvironmentModification
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) – Any
EnvironmentModification
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.
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 (seeIsGlobalHookActive()
).This function must be called when the process is running with administrator/superuser permissions.
Parameters: Returns: True
if the hook is active,False
if something went wrong. The hook must be closed withStopGlobalHook()
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 (seeIsGlobalHookActive()
).
-
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, orFalse
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
-
renderdoc.
GetCommitHash
()¶ Retrieves the commit hash used to build.
This will be in the form “0123456789abcdef0123456789abcdef01234567”
Returns: The commit hash. Return type: str
Maths & Utilities¶
-
renderdoc.
CreateHeadlessWindowingData
(width, height)¶ Create a
WindowingData
for no backing window, it will be headless.Parameters: Returns: A
WindowingData
corresponding to an ‘empty’ backing window.Return type: WindowingData
-
renderdoc.
CreateWin32WindowingData
(window)¶ Create a
WindowingData
for a Win32HWND
handle.Parameters: window# (HWND) – The native HWND
handle for this window.Returns: A WindowingData
corresponding to the given window.Return type: WindowingData
-
renderdoc.
CreateXlibWindowingData
(display, window)¶ Create a
WindowingData
for an XlibDrawable
handle.Parameters: Returns: A
WindowingData
corresponding to the given window.Return type: WindowingData
-
renderdoc.
CreateXCBWindowingData
(connection, window)¶ Create a
WindowingData
for an XCBxcb_window_t
handle.Parameters: Returns: A
WindowingData
corresponding to the given window.Return type: WindowingData
-
renderdoc.
CreateWaylandWindowingData
(display, window)¶ Create a
WindowingData
for an Waylandwl_surface
handle.Parameters: Returns: A
WindowingData
corresponding to the given window.Return type: WindowingData
-
renderdoc.
CreateGgpWindowingData
()¶ Create a
WindowingData
for a GGP application.Returns: A WindowingData
corresponding to the given system.Return type: WindowingData
-
renderdoc.
CreateAndroidWindowingData
(window)¶ Create a
WindowingData
for an AndroidANativeWindow
handle.Parameters: window# (ANativeWindow) – The native ANativeWindow
handle for this window.Returns: A WindowingData
corresponding to the given window.Return type: WindowingData
-
renderdoc.
CreateMacOSWindowingData
(view, layer)¶ Create a
WindowingData
for an metal/opengl-compatible macOSCALayer
handle andNSView
handle (as void pointers).Parameters: Returns: A
WindowingData
corresponding to the given window.Return type: 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: 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 inclusiveParameters: 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 pointsN
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.
SupportsRestart
(topology)¶ Check whether or not this topology supports primitive restart.
Note
This is almost but not quite the same as being a line/triangle strip - triangle fans also support restart. See also
IsStrip()
.Parameters: t# (Topology) – The topology to check. Returns: True
if it describes a topology that allows restart,False
for a list.Return type: bool
-
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: bool
-
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