API Reference: qrenderdoc Main Interfaces

This is the API reference for the functions, classes, and enums in the qrenderdoc module which represents the UI-specific interface for integrating with the UI and writing UI extensions. For more high-level information and instructions on using the python API, see Python API and Tutorial: UI extensions.

Context

class qrenderdoc.CaptureContext

The capture context that the python script is running in.

Available as a pyrenderdoc global variable in any python scripts run from RenderDoc’s UI.

APIProps()

Retrieve the APIProperties for the currently loaded capture.

Returns:

The API properties.

Return type:

renderdoc.APIProperties

AddCaptureViewer(viewer)

Register a new instance of CaptureViewer to receive capture event notifications.

Parameters:

viewer# (CaptureViewer) – The viewer to register.

AddDockWindow(newWindow, ref, refWindow, percentage=0.5)

Adds a new window within the docking system.

Parameters:

  • newWindow# (QWidget) – The new window to add.

  • ref# (DockReference) – The location to add the new window, possibly relative to refWindow.

  • refWindow# (QWidget) – The window to refer to if the new window is being added relative, or can be None if the new location is absolute.

  • 5# (float) – Optional parameter. The percentage to split the area. If omitted, a 50% split is used.

AddMessages(msgs)

Add messages into the list returned by DebugMessages(). Initially set to unread.

Parameters:

msgs# (List[renderdoc.DebugMessage]) – A list of debug messages to add.

BuiltinWindowClosed(window)

Marks a built-in window as closed.

This function is intended for internal use by the built-in windows for singleton management, and should not be called by user code.

Parameters:

window# (QWidget) – The built-in window that closed.

ClearMessages()

Clear the currently stored messages, and mark all as unread. This can be used in combination with DebugMessages() and AddMessages() to filter the current set of messages.

ClearReplayCache()

Clear any cached data from previous replays and ensure subsequent replays fully re-initialise any data, including e.g. bindless feedback, printf results or mesh output data.

CloseCapture()

Close the currently open capture file.

Config()

Retrieve the current persistent config.

Returns:

The current persistent config manager.

Return type:

PersistentConfig

ConnectToRemoteServer(host)

Connect to a remote server.

Parameters:

host# (RemoteHost) – The host to connect to.

CreateBuiltinWindow(objectName)

Creates and returns a built-in window.

This function is intended for internal use for restoring layouts, and generally should not be used by user code.

Parameters:

objectName# (str) – The built-in name of a singleton window.

Returns:

The handle to the existing or newly created window of this type.

Return type:

QWidget

CreateWindowingData(window)

Create an opaque pointer suitable for passing to CreateOutput() or other functions that expect windowing data.

Note

This function must be called on the main UI thread.

Parameters:

window# (QWidget) – The window to create windowing data for.

Returns:

The windowing data.

Return type:

renderdoc.WindowingData

CurAction()

Retrieve the current action.

Returns:

The current action, or None if no action is selected.

Return type:

renderdoc.ActionDescription

CurD3D11PipelineState()

Retrieve the current D3D11State pipeline state.

The return value will be None if the capture is not using the D3D11 API. You should determine the API of the capture first before fetching it.

Returns:

The current D3D11 pipeline state.

Return type:

renderdoc.D3D11State

CurD3D12PipelineState()

Retrieve the current D3D12State pipeline state.

The return value will be None if the capture is not using the D3D12 API. You should determine the API of the capture first before fetching it.

Returns:

The current D3D12 pipeline state.

Return type:

renderdoc.D3D12State

CurEvent()

Retrieve the current eventId.

Returns:

The current event.

Return type:

int

CurGLPipelineState()

Retrieve the current GLState pipeline state.

The return value will be None if the capture is not using the OpenGL API. You should determine the API of the capture first before fetching it.

Returns:

The current OpenGL pipeline state.

Return type:

renderdoc.GLState

CurPipelineState()

Retrieve the current PipeState abstracted pipeline state.

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

Returns:

The current API-agnostic abstracted pipeline state.

Return type:

renderdoc.PipeState

CurRootActions()

Retrieve the root list of actions in the current capture.

Returns:

The root actions.

Return type:

List[renderdoc.ActionDescription]

CurSelectedAction()

Retrieve the currently selected action.

In most cases, prefer using CurAction(). See CaptureViewer.OnSelectedEventChanged() for more information for how this differs.

Returns:

The currently selected action.

Return type:

renderdoc.ActionDescription

CurSelectedEvent()

Retrieve the currently selected eventId.

In most cases, prefer using CurEvent(). See CaptureViewer.OnSelectedEventChanged() for more information for how this differs.

Returns:

The current selected event.

Return type:

int

CurVulkanPipelineState()

Retrieve the current VKState pipeline state.

The return value will be None if the capture is not using the Vulkan API. You should determine the API of the capture first before fetching it.

Returns:

The current Vulkan pipeline state.

Return type:

renderdoc.VKState

CurWindowingSystem()

Retrieve the current windowing system in use.

Returns:

The active windowing system.

Return type:

renderdoc.WindowingSystem

CustomShaderEncodings()

Retrieve the list of ShaderEncoding that are available for building custom shaders for the currently loaded capture. See BuildCustomShader().

Returns:

The available encodings.

Return type:

List[renderdoc.ShaderEncoding]

CustomShaderSourcePrefixes()

Retrieve the list of prefixes for each ShaderEncoding that should be added to custom compiled shaders. See GetCustomShaderSourcePrefixes().

Returns:

A list of pairs, listing a prefix for each shader encoding referenced.

Return type:

List[renderdoc.ShaderSourcePrefix]

DebugMessages()

Retrieve the current list of debug messages. This includes messages from the capture as well as messages generated during replay and analysis.

Returns:

The debug messages generated to date.

Return type:

List[renderdoc.DebugMessage]

DebugShader(shader, pipeline, trace, debugContext)

Show a new ShaderViewer window, showing a read-only view of a debug trace through the execution of a given shader.

Parameters:

  • shader# (renderdoc.ShaderReflection) – The reflection data for the shader to view.

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

  • trace# (renderdoc.ShaderDebugTrace) – The execution trace of the debugged shader.

  • debugContext# (str) – A human-readable context string describing which invocation of this shader was debugged. For example ‘Pixel 12,34 at eventId 678’.

