Materials Compendium

Document Summary: A description of all material expressions available in UnrealEd's material editor.

Document Changelog: Original article by Alan Willard; updated by Dave Burke^? and Wyeth Johnson.

Overview

This page is a reference for all material expression nodes available in the material editor.

How to Think About Color When Creating Materials

When thinking about materials in UE3, keep in mind that many expressions operate independently on each channel. For example, the Add node takes two inputs and adds them together per channel. If you add together two RGB colors (3-channel values), then the output color will be (Red1+Red2, Green1+Green2, Blue1+Blue2). Think of a per-channel operataion as an operation on greyscale values.

Nodes that perform per-channel operations generally need inputs that have the same number of channels. For example, you can add an RGB color to another RGB color, but you can't add an RGBA color to a RGB color, because the RGB color doesn't have an alaph channel. The exception to this rule is when one of the inputs is a single-channel (greyscale) value, when can apply to anything. So, you are allowed to add 0.1 to the RGB color (0.2,0.3,0.5) to get (0.3,0.4,0.6).

The other thing to keep in mind is that colors in the Unreal Engine are floating point -- in other words, colors no longer have RGB values in the range [0,255]. Instead, RGB values can be anything -- 0.4, -1.2, 3.4 -- where 0.0 means black/no color (0 in the old scheme) and 1.0 means full color (255 in the old scheme). That said, it's perfectly valid to have numbers bigger than 1.0 -- bigger means brighter! (255,0,0) used to be red -- in the Unreal Engine, red is (1.0,0.0,0.0), and a really bright red is (3.0,0.0,0.0).

Colors can also be negative! Think of negative colors as a way of removing color. For example, you can add (-0.5,0.0,0.0) to a texture to reduce all the red colors in the texture by 0.5.

Intermediate expressions are calculated in floating point, but each channel of the final output color of the material will be clamped into [0,4], where 0 is no contribution and 1 is full contribution. Anything over 1 will still result in the same color but will be picked up by the bloom bright pass, and the magnitude of the channel then directly affects the bloom contribution.

Other pages that may be of interest include the MaterialsTutorial page, which is a description of how to combine nodes to achieve various material effects. For a description of how to use the material editor itself, please see MaterialEditor. If you're a programmer, see CreatingMaterialExpressions for details on how to create new material expressions.

Operations

Abs

Abs is an abbreviation for the mathematical term "absolute value". Abs turns negative numbers into positive numbers by knocking off the minus sign. Positive numbers aren't touched.

Examples: Abs of -0.7 is 0.7; Abs of -1.0 is 1.0; Abs of 1.0 is also 1.0

Example Usage: Abs is commonly used with DotProduct. DotProduct goes from -1..0..1, while taking the Abs of DotProduct will go from 1..0..1.

Add

Similar to Photoshop's screen layer blend, the Add node takes two inputs, adds them together and outputs the result. The addition happens per channel.

Examples: Add of 0.2 and 0.4 is 0.6; Add of (0.2,-0.4,0.6) and (0.1,0.5,1.0) is (0.3,0.1,1.6); Add of (0.2,-0.4,0.6) and 1.0 is (1.2,0.6,1.6)

Example Usage: Add is often used to brighten/darken colors and offset UVs.

AppendVector

As with a full color RGB image created from three different greyscales, AppendVector allows you to combine channels together to create a vector with more channels than the original. For example, you can two individual numbers (Constants) and append them to make a two-channel value (Constant2Vector).

Examples: Append of 0.2 and 0.4 is (0.2,0.4); Append of (0.2,0.4) and (1.6) is (0.2,0.4,1.6).

BumpOffset

BumpOffset is the Unreal Engine 3 term for what is commonly known as 'parallax mapping'. BumpOffset materials give the illusion of depth without the need for additional geometry. BumpOffset materials use a heightmap to give depth information. The brighter the value in the heightmap, the more 'popped out' the material will be; these areas will parallax (shift) as a camera moves across the surface. Darker areas in the heightmap are 'further away' and will shift the least. BumpOffset nodes have the following properties:

HeightRatio: Multiplies the depth. The bigger the value, the more extreme the depth will be. Typical values range from .02 to .1

