API Reference: qrenderdoc Persistant Config

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 Writing UI extensions.

Config

class qrenderdoc.PersistantConfig

A persistant config file that is automatically loaded and saved, which contains any settings and information that needs to be preserved from one run to the next.

The config is retrieved by calling CaptureContext.Config().

For more information about some of these settings that are user-facing see the documentation for the settings window.

AddRemoteHost(host)

Adds a new remote host.

Parameters

host (RemoteHost) – The remote host to add.

AllowGlobalHook

True if global hooking is enabled. Since it has potentially problematic side-effects and is dangerous, it requires explicit opt-in.

Defaults to False.

AllowProcessInject

True if process injection is enabled. Since it can often break and is almost always not want users want to do. New users can get confused by it being there and go to it first.

Defaults to False.

AlwaysLoad_Extensions

A list of strings with extension packages to always load on startup, without needing manual enabling.

Type

List[str]

AlwaysReplayLocally

True if when loading a capture that was originally captured on a remote device but uses an API that can be supported locally, should be loaded locally without prompting to switch to a remote context.

Defaults to False.

Analytics_ManualCheck

True if the user has remained with analytics turned on, but has chosen to manually check each report that is sent out. collection and reporting.

Defaults to False.

Analytics_TotalOptOut

True if the user has selected to completely opt-out from and disable all analytics collection and reporting.

Defaults to False.

BufferFormatter_SavedFormats

A list of strings with saved formats for the buffer formatter. The first line is the name and the rest of the contents are the formats.

Type

List[str]

CheckUpdate_AllowChecks

True if the UI should be allowed to make update checks remotely to see if a new version is available.

Defaults to True.

CheckUpdate_CurrentVersion

The current version at the time of update checks. Used to determine if a cached pending update is no longer valid because we got updated through some other method.

CheckUpdate_LastUpdate

A date containing the last time that update checks happened.

CheckUpdate_UpdateAvailable

True if an update to a newer version is currently available.

Defaults to False.

CheckUpdate_UpdateResponse

Contains the response from the update server from the last update check, with any release notes for the new version.

Close()

Closes the config file so that subsequent calls to Save() will not write to disk at the file the config was loaded from.

This function is rarely directly used, except in the case where RenderDoc is relaunching itself and wants to avoid file locking conflicts between the closing instance saving, and the loading instance loading. It can explicitly save and close before relaunching.

Comments_ShowOnLoad

True if when loading a new capture that contains a comments section, the comment viewer will be opened and focussed.

Defaults to False.

CrashReport_EmailAddress

The saved email address for pre-filling out in crash reports.

CrashReport_EmailNagged

True if the user has been prompted to enter their email address on a crash report. This really helps find fixes for bugs, so we prompt the user once only if they didn’t enter an email. Once the prompt has happened, regardless of the answer this is set to true and remains there forever.

Defaults to False.

CrashReport_LastOpenedCapture

The last opened capture, to send if any crash is encountered. This is different to the most recent opened file, because it’s set before any processing happens (recent files are only added to the list when they successfully open), and it’s cleared again when the capture is closed.

CrashReport_ReportedBugs

A list of BugReport detailing previously submitted bugs that we’re watching for updates.

Type

List[BugReport]

CrashReport_ShouldRememberEmail

True if the email address entered in the crash reporter should be remembered for next time. If no email is entered then nothing happens (any previous saved email is kept).

Defaults to True.

DefaultCaptureSaveDirectory

The default path to save captures in, when browsing to save a temporary capture somewhere.

DefaultReplayOptions

A ReplayOptions containing the configured default replay options to use in most scenarios when no specific options are given.

Type

renderdoc.ReplayOptions

DegradedCapture_LastUpdate

A date containing the last time that the user was warned about captures being loaded in degraded support. This prevents the user being spammed if their hardware is low spec.

EventBrowser_AddFake

True if fake action marker regions should be added to captures that don’t have any markers, for easier browsing. The regions are identified by grouping actions that write to the same targets together.