Returns:

The new ShaderViewer window opened, but not shown.

Return type:

ShaderViewer

DelayedCallback(milliseconds, callback)

Registers a delayed callback to be called after a certain number of milliseconds on the UI thread.

Parameters:

  • milliseconds# (int) – The number of milliseconds (approximately) to wait before the callback.

  • callback (Callable[[], None]) – The function to call

EditShader(id, stage, entryPoint, files, knownTool, shaderEncoding, flags, saveCallback, revertCallback)

Show a new ShaderViewer window, showing an editable view of a given shader.

Parameters:
Returns:

The new ShaderViewer window opened but not shown for editing.

Return type:

ShaderViewer

EmbedDependentFiles()

Stores the dependent file data into the capture i.e. shader debug files.

This reads the contents of the dependent files and stores their file contents into the capture. This can help the capture to be more portable by embedding all externally referenced dependent files. Use RemoveDependentFiles() to remove the embedded file data.

Warning

Will remove all the existing embedded file data from the capture. Will directly modify the capture file on disk.

Note

This will increase the size of the capture file. Externally referenced files which can’t be found on disk are skipped. For remote replay the modifications are performed on the remote machine and copied back to the local host.

ExportCapture(fmt, exportfile)

Exports the current capture file to a given path with a specified capture file format.

The capture must be available locally, if it’s not this function will fail.

Parameters:
Extensions()

Retrieve the manager for extensions.

Returns:

The current extension manager.

Return type:

ExtensionManager

FrameInfo()

Retrieve the FrameDescription for the currently loaded capture.

Returns:

The frame information.

Return type:

renderdoc.FrameDescription

GetAPIInspector()

Retrieve the current singleton APIInspector.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

APIInspector

GetAction(eventId)

Retrieve the information about an action at a given eventId.

Parameters:

eventId# (int) – The eventId to query for.

Returns:

The information about the action, or None if the eventId doesn’t correspond to an action.

Return type:

renderdoc.ActionDescription

GetAnnotationViewer()

Retrieve the current singleton AnnotationViewer.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

AnnotationViewer

GetBlockingController()

Returns a blocking version of renderdoc.ReplayController, which provides the same interface but will block for all calls and run them on the correct replay thread. This is provided only as a convenience to avoid calling Replay() to obtain the ReplayManager and use that to directly invoke asynchronously or synchronously onto the replay thread.

This function will return None if no renderdoc.ReplayController is available, for example if there is no capture loaded.

The returned object must not be used if the capture is closed for any reason. It is strongly recommended that you do not cache this object and use it only in local areas of code when needed.

Warning

Care should be taken to ensure that this object is not confused with any other controller that is non-blocking.

Returns:

A blocking version of the renderdoc.ReplayController.

Return type:

renderdoc.ReplayController

GetBookmarks()

Get the current list of bookmarks in the capture. Each bookmark is associated with an eventId and has some text attached. There will only be at most one bookmark for any given eventId.

The list of bookmarks is not necessarily sorted by eventId. Thus, bookmark 1 is always bookmark 1 until it is removed, the indices do not shift as new bookmarks are added or removed.

Returns:

The currently set bookmarks.

Return type:

List[EventBookmark]

GetBuffer(id)

Retrieve the information about a particular buffer.

Parameters:

id# (renderdoc.ResourceId) – The ID of the buffer to query about.

Returns:

The information about a buffer, or None if the ID does not correspond to a buffer.

Return type:

renderdoc.BufferDescription

GetBuffers()

Retrieve the list of buffers in the current capture.

Returns:

The list of buffers.

Return type:

List[renderdoc.BufferDescription]

GetCaptureDialog()

Retrieve the current singleton CaptureDialog.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

CaptureDialog

GetCaptureFilename()

Retrieve the filename for the currently loaded capture.

Returns:

The filename of the current capture.

Return type:

str

GetCaptureModifications()

Get a bitmask indicating which modifications (if any) have been made to the capture in the UI which aren’t reflected in the capture file on disk.

Returns:

The modifications (if any) that have been made to the capture.

Return type:

CaptureModifications

GetCommentView()

Retrieve the current singleton CommentView.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

CommentView

GetDebugMessageView()

Retrieve the current singleton DebugMessageView.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

DebugMessageView

GetDescriptorStore(id)

Retrieve the information about a particular descriptor store.

Parameters:

id# (renderdoc.ResourceId) – The ID of the buffer to query about.

Returns:

The information about a descriptor store, or None if the ID does not correspond to a descriptor store.

Return type:

renderdoc.DescriptorStoreDescription

GetDiagnosticLogView()

Retrieve the current singleton DiagnosticLogView.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

DiagnosticLogView

GetEventBrowser()

Retrieve the current singleton EventBrowser.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

EventBrowser

GetFatalError()

If a capture is loaded, return the current fatal error status.

Returns:

If a capture is currently loaded, return the fatal error status.

Return type:

renderdoc.ResultDetails

GetFirstAction()

Retrieve the first action in the capture.

Returns:

The first action.

Return type:

renderdoc.ActionDescription

GetLastAction()

Retrieve the last action in the capture.

Returns:

The last action.

Return type:

renderdoc.ActionDescription

GetMainWindow()

Retrieve the current singleton MainWindow.

Returns:

The current window.

Return type:

MainWindow

GetMeshPreview()

Retrieve the current singleton BufferViewer configured for mesh viewing.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

BufferViewer

GetNotes(key)

Retrieve the contents for a given notes field.

Examples of fields are:

  • comments for generic comments to be displayed in a text field

  • hwinfo for a plaintext summary of the hardware and driver configuration of the system.

Parameters:

key# (str) – The name of the notes field to retrieve.

Returns:

The contents, or an empty string if the field doesn’t exist.

Return type:

str

GetPerformanceCounterViewer()

Retrieve the current singleton PerformanceCounterViewer.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

PerformanceCounterViewer

GetPipelineViewer()

Retrieve the current singleton PipelineStateViewer.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

PipelineStateViewer

GetPythonShell()