ReferencePlane: Specifies the approximate height in texture space to apply the effect. A value of 0 will appear to distort the texture completely off the surface, whereas a value of 0.5 (the default) means that some of the surface will pop off while some areas will be sunken.

CameraVector

CameraVector is a three-channel value representing the direction of the camera with respect to the surface.

Example Usage: CameraVector is often used to fake environment maps by connecting the CameraVector to a ComponentMask and use the x and y channels of the CameraVector as texture coordinates.

CameraWorldPosition

CameraWorldPosition is the camera's position in world space.

The preview sphere changes color as the camera rotates.

Ceil

Ceil will round values up to the next integer. See also Floor and Frac.

Examples: Ceil of 0.2 is 1.0; Ceil of (0.2,1.6) is (1.0,2.0).

Clamp

Clamp is used to constrain values to a specified range, defined by a minimum (Min) and maximum (Max) value. "Min 0.0, max 0.5" means that the resulting value will never be less than 0.0 and never greater than 0.5.

Examples: Clamping 0.3 with Min 0.0 and Max 1.0 yields 0.3; Clamping 1.3 with Min 0.0 and Max 1.0 yields 1.0;

ComponentMask

ComponentMask allows you to strip away channels, or select out only a subset of channels. ComponentMask has four checkboxes representing each channel (R, G, B, and A) which, when checked, will pass that channel through to the final result.

Examples: ComponentMask with an input of (0.2,0.8,1.4) and the R and B channels checked will output (0.2,1.4).

Constant

One of the most commonly used material nodes, a Constant is a number. Constants aren't limited to whole numbers; they can have decimal places and be negative numbers.

Examples: 0.7, -0.24, 1.1

Constant2Vector

Constant2Vector is a 2-channel value -- in other words, two constants numbers.

Examples: (0.4, 0.6), (1.05, -0.3)

Constant3Vector

Constant3Vector is a 3-channel value -- in other words, three constant numbers. An RGB color can be thought of as a Constant3Vector, where each channel is assigned to a color (red, green, blue).

Examples: (0.4, 0.6, 0.0), (1.05, -0.3, 0.3)

Constant4Vector

Constant3Vector is a 4-channel value -- in other words, four constant numbers. An RGBA color can be thought of as a Constant4Vector, where each channel is assigned to a color (red, green, blue, alpha).

Examples: (0.4, 0.6, 0.0, 1.0), (1.05, -0.3, 0.3, 0.5)

ConstantBiasScale

This is a convenience function that multiplies the input by Scale and then adds Bias. So for example, to convert input data from [0,1] to [-1,1] you would set Scale=2 and bias = -1.

ConstantClamp

Performs the same function as Clamp but uses fixed inputs included in the node itself for simplicity and ease of use. Works well when you have min and max clamp values (say clamping an output from 0 to 1) that do not need to be variable over time.

Cosine

Cosine is a node that outputs a cosine waveform as a function its input, which is typically connected to a Time node. Cosine nodes have a 'Period' property for setting the period ('repeat rate') of the signal

CrossProduct

CrossProduct computes the cross product of two input 3-vectors. given two lines in space, cross product outputs a line which is perpendicular to these two

Example Usage: CrossProduct is often used to compute directions which are perpendicular to two other directions.

DepthBiasBlend

DepthBiasBlend is slower and less flexible than the other depth-biased blending nodes; use DepthBiasAlpha instead.

DepthBiasBlend is most commonly used in materials on sprite particles to remove the sharp edges occurring when the sprite intersects other geometry. Depth-biased blending compares the depth of src and dst pixels and uses a bias to determine the alpha to use for drawing the pixel. See DepthBiasBlendUsage for more information.

Programmers: DepthBiasBlend is the least preferred of the depth-biased blending nodes because 1) it samples color and depth from the most recent frame/depthbuffer resolves (slow); 2) the blend is performed in shader code rather than via hardware blending (slow); and 3) DepthBiasBlend's texture input is via the Texture property rather than an arbitrary expression input.

DepthBiasAlpha

DepthBiasAlpha is the preferred node to use for depth-biased blending.

DepthBiasAlpha is most commonly used in materials on sprite particles to remove the sharp edges occurring when the sprite intersects other geometry. Depth-biased blending compares the depth of src and dst pixels and uses a bias to determine the alpha to use for drawing the pixel. See DepthBiasBlendUsage for more information.

