RenderDoc 扩展工具集 — 技术原理解析

1
extension_name/
2
├── __init__.py       # Python 主模块，必须定义 register() 和 unregister()
3
└── extension.json    # 扩展元数据（名称、版本、作者、描述）

1
RenderDoc 启动
2
  └─> 扫描扩展目录（%APPDATA%/qrenderdoc/extensions/）
3
      └─> 读取 extension.json 获取元信息
4
          └─> 用户在 Manage Extensions 中启用扩展
5
              └─> import __init__ 模块
6
                  └─> 调用 register(version, ctx) 函数
7
                      └─> 扩展注册菜单项、面板等

1
extiface_version = 0          # 接口版本号，当前固定为 0
2

3
def register(version, ctx):   # 扩展加载时调用
4
    """
5
    version: RenderDoc 扩展接口版本
6
    ctx: CaptureContext 对象 — 扩展与 RenderDoc 交互的核心入口
7
    """
8
    pass
9

10
def unregister():             # 扩展卸载时调用
11
    pass

1
ctx.Extensions().RegisterWindowMenu(
2
    qrd.WindowMenu.Tools,                    # 菜单位置：Tools 菜单
3
    ["Texture Exporter", "Export All"],       # 菜单路径（支持多级）
4
    callback_function                        # 点击回调 callback(ctx, data)
5
)

1
┌─────────────────────┐     ┌──────────────────────┐
2
│     UI 线程 (主线程)    │     │   回放线程 (Replay)     │
3
│                     │     │                      │
4
│  - 菜单回调            │     │  - 重放 GPU 指令         │
5
│  - UI 控件操作          │     │  - 读取缓冲区数据          │
6
│  - 对话框显示            │     │  - 查询管线状态            │
7
│                     │     │  - 保存贴图到文件          │
8
│  ─── BlockInvoke() ──┼────>│                      │
9
│     (阻塞等待返回)        │<────┼── (执行完成，返回结果)       │
10
└─────────────────────┘     └──────────────────────┘

1
def _do_export(ctx, ...):
2
    result = [None]                    # 用列表在闭包间传递结果
3

4
    def _run(controller):              # 此函数在回放线程中执行
5
        result[0] = do_export(controller, ...)
6

7
    ctx.Replay().BlockInvoke(_run)     # 阻塞等待回放线程完成
8
    show_result(result[0])             # 回到 UI 线程显示结果

1
def _build_resource_name_map(controller):
2
    """构建 resourceId -> name 的映射表"""
3
    name_map = {}
4
    resources = controller.GetResources()    # 获取所有资源描述
5
    for res in resources:
6
        name_map[int(res.resourceId)] = res.name
7
    return name_map

1
GPU Pipeline 各阶段的资源绑定
2
├── SRV (Shader Resource View) — 着色器读取的贴图
3
│   ├── VS (顶点着色器) 的 SRV
4
│   ├── PS (像素着色器) 的 SRV ← 大部分纹理采样在这里
5
│   └── CS (计算着色器) 的 SRV
6
├── UAV (Unordered Access View) — 可读写的贴图/缓冲
7
│   └── 通常用于计算着色器输出
8
├── Render Targets — 渲染目标（帧缓冲颜色附件）
9
└── Depth Target — 深度/模板缓冲

1
def _extract_resource_id(obj):
2
    if hasattr(obj, 'resource'):      # 新版 API: Descriptor.resource
3
        return obj.resource
4
    if hasattr(obj, 'resourceId'):    # 旧版 API: .resourceId
5
        return obj.resourceId
6
    return rd.ResourceId.Null()

1
save = rd.TextureSave()
2
save.resourceId = tex.resourceId     # 要保存的贴图资源 ID
3
save.mip = mip_level                 # Mipmap 级别
4
save.slice.sliceIndex = slice_idx    # 数组/CubeMap/3D 切片索引
5
save.alpha = rd.AlphaMapping.Preserve  # Alpha 通道处理方式
6
save.destType = rd.FileType.DDS      # 目标文件格式
7

8
controller.SaveTexture(save, filepath)

1
{资源名称}_{宽}x{高}_{原始格式名}[_mip{N}][_面/切片].{扩展名}

1
def get_slice_count(tex, config):
2
    if tex.type == TextureCube:
3
        return 6 if config["cubemap_faces"] else 1
4
    elif tex.type == Texture3D:
5
        return tex.depth if config["slices_3d"] else 1
6
    elif tex.type in (Texture2DArray, ...):
7
        return tex.arraysize
8
    return 1

1
dialog = mqt.CreateToplevelWidget(title, on_closed)
2
# ... 添加控件 ...
3
mqt.ShowWidgetAsDialog(dialog)    # 以模态对话框形式显示

1
# 创建面板类实例
2
panel = TextureExporterPanel(ctx)
3
widget = panel.get_widget()
4

5
# 注册为 RenderDoc 可停靠窗口
6
ctx.AddDockWindow(widget, qrd.DockReference.MainToolArea, None)

1
def _on_open_panel(ctx, data):
2
    if _panel_widget is not None:
3
        ctx.RaiseDockWindow(_panel_widget)    # 已存在，提到前台
4
    else:
5
        _create_panel(ctx)                    # 首次创建

1
# 1. 跳转到目标 DrawCall 事件
2
controller.SetFrameEvent(action.eventId, True)
3

4
# 2. 获取当前管线状态快照
5
state = controller.GetPipelineState()
6

7
# 3. 获取 IA 阶段的配置
8
vbs = state.GetVBuffers()       # 顶点缓冲区绑定列表
9
ib = state.GetIBuffer()         # 索引缓冲区绑定
10
attrs = state.GetVertexInputs() # 顶点属性布局列表

