# Functions

Contents

- Functions
  - Capture File Access
  - Target Control
  - Remote Servers
  - Local Execution & Injection
  - Logging & Versioning
  - Maths & Utilities

## 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.