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

  softMemoryLimit

    Define a soft memory limit which some APIs may aim to keep overhead under where possible. Anything above this limit will where possible be saved directly to disk during capture. This will cause increased disk space use (which may cause a capture to fail if disk space is exhausted) as well as slower capture times.

    Not all memory allocations may be deferred like this so it is not a guarantee of a memory limit.

    Units are in MBs, suggested values would range from 200MB to 1000MB.

    Default - 0 Megabytes

  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.

  result

    The `ResultDetails` resulting from the operation, indicating success or failure.

    Type:

      ResultDetails

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

  The hook must be closed with `StopGlobalHook()` before the application is closed.

  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:

    The result of the operation, if the result succeeded the hook is now active.

  Return type:

    ResultDetails

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.

  RequestShow

    The client has requested that the controller show itself (raise its window to the top).

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.

  title

    The custom title for this capture, if empty a default title can be used.

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

  supportMessage

    A string message if the API is unsupported explaining why.

    Type:

      str

  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.