# renderdoc-mcp

一个精简版 RenderDoc MCP server，只聚焦一件事：从 `.rdc` 捕获文件里导出指定 draw call 的资源。

保留能力：

- 导出 VSIn mesh 数据
- 导出 VSOut mesh 数据
- 导出 shader 绑定纹理
- 可选导出 color/depth render target
- 生成 manifest，方便后续资产处理脚本读取

## 环境要求

RenderDoc 的 Python 模块必须能被当前 Python 解释器加载。通常需要设置：

```powershell
$env:RENDERDOC_MODULE_PATH = "C:\Program Files\RenderDoc\pymodules"
```

注意：RenderDoc 的 `renderdoc.pyd` 必须和 Python ABI 匹配。如果 RenderDoc 安装包提供的是 Python 3.6 扩展，就需要用 Python 3.6 x64 运行 MCP。

## 常用工具

- `open_capture(filepath, mode="auto")`：打开指定 `.rdc`；`mode` 可选 `auto`、`background` 或 `foreground`
- `open_capture_background(filepath)`：通过 qrenderdoc bridge 后台加载指定 `.rdc`，不显示、聚焦或激活窗口；失败时不回退到前台
- `open_capture_at_event(filepath, event_id)`：在 RenderDoc GUI 打开指定 `.rdc` 并聚焦 EID
- `focus_event(event_id)`：在 RenderDoc GUI 当前捕获中聚焦 EID
- `Activity Log`：在 RenderDoc Tools 菜单查看 Bridge 操作历史和结果
- `show_activity_log()`：从 MCP 主动显示或前置 Activity Log 底部面板
- `connect_to_gui_capture()`：通过 RenderDoc GUI bridge 打开当前 GUI 里的捕获
- `export_mesh_stage_data(...)`：导出单个 mesh stage
- `export_event_textures(...)`：导出指定 EID 的纹理。2D 仍是单张图；3D / Cube / 数组会写出全部 slice 和一份 sidecar json，浮点格式用 EXR
- `export_draw_bundle(...)`：一次导出 VSIn、VSOut、纹理和 manifest
- `find_drawcalls_by_reference(...)`：用参考图、锚点 EID、PostVS 屏幕包围盒和管线签名筛选角色部件，并生成 SVG Mesh 联络表
- `find_eids_by_screen_region(...)`：对最终 Present 的归一化区域采样 Pixel History，结合资源使用索引和 PostVS 包围盒返回候选 EID；可选导出 Overlay
- `describe_event(event_id, output_dir=None)`：列出这一笔绑定的每一张纹理，带显存尺寸和格式。传入 `output_dir` 时把整张图存下来
- `find_draws_by_texture(name_parts, event_start=0, event_end=0)`：按贴图资源名片段找出绘制
- `export_present(output_dir)`：导出最后一次 Present 的交换链画面
- `export_present_overlay(event_id, output_dir, overlay="drawcall", crop=True, pad=80)`：用 Texture Viewer 的 DebugOverlay 标出指定 EID，再叠到整个 rdc 最后一次 Present 上。`overlay` 常用 `drawcall`（品红填充）和 `wireframe`
- `capture_mesh_viewer(event_id, output_path)`：在当前 qrenderdoc 里打开 Mesh Viewer 并保存截图。扩展更新后需要重启 RenderDoc
- `find_eids_by_screen_region` 的 `region` 使用 `[x, y, width, height]` 归一化坐标；默认 3×3 Pixel History 采样。Pixel History 不可用时会降级到 Present 资源使用索引，并在结果中标记 `fallback`。
- 传入 `output_dir` 时默认生成 `present_roi.png` 框线图和 `screen_region_eids.json`；`annotate_roi=false` 可关闭框线图，`export_overlays=true` 可为候选 EID 生成最终画面 Overlay。候选结果必须再交叉确认，不能直接当作已确认部件。

### 画面区域反查的边界与验证

ROI 标注和 Overlay 合成在 MCP 主进程执行，依赖主进程的 Pillow；qrenderdoc 内嵌 Python 与 Python 3.6 worker 只导出原图，不需要安装 Pillow。安装项目依赖即可；返回 `image_processing_source="mcp_host"` 表示主进程处理完成。JSON 文件会在图片处理后更新，记录最终路径或明确错误。

`trace_upstream=true` 默认启用有限上游追踪：对于只有 3～6 个索引的全屏绘制，检查其绑定纹理在此前是否被写入；验证整个输出 viewport 和 PostVS 的仿射 UV 后，查询中间目标的对应区域。支持 UV 翻转和缩放，无法建立映射时返回 `upstream_trace.stopped`，不猜测坐标。