Programmers: DepthBiasAlpha is the preferred way to do depth-biased blending because the blend is performed in hardware rather than in the shader.

DepthBiasedBlend

DepthBiasedBlend is slower DepthBiasAlpha; use DepthBiasAlpha instead.

DepthBiasedBlend is most commonly used in materials on sprite particles to remove the sharp edges occurring when the sprite intersects other geometry. Depth-biased blending compares the depth of src and dst pixels and uses a bias to determine the alpha to use for drawing the pixel. See DepthBiasBlendUsage for more information.

Programmers: DepthBiasedBlend is the least preferred of the depth-biased blending nodes because 1) it samples color and depth from the most recent frame/depthbuffer resolves (slow); and 2) the blend is performed in shader code rather than via hardware blending (slow).

DeriveNormalZ

This is a convenience node that derives the z component of a tangent space normal given the x and y. The input (InXY) is the x and y of the tangent space normal, and the output is the 3 component tangent space normal. Z is calculated as Z = sqrt(1 - (x * x + y * y));

Desaturation

A Desaturation node will desaturate its input based a certain percentage specified by the Percent input. Percent can range from 0.0 (fully desaturated) to 1.0 (full original color, no desaturation). The Luminance property of the node specifies the amount of desaturation per channel.

Programmers: Define desaturated color D, input color I and luminance factor L. The output will be O = (1-Percent)*(D.dot(I)) + Percent*I

DestColor

DestColor samples the existing color behind the pixel currently being drawn.

Example Usage: A water material can use DestColor to sample the color of the rocks under the water.

DestDepth

DestColor samples the existing depth behind the pixel currently being drawn.

Example Usage: A water material can use DestDepth to give water a "thickness" or fog color, where the deeper the water (the greater the depth), the more the water obscures the rocks under the water

Programmers: DestDepth returns a raw depth value (integer from 0 to 2^24-1). This non-leaner depth can be normalized as follows:

   MaxZ = 16777215
   NormalizedDepth = 1 - MaxZ / (DestDepth + MaxZ)

The resulting normalized depth is linear in the 0.0 to 1.0 range.

Divide

Divide takes two inputs A and B, outputting the result of A divided by B. The division happens per channel.

Examples: The output of a Divide with A=(1.0,0.5,-0.4) and B=(2.0,2.0,4.0) is (0.5,0.25,-0.1)

DotProduct

DotProduct computes the dot product of two inputs, and is used by many techniques for computing falloff. DotProduct requires both two inputs to have the same number of channels.

DynamicParameter

A DynamicParameter node provides material parameters per-particle for particle emitters. These values are set in Cascade via a ParameterDynamic module placed on an emitter.

FlipBookSample

A FlipBookSample node is the TextureSample node for flipbook textures. Textures that were imported as flipbook texture need to use a FlipBookSample node. Under the hood, FlipBookSample performs the necessary UV manipulation to render the subimages of a flipbook texture, based on the HorizontalImages, VerticalImages and FrameRate properties of the flipbook texture.

Floor

Ceil will round values down to the last integer. See also Ceil and Frac

Examples: Floor of 0.2 is 0.0; Floor of (0.2,1.6) is (0.0, 1.0).

Frac

Frac outputs the decimal part of a number. See also Ceil and Frac

Examples: Frac of 0.2 is 0.2; Frac of (0.0,1.6) is (0.0, 0.6)

Fresnel

takes a normal. Exponent = higher the value, the "tighter" the falloff along the edge the result is clamped to 0,1 so you don't have any negative color in the center

If

The If node compares two inputs, A and B; the output is chosen based on the result of the comparison:

 If A is less than B, the output is ALessThanB.
 If A is the same as B, the output is AEqualsB.
 If A is greater than B, the output is AGreaterThanB.

Example Usage: The 'If' node can be used

LensFlareIntensity

LensFlareOcclusion

LensFlareRadialDistance

LensFlareRayDistance

LensFlareSourceDistance

LightVector

LightVector is a three-channel value representing the direction of the light with respect to the surface.

Example Usage: LightVector can be used to "project" textures from lights onto surfaces as the light passes over a surface.

