FMaterial

[FMaterial](API\Runtime\Engine\FMaterial) serves 3 intertwined purposes: Represents a material to the material compilation process, and provides hooks for extensibility (CompileProperty, etc) Represents a material to the renderer, with functions to access material properties Stores a cached shader map, and other transient output from a compile, which is necessary with async shader compiling (when a material finishes async compilation, the shader map and compile errors need to be stored somewhere)

Windows
MacOS
Linux

Inheritance Hierarchy

References

Module

Engine

Header

/Engine/Source/Runtime/Engine/Public/MaterialShared.h

Include

#include "MaterialShared.h"

Syntax

class FMaterial

Remarks

FMaterial serves 3 intertwined purposes: Represents a material to the material compilation process, and provides hooks for extensibility (CompileProperty, etc) Represents a material to the renderer, with functions to access material properties Stores a cached shader map, and other transient output from a compile, which is necessary with async shader compiling (when a material finishes async compilation, the shader map and compile errors need to be stored somewhere)

Constructors

Name Description

Public function

FMaterial()

Minimal initialization constructor.

Destructors

Name Description

Public function Virtual

~FMaterial()

Destructor

Functions

Name Description

Public function Static

void

 

AddEditorLoadedMaterialResource

(
    FMaterial* Material
)

Adds an FMaterial to the global list.

Public function Virtual

void

 

AddReferencedObjects

(
    FReferenceCollector& Collector
)

Public function Virtual Const

bool

 

AllowNegativeEmissiveColor()

Public function Static

void

 

BackupEditorLoadedMaterialShadersToMemory

(
    TMap< FMaterialShaderMap*, TUniquePtr< TArray< uint8 > > >& ShaderMapToSerializedShaderData
)

Backs up any FShaders in editor loaded materials to memory through serialization and clears FShader references.

Public function

bool

 

CacheShaders

(
    EShaderPlatform Platform,
    const ITargetPlatform* TargetPlatform
)

Caches the material shaders for this material on the given platform.

Public function

bool

 

CacheShaders

(
    const FMaterialShaderMapId& ShaderMapId,
    const FStaticParameterSet& StaticParameterSet,
    EShaderPlatform Platform,
    const ITargetPlatform* TargetPlatform
)

Caches the material shaders for the given static parameter set and platform.

Public function

void

 

CancelCompilation()

Cancels all outstanding compilation jobs for this material.

Public function Virtual Const

bool

 

CastsRayTracedShadows()

Protected function Const

int32

 

CompilePropertyAndSetMaterialProperty

(
    EMaterialProperty Property,
    FMaterialCompiler* Compiler,
    EShaderFrequency OverrideShaderFrequency,
    bool bUsePreviousFrameTime
)

Entry point for compiling a specific material property. This must call SetMaterialProperty.

Public function Virtual Const

bool

 

ComputeFogPerPixel()

Public function

void

 

DiscardShaderMap()

Discards loaded shader maps if the application can't render

Public function

void

 

DumpDebugInfo()

Protected function

int32

 

FindExpression

(
    const TArray< TRefCountPtr< FMaterialUniformExpressionTexture > >& Expressions,
    const FMaterialUniformExpressionTexture& Expression
)

Returns the index to the Expression in the Expressions array, or -1 if not found.

Public function

void

 

FinishCompilation()

Blocks until compilation has completed. Returns immediately if a compilation is not outstanding.

Protected function Virtual Const

void

 

GatherCustomOutputExpressions

(
    TArray< class UMaterialExpressionCustomOutput* >& OutCustomOutputs
)

Gather any UMaterialExpressionCustomOutput expressions they can be compiled in turn

Protected function Virtual Const

void

 

GatherExpressionsForCustomInterpolators

(
    TArray< class UMaterialExpression* >& OutExpressions
)

Gather any UMaterialExpressionCustomOutput expressions in the material and referenced function calls

Public function Virtual Const

bool

 

GetAllowDevelopmentShaderCompile()

Returns true if this material is allowed to make development shaders via the global CVar CompileShadersForDevelopment.

