API Reference: qrenderdoc Windows

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.

Main Window

class qrenderdoc.MainWindow

The main parent window of the application.

This window is retrieved by calling CaptureContext.GetMainWindow().

ShortcutCallback(QWidget focusWidget)

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

Parameters:

focusWidget (QWidget) – The widget with focus at the time this shortcut was detected. May be None.

BringToFront()

Attempts to bring the main window to the front to the user’s focus.

This may not be possible on all OSs, so the function is not guaranteed to succeed.

PromptCloseCapture()

Prompt the user to close the currently open capture file. This will go through the normal workflow and ask the user to save any unsaved capture.

If no capture is open, this function returns True immediately.

Returns:

True if no capture was open, or if it was successfully closed. False if the capture is still open due to user interactions.

Return type:

bool

RegisterShortcut(shortcut, widget, callback)

Register a callback for a particular key shortcut.

This creates a managed shortcut. Qt’s shortcut system doesn’t allow specialisation/duplication, so you can’t use Ctrl+S for a shortcut in a window to update some changes if there’s also a global Ctrl+S shortcut on the window. In the end, neither shortcut will be called.

Instead this function allows the main window to manage shortcuts internally, and it will pick the closest shortcut to a given action. The search goes from the widget with the focus currently up the chain of parents, with the first match being used. If no matches are found, then a ‘global’ default will be invoked, if it exists.

Parameters:

  • shortcut# (str) – The text string representing the shortcut, e.g. Ctrl+S.

  • widget# (QWidget) – A handle to the widget to use as the context for this shortcut, or None for a global shortcut. Note that if an existing global shortcut exists the new one will not be registered.

  • callback (Callable[[QWidget], None]) – The function to callback when the shortcut is hit. Callback function signature must match ShortcutCallback().

UnregisterShortcut(shortcut, widget)

Unregister a callback for a particular key shortcut, made in a previous call to RegisterShortcut().

See the documentation for RegisterShortcut() for what these shortcuts are for.

Parameters:

  • shortcut# (str) – The text string representing the shortcut, e.g. Ctrl+S. To unregister all shortcuts for a particular widget, you can pass an empty string here. In this case, UnregisterShortcut.widget must not be None.

  • widget# (QWidget) – A handle to the widget used as the context for the shortcut, or None if referring to a global shortcut.

Widget()

Retrieves the PySide2 QWidget for this MainWindow if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Event Browser

class qrenderdoc.EventBrowser

The event browser window.

This window is retrieved by calling CaptureContext.GetEventBrowser().

EventFilterCallback(context, filter, params, eventId, chunk, action, name)

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

Called for each event in a capture when performing filtering in the Event Browser. The associated FilterParseCallback() will be called first to parse the parameters, and is available for caching or syntax checking. The same filter name and params string will be passed to this function.

Parameters:

  • context (CaptureContext) – The current capture context.

  • filter (str) – The name of the filter function.

  • params (str) – The parameters to the filter function.

  • eventId (int) – The event’s eventId.

  • chunk (renderdoc.SDChunk) – The structured data chunk for this event.

  • action (renderdoc.ActionDescription) – The action that contains this event. If the event is the action itself then the event ID will be equal.

  • name (str) – The name of the event as shown in the event browser, for string-based filtering.

Returns:

Whether or not this event matches the filter

Return type:

bool

FilterParseCallback(context, filter, params)

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

Called once when the filter changes, to allow parsing any any data caching, as well as reporting of errors in the filter usage.

Parameters:

  • context (CaptureContext) – The current capture context.

  • filter (str) – The name of the filter function.

  • params (str) – The parameters to the filter function.

Returns:

An empty string if the parse succeeded, otherwise any error messages to be displayed to the user, such as syntax or other errors.

Return type:

str

AutoCompleteCallback(context, filter, params)

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

Called when autocompletion is triggered inside a filter. The params passed are any previous text inside the filter’s parameter list up to where the cursor is. The callback should return a list of identifiers used for auto-completion.

The list does not have to be pre-filtered for matches to the AutoCompleteCallback.params, that is provided to allow different autocompletion at different stages (e.g. if there are no parameters, you can autocomplete a property, if a property is already present you can autocomplete valid values for it)

Parameters:

  • context (CaptureContext) – The current capture context.

  • filter (str) – The name of the filter function.

  • params (str) – The previous parameter text to the filter function.

Returns:

A list of strings giving identifiers to autocomplete, or an empty list of there are no such identifiers to prompt.