Retrieve the current singleton PythonShell.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

PythonShell

GetRGPInterop()

Returns the current interop handle for RGP.

This may return None in several cases:

  • if there is no capture loaded

  • if no RGP profile has been associated with the current capture yet (See OpenRGPProfile())

  • if RGP failed to launch or connect.

The handle returned is invalidated when the capture is closed, or if OpenRGPProfile() is called.

Returns:

The RGP interop connection handle.

Return type:

RGPInterop

GetResource(id)

Retrieve the information about a particular resource.

Parameters:

id# (renderdoc.ResourceId) – The ID of the resource to query about.

Returns:

The information about a resource, or None if the ID does not correspond to a resource.

Return type:

renderdoc.ResourceDescription

GetResourceInspector()

Retrieve the current singleton ResourceInspector.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

ResourceInspector

GetResourceName(id)

Retrieve the human-readable name for the resource to display.

This will first check to see if a custom name has been set for the resource, and if so use that. See SetResourceCustomName(). If no custom name has been set, it will use the resource name found in the capture, either a name set via API-specific debug methods, or an auto-generated name based on the resource type.

Parameters:

id# (renderdoc.ResourceId) – The ID of the resource to query.

Returns:

The current name of the resource.

Return type:

str

GetResourceNameUnsuffixed(id)

Returns the same name as GetResourceName() but without any added suffix, e.g. to indicate the resource’s status such as (Edited).

Parameters:

id# (renderdoc.ResourceId) – The ID of the resource to query.

Returns:

The unsuffixed resource name.

Return type:

str

GetResourceReplacement(id)

Return the id of a replacement for the given resource. See RegisterReplacement() and IsResourceReplaced().

Parameters:

id# (renderdoc.ResourceId) – The id of the resource to check.

Returns:

The replacement id, or a null id if the resource hasn’t been replaced

Return type:

renderdoc.ResourceId

GetResources()

Retrieve the list of resources in the current capture.

Returns:

The list of resources.

Return type:

List[renderdoc.ResourceDescription]

GetStatisticsViewer()

Retrieve the current singleton StatisticsViewer.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

StatisticsViewer

GetStructuredFile()

Retrieve the SDFile for the currently open capture.

Returns:

The structured file.

Return type:

renderdoc.SDFile

GetTexture(id)

Retrieve the information about a particular texture.

Parameters:

id# (renderdoc.ResourceId) – The ID of the texture to query about.

Returns:

The information about a texture, or None if the ID does not correspond to a texture.

Return type:

renderdoc.TextureDescription

GetTextureViewer()

Retrieve the current singleton TextureViewer.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

TextureViewer

GetTextures()

Retrieve the list of textures in the current capture.

Returns:

The list of textures.

Return type:

List[renderdoc.TextureDescription]

GetTimelineBar()

Retrieve the current singleton TimelineBar.

Returns:

The current window, which is created (but not shown) it there wasn’t one open.

Return type:

TimelineBar

HasAPIInspector()

Check if there is a current APIInspector open.

Returns:

True if there is a window open.

Return type:

bool

HasAnnotationViewer()

Check if there is a current AnnotationViewer open.

Returns:

True if there is a window open.

Return type:

bool

HasCaptureDialog()

Check if there is a current CaptureDialog open.

Returns:

True if there is a window open.

Return type:

bool

HasCommentView()

Check if there is a current CommentView open.

Returns:

True if there is a window open.

Return type:

bool

HasDebugMessageView()

Check if there is a current DebugMessageView open.

Returns:

True if there is a window open.

Return type:

bool

HasDiagnosticLogView()

Check if there is a current DiagnosticLogView open.

Returns:

True if there is a window open.

Return type:

bool

HasEventBrowser()

Check if there is a current EventBrowser open.

Returns:

True if there is a window open.

Return type:

bool

HasMeshPreview()

Check if there is a current mesh previewing BufferViewer open.

Returns:

True if there is a window open.

Return type:

bool

HasPerformanceCounterViewer()

Check if there is a current PerformanceCounterViewer open.

Returns:

True if there is a window open.

Return type:

bool

HasPipelineViewer()

Check if there is a current PipelineStateViewer open.

Returns:

True if there is a window open.

Return type:

bool

HasPythonShell()

Check if there is a current PythonShell open.

Returns:

True if there is a window open.

Return type:

bool

HasResourceCustomName(id)

Checks whether a runtime custom name has been set with SetResourceCustomName().

In general, IsAutogeneratedName() should be preferred to check if the resource name is default generated just from the ID, or if it has been set to some human readable name. This function will only check if a name has been set in the UI itself, a resource could still have a custom name that was set programmatically during capture time.

Parameters:

id# (renderdoc.ResourceId) – The ID of the resource to query.

Returns:

Whether the name for the resource has been customised with SetResourceCustomName().

Return type:

bool

HasResourceInspector()

Check if there is a current ResourceInspector open.

Returns:

True if there is a window open.

Return type:

bool

HasStatisticsViewer()

Check if there is a current StatisticsViewer open.

Returns:

True if there is a window open.

Return type:

bool

HasTextureViewer()

Check if there is a current TextureViewer open.

Returns:

True if there is a window open.

Return type:

bool

HasTimelineBar()

Check if there is a current TimelineBar open.

Returns:

True if there is a window open.

Return type:

bool

ImportCapture(fmt, importfile, rdcfile)

Imports a capture file from a non-native format, via conversion to temporary rdc.

This converts the file to a specified temporary .rdc and loads it, closing any existing capture.

The capture must be available locally, if it’s not this function will fail.

Parameters:

  • fmt# (renderdoc.CaptureFileFormat) – The capture file format to import from.

  • importfile# (str) – The path to import from.

  • rdcfile# (str) – The temporary path to save the rdc file to.

Returns:

True if the import operation was successful and the capture was loaded.

Return type:

bool

InvokeOntoUIThread(callback)

Invoke a callback on the UI thread. All widget accesses must come from the UI thread, so if work has been done on the render thread then this function can be used to asynchronously and safely go back to the UI thread.

This function is safe to call on the UI thread, but it will synchronously call the callback immediately before returning.

Note