Defaults to True.

EventBrowser_ApplyColors

True if the EventBrowser should apply any colors specified with API marker regions.

Defaults to True.

EventBrowser_ColorEventRow

True if when coloring marker regions in the EventBrowser, the whole row should be colored instead of just a side-bar.

Defaults to True.

EventBrowser_TimeUnit

The TimeUnit to use to display the duration column in the EventBrowser.

Defaults to microseconds.

ExternalTool_RadeonGPUProfiler

The path to the executable of the external Radeon GPU Profiler tool.

Font_Family

The font family to use in the UI.

Defaults to an empty string which means to use the system default.

Font_GlobalScale

The global scale to apply to fonts in the application, expressed as a float.

Defaults to 1.0 which means 100%.

Font_MonoFamily

The monospaced font family to use in the UI.

Defaults to an empty string which means to use the system default.

Font_PreferMonospaced

True if a monospaced font should be used in all places where data is displayed, even if the data is not tabular such as names.

Defaults to False.

Formatter_MaxFigures

The maximum number of decimal places to show in formatted floating point values.

Note

The naming of ‘MaxFigures’ is a historical artifact - this controls the number of decimal places only, not the number of significant figures.

Defaults to 5.

Formatter_MinFigures

The minimum number of decimal places to show in formatted floating point values.

Note

The naming of ‘MinFigures’ is a historical artifact - this controls the number of decimal places only, not the number of significant figures.

Defaults to 2.

Formatter_NegExp

The cut-off on negative exponents of a normalised values to display using scientific notation.

E.g. for a value of 5, anything below 1.0e-5 will be displayed using scientific notation.

Defaults to 5.

Formatter_OffsetSizeDisplayMode

The formatting mode to use for values marked as Offsets or Sizes.

E.g. Auto: decimal by default and hexadecimal if above a certain threshold, Decimal: always use decimal, Hexadecimal: always use hexadecimal. Defaults to Auto.

Formatter_PosExp

The cut-off on positive exponents of a normalised values to display using scientific notation.

E.g. for a value of 7, anything below 1.0e+7 will be displayed using scientific notation.

Defaults to 7.

GetRemoteHost(hostname)

Look up a remote host by hostname.

Parameters

hostname (str) – The hostname to look up

Returns

The remote host for the given hostname, or an invalid RemoteHost if no such exists.

Return type

RemoteHost

GetRemoteHosts()

Returns a list of all remote hosts.

Returns

The remote host list

Return type

List[RemoteHost]

LastCaptureExe

The filename of the last executable that was captured, inside LastCapturePath.

LastCaptureFilePath

The path to the last capture to be opened, which is useful as a default location for browsing.

LastCapturePath

The path containing the last executable that was captured, which is useful as a default location for browsing.

LastFileBrowsePath

The path to the last file browsed to in any dialog. Used as a default location for all file browsers without another explicit default directory (such as opening capture files - see LastCaptureFilePath).

Load(filename)

Loads the config from a given filename. This happens automatically on startup, so it’s not recommended that you call this function manually.

Parameters

filename (str) – The filename to load from

Returns

A boolean status if the load was successful.

Return type

bool

LocalProxyAPI

The index of the local proxy API to use when using remote context replay. -1 if the default proxy should be used.

Defaults to -1.

RecentCaptureFiles

The recently opened capture files.

Type

List[str]

RecentCaptureSettings

The recently opened capture settings files.

Type

List[str]

RemoveRemoteHost(host)

Removes an existing remote host.

Parameters

host (RemoteHost) – The remote host to remove.

Save()

Saves the config to disk. This can happen if you want to be sure a setting has been propagated and will not be forgotten in the case of crash or otherwise unexpected exit.

Returns

A boolean status if the save was successful.

Return type

bool

SetStyle()

Sets the UI style to the value in UIStyle.

Changing the style after the application has started may not properly update everything, so to be sure the new style is applied, the application should be restarted.

Returns

