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
(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: 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:
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:
-
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 returnsTrue
.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:
-
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:
-
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
Maths & Utilities¶
-
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.
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.
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.
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