1. UE5渲染管线源码的整体地图
UE5 的渲染管线源码，平时在项目里接触最多的就是 Renderer 模块。每次翻源码之前我都要先问自己一个问题：你到底想解决什么问题？如果你想写自定义 Pass、改材质渲染链路、排查 GPU 卡顿，源码就是最终答案。很多人被渲染管线这四个字吓住，觉得几千个文件没法下手，其实它有一条非常清晰的骨架线：入口、资源、Pass。这篇分享我把我自己的源码阅读路径整理出来，从目录结构到核心 Pass，再穿插一些我实改渲染时踩过的坑，给后面想往引擎底层走的开发者一条可复制的路线。
你不需要把 UE5 渲染管线全部背下来，但你需要知道它在哪几个文件里、每个文件承担什么角色、Pass 与 Pass 之间怎么串联。这些搞定了，剩下就是索引的问题。
1.1 Renderer 模块的目录结构与关键文件
先说说最核心的三个目录：
Engine/Source/Runtime/Renderer：场景渲染算法层，BasePass、阴影、光照、后处理、Nanite、Lumen 的 Pass 大多在这里。Engine/Source/Runtime/RenderCore：渲染基础设施，包括 RenderGraph（RDG）、渲染线程与 RHI 的桥接层。Engine/Source/Runtime/RHI：底层图形 API 的抽象封装，D3D12、Vulkan、Metal 都挂在下层。
如果你要读管线源码，90% 的时间都会耗在第一个目录。里面真正的高频文件其实就这几个：DeferredShadingRenderer.cpp、BasePassRendering.cpp、LightRendering.cpp、SceneRenderer.cpp、PostProcess/PostProcessing.cpp，以及Nanite/和Lumen/两个子目录。
我用一个表格把它们对应起来：
| 文件 | 对应的渲染阶段 | 你需要关注的函数或类 |
|---|---|---|
| SceneRenderer.cpp | 渲染入口与调度 | FSceneRenderer::Render |
| DeferredShadingRenderer.cpp | 延迟渲染主流程 | FDeferredShadingSceneRenderer::Render |
| BasePassRendering.cpp | 几何体 GBuffer 填充 | FBasePassMeshProcessor |
| LightRendering.cpp | 直接光照与逐光源绘制 | TLightPixelShader |
| PostProcessing.cpp | 色调映射与后处理链 | FPostProcessing::Process |
| Nanite/ | 虚拟几何体光栅化 | Nanite::FSharedContext |
| Lumen/ | 全局光照与反射 | FLumenSceneData |
我自己读源码的习惯是先看DeferredShadingRenderer.cpp的 Render 函数。它是整个管线的调度中枢，像舞台导演一样把每个 Pass 按顺序推给 RenderGraph。如果你直接一头扎进某个 Pass 的实现，很容易迷路。
1.2 SceneRenderer 为什么是总调度中心
UE5 桌面端的默认渲染路径是延迟渲染，入口类是FDeferredShadingSceneRenderer。它的Render()函数，顺序大致是这样的：
- InitViews：做可见性剔除、收集 MeshDrawCommand、创建视图信息。
- RenderPrePass / RenderBasePass：先写深度，再输出 GBuffer。
- RenderShadowDepthMaps：生成阴影深度。
- RenderLights：把所有光源的 G-Buffer 计算结果合入 SceneColor。
- RenderFog：体积雾与高度雾。
- RenderTranslucency：半透明物体单独绘制。
- RenderPostProcessing：从 SceneColor 到最终 BackBuffer 的后处理链路。
不同 UE5 小版本函数名会有调整，比如 5.1 和 5.4 的 BasePass 调度就改过，但大顺序基本没变。你只要把这七个阶段列在纸上，然后对着源码一步一步找，就不会被各种 Switch 分支带跑。
这里有一个很多新手容易忽略的点：渲染管线的数据源不是游戏对象，而是场景代理。当你看到游戏线程里的AActor时，它不会直接进入渲染流程。每个可渲染组件会创建一个FPrimitiveSceneProxy，组件在场景更新时把几何数据打包成FMeshBatch提交给渲染线程。渲染线程手里的 Scene，是由这些代理组成的。所以读源码时如果发现某个物体没显示，先问它的 Proxy 有没有被创建，再问它的 MeshDrawCommand 有没有被收集，最后才轮到 Pass 本身。
1.3 从组件到 MeshBatch 的调用链
举个例子，静态网格体组件的调用链大致是：
UStaticMeshComponent::CreateSceneProxy->FStaticMeshSceneProxy->GetMeshElement/DrawStaticElements->FMeshBatch-> 渲染线程的AddPrimitive。
这条链你把断点打在AddPrimitive上，就能看到所有提交到场景的 MeshBatch。理解这条链对自定义渲染非常关键，因为你的自定义 Pass 如果走的是场景绘制流程，也必须交出FMeshBatch并指定对应的FMeshBatchElement，否则引擎不会自动帮你画它。
2. RenderGraph：管线的电源板设计
UE5 渲染管线源码分析里，绕不开的就是 RenderGraph，也就是 RDG。UE4 时代渲染 Pass 之间经常手动管理资源状态、手动切换 Render Target，那时候写一个跨 Pass 共享资源的渲染功能非常痛苦：你要关心资源该被创建几次、该在哪个阶段转换成哪种状态，漏一步就黑屏或报资源绑定错误。
RDG 的出现把这套逻辑集中管理起来了。它像是给管线发了一块电源插线板，所有 Pass 告诉你“我要读什么、我要写什么”，RDG 在真正执行前自动推导资源生命周期、自动插入状态转换和同步。
2.1 资源声明与 AddPass 的对应关系
RDG 的核心逻辑在RenderGraphBuilder里。最常见的写法是这样：
FRDGTextureRef SceneColor = GraphBuilder.CreateTexture(Desc, TEXT("SceneColor")); GraphBuilder.AddPass( RDG_EVENT_NAME("MyCustomPass"), ERDGPassFlags::Raster, [SceneColor](FRHICommandList& RHICmdList) { // 在这里调用 DrawPrimitive 或设置 PSO });这段代码揭示了几件事：第一，CreateTexture并不会立即创建真正的 GPU 资源，它只是登记资源描述，叫做渲染图资源对象；第二，AddPass的回调也不是立即执行，RDG 会先收集完所有 Pass 和资源依赖，再在合适的时机实际执行；第三，Pass 闭包里捕获的资源引用，只能在执行期间使用，不能在 Pass 外提前访问。
我最早写自定义渲染功能时踩过一个坑：在 AddPass 外拿不到 SceneColor 内容，就手动调用GraphBuilder.QueueTextureExtraction去读，结果在移动端上得到空数据。原因就是资源还没有被写入。你要做回读，应该把回读依赖也放进 RDG 的依赖图里，或者用AddCopyTexturePass把结果拷贝到一个能被回读的外部纹理。
2.2 依赖推导与异步计算
RDG 还有一个很实用的设计：资源状态自动转换。以前你如果要让一张纹理从 RenderTarget 变成 ShaderResource，需要在两处手动设Transition，忘了就出问题。RDG 会根据 Pass 的读取和写入标记自动生成 Barrier。所以你在源码里经常看到 Pass 只是简单写上ERDGPassFlags::Raster或ERDGPassFlags::Compute，剩下的交给 RDG 处理。
异步计算也是 RDG 的强项。你可以把某些纯 Compute 的 Pass 标记为ERDGPassFlags::AsyncCompute，让它在部分 GPU 架构上和光栅化 Pass 并行执行。但不要以为标了就一定变快，异步计算可能造成额外同步开销，尤其在小粒度的 Pass 上，性能可能反而下降。
如果你要从源码层面排查 RDG 问题，有两条 CVar 非常有用：
| CVar | 作用 |
|---|---|
| r.RDG.Debug | 启用后 RDG 会输出大量 Pass 验证信息，资源被非法引用时直接报错 |
| r.RDG.ImmediateMode | 绕过调度，Pass 立即执行，方便用 RenderDoc 定位问题，但性能较差 |
Debug 模式下最常见的报错是 “Resource is not available” 或 “Pass not culled”。前者说明你访问了一个生命周期已经被结束的资源，后者说明你的 Pass 不在任意资源的依赖链上，RDG 认为它可以安全跳过。后者尤其坑，因为很多自定义 Pass 看起来“没执行”，其实是 RDG 判定它没有副作用。
2.3 怎么从源码中看懂一个 Pass 做了什么
我读 Pass 时一般只关注三件事：输入资源、输出资源、修改了哪个管线状态。输入输出资源可以从AddPass的参数列表里看出来；管线状态则需要看闭包里的 RHI 命令。
用 RDG_EVENT_NAME 标记的 Pass 名称，在 RenderDoc 和 GPU 调试器里会显示成清晰的事件层级。比如你在 RenderDoc 里看到 “BasePass” 节点下又有很多子节点，那通常对应 MeshDrawCommand 的分组合并。遇到官方文档没写清楚的功能，先用 RenderDoc 抓一帧，看看名字叫 XXX 的 Pass 出现在管线哪个位置、前后分别是什么，这是最直观的理解方式。
3. BasePass 与 GBuffer：管线的地基
如果说 RDG 是管线骨架，那 BasePass 就是地基。我们常说的 PBR 渲染、材质模型、贴图采样，很大一部分都在 BasePass 这一层解决。它的职责很纯粹：把场景里所有可见的、不透明且能写到 GBuffer 的几何体画一遍，把光照计算所需的材质属性编码进若干张 Render Target。
3.1 BasePass 究竟做了什么
BasePass 的代码在BasePassRendering.cpp，它不是一个单一 DrawCall，而是一整个绘制流程。它通过FBasePassMeshProcessor把每个物体的FMeshBatch处理成MeshDrawCommand，再按管线状态排序后提交。
这里有一个核心概念：FMeshDrawCommand。它把一次 DrawCall 所需的 PSO、资源绑定、Shader 参数全部打包成一个命令。BasePass 会为同一个物体生成多个 MeshDrawCommand，比如有 Depth-Only 的版本，也有输出 GBuffer 的版本。你在源码里看到bDepthOnly、bDecal之类的分支，就是引擎在不同场景下对同一几何体的复用策略。
3.2 GBuffer 布局与材质输出的映射
UE5 桌面端的 GBuffer 格式，大致可以分成五张 Target。我这里写的是经过多年沉淀后的经典布局：
| Render Target | 内容 |
|---|---|
| GBufferA | WorldNormal、PerObjectData |
| GBufferB | Metallic、Specular、Roughness、ShadingModel、SelectiveOutputMask |
| GBufferC | BaseColor、AO |
| GBufferD | CustomData，视材质而定 |
| GBufferE | PreShadow、SubsurfaceProfile 等辅助数据 |
材质面板里的 BaseColor、Roughness、Metallic 并不是直接对应线性浮点，而是经过编码写入这些半浮点或 RGB10A2 的 Target 里。你在自定义 Shader 里取GBuffer.BufferA等变量时，看到的是解码后的结果，但要注意 ShadingModel 会被压缩在有限比特里。如果你自定义了 ShadingModel，必须在相关头文件里注册枚举值，并在 GBuffer 编码、解码、光照响应三处同步修改，少改一处就会出现“角色变成一块黑”或“光照计算完全错误”的问题。
我自己的建议是：除非你非常确定要改光照算法，否则不要轻易扩展 GBuffer。新增一个材质属性，让美术在自定义深度通道里保存一张额外贴图，比改造整套 GBuffer 要稳得多。
3.3 MeshDrawCommand 合批与动态实例化
BasePass 为什么能一个 DrawCall 绘制大量同材质物体？因为网格绘制命令会按 PSO、顶点工厂、资源绑定排序，引擎可以合并相邻的同状态 DrawCall。两个 MeshDrawCommand 要能合并，前提是它们的 VertexFactory、PixelShader、管线状态完全一致，只有 Transform 或 Stencil 这类 Per-Draw 数据不同才可以走实例化。
如果你想通过自定义 Pass 复刻 BasePass 的效果，会遇到一个常见问题：你拿不到某个物体的 MeshDrawCommand。这不是引擎“不给你”，而是因为 MeshDrawCommand 是在 InitViews 阶段生成的，它和当前 Pass 的视口参数、阴影状态强相关。你在后续阶段想要，通常得重新收集可见性或者干脆复用FViewInfo里的可见网格列表。
4. 阴影、光照与后处理链路
BasePass 输出 GBuffer 之后，接下来最耗 GPU 的就是阴影、光照和后处理。很多性能问题排查最后都落在这一截。阅读这部分源码时，你要有“一个 Pass 处理一件事”的心态，而不是期待一个大函数搞定一切。
4.1 Shadow Depth Pass 与阴影降级链
阴影不是光照的一部分，它在光照之前就要生成。UE5 会把所有需要投影的光源阴影深度，先渲染到ShadowDepthMaps里，光照 Pass 再去采样这些阴影。桌面端 UE5 默认使用的是 Virtual Shadow Maps（VSM），它以 Nanite 和更粗粒度的 Page 方式管理阴影，而不是传统 CSM。如果你在源码里找级联阴影，可以先看VirtualShadowMapArray这个类。
阴影相关排查经常遇到两个现象：阴影闪烁，或边缘漏光。闪烁通常与 shadow map 的 Page 分配抖动有关；漏光多半是深度偏移不够或 Page 分辨率不足。先用某个 CVar 或控制台命令查看 VSM 的 Page 分配情况，比直接改采样函数要快得多。
4.2 光照 Pass 与自定义光照模型
光照代码集中在LightRendering.cpp和DeferredShadingRenderer.cpp的RenderLights系列函数。延迟光照阶段会遍历所有光源，把 GBuffer 解码出来的材质属性，和光源的衰减、阴影、光照通道相乘，最终累加到 SceneColor。
源码里最值得读的是光影如何在像素着色器中组合。你可以找到TLightPixelShader，它接收光源类型参数，在内部处理点光、聚光和方向光。如果只想加一个简单的自定义光源类型，工程量大不大？我的经验是：如果你只在已有光源类型上调衰减公式，工作量很小；但要新增一种数据结构和光照模式，必须修改光源基类、渲染器生成逻辑、Shader 内分支，三处联动，不推荐现在动手。
4.3 后处理链路从 SceneColor 到屏幕
后处理源码主要在PostProcess/目录。它是一长串 RDG Pass，常见的顺序是：景深、Bloom、镜头光晕、TAA/FSR、色彩校正、色调映射、最终输出。这个链路的起点是 SceneColor，终点是SceneView对应的 BackBuffer。
每个后处理阶段是否启用，由后处理体积的插值参数决定。源码阅读时，FPostProcessing::Process是最适合打断点的入口。如果你要做自定义后处理，通常不需要直接改源码，更稳定的方式是创建后处理材质放进 Post Process Volume。但如果你要做性能剖析，那么盯住 SceneColor 格式和分辨率变化就够了：Bloom Pass 可能在半分辨率上运算，ToneMapping 只处理 LDR 范围，这些差异往往才是性能瓶颈。
5. Nanite 与 Lumen 的源码落点
UE5 渲染管线越来越复杂，很大程度是因为 Nanite 和 Lumen 这两套新系统被塞进了延迟渲染流程。它们不像原来那样只是增加几个 Pass，而是重构了基元生成和光照更新的方式。
5.1 Nanite 重写了什么
Nanite 的网格数据不再以传统 IndexBuffer 为主，而是用 Cluster 层级剔除和 Compute 着色器做光栅化，最后写入 Visibility Buffer。这个缓冲区里存的不是颜色，而是每个像素对应的 Cluster 和三角形信息。材质阶段再通过NaniteMaterial解开这些信息，走一遍类似 BasePass 的材质输出流程。
源码里你可以重点看NaniteRenderer.cpp和Nanite/NaniteShared.h。你会看到大量DispatchComputeShader的调用，以及围绕 Cluster 的 BVH 剔除过程。如果你只是想给 Nanite 网格加一个类似轮廓线的效果，不要直接改 Nanite 内部光栅化，而是利用后处理阶段读取 Visibility Buffer 信息，或者使用 GBuffer 中已有的法线、深度做边缘检测。
5.2 Lumen 的全局光照路径
Lumen 不是一个独立 Pass，而是分散在很多地方的系统。它包含场景表示更新、Radiance Cache 更新、Screen Probe 采样、反射追踪等。对应源码中的Lumen/LumenScene.cpp和Lumen/LumenRadianceCache.cpp。
桌面端 Lumen 默认会用硬件光追加速某些步骤，但本质还是用球谐或一束束短射线去近似光照反弹。你不需要也没必要读完全部实现，只需要知道一个排查方向：画面里出现烘焙后的光照没有实时跟随场景变化，多半是 Lumen 的 Radiance Cache 更新频率不够，或者任意物体的 MeshCard 没有参与 Lumen 场景。
5.3 移动端与桌面端的分支差异
如果你做移动端项目，直接看桌面端 BasePass 源码可能会被带偏。UE5 的移动端在很多平台上默认走 Forward 渲染，而不是桌面端的 Deferred。移动端有自己的MobileRenderer/FMobileSceneRenderer，GBuffer 只保留移动 ShadingModel 需要的信息，后处理链路也更简化。
跨平台移植时，我习惯在两个路径的交汇处做一次“源码映射”：先把 GPU 帧抓下来，对比桌面端和移动端 Pass 名称列表，数一数差在哪里，再回到DeferredShadingRenderer和MobileShadingRenderer里找对应分支。不要把两套渲染器混为一谈，否则排查问题时会越查越乱。
6. 实战调试：如何验证自己对源码的判断
读源码最怕的就是“看懂了但没验证”。UE5 源码量大、宏多、模板嵌套深，很容易造成错觉。我自己现在做源码级排查时，会固定走以下流程，效率比纯靠翻文件高不少。
6.1 打断点与日志的关键位置
如果你想确认某个 Pass 是否被调用，先在AddPass那一行打断点。如果你捕获不以 GPU 事件为主，而是捕获 CPU 调用栈，那么 Visual Studio 或 Rider 的调用栈会把你带回 RDG 的调度层。
需要确认资源状态时，用UE_LOG不如用引擎自带的RDG_EVENT_NAME输出方便。你可以在 Pass 闭包开头写一个只有 Debug 编译开才生效的日志，输出资源描述信息，这样引擎在真正执行时才会打印。
6.2 用 RenderDoc 观察 RDG 资源
RenderDoc 对 UE5 的支持已经比较成熟，但要记得在启动参数里加上相应调试插件，或者直接点击引擎工具栏的 RenderDoc 按钮。抓帧后不要只看单个 DrawCall，重点看 Resource 标签下的RDG名称，那些名称就是你在AddPass里写的字符串。
RDG 资源在 RenderDoc 里通常能直接看到 bound 状态和内容。如果某张 GBuffer 纹理是纯黑色，但代码流程看起来应该写了，优先检查两次 Pass 之间的依赖关系，再看 PSO 是否绑定到了正确的 Slot。很多自定义 Shader 的绑定错误不会立刻崩溃，只会输出黑屏或莫名颜色。
6.3 常见问题排查速查表
| 症状 | 可能原因 | 优先排查位置 |
|---|---|---|
| 场景全黑 | SceneColor 未被写入，或 RDG 依赖缺失 | RenderDoc 看资源内容，检查 AddPass 输出标记 |
| 金属物体颜色异常 | GBufferB 编码被自定义 Shader 覆盖 | BasePass 编码代码 |
| 阴影闪烁或漏光 | VSM Page 分配抖动，深度偏移不足 | ShadowDepthPass 与 VSM Page 可视化 |
| 自定义 Pass 不执行 | RDG 把它裁掉了，因为没有副作用 | r.RDG.Debug 输出，检查 Pass 依赖输入 |
| 移动端效果和桌面端差异巨大 | 渲染路径不同，移动端是 Forward | MobileRenderer 分支 |
| 后处理颜色过曝 | 自定义 Pass 写入 SceneColor 时没有处理 HDR 范围 | 检查 SceneColor 格式与 ToneMapping 位置 |
6.4 一个我常用的源码版本追踪技巧
每次引擎大版本升级，不要从头重读源码，直接对比Renderer/Private目录下新增文件和改动最大文件的提交记录。比如 5.0 引入 Nanite，5.1 大量改 Lumen，5.3 后加入更多路径追踪选项。你先看到“新东西在哪”，再回到你已经熟悉的延迟渲染主流程里看它被插在了哪个位置。这样学习成本最低，也不会被无关改动干扰。
我个人在实际操作中的体会是，UE5 渲染管线源码千万别通读，要带着任务读。你想改阴影，就从 Shadow 的 Pass 入口顺藤摸瓜；你想排查后处理颜色变化，就从 PostProcessing 开头一路追到输出。源码本身是信息量很大的索引，而不是背诵材料。你不需要记住每一行，但你需要知道一个 Pass 为什么存在、它连接了哪些资源、它修改了什么状态。
最后分享一个小习惯：我日常改动渲染相关功能时，会把ShowMaterialDrawEvents这个控制台变量打开。它能给每个网格绘制事件挂上材质和组件信息，在 RenderDoc 或 GPU 视图里一眼看清每个 DrawCall 属于谁。遇到任何“为什么这个物体没生效”的问题，先用它定位事件名，再去源码里反向寻找对应 Pass 和绑定逻辑。这个方法我用了很多年，简单又高效，希望也对你有用。
