MaterialExpression.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "CoreMinimal.h"
#include "UObject/ObjectMacros.h"
#include "UObject/Object.h"
#include "UObject/UnrealType.h"
#include "Misc/Guid.h"
#include "MaterialExpressionIO.h"
#include "MaterialValueType.h"
 
#include "MaterialExpression.generated.h"
 
class UEdGraphNode;
class UMaterial;
class UTexture;
class UTextureCollection;
struct FGraphActionMenuBuilder;
struct FPropertyChangedEvent;
struct FMaterialParameterMetadata;
struct FMaterialShadingModelField;
struct FSubstrateMaterialInfo;
struct FSubstrateOperator;
 
class UMaterialExpression;
class UMaterialExpressionComment;
class FMaterialExpressionKey;
 
class FFindInMaterialResult;
 
enum EEdGraphPinDirection : int;
enum class EMaterialParameterType : uint8;
 
namespace MIR
{
    class FEmitter;
    struct FValue;
}
 
//@warning: FExpressionInput is mirrored in MaterialShared.h and manually "subclassed" in Material.h (FMaterialInput)
#if !CPP      //noexport struct
USTRUCT(noexport)
struct FExpressionInput
{
    UPROPERTY()
    TObjectPtr<class UMaterialExpression> Expression;
 
    UPROPERTY()
    int32 OutputIndex;
 
    UPROPERTY()
    FName InputName;
 
 
    UPROPERTY()
    int32 Mask;
 
    UPROPERTY()
    int32 MaskR;
 
    UPROPERTY()
    int32 MaskG;
 
    UPROPERTY()
    int32 MaskB;
 
    UPROPERTY()
    int32 MaskA;
};
 
USTRUCT(noexport)
struct FMaterialAttributesInput : public FExpressionInput
{
    UPROPERTY(transient)
    int64 PropertyConnectedMask;
};
 
#endif
 
#if !CPP      //noexport struct
USTRUCT(noexport)
struct FExpressionOutput
{
    UPROPERTY()
    FName OutputName;
 
    UPROPERTY()
    int32 Mask;
 
    UPROPERTY()
    int32 MaskR;
 
    UPROPERTY()
    int32 MaskG;
 
    UPROPERTY()
    int32 MaskB;
 
    UPROPERTY()
    int32 MaskA;
};
#endif
 
enum class EMaterialExpressionSetParameterValueFlags : uint32
{
    None = 0u,
    SendPostEditChangeProperty = (1u << 0), // Send PostEditChangeProperty events for all properties that are modified
    NoUpdateExpressionGuid = (1u << 1), // By default ExpressionGUI will be updated for static parameters
    AssignGroupAndSortPriority  = (1u << 2), //  Update the Group and SortPriority along with parameter value
};
ENUM_CLASS_FLAGS(EMaterialExpressionSetParameterValueFlags);
 
USTRUCT()
struct FMaterialExpressionCollection
{
    GENERATED_BODY()
 
    ENGINE_API void AddExpression(UMaterialExpression* InExpression);
    ENGINE_API void RemoveExpression(UMaterialExpression* InExpression);
    ENGINE_API void AddComment(UMaterialExpressionComment* InExpression);
    ENGINE_API void RemoveComment(UMaterialExpressionComment* InExpression);
    ENGINE_API void Empty();
 
    UPROPERTY()
    TArray<TObjectPtr<UMaterialExpression>> Expressions;
    
    UPROPERTY()
    TArray<TObjectPtr<UMaterialExpressionComment>> EditorComments;
 
    UPROPERTY()
    TObjectPtr<UMaterialExpression> ExpressionExecBegin = nullptr;
 
    UPROPERTY()
    TObjectPtr<UMaterialExpression> ExpressionExecEnd = nullptr;
};
 
UCLASS(abstract, Optional, BlueprintType, Config=MaterialExpressions, hidecategories=Object, MinimalAPI)
class UMaterialExpression : public UObject
{
    GENERATED_UCLASS_BODY()
 