Protected function Virtual Const

FString

 

GetBaseMaterialPathName()

Useful for debugging.

Public function Virtual Const

int32

 

GetBlendableLocation()

Public function Virtual Const

bool

 

GetBlendableOutputAlpha()

Public function Const

enum EBlendMode

 

GetBlendMode()

Public function Const

bool

 

GetCastDynamicShadowAsMasked()

Public function Const

const TArray< FString > &

 

GetCompileErrors()

Protected function Virtual Const

FString

 

GetDebugName()

Public function Virtual Const

uint32

 

GetDecalBlendMode()

Protected function Const

void

 

GetDependentShaderAndVFTypes

(
    EShaderPlatform Platform,
    TArray< FShaderType* >& OutShaderTypes,
    TArray< const FShaderPipelineType* >& OutShaderPipelineTypes,
    TArray< FVertexFactoryType* >& OutVFTypes
)

Produces arrays of any shader and vertex factory type that this material is dependent on.

Public function Const

const TArray< UMaterialExpression * > &

 

GetErrorExpressions()

Public function Const

ERHIFeatureLevel::Type

 

GetFeatureLevel()

Public function Const

FString

 

GetFriendlyName()

Public function Const

FMaterialShaderMap *

 

GetGameThreadShaderMap()

Public function Const

const FGuid &

 

GetLegacyId()

Protected function Const

bool

 

GetLoadedCookedShaderMapId()

Public function Virtual Const

uint32

 

GetMaterialDecalResponse()

Public function Const

EMaterialDomain

 

GetMaterialDomain()

Public function

bool

 

GetMaterialExpressionSource

(
    FString& OutSource
)

Get user source code for the material, with a list of code snippets to highlight representing the code for each MaterialExpression

Protected function Const

FGuid

 

GetMaterialId()

Gets the Guid that represents this material.

Public function Virtual Const

UMaterialInterface *

 

GetMaterialInterface()

Public function Virtual Const

EMaterialShaderMapUsage::Type

 

GetMaterialShaderMapUsage()

Returns which shadermap this material is bound to.

Public function Const

FString

 

GetMaterialUsageDescription()

Returns a string that describes the material's usage for debugging purposes.

Public function Virtual Const

float

 

GetMaxDisplacement()

Public function Virtual Const

int32

 

GetNumCustomizedUVs()

Public function Const

float

 

GetOpacityMaskClipValue()

Public function Const

EMaterialQualityLevel::Type

 

GetQualityLevel()

Public function Const

const TArray< UObject * > &

 

GetReferencedTextures()

Public function Virtual Const

float

 

GetRefractionDepthBiasValue()

Public function Virtual Const

enum ERefractionMode

 

GetRefractionMode()

Public function Const

FMaterialShaderMap *

 

GetRenderingThreadShaderMap()

Public function Const

ShaderType *

 

GetShader

(
    FVertexFactoryType* VertexFactoryType,
    const typename ShaderType::FPermutationDomain& PermutationVector,
    bool bFatalIfMissing
)

Finds the shader matching the template type and the passed in vertex factory, asserts if not found.

Public function Const

ShaderType *

 

GetShader

(
    FVertexFactoryType* VertexFactoryType,
    int32 PermutationId,
    bool bFatalIfMissing
)

Public function Virtual Const

void

 

GetShaderMapId

(
    EShaderPlatform Platform,
    FMaterialShaderMapId& OutId
)

Material properties.

Protected function

void

 

GetShaderMapIDsWithUnfinishedCompilation

(
    TArray< int32 >& ShaderMapIds
)

Fills the passed array with IDs of shader maps unfinished compilation jobs.

Protected function Const

const FMaterialShaderMap *

 

GetShaderMapToUse()

Shared code needed for GetUniformScalarParameterExpressions, GetUniformVectorParameterExpressions, GetUniformCubeTextureExpressions..

Protected function Virtual Const

EMaterialShaderMapUsage::Type

 

GetShaderMapUsage()

Gets the shader map usage of the material, which will be included in the DDC key.