Note: The LightVector expression is not valid while evaluating the Emissive output.

LinearInterpolate

LinearInterpolate can be thought of as a mask to define transitions between two textures, like a layer mask Photoshop. LinearInterpolate takes three inputs: A and B (the input textures/colors) and Alpha (the mask). The intensity of the mask Alpha determines the ratio of color to take from textures A and B. If Alpha is 1.0/white, A is used. If Alpha is 0.0/black, B is used. If Alpha is grey (somewhere between 0.0 and 1.0, the output is a blend between A and B.

Keep in mind that the blend happens per channel. So, if Alpha is an RGB color, Alpha's red channel value defines the blend between A and B's red channels independently of Alpha's green channel, which defines the blend between A and B's green channels.

Programmers: LinearInterpolate does a per-channel lerp between A and B based on the parametric value Alpha.

MeshEmitterVertexColor

Materials used on mesh particles must use this node!

A MeshEmitterVertexColor node is the access point for the material to the outputs of color modules affecting mesh particles emitters. Each mesh rendered as a particle by a mesh emitter has a color available to it -- this is that color.

Programmers: This color is communicated to the shader as a constant, and is not a per-vertex color for mesh particles.

MeshSubUV

Like ParticleSubUV for meshes instead of sprites This needs to be used to avoid repacking the texture coordinates for a mesh particle every frame.

Multiply

Similar to Photoshop's multiply layer blend, a Multiply node takes two inputs, multiplies them together and outputs the result. The multiplication happens per channel.

Don't forget that materials in UE3 are not limited to [0,1]! If colors/values are greater than 1, Multiply will actually brighten colors.

Examples: Multiply of 0.4 and 0.5 is 0.2; Multiply of (0.2,-0.4,0.6) and (0.0,2.0,1.0) is (0.0,-0.8,0.6); Multiply of (0.2,-0.4,0.6) and 0.5 is (0.2,-0.4,0.6)

Example Usage: Multiply is often used to brighten or darken colors/textures.

Normalize

Normalize will normalize its input -- in other words, each component is divided by the L-2 norm of the vector.

Note: It is not necessary to normalize an expression which plugs into the Normal material output.

OneMinus

OneMinus takes an input value and outputs one minus that value.

Examples: OneMinus of 0.4 is 0.6; OneMinus of (0.2,0.5,1.0) is (0.8,0.5,0.0); OneMinus of (0.0,-0.4,1.6) is (1.0,1.4,-0.6)

Example Usage: When the input colors are in the range [0,1], OneMinus has the same effect as what is commonly called "invert" -- that is, OneMinus returns the complimentary color that when added to the input will produce white.

Panner

Panner is used to create panning textures. The horizontal and vertical texture panning speeds can be controlled independently with the SpeedX and SpeedY properties.

Panner generates UVs that change according to the Time input. The Coordinate input can be used to manipulate (e.g. offset) the UVs generated by the Panner node.

ParticleSubUV

ParticleSubUV is used to render subimages of a texture to a particle. ParticleSubUV is similar to a flipbook, except that ParticleSubUV allows the texture animation to be manipulated in Cascade^?.

The UV input of ParticleSubUV is ignored and does nothing.

PixelDepth

PixelDepth nodes output the depth of the pixel currently being rendered. For details on using the value, consult DestDepth.

Power

The Power node takes two inputs, Base and Exp. The output is Base raised to the Exp power -- in other words, Base multiplied by itself Exp times.

Examples: Power of Base 0.5, Exp 2.0 is 0.25;

Example Usage: If the colors you pass to Power are in [0,1], Power can behave as a contrast adjustment, where only the brighter values remain.

ReflectionVector

ReflectonVector is similar in spirit to CameraVector. The output of a ReflectionVector is the camera direction reflected across the surface normal.

Example Usage: ReflectionVector is commonly used in environment maps, where the x/y components of the reflection vector are used as UVs into a cubemap texture.

Rotator

Rotator used to create rotating textures. The rotation speed can be controlled with the Speed property, and the center of rotation can be chosen with the CenterX and CenterY properties.

Rotator generates UVs that change according to the Time input. The Coordinate input can be used to manipulate (e.g. offset) the UVs generated by the rotator node.

ScalarParameter

The ScalarParameter node exposes a single number (Constant) so that its value can be accessed and changed on the fly by code. ScalarParameter's Name property is the name that code will use to access the constant, while DefaultValue is the initial value that the constant takes on.

SceneDepth

Similar to DestDepth, SceneDepth samples the existing scene depth. Where DestDepth and SceneDepth differ is that DestDepth can sample the depth only at the pixel currently being drawn, whereas SceneDepth can sample depth at any location. The value of the UVs input specifies location from which to draw the sample.

Programmers: SceneDepth returns a raw depth value (integer from 0 to 2^24-1). This non-linear depth can be normalized as follows:

   MaxZ = 16777215
   NormalizedDepth = 1 - MaxZ / (SceneDepth + MaxZ)

The resulting normalized depth is linear in the 0.0 to 1.0 range.

SceneTexture

Similar to DestColor, SceneColor samples the existing scene color Where DestColor and SceneTexture differ is that DestColor can sample the color only at the pixel currently being drawn, whereas SceneTexture can sample color at any location. The value of the UVs input specifies location from which to draw the sample.

ScreenPosition

The ScreenPosition node provides access to the worldspace position of the pixel currently being rendered. If the ScreenAlign property is checked, ScreenPosition divides the position by the homogeneous coordinate and maps the position to [-1,-1]-[1,1] for screen alignment.

Sine

Sine is a node that outputs a sine waveform as a function its input, which is typically connected to a Time node. Sine nodes have a 'Period' property for setting the period ('repeat rate') of the signal

SquareRoot

SquareRoot computes the square root of its input. SquareRoot can operate only on a single-channel input.

Subtract

The Subtract node takes two inputs A and B, and outputs A-B. The subtraction happens per channel.

Examples: Subtract of 0.5 and 0.2 is 0.3; Subtract of (0.2,-0.4,0.6) and (0.1,0.1,1.0) is (0.1,-0.5,-0.4); Subtract of (0.2,0.4,1.0) and 0.2 is (0.0,0.2,0.8)

Example Usage: Subtract can be used to darken colors and offset UVs.

Static Switch Parameter

The Static Switch Parameter node takes two inputs A and B, and outputs A if the value of the parameter is true, and B otherwise. These parameters are named static because they cannot change at runtime, they can only be set in the MaterialInstanceEditor. Static Switches are applied at compile time, not at runtime. This means that whatever branch of the material was dropped will never be executed, so static switches are effectively free at runtime. On the other hand, a new version of the material must be compiled out for every used combination of static parameters in a material, which can lead to a shader explosion if abused. Try to minimize the number of static parameters in the material and the number of permutations of those static parameters that are actually used.

Example Usage: Static Switches can be used to remove an entire branch of a material with no runtime cost. Instances can have different values, making it possible to have a templated shader setup with no performance loss.

Static Component Mask Parameter

The Static Component Mask Parameter behaves just like an ordinary Component Mask, except that the mask values can be set by instances. It is static because it cannot change at runtime, it can only be set in the MaterialInstanceEditor. Static Component Masks are applied at compile time, not at runtime. A new version of the material must be compiled out for every used combination of static parameters in a material, which can lead to a shader explosion if abused. Try to minimize the number of static parameters in the material and the number of permutations of those static parameters that are actually used.

Example Usage: Static Component Masks can be used to let instances choose which channel of a mask texture to use. If the mask is static (doesn't need to change at runtime) then this approach should always be used instead of multiplying a texture lookup by a vector parameter to mask out channels, since this wastes texture bandwidth and shader instructions.

TextureCoordinate

The TextureCoordinate node allows materials to use different UV channels and otherwise operate on the UVs of a mesh. For example, TextureCoordinate has a Tiling property which indicates the number of times to tile the texture coordinates.

Example Usage: To access the second UV channel of a mesh, create a TextureCoordinate node, set its CoordinateIndex to 1 (0 - first channel, 1 - second channel, etc), and connect it to the UVs input of a TextureSample node.

TextureSample

A TextureSample is a node that represents a texture. Plain and simple.

To set the texture used by a TextureSample node, first select a texture in the Generic Browser. Then, select the Texture property in the node's property window and click the 'Use Current Selection' button.

The outputs of TextureSample node can be used to connect individual color channels to the inputs of other nodes. From top to bottom, TextureSample's outputs are RGBA, red, green, blue, and alpha.

If a texture does not contain an alpha channel, connecting the 'alpha' channel to something, while not technically illegal, will always result in zero (black).

By default, TextureSample nodes use the texture coordinates of the mesh the material is applied to. These texture coordinates can be modified by connecting another node to the UVs input. For example, a Panner node can be connected to the UVs input to created a panning texture.

If the TextureSample represents a cubemap texture, the UVs coordinate must be a three-channel value rather than just a two-channel value.

TextureSampleParameter2D

Like a ScalarParameter, except that exposed value is a texture instead of a single value.

TextureSampleParameterCube

Like a ScalarParameter, except that exposed value is a cubemap texture instead of a single value.

TextureSampleParameterMovie

Like a ScalarParameter, except that exposed value is a movie texture instead of a single value.

Time

The Time node is used to add the passage of time to a material, such as a Panner, Cosine, or other time-dependent operation. If the bIgnorePause property is checked, Time will continue to march on even if the game is paused.

Transform

Warning: VertexColor is mutually exclusive with the Transform node due to limited interpolators. If you use both a Transform node and VertexColor, then VertexColor will come out all white.

By default, all shader calculations in a material are done in tangent space. The vector constants, camera vector, light vector, etc are all transformed to tangent space before being used in a material.

The Transform node allows any 3-vector value to be transformed to other spaces. The TransformType property specifies the target space, and is one of world, view, or local space.

The Transform node accounts for mirrored UVs, thus allowing, for example, highlights that only affect the right edge of a character.

The Transform node is useful for generating world space normals for sampling a cubemap. A normal map can be transformed to world space. Below is an example of transforming normals to world space in order to sample a cubemap:

Transforming normals to view space can be used for creating edge-on effects. This can be achieved by using mesh normals to generate texture coordinates (commonly referred to as "Sphere Mapping"). With this method, normals facing directly at the camera will map to the center of the texture coordinates, and normals facing perpendicular to the camera will map at the edge of the texture coordinates. Here is an example of Sphere Mapping:

This material is located in the Build for licensees at: UTGame\DemoContent\Packages\UDN_ExampleMaterials\CoordinateTransform\Mat erials\ M_UDN_EM_CoordinateTransform_Materials_SphereMap01

A constant3vector with a value of (0,0,1) is fed into the Transform with TRANSFORM_View set, which is then passed through a ComponentMask (Passing

through only R and G). Since the Transform will output a range of values from -1 to 1, we must bias the values to put them into the 0-1 range. This

is done by multiplying by 0.5, and then adding 0.5. Then simply plug that into the Coordinates of a texture. Any texture will work; I made one with

three rings so that the effect is obvious.

To use this effect with a normal map, simply substitute the Constant3Vector with a normal map texture.

Here is an example of this spheremap material applied to a blob-like rock mesh:

TransformPosition

This node is deprecated due to major precision problems when used to derive world pos away from the origin! Use the WorldPosition node instead.

The TransformPosition node can transform any position from screen space to the destination space specified by the expression's TransformType variable. Currently only transforming into world space is supported. This expression can be used to get world space coordinates in the material. To visualize world position, you can plug it straight into emissive:

You can also use world position as planar texture coordinates:

WorldPosition

The WorldPosition node is the position of the current pixel in world space. To visualize, simply plug the output into Emissive:

Common uses are to find the radial distance from the camera to a pixel (as opposed to the orthogonal distance from PixelDepth). WorldPosition is also useful to use as a texture coordinate and have unrelated meshes using the texture coord match up when they are near each other. Here is a basic example of using WorldPosition.xy to planar map a texture:

VectorParameter

Like a ScalarParameter, except that exposed value is a multi-channel value instead of a single value.

VertexColor

Like a MeshEmitterVertexColor except for sprite particles.

Warning: VertexColor is mutually exclusive with the Transform node due to limited interpolators. If you use both a Transform node and VertexColor, then VertexColor will come out all white.

Programmers: For sprite particles, colors are communicated to the shader per vertex, whereas colors for mesh particles are set as shader constants.