RenderDoc Python 远程回放Remote Replay实战指南连接、传输与回放全流程【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址: https://gitcode.com/gh_mirrors/re/renderdocRenderDoc 支持将捕获文件capture放到远程机器上进行回放而显示与 UI 交互仍然发生在本地。本指南以 docs/python_api/in_depth/remote_replay.rst 为骨架结合仓库源码renderdoc/api/replay/renderdoc_replay.h、renderdoc/core/remote_server.cpp详解远程服务器的启动与连接、进程注入捕获、捕获文件双向传输、API 代理选择与远程打开捕获的完整流程。读完本文你将能脱离 UI用纯 Python 脚本完成连接远程服务器 → 远程启动程序 → 传输捕获 → 远程回放的端到端闭环。远程回放的基本架构本地交互远程回放RenderDoc 的远程回放采用客户端-服务器模型本地端负责 UI 交互、纹理显示、网格渲染等一切与用户直接打交道的工作远程端运行一个 RenderDoc 实例作为远程服务器Remote Server实际执行捕获文件的回放与数据生成两端通过RPC over Socket通信。对于通过 UI 进行的脚本如 qrenderdoc 扩展远程回放对脚本几乎是透明的用户选择一个目标主机后脚本调用与本地回放完全一致的接口就像捕获是本地打开的一样。只有当纯脚本、无 UI运行时才需要自己处理远程连接的生命周期。从源码看远程回放的具体形态在 IRemoteServer 接口中定义得十分清晰它继承自ICaptureAccess支持捕获文件元数据访问并提供连接关闭、保活、文件浏览、进程注入、文件传输、捕获打开等一整套方法。UI 层对应的封装在 qrenderdoc/Code/Interface/RemoteHost.cpp 中RemoteHost::Connect()内部正是调用RENDERDOC_CreateRemoteServerConnection来建立连接的。远程服务器启动与发现以脚本方式启动远程服务器任何 Python 脚本都可以调用renderdoc.BecomeRemoteServer把自己变成一个远程服务器并进入监听循环。其 C 接口原型位于 renderdoc/api/replay/renderdoc_replay.hBecomeRemoteServer(listenhost, port, killReplayNone, previewWindowNone)参数语义依据 renderdoc/api/replay/renderdoc_replay.h 与 renderdoc/replay/entry_points.cpp参数说明listenhost监听的网卡接口名传空字符串时在实现层默认转为0.0.0.0监听所有接口port监听端口传0时使用默认端口39920定义见 renderdoc/common/globalconfig.h 的RenderDoc_RemoteServerPortkillReplay可选回调返回bool指示服务器是否应被关闭不传时默认永不关闭实现为[]() { return false; }previewWindow可选回调服务器需要预览窗口时返回WindowingData不传时默认返回WindowingSystem::Unknown该函数会阻塞运行直到某个远程连接要求服务器关闭或killReplay回调返回True。此外Android 版 RenderDoc 默认即作为远程服务器运行因此 Android 设备无需额外启动步骤。连接与连通性检查连接远程服务器使用renderdoc.CreateRemoteServerConnectionstatus, server renderdoc.CreateRemoteServerConnection(hostname)hostname传空字符串时连接本机localhost如果未指定协议前缀则按默认 TCP 方式发现目标成功时返回(ResultDetails, RemoteServer)元组否则返回失败状态。与之配套的renderdoc.CheckRemoteServerConnection(hostname)只做连通性探测而不建立连接。源码注释renderdoc/api/replay/renderdoc_replay.h明确指出当并不想真正建立连接时应优先使用它因为远程服务器同一时刻只能有一个活跃客户端探测状态不应干扰既有连接。从 renderdoc/core/remote_server.cpp 的实现可以看到建立连接时底层创建客户端 Socket 的超时时间为 750ms且支持通过 URL 中的端口覆盖默认端口也支持通过设备协议如 Android 的 adb 协议进行端口重映射。连接生命周期管理关闭、保活与捕获所有权两种关闭方式断开连接有且仅有两种选择server.ShutdownConnection()只关闭连接远程服务器进程继续运行之后可被再次连接server.ShutdownServerAndConnection()先请求远程服务器关闭自身进程再关闭连接。保活Ping 是必须的server.Ping()用于确认连接仍然存活返回ResultDetails。当没有其他命令执行时必须定期调用 Ping 保活否则连接会因长时间无活动而超时断开。临时捕获与所有权TakeOwnershipCapture远程服务器关闭连接时会删除它拥有的所有临时捕获文件。这涉及捕获文件的所有权链renderdoc/api/replay/renderdoc_replay.h捕获文件最初由被注入的应用库持有当某个通过 target control 连接的程序收到该捕获的创建通知时所有权转移给它该程序负责保存或删除文件调用server.TakeOwnershipCapture(filename)把所有权交给远程服务器后文件会被保留到服务器关闭为止关闭时由服务器统一清理。这对自动化流程很重要如果不想让远程临时文件在会话结束时丢失或被清理就要在合适时机把文件复制到本地见下文捕获文件传输。在远程主机上启动程序并捕获连接建立后即可在远程主机上启动应用进行捕获。核心接口是server.ExecuteAndInject(app, workingDir, cmdLine, env, opts)与本地版本的renderdoc.ExecuteAndInject完全类似区别在于所有路径都相对于远程文件系统。各参数renderdoc/api/replay/renderdoc_replay.happ远程可执行文件路径workingDir工作目录传空时默认使用应用所在目录cmdLine命令行参数按平台特定方式解析envEnvironmentModification列表用于修改环境变量optsCaptureOptions指定捕获选项。返回ExecuteResult包含操作状态、失败原因成功时还携带ident可用于后续 target control 连接。远程文件浏览server.GetHomeFolder()返回远程系统上浏览的起始路径server.ListFolder(path)返回该目录下的内容列表PathEntry列表出错时返回带错误标志的单个PathEntry。组合两者即可实现浏览远程可执行文件 → 选择并启动的交互流程。需要特别留意的是在某些平台上ListFolder返回的并非字面意义上的文件系统而是一份虚拟化的可用应用列表例如 Android 上浏览已安装应用。文档明确预期这些结果与ExecuteAndInject所需的可执行文件兼容——即用于启动时浏览结果应能直接作为app参数使用。捕获文件传输双向复制与临时文件语义远程回放有个硬性前提捕获文件必须存在于远程服务器的磁盘上。因此传输捕获文件是远程工作流的核心环节RemoteServer提供两个方向的操作remote_path server.CopyCaptureToRemote(local_filename, progressNone) # 本地上传 server.CopyCaptureFromRemote(remotepath, localpath, progressNone) # 远程下载两者的关键语义上传CopyCaptureToRemote不指定目标文件名远程服务器自行决定存储位置并从返回值给出实际路径。该文件属于服务器拥有的临时捕获连接关闭时会被删除。下载CopyCaptureFromRemote把远程文件复制到本地指定路径阻塞直至完成或出错。两个函数都支持可选的progress回调ProgressCallback接收float进度值以便展示进度。典型的自动化场景是把仅存在于本地的捕获上传到远程服务器 → 远程回放 → 在远程产生的捕获结果下载回本地保存。结合上文的所有权机制就可以形成一套远程产出、本地归档的完整闭环。API 选择远程支持列表与本地代理连接远程主机后需要处理两套 API 集合远程支持的 APIRemoteSupportedReplaysserver.RemoteSupportedReplays()返回远程服务器支持回放的渲染器名称列表形如D3D11、OpenGL、Vulkan等字符串。用途包括判断某个捕获在远程是否具备回放条件在多个候选远程主机之间做选择——优先挑选支持目标捕获所用 API 的主机。本地代理 APILocalProxies远程回放过程中RenderDoc必须在本地有限地使用一个图形 API来显示纹理、渲染网格。这个本地代理API 与捕获本身使用的 API 完全独立只需要极小的功能子集。server.LocalProxies()返回本机可用的代理渲染器名称列表同样是D3D11、OpenGL这类字符串。打开远程捕获OpenCapture 与本地代理选择server.OpenCapture(proxyid, filename, opts, progressNone)用于打开远程捕获进行回放与renderdoc.CaptureFile.OpenCapture类似成功时同样返回包含ReplayController的元组。status, controller server.OpenCapture(proxyid, filename, opts, progressNone)proxyidLocalProxies()返回列表中的索引指定使用哪个本地代理 API没有偏好时传-1对应源码中的IRemoteServer::NoPreference ~0Urenderdoc/api/replay/renderdoc_replay.h。文档推荐默认使用-1因为代理 API 的选择通常无关紧要filename远程系统上的文件路径若文件只在本地先通过CopyCaptureToRemote上传optsReplayOptions控制回放方式。该调用会阻塞直到远程捕获完全打开并可用。此后ReplayController的行为与本地回放一致所有尽量多的处理纹理上传、网格处理等都在本地完成以节省带宽与延迟——这正是 IRemoteServer 接口注释 中本地代理渲染器 尽可能多在本地完成工作的设计意图。关闭捕获的注意事项远程回放结束时必须调用server.CloseCapture(controller)关闭由OpenCapture返回的 ReplayController而不能直接调用controller.Shutdown()renderdoc/api/replay/renderdoc_replay.h。前者会正确清理本地代理相关资源后者则可能遗留代理状态。端到端脚本示例结合以上全部接口一个无 UI 的纯脚本远程回放流程可以组织如下import renderdoc as rd # 1. 连接远程服务器hostname 为空则连接本机 status, server rd.CreateRemoteServerConnection(replay-host.example.com) if status ! rd.ResultCode.Succeeded: print(连接失败:, status) exit(1) try: # 2. 查看远程支持回放的 API以及本地可用的代理 API remote_apis server.RemoteSupportedReplays() proxies server.LocalProxies() print(远程可回放:, remote_apis, 本地代理:, proxies) # 3.可选远程浏览可执行文件 home server.GetHomeFolder() entries server.ListFolder(home) # 4. 远程启动程序并注入捕获 opts rd.CaptureOptions() opts.CaptureSettings[rd.CaptureSetting.CaptureAll] True result server.ExecuteAndInject(/remote/path/app, , --width 800, [], opts) print(启动结果:, result, ident:, result.ident) # 5. 把本地捕获上传到远程服务器 remote_path server.CopyCaptureToRemote(/local/captures/frame.rdc) # 6. 远程打开捕获-1 表示本地代理 API 无偏好 st, controller server.OpenCapture(-1, remote_path, rd.ReplayOptions()) # 7. 使用 ReplayController 做分析…完成后必须用 CloseCapture 关闭 server.CloseCapture(controller) # 8. 把远程产生的捕获下载回本地 server.CopyCaptureFromRemote(remote_path, /local/backup/frame.rdc) # 9. 保活并选择关闭方式 while not should_exit: st server.Ping() # 空闲时定期保活 if st ! rd.ResultCode.Succeeded: break # server.ShutdownConnection() # 仅断开保留服务器 server.ShutdownServerAndConnection() # 关闭服务器并断开 finally: pass说明上述脚本为接口组合示例ReplayOptions()、CaptureOptions的字段与ResultCode枚举请以当前仓库 renderdoc/api/replay 下的头文件为准BecomeRemoteServer的服务器端示例可参考 renderdoc/core/remote_server.cpp 的监听循环实现。与 UI 脚本路径的对比场景连接管理打开捕获适用接口UI 内脚本qrenderdoc 扩展由 UI 管理脚本不可见直接使用 UI 提供的接口qrenderdoc/Code/Interface/QRDInterface.h 中ConnectToRemoteServer/DisconnectFromRemoteServer等纯脚本无 UI脚本自行处理RemoteServer.OpenCaptureIRemoteServerUI 场景下远程回放对脚本透明——用户选定主机后脚本可像本地一样调用所有功能详见 docs/python_api/in_depth/index.rst 中关于 UI 脚本化的说明。纯脚本场景则必须亲手完成本文所述的全部步骤。延伸阅读远程启动程序与 target control 的完整流程docs/python_api/in_depth/launching_programs.rst打开本地捕获文件docs/python_api/in_depth/capture_access.rst回放控制器的使用docs/python_api/in_depth/replay_controller.rst远程服务器接口的完整 API 参考docs/python_api/renderdoc/replay.rst底层实现renderdoc/core/remote_server.cpp、renderdoc/api/replay/renderdoc_replay.h【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址: https://gitcode.com/gh_mirrors/re/renderdoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考