RenderDoc Python 脚本入门：在 UI 中编写并运行你的第一个自动化分析脚本

开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载本文是 RenderDoc 内置 Python 脚本能力的零基础实战指南。围绕官方教程docs/python_api/first_steps.rst与配套脚本docs/python_api/first_steps.py你将学会如何打开 Python Scripting 面板、借助预置全局变量pyrenderdoc访问当前捕获与事件信息、查询管线颜色输出与深度目标并在 REPL 与输出面板之间完成交互式调试。读完本文你将掌握用 Python 快速巡检任一捕获文件的核心套路为后续编写一键式 UI 扩展与自动化分析脚本打下基础。打开 Python Scripting 面板在 RenderDoc 主界面中通过菜单Window→Python Scripting即可打开 Python 脚本面板。这是所有脚本工作的入口无论是临时执行一段分析代码还是编辑、加载、运行保存的脚本文件都在这里完成。面板由三个核心区域组成与源码qrenderdoc/Windows/PythonShell.cpp中PythonShell类的实现一一对应主区域脚本编辑器一个多标签的代码编辑器支持编写 Python 代码、加载和保存脚本、一键运行。编辑器内置语法检查与自动补全autocomplete源码中通过doSyntaxCheck()定时器与m_SyntaxCheckTimer实现延迟语法检查并在退出自动补全后触发避免在用户编辑过程中打扰输入。左侧项目浏览器展示最近加载过的文件、已安装的 UI 扩展UI extensions以及若干随 RenderDoc 预置的示例脚本可直接加载并运行。底部交互式 REPLread-evaluate-print loop可以逐行交互式地执行 Python 语句同区域还有标签页分别展示脚本的文本输出、错误信息以及帮助信息。源码中对应的replGroup标题即为 Interactive REPL。运行脚本时脚本内print()语句的输出会被送往底部输出面板如果该面板当前处于隐藏状态运行脚本时会自动显示。Python 异常同样会打印到该输出面板。你的第一个脚本巡检当前事件与输出目标打开任意一个捕获文件例如一个 Vulkan 捕获然后编写下面这段脚本。你可以直接复制粘贴也可以逐字敲一遍以体验编辑器实时提供的自动补全信息。这段代码同样以Tutorial: First Steps with Python为名预置在项目浏览器的Examples部分加载即可运行。if not pyrenderdoc.IsCaptureLoaded(): filename pyrenderdoc.Extensions().OpenFileName(Choose a capture, , *.rdc) pyrenderdoc.LoadCapture(filename, renderdoc.ReplayOptions(), filename, False, True) eid pyrenderdoc.CurEvent() name pyrenderdoc.GetEventBrowser().GetEventName(eid) print(fCurrently we are at EID {eid} named: {name}) if eid 1: prevname pyrenderdoc.GetEventBrowser().GetEventName(eid - 1) print(f the previous event {eid-1} is named: {prevname}) pipe pyrenderdoc.CurPipelineState() outputs pipe.GetOutputTargets() for idx, out in enumerate(outputs): if out.resource ! renderdoc.ResourceId.Null(): name pyrenderdoc.GetResourceName(out.resource) print(fOutput {idx} is: {name}) depth pipe.GetDepthTarget() name pyrenderdoc.GetResourceName(depth.resource) print(fDepth is: {name})点击Run之后输出窗口会得到类似下面的结果Currently we are at EID 9408 named: vkCmdDrawIndexed(123, 2) the previous event 9407 is named: vkCmdBindDescriptorSets(1, { Descriptor Set 692529 }) Output 0 is: 2D Color Attachment 690491 Output 1 is: 2D Color Attachment 690493 Output 2 is: 2D Color Attachment 690496 Output 3 is: 2D Color Attachment 690498 Output 4 is: 2D Color Attachment 690500 Depth is: 2D Depth Attachment 690502逐段拆解理解背后的 APIpyrenderdocUI 侧 API 的入口在 RenderDoc UI 中运行脚本时存在一个预填充的全局变量pyrenderdoc它是访问 API 的入口。该变量是qrenderdoc.CaptureContext的实例完整成员见 API 参考qrenderdoc 主接口提供当前事件、加载/关闭捕获等通用数据也持有事件浏览器等面板的句柄。这一点在源码中有直接印证qrenderdoc/Windows/PythonShell.cpp的PythonShell::scriptHeader()在启动控制台时打印的提示文本明确写道The pyrenderdoc object is the current CaptureContext instance. The renderdoc and qrenderdoc modules are available.也就是说脚本环境中renderdoc与qrenderdoc两个模块都已预先导入renderdoc是底层核心 API对应docs/python_api/renderdoc/index.rstqrenderdoc是 UI 专用接口。脚本中可以直接使用而无需import不过为了在 VS Code 等外部 IDE 中获得正确的自动补全与类型检查官方示例仍会在文件头部加上一段前置声明参见 Python FAQ为什么示例带有 pyrenderdoc 前置声明# these imports are not strictly necessary, but are convenient import renderdoc import qrenderdoc # this is here to give autocomplete when editing the example # in VS Code where it doesnt know about this global from typing import TYPE_CHECKING if TYPE_CHECKING: pyrenderdoc qrenderdoc.CaptureContext()这段代码在真实运行时什么都不做TYPE_CHECKING在运行时为False仅用于让 IDE 的静态检查器认识pyrenderdoc的类型。确保有捕获文件可分析if not pyrenderdoc.IsCaptureLoaded(): filename pyrenderdoc.Extensions().OpenFileName(Choose a capture, , *.rdc) pyrenderdoc.LoadCapture(filename, renderdoc.ReplayOptions(), filename, False, True)脚本的第一步是检查当前是否已加载捕获IsCaptureLoaded()返回布尔值若未加载则通过Extensions().OpenFileName()弹出文件选择对话框标题为 Choose a capture过滤*.rdc文件随后用LoadCapture()加载该文件。注意LoadCapture需要传入renderdoc.ReplayOptions()——一个用于控制回放行为的配置对象默认构造即可其余参数依次为文件名、以及控制加载方式与是否显示日志等标志。查询当前事件及其名称eid pyrenderdoc.CurEvent() name pyrenderdoc.GetEventBrowser().GetEventName(eid) print(fCurrently we are at EID {eid} named: {name}) if eid 1: prevname pyrenderdoc.GetEventBrowser().GetEventName(eid - 1) print(f the previous event {eid-1} is named: {prevname})pyrenderdoc.CurEvent()返回当前事件 IDEIDEvent ID。关于事件 ID 的语义参见 事件 ID 详解捕获内的事件都被分配整型 EID捕获中第一个真实事件的 EID 为 1EID 0 表示第一个事件发生之前的那个时刻。绘制draw、分发dispatch、拷贝copy等动作也都是事件同样获得 EID。EID 通常与应用的函数调用一一对应但并不保证例如多绘制multi-draw或间接执行中一次 CPU 侧函数调用可能对应多个 GPU 事件因此会产生多个 EID。而 当前事件 的含义参见 当前帧事件RenderDoc 中所有信息纹理/缓冲区内容、管线状态等都反映在某个虚拟时刻——即 GPU 上某个事件执行完毕之后的瞬间。当前事件就是该时刻所在的位置其 EID 由CurEvent()给出。当选中一个包含大量子事件的标记区域marker region时selected 事件是该区域的根事件而 current 事件是区域内最后一个子事件执行完毕后的有效事件。拿到 EID 后pyrenderdoc.GetEventBrowser()返回qrenderdoc.EventBrowser其GetEventName(eid)可查询事件的格式化名称例如vkCmdDrawIndexed(123, 2)。读取管线状态与输出目标pipe pyrenderdoc.CurPipelineState() outputs pipe.GetOutputTargets()CurPipelineState()返回renderdoc.PipeState这是对当前管线状态的一个子集的抽象屏蔽了底层 APIVulkan / D3D11 / D3D12 / OpenGL 等的差异对所有捕获都可用。它并不覆盖所有状态——尤其是各 API 之间差异较大的部分——但对简单用法非常方便。PipeState.GetOutputTargets()返回颜色输出目标列表。需要特别注意的是某些 API 拥有固定数量的输出槽位且可能稀疏填充因此该列表中可能包含未绑定的资源。脚本中通过out.resource ! renderdoc.ResourceId.Null()跳过未绑定项ResourceId.Null()是空资源 ID 的哨兵值资源 ID 的详细说明见 资源 ID再调用pyrenderdoc.GetResourceName(out.resource)把资源 ID 翻译成可读名称打印出来for idx, out in enumerate(outputs): if out.resource ! renderdoc.ResourceId.Null(): name pyrenderdoc.GetResourceName(out.resource) print(fOutput {idx} is: {name})这里enumerate()是 Python 内置函数对列表中的每个元素返回(下标, 元素)成对结果从而在打印时同时给出输出槽位索引与资源名称。深度目标用同样的机制单独查询并打印depth pipe.GetDepthTarget() name pyrenderdoc.GetResourceName(depth.resource) print(fDepth is: {name})输出面板、异常与sys.exit()脚本运行期间print()的内容会送到底部输出面板面板隐藏时会自动弹出未捕获的 Python 异常同样打印到该面板。一个常见疑问是脚本中途退出在 UI 中运行脚本时调用sys.exit()是安全的它只会中止当前脚本而不会关闭 RenderDoc 本身。这一点与命令行模式有重要区别——参见 Python FAQ以--py path/to/script.py启动 RenderDoc UI脚本会在初始化早期、UI 创建并显示之前执行可用于无头headless执行或批处理此场景下调用sys.exit()会导致 RenderDoc 进程退出。以--ui-py path/to/script.py启动则会等 UI 显示后打开 Python 脚本窗口并把指定脚本作为新标签页加载运行。编写脚本时的几个实用提醒结合 Python FAQ 与源码行为初学时值得注意以下几点API 是 C 的薄封装错误校验有限。RenderDoc 的 Python 绑定是对 C API 的轻量包装传入语义无效的数据例如把纹理的 ResourceId 传给期望着色器的函数可能导致崩溃或数据损坏脚本中不应依赖健壮的错误检查。注意对象生命周期。Python 引用计数与 C 对象生命周期不一定一致捕获关闭后即使 Python 仍持有句柄底层 C 对象可能已被清理继续使用可能导致崩溃。常见场景是缓存了关闭前的捕获信息。部分对象只读不可修改。大多数返回给 Python 的列表与对象是拷贝、可自由修改但ShaderReflection、捕获的ActionDescription其兄弟/子节点按引用关联、以及SDFile中的SDObject与缓冲区是按引用返回的修改这些对象可能破坏内部数据甚至导致崩溃。REPL 中对象预览不友好时可使用renderdoc.DumpObject。直接打印对象可能得到Swig Object of type FooBar * at 0x...这类无意义输出用DumpObject(obj)可以展示结构体的属性内容。调试器集成RenderDoc 支持 VS Code 调试但需按 IDE 集成指南 配置注意 RenderDoc 只监听一个固定端口多个 UI 实例同时打开时只有第一个能调试 Python 代码。从一次性脚本走向 UI 扩展本文只是 5 分钟的极简入门pyrenderdocCaptureContext上下文中还有大量能力没有展开你可以通过浏览 Python API 文档 或直接在编辑器中体验自动补全来探索。接下来推荐两条进阶路径阅读示例库查看 Python 示例索引 中预置的show_buffer、show_texture、iter_actions、pipe_state、mesh_output、event_filter等示例它们覆盖了常见的分析工作流缓冲区查看、纹理查看、动作遍历、网格输出、事件过滤等每个示例的源码都可从脚本面板的Examples部分直接加载运行。编写 UI 扩展如果不想每次都手动打开并运行脚本下一步就是创建一个 UI 扩展——在扩展目录Windows 为%APPDATA%\qrenderdoc\extensionsLinux 为~/.local/share/qrenderdoc/extensions下通过extension.json与__init__.py注册即可把脚本固化为一键可用的界面功能。完整的开发流程见 UI 扩展教程 与 深入话题覆盖回放控制器、远程回放、结构化数据、shader 反射等。如果你需要脱离 UI、在独立 Python 解释器中加载renderdoc模块做最底层的自动化控制可以参考 手动使用 Python 模块——不过官方明确提示这是高级用法编写脚本或扩展定制 UI 并不需要它。以上所有脚本行为均可在本仓库源码中验证面板实现位于 qrenderdoc/Windows/PythonShell.cpppyrenderdoc全局变量的来源与说明见其中的scriptHeader()约第 2419-2426 行完整教程原文与配套脚本分别位于 docs/python_api/first_steps.rst 与 docs/python_api/first_steps.py。赞分享开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载相关推荐Tampermonkey脚本编写入门从零开始创建你的第一个用户脚本Tampermonkey用户脚本管理器是全球最受欢迎的浏览器扩展之一拥有超过1000万用户。它能让你轻松创建和管理自定义脚本为任何网页添加个性化功能。无论你前端插件系统Nextflow入门指南编写你的第一个数据处理脚本Nextflow入门指南编写你的第一个数据处理脚本 前言 Nextflow是一个强大的工作流框架专为数据密集型计算而设计。它结合了DSL领域特定语言的强Vue3-Vant-Mobile一站式移动端H5应用开发解决方案Vue3 Vant Mobile一站式移动端H5应用开发解决方案 在移动互联网时代如何快速构建高质量的H5应用是前端开发者和产品经理面临的核心挑战。传统移动前端示例工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考