自动关联目录：RDG 渲染图

官方依据：Render Dependency Graph（UE 5.8 Documentation）。本页覆盖该页全部 36 个条目，并按本库标准重排为"模型 → 写法 → 参数 → 代价 → 排查"。

1. 定位

RDG（Render Dependency Graph / Render Graph）是一个立即模式 API：把渲染命令记录进一个图数据结构，之后再编译并执行。

一句话定位：RDG 把"手写渲染管线"里最容易出错的那几件事自动化了——资源生命周期、内存复用、屏障、并行录制、无用 pass 剔除。官方明确要求：所有高层渲染代码都应该用 RDG 写，延迟渲染器与移动端渲染器（及关联插件）都已转换。

它自动化的七件事：

2. 核心模型：Setup / Execute 两条时间线

Setup 时间线（构建图）
  创建资源描述符、做管线分支、AddPass 登记 lambda
        │
        │  RDG 编译：剔除、排生命周期、插屏障与 fence
        ▼
Execute 时间线（执行）
  跨多个线程调用 pass lambda，把命令录进 RHI 命令列表

因此有一条铁律：pass lambda 里不能有副作用，只应往命令列表里记录命令——因为执行可能被并行化。

GetRHI() 在任何其它地方调用都会触发校验层断言。

另一个硬约束：Graph Builder 的 API 是单线程的，同一时刻只能有一个实例——这排除了层级式或并列的图。延迟与移动端渲染器都是每次场景渲染用一个 builder。

3. 写法

参数结构体

BEGIN_SHADER_PARAMETER_STRUCT(FParameters, )
    SHADER_PARAMETER(FVector2D, HalfTexelSize)
    SHADER_PARAMETER(float, Level)
    SHADER_PARAMETER_RDG_TEXTURE_SRV(Texture2D, MipInSRV)
    SHADER_PARAMETER_SAMPLER(SamplerState, MipSampler)
    RENDER_TARGET_BINDING_SLOTS()
END_SHADER_PARAMETER_STRUCT()

赋 null 是允许的，RDG 会忽略——这是减少图复杂度的手段。

一个 pass

FMyCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FMyCS::FParameters>();
PassParameters->MipInSRV   = GraphBuilder.CreateSRV(FRDGTextureSRVDesc::CreateForMipLevel(Tex, Level-1));
PassParameters->MipOutUAV  = GraphBuilder.CreateUAV(FRDGTextureUAVDesc(Tex, Level));

GraphBuilder.AddPass(
    RDG_EVENT_NAME("GenerateMips DestMipLevel=%d", Level),
    PassParameters,
    ERDGPassFlags::Compute,
    [PassParameters, ComputeShader, GroupCount](FRHIComputeCommandList& RHICmdList)
    {
        FComputeShaderUtils::Dispatch(RHICmdList, ComputeShader, *PassParameters, GroupCount);
    });

命令列表类型的选择有性能含义：

• 计算 pass 用 FRHIComputeCommandList（异步与图形计算的共用接口）
• 光栅 pass 用 FRHICommandList
• 除非绝对必要，不要用 FRHICommandListImmediate——它会让该 pass 失去并行执行资格

光栅 pass 的 Load Action

Tile-based 硬件（移动端）上准确的 load action 直接决定性能。深度与模板各自单独指定，且需要 FExclusiveDepthStencil 控制读写权限。

内存生命周期（最常见的崩溃来源）

// 错！栈上对象被引用捕获，Execute 时已失效
FMyObject Object;
GraphBuilder.AddPass(..., [&Object](FRHICommandList&){ /* 悬垂 */ });

// 对：用 RDG 自带的线性分配器
FMyObject* Object = GraphBuilder.AllocObject<FMyObject>();   // 会调析构
FMyObject* Obj2   = GraphBuilder.AllocPOD<FMyObject>();      // POD，不调析构

分配的内存存活到 builder 销毁，线性分配器，很快。

资源：Transient vs External

// 提取：Execute 之后指针才被填充
TRefCountPtr<IPooledRenderTarget> ExtractedTexture;
GraphBuilder.QueueTextureExtraction(Texture, &ExtractedTexture);
GraphBuilder.Execute();
check(ExtractedTexture);

// 注册：下一个图里用
FRDGTexture* Tex2 = GraphBuilder.RegisterExternalTexture(ExtractedTexture);

• 注册 → 生命周期延伸到图的开头（因为分配发生在 setup 阶段）
• 提取 → 延伸到末尾
• ConvertToExternal 是替代方案：立即分配并返回，但它意味着该资源无法与帧内任何其它资源共享底层分配

RDG 资源指针归 Graph Builder 所有，builder 销毁后失效；执行结束后应把这些指针置空。

4. 参数与控制台变量

5. 性能剖析与可视化

它们接受 builder 作为输入，能正确处理 setup / execute 两条时间线的归属。

RDG Insights 插件（Edit > Plugins > Insights）能看：资源生命周期、pass 关联、资源池分配重叠、异步计算 fence 与重叠、图剔除与 render pass 合并、并行执行区间、瞬态内存布局。

典型用法：回答"为什么异步计算没有和图形 pass 重叠""某个资源分配和谁重叠了""哪些 pass 被剔除了"。

注意：RDG 轨迹数据量很大。

命名约定（影响可查性）

• 资源命名空间用点分隔：如 TSR.History.ScreenPercentage——这样在 RDG Insights 里过滤很方便
• builder 实例命名 GraphBuilder
• 着色器参数内联命名 FParameters
• 用 RDG_EVENT_SCOPE 作为 pass 的命名空间
• 优先用 RenderGraphUtils.h / ScreenPass.h 里的工具函数（FComputeShaderUtils::AddPass、FPixelShaderUtils::AddFullscreenPass）

6. 代价与权衡

7. 踩坑与排查

排查顺序

1. 崩溃在 lambda 里 → r.RDG.ImmediateMode=1 + r.RHICmdBypass 拿单一调用栈
2. 画面错误 → 先 r.RDG.TransientAllocator=0 对比（alias / 未初始化）
             再 r.RDG.ClobberResources 验证"读取前未初始化"
3. pass 没跑 → r.RDG.CullPasses=0 对比
4. 性能 → RDG Insights 看并行区间与异步计算重叠（profile 时 r.RDG.AsyncCompute=0）
5. 资源状态问题 → 两条 transition log 对齐后比对
6. 看具体资源 → vis 命令（Development 构建下 RDG 会发布所有 UAV/RTV 写入）

参考

• Render Dependency Graph
• Graphics Programming
• 管线与渲染线程 · 材质与着色器编译 · TSR 时域超分