1
if pos_attr is None:
2
    for attr in attrs:
3
        if attr.format.compCount >= 3 and attr.format.compType == Float:
4
            if not any_known_semantic(attr.name):
5
                pos_attr = attr    # 启发式选择

1
# 从管线状态获取 IB 信息
2
ib = state.GetIBuffer()
3
# ib.resourceId  — 索引缓冲区的 GPU 资源 ID
4
# ib.byteStride  — 每个索引的字节宽度（2 = uint16, 4 = uint32）
5
# ib.byteOffset  — 缓冲区起始偏移
6

7
# 从 DrawCall 获取索引范围
8
# action.numIndices    — 本次 DrawCall 使用的索引数量
9
# action.indexOffset   — 索引起始偏移（以索引为单位，非字节）
10
# action.flags         — 标志位，ActionFlags.Indexed 表示使用索引绘制

1
# 读取整个索引缓冲区的原始字节
2
ib_data = controller.GetBufferData(ib.resourceId, 0, 0)
3

4
# 计算实际字节偏移
5
byte_offset = action.indexOffset * ib.byteStride + ib.byteOffset
6

7
# 逐个解码索引
8
for i in range(num_indices):
9
    off = byte_offset + i * ib.byteStride
10
    if ib.byteStride == 2:
11
        index = struct.unpack_from('<H', ib_data, off)[0]    # uint16
12
    elif ib.byteStride == 4:
13
        index = struct.unpack_from('<I', ib_data, off)[0]    # uint32

1
VB0, stride=32:
2
┌─────────┬─────────┬────────┐
3
│ Vertex 0 │ Vertex 1 │ Vertex 2 │ ...
4
├─────────┼─────────┼────────┤
5
│ [Position: 12B] [Normal: 12B] [UV: 8B] │ → 共 32 字节 = stride
6
└─────────┴─────────┴────────┘

1
TEXCOORD0: float2 (R32G32_FLOAT)     → 一套 UV，直接使用
2
TEXCOORD1: float2 (R32G32_FLOAT)     → 第二套 UV

1
TEXCOORD0: float4 (R32G32B32A32_FLOAT)
2
  → xy 分量 = UV0
3
  → zw 分量 = UV1（两套 UV 打包进一个 float4）
4

5
TEXCOORD0: float3 (R32G32B32_FLOAT)
6
  → xy 分量 = UV
7
  → z 分量 = 额外数据（通常可忽略）

1
# 先读取属性的全部分量（如 float4 的 4 个分量）
2
raw_uvs = read_vertex_attr(attr, full_comp_count=4)
3

4
# 再提取需要的子分量
5
for uv in raw_uvs:
6
    u = uv[comp_start]        # 如 comp_start=2 → 取 z 分量
7
    v = uv[comp_start + 1]    # 取 w 分量

1
if len(uv_sets) > 1:
2
    unique_uv_sets = [uv_sets[0]]
3
    for ui in range(1, len(uv_sets)):
4
        if uv_sets[ui] != any_existing:
5
            unique_uv_sets.append(uv_sets[ui])

1
if flip_v:
2
    v = 1.0 - v

1
if swap_yz:
2
    y, z = z, y    # 位置和法线都需要交换

1
for v in vals:
2
    if not math.isfinite(v) or abs(v) > 1e9:
3
        cleaned.append(0.0)    # 将无效值替换为 0
4
    else:
5
        cleaned.append(v)

1
if all_range <= 1.0 and pos_attr.format.compType in (SNorm, UNorm):
2
    print("[WARN] Position data appears to be in normalized format.")
3
    print("       The mesh may need manual scaling.")

1
mesh_data = {
2
    "name":      str,              # DrawCall 名称
3
    "event_id":  int,              # Event ID
4
    "positions": [(x, y, z), ...], # 顶点位置列表（物体空间）
5
    "normals":   [(nx, ny, nz), ...],  # 法线列表（可能为空）
6
    "uvs":       [(u, v), ...],    # 第一套 UV（向后兼容）
7
    "uv_sets":   [                 # 所有 UV 通道
8
        [(u, v), ...],             #   UV channel 0
9
        [(u, v), ...],             #   UV channel 1
10
        ...
11
    ],
12
    "colors":    [(r, g, b, a), ...],  # 顶点色（可能为空）
13
    "indices":   [int, ...],       # 三角面索引（flat list, 每3个一组）
14
}

1
def _extract_resource_id(obj):
2
    if hasattr(obj, 'resource'):      # 新版 API
3
        return obj.resource
4
    if hasattr(obj, 'resourceId'):    # 旧版 API
5
        return obj.resourceId
6
    return rd.ResourceId.Null()

1
for item in ro_resources:
2
    if hasattr(item, 'descriptor'):       # 新版: UsedDescriptor
3
        rid = _extract_resource_id(item.descriptor)
4
    elif hasattr(item, 'resources'):      # 旧版: BoundResourceArray
5
        for res in item.resources:
6
            rid = _extract_resource_id(res)
7
    else:
8
        rid = _extract_resource_id(item)  # 直接尝试

1
菜单回调函数
2
└── try-except (最外层：防止菜单回调异常导致 RenderDoc 崩溃)
3
    └── BlockInvoke 内部回调
4
        └── try-except (回放线程层：捕获 GPU 数据访问异常)
5
            └── 单个 DrawCall / 贴图处理
6
                └── try-except (单项层：捕获单个资源的错误，跳过继续)

1
[DEBUG]  — 详细的中间数据（属性列表、数值范围、资源 ID 集合）
2
[INFO]   — 关键决策结果（属性映射、UV 去重）
3
[WARN]   — 可恢复的异常情况（属性缺失、数据不一致）
4
[ERROR]  — 不可恢复的错误