Return type:

List[str]

GetAPIEventForEID(eventId)

Uses the existing caching in the event browser to return a APIEvent for a specified EID.

If no capture is loaded or the EID doesn’t correspond to a known event, an empty struct will be returned.

Parameters:

eventId# (int) – The EID to look up.

Returns:

The event corresponding to the EID, or an empty struct if no such EID exists.

Return type:

renderdoc.APIEvent

GetActionForEID(eventId)

Uses the existing caching in the event browser to return a ActionDescription for a specified EID. This action may not be the exact EID specified, but it will be the action that the EID is associated with. I.e. if you specify the EID for a state setting event the next action will be returned.

If no capture is loaded or the EID doesn’t correspond to a known event, None will be returned.

Parameters:

eventId# (int) – The EID to look up.

Returns:

The action containing the EID, or None if no such EID exists.

Return type:

renderdoc.ActionDescription

GetCurrentFilterText()

Returns the current filter text, whether temporary or a saved filter.

Returns:

The current filter text.

Return type:

str

GetEventName(eventId)

Returns the formatted name of an event according to the current settings, whether that be a custom name or an auto-generated name with/without parameter names.

If no capture is loaded or the EID doesn’t correspond to a known event, an empty string will be returned.

Parameters:

eventId# (int) – The EID to look up.

Returns:

The formatted name of the specified event, or None if no such EID exists.

Return type:

str

GetHighlightedAnnotation()

Returns the current annotation key path as being highlighted in the annotation column.

Returns:

The current annotation path.

Return type:

str

IsAPIEventVisible(eventId)

Determines if a given EID is visible with the current filters applied to the event browser.

If no capture is loaded or the EID doesn’t correspond to a known event, False will be returned.

Parameters:

eventId# (int) – The EID to look up.

Returns:

Whether or not the event is currently visible (passing the filters).

Return type:

bool

RegisterEventFilterFunction(name, description, filter, parser, completer)

Registers a new event browser filter function.

Filter functions are available as $name() so long as they don’t shadow an existing function. The filter callback will be called for each event to filter.

The parser callback will be called once when a filter is first specified or the parameters change. Note that a filter can be used multiple times in a filter expression! For this reason the parser may be called multiple times and the filter callback takes the parameters string. If any expensive work is done then the parameters can be used as a cache key to cache any data once per filter expression.

Parameters:

  • name# (str) – The name of the filter function.

  • description# (str) – The description of the filter function. This should explain the available parameters (if applicable) and what the filter does. It will be used for documenting to users what each filter means.

  • filter (Callable[[CaptureContext,str,str,int,renderdoc.SDChunk,renderdoc.ActionDescription,str], bool]) – The callback to call for each candidate event to perform filtering. Callback function signature must match EventFilterCallback().

  • parser (Callable[[CaptureContext,str,str], str]) – The callback to call when the parsing the parameters and checking for any errors. This can be None if no pre-parsing is required. Callback function signature must match FilterParseCallback().

  • completer (Callable[[CaptureContext,str,str], List[str]]) – The callback to call when trying to provide autocomplete suggestions. This can be None if no completion is desired/applicable. Callback function signature must match AutoCompleteCallback().

Returns:

Whether or not the registration was successful.

Return type:

bool

SetAnnotationColumnVisible(show)

Sets whether or not the annotation column is visible.

Parameters:

show# (bool) – If the duration column should be shown.

SetCurrentFilterText(text)

Sets the current filter text. This will not modify any saved filter but will modify the scratch filter. The filter is applied immediately.

Parameters:

text# (str) – The filter text.

SetDurationColumnVisible(show)

Sets whether or not the duration column is visible.

Parameters:

show# (bool) – If the duration column should be shown.

SetEmptyRegionsVisible(show)

Sets whether or not marker regions which have no visible actions.

Parameters:

show# (bool) – Whether or not empty regions after filtering will be shown.

SetHighlightedAnnotation(annotationPath)

Sets the current annotation key path. This will not display the annotation column if it is not already visible.

Parameters:

annotationPath# (str) – The new annotation path.

SetShowAllParameters(show)

Sets whether or not all parameters are shown in the events. By default only the most significant parameters are shown.

Note

If custom action names are used this will not have an effect for any such actions. See SetUseCustomActionNames().

Parameters:

show# (bool) – Whether or not parameter names will be shown.

SetShowParameterNames(show)

Sets whether or not parameter names are shown in the events. If disabled, only the value is shown and the parameter is implicit.

