1. Epic GamesDeveloper
  3. FMaterial

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)

API > API/Runtime > API/Runtime/Engine

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)

Variables

  Type Name Description
Public variable FUniformParameterOverrides TransientOverrides  

Constructors

  Type Name Description
Public function   Minimal initialization constructor.

Destructors

  Type Name Description
Public function Virtual   Destructor

Functions

  Type Name Description
Public function Static void Adds an FMaterial to the global list.
Public function Const uint32

AddRef ()

  
Public function Virtual void  
Public function Virtual Const bool  
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 Virtual void  
Public function void

BeginCacheShaders ( const FMaterialShaderMapId& ShaderMapId,
EShaderPlatform Platform,
EMaterialShaderPrecompileMode PrecompileMode,
const ITargetPlatform* TargetPlatform,
TUniqueFunction< void(boolbSuccess)>&& CompletionCallback
)

 Begins caching the material shaders for the given static parameter set and platform.
Public function void

BeginCacheShaders ( EShaderPlatform Platform,
EMaterialShaderPrecompileMode PrecompileMode,
const ITargetPlatform* TargetPlatform,
TUniqueFunction< void(boolbSuccess)>&& CompletionCallback
)

 Begins caching the material shaders for the given static parameter set and platform.
Public function void

CacheGivenTypes ( EShaderPlatform ShaderPlatform,
const TArray< const FVertexFactoryType* >& VFTypes,
const TArray< const FShaderPipelineType* >& PipelineTypes,
const TArray< const FShaderType* >& ShaderTypes
)

 Submits local compile jobs for the exact given shader types and vertex factory type combination.
Public function bool

CacheShaders ( const FMaterialShaderMapId& ShaderMapId,
EShaderPlatform Platform,
EMaterialShaderPrecompileMode PrecompileMode,
const ITargetPlatform* TargetPlatform
)

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

CacheShaders ( EShaderPlatform Platform,
EMaterialShaderPrecompileMode PrecompileMode,
const ITargetPlatform* TargetPlatform
)

 Caches the material shaders for this material on the given platform.
Public function void Cancels all outstanding compilation jobs for this material.
Public function Virtual Const bool  
Protected function Virtual Const bool Checks that no pre-compilation errors have been detected and if so it reports them using specified compiler.
Public function FGraphEventArray

CollectPSOs ( ERHIFeatureLevel::Type InFeatureLevel,
const FPSOPrecacheVertexFactoryDataList& VertexFactoryDataList,
const FPSOPrecacheParams& PreCacheParams,
EPSOPrecachePriority Priority,
TArray< FMaterialPSOPrecacheRequestID >& OutMaterialPSORequestIDs
)

 Collect all possible PSO's which can be used with this material for given parameters - PSOs will be async precached
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  
Public function Static void

DeferredDelete ( FMaterial* Material
)

  
Public function Static void

DeferredDeleteArray ( TArray< TMaterial* >& Materials
)

  
Public function Static void

DeferredDeleteArray ( TArray< TRefCountPtr< TMaterial >>& Materials
)

  
Public function Static void  
Public function void Discards loaded shader maps if the application can't render
Public function void

DumpDebugInfo ( FOutputDevice& OutputDevice
)

  
Public function Virtual void  
Public function Const bool Finishes any pending material caching.
Public function void Blocks until compilation has completed. Returns immediately if a compilation is not outstanding.
Public function Virtual Const void Gather any UMaterialExpressionCustomOutput expressions they can be compiled in turn
Public function Virtual Const void Gather any UMaterialExpressionCustomOutput expressions in the material and referenced function calls
Public function Virtual Const bool Returns true if this material is allowed to make development shaders via the global CVar CompileShadersForDevelopment.
Public function Virtual Const FString Similar to GetFriendlyName, but but avoids historical behavior of the former, returning the exact asset name for material instances instead of just the material.
Public function Virtual Const FName Allows to associate the shader resources with the asset for load order.
Protected function Virtual Const FString Useful for debugging.
Public function Virtual Const int32  
Public function Virtual Const bool  
Public function Const enum EBlendMode  
Public function Const const FMaterialCachedExpressionData &  
Public function Virtual Const const FMaterialCachedHLSLTree *  
Public function Const bool  
Public function Const const TArray< FString > &  
Public function Const uint8 The material usage mask of CustomDepth and CustomStencil
Protected function Virtual Const FString  
Protected function Const void

