RenderDoc Python 模块 API 参考全览:renderdoc 模块结构与十二大接口板块导航

原创2026-09-23 19:27:031,638 阅读
文章标签:图形学3D渲染开发工具调试器游戏开发桌面应用

RenderDoc Python 模块 API 参考全览:renderdoc 模块结构与十二大接口板块导航

RenderDoc 在图形调试工具之外,还向 Python 暴露了完整的内部接口,使开发者可以用脚本自动完成捕获、回放、分析等任务。本文以仓库中的 docs/python_api/renderdoc/index.rst 为骨架,系统梳理 renderdoc Python 模块的定位、十二大 API 参考板块及各自核心成员,并结合仓库源码说明其绑定与实现路径。读完本文,你可以快速定位所需 API 所在板块,掌握嵌入式脚本与独立解释器两种使用方式的差异与生命周期约束。

renderdoc 模块的定位:UI 之下的同一套底层接口

按 API 参考索引页的原始说明,renderdoc 模块中的函数、类与枚举代表了 UI 构建其上的底层接口("the underlying interface that the UI is built on top of")。这意味着:

  • UI 中能看到的任何功能,原则上都能以某种方式通过 Python 访问;
  • 更高级的使用说明与脚本示例,见 docs/python_api/index.rst 的引导文档(first_steps、ui_extensions、ide_integration、faq、examples、in_depth 等)。

在 Python 侧存在两个分工明确的模块:

模块 作用域 说明
renderdoc 通用(UI 内嵌 Python 与独立解释器均可) 底层捕获、回放、分析、资源、着色器、结构化数据等接口
qrenderdoc 仅在 RenderDoc UI 内可用 提供 UI 相关功能访问,参考 docs/python_api/qrenderdoc/index.rst

renderdoc 模块的 API 参考共分十二个板块,索引页 docs/python_api/renderdoc/index.rst 通过 toctree 组织:capturing、replay、outputs、analysis、formats、resources、shaders、pipelines/index、structured_data、counters、frame_stats、utils。下文逐一展开。

两种使用场景:UI 内嵌脚本 vs 独立解释器加载

UI 内嵌 Python:开箱即用

在 RenderDoc UI 中,Python 脚本直接运行于内嵌的解释器(实现见 qrenderdoc/Code/pyrenderdoc/PythonContext.cpp),此时 renderdoc 与 qrenderdoc 两个模块都已可用,且回放系统已由 UI 初始化完毕,无需开发者手动处理生命周期。

独立解释器加载:高级用法,需自行初始化

docs/python_api/python_module.rst 详细说明了如何把 renderdoc 作为普通 Python 模块加载到独立解释器中。要点如下:

  • 构建模块:RenderDoc 默认不随安装包分发可加载的 Python 模块(Python 绑定与具体的大版本/小版本绑定)。需要先构建 RenderDoc 源码,构建依赖与步骤见 docs/CONTRIBUTING/Dependencies.md 与 docs/CONTRIBUTING/Compiling.md。构建产物位置因平台而异:Windows 上位于平台/构建类型下的 pymodules 子目录,Linux 上输出到 lib 目录下的 renderdoc.so。
  • 指定 Python 版本:Windows 在 Visual Studio 项目的 "Python Configuration" 属性页中指定解释器路径,并需要把标准库打包为 python3.xx.zip(可运行 util/make_python_lib_zip.py 自动从 Lib/ 编译生成);Linux 在 CMake 3.12+ 下使用 -DFORCE_PY_VERSION=3.xx 强制目标版本。
  • 加载模块:把模块所在目录加入 sys.path;Windows 上 Python 3.8+ 还需 os.add_dll_directory 指向 renderdoc.dll 所在目录;Linux 上模块自带 RUNPATH 可默认找到同目录的 librenderdoc.so,移动后需自行设置 LD_LIBRARY_PATH。
  • 生命周期约束:使用模块直连 API 时,必须在调用任何 API 之前调用一次 renderdoc.InitialiseReplay(),在进程结束前调用 renderdoc.ShutdownReplay();初始化前、关闭后调用任何 API 均非法,且关闭后不可重新初始化。UI 内嵌场景下这两个函数由 UI 自动调用,因此只有在独立使用模块时才需要手动处理。

