Quartz 4

🔍 搜索

RenderDoc 常见问题与使用技巧

12 min read

第九章 常见问题与使用技巧

9.1 常见错误 FAQ

Q: Launch Application 中填入 com.android.systemui 后提示 “Invalid executable” 错误，如何处理？

A: com.android.systemui 是 Android 系统进程，无法通过 RenderDoc 的 Launch Application 直接启动。正确做法是：

  1. 先让目标进程正常运行。
  2. 在 RenderDoc 中使用 “Attach to Running Instance” 功能，选择已运行的目标进程进行挂载，而非通过 Launch Application 启动。
  3. 对于无法直接启动的系统进程或特殊进程，可考虑使用 Global Process Hook（全局进程钩子）选项，但需谨慎使用，详见 capture options 页面的相关警告说明。

Q: 无法连接 Android 设备，应该怎么排查？

A: 请按以下步骤排查：

  1. 确认 adb 已正确连接设备，执行 adb devices 可看到目标设备。
  2. 确认 RenderDoc 使用的网络端口未被防火墙或其他程序占用。RenderDoc 使用 TCP/UDP 端口 38920-38927 用于远程访问与控制，使用 TCP/UDP 端口 39920 用于远程 replay 连接。
  3. 确认设备上已正确部署 RenderDoc 的 Android layer（libVkLayer_GLES_RenderDoc.so 或相应的 Vulkan layer）。
  4. 若连接仍失败，检查 Android 设备日志（logcat）是否有相关错误输出。

Q: 抓帧完成后 RDC 文件为空，没有任何数据，原因是什么？

A: 可能原因及解决方案：

  1. Uncapped command list（D3D11）：若在抓帧触发前已录制了 deferred command list，RenderDoc 会无法捕获并重试。解决方案是启用 Capture all cmd lists 选项，代价是更高的性能开销。
  2. Uncapped Map()/Unmap()：若在 Present() 前后跨帧进行了 Map()/Unmap() 调用，RenderDoc 会错过该帧。解决方案是将 Map()/Unmap() 的调用范围收敛在同一帧内。
  3. 只有一个 swapchain 被捕获：RenderDoc 在同一时刻只捕获一个活跃的 swapchain。可通过 F11 键在多个 swapchain 之间切换，确认当前活跃的是目标 swapchain。
  4. API 兼容性问题：OpenGL 仅支持 Core Profile 3.2 及以上。若应用使用了兼容模式（compatibility profile）或旧版 OpenGL，RenderDoc 会拒绝捕获。

Q: Texture Viewer 中纹理显示黑屏或颜色异常，如何处理？

A: 颜色显示异常通常与 gamma/sRGB 校正有关：

  1. 对于明确标注 sRGB 格式的纹理，RenderDoc 会自动处理，显示应正常。
  2. 对于未标注 sRGB 但实际包含 sRGB 数据的纹理（如普通法线贴图），RenderDoc 默认会进行”过度校正”，导致显示看起来不正确。
  3. 可通过纹理查看器中的 gamma (γ) 按钮来切换是否进行校正。关闭该按钮后，数据将以线性方式显示。
  4. 注意 RenderDoc 显示的 texel 数值始终为线性浮点格式——例如 0.5, 0.5, 0.5 在存储字节中可能对应 186, 186, 186。
  5. 若纹理显示为全黑，还需检查通道选择按钮（R、G、B、A）是否只选中了某一个通道。右键点击通道按钮可以快速切换只显示该通道或显示全部通道。

Q: Shader 调试功能不可用，如何启用？

A: Shader 调试不可用通常由以下原因造成：

  1. 缺少 debug 信息：如果 shader 在编译后被 strip 掉了反射/调试信息，shader 变量将只显示为 cbuffer0、texture0 等无名称的占位符，且无法进行源码级调试。解决方案是在构建 shader 时保留调试信息（embedded debug info），或将调试信息单独存储并通过 RenderDoc 的 separated debug shader blobs 机制加载，详见 how_shader_debug_info 文档。
  2. OpenGL ES 兼容性：OpenGL ES 的 shader 调试支持受限，部分功能可能不可用。
  3. API Validation 未启用：在 capture 选项中启用 Enable API Validation，可以通过 Debug Messages 窗口查看 API 层面的错误和警告，有助于定位 shader 相关问题。

9.2 已知限制与注意事项

API 支持范围

  • Vulkan：支持 Vulkan 1.3，但 Vulkan 抓帧不保证跨 GPU 厂商可移植，甚至同一厂商不同型号的 GPU 之间也可能无法回放。
  • OpenGL：仅支持 Core Profile 3.2 及以上。OpenGL 2.0 及之前的兼容模式特性（compatibility profile）不受支持。OpenGL ES 支持 2.0 及以上版本。
  • D3D11/D3D12：回放要求 Feature Level 11.0 及以上的硬件。若硬件不满足，RenderDoc 会回退到 WARP 软件模拟，速度较慢。

抓帧限制

  • 每次只有一个 swapchain 处于活跃捕获状态，可通过 F11 切换。
  • RenderDoc 保存的是图形命令流，在回放时重新执行。因此，与时序、机器或驱动强相关的 bug 不一定在不同机器或驱动上可以复现。
  • 32 位进程在抓帧时内存峰值较高，建议使用 64 位版本，或限制抓帧场景的复杂度。
  • 若应用已加载 dbghelp.dll，可能与 RenderDoc 的 callstack 捕获功能产生冲突，导致结果为空或异常。
  • RenderDoc 不处理 API 非法调用（invalid API use），此类问题应使用各 API 自带的 validation 层来检测。