GetDependentShaderAndVFTypes ( EShaderPlatform Platform,
const FPlatformTypeLayoutParameters& LayoutParams,
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 Virtual Const FDisplacementScaling  
Public function Const const TArray< UMaterialExpression * > &  
Public function Const const FStaticFeatureLevel  
Public function Virtual Const bool  
Public function Const FString  
Public function Virtual Const FString  
Protected function Const uint32  
Public function Const FMaterialShaderMap *  
Public function Const const FGuid &  
Protected function Const bool  
Public function Virtual Const uint32  
Public function Const EMaterialDomain  
Public function bool Get user source code for the material, with a list of code snippets to highlight representing the code for each MaterialExpression
Public function Virtual Const enum EMaterialFloatPrecisionMode  
Protected function Virtual Const UMaterialExpression * The returned value is not const because the expression is used to build the Strata tree and this requires to execute multiple such as link function caller, compile expression, etc.
Protected function Const FGuid Gets the Guid that represents this material.
Public function Virtual Const UMaterialInterface *  
Public function Virtual Const EMaterialShaderMapUsage::Type Returns which shadermap this material is bound to.
Public function Const FString Returns a string that describes the material's usage for debugging purposes.
Public function Virtual Const int32  
Public function Const float  
Public function Const FName For tracking ownership data
Public function Const EMaterialQualityLevel::Type  
Public function Const uint32  
Public function Const TArrayView< const TObjectPtr< UObject > >  
Public function Virtual Const ERefractionCoverageMode  
Public function Virtual Const float  
Public function Virtual Const enum ERefractionMode  
Public function Const FMaterialShaderMap *  
Public function Const bool  
Public function Const uint8 Get the runtime virtual texture output attribute mask for the material.
Public function Const uint8  
Public function Const TShaderRef< 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 TShaderRef< ShaderType >

GetShader ( FVertexFactoryType* VertexFactoryType,
int32 PermutationId,
bool bFatalIfMissing
)

  
Public function Virtual Const void

GetShaderMapId ( EShaderPlatform Platform,
const ITargetPlatform* TargetPlatform,
FMaterialShaderMapId& OutId
)

 Material properties.
Protected function void Fills the passed array with IDs of shader maps unfinished compilation jobs.
Protected function Const const FMaterialShaderMap * Shared code needed for GetUniformScalarParameterExpressions, GetUniformVectorParameterExpressions, GetUniformCubeTextureExpressions..
Protected function Virtual Const EMaterialShaderMapUsage::Type Gets the shader map usage of the material, which will be included in the DDC key.
Public function Const FShaderPipelineRef

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

  
Public function Const void

GetShaderTypes ( EShaderPlatform Platform,
const FPlatformTypeLayoutParameters& LayoutParams,
TArray< FDebugShaderTypeInfo >& OutShaderInfo
)

 Gathers a list of shader types sorted by vertex factory types that should be cached for this material.
Public function Const void

GetShaderTypesForLayout ( EShaderPlatform Platform,
const FShaderMapLayout& Layout,
FVertexFactoryType* VertexFactory,
TArray< FDebugShaderTypeInfo >& OutShaderInfo
)

  
Public function Const FMaterialShadingModelField  
Public function Virtual Const EMaterialShadingRate  
Public function Virtual Const void

GetStaticParameterSet ( EShaderPlatform Platform,
FStaticParameterSet& OutSet
)

  
Public function Virtual Const uint32  
Public function Virtual Const uint32  
Public function Virtual Const const FStrataCompilationConfig & Get to the strata compilation config
Public function Virtual Const float  
Public function Virtual Const enum ETranslucencyLightingMode  
Public function Virtual Const float  
Public function Virtual Const FLinearColor  
Public function Virtual Const float  
Public function Virtual Const float  
Public function Virtual Const float  
Public function Virtual Const float  
Public function Virtual Const float  
Public function Const TArrayView< const FMaterialTextureParameterInfo >  
Public function Const TArrayView< const FMaterialTextureParameterInfo >  
Public function Const TArrayView< const FMaterialTextureParameterInfo >  
Public function Const const FUniformExpressionSet & Accessors.
Public function Const TArrayView< const FMaterialNumericParameterInfo >  
Public function Const TArrayView< const FMaterialTextureParameterInfo >  
Public function Const TArrayView< const FMaterialTextureParameterInfo >

GetUniformTextureExpressions ( EMaterialTextureParameterType Type
)

  
Public function Const TArrayView< const FMaterialTextureParameterInfo >  
Public function Const TArrayView< const FMaterialTextureParameterInfo >  
Public function Const FString

GetUniqueAssetName ( EShaderPlatform Platform,
const FMaterialShaderMapId& ShaderMapId
)

 Similar to GetFriendlyName, but appends a hash of shader map ID portion of the DDC key (excluding source file hashes) to differentiate materials/material instances that would collide when considering the base material name alone (this name is used when creating debug output paths for disambiguation).
Public function Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool

HasMaterialPropertyConnected ( EMaterialProperty In
)

  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool

HasShaders ( const FMaterialShaderTypes& InTypes,
const FVertexFactoryType* InVertexFactoryType
)

  
Public function Virtual Const bool  
Public function Const bool Checks if there is a valid GameThreadShaderMap, that is, the material can be rendered as intended.
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool Returns whether or not a material caching is still pending.
Public function Const bool Checks if the compilation for this shader is finished
Public function Virtual Const bool  
Public function Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool

IsDualBlendingEnabled ( EShaderPlatform Platform
)

  
Public function Virtual Const bool  
Public function Const bool  
Public function Const bool  
Public function Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Const bool Should shaders compiled for this material be saved to disk?
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Const bool Is the material required to be complete? Default materials, special engine materials, etc
Public function Const bool  
Public function Virtual Const bool

IsSky ()

  
Public function Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool Should the material be compiled using exec pin?
Public function Virtual Const bool  
Public function Virtual Const bool Is the material using the new (WIP) HLSL generator?
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Const bool  
Public function Virtual void Serializes the material.
Public function Const uint8 Get Strata material BSDF count.
Public function Const uint8  
Public function Const uint8 Get Strata material type (single, single, complex slab).
Public function Const uint8  
Public function Const uint8 Get Strata material uint count per pixel.
Public function Const uint8  
Public function Const bool Get Strata material special path requirement (for more expenssive features such as Glints or SpecularLUT).
Public function Const bool  
Public function Const bool 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  
Public function Const bool Does the material modify the mesh position.
Public function Const bool  
Public function Const bool  
Public function Const bool  
Public function Const bool Does the material use displacement.
Public function Const bool Does the material use a distance cull fade.
Public function Const bool  
Public function Const bool Does the material use a pixel depth offset.
Public function Const bool  
Public function Const bool Does the material use a SceneDepth lookup.
Public function Const bool  
Public function Const bool Does the material use world position offset.
Public function Const bool  
Public function Const bool  
Public function Virtual void 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 bool Prepares to destroy the material, must be called from game thread Returns 'true' if PrepareDestroy_RenderThread() is required
Public function Virtual void Prepares to destroy the material, must be called from render thread, only if PrepareDestroy_GameThread() returned true
Public function void

RegisterInlineShaderMap ( bool bLoadedByCookedMaterial
)

 Serializes the shader map inline in this material, including any shader dependencies.
Public function Const uint32

Release ()

  
Public function void Releases this material's shader map.
Public function Const bool  
Public function Const bool  
Public function Virtual Const bool  
Public function Static void

RestoreEditorLoadedMaterialShadersFromMemory ( const TMap< FMaterialShaderMap*, TUniquePtr< TArray< uint8 > > >& ShaderMapToSerializedShaderD...
)

 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 Serializes the shader map inline in this material, including any shader dependencies.
Public function void

SetCompileErrors ( const TArray< FString >& InCompileErrors
)

  
Protected function void

SetCompilingShaderMap ( FMaterialShaderMap* InMaterialShaderMap
)

  
Public function void

SetGameThreadShaderMap ( FMaterialShaderMap* InMaterialShaderMap
)

  
Public function void

SetInlineShaderMap ( FMaterialShaderMap* InMaterialShaderMap
)

  
Public function void  
Protected function void  
Public function void  
Public function Static void Sets shader maps on the specified materials without blocking.
Public function Virtual void Set the strata compilation config
Public function Virtual Const void

SetupExtraCompilationSettings ( 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  
Public function Virtual Const bool  
Public function Virtual Const bool  
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

ShouldCachePipeline ( EShaderPlatform Platform,
const FShaderPipelineType* PipelineType,
const FVertexFactoryType* VertexFactoryType
)

  
Public function Const bool

ShouldCacheShaders ( const EShaderPlatform ShaderPlatform,
const FMaterialShaderTypes& InTypes,
const FVertexFactoryType* InVertexFactoryType
)

  
Public function Const bool Returns whether this material should be considered for casting dynamic shadows.
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Virtual Const bool Some materials may be loaded early - before the shader library - and need their code inlined
Public function Virtual Const bool  
Public function void

SubmitCompileJobs_GameThread ( EShaderCompileJobPriority Priority
)

  
Public function Const void

SubmitCompileJobs_RenderThread ( EShaderCompileJobPriority Priority
)

  
Public function Const bool

TryGetShaders ( const FMaterialShaderTypes& InTypes,
const FVertexFactoryType* InVertexFactoryType,
FMaterialShaders& OutShaders
)

  
Public function Static void

UpdateEditorLoadedMaterialResources ( EShaderPlatform InShaderPlatform
)

 Recompiles any materials in the EditorLoadedMaterialResources list if they are not complete.
Public function void  
Public function Virtual Const bool  
Public function Virtual Const bool  
Public function Const bool  
Public function Const bool  
Public function Const bool

WritesEveryPixel ( bool bShadowPass
)

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

WritesEveryPixel ( bool bShadowPass,
bool bVFTypeSupportsNullPixelShader
)

 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.
PrecachedPSORequestIDsCS Shared critical section on PrecachedPSORequestIDs because contention should be very limited

Deprecated Functions

  Type Name Description
Public function Virtual Const bool Should instead check individual properties
Public function Const bool This function is deprecated. Use MaterialUsesPixelDepthOffset_RenderThread() instead.
Protected function void

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

 Parameter bInHasQualityLevelUsage is deprecated
Public function Const bool This function is deprecated. Use MaterialUsesWorldPositionOffset_GameThread() instead.

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page