Main Interfaces¶
Context¶
-
class
qrenderdoc.
CaptureContext
¶ The capture context that the python script is running in.
-
APIProps
()¶ Retrieve the
APIProperties
for the currently loaded capture.Returns: The API properties. Return type: APIProperties
-
AddDockWindow
(newWindow, ref, refWindow, percentage=0.5)¶ AddDockWindow(newWindow, ref, refWindow)
Adds a new window within the docking system.
Parameters: - dockWindow (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. - percentage (float) – Optionally the percentage to split the area. If omitted, a 50% split is used.
-
AddLogViewer
(viewer)¶ Register a new instance of
LogViewer
to receive capture event notifications.Parameters: viewer (LogViewer) – The viewer to register.
-
AddMessages
(msgs)¶ Add messages into the list returned by
DebugMessages()
. Initially set to unread.Parameters: msgs (list) – A list of DebugMessage
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.
-
CloseLogfile
()¶ Close the currently open capture file.
-
Config
()¶ Retrieve the current persistant config.
Returns: The current persistant config manager. Return type: PersistantConfig
-
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
-
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, or None
if PySide2 is not available.Return type: QWidget
-
CurD3D11PipelineState
()¶ Retrieve the current
D3D11_State
pipeline state.Returns: The current D3D11 pipeline state. Return type: D3D11_State
-
CurD3D12PipelineState
()¶ Retrieve the current
D3D12_State
pipeline state.Returns: The current D3D12 pipeline state. Return type: D3D12_State
-
CurDrawcall
()¶ Retrieve the current drawcall.
Returns: The current drawcall. Return type: DrawcallDescription
-
CurDrawcalls
()¶ Retrieve the root list of drawcalls in the current capture.
Returns: The root drawcalls. Return type: list
ofDrawcallDescription
-
CurGLPipelineState
()¶ Retrieve the current
GL_State
pipeline state.Returns: The current OpenGL pipeline state. Return type: GL_State
-
CurPipelineState
()¶ Retrieve the current
CommonPipelineState
abstracted pipeline state.Returns: The current API-agnostic abstracted pipeline state. Return type: CommonPipelineState
-
CurSelectedDrawcall
()¶ Retrieve the currently selected drawcall.
In most cases, prefer using
CurDrawcall()
. SeeLogViewer.OnSelectedEventChanged()
for more information for how this differs.Returns: The currently selected drawcall. Return type: DrawcallDescription
-
CurSelectedEvent
()¶ Retrieve the currently selected
EID
.In most cases, prefer using
CurEvent()
. SeeLogViewer.OnSelectedEventChanged()
for more information for how this differs.Returns: The current selected event. Return type: int
-
CurVulkanPipelineState
()¶ Retrieve the current
VK_State
pipeline state.Returns: The current Vulkan pipeline state. Return type: VK_State
-
CurWindowingSystem
()¶ Retrieve the current windowing system in use.
Returns: The active windowing system. Return type: WindowingSystem
-
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
ofDebugMessage
-
DebugShader
(bind, shader, stage, trace, debugContext)¶ Show a new
ShaderViewer
window, showing a read-only view of a debug trace through the execution of a given shader.Parameters: - bind (ShaderBindpointMapping) – The bindpoint mapping for the shader to view.
- shader (ShaderReflection) – The reflection data for the shader to view.
- stage (ShaderStage) – The stage that the shader is bound to.
- trace (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 EID 678’.
Returns: The new
ShaderViewer
window opened, but not shown.Return type:
-
EditShader
(customShader, entryPoint, files, saveCallback, closeCallback)¶ Show a new
ShaderViewer
window, showing an editable view of a given shader.Parameters: - customShader (bool) –
True
if the shader being edited is a custom display shader. - entryPoint (str) – The entry point to be used when compiling the edited shader.
- files (dict) – The files stored in a
dict
withstr
keys as filenames andstr
values with the file contents. - saveCallback (ShaderViewer.SaveCallback) – The callback function to call when a save/update is triggered.
- closeCallback (ShaderViewer.CloseCallback) – The callback function to call when the shader viewer is closed.
Returns: The new
ShaderViewer
window opened but not shown for editing.Return type: - customShader (bool) –
-
FillWindowingData
(winId)¶ Create an opaque pointer suitable for passing to
CreateOutput()
or other functions that expect windowing data.Note
This data only stays valid until the next call to FillWindowingData. You should pass it to the consuming function immediately.
Parameters: winId (int) – The window ID as returned from QWidget.winId()
.Returns: The windowing data. Return type: opaque void * pointer.
-
FrameInfo
()¶ Retrieve the
FrameDescription
for the currently loaded capture.Returns: The frame information. Return type: 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
-
GetBuffer
(id)¶ Retrieve the information about a particular buffer.
Parameters: id (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: BufferDescription
-
GetBuffers
()¶ Retrieve the list of buffers in the current capture.
Returns: The list of buffers. Return type: list
ofBufferDescription
-
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
-
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
-
GetDrawcall
(eventID)¶ Retrieve the information about a drawcall at a given
EID
.Parameters: id (int) – The EID
to query for.Returns: The information about the drawcall, or None
if theEID
doesn’t correspond to a drawcall.Return type: BufferDescription
-
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
-
GetMainWindow
()¶ Retrieve the current singleton
MainWindow
.Returns: The current window. Return type: MainWindow
-
GetMeshPreview
()¶ Retrieve the current singleton
BufferViewer
.Returns: The current window, which is created (but not shown) it there wasn’t one open. Return type: BufferViewer
-
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
-
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
-
GetTexture
(id)¶ Retrieve the information about a particular texture.
Parameters: id (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: 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
ofTextureDescription
-
HasAPIInspector
()¶ Check if there is a current
APIInspector
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
-
HasDebugMessageView
()¶ Check if there is a current
DebugMessageView
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
MeshPreview
open.Returns: True
if there is a window open.Return type: bool
-
HasPipelineViewer
()¶ Check if there is a current
PipelineViewer
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
-
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
-
IsLogLocal
()¶ 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
-
LoadLogfile
(logFile, origFilename, temporary, local)¶ Open a capture file for replay.
Parameters: - logFile (str) – The actual path to the capture file.
- 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
iflogFile
refers to a file on the local machine.
-
LogFilename
()¶ Retrieve the filename for the currently loaded capture.
Returns: The filename of the current capture. Return type: str
-
LogLoaded
()¶ Check whether or not a capture is currently loaded.
Returns: True
if a capture is loaded.Return type: bool
-
LogLoading
()¶ Check whether or not a capture is currently loading in-progress.
Returns: True
if a capture is currently loading.Return type: bool
-
MarkMessagesRead
()¶ Mark all messages as read, resets
UnreadMessageCount()
to 0.
-
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.
-
RefreshStatus
()¶ Replay the capture to the current event again, to pick up any changes that might have been made.
-
RemoveLogViewer
(viewer)¶ Unregister an instance of
LogViewer
from receiving notifications.Parameters: viewer (LogViewer) – The viewer to unregister.
-
Replay
()¶ Retrieve the replay manager for access to the internal RenderDoc replay controller.
Returns: The current replay manager. Return type: ReplayManager
-
SetEventID
(exclude, selectedEventID, eventID, force=False)¶ SetEventID(exclude, selectedEventID, eventID)
Move the current replay to a new event in the capture.
Parameters: - exclude (list) – A list of
LogViewer
to exclude from being notified of this, to stop infinite recursion. - selectedEventID (int) – The selected
EID
. SeeLogViewer.OnSelectedEventChanged()
for more information. - eventID (int) – The new current
EID
. SeeLogViewer.OnEventChanged()
for more information. - force (bool) – Optional parameter, if
True
then the replay will ‘move’ even if it is moving to the sameEID
as it’s currently on.
- exclude (list) – A list of
-
ShowAPIInspector
()¶ Raise the current
APIInspector
, showing it in the default place if needed.
-
ShowCaptureDialog
()¶ Raise the current
CaptureDialog
, showing it in the default place if needed.
-
ShowDebugMessageView
()¶ Raise the current
DebugMessageView
, 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
MeshPreview
, showing it in the default place if needed.
-
ShowPipelineViewer
()¶ Raise the current
PipelineViewer
, showing it in the default place if needed.
-
ShowPythonShell
()¶ Raise the current
PythonShell
, 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.
-
TempLogFilename
(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
-
ViewBuffer
(byteOffset, byteSize, id, format)¶ ViewBuffer(byteOffset, byteSize, id)
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 (ResourceId) – The ID of the buffer to fetch data from.
- format (str) – Optionally a HLSL/GLSL style formatting string.
Returns: The new
BufferViewer
window opened, but not shown.Return type:
-
ViewConstantBuffer
(stage, slot, idx)¶ Show a new
ConstantBufferPreviewer
window, showing a read-only view of a the variables in a constant buffer with their values.Parameters: - stage (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
ConstantBufferPreviewer
window opened, but not shown.Return type:
-
ViewPixelHistory
(texID, x, y, display)¶ Show a new
PixelHistoryView
window, showing the results from a pixel history operation.Parameters: - id (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.
- display (TextureDisplay) – The texture display configuration to use when looking up the history.
Returns: The new
PixelHistoryView
window opened, but not shown.Return type:
-
ViewShader
(bind, shader, stage)¶ Show a new
ShaderViewer
window, showing a read-only view of a given shader.Parameters: - bind (ShaderBindpointMapping) – The bindpoint mapping for the shader to view.
- shader (ShaderReflection) – The reflection data for the shader to view.
- stage (ShaderStage) – The stage that the shader is bound to.
Returns: The new
ShaderViewer
window opened, but not shown.Return type:
-
ViewTextureAsBuffer
(arrayIdx, mip, id, format)¶ ViewTextureAsBuffer(arrayIdx, mip, id)
Show a new
BufferViewer
window, showing a read-only view of a texture’s raw bytes.Parameters: - arrayIdx (int) – The array slice to load from.
- mip (int) – The mip level to load from.
- id (ResourceId) – The ID of the texture itself.
- format (str) – Optionally a HLSL/GLSL style formatting string.
Returns: The new
BufferViewer
window opened, but not shown.Return type:
-
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.-
InvokeCallback
(controller)¶ Not a member function - the signature for any
InvokeCallback
callbacks.Parameters: controller (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) – The
PathEntry
entries underneath the path, as relevant.
-
AsyncInvoke
(tag, method)¶ AsyncInvoke(method)
Make a tagged non-blocking invoke call onto the replay thread.
This tagged function is for cases when we might send a request - e.g. to pick a vertex or pixel - and want to pre-empt 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.
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.
Parameters: - tag (str) – The tag to identify this callback.
- method (InvokeCallback) – The function to callback on the replay thread.
-
BlockInvoke
(m)¶ Make a blocking invoke call onto the replay thread.
Parameters: method (InvokeCallback) – The function to callback on the replay thread.
-
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: ReplayStatus
-
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 None
if no connection is active.Return type: RemoteHost
-
DeleteCapture
(logfile, local)¶ Delete a capture file, whether local or remote.
Parameters: - logfile (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, logfile, 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) – Any
EnvironmentModification
that should be made when running the program. - logfile (str) – The location to save any captures, if running locally.
- opts (CaptureOptions) – The capture options to use when injecting into the program.
Returns: The ident where the new application is listening for target control, or 0 if something went wrong.
Return type: int
-
GetHomeFolder
(synchronous, cb)¶ 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: - synchronous (bool) – If a capture is open, then
True
will useBlockInvoke()
to call the callback. Otherwise ifFalse
thenAsyncInvoke()
will be used. - method (DirectoryBrowseMethod) – The function to callback on the replay thread.
- synchronous (bool) – If a capture is open, then
-
GetRemoteSupport
()¶ Retrieve a list of drivers that the current remote server supports.
Returns: The list of supported replay drivers. Return type: list
ofstr
.
-
ListFolder
(path, synchronous, cb)¶ 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 useBlockInvoke()
to call the callback. Otherwise ifFalse
thenAsyncInvoke()
will be used. - method (DirectoryBrowseMethod) – The function to callback on the replay thread.
-
PingRemote
()¶ Ping the remote server to ensure the connection is still alive.
-
ShutdownServer
()¶ Shutdown the server the manager is currently connected to.
-
LogViewer Interface¶
-
class
qrenderdoc.
LogViewer
¶ An interface implemented by any object wanting to be notified of capture events.
-
OnEventChanged
(eventID)¶ Called whenever the effective current event changes.
Parameters: eventID (int) – The new EID
.
-
OnLogfileClosed
()¶ Called whenever a capture is closed.
-
OnLogfileLoaded
()¶ Called whenever a capture is opened.
-
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
EID
that was actually selected, which will usually but not always be the same as the current effectiveEID
.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 EID
.
-
Utilities¶
-
class
qrenderdoc.
DockReference
¶ 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.
-
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.
-
ConstantBufferArea
¶ The new dock window is docked with other constant buffer views, if they exist, or to the right of the existing window if there are none open.
-
-
class
qrenderdoc.
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.
-
CmdLine
¶ The command line to pass when running
Exectuable
.
-
Environment
¶ A
list
ofEnvironmentModification
with environment changes to apply.
-
Executable
¶ The path to the executable to run.
-
Inject
¶ True
if the described capture is an inject-into-process instead of a launched executable.
-
Options
¶ The
CaptureOptions
with fine-tuned settings for the capture.
-
WorkingDir
¶ The path to the working directory to run in, or blank for the executable’s directory.
-