RenderDoc Python API 完整指南:脚本自动化、UI 扩展与 IDE 调试实战

原创2026-09-23 15:49:141,631 阅读
文章标签:调试器图形学开发工具

RenderDoc Python API 完整指南:脚本自动化、UI 扩展与 IDE 调试实战

导读

RenderDoc 将内部 C++ API 直接封装暴露给 Python,使其成为一款可深度脚本化、可个性化定制的图形调试工具——UI 中看到的任何功能都能以某种方式通过 Python 触达,UI 本身的大量组件也可编程访问。本篇指南以 docs/python_api/index.rst 为主线,系统讲解三大核心场景:在 UI 内编写并运行脚本(First Steps)、把脚本固化为可持久加载的 UI 扩展(UI Extensions)、以及通过外部 IDE(如 VS Code)获得完整补全与断点调试能力。读完后你将能独立完成"打开捕获 → 遍历事件与管线状态 → 自动化分析 → 注册菜单与自建面板 → 外部调试"的完整技术闭环。

一、Python API 全景:两套模块,一条主线

RenderDoc 的 Python 能力分为两个层次,理解二者的边界是使用一切 API 的前提:

  • renderdoc 模块:底层核心接口,即 UI 本身构建其上的那套 API 的 Python 封装。涵盖捕获(capturing)、重放(replay)、输出(outputs)、分析(analysis)、资源(resources)、着色器(shaders)、管线(pipelines)、结构化数据(structured_data)、计数器(counters)与帧统计(frame_stats)等,参考 renderdoc 模块索引。
  • qrenderdoc 模块:UI 专属接口,面向界面集成与扩展开发,提供窗口(windows)、扩展注册(extensions)、配置(config)与主流程控制(main),参考 qrenderdoc 模块索引。

两条主线贯穿所有文档:

  1. 脚本(Scripting):在 UI 内置的 Python 脚本面板中运行的一次性脚本,适合临时分析与自动化;
  2. 扩展(Extensions):以 extension.json + __init__.py 形式持久化注册的 Python 模块,随 UI 启动自动加载,适合日常长期使用。

从源码结构看,UI 脚本环境由 qrenderdoc/Code/pyrenderdoc 下的 SWIG 绑定实现,示例脚本与完整教程代码可在 docs/python_api/examples 中找到,而 renderdoc 底层核心对应的 C++ 入口集中在 renderdoc/replay 与 renderdoc/api/replay。

二、第一个脚本:在 UI 内读取当前事件与输出目标

2.1 打开 Python 脚本面板

从菜单 Window → Python Scripting 打开脚本面板。主区域是脚本编辑器,支持编写、加载、保存与运行 Python 代码;左侧是项目浏览器,展示最近打开的文件、UI 扩展以及预置示例;底部是交互式 REPL(可逐行执行 Python)、输出/错误标签页与帮助信息。

Python 脚本面板首次打开时的界面

2.2 环境全局变量:pyrenderdoc

在 RenderDoc UI 中运行脚本时,会预置一个全局变量 pyrenderdoc,它是 qrenderdoc.CaptureContext 的实例,是访问 API 的入口,提供当前事件、管线状态以及事件浏览器等面板句柄。

2.3 完整示例脚本

