UI Extensions¶
Extension Manager¶
-
class
qrenderdoc.
ExtensionManager
¶ A manager for listing available and active extensions, as well as the interface for extensions to register hooks and additional functionality.
-
ExtensionCallback
(context, data)¶ Not a member function - the signature for any
ExtensionCallback
callbacks.Callback for extensions to register entry points with, used in many situations depending on how it was registered.
Parameters: - context (CaptureContext) – The current capture context.
- data (dict) – Additional data for the call, as a dictionary with string keys. Context-dependent based on what generated the callback
-
ErrorDialog
(text, title)¶ ErrorDialog(text)
Display an error message dialog.
Parameters:
-
GetInstalledExtensions
()¶ Retrieve a list of installed extensions.
Returns: The list of installed extensions. Return type: list
ofExtensionMetadata
.
-
GetMiniQtHelper
()¶ Returns a handle to the mini Qt helper. See
MiniQtHelper
.Returns: The helper interface. Return type: MiniQtHelper
-
IsExtensionLoaded
(name)¶ Check if an installed extension is enabled.
Parameters: name# (str) – The qualified name of the extension, e.g. foo.bar
Returns: If the extension is enabled or not. Return type: bool
-
LoadExtension
(name)¶ Enable an extension by name. If the extension is already enabled, this will reload it.
Parameters: name# (str) – The qualified name of the extension, e.g. foo.bar
Returns: If the extension loaded successfully or not. Return type: bool
-
MessageDialog
(text, title)¶ MessageDialog(text)
Display a simple informational message dialog.
Parameters:
-
OpenDirectoryName
(caption, dir)¶ OpenDirectoryName(caption) OpenDirectoryName()
Browse for a directory to open.
Parameters: Returns: The directory selected, or an empty string if nothing was selected.
Return type: str
-
OpenFileName
(caption, dir, filter)¶ OpenFileName(caption, dir) OpenFileName(caption) OpenFileName()
Browse for a filename to open.
Parameters: Returns: The filename selected, or an empty string if nothing was selected.
Return type: str
-
QuestionDialog
(text, options, title)¶ QuestionDialog(text, options)
Display an error message dialog.
Parameters: Returns: The button that was clicked on.
Return type: DialogButton
-
RegisterContextMenu
(base, submenus, callback)¶ Register a context menu item in a panel for an extension.
Parameters: - base# (ContextMenu) – The panel to add the item to.
- submenus# (list) – A list of strings containing the submenus to add before the item. The last string will be the name of the menu item itself. Must contain at least one entry.
- callback# – The function to callback when the menu item is selected.
-
RegisterPanelMenu
(base, submenus, callback)¶ Register a menu item in a panel for an extension.
Parameters:
-
RegisterWindowMenu
(base, submenus, callback)¶ Register a new menu item in the main window’s menus for an extension.
Parameters: - base# (WindowMenu) – The base menu to add the item to.
- submenus# (list) – A list of strings containing the submenus to add before the item. The last
string will be the name of the menu item itself. Must contain at least one entry, or two entries
if
base
isWindowMenu.NewMenu
. - callback# – The function to callback when the menu item is selected.
-
SaveFileName
(caption, dir, filter)¶ SaveFileName(caption, dir) SaveFileName(caption) SaveFileName()
Browse for a filename to save to.
Parameters: Returns: The filename selected, or an empty string if nothing was selected.
Return type: str
-
Mini-Qt Helper¶
-
class
qrenderdoc.
MiniQtHelper
¶ Python can have direct access to Qt via PySide2, but this is not always available in all RenderDoc builds. To aid extensions to manipulate widgets in a simple but portable fashion this helper exposes a small subset of Qt via RenderDoc’s python bindings.
The intention is not to allow fully flexible building of Qt panels, but to allow access to some basic UI building tools for simple data input and display which can be used on any RenderDoc build.
Note
The widget handles returned are PySide2 widgets where that is available, so this can be used to make a basic UI and optionally customise it further with PySide2 when possible.
-
WidgetCallback
(context, widget, text)¶ Not a member function - the signature for any
WidgetCallback
callbacks.Callback for widgets can be registered at creation time, the text field is optional and may be blank depending on the event, but the context and widget are always valid.
Parameters: - context (CaptureContext) – The current capture context.
- widget (QWidget) – The widget sending the callback.
- text (str) – Additional data for the call, such as the current or selected text.
-
AddGridWidget
(parent, row, column, child, rowSpan, columnSpan)¶ Adds a child widget to a grid layout. If the parent is not a grid layout nothing will happen and the widget will not be added anywhere.
Parameters: - parent# (QWidget) – The parent grid layout widget.
- row# (int) – The row at which to add the child widget.
- column# (int) – The column at which to add the child widget.
- child# (QWidget) – The child widget to add.
- rowSpan# (int) – How many rows should this child span over.
- columnSpan# (int) – How many columns should this child span over.
-
AddWidget
(parent, child)¶ Adds a child widget to the end of an ordered layout (either horizontal or vertical). If the parent is not an ordered layout nothing will happen and the widget will not be added anywhere.
Parameters:
-
ClearContainedWidgets
(parent)¶ Removes all child widgets from a parent and makes them invisible.
These widgets remain valid and can be re-added to another parent or the same parent.
Parameters: parent# (QWidget) – The parent widget to clear of children.
-
CloseCurrentDialog
(success)¶ Close the active modal dialog. This does nothing if no dialog is being shown.
Note
Closing a dialog ‘sucessfully’ does nothing except modify the return value of
CloseCurrentDialog()
. It allows quick distinguishing between OK and Cancel actions without having to carry that information separately in a global or other state.Parameters: success# (bool) – True
if the dialog was successful (the user clicked an OK/Accept type button).
-
CreateButton
(pressed)¶ Create a normal button widget.
Parameters: pressed# (WidgetCallback) – Callback to be called when the button is pressed. Returns: The handle to the newly created widget. Return type: QWidget
-
CreateCheckbox
(changed)¶ Create a checkbox widget which can be toggled between unchecked and checked. When created the checkbox is unchecked.
Parameters: changed# (WidgetCallback) – Callback to be called when the widget is toggled. Returns: The handle to the newly created widget. Return type: QWidget
-
CreateComboBox
(editable, changed)¶ Create a drop-down combo box widget.
When created there are no pre-defined entries in the drop-down section. This can be changed with
SetComboOptions()
.Parameters: - editable# (bool) –
True
if the widget should allow the user to enter any text they wish as well as being able to select a pre-defined entry. - changed# (WidgetCallback) – Callback to be called when the text in the combobox is changed. This will be called both when a new option is selected or when the user edits the text.
Returns: The handle to the newly created widget.
Return type: QWidget
- editable# (bool) –
-
CreateGridContainer
()¶ Creates and returns a grid layout widget.
The widget needs to be added to a parent to become part of a panel or window.
Children added to this layout widget are arranged in a grid. Widget sizing follows default logic, which typically has some widgets be only large enough for their content and others which are ‘greedy’ evenly divide any remaining free space. This will not violate the grid constraint though.
Returns: The handle to the newly created widget. Return type: QWidget
-
CreateGroupBox
(collapsible)¶ Create a groupbox widget which can optionally allow collapsing.
This widget can have children added, but it is recommended to immediately add only one child which is a layout type widget, to allow customising how children are added. By default the children are added in a vertical layout.
The widget needs to be added to a parent to become part of a panel or window.
Parameters: collapsible# (bool) – True
if the groupbox should have a toggle in its header to allow collapsing its contents down vertically.Returns: The handle to the newly created widget. Return type: QWidget
-
CreateHorizontalContainer
()¶ Creates and returns a horizontal layout widget.
The widget needs to be added to a parent to become part of a panel or window.
Children added to this layout widget are listed horizontally. Widget sizing follows default logic, which typically has some widgets be only large enough for their content and others which are ‘greedy’ evenly divide any remaining free space.
Returns: The handle to the newly created widget. Return type: QWidget
-
CreateLabel
()¶ Create a read-only label widget.
Note
This widget will be blank by default, you can set the text with
SetWidgetText()
.Returns: The handle to the newly created widget. Return type: QWidget
-
CreateOutputRenderingWidget
()¶ Create a widget suitable for rendering to with a
renderdoc.ReplayOutput
. This widget takes care of painting on demand and recreating the internal display widget when necessary, however this means you must useGetWidgetWindowingData()
to retrieve the windowing data for creating the output as well as callSetWidgetReplayOutput()
to notify the widget of the current output.Returns: The handle to the newly created widget. Return type: QWidget
-
CreateRadiobox
(changed)¶ Create a radio box widget which can be toggled between unchecked and checked but with at most one radio box in any group of sibling radio boxes being checked.
Upon creation the radio box is unchecked, even in a group of other radio boxes that are unchecked. If you want a default radio box to be checked, you should use
SetWidgetChecked()
.Parameters: changed# (WidgetCallback) – Callback to be called when the widget is toggled. Returns: The handle to the newly created widget. Return type: QWidget
-
CreateSpinbox
(decimalPlaces, step)¶ Create a spinbox widget with a numerical value and up/down buttons to change it.
The number of decimal places can be set to 0 for an integer spinbox, and in that case the step should be set to 1.0.
By default the spinbox has minimum and maximum values of 0.0 and 100.0, these can be changed with
SetSpinboxBounds()
.Parameters: Returns: The handle to the newly created widget.
Return type: QWidget
-
CreateTextBox
(singleLine, changed)¶ Create a text box widget for the user to enter text into.
Parameters: Returns: The handle to the newly created widget.
Return type: QWidget
-
CreateToplevelWidget
(windowTitle)¶ Creates and returns a top-level widget for creating layouts.
The widget is not immediately visible. It should be shown either with
ShowWidgetAsDialog()
or withCaptureContext.AddDockWindow()
once it’s ready.This widget can have children added, but it is recommended to immediately add only one child which is a layout type widget, to allow customising how children are added. By default the children are added in a vertical layout.
Parameters: windowTitle# (str) – The title of any window with this widget as its root. Returns: The handle to the newly created widget. Return type: QWidget
-
CreateVerticalContainer
()¶ Creates and returns a vertical layout widget.
The widget needs to be added to a parent to become part of a panel or window.
Children added to this layout widget are listed vertically. Widget sizing follows default logic, which typically has some widgets be only large enough for their content and others which are ‘greedy’ evenly divide any remaining free space.
Returns: The handle to the newly created widget. Return type: QWidget
-
FindChildByName
(parent, name)¶ Find a child widget of a parent by internal name.
Parameters: Returns: The handle to the first widget with a matching name, or
None
if no widget is found.Return type: QWidget
-
GetChild
(parent, index)¶ Return a child widget for a parent.
Parameters: Returns: The specified child of the parent, or
None
if the index is out of bounds.Return type: QWidget
-
GetNumChildren
(widget)¶ Return the number of children this widget has. This is generally only useful for layout type widgets.
Parameters: widget# (QWidget) – The widget to query. Returns: The number of child widgets this widget has. Return type: int
-
GetParent
(widget)¶ Return the parent of a widget in the widget hierarchy.
Note
The widget returned may not be a widget created through this helper interface if the specified widget has been docked somewhere. Beware making changes to any widgets returned as you may modify the RenderDoc UI itself.
Parameters: widget# (QWidget) – The widget to query. Returns: The handle to the parent widget with a matching name, or None
if this widget is either not yet parented or is a top-level window.Return type: QWidget
-
GetSpinboxValue
(spinbox)¶ Return the current value of a spinbox widget. If another type of widget is passed
0.0
will be returned.Parameters: spinbox# (QWidget) – The widget to query. Returns: The current value of the spinbox. Return type: float
-
GetWidgetName
(widget)¶ Return the internal name of a widget, as set my
SetWidgetName()
.Parameters: widget# (QWidget) – The widget to query. Returns: The widget’s internal name, which may be an empty string if no name has been set. Return type: str
-
GetWidgetText
(widget)¶ Return the current text of a widget. See
SetWidgetText()
.Parameters: widget# (QWidget) – The widget to query. Returns: The widget’s current text, which may be an empty string if no valid text is available. Return type: str
-
GetWidgetType
(widget)¶ Return the type of the widget as a string. This type is the Qt type name so this should only be used for debugging as the name may change even if for the same type of widget.
Parameters: widget# (QWidget) – The widget to query. Returns: The widget’s type name. Return type: str
-
GetWidgetWindowingData
(widget)¶ Return the opaque pointer of windowing data suitable for passing to
CreateOutput()
or other functions that expect windowing data.If the widget is not a output rendering widget created with
CreateOutputRenderingWidget()
this function will fail and return an invalid set of windowing data.It’s important to note that the windowing data is not valid forever, so this function should be called as close to where you call
CreateOutput()
as possible. Also don’t fetch windowing data unless you are going to create an output, because this function will cause the widget to go into an undefined state unless an output is created to render onto it.Note
This function must be called on the main UI thread.
Parameters: window# (QWidget) – The widget to create windowing data for. Returns: The windowing data. Return type: WindowingData
-
InsertWidget
(parent, index, child)¶ Insert a child widget at the specified index in an ordered layout (either horizontal or vertical). If the parent is not an ordered layout nothing will happen and the widget will not be added anywhere.
Parameters: - parent# (QWidget) – The parent grid layout widget.
- index# (int) – The index to insert the widget at. If this index is out of bounds it will be clamped, so that negative indices will be equivalent to index 0 and all indices above the number of children will append the widget
- child# (QWidget) – The child widget to add.
-
IsWidgetChecked
(checkableWidget)¶ Return the current checked-state of a widget. See
SetWidgetChecked()
. If another type of widget is passed other than a checkbox or radio boxFalse
will be returned.Parameters: checkableWidget# (QWidget) – The widget to query. Returns: True
if the widget is currently checked.Return type: bool
-
IsWidgetEnabled
(widget)¶ Return the current enabled-state of a widget. See
SetWidgetEnabled()
.Parameters: widget# (QWidget) – The widget to query. Returns: True
if the widget is currently enabled.Return type: bool
-
SetComboOptions
(combo, options)¶ Set the pre-defined options in a drop-down combo box. If another type of widget is passed nothing will happen.
Parameters:
-
SetSpinboxBounds
(spinbox, minVal, maxVal)¶ Set the minimum and maximum values allowed in the spinbox. If another type of widget is passed nothing will happen.
Parameters:
-
SetSpinboxValue
(spinbox, value)¶ Set the value contained in a spinbox. If another type of widget is passed nothing will happen.
Parameters:
-
SetWidgetBackgroundColor
(widget, red, green, blue)¶ Set the default backkground color for a rendering widget. This background color is used when no output is currently configured, e.g. when a capture is closed.
For all other widget types this has no effect.
To disable the background color pass negative values for the components, this will cause a default checkerboard to be rendered instead. This is the default behaviour when a widget is created.
Parameters:
-
SetWidgetChecked
(checkableWidget, checked)¶ Set whether the widget is checked or not. This only affects checkboxes and radio boxes. If another type of widget is passed nothing will happen.
Parameters:
-
SetWidgetEnabled
(widget, enabled)¶ Set whether the widget is enabled or not. This generally only affects interactive widgets and not fixed widgets, interactive widgets become read-only while still displaying the same data.
Note
Disabled widgets can still be modified programmatically, they are only disabled for the user.
Parameters:
-
SetWidgetFont
(widget, font, fontSize, bold, italic)¶ Change the font properties of a widget.
Parameters: - widget# (QWidget) – The widget to change font of.
- font# (str) – The new font family to use, or an empty string to leave the font family the same.
- fontSize# (int) – The new font point size to use, or 0 to leave the size the same.
- bold# (bool) –
True
if the font should be bold. - italic# (bool) –
True
if the font should be italic.
-
SetWidgetName
(widget, name)¶ Set the internal name of a widget. This is not displayed anywhere but can be used by
FindChildByName()
to locate a widget within a hierarchy.Note
Names are optional and only for your use. Nothing prevents from you from setting duplicate names, but this makes searches by name ambiguous.
Parameters:
-
SetWidgetReplayOutput
(widget, output)¶ Set the current output for a widget. This only affects output rendering widgets. If another type of widget is passed nothing will happen.
Passing
None
as the output will reset the widget and make it display the default background until another output is set.When a capture is closed and all outputs are destroyed, the widget will automatically unset the output so there is no need to do that manually.
Parameters: - widget# (QWidget) – The widget to set the output for.
- output# (ReplayOutput) – The new output to set, or
None
to unset any previous output.
-
SetWidgetText
(widget, text)¶ Set the ‘text’ of a widget. How this manifests depends on the type of the widget, for example a text-box or label will set the text directly. For a checkbox or radio button this will add text next to it.
Parameters:
-
ShowWidgetAsDialog
(widget)¶ Show a top-level widget as a blocking modal dialog. This is most useful to prompt the user for some specific information.
The dialog is only closed when the user closes the window explicitly or if you call
CloseCurrentDialog()
in a widget callback, e.g. upon a button press.Parameters: widget# (QWidget) – The top-level widget to show as a dialog. Returns: Whether the dialog was closed successfully, via CloseCurrentDialog()
.Return type: bool
-
Helpers¶
-
class
qrenderdoc.
ExtensionMetadata
¶ The metadata for an extension.
The author of the extension, optionally with an email contact
-
description
¶ A longer description of what the extension does
-
extensionAPI
¶ The version of the extension API that this extension is written against
-
extensionURL
¶ The URL for where the extension is fetched from
-
filePath
¶ The location of this package on disk
-
name
¶ The short friendly name for the extension
-
package
¶ The python package for this extension, e.g. foo.bar
-
version
¶ The version of the extension
-
class
qrenderdoc.
WindowMenu
¶ Specifies the base menu to add a menu item into.
-
File
¶ The menu item will be in a section between Open/Save/Close captures and Import/Export.
-
Window
¶ The menu item will be in a new section at the end of the menu.
-
Tools
¶ The menu item will be added to a new section above Settings.
-
NewMenu
¶ The menu item will be a root menu, placed between Tools and Help.
-
Help
¶ The menu item will be added after the error reporting item.
-
-
class
qrenderdoc.
PanelMenu
¶ Specifies the panel to add a menu item into.
-
EventBrowser
¶ The
EventBrowser
.
-
PipelineStateViewer
¶ The
PipelineStateViewer
.
-
MeshPreview
¶ The mesh previewing
BufferViewer
.
-
TextureViewer
¶ The
TextureViewer
.
-
-
class
qrenderdoc.
ContextMenu
¶ Specifies the panel to add a menu item into.
-
EventBrowser_Event
¶ Adds the item to the context menu for events in the
EventBrowser
.
-
MeshPreview_Vertex
¶ Adds the item to the context menu for all vertices in the mesh previewing
BufferViewer
.
-
MeshPreview_VSInVertex
¶ Adds the item to the context menu for vertex inputs in the mesh previewing
BufferViewer
.
-
MeshPreview_VSOutVertex
¶ Adds the item to the context menu for VS output in the mesh previewing
BufferViewer
.
-
MeshPreview_GSOutVertex
¶ Adds the item to the context menu for GS/Tess output in the mesh previewing
BufferViewer
.
-
TextureViewer_Thumbnail
¶ Adds the item to the context menu for all thumbnails in the
TextureViewer
.
-
TextureViewer_InputThumbnail
¶ Adds the item to the context menu for input thumbnails in the
TextureViewer
.
-
TextureViewer_OutputThumbnail
¶ Adds the item to the context menu for output thumbnails in the
TextureViewer
.
-