Navigation
API > API/Runtime > API/Runtime/Engine
The FEmitter is a helper object responsible for emitting MIR values and instructions. It is primarily used within UMaterialExpression::Build() implementations to lower the high-level semantics of a material expression into corresponding lower-level MIR nodes.
During the emission process, the emitter automatically performs various simplifications and constant folding optimizations where possible.
An instance of the emitter is created and managed by the FMaterialIRModuleBuilder. This instance is then passed to the UMaterialExpression::Build() functions so that they can emit their corresponding IR values.
IMPORTANT: Users should not assume the exact MIR::FType of the FValue* returned by EmitXXX() functions. The emitter is free to optimize operations, which may result in a returned value having a different type than naively expected (e.g., folding an operation into a constant).
The emitter handles invalid inputs gracefully. If an operation is attempted with invalid arguments (e.g., acting on arguments of unexpected types), the emitter automatically reports an error and returns the MIR::FPoison value. Furthermore, all EmitXXX() functions are robust to receiving MIR::FPoison as input; they will simply propagate the poison value without attempting the operation.
| Name | FEmitter |
| Type | class |
| Header File | /Engine/Source/Runtime/Engine/Public/Materials/MaterialIREmitter.h |
| Include Path | #include "Materials/MaterialIREmitter.h" |
Syntax
class FEmitter
Constructors
| Name | Remarks | Include Path | Unreal Specifiers |
|---|---|---|---|
FEmitter() |
Materials/MaterialIREmitter.h |
Structs
| Name | Remarks |
|---|---|
| FPrivate | |
| FValueKeyFuncs |
Variables
Protected
| Name | Type | Remarks | Include Path | Unreal Specifiers |
|---|---|---|---|---|
| bCurrentExpressionHasErrors | bool | Whether the current expression has reported any error. | Materials/MaterialIREmitter.h | |
| BuilderImpl | FMaterialIRModuleBuilderImpl * | Pointer to the builder internal implementation. | Materials/MaterialIREmitter.h | |
| Expression | UMaterialExpression * | The current expression being built (set by the builder). | Materials/MaterialIREmitter.h | |
| FalseConstant | FValue * | Global "false" constant. | Materials/MaterialIREmitter.h | |
| FMaterialIRModuleBuilder | friend | Materials/MaterialIREmitter.h | ||
| FMaterialIRModuleBuilderImpl | friend | Materials/MaterialIREmitter.h | ||
| Material | UMaterial * | The material being translated. | Materials/MaterialIREmitter.h | |
| Module | FMaterialIRModule * | The IR module being built. | Materials/MaterialIREmitter.h | |
| StaticParameterSet | const FStaticParameterSet * | The set of static parameter assignments to use during this translation. | Materials/MaterialIREmitter.h | |
| TrueConstant | FValue * | Global "true" constant. | Materials/MaterialIREmitter.h | |
| ValueSet | TSet< FValue *, FValueKeyFuncs > | The set of all values previously emitted. | Materials/MaterialIREmitter.h |
Functions
Public
| Name | Remarks | Include Path | Unreal Specifiers |
|---|---|---|---|
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
FValueRef Aggregate
(
const UMaterialAggregate* InAggregate, |
Constructs an aggregate value using the given type and prototype, initializing its attributes using the provided assignments. | Materials/MaterialIREmitter.h | |
FValueRef Aggregate
(
const UMaterialAggregate* InAggregate, |
Constructs an aggregate value using the given type and prototype, and initializes it with the provided list of attribute values. | Materials/MaterialIREmitter.h | |
FValueRef Aggregate
(
const UMaterialAggregate* InAggregate |
Constructs an aggregate value using the provided aggregate definition. | Materials/MaterialIREmitter.h | |
FValueRef AnalyticalPartialDerivative
(
FValueRef Value, |
Computes and emits the analytical partial derivative of a give value. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Emits a branch instruction. | Materials/MaterialIREmitter.h | ||
| Emits a call to a specified user function using specified input arguments. | Materials/MaterialIREmitter.h | ||
| Emits an instruction that retrieves the output parameter value from a function call. | Materials/MaterialIREmitter.h | ||
| Casts the given value to the specified target type. Returns poison if the cast is invalid. | Materials/MaterialIREmitter.h | ||
FValueRef CastToBool
(
FValueRef Value, |
These functions cast the given value to the a primitive scalar or column vector type of given rows. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Casts the given primitive value to a scalar. If this is a vector, it will convert to its first component. | Materials/MaterialIREmitter.h | ||
FValueRef CastToScalarKind
(
FValueRef Value, |
Casts the given primitive value to a given scalar kind, maintaining the same number of rows and columns. | Materials/MaterialIREmitter.h | |
| Casts the given primitive value to a row vector of specified columns. | Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
FValueRef CheckIsAggregate
(
FValueRef Value, |
Validates that the value is of an aggregate type. If not, reports error and returns poison. | Materials/MaterialIREmitter.h | |
| Validates that the value is of an arithmetic type (int or float). Reports error and returns poison otherwise. | Materials/MaterialIREmitter.h | ||
| Validates that the value is of a boolean type. If not, reports an error and returns poison. | Materials/MaterialIREmitter.h | ||
| Validates that the value is of a integral type. If not, reports an error and returns poison. | Materials/MaterialIREmitter.h | ||
| Validates that the value is a matrix. If not, reports error and returns poison. | Materials/MaterialIREmitter.h | ||
| Validates that the value is of a primitive type. If not, reports an error and returns poison. | Materials/MaterialIREmitter.h | ||
| Validates that the value is a scalar. If not, reports error and returns poison. | Materials/MaterialIREmitter.h | ||
| Validates that the value is either a scalar or a vector. Reports error and returns poison otherwise. | Materials/MaterialIREmitter.h | ||
FValueRef CheckIsTexture
(
FValueRef Value |
Retrieves the texture value flowing into given input. | Materials/MaterialIREmitter.h | |
| Validates that the value is a vector. If not, reports error and returns poison. | Materials/MaterialIREmitter.h | ||
FValueRef CheckTypeIsKind
(
FValueRef Value, |
Retrieves the value from the given input of given type kind. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
FValueRef ConstantBool
(
bool InX |
Returns the given constant boolean scalar. | Materials/MaterialIREmitter.h | |
FValueRef ConstantBool2
(
bool InX, |
Emits a constant bool 2D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantBool3
(
bool InX, |
Emits a constant bool 3D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantBool4
(
bool InX, |
Emits a constant bool 4D column vector and returns it. | Materials/MaterialIREmitter.h | |
| Emits a default value of given type (zero initialized). | Materials/MaterialIREmitter.h | ||
FValueRef ConstantDouble
(
TDouble InX |
Returns the given constant LWC scalar. | Materials/MaterialIREmitter.h | |
FValueRef ConstantFalse() |
Returns the constant boolean scalar `false_. | Materials/MaterialIREmitter.h | |
FValueRef ConstantFloat
(
TFloat InX |
Returns the given constant float scalar. | Materials/MaterialIREmitter.h | |
FValueRef ConstantFloat2
(
UE::Math::TVector2< TFloat > InValue |
Emits a constant float 2D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantFloat3
(
UE::Math::TVector< TFloat > InValue |
Emits a constant float 3D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantFloat4
(
UE::Math::TVector4< TFloat > InValue |
Emits a constant float 4D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantFromShaderValue
(
const UE::Shader::FValue& InValue |
Converts the given UE::Shader::FValue to a MIR constant value and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantInt
(
TInteger InX |
Returns the given constant integer scalar. | Materials/MaterialIREmitter.h | |
FValueRef ConstantInt2
(
UE::Math::TIntVector2< TInteger > InValue |
Emits a constant integer 2D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantInt3
(
UE::Math::TIntVector3< TInteger > InValue |
Emits a constant integer 3D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantInt4
(
UE::Math::TIntVector4< TInteger > InValue |
Emits a constant integer 4D column vector and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantOne
(
EScalarKind Kind |
Emits a scalar constant value of given kind with value 1 and returns it. | Materials/MaterialIREmitter.h | |
FValueRef ConstantScalar
(
EScalarKind Kind, |
Casts the given float value to the given scalar kind and returns its value. | Materials/MaterialIREmitter.h | |
FValueRef ConstantTrue() |
Returns the constant boolean scalar `true_. | Materials/MaterialIREmitter.h | |
FValueRef ConstantZero
(
EScalarKind Kind |
Emits a scalar constant value of given kind with value 0 and returns it. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
bool CurrentExpressionHasErrors () |
Returns whether the current expression generated an error. | Materials/MaterialIREmitter.h | |
FValueRef CustomPrimitiveData
(
uint32 PrimitiveDataIndex |
Emits a custom primitive data value with given index. | Materials/MaterialIREmitter.h | |
FValueRef DBufferTexture
(
EDBufferTextureId DBufferId |
Emit a screen texture with the given DBuffer Texture id. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
void Error
(
FStringView Message |
Reports an error with given error message. | Materials/MaterialIREmitter.h | |
| Reports an error with given error message. | Materials/MaterialIREmitter.h | ||
void Errorf
(
UE::Core::TCheckedFormatString< FString::FmtCharType, TArgs... > Format, |
Reports an error using printf-like format and arguments to format the error message. | Materials/MaterialIREmitter.h | |
| Reports an error using printf-like format and arguments to format the error message. | Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
FValueRef ExternalInput
(
EExternalInput Id, |
Emits an external input value of given input Id and returns it. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
const FFunction * FunctionHLSL
(
const FFunctionHLSLDesc& Desc |
Defines a user-specified HLSL function to embed in the generated HLSL when generated IR Module is translated to HLSL. | Materials/MaterialIREmitter.h | |
FType GetCommonType
(
FType A, |
Gets the common type between A and B and reports an error if no such type exists. | Materials/MaterialIREmitter.h | |
FType GetCommonType
(
TConstArrayView< FValueRef > Values |
Gets the common type between the specified values types. | Materials/MaterialIREmitter.h | |
ERHIFeatureLevel::Type GetFeatureLevel() |
Materials/MaterialIREmitter.h | ||
FType GetMaterialAggregateAttributeType
(
const UMaterialAggregate* Aggregate, |
Returns the type of the i-th attribute in the given material aggregate. | Materials/MaterialIREmitter.h | |
EMaterialQualityLevel::Type GetQualityLevel() |
Materials/MaterialIREmitter.h | ||
EShaderPlatform GetShaderPlatform() |
Materials/MaterialIREmitter.h | ||
const ITargetPlatform * GetTargetPlatform() |
Materials/MaterialIREmitter.h | ||
UObject * GetTextureFromValue
(
MIR::FValueRef Texture |
Returns the UTexture or URuntimeVirtualTexture of the specified texture object or uniform parameter. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
FValueRef InlineHLSL
(
FType Type, |
Emit a new HLSL function inline within the material shader. | Materials/MaterialIREmitter.h | |
FValueRef InlineHLSL
(
const FMaterialExternalCodeDeclaration* InExternalCodeDeclaration, |
Emit a new HLSL function inline within the material shader based on an external code declaration. | Materials/MaterialIREmitter.h | |
FValueRef Input
(
const FExpressionInput* Input |
Retrieves the value flowing into given input. | Materials/MaterialIREmitter.h | |
FValueRef InputDefaultBool
(
const FExpressionInput* Input, |
If the input has no value flowing in (e.g., because the input is disconnected), these DefaultXXX() functions will emit a constant value, bind it to the input, and return it. | Materials/MaterialIREmitter.h | |
FValueRef InputDefaultFloat
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultFloat2
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultFloat3
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultFloat4
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultInt
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultInt2
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultInt3
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
FValueRef InputDefaultInt4
(
const FExpressionInput* Input, |
Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
FValueRef MaterialParameterCollection
(
UMaterialParameterCollection* Collection |
Emits a material parameter collection. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Emits a NOP instruction that behaves as a default value of Arg type, but will still cause Arg to be analyzed. | Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Emits a mathematical operation instruction with given operator and arguments. | Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
FEmitter & Output
(
const FExpressionOutput* ExpressionOutput, |
Flows given Value_ out of given expression ExpressionOutput_. |
Materials/MaterialIREmitter.h | |
Flows given Value_ out of the expression output with given OutputIndex_. |
Materials/MaterialIREmitter.h | ||
FEmitter & Outputs
(
const TConstArrayView< FExpressionOutput >& ExpressionOutputs, |
Flows given `Value_ out of given expression output list. Each output applies its respective mask. | Materials/MaterialIREmitter.h | |
FValueRef Parameter
(
FName Name, |
Emits a material parameter value with given name, metadata, sampler type (if it's a texture) and optional parameters for RVT layer index and page table index. | Materials/MaterialIREmitter.h | |
FValueRef PartialDerivative
(
FValueRef Value, |
Emits the partial derivative of given value. | Materials/MaterialIREmitter.h | |
FValueRef Poison() |
Emits the poison value. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
FValueRef PreshaderParameter
(
FType Type, |
Emits a preshader parameter value with given opcode. | Materials/MaterialIREmitter.h | |
FValueRef PromoteSubstrateParameter() |
Emits an instruction that promotes a Substrate parameter, encoded as MCT_Substrate. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
FValueRef RuntimeVirtualTextureObject
(
URuntimeVirtualTexture* RVTexture, |
Emits a runtime virtual texture object value. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
FValueRef SceneTexture
(
ESceneTextureId SceneTextureId |
Emit a screen texture with the given Scene Texture id. | Materials/MaterialIREmitter.h | |
FValueRef ScreenTexture
(
EScreenTexture TextureKind |
Emit another type of screen texture (not one of the three types above). | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
FSetMaterialOutput * SetMaterialOutput
(
EMaterialProperty InProperty, |
Emits an instruction that sets the material attribute with given property to given argument. | Materials/MaterialIREmitter.h | |
FValueRef ShadingModel
(
EMaterialShadingModel Id |
Emits a shading model. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
| Materials/MaterialIREmitter.h | |||
FValueRef StageSwitch
(
FType Type, |
Emits a stage switch instruction. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
| Extracts the component with given index from the given argument value. | Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
FValueRef Swizzle
(
FValueRef Value, |
Swizzles the given argument by given mask. | Materials/MaterialIREmitter.h | |
| Materials/MaterialIREmitter.h | |||
FValueRef TextureGather
(
FValueRef Texture, |
Emits a texture gather instruction. | Materials/MaterialIREmitter.h | |
FValueRef TextureObject
(
UTexture* Texture, |
Emits a texture object value of fiven sampler type and returns it. | Materials/MaterialIREmitter.h | |
FValueRef TextureSample
(
FValueRef Texture, |
Emits a texture sample instruction. | Materials/MaterialIREmitter.h | |
FValueRef TextureSampleBias
(
FValueRef Texture, |
Emits a texture sample instruction with bias added to the automatically selected mip level. | Materials/MaterialIREmitter.h | |
| Emits a texture sample instruction using user provided partial derivatives. | Materials/MaterialIREmitter.h | ||
FValueRef TextureSampleLevel
(
FValueRef Texture, |
Emits a texture sample instruction with a manually given mip level. | Materials/MaterialIREmitter.h | |
bool ToConstantBool
(
FValueRef Value |
Casts the value flowing into this input to a constant boolean and returns it. | Materials/MaterialIREmitter.h | |
| Transposes the given MxN primitive value into the NxM result. | Materials/MaterialIREmitter.h | ||
| Materials/MaterialIREmitter.h | |||
FType TryGetCommonType
(
FType A, |
Tries to find a common type between A and B. | Materials/MaterialIREmitter.h | |
FValueRef TryInput
(
const FExpressionInput* Input |
Retrieves the value from the given input, if present. | Materials/MaterialIREmitter.h | |
| Emit a screen texture with the given User Scene Texture name. | Materials/MaterialIREmitter.h | ||
| Emits a 2D column vector from X and Y values. | Materials/MaterialIREmitter.h | ||
| Emits a 3D vector from a 2D vector (XY) and a Z value. | Materials/MaterialIREmitter.h | ||
| Emits a 3D vector from separate X, Y, and Z values. | Materials/MaterialIREmitter.h | ||
| Emits a 4D vector from a 2D vector (XY), a Z value, and a W value. | Materials/MaterialIREmitter.h | ||
| Emits a 4D vector from a 3D vector (XYZ) and a W value. | Materials/MaterialIREmitter.h | ||
| Emits a 4D vector from separate X, Y, Z, and W values. | Materials/MaterialIREmitter.h | ||
FValueRef VTPageTableLoad
(
FValueRef Texture, |
Emits the virtual texture page load instruction. | Materials/MaterialIREmitter.h |