No parameters are provided to the callback, it is assumed that the callback will maintain its own context as needed.

Parameters:

callback (Callable[[], None]) – The callback to invoke on the UI thread.

IsAutogeneratedName(id)

Determines whether the name for the given resource has been customised at all, either during capture time or with SetResourceCustomName().

If not, the name is just auto-generated based on the ID and resource type, so depending on circumstance it may be preferable to omit the name.

Parameters:

id# (renderdoc.ResourceId) – The ID of the resource to query.

Returns:

Whether the name for the resource has just been auto-generated.

Return type:

bool

IsCaptureLoaded()

Check whether or not a capture is currently loaded.

Returns:

True if a capture is loaded.

Return type:

bool

IsCaptureLoading()

Check whether or not a capture is currently loading in-progress.

Returns:

True if a capture is currently loading.

Return type:

bool

IsCaptureLocal()

Check whether or not the current capture is stored locally, or on a remote host.

Returns:

True if a capture is local.

Return type:

bool

IsCaptureTemporary()

Check whether or not the current capture is considered temporary. Captures that were made by an application and then have not been explicitly saved anywhere are temporary and will be cleaned up on close (with a final prompt to save). Once they are save to disk, they are no longer temporary and treated like any other capture.

Returns:

True if a capture is temporary.

Return type:

bool

IsResourceReplaced(id)

Determine if a resource has been replaced. See RegisterReplacement().

Parameters:

id# (renderdoc.ResourceId) – The id of the resource to check.

Returns:

True if the resource has been replaced.

Return type:

bool

LoadCapture(captureFile, opts, origFilename, temporary, local)

Open a capture file for replay.

Parameters:

  • captureFile# (str) – The actual path to the capture file.

  • opts# (renderdoc.ReplayOptions) – The options controlling how the capture should be replayed.

  • origFilename# (str) – The original filename, if the capture was copied remotely for replay.

  • temporary# (bool) – True if this is a temporary capture which should prompt the user for either save or delete on close.

  • local# (bool) – True if captureFile refers to a file on the local machine.

MarkMessagesRead()

Mark all messages as read, resets UnreadMessageCount() to 0.

OpenRGPProfile(filename)

Sets the path to the RGP profile to use with GetRGPInterop(), launches RGP and opens an interop connection. This function will block (with a progress dialog) until either an error is encountered or else the connection is successfully established.

This could be newly created, or extracted from an embedded section in the RDC.

The connection is automatically closed when the capture is closed. If OpenRGPProfile is called again, any previous connection will be closed.

Parameters:

filename# (str) – The filename of the extracted temporary RGP capture on disk.

Returns:

Whether RGP launched successfully.

Return type:

bool

RaiseDockWindow(dockWindow)

Raises a window within its docking manager so it becomes the focus of wherever it is currently docked.

Parameters:

dockWindow# (QWidget) – The window to raise.

RecompressCapture()

Recompress the current capture as much as possible.

RefreshStatus()

Replay the capture to the current event again, to pick up any changes that might have been made.

RegisterReplacement(arg2, to)

Register that a resource has replaced, so that the UI can be updated to reflect the change.

This should be called at the same time as ReplaceResource().

Parameters:
RemoveBookmark(eventId)

Remove a bookmark at a given eventId.

If no bookmark exists, this function will do nothing.

Parameters:

eventId# (int) – The eventId of the bookmark to remove.

RemoveCaptureViewer(viewer)

Unregister an instance of CaptureViewer from receiving notifications.

Parameters:

viewer# (CaptureViewer) – The viewer to unregister.

RemoveDependentFiles()

Removes the dependent files storage from the capture i.e. shader debug files.

The files will be still be considered to be referenced by the capture and could be re-embedded by calling EmbedDependentFiles().

Warning

Will directly modify the capture file on disk.

Note

For remote replay the modifications are performed on the remote machine and copied back to the local host.

Replay()

Retrieve the replay manager for access to the internal RenderDoc replay controller.

Returns:

The current replay manager.

Return type:

ReplayManager

ResourceNameCacheID()

Returns an index that can be used to cache the results of resource naming.

In some cases (e.g. formatting in widgets) there might be high frequency fetches to names without an easy way to force a refresh on a rename. Instead, the index here can be cached and compared each time to see if any names have changed.

The index starts at 1, so initialising an internal cache to 0 will cause the first check to be considered out of date

Returns:

An incrementing index that can be used as a quick check if any names have changed.

Return type:

int

SaveCaptureTo(captureFile)

Saves the current capture file to a given path.

If the capture was temporary, this save action means it is no longer temporary and will be treated like any other capture.

Any modifications to the capture (see GetCaptureModifications()) will be applied at the same time.

Parameters:

captureFile# (str) – The path to save the capture file to.

Returns:

True if the save operation was successful.

Return type:

bool

SetBookmark(mark)

Set or update a bookmark.

A bookmark will be added at the specified eventId, or if one already exists then the attached text will be replaced.

Parameters:

mark# (EventBookmark) – The bookmark to add.

SetEventID(exclude, selectedEventId, eventId, force=False)

Move the current replay to a new event in the capture.

Parameters:
SetNotes(key, contents)

Set the contents for a given notes field.

See GetNotes() for a list of possible common field keys.

Parameters:

  • key# (str) – The name of the notes field to set.

  • contents# (str) – The new contents to assign to that field.

SetResourceCustomName(id, name)

Set a custom name for a resource.

This allows an override to the name returned by GetResourceName(), most useful when there are no pre-existing debug names specified in the capture.

To remove a custom name that has been set previously, specify the empty string as the name. Then the custom name will be removed, and instead GetResourceName() will fall back to returning any name fetched from the capture.

Parameters:

  • id# (renderdoc.ResourceId) – The ID of the resource to name.

  • name# (str) – The name to provide, or an empty string to remove any previous custom name.

ShowAPIInspector()

Raise the current APIInspector, showing it in the default place if needed.

ShowAnnotationViewer()

Raise the current AnnotationViewer, showing it in the default place if needed.

ShowCaptureDialog()

Raise the current CaptureDialog, showing it in the default place if needed.

ShowCommentView()