先打开任意一个捕获文件,然后运行以下脚本(同样可在项目浏览器的 Examples 中找到 Tutorial: First Steps with Python,源码见 first_steps.py):

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(f"Currently 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(f"Output {idx} is: {name}")

depth = pipe.GetDepthTarget()

name = pyrenderdoc.GetResourceName(depth.resource)
print(f"Depth 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

2.4 逐段拆解

① 加载捕获(若未打开):IsCaptureLoaded() 判断当前是否已有捕获;否则通过 Extensions().OpenFileName 弹出文件选择框(过滤 *.rdc),再用 LoadCapture(filename, renderdoc.ReplayOptions(), filename, False, True) 加载。ReplayOptions 是重放配置的默认值,可后续按需定制。

② 查询当前事件:CurEvent() 返回当前事件 ID(EID,整数);用 GetEventBrowser().GetEventName(eid) 获取该事件的格式化名称(如 vkCmdDrawIndexed(123, 2))。事件 ID 的详细语义参见 事件 ID 深入讲解,当前事件的概念参见 curevent。

③ 读取管线输出:CurPipelineState() 返回 renderdoc.PipeState,这是对当前管线状态子集的跨 API 抽象,与捕获所用图形 API 无关(不覆盖所有状态,尤其 API 间存在差异的部分,但适合常规用法)。GetOutputTargets() 获取颜色输出目标列表;GetDepthTarget() 获取深度目标。

④ 资源名解析与判空:由于部分 API 输出槽位固定且可能稀疏,需用 out.resource != renderdoc.ResourceId.Null() 跳过未绑定的槽位;GetResourceName(resource) 将 Resource ID 解析为人可读名称(如 2D Color Attachment 690491)。Resource ID 的完整机制见 resourceids。

⑤ 输出与异常:print() 的输出发送到输出面板,面板隐藏时会自动弹出;Python 异常同样打印到此面板。sys.exit() 可以安全地中止脚本,不会关闭 RenderDoc 本身。

三、UI 扩展:把脚本固化为常驻功能

一次性脚本适合快速验证,而 UI 扩展 更适合日常使用:它以磁盘上的 Python 模块形式存在,随 UI 启动自动加载,并可注册菜单项、创建自定义面板。

3.1 扩展的存储位置与目录结构

扩展位于用户配置目录下(平台相关):

  • Windows:%APPDATA%\qrenderdoc\extensions
  • Linux:~/.local/share/qrenderdoc/extensions

扩展本质是位于该根目录下的 Python 模块子文件夹,且支持嵌套:extensions/foo/bar/first 对应模块 foo.bar.first,与 extensions/foo/bar/second 相互独立。每个模块需要两个文件:

  • __init__.py:Python 模块主体,必须包含全局函数 register;
  • extension.json:清单文件(元数据 + 兼容性约束)。

3.2 extension.json 清单

清单模板(完整字段说明参见 如何注册 Python 扩展):

{
    "extension_api": 1,
    "name": "Extension name for users",
    "version": "1.0",
    "minimum_renderdoc": "1.2",
    "description": "A longer description of your extension.\n\nIt can contain multiple lines",
    "author": "Your name <your@email.com>",
    "url": "url/to/repository"
}
  • extension_api:当前固定为 1,是唯一必填字段;其余字段省略时使用默认值,但建议填全。
  • minimum_renderdoc:控制扩展可在哪个 RenderDoc 版本上启用,用于屏蔽不兼容版本。
  • name、description、version、author、url:均为展示性信息,会呈现给用户。
  • 缺少 extension.json 的模块不会被 RenderDoc 枚举和展示。

3.3 创建与启用扩展

快速创建:在 Python 脚本窗口的项目侧栏中,双击 UI Extensions 下的 Create New...(或右键该节标题选择对应菜单),在弹出的对话框中输入包名(如 tutorialext),RenderDoc 会自动生成 extension.json 与 __init__.py。

启用:通过 Tools → Manage Extensions 打开扩展管理器,勾选目标扩展的 Enable 列即可加载。默认扩展不启用;由于 Python 模块无法卸载,取消勾选后需重启 RenderDoc 才会真正禁用。扩展文件在磁盘上被修改后,可在 Python 脚本窗口或状态栏中重新加载(reload);若涉及回调、打开的 UI 或已注册处理器等持久化代码,重载可能不稳定,此时建议重启 RenderDoc 保证干净加载。

扩展管理器:配置已安装的扩展

3.4 register 入口与生命周期

扩展加载(或重载)时,模块中必须存在全局函数 register,签名如下:

def register(version, pyrenderdoc):
    # version 是 RenderDoc Major.Minor 版本字符串,如 "1.2"
    # pyrenderdoc 是 CaptureContext 句柄,与 UI 内全局变量相同

可选定义 unregister()(无参数),在扩展被重载时先执行清理,再调用 register。

3.5 实战示例:注册菜单并创建"寻宝"面板

以下完整代码可在 Examples 的 Tutorial: UI extension 中找到(需复制进你的 __init__.py 才能运行),源码见 ui_extensions.py:

import renderdoc as rd
import qrenderdoc as qrd
from typing import List


def check_draw(best_size: int, action: rd.ActionDescription):
    if action.flags & rd.ActionFlags.Drawcall:
        size = action.numIndices * action.numInstances
        if size > best_size:
            return action.eventId, size
    return 0, 0


def find_largest_draw(best_size: int, actions: List[rd.ActionDescription]):
    ret = 0
    for action in actions:
        result = check_draw(best_size, action)

        if result[0] == 0:
            result = find_largest_draw(best_size, action.children)

        if result[0] > 0:
            ret, best_size = result

    return ret, best_size


def open_window(pyrenderdoc: qrd.CaptureContext, data):
    mqt = pyrenderdoc.Extensions().GetMiniQtHelper()

    top = mqt.CreateToplevelWidget("Scavenger Hunt")

    group = mqt.CreateGroupBox(False)
    mqt.SetWidgetText(group, "Exciting scavenger hunt!")

    label = mqt.CreateLabel()
    mqt.SetWidgetText(label, "Guess the biggest draw!")

    eid, size = find_largest_draw(0, pyrenderdoc.CurRootActions())

    def do_guess(pyrenderdoc, widget, text):
        print(f"Spoiler: largest draw is {eid}, it drew {size} indices")

        if pyrenderdoc.CurEvent() == eid:
            msg = "You found it!"
        elif pyrenderdoc.CurEvent() < eid:
            msg = "The largest draw is later in the capture..."
        else:
            msg = "The largest draw is earlier in the capture..."

        mqt.SetWidgetText(label, f"Guess the biggest draw!\n\n{msg}")

    button = mqt.CreateButton(do_guess)
    mqt.SetWidgetText(button, "Guess")

    if eid == 0:
        mqt.SetWidgetText(
            label,
            "You don't have a capture with drawcalls loaded :(.\n"
            "Re-open this window after opening a capture!",
        )
        mqt.SetWidgetEnabled(button, False)

    mqt.AddWidget(top, group)
    mqt.AddWidget(group, label)
    mqt.AddWidget(group, button)

    pyrenderdoc.AddDockWindow(
        top, qrd.DockReference.TopOf, pyrenderdoc.GetEventBrowser().Widget(), 0.2
    )


def register(version, pyrenderdoc: qrd.CaptureContext):
    print(f"Tutorial extension registered in RenderDoc {version}")

    pyrenderdoc.Extensions().RegisterPanelMenu(
        qrd.PanelMenu.EventBrowser, ["Tutorial", "Scavenger Hunt"], open_window
    )

3.6 逐段拆解:从菜单到面板的完整链路

  • 注册菜单项:RegisterPanelMenu(qrd.PanelMenu.EventBrowser, ["Tutorial", "Scavenger Hunt"], open_window) 在事件浏览器工具栏注册带子菜单结构的菜单项,点击时回调 open_window。PanelMenu 枚举还提供其他可注册菜单位置,可自行探索。
  • 获取 MiniQtHelper:Extensions().GetMiniQtHelper() 返回 qrenderdoc.MiniQtHelper——RenderDoc 提供的简化 UI 构建 API。虽然 RenderDoc 通常内置 PySide 提供的完整 Qt 绑定(qrenderdoc 模块可访问),但完整 Qt API 复杂,简单 UI 用 MiniQtHelper 更高效。
  • 创建窗口与控件:CreateToplevelWidget("Scavenger Hunt") 创建顶层窗口(其标题为 Scavenger Hunt);CreateGroupBox(False)、CreateLabel()、CreateButton(callback) 分别创建分组框、标签与按钮;SetWidgetText 设置文本,SetWidgetEnabled 控制可用性。
  • 回调参数约定:交互控件的回调统一为 WidgetCallback(context: qrenderdoc.CaptureContext, widget, text) 形式——第一个参数是 CaptureContext,widget 是触发事件的控件,text 随事件类型不同提供当前或选中文本等上下文信息;回调可选,且创建后不能增删。
  • 布局:控件按"容器递归"方式排布——垂直容器(CreateVerticalContainer)、水平容器(CreateHorizontalContainer)与网格容器(CreateGridContainer);AddWidget 用于垂直/水平容器,AddGridWidget 用于网格。顶层窗口与分组框默认自带隐式垂直容器,因此可直接 AddWidget。详见 Mini-Qt Helper 深入讲解。
  • 生命周期:控件句柄由 Python 持有但具有显式生命周期——顶层面板被用户关闭或调用 CloseToplevelWidget 时会递归销毁所有子控件;未挂载的控件须用 DestroyWidget 显式销毁。关闭后遗留的句柄不可再访问。详见 生命周期管理。
  • 接入停靠系统:AddDockWindow(top, qrd.DockReference.TopOf, pyrenderdoc.GetEventBrowser().Widget(), 0.2) 将顶层控件加入 RenderDoc 的停靠(docking)系统,停靠在事件浏览器上方、占 20% 空间。任何控件都可作为新顶层停靠面板,但官方建议使用显式顶层控件以便捕获其关闭回调。

扩展添加的按钮与新窗口

编辑 __init__.py 后,状态栏会提示文件已变更,点击状态栏按钮即可重载扩展:

状态栏提示扩展已修改

四、IDE 集成:VS Code 补全、Stubs 与断点调试

RenderDoc 内置的脚本环境不如专业 IDE 强大,因此官方支持外部 IDE 集成——既能获得完整自动补全,还能设置断点、单步调试 UI 内运行的 Python 代码。

4.1 VS Code 快速配置

VS Code 开箱即可用于简单代码编辑;要获得完整调试与补全,按以下步骤配置(以 VS Code 为例,PyCharm 等工具亦可参考):

  1. 安装 pylance 与 debugpy 扩展(Python 官方元扩展会自动安装二者)。
  2. 打开设置(Ctrl-,):
    • 将 RenderDoc stubs 目录加入 Extensions → PyLance → Extra Paths(@id:python.analysis.extraPaths);
    • 禁用 Extensions → Python Debugger → Just my code(@id:debugpy.debugJustMyCode);
    • (可选)启用 Features → Tasks → Allow Automatic Tasks(@id:task.allowAutomaticTasks);
    • 调试时启用 Run and Debug 侧栏底部的 Breakpoints → User Uncaught Exceptions。
  3. 若刚安装调试扩展,需重启 RenderDoc UI 使其被发现。之后可在 Python 脚本面板点击 Attach External Debugger 按钮调试 Python 代码。

stubs 目录位置(平台相关):Windows 为 %APPDATA%\qrenderdoc\pystubs\latest,Linux 为 ~/.local/share/qrenderdoc/pystubs/latest。settings.json 形如:

{
    "python.analysis.extraPaths": [
        "C:\\users\\baldurk\\appdata\\roaming\\qrenderdoc\\pystubs\\latest"
    ],
    "debugpy.debugJustMyCode": false,
    "task.allowAutomaticTasks": "on"
}

4.2 Python Stubs:补全的基石

RenderDoc 的模块由 C 编写,无法携带 IDE 所需类型注解。标准替代方案是提供 stub 文件——纯 Python 编写、只有签名与类型注解、无实现体。RenderDoc 会在应用数据目录(Windows %APPDATA%\qrenderdoc\pystubs,Linux ~/.local/share/qrenderdoc/pystubs)下为每个版本生成一套 stubs,另有滚动更新的 latest 版本。日常开发直接用 latest 即可;若针对特定版本,可改用带版本号的目录。配置完成后,任何 import renderdoc / import qrenderdoc 的脚本都会获得完整补全。

4.3 Python 调试:debugpy 与端口 5678

RenderDoc 通过集成 debugpy(常见的远程调试库)让外部调试器连接并调试 UI 内的 Python 代码:

  • 若 VS Code 安装在标准位置且安装了 ms-python.debugpy,RenderDoc 首次启动会自动加载并初始化 debugpy;找不到 VS Code 时尝试从 PyCharm 安装目录加载,也可自定义 debugpy 路径。
  • 刚装扩展后需重启 RenderDoc。
  • debugpy 就绪后,调试器默认监听本地端口 5678。在 VS Code/IDE 中配置 "remote attach" 连接 localhost:5678 即可。
  • RenderDoc 检测到 VS Code 后,脚本中按 Attach External Debugger 会自动以必要环境启动 VS Code;若启用 Allow Automatic Tasks 会在启动时自动连接调试器。
  • 重要:RenderDoc 的调试连接是单例的——同一时刻只能有一个 IDE/调试器连接,且多个 UI 实例时仅第一个启动的实例可被连接。附加动作须从 IDE 侧发起;UI 内的按钮只是启动 IDE 并可能触发其立即连接,并非必须。
  • 注意:若从源码构建,默认基于 Python 3.6(不支持调试),需按 自定义 Python 版本 一节改用更新版本,或直接使用官方发布版(基于 Python 3.8)。

4.4 常见陷阱:路径映射与"Just My Code"

  • 路径映射(path mappings):RenderDoc 默认会创建 .vscode/launch.json 配置附加调试,但不会覆盖已存在的文件。VS Code 默认的远程附加配置含 "path mappings",而同机同路径调试时会导致 RenderDoc 调试失效(表现为文件重复打开新标签、断点不生效)。强烈建议删除所有路径映射,并在重新附加前重启 RenderDoc 与 VS Code。
  • "Just My Code":由于 RenderDoc 的 Python 集成方式特殊,VS Code 可能认为脚本不属于项目,因此务必禁用 debugpy 的 Just my code。
  • 未捕获异常:RenderDoc 自身会捕获未处理异常以提升 UI 稳定性,因此需在 Breakpoints 中启用 User Uncaught Exceptions,VS Code 才能正确拦截异常。

五、命令行脚本执行与进阶场景

5.1 --py 与 --ui-py

部分工作流需要从命令行运行脚本,RenderDoc UI 提供两种方式:

  • --py path/to/script.py:在初始化早期、UI 创建显示之前运行脚本,适合无头执行与批量处理。与 UI 内运行不同,此类脚本中调用 sys.exit() 会使整个 RenderDoc 进程退出。
  • --ui-py path/to/script.py:等待 UI 显示后,打开 Python 脚本窗口并以新标签页加载运行指定脚本。

5.2 示例集合与深入专题

项目浏览器 Examples 中预置了大量可直接加载运行的示例,对应源码位于 docs/python_api/examples,覆盖常见工作流:

所有示例共用一个 preamble(用于外部 IDE 的类型提示,见 FAQ 中对应条目):

# 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 doesn't know about this global
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    pyrenderdoc = qrenderdoc.CaptureContext()

原理:TYPE_CHECKING 仅在类型检查器(如 IDE)中为 True、实际执行时为 False,从而在不影响运行的前提下为 pyrenderdoc 标注正确的 CaptureContext 类型(该类型无法从 Python 创建,直接执行会失败)。示例还普遍带有"检查捕获是否打开、未打开则提示选择"的前置逻辑,与 first_steps.py 开头一致。

深入专题参见 in_depth/index:资源 ID、事件 ID、当前事件、帧观察者回调(frame_viewers,可在捕获加载/关闭或事件选择时获得回调)、ReplayController(底层 API 的主入口)、线程模型、生命周期、着色器反射、描述符与绑定、结构化数据、MiniQt、输出、捕获访问、程序启动与远程重放。

六、常见问题(FAQ)要点

  1. 脚本崩溃:Python 绑定是 C++ API 的薄封装,向 API 传递语义非法数据(如把纹理 ID 传给期望着色器 ID 的函数)可能直接崩溃,Python API 不做健壮错误检查;持有指向已删除 C++ 对象的 Python 引用(如捕获关闭后的缓存信息)也可能崩溃。此类问题通常需自查脚本,除非能用纯 UI 复现,否则不应归为 RenderDoc 缺陷。

  2. REPL 中对象预览不友好:临时对象可能显示 <Swig Object of type 'FooBar *' at 0x...>,这是绑定生成方式所致;对含属性的结构体可用 renderdoc.DumpObject 获得更可读的预览。

  3. 新建面板看不到:为避免 UI 抖动,新创建的 BufferViewer、ShaderViewer 等非单例面板不会自动显示,必须调用 AddDockWindow 将其挂入 UI 层级。

  4. API 兼容性:Python API 目前未锁定,各版本间可能有破坏性变更(重命名、删除成员或改变成员含义);结构体新增成员或类新增方法不影响现有脚本。每个版本 release notes 会列出 Python 破坏性变更,建议面向最新版本编写脚本。

  5. UI 定制权限:底层 renderdoc 模块自动暴露全部能力(UI 与 Python 使用同一 API);qrenderdoc 模块则编写得更保守,避免暴露大量未用功能。若需要 UI 中尚不可编程访问的功能,可提交 feature request,按需开放。

  6. C++ 直接使用这些 API:可以但不推荐且不受支持。Python 因不依赖 ABI 而能容忍结构体重排/新增成员;C++ 则需承受全部 ABI 变更。

  7. 数据修改边界:多数情况下返回的列表与对象是拷贝,归 Python 所有可自由修改;但有例外——ShaderReflection 对象、ActionDescription 的相邻/子节点引用、SDFile 的 SDObject 与缓冲区均为引用,修改它们可能损坏内部数据甚至崩溃,不应修改。

  8. Android:理论上脚本重放与平台无关,但因 Android 平台本身的不稳定性,Python 脚本与 Android 捕获组合不被官方支持,如需使用需谨慎。

七、脱离 UI 使用 Python 模块(高级用法)

除 UI 内嵌运行时外,还可在独立 Python 解释器中以普通模块方式加载 renderdoc 模块(qrenderdoc 因依赖 UI 不可独立加载)。此用法属于高级场景,写普通脚本或扩展并不需要,完整说明见 python_module。

7.1 构建与版本匹配

RenderDoc 默认不随发布包附带可导入解释器的 Python 模块,因为绑定与特定 Python 主次版本强绑定。需自行从源码构建:

  • 构建成功后模块位置依平台而异:Windows 为避免文件名冲突位于 pymodules 子目录;Linux 输出到 lib 目录下的 renderdoc.so。
  • 模块默认针对构建时的 Python 版本编译(Linux 取决于系统版本;Windows 为源码捆绑的 Python 3.6),只能在该版本中安全加载。

7.2 指定 Python 版本

  • Windows:在 Visual Studio 工程中,qrenderdoc、pyrenderdoc_module、qrenderdoc_module 各自的 Python Configuration 属性页指定解释器路径。RenderDoc 还需标准库 zip 包(python3.xx.zip,类似官方 "embeddable package")。可用源码树中的 util/make_python_lib_zip.py 从解释器自身将 Lib/ 编译为 zip 放到 python.exe 旁。构建成功提示形如 Built against python from C:\Python314;失败则回退到捆绑 Python 3.6 并给出缺失项提示(如 Python.h、pythonMAJMIN.zip、pythonMAJMIN.lib)。
  • Linux:CMake 3.12+ 可用 -DFORCE_PY_VERSION=3.xx 强制指定版本,配置阶段会打印实际使用的 Python 版本。

7.3 加载模块与核心库依赖

模块只是薄封装,依赖 RenderDoc 核心库:

  • Windows:核心库需在 PATH 中;Python 3.8+ 还需调用 os.add_dll_directory 指向 renderdoc.dll 所在目录。缺失时报 ImportError: DLL load failed while importing renderdoc: The specified module could not be found.
  • Linux:模块带 RUNPATH 指向自身位置,核心库 librenderdoc.so 通常同目录即可加载;移动后可设置 LD_LIBRARY_PATH,否则报 ImportError: librenderdoc.so: cannot open shared object file: No such file or directory。

7.4 直接使用 API 的必备初始化

UI 通常代为处理初始化,独立使用时必须显式管理:

import renderdoc

renderdoc.InitialiseReplay()   # 任何其他 API 调用前必须调用一次
# ... 执行捕获/重放/分析 ...
renderdoc.ShutdownReplay()     # 进程结束前调用

初始化前或关闭后的任何 API 调用均非法,关闭后不可再次初始化。仓库 util/test 下的自动化测试脚本全部由 Python 编写,演示了捕获、重放与分析全流程的直接模块用法。

八、推荐学习路径

  1. 先按 first_steps.py 在 UI 中跑通第一个脚本,理解 pyrenderdoc 入口;
  2. 阅读 examples 中的示例,覆盖各常见工作流;
  3. 按 ui_extensions.py 创建你的第一个 UI 扩展,将脚本固化为常驻功能;
  4. 按 ide_integration.rst 配置 VS Code,获得补全与断点调试能力;
  5. 编写复杂脚本前,通读 in_depth 专题(尤其是生命周期、线程、事件 ID 与资源 ID);
  6. 需要脱离 UI 的自动化时,参考 python_module 手动构建与加载模块;
  7. 遇到疑难先查 FAQ,它涵盖了崩溃、对象预览、命令行执行、兼容性等高频问题。
登录后查看全文
renderdoc