RenderDoc Python 脚本中的 Replay Output 系统：创建、配置与渲染可视化输出实战指南

• 开发工具
• 调试器
• 图形学
• GPU

导读

RenderDoc 的很多分析功能（如纹理叠加层、3D 网格预览）无法用纯文本或数据表格直观呈现，必须借助可视化输出。本文以 docs/python_api/in_depth/outputs.rst 为核心，系统讲解 RenderDoc 的replay output（重放输出）系统：如何为输出创建原生窗口或离屏缓冲区、如何通过ReplayController.CreateOutput建立输出、如何配置纹理与网格显示、如何驱动渲染刷新，以及缩略图、像素上下文、调试叠加层等进阶辅助能力。读完本文，你将掌握在 Python 脚本中从零搭建一套可交互的可视化重放输出（包括保存到图片文件）的完整方案。

什么是 Replay Output

Replay output 是 RenderDoc 在 Python 脚本中呈现分析结果的桥梁。它把"重放捕获内容"与"可视化展示"解耦：重放工作由 ReplayController 负责，而 output 负责把纹理、网格等资源渲染到指定目标上。

从 API 结构看，这一机制定义在 renderdoc/api/replay/renderdoc_replay.h 的IReplayOutput接口中，其核心能力包括：

• SetTextureDisplay/SetMeshDisplay：设置输出内容；
• Display：触发渲染刷新；
• ReadbackOutputTexture：读取渲染结果到内存字节；
• AddThumbnail/DrawThumbnail/ClearThumbnails：管理缩略图子窗口；
• SetPixelContext/SetPixelContextLocation：固定高缩放像素预览；
• GetDebugOverlayTexID/GetCustomShaderTexID：获取内部纹理 ID。

在 Python 侧，output 通过renderdoc.ReplayOutput类暴露，类型由 ReplayOutputType 枚举 决定：

class ReplayOutputType: Headless = 0 # 无窗口输出，配合 ReadbackOutputTexture 使用 Texture = 1 # 纹理、缩略图与像素上下文显示 Mesh = 2 # 网格数据预览

创建输出

窗口 / Widget 与 1:1 对应关系

Replay output 与原生窗口或 widget 是1:1 关系：每个输出绑定一个显示目标。文档特别警告：D3D12 等 API 会对原生窗口取得独占访问权，使用后该窗口无法再复用。因此建议每次用完输出后重建 widget。

如果使用 Qt 界面，qrenderdoc.MiniQtHelper.CreateOutputRenderingWidget会自动处理窗口的创建与重建，无需手动管理这一限制；对应文档见 miniqt.rst。

获取 WindowingData

要把窗口交给 RenderDoc，必须先把窗口句柄封装成WindowingData。该结构在 renderdoc/api/replay/control_types.h 中定义，内部是一个按窗口系统区分的联合体：