- `max_trace_depth=3`：默认最多追踪 3 层，可设为 0～8。
- `max_trace_resources=4`：默认最多查询 4 个上游资源，可设为 1～16。
- `max_candidates=64`：最终目标与全部上游节点共用分析预算，不是每个资源各分析 64 个。
- `trace_upstream=false`：只查询最终 Present，保留原有候选输出。
- `candidates`：最终目标的候选；`upstream_trace.nodes[].query.candidates`：中间目标的候选，不混在一起。
- `present_resource_id/present_size`：最终目标；`queried_resource_id/queried_size`：本节点实际查询目标。采样像素坐标属于实际查询目标。
- `mapping_status="geometry_verified_shader_unverified"`：UV 几何插值已检查，但没有证明像素着色器直接使用该 UV，也没有证明后处理、畸变或历史缓冲的对应关系。所有候选保持 `identity_status="unconfirmed"`，`confidence` 只是排序分数，不是物体身份概率。

先调用区域查询，再对候选调用 `describe_event`、`export_present_overlay`、`capture_mesh_viewer`、`export_draw_bundle` 交叉验证。Mesh Viewer 截图直接捕获 `render` 布局的原生预览子窗口，等待数据表重置与边界加载完成后再重置、旋转相机，并检查事件、阶段、实例、视图和尺寸。可选参数为 `stage="vsin"`、`instance=0`、`view=0`、`orbit=0.35`、`axis="y_up"`，`orbit` 范围为 -0.9～0.9；`axis` 支持 `y_up` 与 `z_up`。地面资产可用 `axis="z_up", orbit=0` 正视 XZ 铺面；这只是 Mesh Viewer 的观察坐标，不改变顶点或 Present 方向。空图或侧视细线返回 `saved=false`，原图保留以便诊断。`content_status="visible_solid_colour"` 仅表示检测到实色网格像素，`mesh_verified=false` 与 `requires_visual_review=true` 表示仍需检查真实形状，不是自动身份认证。

该工具仍要求调用方提供 ROI；不包含参考图片自动识别或交互框选。Overlay 保留真实原图和两端 ResourceId，只有同一资源且尺寸一致时才输出 `fused_path`；不同目标返回 `mapping_status="unverified"`、`position_verified=false`、`fused_path=null`，不能仅凭尺寸一致或等比缩放合成。多个交换链返回 `AMBIGUOUS_SWAPCHAIN`，无高亮即使 `crop=false` 也返回 `EMPTY_OVERLAY`。复杂后处理、透明、多 Pass 的映射仍需要实际捕获验证，部件身份始终保持 `identity_status="unconfirmed"`。

`describe_event.bindings` 保留重复资源的全部槽位与 mip/slice view 范围；`binding_count` 是绑定条数，`unique_resource_count` 是独立 ResourceId 数。导出图片是资源图，不等同于已证明该 view 的实际采样。`triangles` 仅对无 restart 的 TriangleList 返回每实例提交数，其他拓扑返回 null，并附带拓扑和 restart 状态。

GUI 聚焦功能依赖 qrenderdoc bridge。安装或更新扩展后，需要重启 RenderDoc：

```powershell
python -m renderdoc_mcp.install_bridge
```

打开指定捕获并跳到 EID 852：

```json
{
  "filepath": "D:\\captures\\frame.rdc",
  "event_id": 852
}
```

## ClearBeforeDraw 独立识别图

`export_texture_viewer_clear_before_draw(event_id, output_dir, target_slot=0, resource_id=None,
mip=None, slice_index=None, sample=0, range_min=0.0, range_max=1.0,
linear_display_as_gamma=True, flip_y=False)` 导出所选颜色附件的真实 Texture Viewer
ClearBeforeDraw 显示结果。mip/slice 默认附件 view 的第一项，sample 默认 0。
resource_id 可核实槽位，不匹配即失败，不自动换目标或 EID。

通过独立离屏 ReplayOutput 的 ReadbackOutputTexture 读取 RGB 显示图，
不是保存辅助 Overlay 纹理；不调用 Present、不裁剪、不缩放、不合成最终帧。
显示使用 RGB、关闭 alpha 混合、黑色背景、范围 0～1 和默认 gamma。
PNG 是 RGB8 人工识别证据，不能代表原始浮点/alpha 或 Shader 零差异验收。

`export_draw_bundle` 和 `export_resource_asset` 默认附带该图，可用
`identification_target_slot` 指定颜色附件（默认 0）。保持已有 EID 包目录，
新增 `texture_viewer_clear_before_draw.png`、同名 JSON，写入 manifest 的
`identification`；失败写入 errors，已有资源不丢弃。无有效颜色目标/深度专用
报告 NO_COLOR_TARGET；均匀输出保留 diagnostic_path，成功 output_path 为空。
所有结果 identity_status 为 unconfirmed，必须人工复核。

复用现有 GUI Bridge，不改变用户 Texture Viewer 设置，不增删 Shader Replacement。
finally 禁用临时输出 Overlay、刷新并销毁离屏输出，随后恢复原事件。
GUI 客户端用 client.lock 跨进程保护同 namespace，不要同时使用旧客户端。
超时保留 client.lock 并停止后续请求，不自动重试或启动/关闭实例；确认旧请求
已经结束、响应已核对后才可人工恢复锁。

新工具需要部署更新后的 Bridge 扩展；安装与重启仅在用户明确授权后执行，不由工具请求自动触发。
真实图像正确性仍需在已更新、明确允许使用的现有实例上验证。