True if the style was set successfully, False if there was a problem e.g. the value of UIStyle was unrecognised or empty.

Return type

bool

SetupFormatting()

Configures the Formatter class with the settings from this config.

ShaderProcessors

A list of ShaderProcessingTool detailing shader processing programs. The list comes in priority order, with earlier processors preferred over later ones.

Type

List[ShaderProcessingTool]

TemporaryCaptureDirectory

The path to where temporary capture files should be stored until they’re saved permanently.

TextureViewer_PerTexSettings

True if the TextureViewer should store most visualisation settings on a per-texture basis instead of keeping it persistent across different textures.

:Defaults to True.

TextureViewer_PerTexYFlip

True if the TextureViewer should treat y-flipping as a per-texture state rather than a global toggle.

Does nothing if per-texture settings are disabled in general.

Defaults to False.

TextureViewer_ResetRange

True if the TextureViewer should reset the visible range when a new texture is selected.

:Defaults to False.

TextureViewer_ShaderDirs

List of the directories containing custom shader files for the Texture Viewer.

Type

List[str]

Tips_HasSeenFirst

True if the user has seen the first tip, which should always be shown first before randomising.

Defaults to False.

UIStyle

The style to load for the UI. Possible values include ‘Native’, ‘RDLight’, ‘RDDark’. If empty, the closest of RDLight and RDDark will be chosen, based on the overall light-on-dark or dark-on-light theme of the application native style.

UnsupportedAndroid_LastUpdate

A date containing the last time that the user was warned about an Android device being older than is generally supported. This prevents the user being spammed if they consistently use an old Android device. If it has been more than 3 weeks since the last time an old device was seen, we re-warn the user, but if it’s less than 3 weeks we silently update this date so continuous use doesn’t nag.

UpdateEnumeratedProtocolDevices()

If configured, queries available device protocols to update auto-configured hosts.

class qrenderdoc.TimeUnit(value)

The unit that GPU durations are displayed in.

Seconds

The durations are displayed as seconds (s).

Milliseconds

The durations are displayed as milliseconds (ms).

Microseconds

The durations are displayed as microseconds (µs).

Nanoseconds

The durations are displayed as nanoseconds (ns).

class qrenderdoc.OffsetSizeDisplayMode(value)

The formatting mode used when displaying fields marked as Offsets or Sizes.

Auto

The data is displayed as decimal values by default and hexadecimal if above a certain threshold.

Decimal

The data is displayed as decimal values.

Hexadecimal

The data is displayed as hexadecimal values.

qrenderdoc.ConfigFilePath(filename)

Retrieve the absolute path where a given file can be stored with other application data.

Parameters

filename (str) – The base filename.

Returns

The absolute path.

Return type

str

qrenderdoc.UnitSuffix(unit)

Gets the suffix for a time unit.

Parameters

unit (TimeUnit) – The unit to get a suffix for.

Returns

The one or two character suffix.

Return type

str

qrenderdoc.AddRecentFile(recentList, file)

Checks if a given file is in a list. If it is, then it’s shuffled to the end. If it’s not then it’s added to the end

As the name suggests, this is used for tracking a ‘recent file’ list.

Parameters

• recentList (List[str]) – The list that is mutated by the function.

• file (str) – The file to add to the list.

qrenderdoc.RemoveRecentFile(recentList, file)

Removes a given file from the list, after normalising the path. If the path isn’t present then the list is not modified.

As the name suggests, this is used for tracking a ‘recent file’ list.

Parameters

• recentList (List[str]) – The list that is mutated by the function.

• file (str) – The file to remove from the list.

Shader Processing

class qrenderdoc.ShaderProcessingTool

Describes an external program that can be used to process shaders, typically either compiling from a high-level language to a binary format, or decompiling from the binary format to a high-level language or textual representation.

Commonly used with SPIR-V.

CompileShader(window, source, entryPoint, stage, spirvVer, args)

Runs this program to disassemble a given shader source.

Parameters

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