struct WindowingData { WindowingSystem system; union { struct { int32_t width, height; } headless; // 离屏伪窗口 struct { HWND window; } win32; // Win32 窗口 struct { Display *display; Drawable window; } xlib; // X11/Xlib struct { xcb_connection_t *connection; xcb_window_t window; } xcb; // XCB struct { wl_display *display; wl_surface *window; } wayland; // Wayland struct { ANativeWindow *window; } android; // Android 原生窗口 struct { void *view; void *layer; } macOS; // macOS 视图/图层 }; };

注：通过 SWIG 绑定导出到 Python 时，WindowingData被当作完全不透明的结构（见 control_types.h），你只需要创建并传递它，不需要也不应访问其内部字段。

获取WindowingData有两条路径：

1. Qt 环境：使用qrenderdoc.MiniQtHelper.GetWidgetWindowingData直接从 widget 获取；
2. 原生窗口：调用平台相关函数，定义于 renderdoc_replay.h：
   • renderdoc.CreateWin32WindowingData(HWND)—— Win32；
   • renderdoc.CreateXCBWindowingData(connection, window)—— XCB（Linux/X11）。

离屏渲染：CreateHeadlessWindowingData

除真实窗口外，还可以渲染到固定尺寸的离屏伪窗口。renderdoc.CreateHeadlessWindowingData(width, height)会创建一个带内部缓冲区的固定大小窗口，之后用ReplayOutput.ReadbackOutputTexture()把渲染结果读取成原始字节。典型场景是把纹理视图保存为磁盘图片文件（配合图片编码库写 PNG/JPG）。

在 GUI 应用中，headless 输出同样可以用于后台批量生成缩略图，而不需要任何可见窗口。

用 ReplayController.CreateOutput 创建输出

准备好WindowingData与ReplayController后，调用：

output = controller.CreateOutput(windowing_data, ReplayOutputType.Texture) # 或 ReplayOutputType.Mesh

对应 C++ 接口为 IReplayController::CreateOutput。创建之后必须遵循两条纪律（详见 lifetimes.rst 与 threading.rst）：

• 生命周期：output 由 controller 管理，必须只在 controller 存续期间使用；用完调用ReplayOutput.Shutdown()，或者直接ReplayController.Shutdown()（它会一并关闭其创建的所有输出，见 renderdoc_replay.h）；
• 线程：output 只能在与ReplayController相同的线程上使用，跨线程调用会破坏重放一致性。

配置输出

创建之后，根据输出类型调用对应的配置方法：

# 纹理输出 display_cfg = renderdoc.TextureDisplay() # ... 设置纹理、通道、范围等字段 ... output.SetTextureDisplay(display_cfg) # 网格输出 mesh_cfg = renderdoc.MeshDisplay() # ... 设置网格位置、变换等字段 ... output.SetMeshDisplay(mesh_cfg)

网格输出的相机设置

MeshDisplay需要指定一个相机，用renderdoc.InitCamera(CameraType)初始化。CameraType枚举定义于 replay_enums.h：

class CameraType: Arcball = 0 # 围绕原点旋转 + 缩放的球面控制 FPSLook = 1 # 传统 FPS 式控制，沿当前朝向各轴移动

两种相机的参数模型不同：

InitCamera在 C API 侧对应RENDERDOC_InitCamera（renderdoc_replay.h），返回ICamera实例，可通过修改其 position / direction / angle / distance 字段实现相机操控。

渲染输出

配置完成后，调用ReplayOutput.Display()触发重绘。何时需要调用：

• 修改配置之后：SetTextureDisplay/SetMeshDisplay之后必须手动调用一次Display让新配置生效；
• 平台需要重绘时：原生窗口因平台原因（遮挡恢复、尺寸变化等）需要重画时。

如果使用MiniQtHelper.CreateOutputRenderingWidget创建的 widget，更新会自动处理，你只需在修改配置后手动调用Display()即可，无需关心窗口自身重绘事件。

子窗口系统

对于纹理输出，常见需求是在主视图旁边显示低开销的小缩略图。Replay output 内置了子窗口管理能力。

AddThumbnail 与 ClearThumbnails

# 把另一个窗口注册为缩略图显示目标 output.AddThumbnail(thumbnail_windowing_data, texture_id, ...) # 手动释放全部缩略图（不影响主输出） output.ClearThumbnails()

要点：

• AddThumbnail传入目标窗口的WindowingData与要显示的纹理 ID；该窗口从此归 output 所有，直到输出 shutdown；
• ClearThumbnails可随时释放所有缩略图，而无需关停主 replay output 本身。

DrawThumbnail 快速预览

如果不需要持续显示的窗口，只想临时拿到缩略图数据：

raw_bytes = output.DrawThumbnail(width, height, texture_id, ...)

DrawThumbnail直接渲染并返回原始字节，适合做快速预览、列表图标或批量导出，省去创建和管理子窗口的开销。

像素上下文（Pixel Context）

像素上下文是另一个类似缩略图的辅助视图：它在另一个窗口中渲染当前纹理在指定位置的高度放大视图，常用于逐像素检查。

output.SetPixelContext(windowing_data) # 注册像素上下文窗口（归 output 所有） output.SetPixelContextLocation(x, y) # 更新放大中心位置

• 像素上下文窗口同样由 output 拥有，直到 shutdown；
• 它不需要单独驱动重绘：在主输出调用Display()时自动同步渲染；
• 显示位置通过SetPixelContextLocation随时更新（renderdoc_replay.h 注释说明：它使用SetTextureDisplay的配置，但强制高缩放值与固定位置）。

纹理输出专属辅助：内部调试纹理

对于纹理显示型输出，可以查询两个内部资源 ID（详见 resourceids.rst 关于 ID 体系的说明）：

overlay_tex_id = output.GetDebugOverlayTexID() # 当前纹理叠加层渲染结果 custom_shader_id = output.GetCustomShaderTexID() # 自定义显示着色器的输出

用途：

• GetDebugOverlayTexID：获取用于显示当前纹理 overlay（如 Drawcall、Depth、Wireframe 等叠加层，见 ReplayOutputType 相关文档 中DebugOverlay枚举）的内部纹理 ID；
• GetCustomShaderTexID：获取自定义显示着色器（custom display shader）的输出纹理 ID。

通过这两个 ID 可以拿到对应处理过程的直接输出内容，用于后续分析或再处理。

重要注意事项：这些 ID 指向的是内部资源，不要长期缓存！下次配置变化或当前事件切换时，对应纹理可能被销毁重建。正确用法是：需要时即时查询、立即使用（例如传给ReadbackOutputTexture读取内容或作为纹理输入）。

端到端示例：离屏保存纹理视图

把以上环节串起来，一个典型的"把当前纹理视图保存为图片"的 Python 脚本骨架如下：

import renderdoc as rd # 1. 获取 ReplayController（来源参见 replay_controller.rst） # controller = ... # 2. 创建固定尺寸离屏窗口 windowing_data = rd.CreateHeadlessWindowingData(512, 512) # 3. 创建纹理输出 output = controller.CreateOutput(windowing_data, rd.ReplayOutputType.Texture) # 4. 配置纹理显示 cfg = rd.TextureDisplay() # ... 设置目标纹理 resourceId、通道、缩放、范围、叠加层等 ... output.SetTextureDisplay(cfg) # 5. 渲染并读取结果 output.Display() raw_pixels = output.ReadbackOutputTexture() # 6. 把 raw_pixels 按 RGBA8 等格式编码写入磁盘图片文件 # 7. 清理 output.Shutdown()

这个流程把"窗口"抽象成一块离屏缓冲区，完全不需要可见 GUI，非常适合批量导出、CI 快照或文档截图生成。

小结与进一步阅读

Replay output 系统的完整使用链路是：准备显示目标（原生窗口 / Qt widget / 离屏伪窗口）→ 取得WindowingData→CreateOutput创建输出 → 用SetTextureDisplay/SetMeshDisplay配置 →Display()驱动渲染 → 可选地叠加缩略图、像素上下文或读取内部纹理。其接口定义集中在 renderdoc/api/replay/renderdoc_replay.h，类型定义见 renderdoc/api/replay/replay_enums.h，窗口数据结构见 renderdoc/api/replay/control_types.h。

围绕本文主题，可继续深入阅读：

• frame_viewers.rst：纹理与网格查看器的更上层封装；
• replay_controller.rst：ReplayController的获取与完整生命周期；
• lifetimes.rst：输出与控制器等对象的生命周期规则；
• threading.rst：重放与输出的线程约束；
• resourceids.rst：资源 ID 的获取、传递与缓存注意事项；
• miniqt.rst：MiniQtHelper在 Qt 环境下的窗口管理辅助。

• 开发工具
• 调试器
• 图形学
• GPU