第四章：帧捕获进阶配置
本章覆盖 RenderDoc 帧捕获的进阶配置能力，包括 Capture Options 各参数含义、远程 Replay 服务器的搭建与使用、回放控制选项、为 Capture 添加注解标记，以及调用栈捕获的配置与查看。
Capture Options 各参数详解
在 Launch Application 对话框中，Capture Options 区域提供了一系列控制采集行为的参数。大多数场景下默认值即可正常使用，但了解每个参数有助于在特殊场景下调整采集策略。
Allow Fullscreen
允许被采集应用以全屏模式运行。默认开启。如果关闭该选项，RenderDoc 会强制应用以窗口模式运行，便于在采集时操作 UI。
Allow VSync
允许被采集应用启用垂直同步（VSync）。默认开启。如果关闭，RenderDoc 会禁用 VSync，使帧率不受刷新率约束，这在测量性能时更准确。
Debugger Delay
启动后等待调试器附加的延迟时间（秒）。默认为 0，即不等待。设置大于 0 的值时，程序启动后会暂停指定秒数，留给开发者时间将调试器附加到目标进程，便于在程序初始化阶段打断点。
Collect Callstacks
采集每次 API 调用时的调用栈信息，并将其序列化到 .rdc 文件中。默认关闭。开启后可在 API Inspector 中查看每个 draw call 或 API 调用的代码调用路径，但会带来额外的采集开销和内存占用。
配合 Only action stacks 子选项使用时，可以只在 action 类调用（如 Draw、Dispatch）时采集调用栈，从而在保留关键信息的同时降低开销。
Capture Child Processes
采集目标程序启动的子进程。默认关闭。开启后 RenderDoc 的 hook 会传递给子进程，适合用于采集通过 launcher 间接启动的渲染进程。
Ref all Resources
强制 RenderDoc 引用并序列化帧中出现的所有资源，即使某些资源在当前帧并未被显式访问。默认关闭。开启后 .rdc 文件体积会增大，但可以确保 Replay 时所有资源都可见。
Soft Mem Limit
采集时的软性内存限制（单位：MB）。RenderDoc 会尝试将采集的内存占用控制在该阈值以内。达到限制后，RenderDoc 不会强制停止采集，而是尽量减少保存的数据量。设置为 0 表示不限制。
保存与加载 Capture 配置（.cap 文件）
在开发迭代中，采集参数通常固定不变。RenderDoc 支持将当前的所有采集配置（可执行文件路径、工作目录、命令行参数及 Options）保存为 .cap 文件。
- 在 Capture 对话框中点击 Save 保存配置文件。
- 在设置了文件关联的系统上，直接双击
.cap文件即可打开 RenderDoc 并加载该配置。 - 勾选 Auto start 后保存，再次打开该
.cap文件时会自动启动目标程序，实现一键采集。
注入已运行进程（Inject to Process）
RenderDoc 可以注入一个已经在运行但尚未初始化图形 API 的进程。
注意：必须在目标进程初始化图形 API 之前完成注入，否则 RenderDoc 无法正常 hook。注入功能默认未启用，需要在 Settings 中手动开启，且仅作为最后手段使用——优先使用 Launch Application 方式更加可靠。
操作路径：File → Inject to Process，Capture 对话框切换为进程列表视图，选择目标进程后注入。
远程 Replay 服务器配置与使用
RenderDoc 支持跨网络的采集与回放，核心概念是 Replay Context（回放上下文）。
默认状态下处于本地回放上下文，所有操作（采集、回放）均在本机完成。切换到远程上下文后，程序在远端机器上运行，采集与回放也在远端执行，UI 保持在本机运行。这与 Android 采集时的工作机制相同。
配置远程主机
打开 Tools → Manage Remote Servers，在此管理远程主机。
- 在 hostname 输入框中填入目标主机的主机名或 IP 地址，点击 Add。
- RenderDoc 立即发起网络探测，检查远端 Remote Server 是否在线。
- 支持在同一主机上运行多个 Remote Server，通过
hostname:端口号的形式区分，例如192.168.1.10:12345。
配置自动启动命令（Run Command）
在 Remote Host 配置中可以填写一条在本机执行的命令，该命令负责远程启动目标主机上的 Remote Server。配置后，RenderDoc 在需要连接时会自动执行该命令，无需手动干预。
Remote Server 的启动命令为：
renderdoccmd remoteserver
使用 -d 参数可以让服务器在后台运行（daemon 模式）：
renderdoccmd remoteserver -d
在 Linux 环境下的典型 Run Command 配置示例（使用 plink.exe + 免密 key 认证）：
plink.exe user@host DISPLAY=:0.0 renderdoccmd remoteserver -d
提示：在 Linux 上建议在 Run Command 中同时配置
DISPLAY环境变量，否则每次采集时都需要单独设置。
切换回放上下文
在 UI 底部状态栏的左侧可以切换 Replay Context。下拉列表会显示当前已配置且 Remote Server 在线的主机。切换前需确保没有已打开的 Capture。
选中远程主机后，RenderDoc 尝试连接。如果连接失败且配置了 Run Command，则自动执行该命令启动 Remote Server。
远程上下文中的工作方式
远程上下文下的操作体验与本地几乎一致，区别如下：
- 文件浏览器：浏览的是远端文件系统，RenderDoc 使用自定义对话框展示远端目录内容。
- 环境变量：远端进程继承 Remote Server 的环境，不继承本机环境。
- Capture 文件存储：默认保留在远端，只有显式 Save 到本地路径时才会复制到本机。
- 跨平台 Replay 提示：打开与当前系统平台差异显著的 Capture 文件时（如在 Windows 上打开 Linux 64-bit 的 Capture），UI 会提示是否切换到对应远端上下文进行回放。
配置 Remote Server 的访问控制
Remote Server 可通过 ~/.renderdoc/remoteserver.conf（Linux）或 %APPDATA%/renderdoc/remoteserver.conf（Windows）进行访问控制配置。
IP 白名单（允许指定 IP 段连接）：
whitelist 192.168.0.0/16
若未配置任何白名单，默认允许所有私有 IP 段（10.0.0.0/24、192.168.0.0/16、172.16.0.0/12）连接。
禁止执行命令（只读模式）：
noexec
配置 noexec 后，Remote Server 拒绝执行任何命令。此时需要通过其他方式手动启动 RenderDoc-hooked 的目标程序。
配置文件支持空行和以 # 开头的注释行。
控制 Replay（回放控制选项）
RenderDoc 默认的回放策略对大多数场景已足够，但也提供了若干精细控制选项。
使用非默认选项打开 Capture
通过 File → Open Capture with Options 可以在加载 Capture 时指定自定义的回放选项。该对话框会自动填充最近使用的文件路径，并提供以下配置项。
Use API Validation on Replay
- 默认值：
Disabled
通常 RenderDoc 在采集时启用 API Validation，并将校验消息保存到 .rdc 文件中——这是获取 API 校验信息最可靠的方式。
若当时未启用 API Validation，可在此选项开启，Replay 阶段将实时收集 API 校验消息，结果在 Debug Messages 窗口中查看。
注意：Replay 阶段的分析工作比采集阶段更重，可能产生不同甚至误报的校验消息。最佳实践是在不使用 RenderDoc 的情况下直接对程序启用 API Validation。
GPU Selection Override
- 默认值：
Default GPU selection
默认情况下 RenderDoc 会尝试选择与采集时最接近的 GPU 进行 Replay。此选项允许手动指定使用系统中的某块具体 GPU（及对应 API），适用于需要在不同硬件上验证兼容性的场景。
- 如果指定的 GPU 对该 Capture 不可用，回退到默认选择算法。
- 如果指定的 GPU 可用但无法打开 Capture，Replay 直接失败，不进行回退。
Replay Optimisation Level
- 默认值：
Balanced
RenderDoc 的 Replay 内部在正确性与性能之间有多种权衡，此选项控制优化程度：
| 级别 | 说明 |
|---|---|
| No Optimisation | 禁用所有优化，用于隔离 RenderDoc 自身的 bug |
| Conservative | 开启安全优化，用户不可感知 |
| Balanced | 开启更多优化，对最终帧结果无影响（例如清除无法被读取的 Render Target，而不是从前帧恢复其内容） |
| Fastest | 最激进的优化，中间状态可能出现”不可能”的数据（例如前述情形不清除 Render Target，导致后续帧数据反向泄漏），但最终帧结果仍然正确 |
并非所有 API 都能达到同等的优化程度，部分 API 下此选项效果有限。
修改全局默认选项
在 Settings → Replay 中可以修改上述选项的全局默认值，作用于所有未指定特定回放选项打开的 Capture。
为 Capture 添加注解标记（API Annotations）
RenderDoc 支持两种 Capture 注解方式：应用程序在运行时通过图形 API 写入的标记，以及在 UI 分析阶段手动添加的标记。所有 UI 侧的修改均可通过 Ctrl-S 或 File → Save 保存到 .rdc 文件中。
Marker Regions（API 侧标注分组）
可在应用代码中调用图形 API 提供的标注接口，将一段 GPU 命令标注为具名区域，支持嵌套层级。这些标注区域及其颜色会显示在 Event Browser 中。
D3D11（使用 D3DPERF 或 ID3DUserDefinedAnnotation）：
D3DPERF_BeginEvent(0xff00ff00, L"Sub section");
// GPU commands
D3DPERF_EndEvent();
// 也可使用较新的接口
ID3DUserDefinedAnnotation *annot;
immediateContext->QueryInterface(__uuidof(ID3DUserDefinedAnnotation), (void **)&annot);
annot->BeginEvent(L"Sub section 2");
annot->EndEvent();D3D12（在 Command List 或 Queue 上调用）：
// 第一个参数 1 表示 ANSI 字符串，0 表示 wchar 字符串
list->BeginEvent(1, "Begin Section", sizeof("Begin Section"));
list->EndEvent();OpenGL（使用 KHR_debug 扩展）：
glPushDebugGroupKHR(GL_DEBUG_SOURCE_APPLICATION, 0, -1, "Begin Section");
// GPU commands
glPopDebugGroupKHR();Vulkan（使用 VK_EXT_debug_utils 扩展）：
VkDebugUtilsLabelEXT markerInfo = {};
markerInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT;
markerInfo.pLabelName = "Begin Section";
vkCmdBeginDebugUtilsLabelEXT(cmd, &markerInfo);
// GPU commands
vkCmdEndDebugUtilsLabelEXT(cmd);在 D3D12 和 Vulkan 中，标注区域按提交顺序处理，允许跨越多个 primary command buffer。Secondary command buffer（或 Bundle）中的标注必须是自封闭的，不允许不平衡。
Object Names（资源命名）
通过图形 API 为 GPU 资源设置名称，RenderDoc 在 UI 中会以该名称代替自动生成的默认名称显示。
注意：RenderDoc 不支持在同一 Capture 内多次修改同一资源的名称，只保留最后一次设置的名称。
D3D11（SetPrivateData）：
tex2d->SetPrivateData(WKPDID_D3DDebugObjectName, sizeof("Example Texture"), "Example Texture");D3D12（SetName）：
tex2d->SetName(L"Example Texture");OpenGL（GL_KHR_debug，glObjectLabel）：
glObjectLabel(GL_TEXTURE, tex2d, -1, "Example Texture");Vulkan（VK_EXT_debug_utils，vkSetDebugUtilsObjectNameEXT）：
VkDebugUtilsObjectNameInfoEXT nameInfo = {};
nameInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT;
nameInfo.objectType = VK_OBJECT_TYPE_IMAGE;
nameInfo.objectHandle = (uint64_t)tex2d;
nameInfo.pObjectName = "Off-screen color framebuffer";
vkSetDebugUtilsObjectNameEXT(device, &nameInfo);D3D12 还提供了 RenderDoc 扩展接口 IRenderDocDescriptorNamer，可通过 ID3D12DescriptorHeap 查询，用于为 SM6.6 ResourceDescriptorHeap[] 样式访问的 Descriptor 设置自定义名称。
Bookmarks（事件书签）
在 Event Browser 中，可以为感兴趣的 Event 添加书签（快捷键 Ctrl-B），用于快速跳转。书签保存在 .rdc 文件中，其他人打开同一 Capture 文件时可直接使用 Ctrl-1 至 Ctrl-0 在书签间跳转，无需重新标注。
Resource Renaming（资源重命名）
在 Resource Inspector 窗口中，可以为任意资源提供覆盖名称，无论该资源原本是否有自定义名称。操作步骤：
- 在 Resource Inspector 中选中目标资源（通过绑定链接跳转，或按名称/类型搜索）。
- 点击 Rename Resource 按钮，输入新名称。
- 按
Enter或再次点击 Rename Resource 确认；按Escape或点击 Reset name 取消。
资源重命名同样会随 Capture 保存，后续加载时自动生效。
Capture Comments（附加文字说明）
在 Capture Comments 窗口中有一个自由文本输入框，可将任意文字（如环境信息、Build 版本说明）存入 .rdc 文件。默认情况下，打开包含 Comments 的 Capture 时会优先展示该内容；此行为可在 Settings 中关闭。
调用栈捕获配置与查看
概述
在非平凡的程序中，仅凭 Event Browser 中的 API 调用序列难以判断某个调用来自代码的哪个位置。RenderDoc 提供的 Callstack 采集功能，可为每个 API 调用记录代码侧的完整调用链，帮助快速定位问题源头。
注意（Windows）：Callstack 采集依赖
dbghelp.dll。若应用自身也在使用该 DLL 进行调试，建议禁用应用自身的dbghelp.dll使用，避免与 RenderDoc 产生冲突。
采集时启用 Callstack
在 Launch Application 对话框中勾选 Collect callstacks，RenderDoc 会在每个 API 入口点采集调用栈并将其序列化到 .rdc 文件中。
若希望降低开销，可同时勾选 Only action stacks，仅在 action 类调用（Draw、Dispatch 等）时采集调用栈，以较低的代价换取最关键的信息。
Replay 时解析 Callstack
打开 Capture 后，在 API Inspector 底部可展开 Callstack 面板。初始状态显示”需要解析符号”。
解析步骤：
- 打开
Tools菜单，选择 Resolve Symbols。 - RenderDoc 会搜索已加载模块对应的 PDB/符号文件（包括 Microsoft Symbol Server 及 PE 元数据中指定的原始构建路径）。
- 若找不到某个 PDB，UI 会弹出提示要求手动定位，并将该路径记忆以备后续使用。
- 若确认某个第三方 PDB 永远不可用，可选择永久忽略，避免每次打开 Capture 时重复提示。已忽略的 PDB 列表可在 Settings 中查看和移除。
符号解析完成后，API Inspector 中的 Callstack 面板会显示当前选中 API 调用或 action 的完整调用栈，支持选中复制到剪贴板。
首次使用时可能需要从 Microsoft Symbol Server 下载符号，耗时较长；后续会从缓存中直接读取。