Instanced Materials

Document Summary: Explains how material instancing works.

Document Changelog: Created by Scott Sherman; updated by Dave Burke^? and Amitt Mahajan^?.

Overview

In Unreal Engine 3, material instancing may be used to change the appearance of a material without incurring an expensive recompilation of the material.

General modification of the material cannot be supported without recompilation, so the instances are limited to changing the values of predefined material parameters.

The parameters are statically defined in the compiled material by a unique name, type and default value. An instance of a material can dynamically provide new values for these parameters with very little expense.

To allow applying un-instanced materials to primitives, the abstract base class MaterialInstance is used. This class is an interface to both the expressions and parameter values of an applied material. The Material class is a subclass of MaterialInstance which defines the expressions and default parameter values. The MaterialInstanceConstant class is a subclass of MaterialInstance with a parent MaterialInstance. MaterialInstanceConstant inherits its expressions and parameter values from its parent, optionally overriding some of the parameter values.

Instancing a material in the editor

To create an instance of a material in the editor, use the new menu in the Generic Browser to create a MaterialInstanceConstant. This is a material instance that has explicitly defined parameter values. Material Instances can then be edited using the Material Instance Editor. See the MaterialInstanceEditor doc for more information.

Creating a parameterized material

To add a parameter definition to a material, use the ScalarParameter or VectorParameter expression types in the material editor. ScalarParameter is a single floating-point parameter and VectorParameter is a 4-component floating-point value. Give the parameter a unique name and a default value.

Editing a material with a VectorParameter

Creating a parameterized texture in a material

To add a texture parameter to a material, use the TextureSampleParameter2D, TextureSampleParameter3D, or TextureSampleParameterCube expression types in the material editor. TextureSampleParameter2D is a Texture2D parameter, TextureSampleParameter3D is a Texture3D, and TextureSampleParameterCube is a TextureCube. Due to the shader code that is generated being different depending on the texture type, each specific texture-type is required. Give the parameter a unique name and a default texture to use.

Editing a material with a TextureSampleParameter2D

Static Parameters

Static parameters are applied at compile-time, so they produce more optimal code as entire branches of the material that are masked out by a static parameter will be compiled out and not executed at runtime. Because they are applied at compile-time, they can only be changed from within the MaterialInstanceEditor and not from script.

Warning: A new material will be compiled out for every combination of static parameters in the base material that are used by instances!

This can lead to an excessive amount of shaders being compiled. Try to minimize the number of static parameters in the material and the number of permutations of those static parameters that are actually used. See MaterialsCompendium#Static_Switch_Parameter and MaterialsCompendium#Static_Component_Mask_Parameter for information on the specific static parameter types.

Time Varying Material Instances

See the Material Instances Time Varying^? page for information on changing materials over time.

For Programmers

Instancing a material in script

To create a script-controlled material instance, use the new keyword in UnrealScript to create a new MaterialInstanceConstant object. Use the SetParent function to set the material which defines the expressions and default parameter values of the instance, and use the SetScalarParameterValue or SetVectorParameterValue functions to change parameter values for that instance.

Here's code demonstrating how to create and apply a material instance with UnrealScript controlled parameters:

var MeshComponent Mesh;
var MaterialInstanceConstant MatInst;

var float TanPercent;

function InitMaterialInstance()
{
   MatInst = new(None) Class'MaterialInstanceConstant';
   MatInst.SetParent(Mesh.GetMaterial(0));
   Mesh.SetMaterial(0, MatInst);
   UpdateMaterialInstance();
}

function UpdateMaterialInstance()
{
   MatInst.SetScalarParameterValue('TanPercent',TanPercent);
}

function Timer()
{
   if(/*character is outside*/)
      TanPercent = Lerp(/*tanning rate*/,TanPercent,1.0);
   UpdateMaterialInstance();
}

Texture parameter example

Attached is a package named TextureParameter that contains the texture parameter material instance example described above.

https://udn.epicgames.com/pub/Three/InstancedMaterials/TextureParameter.upk