Raise the current CommentView, showing it in the default place if needed.

ShowDebugMessageView()

Raise the current DebugMessageView, showing it in the default place if needed.

ShowDiagnosticLogView()

Raise the current DiagnosticLogView, showing it in the default place if needed.

ShowEventBrowser()

Raise the current EventBrowser, showing it in the default place if needed.

ShowMeshPreview()

Raise the current mesh previewing BufferViewer, showing it in the default place if needed.

ShowPerformanceCounterViewer()

Raise the current PerformanceCounterViewer, showing it in the default place if needed.

ShowPipelineViewer()

Raise the current PipelineStateViewer, showing it in the default place if needed.

ShowPythonShell()

Raise the current PythonShell, showing it in the default place if needed.

ShowResourceInspector()

Raise the current ResourceInspector, showing it in the default place if needed.

ShowStatisticsViewer()

Raise the current StatisticsViewer, showing it in the default place if needed.

ShowTextureViewer()

Raise the current TextureViewer, showing it in the default place if needed.

ShowTimelineBar()

Raise the current TimelineBar, showing it in the default place if needed.

TargetShaderEncodings()

Retrieve the list of ShaderEncoding that are available for building target shaders for the currently loaded capture. See BuildTargetShader().

Returns:

The available encodings.

Return type:

List[renderdoc.ShaderEncoding]

TempCaptureFilename(appname)

Retrieve the absolute path where a given temporary capture should be stored. data.

Parameters:

appname# (str) – The name of the application to use as part of the template.

Returns:

The absolute path.

Return type:

str

UnreadMessageCount()

Retrieve how many messages in DebugMessages() are currently unread.

Returns:

The number of unread messages.

Return type:

int

UnregisterReplacement(id)

Register that a replacement has been removed, so that the UI can be updated to reflect the change.

This should be called at the same time as RemoveReplacement().

See RegisterReplacement().

Parameters:

id# (renderdoc.ResourceId) – The id of the original resource that was previously replaced.

ViewBuffer(byteOffset, byteSize, id, format)

Show a new BufferViewer window, showing a read-only view of buffer data.

Parameters:

  • byteOffset# (int) – The offset in bytes to the start of the buffer data to show.

  • byteSize# (int) – The number of bytes in the buffer to show.

  • id# (renderdoc.ResourceId) – The ID of the buffer to fetch data from.

  • format=""# (str) – Optional parameter. A HLSL/GLSL style formatting string.

Returns:

The new BufferViewer window opened, but not shown.

Return type:

BufferViewer

ViewConstantBuffer(stage, slot, idx)

Show a new BufferViewer window, showing a read-only view of a the variables in a constant buffer with their values.

Parameters:

  • stage# (renderdoc.ShaderStage) – The stage that the constant buffer is bound to.

  • slot# (int) – The index in the shader’s constant buffer list to look up.

  • idx# (int) – For APIs that support arrayed resource binds, the index in the constant buffer array.

Returns:

The new BufferViewer window opened, but not shown.

Return type:

BufferViewer

ViewDescriptorStore(id)

Show a new DescriptorViewer window, showing the full raw contents of a descriptor store.

Parameters:

id# (renderdoc.ResourceId) – The ID of the descriptor store to fetch data from.

Returns:

The new DescriptorViewer window opened, but not shown.

Return type:

DescriptorViewer

ViewDescriptors(descriptors, samplerDescriptors)

Show a new DescriptorViewer window, showing contents of an arbitrary list of descriptors.

The descriptor lists should be in parallel, with identical sizes. If a non-sampler descriptor is to be displayed, the corresponding sampler descriptor should be uninitialised and vice-versa. If the lists are not the same length, only indices up to the minimum of the two lengths will be used.

This function should not be used to view the entirety of a descriptor store - in that case the ViewDescriptorStore() function will be more efficient.

Parameters:
Returns:

The new DescriptorViewer window opened, but not shown.

Return type:

DescriptorViewer

ViewPixelHistory(id, x, y, view, display)

Show a new PixelHistoryView window, showing the results from a pixel history operation.

Parameters:

  • id# (renderdoc.ResourceId) – The ID of the texture to show the history of.

  • x# (int) – The x co-ordinate of the pixel to search for.

  • y# (int) – The y co-ordinate of the pixel to search for.

  • view# (int) – The layered or multiview rendering view index of the pixel to search for.

  • display# (renderdoc.TextureDisplay) – The texture display configuration to use when looking up the history.

Returns:

The new PixelHistoryView window opened, but not shown.

Return type:

PixelHistoryView

ViewShader(shader, pipeline)

Show a new ShaderViewer window, showing a read-only view of a given shader.

Parameters:
Returns:

The new ShaderViewer window opened, but not shown.

Return type:

ShaderViewer

ViewShaderMessages(stages)

Show a new ShaderMessageViewer window, showing the current event’s messages.

Parameters:

stages# (renderdoc.ShaderStageMask) – The initial stages being viewed.

Returns:

The new ShaderMessageViewer window opened, but not shown.

Return type:

ShaderMessageViewer

ViewTextureAsBuffer(id, sub, format)

Show a new BufferViewer window, showing a read-only view of a texture’s raw bytes.

Parameters:
Returns:

The new BufferViewer window opened, but not shown.

Return type:

BufferViewer

Replay Manager

class qrenderdoc.ReplayManager

A manager for accessing the underlying replay information that isn’t already abstracted in UI side structures. This manager controls and serialises access to the underlying ReplayController, as well as handling remote server connections.

This manager is retrieved by calling CaptureContext.Replay().

ReplayInvokeCallback(controller)

Not a member function - the signature for any ReplayInvokeCallback callbacks.

Parameters:

controller (renderdoc.ReplayController) – The controller to access. Must not be cached or used after the callback returns.

DirectoryBrowseCallback(path, entries)

Not a member function - the signature for any DirectoryBrowseCallback callbacks.

Parameters:

  • path (str) – The path that was queried for.

  • entries (List[renderdoc.PathEntry]) – The entries underneath the path, as relevant.

AsyncInvoke(method, tag)

Make a non-blocking invoke call onto the replay thread.

The callback can optionally have a tag provided.