Note

If custom action names are used this will not have an effect for any such actions. See SetUseCustomActionNames().

Parameters:

show# (bool) – Whether or not parameter names will be shown.

SetUseCustomActionNames(use)

Sets whether or not custom action names are used. Certain actions such as indirect actions it is useful to show a custom action name which contains the actual indirect parameters instead of the ‘raw’ parameters.

Parameters:

use# (bool) – Whether or not custom action names will be used.

UnregisterEventFilterFunction(name)

Unregisters an event browser filter function that was previously registered.

Parameters:

name# (str) – The name of the filter function.

Returns:

Whether or not the unregistration was successful.

Return type:

bool

UpdateDurationColumn()

Updates the duration column if the selected time unit changes.

Widget()

Retrieves the PySide2 QWidget for this EventBrowser if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

API Inspector

class qrenderdoc.APIInspector

The API inspector window.

This window is retrieved by calling CaptureContext.GetAPIInspector().

Refresh()

Refresh the current API view - useful if callstacks are now available.

RevealParameter(param)

Expand the API view to reveal a given parameter and select it.

Parameters:

param# (renderdoc.SDObject) – The parameter to reveal and select.

Widget()

Retrieves the PySide2 QWidget for this APIInspector if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Pipeline State

class qrenderdoc.PipelineStage(value)

Specifies a pipeline stage for the PipelineStateViewer.

VertexInput

The fixed function vertex input stage.

VertexShader

The vertex shader.

HullShader

The vertex shader.

TessControlShader

The tessellation control shader.

DomainShader

The domain shader.

TessEvalShader

The tessellation evaluation shader.

GeometryShader

The geometry shader, including stream-out/transform feedback.

Rasterizer

The fixed function rasterizer stage.

ViewportsScissors

The viewports and scissors. Helper alias for Rasterizer.

PixelShader

The pixel shader.

FragmentShader

The fragment shader.

ColorDepthOutput

The fixed function color and depth output stage, including color blending and depth/stencil testing state.

Blending

The color blending state. Helper alias for ColorDepthOutput.

DepthTest

The depth test state. Helper alias for ColorDepthOutput.

StencilTest

The stencil test state. Helper alias for ColorDepthOutput.

ComputeShader

The compute shader.

SampleMask

The sample mask.

class qrenderdoc.PipelineStateViewer

The pipeline state viewer window.

This window is retrieved by calling CaptureContext.GetPipelineViewer().

SaveShaderFile(shader)

Prompt the user to save the binary form of the given shader to disk.

Parameters:

shader# (renderdoc.ShaderReflection) – The shader reflection data to save.

Returns:

True if the shader was saved successfully, False if an error occurred.

Return type:

bool

SelectPipelineStage(stage)

Select a given pipeline stage in the viewer.

Parameters:

stage# (PipelineStage) – The stage to select.

Widget()

Retrieves the PySide2 QWidget for this PipelineStateViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Descriptor Viewer

class qrenderdoc.DescriptorViewer

A descriptor viewer window.

This window is retrieved by calling CaptureContext.ViewDescriptorStore() or CaptureContext.ViewDescriptors().

Widget()

Retrieves the PySide2 QWidget for this DescriptorViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Annotation Viewer

class qrenderdoc.AnnotationViewer

The annotation viewer window.

This window is retrieved by calling CaptureContext.GetAnnotationViewer().

RevealAnnotation(keyPath)

Expand the annotation view to reveal a given path and select it.

If the path does not exist, this will do nothing.

Parameters:

keyPath# (str) – The key path to the annotation.

Widget()

Retrieves the PySide2 QWidget for this AnnotationViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Texture Viewer

class qrenderdoc.FollowType(value)

Specifies a type of followed resource for the TextureViewer.

OutputColor

The index specifies which output color target to select. Shader stage and array index are ignored.

OutputDepth

The resource followed is the depth/stencil output target. All other parameters are ignored.

ReadWrite

The index specifies a resource within the given shader’s readWriteResources. The array element then specifies the index within that resource’s array, if applicable.

ReadOnly

The index specifies a resource within the given shader’s readOnlyResources. The array element then specifies the index within that resource’s array, if applicable.

OutputDepthResolve

The resource followed is the depth/stencil resolve output target. All other parameters are ignored.

class qrenderdoc.TextureViewer

The texture viewer window.

This window is retrieved by calling CaptureContext.GetTextureViewer().

GetChannelVisibility()