注意:官方文档明确警告——直接使用 Python 模块属于高级用法,编写 UI 脚本或扩展时并不需要这么做。

十二大 API 板块逐一导航

以下每个板块的内容继承自对应参考页,完整成员列表由 Sphinx autodoc 从绑定接口自动生成,请以参考页为准。

1. Capturing:捕获、注入与目标控制

对应 docs/python_api/renderdoc/capturing.rst,分三组:

  • Execution & Injection(执行与注入):ExecuteAndInject(启动并注入目标进程)、InjectIntoProcess(向已运行进程注入);相关配置类 CaptureOptions、EnvironmentModification、EnvMod、EnvSep,以及返回结果 ExecuteResult。其中环境修改相关结构用于在捕获时对目标进程注入/修改环境变量,UI 的捕获选项中即有对应图形化配置。
  • Global Hooking(全局挂钩):StartGlobalHook、StopGlobalHook、IsGlobalHookActive、CanGlobalHook,用于对系统全局图形 API 调用进行挂钩。
  • Target Control(目标控制):EnumerateRemoteTargets、CreateTargetControl,配合 TargetControl、TargetControlMessage、TargetControlMessageType、NewCaptureData、APIUseData、BusyData、NewChildData 等,实现与目标进程/设备建立受控连接并收取捕获数据。

2. Replay Control:初始化、打开捕获文件与回放控制器

对应 docs/python_api/renderdoc/replay.rst,这是使用最频繁的板块之一,分六组:

  • Initialisation and Shutdown(初始化与关闭):InitialiseReplay、ShutdownReplay;GlobalEnvironment、ResultCode、ResultDetails 用于状态传递与错误描述。
  • Capture File Access(捕获文件访问):OpenCaptureFile、CaptureAccess、CaptureFile、ReplaySupport、CaptureFileFormat、SectionProperties、SectionType、SectionFlags、Thumbnail。CaptureFile 是打开 .rdc 文件后的主要操作入口,例如读取文件头、枚举节(Section)、获取缩略图并创建回放控制器。
  • GPU Enumeration(GPU 枚举):GPUDevice、GPUVendor、GPUVendorFromPCIVendor、GraphicsAPI、IsD3D、GetDriverInformation、DriverInformation,用于查询设备与驱动信息。
  • Replay Controller(回放控制器):ReplayController 及其配置 ReplayOptions、ReplayOptimisationLevel、APIProperties。ReplayController 是回放、分析、取帧的核心对象。
  • Device Protocols(设备协议):DeviceProtocolController、GetSupportedDeviceProtocols、GetDeviceProtocolController。
  • Remote Servers(远程服务器):RemoteServer、CreateRemoteServerConnection、CheckRemoteServerConnection、BecomeRemoteServer,以及文件浏览相关的 PathEntry、PathProperty。

3. Replay Outputs:回放输出(纹理、网格等视图)

对应 docs/python_api/renderdoc/outputs.rst:

  • General:ReplayOutput、ReplayOutputType(如 Texture / Mesh 输出类型)、SetColors。
  • Window Configuration(窗口配置):WindowingData、WindowingSystem,以及平台相关的构造函数 CreateHeadlessWindowingData、CreateWin32WindowingData、CreateXlibWindowingData、CreateXCBWindowingData、CreateWaylandWindowingData、CreateAndroidWindowingData、CreateMacOSWindowingData——这些函数把不同平台的窗口句柄统一封装为 WindowingData,供回放输出呈现使用。
  • Texture View(纹理视图):TextureDisplay 与 DebugOverlay,控制纹理显示方式与调试叠加层。
  • Mesh View(网格视图):MeshDisplay、MeshDataStage、MeshletSize、TaskGroupSize、MeshFormat、Visualisation、Camera、CameraType、AxisMapping,以及相机初始化辅助函数 InitCamera。

4. Replay Analysis:帧、动作、调试消息与像素历史