• source (str) – The source code, preprocessed into a single file.

• entryPoint (str) – The name of the entry point in the shader to compile.

• stage (renderdoc.ShaderStage) – The pipeline stage that this shader represents.

• spirvVer (str) – The version of SPIR-V in use for this shader, or an empty string for defaults. The current version can be obtained from reflection data via the @spirver compile flag.

• args (str) – arguments to pass to the tool. The default arguments can be obtained using DefaultArguments() which can then be customised as desired. Passing an empty string uses the default arguments.

Returns

The result of running the tool.

Return type

ShaderToolOutput

DefaultArguments()

Return the default arguments used when invoking this tool

Returns

The arguments specified for this tool.

Return type

str

DisassembleShader(window, shader, args)

Runs this program to disassemble a given shader reflection.

Parameters

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

• shader (renderdoc.ShaderReflection) – The shader to disassemble.

• args (str) – arguments to pass to the tool. The default arguments can be obtained using DefaultArguments() which can then be customised as desired. Passing an empty string uses the default arguments.

Returns

The result of running the tool.

Return type

ShaderToolOutput

args

The command line argmuents to pass to the program.

executable

The path to the executable to run for this program.

input

The input that this program expects.

name

The human-readable name of the program.

output

The output that this program provides.

tool

The KnownShaderTool identifying which known tool this program is.

class qrenderdoc.ShaderToolOutput

Contains the output from invoking a ShaderProcessingTool, including both the actual output data desired as well as any stdout/stderr messages.

log

The output log - containing the information about the tool run and any errors.

result

The actual output data from the tool

Bug Reports

class qrenderdoc.BugReport

Describes a submitted bug report.

URL()

Gets the URL for this report.

Returns

The URL to the report.

Return type

str

checkDate

The last date that we checked for updates.

reportId

The private ID of the bug report.

submitDate

The original date when this bug was submitted.

unreadUpdates

Unread updates to the bug exist

Remote Host

class qrenderdoc.RemoteHost

A handle for interacting with a remote server on a given host.

CheckStatus()

Ping the host to check current status - if the server is running, connection status, etc.

Connect(server)

Create a connection to the remote server.

Returns

The status of opening the capture, whether success or failure, and a RemoteServer instance if it were successful

Return type

Tuple[renderdoc.ResultDetails, renderdoc.RemoteServer]

FriendlyName()

Returns

The friendly name for this host, if available (if empty, the Hostname is used).

Return type

str

Hostname()

Returns

The hostname of this host.

Return type

str

IsBusy()

Returns

True if someone else is currently connected to this server.

Return type

bool

IsConnected()

Returns

True if an active connection exists to this remote server.

Return type

bool

IsLocalhost()

Returns

Returns True if this host represents the special localhost device.

Return type

bool

IsServerRunning()

Returns

True if a remote server is currently running on this host.

Return type

bool

IsValid()

Returns True if this host represents a valid remote host. :rtype: bool

IsVersionMismatch()

Returns

True if there is a code version mismatch with this server.

Return type

bool

LastCapturePath()

Returns

The last folder browsed to on this host, to provide a reasonable default path.

Return type

str

Launch()

Runs the command specified in runCommand. Returns ResultDetails which indicates success or the type of failure.

Returns

The result from launching the remote server.

Return type

renderdoc.ResultDetails

Name()

Returns

The name to display for this host in the UI, either FriendlyName() if it is valid, or Hostname() if not.

Return type

str

Protocol()

Returns

The DeviceProtocolController for this host, or None if no protocol is in use

Return type

renderdoc.DeviceProtocolController

RunCommand()

Returns

The command to run locally to try to launch the server remotely.

Return type

str

SetLastCapturePath(path)

Sets the last folder browsed to. See LastCapturePath().

Parameters

path (str) – The new path to set.

SetRunCommand(cmd)

Sets the run command. See RunCommand().

Parameters

cmd (str) – The new command to set.

VersionMismatchError()

Returns

The version mismatch error.

Return type

str