Tags are for cases when we might send a request - e.g. to pick a vertex or pixel - and want to preempt it with a new request before the first has returned. Either because some other work is taking a while or because we’re sending requests faster than they can be processed.

If a tag is present the manager processes only the request on the top of the queue, so when a new tagged invoke comes in, we remove any other requests in the queue before it that have the same tag.

If no tag is present, the callback will be processed as normal.

Parameters:
BlockInvoke(m)

Make a blocking invoke call onto the replay thread.

Parameters:

method (Callable[[renderdoc.ReplayController], None]) – The function to callback on the replay thread. Callback function signature must match ReplayInvokeCallback().

CancelReplayLoop()

Cancels the active replay loop. See ReplayLoop().

ConnectToRemoteServer(host)

Connect to a remote server.

Parameters:

host# (RemoteHost) – The host to connect to.

Returns:

Whether or not the connection was successful.

Return type:

renderdoc.ResultDetails

CopyCaptureFromRemote(remotepath, localpath, window)

Copy a capture from the remote host to the local machine.

Parameters:

  • remotepath# (str) – The path on the remote server to copy from.

  • localpath# (str) – The path on the local machine to copy to.

  • window# (QWidget) – A handle to the window to use when showing a progress bar.

CopyCaptureToRemote(localpath, window)

Copy a capture from the local machine to the remote host.

Parameters:

  • localpath# (str) – The path on the local machine to copy from.

  • window# (QWidget) – A handle to the window to use when showing a progress bar.

Returns:

The path on the local machine where the file was saved, or empty if something went wrong.

Return type:

str

CurrentRemote()

Retrieves the host that the manager is currently connected to.

Returns:

The host connected to, or an invalid RemoteHost if no connection is active.

Return type:

RemoteHost

DeleteCapture(capturefile, local)

Delete a capture file, whether local or remote.

Parameters:

  • capturefile# (str) – The path to the file.

  • local# (bool) – True if the file is on the local machine.

DisconnectFromRemoteServer()

Disconnect from the server the manager is currently connected to.

ExecuteAndInject(exe, workingDir, cmdLine, env, capturefile, opts)

Launch an application and inject into it to allow capturing.

This happens either locally, or on the remote server, depending on whether a connection is active.

Parameters:

  • exe# (str) – The path to the executable to run.

  • workingDir# (str) – The working directory to use when running the application. If blank, the directory containing the executable is used.

  • cmdLine# (str) – The command line to use when running the executable, it will be processed in a platform specific way to generate arguments.

  • env# (List[renderdoc.EnvironmentModification]) – Any environment changes that should be made when running the program.

  • capturefile# (str) – The location to save any captures, if running locally.

  • opts# (renderdoc.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:

renderdoc.ExecuteResult

GetCaptureAccess()

Retrieves the capture access handle for the currently open file.

Returns:

The file handle active, or None if no capture is open.

Return type:

renderdoc.CaptureAccess

GetCaptureFile()

Retrieves the capture file handle for the currently open file, if it is available.

If the capture is not open locally this will not be available, and only GetCaptureAccess() will be usable.

Returns:

The file handle active, or None if no capture is open or the capture is only available remotely.

Return type:

renderdoc.CaptureFile

GetCurrentProcessingTime()

Return the amount of time that the currently active command on the replay thread has been executing for.

This can be used to identify if a command is long-running to display a progress bar or notification.

Returns:

The time in seconds that the current command has been executing for, or 0.0 if no command is executing.

Return type:

float

GetHomeFolder(synchronous, callback)

Query the remote host for its home directory.

If a capture is open, the callback will happen on the replay thread, otherwise it will happen in a blocking fashion on the current thread.

Parameters:
GetRemoteSupport()

Retrieve a list of drivers that the current remote server supports.

Returns:

The list of supported replay drivers.

Return type:

List[str]

ListFolder(path, synchronous, callback)

Query the remote host for the contents of a path.

If a capture is open, the callback will happen on the replay thread, otherwise it will happen in a blocking fashion on the current thread.

Parameters:

  • path# (str) – The path to query the contents of.

  • synchronous# (bool) – If a capture is open, then True will use BlockInvoke() to call the callback. Otherwise if False then AsyncInvoke() will be used.

  • callback (Callable[[str, List[renderdoc.PathEntry]], None]) – The function to callback on the replay thread. Callback function signature must match DirectoryBrowseCallback().

PingRemote()

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

ShutdownServer()

Shutdown the server the manager is currently connected to.

RGP Interop Control

class qrenderdoc.RGPInterop

Controlling interface for interop with RGP tool.

HasRGPEvent(eventId)

Return true if the given eventId has and equivalent in RGP.

Parameters:

eventId# (int) – The eventId to query for.

Returns:

True if there is an equivalent. This only confirms the equivalent exists, not that it will be selectable in all cases.

Return type:

bool

SelectRGPEvent(eventId)

Select the given eventId equivalent in RGP.

Parameters:

eventId# (int) – The eventId to query for.

Returns:

True if the selection request succeeded. This only confirms the request was sent, not that the event was selected in RGP.

Return type:

bool

CaptureViewer Interface

class qrenderdoc.CaptureViewer

An interface implemented by any object wanting to be notified of capture events.

OnCaptureClosed()

Called whenever a capture is closed.

OnCaptureLoaded()

Called whenever a capture is opened.

OnEventChanged(eventId)

Called whenever the effective current event changes.

Parameters:

eventId# (int) – The new eventId.

OnSelectedEventChanged(eventId)

Called whenever the current selected event changes. This is distinct from the actual effective current event, since for example selecting a marker region will change the current event to be the last event inside that region, to be consistent with selecting an item reflecting the current state after that item.

The selected event shows the eventId that was actually selected, which will usually but not always be the same as the current effective eventId.

The distinction for this callback is not normally desired, instead use OnEventChanged() to be notified whenever the current event changes. The API inspector uses this to display API events up to a marker region.

Parameters:

eventId# (int) – The new eventId.

Helpers

class qrenderdoc.BufferInterpreter
class qrenderdoc.BufferInterpreter(other: BufferInterpreter)

