UE 【材质扩展】从蓝图到C++：打造专属材质函数节点

1. 为什么需要自定义材质函数节点在Unreal Engine的材质编辑器中工作过一段时间的朋友应该都有这样的体验某些特定的材质效果需要反复搭建相同的节点组合。比如做一个简单的颜色混合效果每次都要拖拽三四个节点连来连去不仅效率低下还容易出错。这时候你就会想——要是能把这些常用逻辑打包成一个专属节点该多好。自定义材质函数节点的核心价值就在于封装复用。举个例子我最近在做的项目中需要频繁使用根据遮罩混合两种材质的功能。如果每次都重新搭建节点不仅浪费时间后期修改维护更是噩梦。而把它封装成自定义节点后只需要像调用普通函数一样拖出来就能用所有修改都在一个地方完成。从技术实现来看UE内置的材质节点本质上都是HLSL代码的封装。当你使用Add或Multiply这样的基础节点时引擎实际上是在调用对应的着色器运算指令。自定义节点允许我们将任意HLSL逻辑封装成同样规范的节点这意味着可以隐藏复杂实现细节提供简洁的输入输出接口能够复用经过验证的稳定算法避免重复造轮子可以构建专属工具链提升团队协作效率甚至能开发出带有特定艺术风格的创意节点2. 从蓝图节点到C类的实现路径2.1 解剖标准材质节点结构要创建自定义节点最好的学习方式就是研究UE自带的节点实现。打开引擎安装目录下的Engine/Source/Runtime/Engine/Classes/Materials文件夹你会看到各种材质表达式类的头文件。以最基础的MaterialExpressionAdd.h为例UCLASS(MinimalAPI, collapsecategories, hidecategoriesObject) class UMaterialExpressionAdd : public UMaterialExpression { GENERATED_UCLASS_BODY() UPROPERTY(meta (RequiredInput false, ToolTip Defaults to ConstA if not specified)) FExpressionInput A; UPROPERTY(meta (RequiredInput false, ToolTip Defaults to ConstB if not specified)) FExpressionInput B; //~ Begin UMaterialExpression Interface virtual int32 Compile(class FMaterialCompiler* Compiler, int32 OutputIndex) override; virtual void GetCaption(TArrayFString OutCaptions) const override; //~ End UMaterialExpression Interface };这个结构清晰地展示了节点的三个关键部分输入接口通过FExpressionInput定义的输入引脚编译函数将节点逻辑转换为HLSL代码元信息节点名称、提示信息等2.2 创建自定义节点类基于这个模式我们可以创建自己的节点类。假设我们要实现一个条件选择器节点根据阈值选择输出A或B// MyMaterialExpressionSelect.h #pragma once #include CoreMinimal.h #include Materials/MaterialExpression.h #include MyMaterialExpressionSelect.generated.h UCLASS() class UMyMaterialExpressionSelect : public UMaterialExpression { GENERATED_BODY() public: UPROPERTY(meta(ToolTipInput A)) FExpressionInput A; UPROPERTY(meta(ToolTipInput B)) FExpressionInput B; UPROPERTY(EditAnywhere, CategoryCondition, meta(ToolTipThreshold value)) float Threshold 0.5f; //~ Begin UMaterialExpression Interface virtual int32 Compile(class FMaterialCompiler* Compiler, int32 OutputIndex) override; virtual void GetCaption(TArrayFString OutCaptions) const override; //~ End UMaterialExpression Interface };对应的.cpp文件需要实现关键编译逻辑int32 UMyMaterialExpressionSelect::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { int32 ACode A.Compile(Compiler); int32 BCode B.Compile(Compiler); if(ACode INDEX_NONE || BCode INDEX_NONE) { return Compiler-Errorf(TEXT(Missing required inputs)); } return Compiler-If( Compiler-Greater(Compiler-Constant(Threshold), Compiler-Constant(0.5f)), ACode, BCode ); }这个实现展示了如何编译输入表达式处理错误情况使用FMaterialCompiler提供的HLSL生成工具返回生成的HLSL代码索引3. HLSL代码生成的核心机制3.1 FMaterialCompiler的工作原理FMaterialCompiler是UE材质系统的核心组件它负责将节点网络转换为最终的HLSL代码。在Compile函数中我们不是直接编写HLSL字符串而是通过Compiler提供的方法构建代码结构。常用的Compiler方法包括Constant(float)生成常量值Add(int32 A, int32 B)生成加法运算Mul(int32 A, int32 B)生成乘法运算If(int32 Condition, int32 True, int32 False)生成条件判断Errorf(const TCHAR* Text)输出编译错误每个方法都返回一个int32索引代表生成的HLSL代码片段。这些索引可以像乐高积木一样组合成更复杂的表达式。3.2 实现复杂数学函数让我们看一个更复杂的例子——实现一个自定义的噪声函数。假设我们要创建一个Perlin噪声节点int32 UMaterialExpressionMyNoise::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { int32 CoordCode Coordinates.Compile(Compiler); if(CoordCode INDEX_NONE) { return Compiler-Errorf(TEXT(Missing coordinates input)); } // 生成唯一的函数名避免冲突 FString FunctionName FString::Printf(TEXT(MyNoise_%u), GetTypeHash(this)); // 注册自定义HLSL函数 Compiler-GetSharedEnvironment().IncludeVirtualPath(TEXT(/Engine/Private/NoiseUtilities.ush)); // 调用函数并返回结果 return Compiler-CustomOutput( FunctionName, Compiler-TextureCoordinate(0, false, false), TEXT(float2(0,0)), TEXT(return PerlinNoise2D(Parameters.%s.xy);), FunctionName ); }这个实现展示了如何引入引擎内置的HLSL工具函数生成唯一函数名避免冲突使用CustomOutput创建复杂HLSL表达式重用现有的着色器函数库4. 提升节点的易用性4.1 添加友好的UI提示好的自定义节点不仅要功能强大还要易于使用。UE提供了多种方式来增强节点的用户体验void UMaterialExpressionMyNoise::GetCaption(TArrayFString OutCaptions) const { OutCaptions.Add(TEXT(My Custom Noise)); } void UMaterialExpressionMyNoise::GetExpressionToolTip(TArrayFString OutToolTip) { ConvertToMultilineToolTip( TEXT(Generates Perlin noise pattern\n) TEXT(Input: 2D coordinates\n) TEXT(Output: Noise value between 0 and 1), 40, OutToolTip ); } FText UMaterialExpressionMyNoise::GetKeywords() const { return FText::FromString(TEXT(noise,perlin,pattern)); }这些元信息会显示在节点标题栏GetCaption鼠标悬停提示GetExpressionToolTip材质编辑器搜索框GetKeywords4.2 参数验证与错误处理健壮的错误处理能显著提升开发体验。我们可以在编译时验证输入参数int32 UMaterialExpressionAdvancedBlend::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { if(BlendMode EBlendMode::BM_Custom CustomBlendCurve nullptr) { return Compiler-Errorf(TEXT(Custom blend mode requires a curve asset)); } // ...其余编译逻辑 }还可以为参数添加编辑时验证#if WITH_EDITOR void UMaterialExpressionAdvancedBlend::PostEditChangeProperty(FPropertyChangedEvent PropertyChangedEvent) { if(PropertyChangedEvent.Property PropertyChangedEvent.Property-GetFName() GET_MEMBER_NAME_CHECKED(ThisClass, Intensity)) { Intensity FMath::Clamp(Intensity, 0.0f, 1.0f); } Super::PostEditChangeProperty(PropertyChangedEvent); } #endif5. 高级技巧与性能优化5.1 使用静态分支优化性能在着色器中分支语句可能影响性能。我们可以使用静态分支来优化int32 UMaterialExpressionConditionalFeature::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { if(Compiler-GetFeatureLevel() ERHIFeatureLevel::ES3_1) { // 移动端回退方案 return Fallback.Compile(Compiler); } else { // 高端平台完整实现 return MainFeature.Compile(Compiler); } }5.2 实现多输出节点某些复杂运算可能需要多个输出。例如一个解包RGB通道的节点int32 UMaterialExpressionUnpackRGB::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { int32 InputCode Input.Compile(Compiler); if(InputCode INDEX_NONE) { return Compiler-Errorf(TEXT(Missing input)); } switch(OutputIndex) { case 0: return Compiler-ComponentMask(InputCode, true, false, false); // R case 1: return Compiler-ComponentMask(InputCode, false, true, false); // G case 2: return Compiler-ComponentMask(InputCode, false, false, true); // B default: return INDEX_NONE; } } void UMaterialExpressionUnpackRGB::GetOutputs(TArrayFExpressionOutput OutOutputs) const { OutOutputs.Add(FExpressionOutput(TEXT(R))); OutOutputs.Add(FExpressionOutput(TEXT(G))); OutOutputs.Add(FExpressionOutput(TEXT(B))); }5.3 与材质参数集合交互自定义节点可以访问材质参数集合实现动态配置int32 UMaterialExpressionDynamicParameter::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { return Compiler-DynamicParameter( ParameterName, DefaultValue, Compiler-Constant(MinValue), Compiler-Constant(MaxValue) ); }6. 调试与测试技巧开发自定义节点时调试是必不可少的环节。这里分享几个实用技巧使用ShaderPrint调试在HLSL代码中插入调试输出int32 UMaterialExpressionDebugNode::Compile(FMaterialCompiler* Compiler, int32 OutputIndex) { int32 ValueCode Input.Compile(Compiler); return Compiler-CustomOutput( TEXT(DebugOutput), ValueCode, TEXT(ShaderPrintf(TEXT(\[Debug] Value: %f\), Parameters.Value);\n) TEXT(return Parameters.Value;) ); }验证HLSL输出在材质编辑器中使用View Generated HLSL功能检查实际生成的代码打开材质编辑器选择Window HLSL Code查找你的节点生成的代码片段性能分析使用UE的GPU Profiler分析节点性能影响在编辑器启动参数中添加-traceframe,counters,gpu运行游戏并捕获分析数据在Unreal Insights中查看着色器耗时7. 打包与分发自定义节点完成开发后你可能需要将节点打包供团队使用。推荐的做法是创建插件创建新的插件项目选择Editor类型将节点类放入插件目录在插件的.Build.cs中添加引擎模块依赖PublicDependencyModuleNames.AddRange(new string[] { Core, Engine, Slate, SlateCore, RenderCore, RHI });在插件描述文件中设置加载阶段LoadingPhasePostConfigInit对于更复杂的节点集合可以考虑添加自定义材质编辑器工具按钮实现节点自动放置功能创建预设材质函数库开发配套的文档和示例材质在实际项目中我们团队将常用的30多个自定义节点打包成插件配合自动化的材质测试系统显著提升了材质开发效率和质量。特别是对于艺术指导类节点如风格化渲染效果封装成节点后艺术家可以自由组合而无需担心底层实现。