Public function Const

FShaderPipeline *

 

GetShaderPipeline

(
    FShaderPipelineType* ShaderPipelineType,
    FVertexFactoryType* VertexFactoryType,
    bool bFatalIfNotFound
)

Public function Const

FMaterialShadingModelField

 

GetShadingModels()

Public function Virtual Const

void

 

GetStaticParameterSet

(
    EShaderPlatform Platform,
    FStaticParameterSet& OutSet
)

Public function Virtual Const

uint32

 

GetStencilCompare()

Public function Virtual Const

uint32

 

GetStencilRefValue()

Public function Virtual Const

enum EMaterialTessellationMode

 

GetTessellationMode()

Public function Virtual Const

float

 

GetTranslucencyDirectionalLightingIntensity()

Public function Virtual Const

enum ETranslucencyLightingMode

 

GetTranslucencyLightingMode()

Public function Virtual Const

float

 

GetTranslucentBackscatteringExponent()

Public function Virtual Const

FLinearColor

 

GetTranslucentMultipleScatteringExtinction()

Public function Virtual Const

float

 

GetTranslucentSelfShadowDensityScale()

Public function Virtual Const

float

 

GetTranslucentSelfShadowSecondDensityScale()

Public function Virtual Const

float

 

GetTranslucentSelfShadowSecondOpacity()

Public function Virtual Const

float

 

GetTranslucentShadowDensityScale()

Public function Virtual Const

float

 

GetTranslucentShadowStartOffset()

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpressionTexture > > &

 

GetUniform2DArrayTextureExpressions()

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpressionTexture > > &

 

GetUniform2DTextureExpressions()

Accessors.

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpressionTexture > > &

 

GetUniformCubeTextureExpressions()

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpression > > &

 

GetUniformScalarParameterExpressions()

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpression > > &

 

GetUniformVectorParameterExpressions()

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpressionTexture > > &

 

GetUniformVirtualTextureExpressions()

Public function Const

const TArray< TRefCountPtr< FMaterialUniformExpressionTexture > > &

 

GetUniformVolumeTextureExpressions()

Public function Const

bool

 

GetUsesDynamicParameter()

Public function Virtual Const

bool

 

HasEmissiveColorConnected()

Public function Virtual Const

bool

 

HasMaterialAttributesConnected()

Public function Virtual Const

bool

 

HasNormalConnected()

Public function Virtual Const

bool

 

HasPixelDepthOffsetConnected()

Public function Virtual Const

bool

 

HasRuntimeVirtualTextureOutput()

Public function Const

bool

 

HasRuntimeVirtualTextureOutput_RenderThread()

Does the material have a runtime virtual texture output node.

Public function Const

bool

 

HasValidGameThreadShaderMap()

Checks if there is a valid GameThreadShaderMap, that is, the material can be rendered as intended.

Public function Virtual Const

bool

 

HasVertexPositionOffsetConnected()

Public function Virtual Const

bool

 

IsAdaptiveTessellationEnabled()

Public function Const

bool

 

IsCompilationFinished()

Checks if the compilation for this shader is finished

Public function Virtual Const

bool

 

IsCrackFreeDisplacementEnabled()

Public function Virtual Const

bool

 

IsDefaultMaterial()

Public function Const

bool

 

IsDeferredDecal()

Public function Virtual Const

bool

 

IsDistorted()

Public function Const

bool

 

IsDitheredLODTransition()

Public function Virtual Const

bool

 

IsDitherMasked()

Public function Virtual Const

bool

 

IsFullyRough()

Public function Const

bool

 

IsLightFunction()

Public function Const

bool

 

IsMasked()

Public function Virtual Const

bool

 

IsMobileSeparateTranslucencyEnabled()

Public function Virtual Const

bool

 

IsNonmetal()

Public function Const

bool

 

IsPersistent()

Should shaders compiled for this material be saved to disk?

Public function Const

bool

 

IsShadingModelFromMaterialExpression()

Public function Virtual Const

bool

 

IsSky()

Public function Const

bool

 

IsSpecialEngineMaterial()

