RenderDoc 是什么
RenderDoc 是一款开源的、跨平台的图形调试与帧捕获工具，由 Baldur Karlsson 主导开发并维护于 https://github.com/baldurk/renderdoc。它的核心定位是：在不修改应用程序源码的前提下，对目标进程的某一帧 GPU 绘制过程进行完整记录，再通过离线 replay 方式逐 draw call 分析渲染状态、资源、Shader 及性能指标。
本项目（renderdocproject）基于 RenderDoc 原始仓库，针对 Android 平台的 GPU 性能分析场景进行定制，核心扩展集中在 Android 帧捕获适配、SurfaceFlinger trace 导出、OpenCode 桥接服务集成等方向。UI 层基于 Qt 构建，可运行于 Windows、Linux 等桌面平台，通过网络或 USB 连接到 Android 设备进行远程抓帧与回放。
支持的图形 API
Vulkan
- 支持 Vulkan 1.3，覆盖 Windows、Linux、Android 三个平台。
- Event marker 和对象命名通过
VK_EXT_debug_utils或已废弃的VK_EXT_debug_marker扩展提供。 - 支持 Vertex、Pixel、Mesh、Compute shader 调试。
- Android 平台通过
vkFrameBoundaryANDROID函数标记帧边界，这是一个直接 Vulkan 函数调用（函数签名：void vkFrameBoundaryANDROID(VkDevice device, VkSemaphore semaphore, VkImage image)），不是 pNext 扩展结构体。
OpenGL
- 支持 OpenGL Core Profile 3.2 至 4.6，运行于 Windows 和 Linux。
- 事件层级由标准或厂商特定扩展定义；对象命名使用
KHR_debug标签。
OpenGL ES（GLES）
- 支持 OpenGL ES 2.0 至 3.2，覆盖 Linux、Windows 和 Android。
- 对象命名同样使用
KHR_debug标签。 - Android GPU 性能分析中，部分 App 渲染层使用 GLES，RenderDoc 可对其进行完整帧捕获与回放。
D3D11 / D3D12（桌面平台）
- D3D11 支持至 D3D11.4，Windows Vista 及以上；D3D12 支持至 D3D12.9，Windows 10 及以上。
- 仅用于 Windows 桌面开发调试场景，与 Android GPU 性能分析无直接关联。
核心功能列表
帧捕获（Frame Capture）
- Trimming capture：捕获文件仅包含重放所需数据，而非应用生命周期内创建的全部纹理与 buffer，大幅压缩文件体积。
- 多帧捕获：支持同时捕获多帧并并排对比。
- 网络捕获：支持通过网络连接到远端设备（Android 设备）触发捕获，再在本地 PC 进行 replay。
- 捕获文件导入/导出：
.rdc格式可导出为.xml等外部格式供第三方工具处理，也支持从外部格式重新导入为.rdc。
事件浏览（Event Browser）
- 按 API 标准树形层级展示所有 draw call 和 dispatch call。
- 每个 action 对应的全量 API 调用列表（状态设置、资源绑定）均可查看，可附带完整 callstack 定位到 App 代码位置。
- Timeline 视图以时间轴左右展示场景层级，事件树自上而下，当前选中资源在 timeline 下方高亮标注（橙色=读，蓝色=写）。
完整图形管线状态查看（Pipeline State）
- 展示每个 draw call 时 GPU 管线的完整绑定状态（Vertex Input、Shader、Rasterizer、Blend、Depth/Stencil 等阶段）。
- 绑定到管线的资源按 Shader 实际引用情况裁剪展示，不参与当前 draw 的 slot 默认隐藏。
- 支持将管线状态导出为 HTML 文件。
资源查看器（Resource Inspector）
- 包含帧内所有资源与 API 对象的完整列表。
- 每个资源链接到其父/子对象，可视化构建依赖关系。
- 显示对象在帧前被创建时所使用的 API 调用序列。
- 任意对象可重命名，名称在整个 UI 中自动同步更新。
- UI 中任何以名称或句柄引用资源的地方，均可一键跳转到资源查看器。
Texture/Render Target 查看器
- 帧内所有纹理和 RT 的列表，支持过滤。
- 标准可视化控件：缩放/适应窗口、mip/face/slice 选择。
- RGBA 通道或 depth/stencil 分量独立显示。
- 灵活的 range 工具：自定义黑/白点，自动拟合 min/max 值，直方图展示。
- 当前管线绑定的 RT/纹理缩略图条，随帧内移动实时更新。
- 多种调试 overlay：Wireframe、Depth pass/fail、Stencil pass/fail、Clipping、NaN/-Inf/INF 高亮、quad overdraw、triangle size。
- 像素值拾取（Pixel value picking）。
- 纹理导出：支持 DDS、PNG、JPG 等格式。
Shader 查看与调试
- 显示 Shader 源码（需要调试信息）或反汇编代码。
- 支持 Vertex、Pixel、Compute shader 的单步调试（Vulkan/D3D）。
- 热 Shader 编辑与替换（Hot shader editing），无需重新捕获即可测试修改效果。
- 自定义可视化 Shader：用于解码自定义打包格式或 GBuffer。
Mesh Buffer 查看与可视化
- vertex shader 前后及几何管线末端（GS/DS 之后）的 mesh buffer 查看。
- 所有视图支持 arcball 和 flycam 控制，投影数据支持反投影到世界空间。
- 支持以其他 component（如 UV）作为坐标轴渲染 mesh，以及从输入/输出面板进行可视化 mesh picking。
Buffer 查看与导出
- 原始 buffer 内容查看，支持使用 HLSL-lite 或 GLSL-lite 语法设置自定义格式。
- Buffer 导出为 CSV 或原始二进制。
性能计数器与计时
- 每个 action 的简单耗时统计。
- GPU counter 数据的表格视图。
Python 脚本控制台
- 内置 Python 脚本控制台，提供完整文档化的 API，可访问 RenderDoc 内部数据结构和 Qt UI，支持自动化分析与批量处理。
与 Android GPU 性能分析的关联和应用场景
应用背景
Android 平台的 GPU 渲染链路复杂，涉及 App 端（Vulkan/GLES 绘制）和 SurfaceFlinger 端（合成）两个层次。传统工具难以在不侵入源码的前提下完整捕获某一帧的全量 GPU 指令与资源状态。RenderDoc 通过 debug layer 注入机制，在 GPU Driver 层面拦截所有图形 API 调用，做到零侵入帧捕获。
核心应用场景
1. App 端单帧 GPU 分析
针对目标 App 进程（Vulkan 或 GLES），RenderDoc hook 进程后可触发单帧捕获。捕获完成后，在 PC 端通过 replay 逐 draw call 查看：
- 每个 draw 的 RT 输出结果（纹理查看器）
- 绑定的 Shader 源码与反汇编
- 顶点/索引 buffer 内容
- 完整的管线状态（blend mode、depth/stencil 设置等）
典型问题定位场景：过度绘制（overdraw）、错误的深度测试配置、Shader 性能热点、RT 格式选择不当等。
2. SurfaceFlinger 合成帧分析
本项目扩展了对 SurfaceFlinger 进程的抓帧支持，可捕获 SF 合成一帧时的全量 GPU 操作，用于分析：
- 合成层数与合成策略（GPU 合成 vs HWC）
- 合成 Shader 的执行效率
- 各 Layer 的纹理使用情况
3. 与 Perfetto Trace 联合分析
RenderDoc 抓帧提供 GPU 侧的静态快照（某一帧的全量状态），Perfetto trace 提供 CPU/GPU 侧的时序数据（耗时分布、线程调度）。两者结合可完成：
- 定位具体哪一帧出现性能异常（Perfetto）
- 对异常帧进行 draw call 级别的 GPU 负载拆解（RenderDoc）
- 将 GPU 耗时与上层 Android 代码（RenderThread、SurfaceFlinger）的调用链关联
4. Shader 优化迭代
利用热 Shader 替换功能，可在不重新触发抓帧的前提下，直接在 PC 端修改 Shader 代码并立即看到渲染结果变化，加速 Shader 优化迭代效率。
5. 资源状态验证
在 Android 开发中，YUV 格式纹理、Vulkan image layout 转换、external memory 导入等场景容易出现资源状态不一致的问题。RenderDoc 的资源查看器和纹理查看器可直接显示每个 draw call 时资源的实际状态，辅助定位此类问题。
本项目的定制扩展
| 扩展点 | 说明 |
|---|---|
vkFrameBoundaryANDROID hook | 适配 Android 平台的显式帧边界标记，替代基于 vkQueuePresentKHR 的隐式帧切割 |
| SurfaceFlinger 抓帧适配 | 支持对 SF 进程触发帧捕获，导出 SF 的 Vulkan/GLES trace |
| GL Shader 导出 | 适配 OpenGL ES Shader 的导出能力 |
| 桥接服务集成 | 通过 4097 端口桥接服务和 4096 端口 OpenCode 服务，实现 PC 端与 Android 设备的通信 |
| Analyse 功能 | 新增 Analyse 按钮，集成 GPU 性能分析入口 |