## 严格 PS 验收

连接恢复与完整原 Mip 工具的用法和部署边界见
`docs/tasks/2026-10-10-connection-and-original-mips/usage.md`。
完整采样资源使用 `export_original_texture_mips`，现有 PNG/EXR 导出仍是基础级显示/旧流程兼容入口，不能用于原 Mip 严格迁移。

`validate_shader_strict` 是独立注册的验收工具，当前仅支持现有 qrenderdoc Bridge 中的
D3D11 DXBC pixel shader，不会自动启动 worker、打开捕获或重建实例。
旧 `validate_pixel_shader` 的 `status="ok"` 仍只表示处理完成，不能当作资产验收通过。

参数：`event_id`、`output_dir`，以及互斥的 `source_text` / `source_path`；
`stage="pixel"`，可选 `entry_point`、`compile_options=[{"name":"...","value":"..."}]`。
默认沿用原 shader 的编译标志；DXBC 反射入口名称可能为 main，与实际提交的编译入口
分别记录。source_path 展开本地引号 include，仍有未解析 include 时拒绝。
保存实际提交 UTF-8 字节及 SHA256、原 DXBC、编译 DXBC、捕获路径/大小/修改时间。

显示参数与识别工具一致：`target_slot`、`resource_id`、`mip`、`slice_index`、`sample`、
`range_min`、`range_max`、`linear_display_as_gamma`、`flip_y`。
RGB 与 alpha 通过独立 ClearBeforeDraw ReplayOutput 显示回读；alpha 使用范围 0～1、
关闭 gamma 的 alpha-only 灰度显示，组合为可解码 RGBA 证据。不是对 RGB 填固定 alpha。
此图为显示转换后的 8-bit 证据，必须同时通过原始 MRT 字节检查，不能代替浮点或真实混合验证。

执行顺序：

1. 拒绝已有用户 Replacement，核对原捕获 shader 和 EID；用户 Texture Viewer 已处于
   ClearBeforeDraw/Pass 时要求先关闭该模式，不静默修改显示。
2. 完整重放两次原基线，分别导出普通 MRT 原始字节与 ClearBeforeDraw RGBA，核实稳定。
3. 编译并 Apply，强制从事件 0 回放到目标 EID，核实实际绑定的 shader hash/反射资源 ID，
   导出 applied 的普通 MRT 和独立 ClearBeforeDraw 图。
4. 移除自身 Replacement，核实原 shader 恢复，重新回放，导出 reset 的同设置证据。
5. 主进程比较完整解码 RGBA（阈值固定 0）及所有有效颜色附件 view 的所有 mip/slice/sample
   原始字节。检查基线和末次 reset 一致、附件身份及证据完整、清理成功后给出结论。

目录包括 baseline_a、baseline_b、applied、reset，各有 ClearBeforeDraw RGBA、独立 alpha 图
及所有 MRT 子资源 .bin；另有可见 diff、RGBA 通道差图与 strict_validation.json。
记录差异像素数、最大通道差、包围盒/前 16 个位置、各 MRT 差异字节及源码/shader hash。
仅 PNG 编码/hash 不同而解码像素相同不算差异。alpha-only 变化在可见 diff 中也可见。

返回值明确分离：

- `operation_success`：执行与采集是否完成，不等于通过。
- `validation_status`：PASS / FAIL / INCOMPLETE / ERROR。
- `exact_match`、`can_promote`：只在证据完整、基线稳定、无未覆盖项、全部零差异且清理成功时为 true。
- 非零差异 FAIL；缺证据/漂移/未覆盖 INCOMPLETE；编译/取消/超时/失联清理错误 ERROR。

目前绑定深度模板、UAV/可写资源、stream-out、predication、动态 shader linkage、非颜色输出，
以及不支持的原始格式/3D 目标会拒绝通过或标记未覆盖。uniform/不可见 ClearBeforeDraw 也不通过。
`max_subresources=256` 可设置 1～4096；超预算不截断验收。回放预算 240 秒，Bridge 等待 300 秒；
原生调用卡死无法在 Python 内强行中断，主进程超时返回未知清理状态并保留 namespace 锁。
所有验证仅针对当前捕获的指定事件，不证明其他场景或整个 shader 的通用等价。

2026-10-10 已按用户授权完成本机 Bridge 部署、重启和新增路由连通性验证；真实捕获 Overlay/Apply/Reset 验收尚未执行。模拟测试与连通性验证不证明实际 Overlay 已正确导出。不会修改 Unity 资产。

## 示例

```json
{
  "event_id": 852,
  "output_dir": "D:\\_Proj\\QTAU6\\Assets\\EndField\\Elwin",
  "prefix": "skin"
}
```

输出目录大致如下：

```text
skin_eid_852/
  skin_vsin.json
  skin_vsout.json
  skin_manifest.json
  skin_textures/
    skin_pixel_t0_xxx.png
    skin_rt_color0_eid852_xxx.png
```