Return which channels are currently displayed, as a four-component tuple.

Returns:

The current channel visibility per component.

Return type:

Tuple[bool,bool,bool,bool]

GetChannelVisibilityBits()

Return which channels are currently displayed, as a bitmask.

If red is visible 0x1 will be set in the returned value, if blue is visible 0x2 will be set, etc.

Returns:

The current bitmask showing channel visibility.

Return type:

int

GetCurrentResource()

Return which resource is currently being displayed in the active tab.

Returns:

The ID of the resource being displayed.

Return type:

renderdoc.ResourceId

GetHistogramRange()

Return the current histogram blackpoint to whitepoint range.

Returns:

The current histogram range.

Return type:

Tuple[float,float]

GetPickedLocation()

Returns the currently selected texel location in the current texture.

If no location is currently selected or there is no current texture, this will return (-1, -1).

Returns:

The currently picked pixel location.

Return type:

Tuple[int,int]

GetSelectedSubresource()

Return which subresource is currently selected for viewing.

Returns:

The subresource currently selected.

Return type:

renderdoc.Subresource

GetTextureDisplay()

Return the currently configured texture display structure.

Returns:

The current texture display.

Return type:

renderdoc.TextureDisplay

GetTextureOverlay()

Return the currently selected texture overlay.

Returns:

The currently selected texture overlay.

Return type:

renderdoc.DebugOverlay

GetZoomLevel()

Return the current zoom level, whether manually set or auto-calculated.

Returns:

The current zoom level, with 100% being represented as 1.0.

Return type:

float

GotoLocation(x, y)

Highlights the given pixel location in the current texture.

Parameters:

  • x# (int) – The X co-ordinate.

  • y# (int) – The Y co-ordinate.

IsZoomAutoFit()

Return whether or not the texture viewer is currently auto-fitting the zoom level.

Returns:

True if the zoom level is currently auto-fitting.

Return type:

bool

SetChannelVisibility(red, green, blue, alpha)

Set the visibility of each channel.

Parameters:

  • red# (bool) – Whether the red channel should be visible.

  • green# (bool) – Whether the green channel should be visible.

  • blue# (bool) – Whether the blue channel should be visible.

  • alpha# (bool) – Whether the alpha channel should be visible.

SetHistogramRange(blackpoint, whitepoint)

Set the current histogram blackpoint to whitepoint range.

Parameters:

  • blackpoint# (float) – The value that should be mapped to black, component-wise.

  • whitepoint# (float) – The value that should be mapped to white, component-wise.

SetSelectedSubresource(sub)

Select a particular subresource within the currently selected texture. Any out of bounds parameters will be clamped to the available subresources.

Parameters:

sub# (renderdoc.Subresource) – The subresource to select.

SetTextureOverlay(overlay)

Changes the currently selected overlay the given pixel location in the current texture.

Parameters:

overlay# (renderdoc.DebugOverlay) – The overlay to enable.

SetZoomLevel(autofit, zoom)

Set the zoom level for displaying textures.

Parameters:

  • autofit# (bool) – True if the zoom level should be auto-calculated continuously to automatically fit the texture completely in view.

  • zoom# (float) – The zoom level as a percentage, with 100% being 1.0. Ignored if SetZoomLevel.autofit is True.

ViewFollowedResource(followType, stage, index, arrayElement)

Select the ‘following’ view and choose which resource slot to follow.

Parameters:

  • followType# (FollowType) – The type of followed resource.

  • stage# (renderdoc.ShaderStage) – The shader stage of the shader reflection data to look up.

  • index# (int) – The index within the given resource list (if applicable) to follow.

  • arrayElement# (int) – The index within the given resource array (if applicable) to follow.

ViewTexture(resourceId, typeCast, focus)

Open a texture view, optionally raising this window to the foreground.

Parameters:

  • resourceId# (renderdoc.ResourceId) – The ID of the texture to view.

  • typeCast# (renderdoc.CompType) – If possible interpret the texture with this type instead of its normal type. If set to 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.

  • focus# (bool) – True if the TextureViewer should be raised.

Widget()

Retrieves the PySide2 QWidget for this TextureViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Buffer Viewer

class qrenderdoc.BufferViewer

The buffer viewer window, either a raw buffer or the geometry pipeline.

This mesh viewer is retrieved by calling CaptureContext.GetMeshPreview().

A raw buffer viewer can be opened by calling CaptureContext.ViewBuffer(), CaptureContext.ViewTextureAsBuffer(), or CaptureContext.ViewConstantBuffer().

