Untoon Engine

Upstream-Merge-Checklist

本页目录

上游合并检查清单

目标

release -> untoon 同步时，用这份清单过一遍高风险区域。

合并前

动手之前先确认：

  • 当前 untoon 工作区干净
  • 已记录本次同步目标版本
  • 已知 Untoon 关键改动区域清单是最新的
  • 当前 Wiki 与 README 已更新到最近一次架构状态

高风险目录

每次同步优先看这些目录：

  • Engine/Source/Runtime/Engine/Private/Materials
  • Engine/Source/Runtime/Engine/Private/ShaderCompiler
  • Engine/Source/Runtime/Engine/Private/SceneTexturesConfig.cpp
  • Engine/Source/Runtime/Renderer/Private
  • Engine/Source/Runtime/Renderer/Internal
  • Engine/Source/Runtime/RenderCore
  • Engine/Shaders/Private
  • Engine/Shaders/Private/Untoon
  • Engine/Source/Runtime/Renderer/Private/Untoon

Marker 检查

合并或解决冲突时必须确认：

  • 上游引擎文件中的 Untoon 改动仍位于 Untoon Engine Start/End marker 内
  • Engine/Shaders/Private/Untoon 内文件不需要 marker
  • Engine/Source/Runtime/Renderer/Private/Untoon 内文件不需要 marker
  • marker 不嵌套；如果冲突解决后出现嵌套 marker，需要合并为单层
  • 新增 Untoon 改动使用最小合理 marker 范围

必查项目

Shading Model

  • MSM_Untoon 是否仍然正确注册
  • Shading Model 枚举值变更是否影响兼容性
  • 调试视图和材质编译路径是否仍然覆盖 Untoon

GBuffer

  • GBufferToon 是否仍然正确绑定
  • Slot 变化是否影响 Untoon 数据读写
  • 编码/解码函数是否与数据结构一致

材质节点

  • Toon Light
  • ToonShadowMask
  • ToonPassSwitch

需要确认：

  • 节点仍能正常编译
  • 输出函数名没有与上游逻辑冲突
  • 新的编译器/翻译器改动没有绕开 Untoon 输出

渲染 Pass

  • RenderToonBasePass 是否仍按当前设计保持禁用；若要重新启用，必须重新确认 UntoonShadow R/G/B 通道语义
  • Untoon Light Pass 是否仍然执行
  • Shadow Mask 与 Blur 是否仍然接通
  • Outline 是否仍然在正确阶段合成

灯光参数

  • Light|Toon 属性是否仍然传递到渲染线程
  • LightSceneProxy 参数结构是否仍然对齐
  • GPUScene 中的参数复制是否仍然正确
  • 所有 GetLightShaderParameters 重载是否仍然填满全部 Untoon 字段：FLightRenderParameters 不做清零，漏填会把未初始化数据写进 GPU Scene 灯光缓冲并触发 stale 告警（方向光的 UntoonLightFlatten / FlattenDistance 固定为 0）
  • 非投影局部灯的半径更新是否仍通过 ULightComponent::UpdateProxy 路径：直接改代理会让 SceneLightInfoUpdates 变更集缺失该灯，导致 GPU Scene 数据滞后

场景与后处理参数

  • Untoon Diffuse 系列参数是否仍然参与视图融合
  • Lumen 相关路径是否仍然读取这些参数

Shader 编译

  • Shader 是否全量通过编译
  • Untoon 专用 Shader 是否有宏失配
  • Shader Debug Dump 是否可用于排查
  • marker 是否仍符合 维护者规则

合并后验证

同步完成后至少验证：

  1. 编辑器可启动
  2. Untoon 材质可编译
  3. Untoon 灯光可生效
  4. Untoon Shadow Mask 可工作
  5. Outline 合成无明显异常
  6. Lumen 路径无明显回归
  7. Ray Tracing 路径无编译错误

建议记录

每次同步后记下：

  • 合并来源版本
  • 冲突文件清单
  • 手工处理策略
  • 新增上游结构变化
  • 已知未解决问题
  • 是否涉及 marker 调整或 Untoon 自有目录移动

最近一次同步记录（5.8.1 → 5.8.2）

  • 合并来源版本：Unreal Engine 5.8.2 release（16d75d847145）
  • 集成分支：codex/merge-release-5.8.2-into-untoon
  • 上游提交范围：5.8.1（71fe36aac5a8）→ 5.8.2，共 242 个提交，涉及 403 个文件（+8558/-2535）
  • 冲突文件清单（0）：无手工冲突；git merge-tree 预检与 ort 合并均干净
  • 手工处理策略：全部文件自动合并；7 个含 marker 的渲染/材质文件（SceneTextures.cpp、BasePassRendering.cpp、SceneVisibility.cpp、IndirectLightRendering.cpp、MaterialInstance.cpp、MaterialInterface.cpp、MaterialAttributeDefinitionMap.cpp）合并后 marker 内容与合并前完全一致（共 23 个 marker 块）
  • 新增上游结构变化：Translucent 半透明 Stencil Mask 重构（新增 TranslucentRenderStateNeedsStencilMask）、Velocity 格式统一为 FVelocityRendering::GetFormat、UserSceneTexture VR 分屏 tile rect 修复、材质参数查询 CheckNonOverrides 路径重构、CacheTexturesSamplingInfo 异步线程安全修复、自定义输出节点未连接输入跳过、Substrate 相关修复等；未触碰 GBufferToon/GBuffer 布局及 Untoon 依赖头文件
  • 已知未解决问题：编译与运行验证未执行（仓库规范禁止编译），需手动验证编辑器启动、Untoon 材质编译、灯光/Shadow Mask/Outline/Lumen/Ray Tracing 路径
  • marker 调整：无嵌套、无丢失、无新增删除；Untoon 自有目录未移动