    static constexpr int32 CompileExecutionOutputIndex = -2;
 
    UPROPERTY(BlueprintReadWrite, Category = MaterialEditing)
    int32 MaterialExpressionEditorX;
 
    UPROPERTY(BlueprintReadWrite, Category = MaterialEditing)
    int32 MaterialExpressionEditorY;
 
    UPROPERTY(transient)
    TObjectPtr<UEdGraphNode>    GraphNode;
 
    UPROPERTY()
    TObjectPtr<UMaterialExpression> SubgraphExpression;
 
    FString LastErrorText;
 
    UPROPERTY()
    FGuid MaterialExpressionGuid;
 
    UPROPERTY()
    TObjectPtr<class UMaterial> Material;
 
    UPROPERTY()
    TObjectPtr<class UMaterialFunction> Function;
 
    UPROPERTY(EditAnywhere, Category=MaterialExpression, meta=(MultiLine=true, DisplayAfter = "SortPriority"))
    FString Desc;
 
    UPROPERTY()
    uint32 bRealtimePreview:1;
 
    UPROPERTY(transient)
    uint32 bNeedToUpdatePreview:1;
 
    UPROPERTY()
    uint8 bIsParameterExpression : 1;
 
    UPROPERTY()
    uint32 bCommentBubbleVisible:1;
 
    UPROPERTY()
    uint32 bShowOutputNameOnPin:1;
 
    UPROPERTY()
    uint32 bShowMaskColorsOnPin:1;
 
    UPROPERTY()
    uint32 bHidePreviewWindow:1;
 
    UPROPERTY()
    uint32 bCollapsed:1;
 
    UPROPERTY(config)
    uint32 bShaderInputData:1;
 
    UPROPERTY()
    uint32 bShowInputs:1;
 
    UPROPERTY()
    uint32 bShowOutputs:1;
 
    UPROPERTY(config)
    TArray<FText> MenuCategories;
 
    UPROPERTY()
    TArray<FExpressionOutput> Outputs;
 
    //~ Begin UObject Interface.
    ENGINE_API virtual void PostInitProperties() override;
    ENGINE_API virtual void PostLoad() override;
    ENGINE_API virtual void PostDuplicate(bool bDuplicateForPIE) override;
#if WITH_EDITOR
    ENGINE_API virtual void PostEditChangeProperty(FPropertyChangedEvent& PropertyChangedEvent) override;
    ENGINE_API virtual void PostEditImport() override;
    ENGINE_API virtual bool CanEditChange( const FProperty* InProperty ) const override;
    
    ENGINE_API virtual bool Modify( bool bAlwaysMarkDirty=true ) override;
#endif // WITH_EDITOR
    ENGINE_API virtual void Serialize( FStructuredArchive::FRecord Record ) override;
    //~ End UObject Interface.
 
    ENGINE_API UObject* GetAssetOwner() const;
    ENGINE_API FString GetAssetPathName() const;
 
#if WITH_EDITOR
    ENGINE_API virtual int32 Compile(class FMaterialCompiler* Compiler, int32 OutputIndex);
    virtual int32 CompilePreview(class FMaterialCompiler* Compiler, int32 OutputIndex) { return Compile(Compiler, OutputIndex); }
 
    ENGINE_API bool IsUsingNewHLSLGenerator() const;
 
    ENGINE_API virtual void Build(MIR::FEmitter& Emitter);
 
    /* Material expressions can add shader tags that to a material.  Adding a shader tag helps to identify materials
     *  that use certain material expressions, and can be used to limit shader generation to only materials that have
     *  use that material expression
     */
    virtual void GetShaderTags(TArray<FName>& ShaderTagsOut) {}
 
    virtual TSharedPtr<class SGraphNodeMaterialBase> CreateCustomGraphNodeWidget() { return nullptr; }
#endif // WITH_EDITOR
 