ScrollToColumn(column, stage)

Scroll to the given column in the given stage’s data.

Parameters:

  • column# (int) – the column to scroll to.

  • VSIn# (renderdoc.MeshDataStage) – Optional parameter. The stage of the geometry pipeline to scroll within. Ignored for non-mesh buffer viewers.

ScrollToRow(row, stage)

Scroll to the given row in the given stage’s data.

Parameters:

  • row# (int) – the row to scroll to.

  • VSIn# (renderdoc.MeshDataStage) – Optional parameter. The stage of the geometry pipeline to scroll within. Ignored for non-mesh buffer viewers.

SetCurrentInstance(instance)

For a mesh view, set the current instance. This is ignored when called on a raw buffer view.

Parameters:

instance# (int) – The instance to select, will be clamped to the range [0, numInstances-1]

SetCurrentView(view)

For a mesh view, set the current multiview view. This is ignored when called on a raw buffer view.

Parameters:

view# (int) – The view to select, will be clamped to the range [0, numViews-1]

SetPreviewStage(stage)

For a mesh view, set the current preview stage. This is ignored when called on a raw buffer view.

Parameters:

stage# (renderdoc.MeshDataStage) – The stage to show

ShowMeshData(stage)

Ensure the given stage’s data is visible and raised, if it wasn’t before.

Parameters:

stage# (renderdoc.MeshDataStage) – The stage of the geometry pipeline to show data for.

Widget()

Retrieves the PySide2 QWidget for this BufferViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Resource Inspector

class qrenderdoc.ResourceInspector

The Resource inspector window.

This window is retrieved by calling CaptureContext.GetResourceInspector().

CurrentResource()

Return which resource is currently being inspected.

Returns:

The ID of the resource being inspected.

Return type:

renderdoc.ResourceId

Inspect(id)

Change the current resource being inspected.

Parameters:

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

RevealParameter(param)

Expand the resource initialisation chunks to reveal and select a given parameter.

Parameters:

param# (renderdoc.SDObject) – The parameter to reveal and select.

Widget()

Retrieves the PySide2 QWidget for this ResourceInspector if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Capture Dialog

class qrenderdoc.CaptureDialog

The executable capture window.

This window is retrieved by calling CaptureContext.GetCaptureDialog().

IsInjectMode()

Determines if the window is in inject or launch mode.

Returns:

True if the window is set up for injecting.

Return type:

bool

Launch()

Launches a capture of the current executable.

Returns:

The connection window if successful, or None if no connection was made.

Return type:

CaptureConnection

LoadSettings(filename)

Loads settings from a file and applies them. See SetSettings().

Parameters:

filename# (str) – The filename to load the settings from.

SaveSettings(filename)

Saves the current settings to a file. See Settings().

Parameters:

filename# (str) – The filename to save the settings to.

SetCommandLine(cmd)

Sets the command line string to use when launching an executable.

Parameters:

cmd# (str) – The command line to use.

SetEnvironmentModifications(modifications)

Sets the list of environment modifications to apply when launching.

Parameters:

modifications# (List[renderdoc.EnvironmentModification]) – The list of modifications to apply.

SetExecutableFilename(filename)

Sets the executable filename to capture.

Parameters:

filename# (str) – The filename to execute.

SetInjectMode(inject)

Switches the window to or from inject mode.

Parameters:

inject# (bool) – True if the window should configure for injecting into processes.

SetSettings(settings)

Configures the window based on a bulk structure of settings.

Parameters:

settings# (CaptureSettings) – The settings to apply.

SetWorkingDirectory(dir)

Sets the working directory for capture.

Parameters:

dir# (str) – The directory to use.

Settings()

Retrieves the current state of the window as a structure of settings.

Returns:

The settings describing the current window state.

Return type:

CaptureSettings

UpdateGlobalHook()

Update the current state of the global hook, e.g. if it has been enabled.

UpdateRemoteHost()

Update the current state based on the current remote host, when that changes.

Widget()

Retrieves the PySide2 QWidget for this CaptureDialog if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

class qrenderdoc.CaptureConnection

A capture connection window.

When a program is successfully launched by CaptureDialog and a connection is made, this window can be used to access the details of that connection and any captures that have been made.

ClosedCallback(connection)

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

Called whenever a capture connection is closed.

Parameters:

connection (CaptureConnection) – The connection window. Invalid to use after the callback has returned.

Close(discardUnsaved)

