企业官网建设流程全解析

RenderDoc Python 远程回放（Remote Replay）实战指南：连接、传输与回放全流程

【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址: https://gitcode.com/gh_mirrors/re/renderdoc

RenderDoc 支持将捕获文件（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.h：

BecomeRemoteServer(listenhost, port, killReplay=None, previewWindow=None)

参数语义（依据 renderdoc/api/replay/renderdoc_replay.h 与 renderdoc/replay/entry_points.cpp）：

该函数会阻塞运行，直到某个远程连接要求服务器关闭，或killReplay回调返回True。此外，Android 版 RenderDoc 默认即作为远程服务器运行，因此 Android 设备无需额外启动步骤。

连接与连通性检查

连接远程服务器使用renderdoc.CreateRemoteServerConnection：

status, 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）：

1. 捕获文件最初由被注入的应用库持有；
2. 当某个通过 target control 连接的程序收到该捕获的创建通知时，所有权转移给它；
3. 该程序负责保存或删除文件；
4. 调用server.TakeOwnershipCapture(filename)把所有权交给远程服务器后，文件会被保留到服务器关闭为止，关闭时由服务器统一清理。

这对自动化流程很重要：如果不想让远程临时文件在会话结束时丢失或被清理，就要在合适时机把文件复制到本地（见下文"捕获文件传输"）。

在远程主机上启动程序并捕获

连接建立后，即可在远程主机上启动应用进行捕获。核心接口是server.ExecuteAndInject(app, workingDir, cmdLine, env, opts)，与本地版本的renderdoc.ExecuteAndInject完全类似，区别在于所有路径都相对于远程文件系统。各参数（renderdoc/api/replay/renderdoc_replay.h）：

• app：远程可执行文件路径；
• workingDir：工作目录，传空时默认使用应用所在目录；
• cmdLine：命令行参数，按平台特定方式解析；
• env：EnvironmentModification列表，用于修改环境变量；
• opts：CaptureOptions，指定捕获选项。

返回ExecuteResult：包含操作状态、失败原因；成功时还携带ident，可用于后续 target control 连接。

远程文件浏览

server.GetHomeFolder()返回远程系统上浏览的起始路径；server.ListFolder(path)返回该目录下的内容列表（PathEntry列表），出错时返回带错误标志的单个PathEntry。组合两者即可实现"浏览远程可执行文件 → 选择并启动"的交互流程。

需要特别留意的是：在某些平台上，ListFolder返回的并非字面意义上的文件系统，而是一份虚拟化的可用应用列表（例如 Android 上浏览已安装应用）。文档明确预期这些结果与ExecuteAndInject所需的可执行文件兼容——即用于启动时，浏览结果应能直接作为app参数使用。

捕获文件传输：双向复制与临时文件语义

远程回放有个硬性前提：捕获文件必须存在于远程服务器的磁盘上。因此传输捕获文件是远程工作流的核心环节，RemoteServer提供两个方向的操作：

remote_path = server.CopyCaptureToRemote(local_filename, progress=None) # 本地上传 server.CopyCaptureFromRemote(remotepath, localpath, progress=None) # 远程下载

两者的关键语义：

• 上传（CopyCaptureToRemote）不指定目标文件名：远程服务器自行决定存储位置，并从返回值给出实际路径。该文件属于服务器拥有的临时捕获，连接关闭时会被删除。
• 下载（CopyCaptureFromRemote）：把远程文件复制到本地指定路径，阻塞直至完成或出错。
• 两个函数都支持可选的progress回调（ProgressCallback，接收float进度值）以便展示进度。

典型的自动化场景是：把仅存在于本地的捕获上传到远程服务器 → 远程回放 → 在远程产生的捕获结果下载回本地保存。结合上文的所有权机制，就可以形成一套"远程产出、本地归档"的完整闭环。

API 选择：远程支持列表与本地代理

连接远程主机后，需要处理两套 API 集合：

远程支持的 API：RemoteSupportedReplays

server.RemoteSupportedReplays()返回远程服务器支持回放的渲染器名称列表（形如"D3D11"、"OpenGL"、"Vulkan"等字符串）。用途包括：

• 判断某个捕获在远程是否具备回放条件；
• 在多个候选远程主机之间做选择——优先挑选支持目标捕获所用 API 的主机。

本地代理 API：LocalProxies

远程回放过程中，RenderDoc必须在本地有限地使用一个图形 API来显示纹理、渲染网格。这个"本地代理"API 与捕获本身使用的 API 完全独立，只需要极小的功能子集。server.LocalProxies()返回本机可用的代理渲染器名称列表（同样是"D3D11"、"OpenGL"这类字符串）。

打开远程捕获：OpenCapture 与本地代理选择

server.OpenCapture(proxyid, filename, opts, progress=None)用于打开远程捕获进行回放，与renderdoc.CaptureFile.OpenCapture类似，成功时同样返回包含ReplayController的元组。

status, controller = server.OpenCapture(proxyid, filename, opts, progress=None)

• proxyid：LocalProxies()返回列表中的索引，指定使用哪个本地代理 API；没有偏好时传-1（对应源码中的IRemoteServer::NoPreference = ~0U，renderdoc/api/replay/renderdoc_replay.h）。文档推荐默认使用-1，因为代理 API 的选择通常无关紧要；
• filename：远程系统上的文件路径；若文件只在本地，先通过CopyCaptureToRemote上传；
• opts：ReplayOptions，控制回放方式。

该调用会阻塞直到远程捕获完全打开并可用。此后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 场景下远程回放对脚本透明——用户选定主机后，脚本可像本地一样调用所有功能（详见 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