    ENGINE_API virtual bool IsAllowedIn(const UObject* MaterialOrFunction) const;
 
 
    virtual void GetTexturesForceMaterialRecompile(TArray<UTexture *> &Textures) const { }
 
 
    virtual UObject* GetReferencedTexture() const { return nullptr; }
 
    using ReferencedTextureArray = TArray<UObject*, TInlineAllocator<4>>; 
    virtual ReferencedTextureArray GetReferencedTextures() const { return { GetReferencedTexture() }; }
    
    virtual bool CanReferenceTexture() const { return false; }
 
    virtual UTextureCollection* GetReferencedTextureCollection() const { return nullptr; }
 
#if WITH_EDITOR
 
    ENGINE_API virtual int32 CountInputs() const;
 
    FExpressionOutput* GetOutput(int32 OutputIndex) { return Outputs.IsValidIndex(OutputIndex) ? &Outputs[OutputIndex] : nullptr; }
 
    ENGINE_API virtual FExpressionInput* GetInput(int32 InputIndex);
    const FExpressionInput* GetInput(int32 InputIndex) const { return const_cast<UMaterialExpression*>(this)->GetInput(InputIndex); }
 
    UE_DEPRECATED(5.5, "Use FExpressionInputIterator instead or GetInput() directly.")
    ENGINE_API virtual TArrayView<FExpressionInput*> GetInputsView();
 
    ENGINE_API virtual FName GetInputName(int32 InputIndex) const;
    
    ENGINE_API virtual bool IsInputConnectionRequired(int32 InputIndex) const;
        
    UE_DEPRECATED(5.6, "Use EMaterialValueType GetInputValueType(...) instead")
    ENGINE_API virtual uint32 GetInputType(int32 InputIndex);
 
    ENGINE_API virtual TArray<FExpressionOutput>& GetOutputs();
 
    UE_DEPRECATED(5.6, "Use EMaterialValueType GetOutputValueType(...) instead")
    ENGINE_API virtual uint32 GetOutputType(int32 OutputIndex);
    
    virtual EMaterialValueType GetInputValueType(int32 InputIndex)
    {
        PRAGMA_DISABLE_DEPRECATION_WARNINGS
        return static_cast<EMaterialValueType>(GetInputType(InputIndex));
        PRAGMA_ENABLE_DEPRECATION_WARNINGS
    }
    
    virtual EMaterialValueType GetOutputValueType(int32 OutputIndex)
    {
        PRAGMA_DISABLE_DEPRECATION_WARNINGS
        return static_cast<EMaterialValueType>(GetOutputType(OutputIndex));
        PRAGMA_ENABLE_DEPRECATION_WARNINGS
    }
 
    virtual bool IsStaticExpression() const { return false; }
    virtual bool CanUserDeleteExpression() const { return true; }
 
    ENGINE_API virtual TArray<FProperty*> GetInputPinProperty(int32 PinIndex);
    ENGINE_API virtual FName GetInputPinSubCategory(int32 PinIndex);
    ENGINE_API virtual UObject* GetInputPinSubCategoryObject(int32 PinIndex);
    ENGINE_API virtual void PinDefaultValueChanged(int32 PinIndex, const FString& DefaultValue);
    ENGINE_API virtual void ForcePropertyValueChanged(FProperty* Property, bool bUpdatePreview = true);
    ENGINE_API virtual void RefreshNode(bool bUpdatePreview = true);
    ENGINE_API virtual FString GetInputPinDefaultValue(int32 PinIndex);
    ENGINE_API virtual TArray<FProperty*> GetPropertyInputs() const;
 
    ENGINE_API virtual FText GetCreationDescription() const;
    ENGINE_API virtual FText GetCreationName() const;
 
