# Replay Control

Contents

- Replay Control

  - Initialisation and Shutdown

  - Capture File Access

  - GPU Enumeration

  - Replay Controller

  - Device Protocols

  - Remote Servers

## Initialisation and Shutdown

`renderdoc.``InitialiseReplay`(globalEnv, args)

  Initialises RenderDoc for replay. Replay API functions should not be called before this has been called. It should be called exactly once, and before shutdown you must call `ShutdownReplay()`.

  Parameters

    - globalEnv (GlobalEnvironment) – The path to the new log file.

    - args (List[str]) – Any extra command-line arguments.

`renderdoc.``ShutdownReplay`()

  Shutdown RenderDoc for replay. Replay API functions should not be called after this has been called. It is not safe to re-initialise replay after this function has been called so it should only be called at program shutdown. This function must only be called if `InitialiseReplay()` was previously called.

class `renderdoc.``GlobalEnvironment`

  Structure used for initialising environment in a replay application.

  `enumerateGPUs`

    Whether to enumerate available GPUs. If the replay program is only being used for internal operation where enumerating GPUs would be too expensive or problematic, it can be disabled here.

  `waylandDisplay`

    The handle to the wayland display to use internally. If left `NULL`, wayland cannot be used.

  `xlibDisplay`

    The handle to the X display to use internally. If left `NULL`, one will be opened.

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

class `renderdoc.``CaptureAccess`

  An interface for accessing a capture, possibly over a network connection. This is a subset of the functionality provided in `CaptureFile` which only supports import/export and construction of files.

  `DriverName`()

    Retrieves the name of the driver that was used to create this capture.

    Returns

      A simple string identifying the driver used to make the capture.

    Return type

      str

  `FindSectionByName`(name)

    Locate the index of a section by its name. Returns `-1` if the section is not found.

    This index should not be cached, as writing sections could re-order the indices.

    Parameters

      name (str) – The name of the section to search for.

    Returns

      The index of the section, or `-1` if not found.

    Return type

      int

  `FindSectionByType`(type)

    Locate the index of a section by its type. Returns `-1` if the section is not found.

    This index should not be cached, as writing sections could re-order the indices.

    Parameters

      type (SectionType) – The type of the section to search for.

    Returns

      The index of the section, or `-1` if not found.

    Return type

      int

  `GetAvailableGPUs`()

    Returns the list of available GPUs, that can be used in combination with `ReplayOptions` to force replay on a particular GPU.

    Returns

      The list of GPUs available.

    Return type

      List[GPUDevice]

  `GetResolve`(callstack)

    Retrieve the details of each stackframe in the provided callstack.

    Must only be called after `InitResolver()` has returned `True`.

    Parameters

      callstack (List[int]) – The integer addresses in the original callstack.

    Returns

      The list of resolved callstack entries as strings.

    Return type

      List[str]

  `GetSectionContents`(index)

    Get the raw byte contents of the specified section.

    Parameters

      index (int) – The index of the section.

    Returns

      The raw contents of the section, if the index is valid.

    Return type

      bytes

  `GetSectionCount`()

    Retrieve the total number of available sections.

    Returns

      The number of sections in the capture

    Return type

      int

  `GetSectionProperties`(index)

    Get the describing properties of the specified section.

    Parameters

      index (int) – The index of the section.

    Returns

      The properties of the section, if the index is valid.

    Return type

      SectionProperties

  `HasCallstacks`()

    Query if callstacks are available.

    Returns

      `True` if any callstacks are available, `False` otherwise.

    Return type

      bool

  `InitResolver`(interactive, progress)

    Begin initialising a callstack resolver, looking up symbol files and caching as necessary.

    This function blocks while trying to initialise callstack resolving, so it should be called on a separate thread.

    Parameters

      - interactive (bool) – `True` if missing symbols or other prompts should be resolved interactively. If this is `False`, the function will not interact or block forever on user interaction and will always assume the input is effectively ‘cancel’ or empty. This may cause the symbol resolution to fail.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the resolver process. Can be `None` if no progress is desired.

    Returns

      `True` if the resolver successfully initialised, `False` if something went wrong.

    Return type

      bool

  `WriteSection`(props, contents)

    Writes a new section with specified properties and contents. If an existing section already has the same type or name, it will be overwritten (two sections cannot share the same type or name).

    Parameters

      - props (SectionProperties) – The properties of the section to be written.

      - contents (bytes) – The raw contents of the section.

    Returns

      `True` if the section was written successfully, `False` otherwise.

    Return type

      bool