Closes the connection to the target program. Normally there will be a prompt to the user to ask them whether they would like to save any unsaved captures to prevent data loss. If they choose to cancel, the connection may not be closed.

This prompt can be overridden with the parameter, at which point all unsaved captures will be deleted. You should ensure the user understands that this will happen.

Parameters:

discardUnsaved# (bool) – Whether to discard unsaved captures without prompting.

ConnectToChild(pid)

Connected to a given child process and return a connection window.

The connection window will automatically be shown if the connection is successfully made.

If the PID is unrecognised, no connection will be made.

Parameters:

pid# (int) – The PID of the child to connect to.

Returns:

The connection window if successful, or None if no connection was made.

Return type:

CaptureConnection

CycleActiveWindow()

Cycles which window is active on the connected device. Has no effect if there are not multiple windows or if the connection is inactive.

DeleteCapture(ID, promptForSave)

Delete the given capture, referred to by ID. If the capture is remote, an appropriate remote host connection is required.

Normally deleting a capture will prompt the user to prevent data loss, but this can be overridden with the argument.

Parameters:

  • ID# (int) – The ID of the capture to delete.

  • promptForSave# (bool) – True if the user should be prompted as normal to save the capture.

FriendlyHostname()

Gets the user friendly hostname for the connected target. This may not be a true hostname but is suitable for displaying to users particularly for platforms where the raw hostname is not necessarily user-friendly and there may be a more descriptive name available.

Returns:

The friendly hostname of the target this connection is to.

Return type:

str

GetAPIs()

Lists the names of APIs that have been used in the program. These APIs may not all be actively in use, as APIs are not removed from this list once they have been observed.

Note that some APIs may be listed here that RenderDoc does not support, but does recognise. You should not assume that these names will match those in the GraphicsAPI enum.

Returns:

The set of API names that have been used in the program.

Return type:

List[str]

GetCaptures()

Lists the captures that are known to have been made on this connection. Note that this reflects the UI and so the user is free to delete captures at any point, which will be reflected by them being removed from this list.

Each capture has an ID that is used to refer to it, note that this ID is not globally unique and is only unique within this connection.

Returns:

The currently known captures on this connection.

Return type:

List[ConnectedTempCapture]

GetChildProcesses()

Lists the PIDs of child processes that are known to still be running.

Returns:

The PIDs of each child process running under the connected program.

Return type:

List[int]

Hostname()

Gets the raw hostname for the connected target. This can be used elsewhere as a true hostname. For displaying to the user, prefer FriendlyHostname().

Returns:

The raw hostname of the target this connection is to.

Return type:

str

IsConnected()

Checks whether or not the connection is still active. If a program exits the connection will no longer be active.

Note that there is an inherent race here - the connection could drop immediately after returning.

Returns:

True if the window is set up for injecting.

Return type:

bool

OpenCapture(ID)

Open the given capture, referred to by ID, in the UI for analysis. If the capture is remote, an appropriate remote host connection is required.

This will prompt the user for closing any currently open capture and if the user chooses not to close the current capture the loading will be stopped.

Parameters:

ID# (int) – The ID of the capture to open.

PreventAutoClose()

Normally connection windows will self-close if the program exits and there are no captures made. This behaviour can be disabled by calling this function at which point the window will not close itself automatically.

QueueCapture(frameNumber, numFrames)

Asks the connected program to take captures beginning at a certain frame number.

If the frame number has already passed when the request is received, no capture is made.

Parameters:

  • frameNumber# (int) – The first frame number to capture.

  • numFrames# (int) – How many frames to capture including the first. If set to 0, nothing is captured.

RegisterClosedCallback(method)

Register a callback to be called when the connection window is closed for any reason.

Because capture connections can self-close when a program exits with no captures having been made, it can be useful to get a callback to notify you that the connection is no longer legal to use.

This callback happens on the UI thread.

Parameters:

method (Callable[[CaptureConnection], None]) – The function to callback when closed. Callback function signature must match ClosedCallback().

SaveCapture(ID, filename)

Save the given capture to disk, referred to by ID. If the capture is remote, an appropriate remote host connection is required.

If the filename is omitted the user will be prompted to choose a file and the capture will only be saved if they select a filename.

Parameters:

  • ID# (int) – The ID of the capture to delete.

  • filename=""# (str) – Optional parameter. The filename to save to on the local disk, if omitted the user will be prompted to choose a filename.

Target()

Gets the name of the program connected to. Usually the name of the executable for the process.

