开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载本指南围绕 RenderDoc Python 模块renderdoc中与捕获Capturing直接相关的 API 展开涵盖三大核心板块执行与注入Execution Injection、全局钩子Global Hooking与目标控制Target Control。读完本文你将掌握如何用 Python 启动一个带捕获能力的程序、将 RenderDoc 注入到已运行的进程中、通过目标控制连接远程触发与回收帧捕获并能理解这些接口背后的底层实现逻辑。说明renderdoc模块是 RenderDoc UI 所依赖的底层接口的 Python 直通层因此本模块中的函数、类与枚举全部源自渲染后端 C API声明于 renderdoc/api/replay 目录并通过 SWIG 暴露给 Python。更高层的使用流程含 UI 场景可参见 docs/python_api/index.rst 与 docs/python_api/in_depth/launching_programs.rst。一、API 总览Capturing 板块包含哪些接口capturing.rst将捕获相关接口划分为三组本文依次展开分组函数 / 类用途Execution InjectionExecuteAndInject、InjectIntoProcess、CaptureOptions、EnvironmentModification、EnvMod、EnvSep、ExecuteResult启动新程序并注入、向已有进程注入、配置捕获选项与环境变量Global HookingStartGlobalHook、StopGlobalHook、IsGlobalHookActive、CanGlobalHook系统级全局钩子按可执行路径匹配并捕获新启动的进程Target ControlEnumerateRemoteTargets、CreateTargetControl、TargetControl、TargetControlMessage、TargetControlMessageType、NewCaptureData、APIUseData、BusyData、NewChildData枚举/连接运行中的目标收发控制消息管理捕获文件所有接口的原生声明位于 renderdoc_replay.h其中 C 导出函数如RENDERDOC_ExecuteAndInject的实际实现位于 renderdoc/replay/entry_points.cpp目标控制连接层的实现位于 renderdoc/core/target_control.cpp。二、执行与注入Execution Injection2.1 ExecuteAndInject启动并注入新进程renderdoc.ExecuteAndInject(app, workingDir, cmdLine, env, capturefile, opts, waitForExit)用于启动一个应用程序并注入 RenderDoc使目标程序具备被捕获的能力。其 C 声明见 renderdoc_replay.h逐参数说明如下app (str)要运行的应用程序路径。workingDir (str)程序的工作目录传入空字符串时默认使用应用程序所在目录。cmdLine (str)要传递的命令行会按平台相关方式解析生成参数。env (List[EnvironmentModification])启动程序时需要做的环境变量修改列表。capturefile (str)捕获文件路径模板传空字符串则使用默认位置。opts (CaptureOptions)注入时使用的捕获选项。waitForExit (bool)若为True该函数将阻塞直到进程退出。返回ExecuteResult包含操作状态成功/失败及失败原因成功时还包含新程序监听目标控制的ident。从源码实现看entry_points.cpp该函数最终调用Process::LaunchAndInjectIntoProcess(...)将结果打包为ExecuteResult返回extern C RENDERDOC_API ExecuteResult RENDERDOC_CC RENDERDOC_ExecuteAndInject(const rdcstr app, const rdcstr workingDir, const rdcstr cmdLine, const rdcarrayEnvironmentModification env, const rdcstr capturefile, const CaptureOptions opts, bool waitForExit) { rdcpairRDResult, uint32_t status Process::LaunchAndInjectIntoProcess( app, workingDir, cmdLine, env, capturefile, opts, waitForExit ! 0); ExecuteResult ret; ret.result status.first; ret.ident status.second; return ret; }2.2 InjectIntoProcess注入到运行中的进程renderdoc.InjectIntoProcess(pid, env, capturefile, opts, waitForExit)在操作系统与权限允许的前提下将 RenderDoc 注入到已经运行的进程中声明见 renderdoc_replay.hpid (int)要注入的进程 ID。其余参数env、capturefile、opts、waitForExit语义与ExecuteAndInject相同。返回ExecuteResult。其实现entry_points.cpp转发到Process::InjectIntoProcess(pid, env, capturefile, opts, waitForExit)。2.3 ExecuteResult执行/注入的结果ExecuteResult是上述两个函数统一的返回值定义于 control_types.h包含两个字段字段类型说明resultResultDetails操作结果成功或失败及其原因identint新程序监听目标控制所用的标识符失败时为0配套的ResultDetailscontrol_types.h包含code: ResultCode与可选的错误消息它可直接与ResultCode比较也可用OK()判断是否成功。注意错误消息中的字符串信息只在ShutdownReplay之前有效若在错误响应中调用ShutdownReplay应先把错误码读取保存例如转换为Tuple[ResultCode, str]。官方推荐的非阻塞用法见 launching_programs.rst自动化时通常不要设置waitForExitTrue而是用返回的ExecuteResult判断启动是否成功并据此连接目标import renderdoc res renderdoc.ExecuteAndInject( app/path/to/game, workingDir, cmdLine--level demo, env[], capturefile, optsrenderdoc.CaptureOptions(), waitForExitFalse, ) if not res.result.OK(): print(Launch failed:, res.result.Message()) else: ident res.ident # 用于 CreateTargetControl print(Launched, target ident , ident)2.4 CaptureOptions捕获选项详解CaptureOptions是捕获时或 API 初始化时可配置的可选功能开关集合定义于 capture_options.h是上述注入函数、全局钩子以及 UI 捕获对话框共同使用的核心数据结构。所有字段及其默认值如下字段类型默认值含义allowVSyncboolTrue允许应用自行开启/关闭 vsyncFalse时强制禁用allowFullscreenboolTrue允许应用自行切换全屏False时强制禁用apiValidationboolFalse记录 API 调试事件与消息到捕获日志回放时与事件对应captureCallstacksboolFalse为 API 事件捕获 CPU 调用栈captureCallstacksOnlyActionsboolFalse仅在开启调用栈捕获时有效只对 action 记录调用栈否则对每个事件记录delayForDebuggerint0创建/注入进程后等待调试器附加的秒数0表示立即运行verifyBufferAccessboolFalse校验缓冲区访问检测越界写入、以标记值初始化未定义内容。仅对 OpenGL 与 D3D11 有效显式 APID3D12、Vulkan不适用hookIntoChildrenboolFalse挂钩系统创建子进程的 API用相同选项递归注入子进程refAllResourcesboolFalse默认只记录帧所需资源开启后捕获时刻所有活跃资源都会写入日志captureAllCmdListsboolFalse从应用启动起捕获所有命令列表关闭时仅捕获录制发生在帧捕获期间的命令列表。Vulkan/D3D12 会忽略此选项始终全捕获debugOutputMuteboolTrue开启 API 验证时静默 API 调试输出softMemoryLimitint0MB软内存上限超限数据尽量直接落盘单位 MB建议 200–1000MB并非严格内存限制此外CaptureOptions提供两个实用的序列化方法源码可见 capture_options.hEncodeAsString()将当前选项编码为字符串便于跨进程传递DecodeFromString(encoded)从编码字符串原位解码恢复选项。官方示例exe_launching.py展示了在 UI 捕获对话框中重置并启用调用栈捕获的典型写法settings dialog.Settings() # 重置为用户修改前的默认值 settings.options renderdoc.CaptureOptions() # 启用调用栈捕获 settings.options.captureCallstacks True dialog.SetSettings(settings)2.5 EnvironmentModification、EnvMod 与 EnvSep环境变量修改EnvironmentModification描述对单个环境变量的修改定义于 control_types.h构造签名如下EnvironmentModification(mod: EnvMod, sep: EnvSep, name: str, value: str)字段说明字段类型说明modEnvMod修改方式sepEnvSep需要时使用的分隔符namestr环境变量名valuestr配合mod使用的值EnvModreplay_enums.h取值Set将变量设置为给定值Append使用分隔符把值追加到变量末尾Prepend使用分隔符把值放到变量开头。EnvSepreplay_enums.h取值Platform使用平台对应的分隔符——Windows 用分号;POSIX 系统用冒号:SemiColon强制使用分号;Colon强制使用冒号:NoSep不使用分隔符。实际使用示例——为启动的程序注入启用 Vulkan 验证层的环境变量import renderdoc env [ renderdoc.EnvironmentModification( renderdoc.EnvMod.Set, renderdoc.EnvSep.NoSep, VK_INSTANCE_LAYERS, VK_LAYER_KHRONOS_validation, ) ]三、全局钩子Global Hooking全局钩子允许 RenderDoc 系统级地投机式注入开始注入系统上新启动的所有进程并按可执行路径匹配决定哪些真正捕获。C 导出函数声明与文档位于 renderdoc_replay.h实现转发到Process::StartGlobalHook等entry_points.cpp。函数签名要点说明StartGlobalHook(pathmatch, capturefile, opts)str, str, CaptureOptions - ResultDetails开始按pathmatch匹配注入新进程并捕获到capturefileStopGlobalHook()() - None停止之前激活的全局钩子IsGlobalHookActive()() - bool全局钩子是否处于激活状态CanGlobalHook()() - bool当前平台与配置是否支持全局钩子使用前提与限制依据源码文档调用前提StartGlobalHook只能在使用CanGlobalHook()确认支持、且IsGlobalHookActive()返回False时调用应用退出前必须用StopGlobalHook()关闭钩子。权限要求StartGlobalHook必须在以管理员/超级用户权限运行的进程中被调用。匹配规则pathmatch是用于匹配每个新进程可执行路径的字符串用于确定哪个程序是实际要捕获的目标。全局钩子支持与否取决于平台与配置CanGlobalHook()是唯一的事实依据。典型流程import renderdoc if renderdoc.CanGlobalHook() and not renderdoc.IsGlobalHookActive(): res renderdoc.StartGlobalHook( pathmatchmygame, capturefile/tmp/captures/game_frame.rdc, optsrenderdoc.CaptureOptions(), ) if res.OK(): print(Global hook active) # ... 运行其他工作 ... renderdoc.StopGlobalHook()四、目标控制Target Control目标控制是连接一个已注入 RenderDoc 的进程的通道用于查询状态、下发命令、接收捕获与子进程事件是捕获自动化中最常用的一层接口。4.1 EnumerateRemoteTargets枚举可用目标renderdoc.EnumerateRemoteTargets(URL, nextIdent) - int声明见 renderdoc_replay.h用于反复查询指定机器上活跃的目标及其ident首次调用传入nextIdent0获取第一个活跃目标之后用上一次的返回值继续调用即可枚举更多目标返回0表示已无其他目标URL为空表示本机未指定协议时进行默认 TCP 枚举显式带端口的主机仅支持回放不会枚举目标。从实现看entry_points.cpp枚举实质是对目标控制端口区间RenderDoc_FirstTargetControlPort到RenderDoc_LastTargetControlPort逐端口建立短超时250mssocket 探测命中即返回对应ident设备协议处理器如 Android 的 JDWP 桥接见 renderdoc/android会先对主机名/端口做重映射。import renderdoc ident 0 while True: ident renderdoc.EnumerateRemoteTargets(, ident) if ident 0: break print(Found target with ident:, ident)4.2 CreateTargetControl建立控制连接renderdoc.CreateTargetControl(URL, ident, clientName, forceConnection)声明见 renderdoc_replay.h阻塞直到控制连接就绪或出错URL (str)连接地址空表示本机未指定协议时默认 TCP 枚举。ident (int)目标机上特定目标的标识符。clientName (str)连接时使用的客户端名用于标识见TargetControl.GetBusyClient。forceConnection (bool)强制连接并踢掉当前已连接的客户端。返回成功返回TargetControl失败返回None。从实现看target_control.cppident的低 16 位即目标端口号主机名中的:会被解析为显式端口。同一程序同一时刻仅允许一个目标控制连接RenderDoc 假设多方之间协作而非竞争clientName用于区分也可用forceConnection强制抢占launching_programs.rst。4.3 TargetControl连接句柄的方法集TargetControl接口完整定义于 renderdoc_replay.h方法如下方法签名说明Shutdown()() - None关闭连接不影响运行中的应用Connected()() - bool连接是否仍然存活GetTarget()() - str目标名称/标识通常是可执行文件名GetAPI()() - str目标当前使用的 API 名未初始化 API 时为空字符串GetPID()() - int目标在本机的进程 ID不适用的平台返回0GetBusyClient()() - str若收到 busy 消息返回占用目标的客户端名TriggerCapture(numFrames)(int) - None触发捕获语义等同按下捕获键——从消息处理后的下一次呈现调用起到再下一次呈现为止numFrames指定连续独立捕获的帧数QueueCapture(frameNumber, numFrames)(int, int) - None在指定帧号排队捕获该帧开始捕获、结束于该帧结束帧 0 定义为设备创建起到第一次交换链呈现边界CopyCapture(captureId, localpath)(int, str) - None通过控制连接把远端捕获拷贝到本机绝对路径DeleteCapture(captureId)(int) - None删除远端捕获ReceiveMessage(progressNone)(Optional[Callable[[float],None]]) - TargetControlMessage接收消息见下节CycleActiveWindow()() - None有多个可捕获窗口时循环切换当前活动窗口连接使用完毕后必须由 Python 调用Shutdown()关闭launching_programs.rst。4.4 消息循环与 TargetControlMessage目标控制采用简单消息循环而非阻塞回调调用ReceiveMessage()会检查新消息若无消息则短暂等待后返回一个Noop消息因此可以在循环中无额外等待地反复调用同时它会泵送连接所以必须每几秒至少调用一次ReceiveMessage()以维持连接存活launching_programs.rst。TargetControlMessage定义于 control_types.h是消息的容器核心成员为type: TargetControlMessageType——消息类型newCapture: NewCaptureData——NewCapture类型时有效apiUse: APIUseData——RegisterAPI类型时有效busy: BusyData——Busy类型时有效newChild: NewChildData——NewChild类型时有效capProgress: float——进行中捕获的进度0.0–1.0无捕获时为 -1.0capturableWindowCount: int——可捕获窗口数。TargetControlMessageTypereplay_enums.h枚举值值含义Unknown未知/初始Disconnected连接已断开Busy目标正被其他客户端占用Noop空操作无待处理消息时返回NewCapture目标产生了新捕获CaptureCopied捕获拷贝完成RegisterAPI目标注册了 API 使用信息NewChild目标派生了新的子进程CaptureProgress进行中帧捕获的进度更新CapturableWindowCount可捕获窗口数发生变化RequestShow客户端请求控制器显示自身窗口置顶典型的消息分发写法import renderdoc tc renderdoc.CreateTargetControl(, ident, my-client, False) if tc is None: raise RuntimeError(Failed to connect) # 触发 1 帧捕获 tc.TriggerCapture(1) while tc.Connected(): msg tc.ReceiveMessage() if msg.type renderdoc.TargetControlMessageType.Noop: continue elif msg.type renderdoc.TargetControlMessageType.NewCapture: cap msg.newCapture print(Capture #%u, frame %u, %u bytes % (cap.captureId, cap.frameNumber, cap.byteSize)) print(Saved at:, cap.path, | title:, cap.title, | api:, cap.api, | local:, cap.local) # 远端目标可用 CopyCapture 拉回本地 tc.CopyCapture(cap.captureId, /local/path/out.rdc) elif msg.type renderdoc.TargetControlMessageType.CaptureCopied: print(Capture copied:, msg.newCapture.path) elif msg.type renderdoc.TargetControlMessageType.Disconnected: break tc.Shutdown()4.5 消息负载数据结构NewCaptureDatacontrol_types.h描述一个新捕获字段类型说明captureIdint引用该捕获的标识符frameNumberint捕获来自的帧号timestampint创建时间UTC Unix 时间戳byteSizeint捕获大小字节thumbnailbytesRGB8 格式的缩略图原始字节thumbWidth/thumbHeightint缩略图宽高pathstr目标系统上捕获保存的本地路径titlestr自定义标题空则使用默认标题apistr捕获所用 API旧版本 RenderDoc 可能为空localbool目标是否运行在本机APIUseDatacontrol_types.hnameAPI 名、presenting是否向交换链呈现、supported是否可捕获、supportMessage不支持时的原因说明。BusyDatacontrol_types.hclientName——当前占用目标的客户端名。NewChildDatacontrol_types.hprocessId子进程 PID、ident子进程目标控制所在标识符——配合CaptureOptions.hookIntoChildren使用。4.6 捕获的流转与后续处理若目标控制连接是本机连接新捕获立即可通过CaptureFile.OpenCapture直接回放见 docs/python_api/in_depth/capture_access.rst。若为远程连接可用TargetControl.CopyCapture把捕获经连接传输到本机完成后会收到CaptureCopied消息也可以把捕获留在远端用RemoteServer连接直接在远端回放详见 docs/python_api/in_depth/remote_replay.rst。捕获文件最初由被注入库所有通过目标控制连接通知并移交所有权给连接的客户端客户端负责保存或删除见TakeOwnershipCapture文档renderdoc_replay.h。五、完整自动化工作流示例综合以上 API一个不依赖 UI 的捕获自动化流程如下对应官方流程见 launching_programs.rstimport renderdoc # 1) 启动并注入非阻塞 res renderdoc.ExecuteAndInject( app/path/to/app, workingDir, cmdLine--profile run1, env[renderdoc.EnvironmentModification( renderdoc.EnvMod.Set, renderdoc.EnvSep.NoSep, RENDERDOC_CAPTUREOPTS, capture_callstacks1)], capturefile, # 空 - 默认位置 optsrenderdoc.CaptureOptions(), # 可继续调整字段 waitForExitFalse, ) if not res.result.OK(): print(启动失败:, res.result.Message()) raise SystemExit(1) ident res.ident # 2) 建立目标控制连接 tc renderdoc.CreateTargetControl(, ident, automation, False) if tc is None: raise SystemExit(1) # 3) 触发捕获并处理消息 tc.TriggerCapture(3) # 连续独立捕获 3 帧 while tc.Connected(): msg tc.ReceiveMessage() if msg.type renderdoc.TargetControlMessageType.NewCapture: print(捕获完成:, msg.newCapture.path) elif msg.type renderdoc.TargetControlMessageType.Noop: continue elif msg.type renderdoc.TargetControlMessageType.Disconnected: break tc.Shutdown()若目标程序已经运行则把第 1 步替换为renderdoc.InjectIntoProcess(pid, env, , opts, False)再对其返回的ident执行同样的连接与捕获流程。六、进一步阅读docs/python_api/index.rstPython API 总览与入门路径docs/python_api/renderdoc/index.rstrenderdoc模块 API 参考目录本指南对应 capturing.rstdocs/python_api/in_depth/launching_programs.rst启动程序与目标控制的配套实战教程docs/python_api/examples/exe_launching.rst 与 docs/python_api/examples/exe_launching.py基于 UI 捕获对话框的启动示例docs/python_api/in_depth/remote_replay.rst远端回放与RemoteServer连接docs/window/capture_attach.rstUI 中的捕获/附加界面说明源码参考renderdoc_replay.h、capture_options.h、control_types.h、replay_enums.h、entry_points.cpp、target_control.cpp。赞分享开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载相关推荐RenderDoc 帧捕获完全指南从 Launch Application 到注入进程与 .cap 配置RenderDoc 帧捕获完全指南从 Launch Application 到注入进程与 .cap 配置 RenderDoc 是一款独立的图形调试工具而 帧开发工具调试器图形学GPURenderDoc 进程内 APIIn-application API1.7.0 权威参考运行时注入、自定义捕获触发与注解系统RenderDoc 进程内 APIIn application API1.7.0 权威参考运行时注入、自定义捕获触发与注解系统 本篇技术指南以 Rende开发工具调试器图形学GPURenderDoc 捕获与注入指南Capture Dialog 启动配置、注入模式与全部捕获选项详解RenderDoc 捕获与注入指南Capture Dialog 启动配置、注入模式与全部捕获选项详解 本文基于 RenderDoc 官方文档 capture_开发工具调试器图形学GPU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/24 6:25:29 · 阅读 1.2k RenderDoc Python API 捕获指南：进程执行、注入与目标控制（Capturing）全解析
开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载本指南围绕 RenderDoc Python 模块renderdoc中与捕获Capturing直接相关的 API 展开涵盖三大核心板块执行与注入Execution Injection、全局钩子Global Hooking与目标控制Target Control。读完本文你将掌握如何用 Python 启动一个带捕获能力的程序、将 RenderDoc 注入到已运行的进程中、通过目标控制连接远程触发与回收帧捕获并能理解这些接口背后的底层实现逻辑。说明renderdoc模块是 RenderDoc UI 所依赖的底层接口的 Python 直通层因此本模块中的函数、类与枚举全部源自渲染后端 C API声明于 renderdoc/api/replay 目录并通过 SWIG 暴露给 Python。更高层的使用流程含 UI 场景可参见 docs/python_api/index.rst 与 docs/python_api/in_depth/launching_programs.rst。一、API 总览Capturing 板块包含哪些接口capturing.rst将捕获相关接口划分为三组本文依次展开分组函数 / 类用途Execution InjectionExecuteAndInject、InjectIntoProcess、CaptureOptions、EnvironmentModification、EnvMod、EnvSep、ExecuteResult启动新程序并注入、向已有进程注入、配置捕获选项与环境变量Global HookingStartGlobalHook、StopGlobalHook、IsGlobalHookActive、CanGlobalHook系统级全局钩子按可执行路径匹配并捕获新启动的进程Target ControlEnumerateRemoteTargets、CreateTargetControl、TargetControl、TargetControlMessage、TargetControlMessageType、NewCaptureData、APIUseData、BusyData、NewChildData枚举/连接运行中的目标收发控制消息管理捕获文件所有接口的原生声明位于 renderdoc_replay.h其中 C 导出函数如RENDERDOC_ExecuteAndInject的实际实现位于 renderdoc/replay/entry_points.cpp目标控制连接层的实现位于 renderdoc/core/target_control.cpp。二、执行与注入Execution Injection2.1 ExecuteAndInject启动并注入新进程renderdoc.ExecuteAndInject(app, workingDir, cmdLine, env, capturefile, opts, waitForExit)用于启动一个应用程序并注入 RenderDoc使目标程序具备被捕获的能力。其 C 声明见 renderdoc_replay.h逐参数说明如下app (str)要运行的应用程序路径。workingDir (str)程序的工作目录传入空字符串时默认使用应用程序所在目录。cmdLine (str)要传递的命令行会按平台相关方式解析生成参数。env (List[EnvironmentModification])启动程序时需要做的环境变量修改列表。capturefile (str)捕获文件路径模板传空字符串则使用默认位置。opts (CaptureOptions)注入时使用的捕获选项。waitForExit (bool)若为True该函数将阻塞直到进程退出。返回ExecuteResult包含操作状态成功/失败及失败原因成功时还包含新程序监听目标控制的ident。从源码实现看entry_points.cpp该函数最终调用Process::LaunchAndInjectIntoProcess(...)将结果打包为ExecuteResult返回extern C RENDERDOC_API ExecuteResult RENDERDOC_CC RENDERDOC_ExecuteAndInject(const rdcstr app, const rdcstr workingDir, const rdcstr cmdLine, const rdcarrayEnvironmentModification env, const rdcstr capturefile, const CaptureOptions opts, bool waitForExit) { rdcpairRDResult, uint32_t status Process::LaunchAndInjectIntoProcess( app, workingDir, cmdLine, env, capturefile, opts, waitForExit ! 0); ExecuteResult ret; ret.result status.first; ret.ident status.second; return ret; }2.2 InjectIntoProcess注入到运行中的进程renderdoc.InjectIntoProcess(pid, env, capturefile, opts, waitForExit)在操作系统与权限允许的前提下将 RenderDoc 注入到已经运行的进程中声明见 renderdoc_replay.hpid (int)要注入的进程 ID。其余参数env、capturefile、opts、waitForExit语义与ExecuteAndInject相同。返回ExecuteResult。其实现entry_points.cpp转发到Process::InjectIntoProcess(pid, env, capturefile, opts, waitForExit)。2.3 ExecuteResult执行/注入的结果ExecuteResult是上述两个函数统一的返回值定义于 control_types.h包含两个字段字段类型说明resultResultDetails操作结果成功或失败及其原因identint新程序监听目标控制所用的标识符失败时为0配套的ResultDetailscontrol_types.h包含code: ResultCode与可选的错误消息它可直接与ResultCode比较也可用OK()判断是否成功。注意错误消息中的字符串信息只在ShutdownReplay之前有效若在错误响应中调用ShutdownReplay应先把错误码读取保存例如转换为Tuple[ResultCode, str]。官方推荐的非阻塞用法见 launching_programs.rst自动化时通常不要设置waitForExitTrue而是用返回的ExecuteResult判断启动是否成功并据此连接目标import renderdoc res renderdoc.ExecuteAndInject( app/path/to/game, workingDir, cmdLine--level demo, env[], capturefile, optsrenderdoc.CaptureOptions(), waitForExitFalse, ) if not res.result.OK(): print(Launch failed:, res.result.Message()) else: ident res.ident # 用于 CreateTargetControl print(Launched, target ident , ident)2.4 CaptureOptions捕获选项详解CaptureOptions是捕获时或 API 初始化时可配置的可选功能开关集合定义于 capture_options.h是上述注入函数、全局钩子以及 UI 捕获对话框共同使用的核心数据结构。所有字段及其默认值如下字段类型默认值含义allowVSyncboolTrue允许应用自行开启/关闭 vsyncFalse时强制禁用allowFullscreenboolTrue允许应用自行切换全屏False时强制禁用apiValidationboolFalse记录 API 调试事件与消息到捕获日志回放时与事件对应captureCallstacksboolFalse为 API 事件捕获 CPU 调用栈captureCallstacksOnlyActionsboolFalse仅在开启调用栈捕获时有效只对 action 记录调用栈否则对每个事件记录delayForDebuggerint0创建/注入进程后等待调试器附加的秒数0表示立即运行verifyBufferAccessboolFalse校验缓冲区访问检测越界写入、以标记值初始化未定义内容。仅对 OpenGL 与 D3D11 有效显式 APID3D12、Vulkan不适用hookIntoChildrenboolFalse挂钩系统创建子进程的 API用相同选项递归注入子进程refAllResourcesboolFalse默认只记录帧所需资源开启后捕获时刻所有活跃资源都会写入日志captureAllCmdListsboolFalse从应用启动起捕获所有命令列表关闭时仅捕获录制发生在帧捕获期间的命令列表。Vulkan/D3D12 会忽略此选项始终全捕获debugOutputMuteboolTrue开启 API 验证时静默 API 调试输出softMemoryLimitint0MB软内存上限超限数据尽量直接落盘单位 MB建议 200–1000MB并非严格内存限制此外CaptureOptions提供两个实用的序列化方法源码可见 capture_options.hEncodeAsString()将当前选项编码为字符串便于跨进程传递DecodeFromString(encoded)从编码字符串原位解码恢复选项。官方示例exe_launching.py展示了在 UI 捕获对话框中重置并启用调用栈捕获的典型写法settings dialog.Settings() # 重置为用户修改前的默认值 settings.options renderdoc.CaptureOptions() # 启用调用栈捕获 settings.options.captureCallstacks True dialog.SetSettings(settings)2.5 EnvironmentModification、EnvMod 与 EnvSep环境变量修改EnvironmentModification描述对单个环境变量的修改定义于 control_types.h构造签名如下EnvironmentModification(mod: EnvMod, sep: EnvSep, name: str, value: str)字段说明字段类型说明modEnvMod修改方式sepEnvSep需要时使用的分隔符namestr环境变量名valuestr配合mod使用的值EnvModreplay_enums.h取值Set将变量设置为给定值Append使用分隔符把值追加到变量末尾Prepend使用分隔符把值放到变量开头。EnvSepreplay_enums.h取值Platform使用平台对应的分隔符——Windows 用分号;POSIX 系统用冒号:SemiColon强制使用分号;Colon强制使用冒号:NoSep不使用分隔符。实际使用示例——为启动的程序注入启用 Vulkan 验证层的环境变量import renderdoc env [ renderdoc.EnvironmentModification( renderdoc.EnvMod.Set, renderdoc.EnvSep.NoSep, VK_INSTANCE_LAYERS, VK_LAYER_KHRONOS_validation, ) ]三、全局钩子Global Hooking全局钩子允许 RenderDoc 系统级地投机式注入开始注入系统上新启动的所有进程并按可执行路径匹配决定哪些真正捕获。C 导出函数声明与文档位于 renderdoc_replay.h实现转发到Process::StartGlobalHook等entry_points.cpp。函数签名要点说明StartGlobalHook(pathmatch, capturefile, opts)str, str, CaptureOptions - ResultDetails开始按pathmatch匹配注入新进程并捕获到capturefileStopGlobalHook()() - None停止之前激活的全局钩子IsGlobalHookActive()() - bool全局钩子是否处于激活状态CanGlobalHook()() - bool当前平台与配置是否支持全局钩子使用前提与限制依据源码文档调用前提StartGlobalHook只能在使用CanGlobalHook()确认支持、且IsGlobalHookActive()返回False时调用应用退出前必须用StopGlobalHook()关闭钩子。权限要求StartGlobalHook必须在以管理员/超级用户权限运行的进程中被调用。匹配规则pathmatch是用于匹配每个新进程可执行路径的字符串用于确定哪个程序是实际要捕获的目标。全局钩子支持与否取决于平台与配置CanGlobalHook()是唯一的事实依据。典型流程import renderdoc if renderdoc.CanGlobalHook() and not renderdoc.IsGlobalHookActive(): res renderdoc.StartGlobalHook( pathmatchmygame, capturefile/tmp/captures/game_frame.rdc, optsrenderdoc.CaptureOptions(), ) if res.OK(): print(Global hook active) # ... 运行其他工作 ... renderdoc.StopGlobalHook()四、目标控制Target Control目标控制是连接一个已注入 RenderDoc 的进程的通道用于查询状态、下发命令、接收捕获与子进程事件是捕获自动化中最常用的一层接口。4.1 EnumerateRemoteTargets枚举可用目标renderdoc.EnumerateRemoteTargets(URL, nextIdent) - int声明见 renderdoc_replay.h用于反复查询指定机器上活跃的目标及其ident首次调用传入nextIdent0获取第一个活跃目标之后用上一次的返回值继续调用即可枚举更多目标返回0表示已无其他目标URL为空表示本机未指定协议时进行默认 TCP 枚举显式带端口的主机仅支持回放不会枚举目标。从实现看entry_points.cpp枚举实质是对目标控制端口区间RenderDoc_FirstTargetControlPort到RenderDoc_LastTargetControlPort逐端口建立短超时250mssocket 探测命中即返回对应ident设备协议处理器如 Android 的 JDWP 桥接见 renderdoc/android会先对主机名/端口做重映射。import renderdoc ident 0 while True: ident renderdoc.EnumerateRemoteTargets(, ident) if ident 0: break print(Found target with ident:, ident)4.2 CreateTargetControl建立控制连接renderdoc.CreateTargetControl(URL, ident, clientName, forceConnection)声明见 renderdoc_replay.h阻塞直到控制连接就绪或出错URL (str)连接地址空表示本机未指定协议时默认 TCP 枚举。ident (int)目标机上特定目标的标识符。clientName (str)连接时使用的客户端名用于标识见TargetControl.GetBusyClient。forceConnection (bool)强制连接并踢掉当前已连接的客户端。返回成功返回TargetControl失败返回None。从实现看target_control.cppident的低 16 位即目标端口号主机名中的:会被解析为显式端口。同一程序同一时刻仅允许一个目标控制连接RenderDoc 假设多方之间协作而非竞争clientName用于区分也可用forceConnection强制抢占launching_programs.rst。4.3 TargetControl连接句柄的方法集TargetControl接口完整定义于 renderdoc_replay.h方法如下方法签名说明Shutdown()() - None关闭连接不影响运行中的应用Connected()() - bool连接是否仍然存活GetTarget()() - str目标名称/标识通常是可执行文件名GetAPI()() - str目标当前使用的 API 名未初始化 API 时为空字符串GetPID()() - int目标在本机的进程 ID不适用的平台返回0GetBusyClient()() - str若收到 busy 消息返回占用目标的客户端名TriggerCapture(numFrames)(int) - None触发捕获语义等同按下捕获键——从消息处理后的下一次呈现调用起到再下一次呈现为止numFrames指定连续独立捕获的帧数QueueCapture(frameNumber, numFrames)(int, int) - None在指定帧号排队捕获该帧开始捕获、结束于该帧结束帧 0 定义为设备创建起到第一次交换链呈现边界CopyCapture(captureId, localpath)(int, str) - None通过控制连接把远端捕获拷贝到本机绝对路径DeleteCapture(captureId)(int) - None删除远端捕获ReceiveMessage(progressNone)(Optional[Callable[[float],None]]) - TargetControlMessage接收消息见下节CycleActiveWindow()() - None有多个可捕获窗口时循环切换当前活动窗口连接使用完毕后必须由 Python 调用Shutdown()关闭launching_programs.rst。4.4 消息循环与 TargetControlMessage目标控制采用简单消息循环而非阻塞回调调用ReceiveMessage()会检查新消息若无消息则短暂等待后返回一个Noop消息因此可以在循环中无额外等待地反复调用同时它会泵送连接所以必须每几秒至少调用一次ReceiveMessage()以维持连接存活launching_programs.rst。TargetControlMessage定义于 control_types.h是消息的容器核心成员为type: TargetControlMessageType——消息类型newCapture: NewCaptureData——NewCapture类型时有效apiUse: APIUseData——RegisterAPI类型时有效busy: BusyData——Busy类型时有效newChild: NewChildData——NewChild类型时有效capProgress: float——进行中捕获的进度0.0–1.0无捕获时为 -1.0capturableWindowCount: int——可捕获窗口数。TargetControlMessageTypereplay_enums.h枚举值值含义Unknown未知/初始Disconnected连接已断开Busy目标正被其他客户端占用Noop空操作无待处理消息时返回NewCapture目标产生了新捕获CaptureCopied捕获拷贝完成RegisterAPI目标注册了 API 使用信息NewChild目标派生了新的子进程CaptureProgress进行中帧捕获的进度更新CapturableWindowCount可捕获窗口数发生变化RequestShow客户端请求控制器显示自身窗口置顶典型的消息分发写法import renderdoc tc renderdoc.CreateTargetControl(, ident, my-client, False) if tc is None: raise RuntimeError(Failed to connect) # 触发 1 帧捕获 tc.TriggerCapture(1) while tc.Connected(): msg tc.ReceiveMessage() if msg.type renderdoc.TargetControlMessageType.Noop: continue elif msg.type renderdoc.TargetControlMessageType.NewCapture: cap msg.newCapture print(Capture #%u, frame %u, %u bytes % (cap.captureId, cap.frameNumber, cap.byteSize)) print(Saved at:, cap.path, | title:, cap.title, | api:, cap.api, | local:, cap.local) # 远端目标可用 CopyCapture 拉回本地 tc.CopyCapture(cap.captureId, /local/path/out.rdc) elif msg.type renderdoc.TargetControlMessageType.CaptureCopied: print(Capture copied:, msg.newCapture.path) elif msg.type renderdoc.TargetControlMessageType.Disconnected: break tc.Shutdown()4.5 消息负载数据结构NewCaptureDatacontrol_types.h描述一个新捕获字段类型说明captureIdint引用该捕获的标识符frameNumberint捕获来自的帧号timestampint创建时间UTC Unix 时间戳byteSizeint捕获大小字节thumbnailbytesRGB8 格式的缩略图原始字节thumbWidth/thumbHeightint缩略图宽高pathstr目标系统上捕获保存的本地路径titlestr自定义标题空则使用默认标题apistr捕获所用 API旧版本 RenderDoc 可能为空localbool目标是否运行在本机APIUseDatacontrol_types.hnameAPI 名、presenting是否向交换链呈现、supported是否可捕获、supportMessage不支持时的原因说明。BusyDatacontrol_types.hclientName——当前占用目标的客户端名。NewChildDatacontrol_types.hprocessId子进程 PID、ident子进程目标控制所在标识符——配合CaptureOptions.hookIntoChildren使用。4.6 捕获的流转与后续处理若目标控制连接是本机连接新捕获立即可通过CaptureFile.OpenCapture直接回放见 docs/python_api/in_depth/capture_access.rst。若为远程连接可用TargetControl.CopyCapture把捕获经连接传输到本机完成后会收到CaptureCopied消息也可以把捕获留在远端用RemoteServer连接直接在远端回放详见 docs/python_api/in_depth/remote_replay.rst。捕获文件最初由被注入库所有通过目标控制连接通知并移交所有权给连接的客户端客户端负责保存或删除见TakeOwnershipCapture文档renderdoc_replay.h。五、完整自动化工作流示例综合以上 API一个不依赖 UI 的捕获自动化流程如下对应官方流程见 launching_programs.rstimport renderdoc # 1) 启动并注入非阻塞 res renderdoc.ExecuteAndInject( app/path/to/app, workingDir, cmdLine--profile run1, env[renderdoc.EnvironmentModification( renderdoc.EnvMod.Set, renderdoc.EnvSep.NoSep, RENDERDOC_CAPTUREOPTS, capture_callstacks1)], capturefile, # 空 - 默认位置 optsrenderdoc.CaptureOptions(), # 可继续调整字段 waitForExitFalse, ) if not res.result.OK(): print(启动失败:, res.result.Message()) raise SystemExit(1) ident res.ident # 2) 建立目标控制连接 tc renderdoc.CreateTargetControl(, ident, automation, False) if tc is None: raise SystemExit(1) # 3) 触发捕获并处理消息 tc.TriggerCapture(3) # 连续独立捕获 3 帧 while tc.Connected(): msg tc.ReceiveMessage() if msg.type renderdoc.TargetControlMessageType.NewCapture: print(捕获完成:, msg.newCapture.path) elif msg.type renderdoc.TargetControlMessageType.Noop: continue elif msg.type renderdoc.TargetControlMessageType.Disconnected: break tc.Shutdown()若目标程序已经运行则把第 1 步替换为renderdoc.InjectIntoProcess(pid, env, , opts, False)再对其返回的ident执行同样的连接与捕获流程。六、进一步阅读docs/python_api/index.rstPython API 总览与入门路径docs/python_api/renderdoc/index.rstrenderdoc模块 API 参考目录本指南对应 capturing.rstdocs/python_api/in_depth/launching_programs.rst启动程序与目标控制的配套实战教程docs/python_api/examples/exe_launching.rst 与 docs/python_api/examples/exe_launching.py基于 UI 捕获对话框的启动示例docs/python_api/in_depth/remote_replay.rst远端回放与RemoteServer连接docs/window/capture_attach.rstUI 中的捕获/附加界面说明源码参考renderdoc_replay.h、capture_options.h、control_types.h、replay_enums.h、entry_points.cpp、target_control.cpp。赞分享开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载相关推荐RenderDoc 帧捕获完全指南从 Launch Application 到注入进程与 .cap 配置RenderDoc 帧捕获完全指南从 Launch Application 到注入进程与 .cap 配置 RenderDoc 是一款独立的图形调试工具而 帧开发工具调试器图形学GPURenderDoc 进程内 APIIn-application API1.7.0 权威参考运行时注入、自定义捕获触发与注解系统RenderDoc 进程内 APIIn application API1.7.0 权威参考运行时注入、自定义捕获触发与注解系统 本篇技术指南以 Rende开发工具调试器图形学GPURenderDoc 捕获与注入指南Capture Dialog 启动配置、注入模式与全部捕获选项详解RenderDoc 捕获与注入指南Capture Dialog 启动配置、注入模式与全部捕获选项详解 本文基于 RenderDoc 官方文档 capture_开发工具调试器图形学GPU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考