class `renderdoc.``CaptureFile`

  A handle to a capture file. Used for simple cheap processing and meta-data fetching without opening the capture for analysis.

  `Convert`(filename, filetype, file, progress)

    Converts the currently loaded file to a given format and saves it to disk.

    This allows converting a native RDC to another representation, or vice-versa converting another representation back to native RDC.

    Parameters

      - filename (str) – The filename to save to.

      - filetype (str) – The format to convert to.

      - file (SDFile) – An optional `SDFile` with the structured data to source from. This is useful in case the format specifies that it doesn’t need buffers, and you already have a `ReplayController` open with the structured data. This saves the need to load the file again. If `None` then structured data will be fetched if not already present and used.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the conversion. Can be `None` if no progress is desired.

    Returns

      The status of the conversion operation, whether it succeeded or failed (and how it failed).

    Return type

      ReplayStatus

  `CopyFileTo`(filename)

    When a capture file is opened, an exclusive lock is held on the file on disk. This makes it impossible to copy the file to another location at the user’s request. Calling this function will copy the file on disk to a new location but otherwise won’t affect the capture handle. The new file will be locked, the old file will be unlocked - to allow deleting if necessary.

    It is invalid to call this function if `OpenFile()` has not previously been called to open the file.

    Parameters

      filename (str) – The filename to copy to.

    Returns

      `True` if the operation succeeded.

    Return type

      bool

  `ErrorString`()

    Returns the human-readable error string for the last error received.

    The error string is not reset by calling this function so it’s safe to call multiple times. However any other function call may reset the error string to empty.

    Returns

      The error string, if one exists, or an empty string.

    Return type

      str

  `GetCaptureFileFormats`()

    Returns the list of capture file formats.

    Returns

      The list of capture file formats available.

    Return type

      List[CaptureFileFormat]

  `GetStructuredData`()

    Returns the structured data for this capture.

    The lifetime of this data is scoped to the lifetime of the capture handle, so it cannot be used after the handle is destroyed.

    Returns

      The structured data representing the file.

    Return type

      SDFile

  `GetThumbnail`(type, maxsize)

    Retrieves the embedded thumbnail from the capture.

    Note

    The only supported values for `GetThumbnail.type` are `FileType.JPG`, `FileType.PNG`, `FileType.TGA`, and `FileType.BMP`.

    Parameters

      - type (FileType) – The image format to convert the thumbnail to.

      - maxsize (int) – The largest width or height allowed. If the thumbnail is larger, it’s resized.

    Returns

      The raw contents of the thumbnail, converted to the desired type at the desired max resolution.

    Return type

      Thumbnail

  `LocalReplaySupport`()

    Queries for how well a particular capture is supported on the local machine.

    If the file was opened with a format other than native `rdc` this will always return no replay support.

    Returns

      How much support for replay exists locally.

    Return type

      ReplaySupport

  `OpenBuffer`(buffer, filetype, progress)

    Initialises the file handle from a raw memory buffer.

    This may be useful if you don’t want to parse the whole file or already have the file in memory.

    For the `OpenBuffer.filetype` parameter, see `OpenFile()`.

    Parameters

      - buffer (bytes) – The buffer containing the data to process.

      - filetype (str) – The format of the given file.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be `None` if no progress is desired.

    Returns

      The status of the open operation, whether it succeeded or failed (and how it failed).

    Return type

      ReplayStatus

  `OpenCapture`(opts, progress)

    Opens a capture for replay locally and returns a handle to the capture. Only supported for handles opened with a native `rdc` capture, otherwise this will fail.

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

    Once the replay is created, this `CaptureFile` can be shut down, there is no dependency on it by the `ReplayController`.

    Parameters

      - opts (ReplayOptions) – The options controlling how the capture should be replayed.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the opening. Can be `None` if no progress is desired.

    Returns

      A tuple containing the status of opening the capture, whether success or failure, and the resulting `ReplayController` handle if successful.

    Return type

      Tuple[ReplayStatus,ReplayController]

  `OpenFile`(filename, filetype, progress)

    Initialises the capture handle from a file.

    This method supports converting from non-native representations via structured data, by specifying the input format in the `OpenFile.filetype` parameter. The list of supported formats can be retrieved by calling `GetCaptureFileFormats()`.

    `rdc` is guaranteed to always be a supported filetype, and will be assumed if the filetype is empty or unrecognised.

    Parameters

      - filename (str) – The filename of the file to open.

      - filetype (str) – The format of the given file.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be `None` if no progress is desired.

    Returns

      The status of the open operation, whether it succeeded or failed (and how it failed).

    Return type

      ReplayStatus

  `RecordedMachineIdent`()

    Retrieves the identifying string describing what type of machine created this capture.

    Returns

      A string identifying the machine ident used to make the capture.

    Return type

      str

  `SetMetadata`(driverName, machineIdent, thumbType, thumbWidth, thumbHeight, thumbData, timeBase, timeFreq)

    Sets the matadata for this capture handle.

    This function may only be called if the handle is ‘empty’ - i.e. no file has been opened with `OpenFile()` or `OpenBuffer()`.

    Note

    The only supported values for `SetMetadata.thumbType` are `FileType.JPG`, `FileType.PNG`, `FileType.TGA`, and `FileType.BMP`.

    Parameters

      - driverName (str) – The name of the driver. Must be a recognised driver name (even if replay support for that driver is not compiled in locally.

      - machineIdent (int) – The encoded machine identity value. Optional value and can be left to 0, as the bits to set are internally defined, so only generally useful if copying a machine ident from an existing capture.

      - thumbType (FileType) – The file type of the thumbnail. Ignored if `SetMetadata.thumbData` is empty.

      - thumbWidth (int) – The width of the thumbnail. Ignored if `SetMetadata.thumbData` is empty.

      - thumbHeight (int) – The height of the thumbnail. Ignored if `SetMetadata.thumbData` is empty.

      - thumbData (bytes) – The raw data of the thumbnail. If empty, no thumbnail is set.

      - timeBase (int) – The base value for timestamps in the capture. Can be set to 0 to indicate that timestamps are already capture relative.

      - timeFreq (float) – The frequency for timestamps and durations to be divided by to convert to microseconds. Can be set to 1.0 to indicate that timestamps and durations are already in microseconds.

  `SetStructuredData`(file)

    Sets the structured data for this capture.

    This allows calling code to populate a capture out of generated structured data. In combination with `SetMetadata()` this allows a purely in-memory creation of a file to be saved out with `Convert()`.

    The data is copied internally so it can be destroyed after calling this function.

    Parameters

      file (SDFile) – The structured data representing the file.

  `Shutdown`()

    Closes the file handle.

  `TimestampBase`()

    Retrieves the timestamp basis that all timestamps in the capture are relative to. May be 0 if all timestamps are already absolute.

    Returns

      The timestamp base value

    Return type

      int

  `TimestampFrequency`()

    Retrieves frequency for timestamps and durations to be divided by to convert to microseconds. May be 1.0 if all timestamps and durations are already in microseconds.

    Returns

      The timestamp frequency

    Return type

      float

class `renderdoc.``ReplayStatus`(value)

  The status of a high-level replay operation such as opening a capture or connecting to a remote server.

  `Succeeded`

    The operation succeeded.

  `UnknownError`

    An unknown error occurred.

  `InternalError`

    An internal error occurred indicating a bug or unexpected condition.

  `FileNotFound`

    The specified file was not found.

  `InjectionFailed`

    Injection or hooking into the target process failed.

  `IncompatibleProcess`

    An incompatible process was found, e.g. a 32-bit process with 32-bit support not available.

  `NetworkIOFailed`

    A network I/O operation failed.

  `NetworkRemoteBusy`

    The remote side of the network connection was busy.

  `NetworkVersionMismatch`

    The other side of the network connection was not at a compatible version.

  `FileIOFailed`

    A filesystem I/O operation failed.

  `FileIncompatibleVersion`

    The capture file had an incompatible version.

  `FileCorrupted`

    The capture file is corrupted or otherwise unrecognisable.

  `ImageUnsupported`

    The image file is recognised but the format is unsupported.

  `APIUnsupported`

    The API used in the capture is not supported.

  `APIInitFailed`

    The API used in the capture failed to initialise.

  `APIIncompatibleVersion`

    The API data in the capture had an incompatible version.

  `APIHardwareUnsupported`

    The API is not supported on the currently available hardware.

  `APIDataCorrupted`

    While loading the capture for replay, the driver encountered corrupted or invalid serialised data.

  `APIReplayFailed`

    The API failed to replay the capture, with some runtime error that couldn’t be determined until the replay began.

  `AndroidGrantPermissionsFailed`

    Failed to grant runtime permissions when installing Android remote server.

  `AndroidABINotFound`

    Couldn’t determine supported ABIs when installing Android remote server.

  `AndroidAPKFolderNotFound`

    Couldn’t find the folder which contains the Android remote server APK.

  `AndroidAPKInstallFailed`

    Failed to install Android remote server for unknown reasons.

  `AndroidAPKVerifyFailed`

    Failed to install Android remote server.

class `renderdoc.``ReplaySupport`(value)

  How supported a given API is on a particular replay instance.

  `Unsupported`

    The API is not supported.

  `Supported`

    The API is fully supported.

  `SuggestRemote`

    The API is supported locally but the capture indicates it was made on a different type of machine so remote replay might be desired.

class `renderdoc.``CaptureFileFormat`

  The format for a capture file either supported to read from, or export to

  `convertSupported`

    Indicates whether captures or structured data can be saved out in this format.

  `description`

    A human readable long-form description of the file format.

  `extension`

    The file of the format as a single minimal string, e.g. `rdc`.

  `name`

    A human readable short phrase naming the file format.

  `openSupported`

    Indicates whether or not files in this format can be opened and processed as structured data.

  `requiresBuffers`

    Indicates whether exporting to this format requires buffers or just structured data. If it doesn’t require buffers then it can be exported directly from an opened capture, which by default has structured data but no buffers available.

class `renderdoc.``SectionProperties`

  Properties of a section in a renderdoc capture file.

  `compressedSize`

    The number of bytes of data in this section when compressed on disk.

  `flags`

    The flags describing how this section is stored.

  `name`

    The name of this section.

  `type`

    The type of this section, if it is a known pre-defined section.

  `uncompressedSize`

    The number of bytes of data contained in this section, once uncompressed.

  `version`

    The version of this section - the meaning of which is up to the type.

class `renderdoc.``SectionType`(value)

  The types of several pre-defined and known sections. This allows consumers of the API to recognise and understand the contents of the section.

  Note that sections above the highest value here may be encountered if they were written in a new version of RenderDoc that addes a new section type. They should be considered equal to `Unknown` by any processing.

  `Unknown`

    An unknown section - any custom or non-predefined section will have this type.

  `FrameCapture`

    This section contains the actual captured frame, in RenderDoc’s internal chunked representation. The contents can be fetched as structured data with or without replaying the frame.

    The name for this section will be “renderdoc/internal/framecapture”.

  `ResolveDatabase`

    This section contains platform-specific data used to resolve callstacks.

    The name for this section will be “renderdoc/internal/resolvedb”.

  `Bookmarks`

    This section contains a JSON document with bookmarks added to the capture to highlight important events.

    The name for this section will be “renderdoc/ui/bookmarks”.

  `Notes`

    This section contains a JSON document with free-form information added for human consumption, e.g. details about how the capture was obtained with repro steps in the original program, or with driver and machine info.

    The name for this section will be “renderdoc/ui/notes”.

  `ResourceRenames`

    This section contains a JSON document with custom names applied to resources in the UI, over and above any friendly names specified in the capture itself.

    The name for this section will be “renderdoc/ui/resrenames”.

  `AMDRGPProfile`

    This section contains a .rgp profile from AMD’s RGP tool, which can be extracted and loaded.

    The name for this section will be “amd/rgp/profile”.

  `ExtendedThumbnail`

    This section contains a thumbnail in format other than JPEG. For example, when it needs to be lossless.

    The name for this section will be “renderdoc/internal/exthumb”.

  `EmbeddedLogfile`

    This section contains the log file at the time of capture, for debugging.

    The name for this section will be “renderdoc/internal/logfile”.

  `EditedShaders`

    This section contains any edited shaders.

    The name for this section will be “renderdoc/ui/edits”.

  `D3D12Core`

    This section contains an internal copy of D3D12Core for replaying.

    The name for this section will be “renderdoc/internal/d3d12core”.

  `D3D12SDKLayers`

    This section contains an internal copy of D3D12SDKLayers for replaying.

    The name for this section will be “renderdoc/internal/d3d12sdklayers”.

class `renderdoc.``SectionFlags`(value)

  A set of flags describing the properties of a section in a renderdoc capture.

  `NoFlags`

    No special section properties.

  `ASCIIStored`

    This section was stored as pure ASCII. This can be useful since it is possible to generate an ASCII section in a text editor by hand or with any simple printf style script, and then concatenate it to a .rdc and have a valid section.

  `LZ4Compressed`

    This section is compressed with LZ4 on disk.

  `ZstdCompressed`

    This section is compressed with Zstd on disk.

class `renderdoc.``Thumbnail`

  Contains the bytes and metadata describing a thumbnail.

  `data`

    The `bytes` byte array containing the raw data.

  `height`

    The height of the thumbnail image.

  `type`

    The `FileType` of the data in the thumbnail.

  `width`

    The width of the thumbnail image.

## GPU Enumeration

class `renderdoc.``GPUDevice`

  Describes a single GPU at replay time.

  `apis`

    The APIs that this device supports.

    Type

      List[GraphicsAPI]

  `deviceID`

    The PCI deviceID of this GPU.

  `driver`

    The name of the driver of this GPU, if multiple drivers are available for it.

  `name`

    The human-readable name of this GPU.

  `vendor`

    The `GPUVendor` of this GPU.

class `renderdoc.``GPUVendor`(value)

  Identifies a GPU vendor.

  `Unknown`

    A GPU from an unknown vendor

  `ARM`

    An ARM GPU

  `AMD`

    An AMD GPU

  `Broadcom`

    A Broadcom GPU

  `Imagination`

    An Imagination GPU

  `Intel`

    An Intel GPU

  `nVidia`

    An nVidia GPU

  `Qualcomm`

    A Qualcomm GPU

  `Verisilicon`

    A Verisilicon or Vivante GPU

  `Software`

    A software-rendering emulated GPU

`renderdoc.``GPUVendorFromPCIVendor`(vendorID)

  Get the GPUVendor for a given PCI Vendor ID.

  Parameters

    vendorID (int) – The PCI Vendor ID

  Returns

    The vendor identified

  Return type

    GPUVendor

class `renderdoc.``GraphicsAPI`(value)

  Identifies a Graphics API.

  `D3D11`

    Direct3D 11.

  `D3D12`

    Direct3D 12.

  `OpenGL`

    OpenGL.

  `Vulkan`

    Vulkan.

`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

  Return type

    bool

`renderdoc.``GetDriverInformation`(api)

  Retrieves the driver information (if available) for a given graphics API.

  Parameters

    api (GraphicsAPI) – The API to get driver information for.

  Returns

    A `DriverInformation` containing the driver information.

  Return type

    DriverInformation

class `renderdoc.``DriverInformation`

  Gives information about the driver for this API.

  `vendor`

    The `GPUVendor` that provides this driver

  `version`

    The version string for the driver

## Replay Controller

class `renderdoc.``ReplayController`

  The primary interface to access the information in a capture and the current state, as well as control the replay and analysis functionality available.

  `KillCallback`()

    Not an actual member function - the signature for any `KillCallback` callbacks.

    Called whenever some on-going blocking process needs to determine if it should close.

    Returns

      Whether or not the process should be killed.

    Return type

      bool

  `ProgressCallback`()

    Not an actual member function - the signature for any `ProgressCallback` callbacks.

    Called by an on-going blocking process to update a progress bar or similar user feedback.

    The progress value will go from 0.0 to 1.0 as the process completes. Any other value will indicate that the process has completed

    Parameters

      progress (float) – The latest progress amount.

  `PreviewWindowCallback`()

    Not an actual member function - the signature for any `PreviewWindowCallback` callbacks.

    Called when a preview window could optionally be opened to display some information. It will be called repeatedly with `active` set to `True` to allow any platform-specific message pumping.

    Parameters

      active (bool) – `True` if a preview window is active/opened, `False` if it has closed.

    Returns

      The windowing data for a preview window, or empty/default values if no window should be created.

    Return type

      WindowingData

  `NoPreference`

    No preference for a particular value, see `ReplayController.DebugPixel()`.

  `AddFakeMarkers`()

    Add fake marker regions to the list of drawcalls in the capture, based on which textures are bound as outputs.

  `BuildCustomShader`(entry, sourceEncoding, source, compileFlags, type)

    Builds a shader suitable for running on the local replay instance as a custom shader.

    See `TextureDisplay.customShaderId`.

    Parameters

      - entry (str) – The entry point to use when compiling.

      - sourceEncoding (ShaderEncoding) – The encoding of the source data.

      - source (bytes) – The source data itself.

      - compileFlags (ShaderCompileFlags) – API-specific compilation flags.

      - type (ShaderStage) – The stage that this shader will be executed at.

    Returns

      A `tuple` with the id of the new shader if compilation was successful, `ResourceId.Null()` otherwise, and a `str` with any warnings/errors from compilation.

    Return type

      Tuple[ResourceId,str]

  `BuildTargetShader`(entry, sourceEncoding, source, compileFlags, type)

    Builds a shader suitable for running in the capture’s API as a replacement shader.

    Parameters

      - entry (str) – The entry point to use when compiling.

      - sourceEncoding (ShaderEncoding) – The encoding of the source data.

      - source (bytes) – The source data itself.

      - compileFlags (ShaderCompileFlags) – API-specific compilation flags.

      - type (ShaderStage) – The stage that this shader will be executed at.

    Returns

      A `tuple` with the id of the new shader if compilation was successful, `ResourceId.Null()` otherwise, and a `str` with any warnings/errors from compilation.

    Return type

      Tuple[ResourceId,str]

  `CancelReplayLoop`()

    Cancels a replay loop begun in `ReplayLoop()`. Does nothing if no loop is active.

  `ContinueDebug`(debugger)

    Continue a shader’s debugging with a given shader debugger instance. This will run an implementation defined number of steps and then return those steps in a list. This may be a fixed number of steps or it may run for a fixed length of time and return as many steps as can be calculated in that time.

    This will always perform at least one step. If the list is empty, the debugging process has completed, further calls will return an empty list.

    Parameters

      debugger (ShaderDebugger) – The shader debugger to continue running.

    Returns

      A number of subsequent states.

    Return type

      List[ShaderDebugState]

  `CreateOutput`(window, type)

    Creates a replay output of the given type to the given native window

    Parameters

      - window (WindowingData) – A `WindowingData` describing the native window.

      - type (ReplayOutputType) – What type of output to create

    Returns

      A handle to the created output, or `None` on failure

    Return type

      ReplayOutput

  `CreateRGPProfile`(window)

    Uses the given output window to create an RGP Profile.

    Parameters

      window (WindowingData) – A `WindowingData` describing the native window.

    Returns

      The path to the created RGP profile, or empty on failure

    Return type

      str

  `DebugPixel`(x, y, sample, primitive)

    Retrieve a debugging trace from running a pixel shader.

    Note

    X and Y co-ordinates are always considered to be top-left, even on GL, for consistency between APIs and preventing the need for API-specific code in most cases. This means if co-ordinates are fetched from e.g. viewport or scissor data or other GL pipeline state which is perhaps in bottom-left co-ordinates, care must be taken to translate them.

    Parameters

      - x (int) – The x co-ordinate.

      - y (int) – The y co-ordinate.

      - sample (int) – The multi-sampled sample. Ignored if non-multisampled texture.

      - primitive (int) – Debug the pixel from this primitive if there’s ambiguity. If set to `NoPreference` then a random fragment writing to the given co-ordinate is debugged.

    Returns

      The resulting trace resulting from debugging. Destroy with `FreeTrace()`.

    Return type

      ShaderDebugTrace

  `DebugThread`(groupid, threadid)

    Retrieve a debugging trace from running a compute thread.

    Parameters

      - groupid (Tuple[int,int,int]) – A list containing the 3D workgroup index.

      - threadid (Tuple[int,int,int]) – A list containing the 3D thread index within the workgroup.

    Returns

      The resulting trace resulting from debugging. Destroy with `FreeTrace()`.

    Return type

      ShaderDebugTrace

  `DebugVertex`(vertid, instid, idx, view)

    Retrieve a debugging trace from running a vertex shader.

    Parameters

      - vertid (int) – The vertex ID as a 0-based index up to the number of vertices in the draw.

      - instid (int) – The instance ID as a 0-based index up to the number of instances in the draw.

      - idx (int) – The actual index used to look up vertex inputs, either from the vertex ID for non- indexed draws or drawn from the index buffer. This must have all drawcall offsets applied.

      - view (int) – The index of the multiview viewport to use, or 0 if multiview is not in use.

    Returns

      The resulting trace resulting from debugging. Destroy with `FreeTrace()`.

    Return type

      ShaderDebugTrace

  `DescribeCounter`(counter)

    Get information about what a counter actually represents, in terms of a human-readable understanding as well as the type and unit of the resulting information.

    Parameters

      counter (GPUCounter) – The counter to query about.

    Returns

      The description of the counter.

    Return type

      CounterDescription

  `DisassembleShader`(pipeline, refl, target)

    Retrieve the disassembly for a given shader, for the given disassembly target.

    Parameters

      - pipeline (ResourceId) – The pipeline state object, if applicable, that this shader is bound to.

      - refl (ShaderReflection) – The shader reflection details of the shader to disassemble

      - target (str) – The name of the disassembly target to generate for. Must be one of the values returned by `GetDisassemblyTargets()`, or empty to use the default generation.

    Returns

      The disassembly text, or an error message if something went wrong.

    Return type

      str

  `EnumerateCounters`()

    Retrieve a list of which counters are available in the current capture analysis implementation.

    Returns

      The list of counters available.

    Return type

      List[GPUCounter]

  `FetchCounters`(counters)

    Retrieve the values of a specified set of counters.

    Parameters

      counters (List[GPUCounter]) – The list of counters to fetch results for.

    Returns

      The list of counter results generated.

    Return type

      List[CounterResult]

  `FileChanged`()

    Notify the interface that the file it has open has been changed on disk.

  `FreeCustomShader`(id)

    Free a previously created custom shader.

    See `BuildCustomShader()`.

    Parameters

      id (ResourceId) – The id of the custom shader to free.

  `FreeTargetResource`(id)

    Free a previously created target shader.

    See `BuildTargetShader()`.

    Parameters

      id (ResourceId) – The id of the target shader to free.

  `FreeTrace`(trace)

    Free a debugging trace from running a shader invocation debug.

    Parameters

      trace (ShaderDebugTrace) – The shader debugging trace to free.

  `GetAPIProperties`()

    Retrieve a `APIProperties` object describing the current capture.

    Returns

      The properties of the current capture.

    Return type

      APIProperties

  `GetBufferData`(buff, offset, len)

    Retrieve the contents of a range of a buffer as a `bytes`.

    Parameters

      - buff (ResourceId) – The id of the buffer to retrieve data from.

      - offset (int) – The byte offset to the start of the range.

      - len (int) – The length of the range, or 0 to retrieve the rest of the bytes in the buffer.

    Returns

      The requested buffer contents.

    Return type

      bytes

  `GetBuffers`()

    Retrieve the list of buffers alive in the capture.

    Returns

      The list of buffers in the capture.

    Return type

      List[BufferDescription]

  `GetCBufferVariableContents`(pipeline, shader, entryPoint, cbufslot, buffer, offset, length)

    Retrieve the contents of a constant block by reading from memory or their source otherwise.

    Parameters

      - pipeline (ResourceId) – The pipeline state object, if applicable, that this shader is bound to.

      - shader (ResourceId) – The id of the shader to use for metadata.

      - entryPoint (str) – The entry point of the shader being used. In some APIs, this is ignored.

      - cbufslot (int) – The index in the `ShaderReflection.constantBlocks` list to look up.

      - buffer (ResourceId) – The id of the buffer to use for data. If `ConstantBlock.bufferBacked` is `False` this is ignored.

      - offset (int) – Retrieve buffer contents starting at this byte offset.

      - length (int) – Retrieve this many bytes after `offset`. May be 0 to fetch the rest of the buffer.

    Returns

      The shader variables with their contents.

    Return type

      List[ShaderVariable]

  `GetCustomShaderEncodings`()

    Retrieve the list of supported `ShaderEncoding` which can be build using `BuildCustomShader()`.

    The list is sorted in priority order, so if the caller has a shader in a form but could compile/translate it to another, prefer to satisfy the first encoding before later encodings.

    This typically means the ‘native’ encoding is listed first, and then subsequent encodings are compiled internally - so compiling externally could be preferable as it allows better customisation of the compile process or using alternate/updated tools.

    Returns

      The list of target shader encodings available.

    Return type

      List[ShaderEncoding]

  `GetD3D11PipelineState`()

    Retrieve the current `D3D11State` pipeline state.

    The return value will be `None` if the capture is not using the D3D11 API. You should use `GetAPIProperties()` to determine the API of the capture.

    See also `GetPipelineState()`.

    Returns

      The current D3D11 pipeline state.

    Return type

      D3D11State

  `GetD3D12PipelineState`()

    Retrieve the current `D3D12State` pipeline state.

    The return value will be `None` if the capture is not using the D3D12 API. You should use `GetAPIProperties()` to determine the API of the capture.

    See also `GetPipelineState()`.

    Returns

      The current D3D12 pipeline state.

    Return type

      D3D12State

  `GetDebugMessages`()

    Retrieve a list of any newly generated diagnostic messages.

    Every time this function is called, any debug messages returned will not be returned again. Only newly generated messages will be returned after that.

    Returns

      The list of the `DebugMessage` messages.

    Return type

      List[DebugMessage]

  `GetDisassemblyTargets`(withPipeline)

    Retrieve the list of possible disassembly targets for `DisassembleShader()`. The values are implementation dependent but will always include a default target first which is the native disassembly of the shader. Further options may be available for additional diassembly views or hardware-specific ISA formats.

    Parameters

      withPipeline (bool) – More disassembly may be available when a pipeline is specified.

    Returns

      The list of disassembly targets available.

    Return type

      List[str]

  `GetDrawcalls`()

    Retrieve the list of root-level drawcalls in the capture.

    Returns

      The list of root-level drawcalls in the capture.

    Return type

      List[DrawcallDescription]

  `GetFrameInfo`()

    Retrieve the information about the frame contained in the capture.

    Returns

      The frame information.

    Return type

      FrameDescription

  `GetGLPipelineState`()

    Retrieve the current `GLState` pipeline state.

    The return value will be `None` if the capture is not using the OpenGL API. You should use `GetAPIProperties()` to determine the API of the capture.

    See also `GetPipelineState()`.

    Returns

      The current OpenGL pipeline state.

    Return type

      GLState

  `GetHistogram`(textureId, sub, typeCast, minval, maxval, channels)

    Retrieve a list of values that can be used to show a histogram of values for the specified texture.

    The output list contains N buckets, and each bucket has the number of pixels that falls in each bucket when the pixel values are divided between `minval` and `maxval`.

    Parameters

      - textureId (ResourceId) – The texture to get the histogram from.

      - sub (Subresource) – The subresource within this texture to use.

      - typeCast (CompType) – If possible interpret the texture with this type instead of its normal type. If set to `CompType.Typeless` then no cast is applied, otherwise where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values.

      - minval (float) – The lower end of the smallest bucket. If any values are below this, they are not added to any bucket.

      - maxval (float) – The upper end of the largest bucket. If any values are above this, they are not added to any bucket.

      - channels (Tuple[bool,bool,bool,bool]) – A set of four flags indicating whether each of RGBA respectively should be included in the count.

    Returns

      A list of the unnormalised bucket values.

    Return type

      List[int]

  `GetMinMax`(textureId, sub, typeCast)

    Retrieves the minimum and maximum values in the specified texture.

    Parameters

      - textureId (ResourceId) – The texture to get the values from.

      - sub (Subresource) – The subresource within this texture to use.

      - typeCast (CompType) – If possible interpret the texture with this type instead of its normal type. If set to `CompType.Typeless` then no cast is applied, otherwise where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values.

    Returns

      A tuple with the minimum and maximum pixel values respectively.

    Return type

      Tuple[PixelValue,PixelValue]

  `GetPipelineState`()

    Retrieve the current `PipeState` pipeline state abstraction.

    This pipeline state will always be valid, and allows queries that will work regardless of the capture’s API.

    Returns

      The current pipeline state abstraction.

    Return type

      PipeState

  `GetPostVSData`(instance, view, stage)

    Retrieve the generated data from one of the geometry processing shader stages.

    Parameters

      - instance (int) – The index of the instance to retrieve data for, or 0 for non-instanced draws.

      - view (int) – The index of the multiview view to retrieve data for, or 0 if multiview is disabled.

      - stage (MeshDataStage) – The stage of the geometry processing pipeline to retrieve data from.

    Returns

      The information describing where the post-transform data is stored.

    Return type

      MeshFormat

  `GetResources`()

    Retrieve the list of all resources in the capture.

    This includes any object allocated a `ResourceId`, that don’t have any other state or are only used as intermediary elements.

    Returns

      The list of resources in the capture.

    Return type

      List[ResourceDescription]

  `GetShader`(pipeline, shader, entry)

    Retrieve the information about the frame contained in the capture.

    Parameters

      - pipeline (ResourceId) – The pipeline state object, if applicable, that this shader is bound to.

      - shader (ResourceId) – The shader to get reflection data for.

      - entry (ShaderEntryPoint) – The entry point within the shader to reflect. May be ignored on some APIs

    Returns

      The frame information.

    Return type

      ShaderReflection

  `GetShaderEntryPoints`(shader)

    Retrieve a list of entry points for a shader.

    If the given ID doesn’t specify a shader, an empty list will be return. On some APIs, the list will only ever have one result (only one entry point per shader).

    Parameters

      shader (ResourceId) – The shader to look up entry points for.

    Returns

      The list of the `ShaderEntryPoint` messages.

    Return type

      List[ShaderEntryPoint]

  `GetStructuredFile`()

    Fetch the structured data representation of the capture loaded.

    Returns

      The structured file.

    Return type

      SDFile

  `GetSupportedWindowSystems`()

    Retrieves the supported `WindowingSystem` systems by the local system.

    Returns

      The list of supported systems.

    Return type

      List[WindowingSystem]

  `GetTargetShaderEncodings`()

    Retrieve the list of supported `ShaderEncoding` which can be build using `BuildTargetShader()`.

    The list is sorted in priority order, so if the caller has a shader in a form but could compile/translate it to another, prefer to satisfy the first encoding before later encodings.

    This typically means the ‘native’ encoding is listed first, and then subsequent encodings are compiled internally - so compiling externally could be preferable as it allows better customisation of the compile process or using alternate/updated tools.

    Returns

      The list of target shader encodings available.

    Return type

      List[ShaderEncoding]

  `GetTextureData`(tex, sub)

    Retrieve the contents of one subresource of a texture as a `bytes`.

    Parameters

      - tex (ResourceId) – The id of the texture to retrieve data from.

      - sub (Subresource) – The subresource within this texture to use.

    Returns

      The requested texture contents.

    Return type

      bytes

  `GetTextures`()

    Retrieve the list of textures alive in the capture.

    Returns

      The list of textures in the capture.

    Return type

      List[TextureDescription]

  `GetUsage`(id)

    Retrieve a list of ways a given resource is used.

    Parameters

      id (ResourceId) – The id of the texture or buffer resource to be queried.

    Returns

      The list of usages of the resource.

    Return type

      List[EventUsage]

  `GetVulkanPipelineState`()

    Retrieve the current `VKState` pipeline state.

    The return value will be `None` if the capture is not using the Vulkan API. You should use `GetAPIProperties()` to determine the API of the capture.

    See also `GetPipelineState()`.

    Returns

      The current Vulkan pipeline state.

    Return type

      VKState

  `PickPixel`(textureId, x, y, sub, typeCast)

    Retrieve the contents of a particular pixel in a texture.

    Note

    X and Y co-ordinates are always considered to be top-left, even on GL, for consistency between APIs and preventing the need for API-specific code in most cases. This means if co-ordinates are fetched from e.g. viewport or scissor data or other GL pipeline state which is perhaps in bottom-left co-ordinates, care must be taken to translate them.

    Parameters

      - textureId (ResourceId) – The texture to pick the pixel from.

      - x (int) – The x co-ordinate to pick from.

      - y (int) – The y co-ordinate to pick from.

      - sub (Subresource) – The subresource within this texture to use.

      - typeCast (CompType) – If possible interpret the texture with this type instead of its normal type. If set to `CompType.Typeless` then no cast is applied, otherwise where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values.

    Returns

      The contents of the pixel.

    Return type

      PixelValue

  `PixelHistory`(texture, x, y, sub, typeCast)

    Retrieve the history of modifications to the selected pixel on the selected texture.

    Note

    X and Y co-ordinates are always considered to be top-left, even on GL, for consistency between APIs and preventing the need for API-specific code in most cases. This means if co-ordinates are fetched from e.g. viewport or scissor data or other GL pipeline state which is perhaps in bottom-left co-ordinates, care must be taken to translate them.

    Parameters

      - texture (ResourceId) – The texture to search for modifications.

      - x (int) – The x co-ordinate.

      - y (int) – The y co-ordinate.

      - sub (Subresource) – The subresource within this texture to use.

      - typeCast (CompType) – If possible interpret the texture with this type instead of its normal type. If set to `CompType.Typeless` then no cast is applied, otherwise where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values.

    Returns

      The list of pixel history events.

    Return type

      List[PixelModification]

  `RemoveReplacement`(id)

    Remove any previously specified replacement for an object.

    See `ReplaceResource()`.

    Parameters

      id (ResourceId) – The id of the original resource that was previously being substituted.

  `ReplaceResource`(original, replacement)

    Replace one resource with another for subsequent replay and analysis work.

    This is commonly used for modifying the capture by selectively replacing resources with newly created resources.

    See `BuildTargetShader()`, `RemoveReplacement()`.

    Parameters

      - original (ResourceId) – The id of the original resource that should be substituted.

      - replacement (ResourceId) – The id of the new resource that should be used instead.

  `ReplayLoop`(window, texid)

    Goes into a blocking loop, repeatedly replaying the open capture as fast as possible, displaying the selected texture in a default unscaled manner to the given output window.

    The function won’t return until `CancelReplayLoop()` is called. Since this function is blocking, that function must be called from another thread.

    Parameters

      - window (WindowingData) – A `WindowingData` describing the native window.

      - texid (ResourceId) – The id of the texture to display.

  `SaveTexture`(saveData, path)

    Save a texture to a file on disk, with possible transformation to map a complex texture to something compatible with the target file format.

    Parameters

      - saveData (TextureSave) – The configuration settings of which texture to save, and how

      - path (str) – The path to save to on disk.

    Returns

      `True` if the texture was saved successfully, `False` otherwise.

    Return type

      bool

  `SetFrameEvent`(eventId, force)

    Move the replay to reflect the state immediately after the given `eventId`.

    Parameters

      - eventId (int) – The `eventId` to move to.

      - force (bool) – `True` if the internal replay should refresh even if the `eventId` is already current. This can be useful if external factors might cause the replay to vary.

  `Shutdown`()

    Shutdown and destroy the current interface and all outputs that have been created.

class `renderdoc.``ReplayOptions`

  The options controlling how replay of a capture should be performed

  `apiValidation`

    Replay with API validation enabled and use debug messages from there, ignoring any that may be contained in the capture.

    The default is not to do any validation.

    Note

    RenderDoc does not handle invalid API use in the general case so validation should still be performed at runtime in your program for ground truth results.

  `forceGPUDeviceID`

    Force the selection of a GPU by device ID. This allows overriding which GPU is used to replay on.

    When set to 0, specifies no particular device.

    See `forceGPUDeviceID` for a full explanation of GPU selection override.

  `forceGPUDriverName`

    Force the selection of a GPU by driver name. This allows overriding which GPU is used to replay on.

    When set to an empty string, specifies no particular driver.

    See `forceGPUDeviceID` for a full explanation of GPU selection override.

  `forceGPUVendor`

    Force the selection of a GPU by vendor ID. This allows overriding which GPU is used to replay on, even if a different GPU would be the best match for the capture.

    When set to `GPUVendor.Unknown`, specifies no particular vendor.

    See also `forceGPUDeviceID` and `forceGPUDriverName`. Available GPUs can be enumerated using `CaptureAccess.GetAvailableGPUs()`.

    The default is not to do any override. The capture contains information about what GPU was used, and the closest matching GPU is used on replay.

    Note

    If a GPU is forced that is not available or not supported for a given capture, such as when GPUs are only available for some APIs and not others, the default GPU selection will be used. If a GPU is available for a capture but fails to open however then there is no fallback to a default GPU.

    OpenGL does not support GPU selection so the default method (which effectively does nothing) will always be used.

  `optimisation`

    How much optimisation should be done, potentially at the cost of correctness.

    The default is `ReplayOptimisationLevel.Balanced`.

class `renderdoc.``ReplayOptimisationLevel`(value)

  The level of optimisation used in

  `NoOptimisation`

    Completely disabled, no optimisation will be used at all.

  `Conservative`

    Optimisation is used when it doesn’t interfere with replay correctness.

  `Balanced`

    Optimisation is used when it has minimal impact on replay correctness. This could include e.g. resources appearing cleared instead of containing contents from prior frames where those resources are written to before being read.

  `Fastest`

    All possible optimisations are enabled as long as they do not cause invalid/incorrect replay. This could result in side-effects like data from one replay being visible early in another replay, if it’s known that the data will be overwritten before being used.

class `renderdoc.``APIProperties`

  Gives some API-specific information about the capture.

  `degraded`

    `True` if the capture was loaded successfully but running in a degraded mode - e.g. with software rendering, or with some functionality disabled due to lack of support.

  `localRenderer`

    The `GraphicsAPI` used to render the log. For remote replay this could be different to the above, and lets the UI make decisions e.g. to flip rendering of images.

  `pipelineType`

    The `GraphicsAPI` of the actual log/capture.

  `pixelHistory`

    (`True` if the API supports viewing pixel history.

  `remoteReplay`

    `True` if the capture is being replayed over a remote connection.

  `rgpCapture`

    `True` if the driver and system are configured to allow creating RGP captures.

  `shaderDebugging`

    (`True` if the API supports shader debugging.

  `shadersMutable`

    `True` if the driver mutates shader reflection structures from event to event. Currently this is only true for OpenGL where the superfluous indirect in the binding model must be worked around by re-sorting bindings.

  `vendor`

    The `GPUVendor` of the active GPU being used.

## Device Protocols

class `renderdoc.``DeviceProtocolController`

  An interface for enumerating and controlling remote devices.

  `GetDevices`()

    Returns a list of devices currently available through the given protocol.

    Until a device is enumerated through this function it may not be available for connection through other methods such as target control or remote server access, even if the device is physically connected, due to initialisation happening only when enumerated.

    The returned string is the hostname of the device, which can be connected via `protocol://hostname` with interfaces that take a hostname.

    Returns

      A list of the devices currently available.

    Return type

      List[str]

  `GetFriendlyName`(URL)

    Retrieves the user friendly name of the given device. This may be easier for a user to correlate to a device than the hostname which may be only a programmatic identifier.

    Parameters

      URL (str) – The URL of the device in the form `protocol://host`, with protocol as returned by `GetProtocolName()` and host as returned by `GetDevices()`.

    Returns

      A string identifying the device.

    Return type

      str

  `GetProtocolName`()

    Retrieves the name of this protocol as passed to `GetDeviceProtocolController()`.

    Returns

      A string identifying the protocol.

    Return type

      str

  `IsSupported`(URL)

    Query if the device supports RenderDoc capture and replay.

    Parameters

      URL (str) – The URL of the device in the form `protocol://host`, with protocol as returned by `GetProtocolName()` and host as returned by `GetDevices()`.

    Returns

      `True` if any the device is supported, `False` otherwise.

    Return type

      bool

  `StartRemoteServer`(URL)

    Start the remote server running on the given device.

    Parameters

      URL (str) – The URL of the device in the form `protocol://host`, with protocol as returned by `GetProtocolName()` and host as returned by `GetDevices()`.

    Returns

      The status of starting the server, whether success or failure.

    Return type

      ReplayStatus

  `SupportsMultiplePrograms`(URL)

    Query if the device supports multiple programs running and being captured. If not, the user can be prompted to close an existing program before a new one is launched.

    Parameters

      URL (str) – The URL of the device in the form `protocol://host`, with protocol as returned by `GetProtocolName()` and host as returned by `GetDevices()`.

    Returns

      `True` if the device supports multiple programs, `False` otherwise.

    Return type

      bool

`renderdoc.``GetSupportedDeviceProtocols`()

  Retrieve the set of device protocols supported (see `GetDeviceProtocolController()`).

  Returns

    The supported device protocols.

  Return type

    List[str]

`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

## Remote Servers

class `renderdoc.``RemoteServer`

  A connection to a running remote RenderDoc server on another machine. This allows the transfer of captures to and from the local machine, as well as remotely replaying a capture with a local proxy renderer, so that captures that are not supported locally can still be debugged with as much work as possible happening on the local machine.

  `NoPreference`

    No preference for a particular value, see `ReplayController.DebugPixel()`.

  `CloseCapture`(rend)

    Close a capture analysis handle previously opened by `OpenCapture()`.

    Parameters

      rend (ReplayController) – The ReplayController that is to be closed.

  `CopyCaptureFromRemote`(remotepath, localpath, progress)

    Copy a capture file that is stored on the remote system to the local system.

    This function will block until the copy is fully complete, or an error has occurred.

    Parameters

      - remotepath (str) – The remote path where the file should be copied from.

      - localpath (str) – The local path where the file should be saved.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the copy. Can be `None` if no progress is desired.

  `CopyCaptureToRemote`(filename, progress)

    Copy a capture file that is stored on the local system to the remote system.

    This function will block until the copy is fully complete, or an error has occurred.

    This is primarily useful for when a capture is only stored locally and must be replayed remotely, as the capture must be available on the machine where the replay happens.

    Parameters

      - filename (str) – The path to the file on the local system.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the copy. Can be `None` if no progress is desired.

    Returns

      The path on the remote system where the capture was saved temporarily.

    Return type

      str

  `ExecuteAndInject`(app, workingDir, cmdLine, env, opts)

    Launch an application and inject into it to allow capturing.

    This happens on the remote system, so all paths are relative to the remote filesystem.

    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.

      - opts (CaptureOptions) – The capture options to use when injecting into the program.

    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

  `GetHomeFolder`()

    Retrieve the path on the remote system where browsing can begin.

    Returns

      The ‘home’ path where browsing for files or folders can begin.

    Return type

      str

  `ListFolder`(path)

    Retrieve the contents of a folder path on the remote system.

    If an error occurs, a single `PathEntry` will be returned with appropriate error flags.

    Parameters

      path (str) – The remote path to list.

    Returns

      The contents of the specified folder.

    Return type

      List[PathEntry]

  `LocalProxies`()

    Retrieve a list of renderers available for local proxying.

    These will be strings like “D3D11” or “OpenGL”.

    Returns

      A list of names of the local proxies.

    Return type

      List[str]

  `OpenCapture`(proxyid, logfile, opts, progress)

    Open a capture file for remote capture and replay. The capture will be opened and replayed on the remote system, and proxied to the local system with a given renderer. As much work as possible will happen locally to save on bandwidth, processing and latency.

    This function will block until the capture is fully opened on the remote system and ready for use, or an error has occurred.

    Note

    You must close the resulting `ReplayController` with the `CloseCapture()` function to ensure the local proxy is correctly tidied up, instead of using `ReplayController.Shutdown()`.

    Parameters

      - proxyid (int) – The index in the array returned by `LocalProxies()` to use as a local proxy, or `NoPreference` to indicate no preference for any proxy.

      - logfile (str) – The path on the remote system where the file is. If the file is only available locally you can use `CopyCaptureToRemote()` to transfer it over the remote connection.

      - opts (ReplayOptions) – The options controlling how the capture should be replayed.

      - progress (ProgressCallback) – A callback that will be repeatedly called with an updated progress value for the opening. Can be `None` if no progress is desired.

    Returns

      A tuple containing the status of opening the capture, whether success or failure, and the resulting `ReplayController` handle if successful.

    Return type

      Tuple[ReplayStatus,ReplayController]

  `Ping`()

    Pings the remote server to ensure the connection is still alive.

    Returns

      `True` if the ping was sent and received successfully, `False` if something went wrong and the connection is no longer alive.

    Return type

      bool

  `RemoteSupportedReplays`()

    Retrieve a list of renderers supported by the remote server.

    These will be strings like “D3D11” or “OpenGL”.

    Returns

      A list of names of the remote renderers.

    Return type

      List[str]

  `ShutdownConnection`()

    Closes the connection without affecting the running server.

  `ShutdownServerAndConnection`()

    Closes the connection and also tells the running server to close.

  `TakeOwnershipCapture`(filename)

    Take ownership over a capture file.

    Initially when a capture is made, it is owned by the injected library in the application. It passes ownership to any program that is connected via target control that is notified about the capture, which is then responsible for either saving the file or deleting it if it’s unwanted.

    Passing ownership of a file to the remote server means that it will be kept around for future use until the server closes, at which point it will delete any files it owns.

    Parameters

      filename (str) – The remote path to take ownership of.

`renderdoc.``CreateRemoteServerConnection`(URL)

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

  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 connection, whether success or failure, and a `RemoteServer` instance if it were successful

  Return type

    Tuple[ReplayStatus,RemoteServer]

`renderdoc.``CheckRemoteServerConnection`(URL)

  Check the connection to a remote server running on given hostname.

  This should be preferred to `CreateRemoteServerConnection()` when no connection is desired, as the status can be checked without interfering with making connections.

  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 the server.

  Return type

    ReplayStatus

`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 returns `True`.

  Parameters

    - listenhost (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.

class `renderdoc.``PathEntry`

  Properties of a path on a remote filesystem.

  `filename`

    The filename of this path. This contains only the filename, not the full path.

  `flags`

    The `PathProperty` flags for this path.

  `lastmod`

    The last modified date of this path, as a unix timestamp in UTC.

  `size`

    The size of the path in bytes.

class `renderdoc.``PathProperty`(value)

  A set of flags describing the properties of a path on a remote filesystem.

  `NoFlags`

    No special file properties.

  `Directory`

    This file is a directory or folder.

  `Hidden`

    This file is considered hidden by the filesystem.

  `Executable`

    This file has been identified as an executable program or script.

  `ErrorUnknown`

    A special flag indicating that a query for this file failed, but for unknown reasons.

  `ErrorAccessDenied`

    A special flag indicating that a query for this file failed because access to the path was denied.

  `ErrorInvalidPath`

    A special flag indicating that a query for this file failed because the path was invalid.