Returns:

The connection target.

Return type:

str

TimedCapture(secondsDelay, numFrames)

Asks the connected program to take a capture after a certain number of seconds have passed, possibly 0 seconds to immediately capture. This has no effect if the connection is inactive and does not guarantee that the program will still be connected in the future - if the connection is lost no capture is made.

While a delayed capture is waiting to be triggered, requests to trigger another delayed capture will be ignored. Only one can be active at once. If you need more complex or overlapping delayed captures you should do this yourself manually and call this function when each one is due.

Parameters:

  • secondsDelay# (float) – How many seconds to wait before triggering a capture.

  • numFrames# (int) – How many frames to capture including the first. If set to 0, nothing is captured.

Widget()

Retrieves the PySide2 QWidget for this CaptureConnection if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

class qrenderdoc.ConnectedTempCapture
class qrenderdoc.ConnectedTempCapture(other: ConnectedTempCapture)

The details of a capture that has been made on a connection but may not have been saved to disk or local.

api

The name of the API used for this capture.

Type:

str

captureID

The ID of the capture, which is arbitrary. IDs are unique for the capture within a given connection, but two connections may have the same ID.

Type:

int

frameNumber

The frame number which was captured. May be -1 if the capture was made via the RenderDoc API.

Type:

int

timestamp

The timestamp when the capture completed.

Type:

datetime

Debug Messages

class qrenderdoc.DebugMessageView

The debug warnings and errors window.

This window is retrieved by calling CaptureContext.GetDebugMessageView().

Widget()

Retrieves the PySide2 QWidget for this DebugMessageView if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Diagnostic Log

class qrenderdoc.DiagnosticLogView

The diagnostic log viewing window.

This window is retrieved by calling CaptureContext.GetDiagnosticLogView().

Widget()

Retrieves the PySide2 QWidget for this DiagnosticLogView if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Comment View

class qrenderdoc.CommentView

The capture comments window.

This window is retrieved by calling CaptureContext.GetCommentView().

GetComments()

Gets the current comments text.

Returns:

The current comments text.

Return type:

str

SetComments(text)

Sets the current comments text.

Parameters:

text# (str) – The new comments text.

Widget()

Retrieves the PySide2 QWidget for this CommentView if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Statistics Viewer

class qrenderdoc.StatisticsViewer

The statistics window.

This window is retrieved by calling CaptureContext.GetStatisticsViewer().

Widget()

Retrieves the PySide2 QWidget for this StatisticsViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Timeline Bar

class qrenderdoc.TimelineBar

The timeline bar.

This window is retrieved by calling CaptureContext.GetTimelineBar().

HighlightHistory(id, history)

Highlights the modifications in a frame of a given resource.

Parameters:
HighlightResourceUsage(id)

Highlights the frame usage of the specified resource.

Parameters:

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

Widget()

Retrieves the PySide2 QWidget for this TimelineBar if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Performance Counter Viewer

class qrenderdoc.PerformanceCounterViewer

The performance counter view window.

This window is retrieved by calling CaptureContext.GetPerformanceCounterViewer().

UpdateDurationColumn()

Updates duration columns if the selected time unit changes.

Widget()

Retrieves the PySide2 QWidget for this PerformanceCounterViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Python Shell

class qrenderdoc.PythonShell

The interactive python shell.

This window is retrieved by calling CaptureContext.GetPythonShell().

AttachDebugger(extensionName)

Tries to launch a python debugger to attach to the current process, in the context of a given extension.

Returns immediately if a debugger is already connected, or is not supported.

If the extension name is not a loaded extension, no debugger will be launched.

Note

The extension name is only used if a new debugger instance is launched, it will target that particular extension’s source location. An attached python debugger can debug all python code in the instance.

Parameters:

extensionName# (str) – The package name of the extension to use as context for launching a debugger program.

CheckUnsavedChanges()

Checks if there are unsaved changes to python scripts, and prompts the user about whether to discard them or not.