    ENGINE_API virtual int32 GetWidth() const;
    ENGINE_API virtual int32 GetHeight() const;
    ENGINE_API virtual bool UsesLeftGutter() const;
    ENGINE_API virtual bool UsesRightGutter() const;
 
    ENGINE_API virtual void GetCaption(TArray<FString>& OutCaptions) const;
    ENGINE_API virtual FString GetDescription() const;
    ENGINE_API virtual void GetConnectorToolTip(int32 InputIndex, int32 OutputIndex, TArray<FString>& OutToolTip);
 
    ENGINE_API virtual void GetExpressionToolTip(TArray<FString>& OutToolTip);
    virtual int GetLabelPadding() { return 0; }
    ENGINE_API virtual int32 CompilerError(class FMaterialCompiler* Compiler, const TCHAR* pcMessage);
#endif // WITH_EDITOR
 
#if WITH_EDITOR
    virtual bool NeedsRealtimePreview() { return false; }
 
    virtual FText GetPreviewOverlayText() const { return FText(); }
 
    ENGINE_API virtual bool MatchesSearchQuery( const TCHAR* SearchQuery );
 
    ENGINE_API virtual bool DeepSearchQuery(const TCHAR* SearchQuery, TSharedPtr<FFindInMaterialResult> SearchResult);
 
    static ENGINE_API void CopyMaterialExpressions(const TArray<class UMaterialExpression*>& SrcExpressions, const TArray<class UMaterialExpressionComment*>& SrcExpressionComments, 
        class UMaterial* Material, class UMaterialFunction* Function, TArray<class UMaterialExpression*>& OutNewExpressions, TArray<class UMaterialExpression*>& OutNewComments);
 
    virtual bool IsResultMaterialAttributes(int32 OutputIndex) { return false; }
 
    virtual bool IsResultSubstrateMaterial(int32 OutputIndex) { return false; }
 
    virtual void GatherSubstrateMaterialInfo(FSubstrateMaterialInfo& SubstrateMaterialInfo, int32 OutputIndex) { }
 
    ENGINE_API virtual FSubstrateOperator* SubstrateGenerateMaterialTopologyTree(class FMaterialCompiler* Compiler, class UMaterialExpression* Parent, int32 OutputIndex);
 
    virtual bool CanIgnoreOutputIndex() { return false; }
 
    ENGINE_API void ConnectToPreviewMaterial(UMaterial* InMaterial, int32 OutputIndex);
#endif // WITH_EDITOR
 
#if WITH_EDITOR
    ENGINE_API virtual bool IsExpressionConnected(FExpressionInput* Input, int32 OutputIndex);
 
    ENGINE_API virtual void ConnectExpression(FExpressionInput* Input, int32 OutputIndex);
#endif // WITH_EDITOR
 
    ENGINE_API void UpdateParameterGuid(bool bForceGeneration, bool bAllowMarkingPackageDirty);
 
    virtual FGuid& GetParameterExpressionId()
    {
        checkf(!bIsParameterExpression, TEXT("Expressions with bIsParameterExpression==true must implement their own GetParameterExpressionId!"));
        static FGuid Dummy;
        return Dummy;
    }
 
    ENGINE_API void UpdateMaterialExpressionGuid(bool bForceGeneration, bool bAllowMarkingPackageDirty);
    
    virtual FGuid& GetMaterialExpressionId()
    {       
#if WITH_EDITORONLY_DATA
        return MaterialExpressionGuid;
#else
        static FGuid Dummy;
        return Dummy;
#endif
    }
 
    ENGINE_API void ValidateState();
 
#if WITH_EDITOR
 
    ENGINE_API bool ShouldShowPreview() const;
 
    virtual FText GetKeywords() const {return FText::GetEmpty();}
 
    ENGINE_API bool GetAllInputExpressions(TArray<UMaterialExpression*>& InputExpressions);
 
    ENGINE_API virtual bool CanRenameNode() const;
 
    ENGINE_API virtual FString GetEditableName() const;
 
