在 Unreal Engine 中处理材质、动态材质…

适用于 Unreal Engine 项目需要从 C++ 处理材质、动态材质实例、参数集合、后处理、渲染目标、贴花及 UE5 渲染特性的场景。

适用场景

解决思路

1. 读取 `.agents/ue-project-context.md`，提取引擎版本（UE5.0–5.4 API 有差异，如 `SetNaniteOverride` 在 5.x 加入、`CopyScalarAndVectorParameters` 签名在 5.7 变化）、目标平台（Mobile 需要 forward rendering，许多后处理仅桌面可用）、渲染设置（Nanite/Lumen 是否启用影响材质特性安全性）、模块名（用于正确的 `#include` 路径和 `Build.cs` 依赖）；文件缺失时先询问引擎版本和目标平台再继续。
2. 询问用户需要哪个渲染领域：1) Dynamic Material Instances (MID)；2) Material Parameter Collections；3) Post-Process；4) Render Targets；5) Decals；6) Rendering Pipeline / UE5 Features（Nanite、Lumen、Virtual Shadow Maps、custom depth/stencil）；可组合多个领域。
3. Pattern A — 从 `UMaterialInterface` 创建独立 MID（不绑定组件 slot）：用 `LoadObject<UMaterialInterface>(nullptr, TEXT("/Game/Materials/M_MyBase.M_MyBase"))` 加载基础材质，再 `UMaterialInstanceDynamic::Create(BaseMat, this)`，在 BeginPlay 或等价初始化时调用一次并缓存。
4. Pattern B — 通过组件 slot 创建 MID（网格优先）：`MeshComponent->CreateDynamicMaterialInstance(0, nullptr, TEXT("MyMID"))`；签名 `CreateDynamicMaterialInstance(int32 ElementIndex, UMaterialInterface* SourceMaterial = nullptr, FName OptionalName = NAME_None)`，自动分配到对应 slot，SourceMaterial 传 nullptr 时使用 slot 当前材质作为父材质。
5. 设置 MID 参数：`MyMID->SetScalarParameterValue(TEXT("Opacity"), 0.5f)`；`MyMID->SetVectorParameterValue(TEXT("BaseColor"), FLinearColor(1.f, 0.2f, 0.1f, 1.f))`；`MyMID->SetVectorParameterValue(TEXT("Offset"), FLinearColor(0.f, 0.f, 100.f, 0.f))` 用 FLinearColor 的 XYZ 传偏移；`MyMID->SetTextureParameterValue(TEXT("DamageMask"), MyTexture)`，也可把 RenderTargetAsset 当 texture 传入。完整签名：`SetScalarParameterValue(FName ParameterName, float Value)`、`SetVectorParameterValue(FName ParameterName, FLinearColor Value)`（不能从 FVector 隐式转换）、`SetTextureParameterValue(FName ParameterName, UTexture* Value)`。
6. 高频更新用索引 API：初始化时对每个参数名调用 `MyMID->InitializeScalarParameterAndGetIndex(TEXT("Opacity"), 1.0f, OpacityIndex)`；Tick 中用 `if (OpacityIndex >= 0) { MyMID->SetScalarParameterByIndex(OpacityIndex, NewOpacity); }`；父材质改变会使索引失效，不要跨不同 MID 实例共享索引。
7. MID 生命周期与 GC：MID 是 UObject，无引用会被 GC；在类头用 `UPROPERTY() TObjectPtr<UMaterialInstanceDynamic> CachedMID;` 保持引用，绝不跨帧用裸指针或局部变量保存 MID。
8. 附加 MID 操作：`MyMID->K2_InterpolateMaterialInstanceParams(InstanceA, InstanceB, Alpha)` 在两个实例的 scalar/vector 参数间插值；UE5 用 `MyMID->SetNaniteOverride(NaniteCompatibleMaterial)` 分配 Nanite 兼容覆盖材质。
9. Material Parameter Collections：创建 `UMaterialParameterCollection` asset，材质中通过 `CollectionParameter` 表达式访问；一次 GPU buffer 更新会传播到所有引用材质。
10. 运行时设置 MPC：用 `UPROPERTY(EditAnywhere, Category="Rendering") TObjectPtr<UMaterialParameterCollection> GlobalRenderingCollection;` 持有资产；调用 `GetWorld()->GetParameterCollectionInstance(GlobalRenderingCollection)` 取得 per-world 实例，再 `Instance->SetScalarParameterValue(TEXT("RainIntensity"), RainIntensity)` 和 `Instance->SetVectorParameterValue(TEXT("FogColor"), FogColor)`。
11. MPC 限制：两个 setter 在参数名不存在时返回 false；参数名大小写敏感；每个 collection 最多 1024 个 scalar + 1024 个 vector；不支持 texture 参数；参数对 world 实例全局。
12. Post-Process Volumes：`APostProcessVolume` 包裹 `FPostProcessSettings`，控制相机进入 volume 内时的渲染，`bUnbound = true` 时全局生效。字段：`FPostProcessSettings Settings`；`float Priority`（重叠时高优先级胜，相等时顺序未定义）；`float BlendRadius`（世界空间 blend 距离 cm，仅 `bUnbound = false`）；`float BlendWeight`（0 无效果，1 全效果）；`uint32 bEnabled:1`；`uint32 bUnbound:1`。
13. 从 C++ 修改后处理 volume：设置 `PPV->bEnabled = true; PPV->bUnbound = true; PPV->BlendWeight = 1.0f;`；对要改的每个字段先设对应 `bOverride_* = true` 再设值，例如 `bOverride_BloomIntensity = true; BloomIntensity = 0.5f`、`bOverride_AutoExposureMinBrightness/MaxBrightness`、`bOverride_DepthOfFieldFstop/FocalDistance`（cm）、`bOverride_AmbientOcclusionIntensity`、`bOverride_VignetteIntensity`、`bOverride_ColorSaturation` 用 `FVector4(1.2f, 1.0f, 0.8f, 1.0f)` 按 RGBA 每通道、`bOverride_FilmSlope` 用 0–1（默认 0.88）；缺少 bOverride 会静默不生效。
14. Post-Process Materials (Blendables)：材质 Domain 必须设为 `Post Process`，用 `PPV->AddOrUpdateBlendable(PostProcessMaterial, 1.0f)` 添加，weight 0.0–1.0。
15. UPostProcessComponent（actor 自有）：构造中 `PostProcessComp = CreateDefaultSubobject<UPostProcessComponent>(TEXT("PostProcess"));`，设 `bUnbound = true; Priority = 5.0f;`，运行时设 `Settings.bOverride_BloomIntensity = true; Settings.BloomIntensity = 1.5f;`；include `Components/PostProcessComponent.h`、`Engine/PostProcessVolume.h`、`Engine/Scene.h`。
16. 创建 Render Target 方式 A：用 `UKismetRenderingLibrary::CreateRenderTarget2D(this, 512, 512, RTF_RGBA16f, FLinearColor::Black, false)`，参数依次为 WorldContextObject、Width、Height、Format、ClearColor、bAutoGenerateMipMaps，自动处理资源初始化。
17. 创建 Render Target 方式 B：`UTextureRenderTarget2D* RT = NewObject<UTextureRenderTarget2D>(this); RT->InitCustomFormat(512, 512, PF_FloatRGBA, true); RT->UpdateResourceImmediate(true);`，分别设置 force linear gamma 和 clear。
18. 选择 `ETextureRenderTargetFormat`：`RTF_RGBA8` 用于 LDR 颜色/UI；`RTF_RGBA8_SRGB` 用于 sRGB 颜色；`RTF_RGBA16f` 用于 HDR 颜色（默认）；`RTF_RGBA32f` 用于高精度数据；`RTF_R16f` 用于单通道数据；`RTF_RGB10A2` 用于显示输出。
19. Scene Capture（安防摄像头/小地图）：创建 `USceneCaptureComponent2D`，`SetupAttachment(RootComponent)`，设 `FOVAngle = 90.f`，`CaptureSource = ESceneCaptureSource::SCS_FinalColorLDR` 或 `SCS_SceneColorHDR`，`bCaptureEveryFrame = true`，`TextureTarget = MyRenderTargetAsset`；为性能可用 `ShowFlags.SetAtmosphere(false); ShowFlags.SetFog(false);` 限制捕获内容。
20. 把材质画到 Render Target：`UKismetRenderingLibrary::DrawMaterialToRenderTarget(this, RT, MyMaterial)` 会用材质渲染全屏 quad 到 TextureTarget；每次调用都设置 render target，开销大，批量绘制用 canvas API。
21. Canvas 批量绘制：`UKismetRenderingLibrary::BeginDrawCanvasToRenderTarget(this, RT, Canvas, CanvasSize, Context);`，在 Canvas 上绘制，例如 `Canvas->K2_DrawMaterial(MyMaterial, FVector2D(0, 0), CanvasSize, FVector2D(0, 0), FVector2D(1, 1));`，最后 `EndDrawCanvasToRenderTarget(this, Context);`。
22. `UCanvasRenderTarget2D` 是 `UTextureRenderTarget2D` 子类，带 `OnCanvasRenderTargetUpdate` delegate；用于自动 2D canvas 重绘（小地图、运行时纹理绘制），替代手动 `BeginDrawCanvasToRenderTarget`。
23. 读取像素：`ReadRenderTargetPixel(this, RT, X, Y)`、`ReadRenderTarget(this, RT, Pixels)`（整张 RT，8-bit sRGB）、`ReadRenderTargetRawPixel(this, RT, X, Y)` 会 stall GPU pipeline；仅限编辑器工具/截图，不要每帧调用；需要异步非阻塞读取时用 `FRHIGPUTextureReadback`。
24. Decal API：`SetDecalMaterial(UMaterialInterface* NewDecalMaterial)`；`CreateDynamicMaterialInstance()` 创建 decal MID；`SetFadeOut(float StartDelay, float Duration, bool DestroyOwnerAfterFade = true)`；`SetFadeIn(float StartDelay, float Duration)`；`SetSortOrder(int32 Value)`（越高越靠上）；`SetLifeSpan(float LifeSpan)`；`DecalSize` 是 local-space extent，不是 component scale。
25. 运行时生成 decal：`UDecalComponent* Decal = UGameplayStatics::SpawnDecalAtLocation(this, DecalMaterial, FVector(200.f), HitLocation, HitNormal.Rotation(), 0.0f);`；lifespan 0.0f 持久，>0.0f 自动销毁；再 `UMaterialInstanceDynamic* DecalMID = Decal->CreateDynamicMaterialInstance(); DecalMID->SetScalarParameterValue(TEXT("Opacity"), 0.8f);`。
26. DBuffer vs 非 DBuffer decals：DBuffer（Translucent + 启用 DBuffer）在光照前写入，影响 diffuse/normals/roughness，通过 `Project Settings > Rendering > DBuffer Decals` 启用；非 DBuffer 在光照后渲染，仅 emissive/opacity，更便宜但受限。
27. 关卡摆放 decals 用 `ADecalActor`（包装 `UDecalComponent`）；运行时生成优先用 `UGameplayStatics::SpawnDecalAtLocation` 或 `SpawnDecalAttached`。
28. Nanite 材质兼容规则：Opaque 材质兼容；Two-sided 材质兼容；Masked 材质兼容（需 `r.Nanite.AllowMaskedMaterials=1`）；Translucent 材质不兼容，会回退到非 Nanite 路径；World Position Offset (WPO) 在 UE 5.1+ 支持（mesh 上 `bEvaluateWorldPositionOffset`）；Pixel Depth Offset 不支持；通过 shader 的自定义顶点法线有限支持。
29. 运行时检查 Nanite：`bool bIsNanite = StaticMeshComponent->GetStaticMesh() && StaticMeshComponent->GetStaticMesh()->IsNaniteEnabled();`；注意 `IsNaniteEnabled` 在 `UStaticMesh` 上，不在 component 上。
30. 为 Nanite 路径覆盖材质：`MyMID->SetNaniteOverride(NaniteCompatibleMaterial);`。
31. Lumen：UE5 动态 GI 和反射系统；自发光表面可作为光源；默认不追踪 Translucent 表面；通过后处理设置控制质量：`bOverride_LumenReflectionQuality = true; LumenReflectionQuality = 1.0f`（0–4）、`bOverride_LumenSceneDetail = true; LumenSceneDetail = 1.0f`（surface cache 分辨率乘数）、`bOverride_LumenSceneLightingQuality = true; LumenSceneLightingQuality = 1.0f`；性能可用 `r.Lumen.SurfaceCache.UpdateDownsampleFactor` 控制 cache 更新率。
32. Deferred vs Forward：UE5 桌面默认 Deferred，几何写入 GBuffer 后逐像素光照；Forward（移动端、VR）逐物体处理光照，支持 MSAA，但限制动态光源数量；通过 `Project Settings > Rendering > Forward Shading` 设置。
33. Scalability：用 `Scalability::SetQualityLevels()`（`Scalability.h`）或控制台命令如 `sg.PostProcessQuality 0-3` 在运行时调整渲染质量；在 `BaseScalability.ini` 配置预设。
34. Virtual Shadow Maps (VSM)：WPO 材质需在材质 Details 面板启用 "Evaluate World Position Offset" 以正确投影 VSM 阴影（材质编辑器设置，不是 C++ 属性）；Masked 材质的 opacity mask 会被正确尊重；Decals 不投射 VSM 阴影。
35. Custom Depth / Stencil（描边和特效）：`MeshComponent->SetRenderCustomDepth(true); MeshComponent->SetCustomDepthStencilValue(1);`（0–255）；在后处理材质中采样 `CustomDepth` / `CustomStencil` 节点实现描边、X-ray、高亮；需启用 `Project Settings > Rendering > Custom Depth-Stencil Pass > Enabled with Stencil`。
36. 常见错误——每帧创建 MID：每次 `CreateDynamicMaterialInstance` 分配新 GPU 资源；应在 BeginPlay 创建一次并缓存，在 Tick 只更新参数。
37. 常见错误——不把 MID 缓存为 UPROPERTY：裸 `UMaterialInstanceDynamic*` 对 GC 不可见，会在下次 GC 被回收；用 `UPROPERTY() TObjectPtr<UMaterialInstanceDynamic> CachedMID;`。
38. 常见错误——参数名错误：参数名大小写敏感且必须精确匹配；`basecolor`、`Base Color`、`Base_Color` 在材质使用 `BaseColor` 时都会静默失败。
39. 常见错误——Render Target 分辨率不匹配用途：小地图/安防摄像头用 256–512，镜子最多 512；大镜子用 planar reflections；全屏可在 `USceneCaptureComponent2D` 上用 `bMainViewResolution`。
40. 常见错误——每帧读取 Render Target 像素：`ReadRenderTargetPixel` 会 stall GPU pipeline，绝不每帧调用；用 `FRHIGPUTextureReadback` 做异步非阻塞读取。
41. 常见错误——在复制 actor 上使用 MID：MID 是客户端本地对象，不要复制 MID 指针；改为复制 scalar/vector 值，并在每个客户端的 `OnRep` 函数中重新应用。
42. 常见错误——后处理未设置 bOverride：每个 `FPostProcessSettings` 字段都需要配对的 `bOverride_*` bool 设为 true；只设值不设 override 是静默 no-op。
43. 常见错误——Nanite 透明材质回退：Nanite mesh 上的 Translucent 材质会使整个 mesh 回退到非 Nanite 渲染；应拆分为单独的 opaque 和 translucent 组件。
44. Build.cs 依赖：添加 `PublicDependencyModuleNames.AddRange(new string[] { "Engine", "RenderCore", "RHI" });`；`Engine` 用于 Materials、render targets、`UTextureRenderTarget2D`；`RenderCore` 用于低层渲染工具；`RHI` 用于 RHI 类型（`EPixelFormat` 等）；`UKismetRenderingLibrary` 已随 `Engine` 提供，无需单独模块。
45. 相关技能协作：UObject/UPROPERTY/TObjectPtr/GC 参考 `ue-cpp-foundations`；组件设置（`UDecalComponent`、`USceneCaptureComponent2D`、`UPostProcessComponent`）参考 `ue-actor-component-architecture`；粒子材质与 Niagara 参数传递参考 `ue-niagara-effects`；引擎版本/目标平台/渲染特性开关参考 `ue-project-context`。

适用边界 · 注意事项

• 不适用于非 Unreal Engine 项目，也不适用于不需要材质/渲染 C++ 的场景。
• 未确认引擎版本与目标平台，或缺少 `.agents/ue-project-context.md` 时，不要直接给出依赖版本差异的 API 建议。
• 粒子渲染本身应使用 `ue-niagara-effects`，而不是本技能；纯 Niagara 粒子材质可参考本技能与 Niagara 技能协作。