Shader 调试限制

  • 需要 shader 保留调试信息（debug info），stripped shader 只能查看基本状态，无法进行源码级调试。
  • Verify Buffer Access 选项目前仅支持 D3D11 和 OpenGL，不支持 Vulkan 和 D3D12。

内存与性能

  • RenderDoc 运行期间内存开销较大，尤其是分配了大量资源时，主内存中会创建对应的 shadow copy。
  • 抓帧会导致帧时间显著增加，并可能触发时序相关的 bug 消失或引入新的 artifact（这是预期行为，并非 RenderDoc 缺陷）。

OpenGL 特别说明

  • 若应用未使用 CreateContextAttribs API 创建上下文，RenderDoc 会认为该程序使用了 legacy 功能，并拒绝捕获。Overlay 会以 fixed-function pipeline 显示提示信息。
  • 使用 CreateContextAttribs 创建了兼容模式上下文（compatibility profile）的应用，RenderDoc 允许捕获，但会在 Overlay 中显示警告。

9.3 实用技巧

快捷键

快捷键功能
Ctrl-G在 Texture Viewer 中打开弹窗，输入像素坐标直接跳转
方向键在 Texture Viewer 中选中像素后，逐像素微调选中位置
Ctrl-F4关闭当前抓帧文件（有未保存修改时会提示保存）
Ctrl-Left / Ctrl-Right在整个 UI 中跳转到上一个/下一个 Action
Ctrl-1 到 Ctrl-0跳转到前 10 个书签（需先添加书签）
F11在多个 swapchain 之间切换活跃捕获目标
中键点击标签页关闭该标签页

书签与标注

  • 可以在抓帧中添加书签（bookmarks）、重命名资源（rename resources）以及添加注释（comments）。这些标注信息可以保存并嵌入 RDC 文件中，方便与他人共享时保留上下文信息。
  • 书签添加后，可通过 Ctrl-1 至 Ctrl-0 快速跳转到对应位置。

Texture Viewer 操作技巧

  • 独立通道查看：右键点击 R、G、B、A 通道按钮，可单独选中该通道；若该通道已是唯一选中状态，再次右键将选中其余所有通道。此功能适合查看 packed texture 或 render target 中的单独通道。
  • 自动范围适配：右键点击 auto-fit 按钮（wand 图标），可开启”每次纹理或事件变化时自动适配显示范围”模式，适合在不同帧之间跳转时保持一致的可视范围。
  • 锁定纹理标签页：在 Texture Viewer 的缩略图上双击，可将该纹理以独立锁定标签页的形式打开。
  • 图像文件查看：RenderDoc 可作为独立图像查看器使用。直接拖入或通过 File → Open 打开以下格式的图像文件：.dds、.hdr、.exr、.bmp、.jpg、.png、.tga、.gif、.psd。其中 .dds 支持所有 DXGI 格式、压缩格式、数组及 mip 层级。文件被修改后，RenderDoc 会自动刷新显示（但若图像尺寸或格式发生变化，需重新打开）。

Mesh Viewer 三维可视化

  • 可通过 Window 菜单打开 Mesh Viewer，或在 Pipeline State 窗口中点击顶点输入属性上的 Go Arrow 图标，以三维方式查看顶点数据，支持逐分量格式化显示。

.cap 文件自动抓帧

  • 若 .cap 文件保存时启用了 “auto-start” 选项，双击该文件启动 RenderDoc 时会自动触发抓帧，无需手动操作。这对于需要反复重复同一套抓帧配置的场景非常便捷。

可执行文件快速填入

  • 将可执行文件直接拖拽到 RenderDoc 窗口任意位置，可自动打开 Launch Executable 面板并填入路径。

从代码触发抓帧

  • renderdoc.dll 导出了 In-Application API，定义在 renderdoc_app.h 中，可在应用代码内主动触发抓帧，适合自动化测试或精确控制抓帧时机的场景。

检测 RenderDoc 是否存在

  • D3D11/D3D12：查询设备接口是否支持 UUID {A7AA6116-9C8D-4BBA-9083-B4D816B71B78}。
  • OpenGL：通过 GL_EXT_debug_tool 扩展（枚举值 0x6789）查询。
  • Vulkan：查询 VK_EXT_tooling_info 扩展是否存在。
  • 通用方式：尝试加载模块，Windows 使用 GetModuleHandleA("renderdoc.dll")，Linux 使用 dlopen("librenderdoc.so", RTLD_NOW | RTLD_NOLOAD)。

多 GPU 环境

  • RenderDoc 默认在回放时选择与抓帧时最匹配的 GPU。若无法匹配，则使用系统默认 GPU。可通过 GPU selection replay option 按 capture 或全局覆盖该选择。

性能分析建议

  • 启用 Enable API Validation 捕获选项，并在 Debug Messages 窗口查看 API 错误和警告，有助于定位渲染问题。
  • 对于大量资源分配的场景，注意 RenderDoc 的内存开销；建议在较简单的场景下抓帧以减少干扰。
  • 在 Android 上抓帧时，建议使用 64 位版本（libVkLayer_GLES_RenderDoc.so 对应 arm64-v8a）以避免内存不足问题。

Graph View

Backlinks