A helper class with static methods to assist with interpreting buffer data according to a given format or parsing format strings into format structures.

static EstimatePackingRules(baseType, shader)

Estimate the packing rules that apply to a given structure type.

This is not exact, as less strict packing rules will apply equally to structures that use more strict packing rules. This function returns only the most-strict set of rules that would be valid.

Parameters:

  • baseType# (renderdoc.ShaderConstantType) – The structure type to analyse.

  • shader=ResourceId#() (renderdoc.ResourceId) – Optional parameter. The shader this struct came from, used for determining the types of any pointer variables. Can be omitted if the struct type did not come from a shader.

Returns:

The most conservative packing rules that satisfy the given type

Return type:

PackingRules

static GetPointerType(pointerTypeId, shader)

Return the type description of a pointer ID. If this is from shader reflection the ID is an index into pointerTypes. If the pointer type was generated by parsing a buffer string it will be an arbitrary index.

Returns an empty type if the type ID is invalid or if a shader is not provided for a shader-based type ID.

Parameters:

  • pointerTypeId# (int) – The ID of the pointer type.

  • shader=ResourceId#() (renderdoc.ResourceId) – Optional parameter. The shader this struct came from, used for determining the types of any pointer variables. Can be omitted if the struct type did not come from a shader.

Returns:

The type description.

Return type:

renderdoc.ShaderConstantType

static GetPointerValType(val)

Return the type description of a given pointer.

Returns an empty type if the value is invalid.

Parameters:

val# (renderdoc.PointerVal) – The pointer value to inspect.

Returns:

The type description.

Return type:

renderdoc.ShaderConstantType

static GetShaderVariables(var, data, maxVariables=-1)

Return a list of shader variables by interpreting a bytes with a given type description.

The number of variables can be limited for example to 1 if needed without needing to calculate how to truncate the byte data.

This will always return a whole number of variables even if the byte data is insufficient, with standard out-of-bound reads returning 0 data.

Parameters:

  • var# (renderdoc.ShaderConstant) – The description of the variable to interpret

  • data# (bytes) – The byte data to read the variable from.

  • maxVariables=-1# (int) – Optional parameter. The maximum number of variables to read, or -1 to read as many as can fit in the given byte data.

Return type:

List[renderdoc.ShaderVariable]

static GetVariableAdvance(pack, var)

Return the number of bytes between the start and end of a variable type.

Note

Depending on the packing rules specified, this may not include the necessary padding or alignment needed for the given type and may calculate only the offset to the end of the variable. If you are calculating the offsets of elements of an array you should use arrayByteStride.

Parameters:
Return type:

int

static LookupPointer(pointerAddress, minSize=0)

Look up a pointer address and return the ResourceId and offset of the containing buffer.

Due to buffer aliasing, it is possible a different overlapping buffer will be returned since there is no way to differentiate based on purely an address. The LookupPointer.minSize parameter can be used to ensure that a range sits in the same buffer.

If no matching buffer is found then the result is default initialised.

This looks through the buffers available in GetBuffers() and compares against gpuAddress and length.

Parameters:

  • pointerAddress# (int) – The address of the pointer to look up.

  • minSize=0# (int) – Optional parameter. The minimum number of bytes that must be available after the address in the same buffer.

Returns:

The buffer ID and offset within that buffer.

Return type:

Tuple[renderdoc.ResourceId,int]

static Parse(format)

Parse a buffer format string and return the format in a structure that can be inspected or used to interpret data.

For more information see How do I specify a buffer format?.

Warning

For format strings that specify pointers, care should be taken that pointerTypeID is an opaque identifier as there is no shader reflection to look up. You should use GetPointerType() to obtain the type description of pointer types.

Parameters:

format# (str) – The format string to interpret

Returns:

The result of parsing the format string.

Return type:

ParsedBufferFormat

static Unparse(structType, pack, shader)

Generate a buffer format string from a known structure type.

This may not generate exactly, depending on the exact structure type. It may also not roundtrip exactly when used with Parse().

Parameters:

  • structType# (renderdoc.ShaderConstantType) – The structure type to unparse.

  • pack# (PackingRules) – The packing rules to use when generating the string.

  • shader=ResourceId#() (renderdoc.ResourceId) – Optional parameter. The shader this struct came from, used for determining the types of any pointer variables. Can be omitted if the struct type did not come from a shader.

Returns:

The generated format string, or an empty string if an error happened.

Return type:

str

class qrenderdoc.PackingRules
class qrenderdoc.PackingRules(other: PackingRules)

A description of individual rules for how data is packed in GPU-side structures and buffers.

Each individual member rule is such that False is more restrictive on packing, and True is less restrictive.

Several helpers are available for the common formats, see PackingRules.STD140(), PackingRules.STD430(), PackingRules.D3DCB(), PackingRules.C() which provide a quick way to fetch a known set of packing rules.

static C()

Note

This is the standard C ABI with no special packing directives such as #pragma pack().

Returns:

The standard C packing rules.

Return type:

PackingRules

static D3DCB()
Returns:

The D3D11 and D3D12 Constant Buffer rules.

Return type:

PackingRules

static D3DUAV()
Returns:

The D3D Structured UAV buffer rules. This is considered to be the same as standard C packing rules.

Return type:

PackingRules

static STD140()
Returns:

The GLSL std140 rules, used on OpenGL and Vulkan.

Return type:

PackingRules

static STD430()
Returns:

The GLSL std430 rules, used on OpenGL and Vulkan.

Return type:

PackingRules

static Scalar()
Returns:

Vulkan scalar block layout rules, which are almost the same as C but in some cases allow more tight packing than C by default.

Return type:

PackingRules

tightArrays

Flag indicating if arrays are tightly packed with the stride being their natural alignment.

If True this means each array element is at a suitably aligned offset after the previous.

If False, each array element is at a 16-byte aligned offset after the previous regardless of the element size and alignment.

Type:

bool

tightBitfieldPacking

Flag indicating if bitfields allow bit-packed regions to straddle the base type.

If True this means bit regions are tightly packed even if one region would cross two base elements. E.g. if the base type is uint then three 20-bit regions would only consume two uints as that is 60 bits total.

