# Primary Interfaces

Contents

- Primary Interfaces
  - ReplayController
  - ReplayOutput
  - TargetControl
  - RemoteServer
  - DeviceProtocolController
  - CaptureFile
  - GlobalEnvironment

## ReplayController

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 (int) – 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` of `ResourceId` and `str`.

  `BuildTargetShader`(entry, sourceEncoding, source, flags, 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` of `ResourceId` and `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` of `ShaderDebugTrace`

  `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 – A list containing the 3D workgroup index. threadid – A list containing the 3D thread index within the above workgroup.
    Returns: | The resulting trace resulting from debugging. Destroy with `FreeTrace()`.
    Return type: | ShaderDebugTrace

  `DebugVertex`(vertid, instid, idx)

    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.
    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` of `GPUCounter`

  `FetchCounters`(counters)

    Retrieve the values of a specified set of counters.

    Parameters: | counters (list) – The list of `GPUCounter` to fetch results for.
    Returns: | The list of counter results generated.
    Return type: | `list` of `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` of `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` of `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` of `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` of `DebugMessage`

  `GetDisassemblyTargets`()

    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.

    Returns: | The list of disassembly targets available.
    Return type: | `list` of `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` of `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 (list) – A list of four `bool` values indicating whether each of RGBA should be included in the count.
    Returns: | A list of the unnormalised bucket values.
    Return type: | `list` of `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` of PixelValue and 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` of `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` of `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` of `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` of `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` of `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` of `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. sampleIdx (int) – The multi-sampled sample. Ignored if non-multisampled texture. 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` of `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.

## ReplayOutput

class `renderdoc.``ReplayOutput`

  A stateful output handle that contains the current configuration for one particular view of the capture. This allows multiple outputs to run independently without interfering with each other.

  The different types are enumerated in `ReplayOutputType`.

  `NoResult`

    No result was found in e.g. `PickVertex()`.

  `AddThumbnail`(window, textureId, sub, typeCast)

    Sets up a thumbnail for displaying a particular texture with sensible defaults.

    The window handle specified will be filled (in an aspect-ratio preserving way) with the texture.

    If the window specified has been used for a thumbnail before, then the texture will be updated but otherwise nothing will be created and the existing internal data will be reused. This means that you can call this function multiple times to just change the texture.

    Should only be called for texture outputs.

    Parameters: | window (WindowingData) – A `WindowingData` describing the native window. textureId (ResourceId) – The texture ID to display in the thumbnail preview. 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 boolean indicating if the thumbnail was successfully created.
    Return type: | `bool`

  `ClearThumbnails`()

    Clear and release all thumbnails associated with this output. See `AddThumbnail()`.

  `DisablePixelContext`()

    Disable the pixel context view from rendering.

  `Display`()

    Render to the window handle specified when the output was created.

    This will also render any thumbnails and the pixel context, if enabled.

  `GetCustomShaderTexID`()

    Retrieves the `ResourceId` containing the contents of the texture after being passed through a custom shader pass.

    Should only be called for texture outputs.

    Returns: | The `ResourceId` assigned to the texture with the results of the custom shader.
    Return type: | ResourceId

  `GetDebugOverlayTexID`()

    Retrieves the `ResourceId` containing the contents of the debug overlay rendering (if enabled).

    Should only be called for texture outputs.

    Returns: | The `ResourceId` assigned to the texture with the debug overlay.
    Return type: | ResourceId

  `GetDimensions`()

    Retrieve the current dimensions of the output.

    Returns: | The current width and height of the output.
    Return type: | `pair` of two `int`

  `PickVertex`(x, y)

    Retrieves the vertex and instance that is under the cursor location, when viewed relative to the current window with the current mesh display configuration.

    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.

    Should only be called for mesh outputs.

    Parameters: | x (int) – The x co-ordinate to pick from. y (int) – The y co-ordinate to pick from.
    Returns: | A tuple with the first value being the vertex index in the mesh, and the second value being the instance index. The values are set to `NoResult` if no vertex was found,
    Return type: | `tuple` of `int` and `int`

  `ReadbackOutputTexture`()

    Read the output texture back as byte data. Primarily useful for headless outputs where the output data is not displayed anywhere natively.

    Returns: | The output texture data as tightly packed RGB 3-byte data.
    Return type: | `bytes`

  `SetDimensions`(width, height)

    Sets the dimensions of the output, useful only for headless outputs that don’t have a backing window which don’t have any implicit dimensions. This allows configuring a virtual viewport which is useful for operations like picking vertices that depends on the output dimensions.

    Note

    For outputs with backing windows, this will be ignored.

    Parameters: | width (int) – The width to use. height (int) – The height to use.

  `SetMeshDisplay`(o)

    Sets the `MeshDisplay` configuration for a mesh output.

  `SetPixelContext`(window)

    Sets up a zoomed in pixel context view around a particular pixel selection.

    The texture rendering uses the configuration specified in `SetTextureDisplay()` except with a fixed high zoom value and a fixed position, see `SetPixelContextLocation()`.

    Should only be called for texture outputs.

    Parameters: | window (WindowingData) – A `WindowingData` describing the native window.
    Returns: | A boolean indicating if the pixel context was successfully configured.
    Return type: | `bool`

  `SetPixelContextLocation`(x, y)

    Sets the pixel that the pixel context should be centred on.

    Should only be called for texture outputs.

  `SetTextureDisplay`(o)

    Sets the `TextureDisplay` configuration for a texture output.

  `Shutdown`()

    Shutdown this output.

    It’s optional to call this, as calling `ReplayController.Shutdown()` will shut down all of its outputs.

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

## RemoteServer

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) – Any `EnvironmentModification` 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` of `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` of `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` of `ReplayStatus` and `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` of `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.

## DeviceProtocolController

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` of `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`

## CaptureFile

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` of `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` of `ReplayStatus` and `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)

    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.

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

## GlobalEnvironment

class `renderdoc.``GlobalEnvironment`

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