    ENGINE_API virtual void SetEditableName(const FString& NewName);
 
    virtual bool HasAParameterName() const { return false; }
    ENGINE_API virtual void ValidateParameterName(const bool bAllowDuplicateName = true);
    ENGINE_API virtual bool HasClassAndNameCollision(UMaterialExpression* OtherExpression) const;
 
    ENGINE_API EMaterialParameterType GetParameterType() const;
 
    virtual FName GetParameterName() const { return NAME_None; }
    virtual void SetParameterName(const FName& Name) {}
    virtual bool GetParameterValue(FMaterialParameterMetadata& OutMeta) const { return false; }
    virtual bool SetParameterValue(const FName& Name, const FMaterialParameterMetadata& Meta, EMaterialExpressionSetParameterValueFlags Flags = EMaterialExpressionSetParameterValueFlags::None) { return false; }
 
    virtual void GetLandscapeLayerNames(TArray<FName>& OutLayers) const {}
    virtual void GetIncludeFilePaths(TSet<FString>& OutIncludeFilePaths) const {}
 
    virtual void PostCopyNode(const TArray<UMaterialExpression*>& CopiedExpressions) {}
 
    ENGINE_API virtual bool HasConnectedOutputs() const;
 
    ENGINE_API bool ContainsInputLoop(const bool bStopOnFunctionCall = true);
 
    ENGINE_API bool ContainsInputLoop(TSet<UMaterialExpression*>& VisitedExpressions, const bool bStopOnFunctionCall = true);
 
    virtual bool CanDeletePin(EEdGraphPinDirection PinDirection, int32 PinIndex) const { return false; }
 
    virtual void DeletePin(EEdGraphPinDirection PinDirection, int32 PinIndex) {}
 
    virtual void RegisterAdditionalMenuActions(FGraphActionMenuBuilder& ActionMenuBuilder, const FText& CategoryName) {}
 
protected:
    TArray<FExpressionInput*> CachedInputs;
 
private:
    struct FContainsInputLoopInternalExpressionStack;
 
    ENGINE_API bool ContainsInputLoopInternal(const FContainsInputLoopInternalExpressionStack& ExpressionStack, TSet<UMaterialExpression*>& VisitedExpressions, const bool bStopOnFunctionCall);
 
#endif // WITH_EDITOR
};
 
UENUM()
enum class EPositionOrigin : uint8
{
    Absolute UMETA(DisplayName="Absolute World Position"),
 
    CameraRelative UMETA(DisplayName="Camera Relative World Position")
};
 
 
#if WITH_EDITOR
 
struct FExpressionInputIterator
{
    UMaterialExpression* Expression;
 
    FExpressionInput* Input;
 
    int Index;
 
    FExpressionInputIterator(UMaterialExpression* InExpression)
    : Expression{ InExpression }
    , Input{ InExpression->GetInput(0) }
    , Index{ 0 }
    {
    }
 
    operator bool() const
    {
        return Input != nullptr;
    }
 
    FExpressionInputIterator& operator++()
    {
        Index += 1;
        Input = Expression->GetInput(Index);
        return *this;
    }
 
    FExpressionInput* operator->()
    {
        return Input;
    }
};
 
struct FExpressionOutputIterator
{
    UMaterialExpression* Expression;
 
    FExpressionOutput* Output;
 
    int Index;
 
    FExpressionOutputIterator(UMaterialExpression* InExpression)
    : Expression{ InExpression }
    , Output{ InExpression->GetOutput(0) }
    , Index{ 0 }
    {
    }
 
    operator bool() const
    {
        return Output != nullptr;
    }
 
    FExpressionOutputIterator& operator++()
    {
        Index += 1;
        Output = Expression->GetOutput(Index);
        return *this;
    }
 
    FExpressionOutput* operator->()
    {
        return Output;
    }
};
 
#endif // WITH_EDITOR