If it is OK to close the window (either because there are no unsaved changes, they were saved after a prompt, or the user chose to discard them then this function returns True.

Returns:

Whether or not it is OK to close without losing changes.

Return type:

bool

CreateNewScriptEditor(name, text)

Creates a new script editor with a given name and text contents.

Parameters:

  • name# (str) – The name to give the editor, does not have to be a filename.

  • text# (str) – The contents to start with in the editor, can be blank.

GetScriptText()

Returns the text of the currently focussed script editor.

Returns:

The current script text.

Return type:

str

LoadScriptFromFilename(filename)

Loads the given file and creates a new tab with the script contents. No tab is created if the file fails to load

Parameters:

filename# (str) – The filename of the script to load.

Returns:

Whether or not the script was successfully loaded.

Return type:

bool

RemoveOutputFilter()

Sets the filter on the output panel to show output from all python sources.

This will show output from the running script, as well as any extensions that are loaded.

RunScript()

Runs the current script in the python shell.

SetExtensionOutputFilter(extensionName)

Sets the filter on the output panel to only show output from the given extension.

If the extension does not exist or is not loaded, no change will be made to the output filter.

Parameters:

extensionName# (str) – The package name of the extension to show output from.

SetScriptOutputFilter()

Sets the filter on the output panel to only show output from scripts run.

This will hide any output from extensions that are loaded, and only show output that comes from the script run from inside the python window.

ShowHelp()

Raises the help panel.

This will ensure the panel showing the help browser is visible.

ShowOutput()

Raises the output panel.

This will ensure the panel showing the output from running python code is visible.

ShowREPL()

Raises the REPL panel.

This will ensure the panel with the interactive REPL is visible.

Widget()

Retrieves the PySide2 QWidget for this PythonShell if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Shader Viewer

class qrenderdoc.ShaderViewer

A shader window used for viewing, editing, or debugging.

This window is retrieved by calling CaptureContext.ViewShader(), CaptureContext.EditShader(), or CaptureContext.DebugShader().

SaveCallback(context, viewer, encoding, flags, entry, compiled)

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

Called whenever a shader viewer that was open for editing triggers a save/update.

Parameters:
RevertCallback(context)

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

Called whenever a shader viewer that was open for editing is closed.

Parameters:
AddWatch(expression)

Add an expression to the watch panel.

Parameters:

expression# (str) – The name of the expression to watch.

CurrentStep()

Retrieves the current step in the debugging.

Returns:

The current step.

Return type:

int

GetCurrentFileContents()

Return the current text of source files within the viewer. Primarily useful for returning any edits applied when editing a shader.

Returns:

The current file contents as a list of (filename, contents) pairs.

Return type:

List[Tuple[str,str]]

RunForward()

Runs execution forward to the next breakpoint, or the end of the trace.

SetCurrentStep(step)

Sets the current step in the debugging.

Parameters:

step# (int) – The current step to jump to.

ShowErrors(errors)

Show a list of shader compilation errors or warnings.

Parameters:

errors# (str) – The string of errors or warnings to display.

ToggleBreakpointOnDisassemblyLine(disassemblyLine)

Toggles a breakpoint at a given disassembly line (starting from 1).

Parameters:

disassemblyLine# (int) – The line of the disassembly to toggle a breakpoint on.

ToggleBreakpointOnInstruction(instruction=-1)

Toggles a breakpoint at a given instruction.

Parameters:

instruction=-1# (int) – Optional parameter. The instruction to toggle breakpoint at. If this is -1 the nearest instruction after the current caret position is used.

Widget()

Retrieves the PySide2 QWidget for this ShaderViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Pixel History

class qrenderdoc.PixelHistoryView

A pixel history window.

This window is retrieved by calling CaptureContext.ViewPixelHistory().

SetFailedDebug()

Indicates that the pixel history was launched as a result of failing to debug a shader, so a message will be displayed to explain.

SetHistory(history)

Set the history displayed in this window.

Parameters:

history# (List[renderdoc.PixelModification]) – A list of pixel events to display.

Widget()

Retrieves the PySide2 QWidget for this PixelHistoryView if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget

Shader Message Viewer

class qrenderdoc.ShaderMessageViewer

A shader message list window.

This window is retrieved by calling CaptureContext.ViewShaderMessages().

GetEvent()

Return the EID that this viewer is displaying messages from.

Returns:

The EID.

Return type:

int

GetShaderMessages()

Return the shader messages displayed in this viewer.

Returns:

The shader messages.

Return type:

List[renderdoc.ShaderMessage]

IsOutOfDate()

Returns whether or not this viewer is out of date - if the shaders have been edited since the messages were fetched.

Returns:

True if the viewer is out of date.

Return type:

bool

Widget()

Retrieves the PySide2 QWidget for this ShaderMessageViewer if PySide2 is available, or otherwise returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a QWidget.

Returns:

Return the widget handle, either a PySide2 handle or an opaque handle.

Return type:

QWidget