Public function Virtual Const

bool

 

IsStencilTestEnabled()

Public function Virtual Const

bool

 

IsTangentSpaceNormal()

Public function Virtual Const

bool

 

IsTranslucencyAfterDOFEnabled()

Public function Virtual Const

bool

 

IsTranslucencyWritingCustomDepth()

Public function Virtual Const

bool

 

IsTranslucencyWritingVelocity()

Public function Const

bool

 

IsTwoSided()

Public function Virtual Const

bool

 

IsUIMaterial()

Public function Virtual Const

bool

 

IsUsedWithAPEXCloth()

Public function Virtual Const

bool

 

IsUsedWithBeamTrails()

Public function Virtual Const

bool

 

IsUsedWithEditorCompositing()

Public function Virtual Const

bool

 

IsUsedWithGeometryCache()

Public function Virtual Const

bool

 

IsUsedWithGeometryCollections()

Public function Virtual Const

bool

 

IsUsedWithHairStrands()

Public function Virtual Const

bool

 

IsUsedWithInstancedStaticMeshes()

Public function Virtual Const

bool

 

IsUsedWithLandscape()

Public function Virtual Const

bool

 

IsUsedWithMeshParticles()

Public function Virtual Const

bool

 

IsUsedWithMorphTargets()

Public function Virtual Const

bool

 

IsUsedWithNiagaraMeshParticles()

Public function Virtual Const

bool

 

IsUsedWithNiagaraRibbons()

Public function Virtual Const

bool

 

IsUsedWithNiagaraSprites()

Public function Virtual Const

bool

 

IsUsedWithParticleSprites()

Public function Virtual Const

bool

 

IsUsedWithParticleSystem()

Public function Virtual Const

bool

 

IsUsedWithSkeletalMesh()

Public function Virtual Const

bool

 

IsUsedWithSplineMeshes()

Public function Virtual Const

bool

 

IsUsedWithStaticLighting()

Public function Virtual Const

bool

 

IsUsedWithUI()

Public function Virtual Const

bool

 

IsUsedWithWater()

Public function Virtual Const

bool

 

IsUsingFullPrecision()

Public function Virtual Const

bool

 

IsUsingHQForwardReflections()

Public function Virtual Const

bool

 

IsUsingPlanarForwardReflections()

Public function Const

bool

 

IsVolumetricPrimitive()

Public function Const

bool

 

IsWireframe()

Public function Virtual

void

 

LegacySerialize

(
    FArchive& Ar
)

Serializes the material.

Public function Const

bool

 

MaterialMayModifyMeshPosition()

Note: This function is only intended for use in deciding whether or not shader permutations are required before material translation occurs.

Public function Const

bool

 

MaterialModifiesMeshPosition_GameThread()

Public function Const

bool

 

MaterialModifiesMeshPosition_RenderThread()

Does the material modify the mesh position.

Public function Const

bool

 

MaterialUsesDistanceCullFade_GameThread()

Does the material use a distance cull fade.

Public function Const

bool

 

MaterialUsesPixelDepthOffset()

Does the material use a pixel depth offset.

Public function Const

bool

 

MaterialUsesSceneDepthLookup_GameThread()

Public function Const

bool

 

MaterialUsesSceneDepthLookup_RenderThread()

Does the material use a SceneDepth lookup.

Public function Const

bool

 

NeedsGBuffer()

Public function Const

bool

 

NeedsSceneTextures()

Public function Virtual

void

 

NotifyCompilationFinished()

Called when compilation of an FMaterial finishes, after the GameThreadShaderMap is set and the render command to set the RenderThreadShaderMap is queued

Public function Virtual Const

bool

 

OutputsVelocityOnBasePass()

Public function

void

 

RegisterInlineShaderMap

(
    bool bLoadedByCookedMaterial
)

Serializes the shader map inline in this material, including any shader dependencies.

Public function

void

 

ReleaseShaderMap()

Releases this material's shader map.

Public function

void

 

RemoveOutstandingCompileId

(
    const int32 OldOutstandingCompileShaderMapId
)