对应 docs/python_api/renderdoc/analysis.rst:

  • Frame and Actions(帧与动作):FrameDescription、ActionDescription、ActionFlags、APIEvent,用于枚举帧内 drawcall/dispatch 等事件动作。
  • Debug Messages(调试消息):DebugMessage、MessageCategory、MessageSeverity、MessageSource。
  • Resource Usage(资源使用):EventUsage、ResourceUsage,以及便捷构造函数 ResUsage、RWResUsage、CBUsage,用于描述资源在某事件上的读写用途。
  • Texture Saving(纹理保存):TextureSave、FileType、AlphaMapping、TextureComponentMapping、TextureSampleMapping、TextureSliceMapping,控制纹理导出为 PNG/EXR 等格式时的通道与切片映射。
  • Pixel History(像素历史):PixelModification、ModificationValue、PixelValue,用于查询某像素在帧内各事件作用下的变化过程。
  • Shader Debugging(着色器调试):DebugPixelInputs,像素着色器逐片元调试的输入描述。

5. Formats:资源格式描述

对应 docs/python_api/renderdoc/formats.rst:ResourceFormat、ResourceFormatType、CompType。这是描述纹理/缓冲底层数据排布的基础类型,被资源、纹理视图等板块广泛引用。

6. Resources:资源枚举与描述

对应 docs/python_api/renderdoc/resources.rst:

  • General:ResourceId、ResourceDescription、ResourceType、DescriptorStoreDescription。
  • Textures(纹理):TextureDescription、TextureType、TextureCategory、Subresource。
  • Buffers(缓冲):BufferDescription、BufferCategory。

配合 ReplayController 的 GetResources/GetTexture 等接口(详见 replay 板块),即可遍历帧内全部 GPU 资源并读取其描述与内容。

7. Shaders:描述符、反射、调试与变量

对应 docs/python_api/renderdoc/shaders.rst,这是内容最多的板块之一,分六组:

  • Descriptors(描述符):Descriptor、SamplerDescriptor、DescriptorFlags、DescriptorCategory、DescriptorType、DescriptorLogicalLocation、DescriptorRange、DescriptorAccess;辅助函数 CategoryForDescriptorType、IsConstantBlockDescriptor、IsReadOnlyDescriptor、IsReadWriteDescriptor、IsSamplerDescriptor。
  • Reflection(着色器反射):ShaderReflection、ShaderStage、ShaderStageMask、MaskForStage、FirstStageForMask、SigParameter、ShaderBuiltin、ConstantBlock、ShaderSampler、ShaderResource。
  • Debug Info(调试信息):ShaderDebugInfo、ShaderEncoding、KnownShaderTool、ToolExecutable、ToolInput、ToolOutput、IsTextRepresentation、ShaderEntryPoint、ShaderSourceFile、ShaderCompileFlags、ShaderCompileFlag、ShaderSourcePrefix。
  • Shader Constants(着色器常量):ShaderConstant、ShaderConstantType、ShaderVariableFlags、VarType、VarTypeByteSize、VarTypeCompType。
  • Shader Debugging(着色器调试):ShaderDebugTrace、ShaderDebugger、SourceVariableMapping、DebugVariableReference、DebugVariableType、LineColumnInfo、InstructionSourceInfo、ShaderDebugState、ShaderEvents、ShaderVariableChange。
  • Shader Variables(着色器变量):ShaderVariable、ShaderValue、PointerVal、ShaderBindIndex、ShaderDirectAccess。

8. Pipelines:按图形 API 划分的管线状态参考

对应 docs/python_api/renderdoc/pipelines/index.rst 目录,从仓库文件命名看,管线状态相关类型按通用与各图形 API 分类组织:

该板块与 UI 的 Pipeline State 窗口(源码位于 qrenderdoc/Windows/PipelineState/)相对应,用于在回放中读取各阶段完整绑定状态。

9. Structured Data:结构化捕获数据

对应 docs/python_api/renderdoc/structured_data.rst:

  • Type information(类型信息):SDType、SDBasic、SDTypeFlags。
  • Objects(对象):SDObject、SDObjectData、SDObjectPODData。
  • Chunks(块):SDChunk、SDChunkMetaData、SDChunkFlags。
  • Structured File(结构化文件):SDFile。
  • Creation Helper Functions(创建辅助函数):makeSDArray、makeSDBool、makeSDEnum、makeSDFloat、makeSDInt32、makeSDInt64、makeSDResourceId、makeSDString、makeSDStruct、makeSDUInt32、makeSDUInt64。

结构化数据让脚本可以遍历捕获文件中每个事件的参数(对应 UI 的 Event Browser 参数视图)。

10. Performance Counters:GPU 性能计数器

对应 docs/python_api/renderdoc/counters.rst:

  • Counters(计数器描述):CounterDescription、CounterUnit、Uuid。
  • Counter Types(计数器类型):GPUCounter 及厂商/类别判定函数 IsAMDCounter、IsARMCounter、IsGenericCounter、IsIntelCounter、IsNvidiaCounter、IsVulkanExtendedCounter。
  • Results(结果):CounterResult、CounterValue。

11. Frame Statistics:帧级统计

对应 docs/python_api/renderdoc/frame_stats.rst:

  • 入口结构 FrameStatistics;
  • Resource Statistics(资源统计):ResourceUpdateStats、BucketRecordType;
  • Drawcall Statistics(绘制调用统计):DrawcallStats、DispatchStats;
  • Shader Statistics(着色器统计):ConstantBindStats、SamplerBindStats、ResourceBindStats、ShaderChangeStats;
  • Fixed Function Statistics(固定功能统计):IndexBindStats、VertexBindStats、LayoutBindStats、BlendStats、DepthStencilStats、RasterizationStats、OutputTargetStats。

12. Utilities:数学、日志、版本、设置与自托管捕获

对应 docs/python_api/renderdoc/utils.rst:

  • Maths(数学):FloatVector、HalfToFloat、FloatToHalf。
  • Logging & Versioning(日志与版本):LogMessage、SetDebugLogFile、GetLogFile、GetCurrentProcessMemoryUsage、DumpObject、LogType;版本信息 GetVersionString、GetCommitHash、IsReleaseBuild。
  • Settings(设置):GetConfigSetting、SetConfigSetting、SaveConfigSettings,可在脚本中读写并持久化配置项。
  • Self-hosted captures(自托管捕获):CanSelfHostedCapture、StartSelfHostCapture、EndSelfHostCapture,支持由应用自身发起捕获的托管流程。

与仓库源码的对应关系

renderdoc 模块并不是独立的另一套实现,而是对 C++ 回放接口的 Python 绑定:

常见任务 → API 板块速查

目标任务 首选板块 关键类型/函数
启动并注入进程、配置捕获环境变量 Capturing ExecuteAndInject、CaptureOptions、EnvironmentModification
初始化回放系统、打开 .rdc 文件 Replay Control InitialiseReplay、OpenCaptureFile、CaptureFile、ShutdownReplay
创建回放控制器并逐帧/逐事件分析 Replay Control / Analysis ReplayController、FrameDescription、ActionDescription
查看纹理/网格并导出图片 Replay Outputs / Analysis ReplayOutput、TextureDisplay、MeshDisplay、TextureSave
遍历 GPU 资源与纹理信息 Resources / Formats ResourceDescription、TextureDescription、ResourceFormat
读取着色器反射与调试变量 Shaders ShaderReflection、ShaderDebugTrace、ShaderVariable
查询像素历史与逐片元调试 Analysis / Shaders PixelModification、DebugPixelInputs、ShaderDebugger
采集性能计数器与帧统计 Counters / Frame Statistics GPUCounter、CounterResult、FrameStatistics
遍历事件参数(结构化数据) Structured Data SDFile、SDChunk、SDObject
读写设置、查询版本、输出日志 Utilities GetConfigSetting、GetVersionString、LogMessage

深入阅读路径

简而言之,renderdoc 模块的 API 参考以十二大板块完整覆盖了从捕获、回放、输出到分析、着色器与统计的全链路能力;无论是编写一次性分析脚本、长期运行的自动化测试,还是在 UI 中做个性化扩展,都可以从本文的板块导航出发,直接进入对应参考页查阅由 autodoc 生成的最新签名与成员说明。

登录后查看全文
renderdoc