If False this means each bit region ensures it only exists in one base element with padding/unused bits in elements as necessary. E.g. if the base type is uint then three 20-bit regions would consume three uints as each region would be padded into its own element.

Note

Bitfield packing is compiler defined on CPU but this mostly matches what happens with #pragma pack(1).

Type:

bool

trailingOverlap

Flag indicating if the trailing alignment padding space after a struct member can be used by the next member.

If True then a struct that contains e.g. 2 bytes of padding at its end to align it to a 4-byte alignment can be followed by a 2-byte member which can have an offset inside that padding region.

If False then a struct consumes its padding space and the next member starts after the struct even if it would otherwise fit and be aligned.

Warning

This is not supported by standard C layouts, but is supported by some GPU layouts.

Type:

bool

vectorAlignComponent

Flag indicating if a vector’s alignment is only equal to its component alignment.

If True this means vectors have no special alignment, and a 3-component float vector is aligned to 4-byte the same as a scalar float.

If False, 2-wide vectors are aligned to their size, and 3-wide and 4-wide vectors are aligned to a 4-wide vector’s size. E.g. float2 has 8 byte alignment, float3 and float4 have 16-byte alignment.

Type:

bool

vectorStraddle16b

Flag indicating if vectors can straddle a 16-byte boundary with their components.

If True this means vectors have no special restrictions and can be at any aligned byte offset.

If False, vectors must be at an offset such that the whole vector sits within the same 16-byte aligned region.

Type:

bool

class qrenderdoc.ParsedBufferFormat
class qrenderdoc.ParsedBufferFormat(other: ParsedBufferFormat)

The result of parsing a buffer format string.

errors

The list of errors encountered while processing the format string.

Type:

List[ParseError]

fixedHeader

The fixed SoA variables before any repeating structure, if present.

On some APIs it is possible to declare a fixed size amount of SoA data before then an unbounded/runtime array of AoS data. If the format string is interpreted this way then the initial fixed data structure will be returned in this member

Type:

renderdoc.ShaderConstant

packing

The packing rules specified in the buffer format string. If not explicitly stated then the estimated rules will be given here, as the most conservative packing that would work for the current API.

Type:

PackingRules

structure

The main structure of data described by the input buffer string.

Type:

renderdoc.ShaderConstant

class qrenderdoc.ParseError
class qrenderdoc.ParseError(other: ParseError)

An error that occurred while parsing a buffer format string.

error

The text of the format parsing error.

Type:

str

line

The 0-based line number in the input string where the error occurred.

Type:

int

Utilities

class qrenderdoc.DockReference(value)

Specifies the relationship between the existing dock window and the new one when adding a new dock window or moving an existing dock window.

LastUsedArea

The existing dock window is not used, the new dock window is placed wherever the last dock window was placed.

NewFloatingArea

The existing dock window is not used, the new dock window is placed in a new floating area.

EmptySpace

The existing dock window is not used, the new dock window is placed in empty area in the dockarea.

NoArea

The existing dock window is not used, the new window is hidden.

AddTo

The new dock window is placed in a tab set with the existing dock window.

LeftOf

The new dock window is placed to the left of the existing dock window, at a specified proportion.

RightOf

The new dock window is placed to the right of the existing dock window, at a specified proportion.

TopOf

The new dock window is placed above the existing dock window, at a specified proportion.

BottomOf

The new dock window is placed below the existing dock window, at a specified proportion.

LeftWindowSide

The new dock window is placed left of all docks in the window, at a specified proportion.

RightWindowSide

The new dock window is placed right of all docks in the window, at a specified proportion.

TopWindowSide

The new dock window is placed above all docks in the window, at a specified proportion.

BottomWindowSide

The new dock window is placed below all docks in the window, at a specified proportion.

MainToolArea

The new dock window is placed in the ‘main’ tool area as defined by finding an existing known window and using that as the main area. In the default layout this is where most windows are placed.

LeftToolArea

The new dock window is placed in the ‘left’ tool area as defined by finding an existing known window and using that as the main area, then adding to the left of that. In the default layout this is where the event browser is placed.

TransientPopupArea

The new dock window is docked with other similar transient views like constant buffer or pixel history windows, if they exist, or else docked to the right of the main window.

class qrenderdoc.CaptureModifications(value)

Details any changes that have been made to a capture in the UI which can be saved to disk but currently aren’t. Note that detection is conservative - e.g. if a change is made, then cancelled out by reversing the change, this will still count as ‘modified’ even if the end result is the same data. In that sense it’s analogous to adding and then deleting some characters in a text editor, since there is no actual undo system.

This is a bitmask, so several values can be present at once.

NoModifications

Fixed value of 0 indicating no modifications have been made.

Renames

One or more resources have been given a custom name which hasn’t been saved.

Bookmarks

Event bookmarks have been added or removed.

Notes

The general notes field has been changed.

EditedShaders

There are shader editing changes (new edits or reverts).

All

Fixed value with all bits set, indication all modifications have been made.

class qrenderdoc.CaptureSettings
class qrenderdoc.CaptureSettings(other: CaptureSettings)

Contains all of the settings that control how to capture an executable.

autoStart

True if this capture settings object should be immediately executed upon load.

Type:

bool

commandLine

The command line to pass when running executable.

Type:

str

environment

The environment changes to apply.

Type:

List[renderdoc.EnvironmentModification]

executable

The path to the executable to run.

Type:

str

inject

True if the described capture is an inject-into-process instead of a launched executable.

Type:

bool

numQueuedFrames

The number of queued frames to capture, or 0 if no frames are queued to be captured.

Type:

int

options

The settings for the capture.

Type:

renderdoc.CaptureOptions

queuedFrameCap

The first queued frame to capture. Ignored if numQueuedFrames is 0.

Type:

int

workingDir

The path to the working directory to run in, or blank for the executable’s directory.

Type:

str

class qrenderdoc.EventBookmark
class qrenderdoc.EventBookmark(other: EventBookmark)
class qrenderdoc.EventBookmark(eventId: int)

A description of a bookmark on an event

eventId

The eventId at which this bookmark is placed.

Type:

int

text

The text associated with this bookmark - could be empty

Type:

str