Public function Const

bool

 

RequiresSceneColorCopy_GameThread()

Public function Const

bool

 

RequiresSceneColorCopy_RenderThread()

Public function Virtual Const

bool

 

RequiresSynchronousCompilation()

Public function Static

void

 

RestoreEditorLoadedMaterialShadersFromMemory

(
    const TMap< FMaterialShaderMap*, TUniquePtr< TArray< uint8 > > >& ShaderMapToSerializedShaderData
)

Recreates FShaders in editor loaded materials from the passed in memory, handling shader key changes.

Public function

void

 

SaveShaderStableKeys

(
    EShaderPlatform TargetShaderPlatform,
    FStableShaderKeyAndValue& SaveKeyVal
)

Public function

void

 

SerializeInlineShaderMap

(
    FArchive& Ar
)

Serializes the shader map inline in this material, including any shader dependencies.

Public function

void

 

SetCompileErrors

(
    const TArray< FString >& InCompileErrors
)

Public function

void

 

SetGameThreadShaderMap

(
    FMaterialShaderMap* InMaterialShaderMap
)

Public function

void

 

SetInlineShaderMap

(
    FMaterialShaderMap* InMaterialShaderMap
)

Protected function

void

 

SetQualityLevelProperties

(
    EMaterialQualityLevel::Type InQualityLevel,
    bool bInHasQualityLevelUsage,
    ERHIFeatureLevel::Type InFeatureLevel
)

Public function

void

 

SetRenderingThreadShaderMap

(
    FMaterialShaderMap* InMaterialShaderMap
)

Note: SetGameThreadShaderMap must also be called with the same value, but from the game thread.

Public function Virtual Const

void

 

SetupExtaCompilationSettings

(
    const EShaderPlatform Platform,
    FExtraShaderCompilerSettings& Settings
)

Call during shader compilation jobs setup to fill additional settings that may be required by classes who inherit from this

Public function Virtual Const

bool

 

ShouldApplyFogging()

Public function Virtual Const

bool

 

ShouldBlockGI()

Public function Virtual Const

bool

 

ShouldCache

(
    EShaderPlatform Platform,
    const FShaderType* ShaderType,
    const FVertexFactoryType* VertexFactoryType
)

Should the shader for this material with the given platform, shader type and vertex factory type combination be compiled

Public function Const

bool

 

ShouldCastDynamicShadows()

Returns whether this material should be considered for casting dynamic shadows.

Public function Virtual Const

bool

 

ShouldDisableDepthTest()

Public function Virtual Const

bool

 

ShouldDoContactShadows()

Public function Virtual Const

bool

 

ShouldDoSSR()

Public function Virtual Const

bool

 

ShouldEnableResponsiveAA()

Public function Virtual Const

bool

 

ShouldGenerateSphericalParticleNormals()

Public function Virtual Const

bool

 

ShouldInjectEmissiveIntoLPV()

Public function Virtual Const

bool

 

ShouldWriteOnlyAlpha()

Public function Static

void

 

UpdateEditorLoadedMaterialResources

(
    EShaderPlatform InShaderPlatform
)

Recompiles any materials in the EditorLoadedMaterialResources list if they are not complete.

Public function Virtual Const

bool

 

UseLmDirectionality()

Public function Virtual Const

bool

 

UseNormalCurvatureToRoughness()

Public function Const

bool

 

UsesCustomDepthStencil_GameThread()

Does the material use CustomDepth or CustomStencil lookup

Public function Const

bool

 

UsesEyeAdaptation()

Public function Const

bool

 

UsesGlobalDistanceField_GameThread()

Public function Const

bool

 

UsesWorldPositionOffset_GameThread()

Public function Const

bool

 

WritesEveryPixel

(
    bool bShadowPass
)

Helper function to look at both IsMasked and IsDitheredLODTransition to determine if it writes every pixel

Constants

Name

Description

EditorLoadedMaterialResources

Tracks FMaterials without a corresponding UMaterialInterface in the editor, for example FExpressionPreviews.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback