MaterialInstance - Filament

Overview

A MaterialInstance represents a specific instance of a Material. While a Material defines the shader code and the set of parameters, a MaterialInstance holds the specific values for those parameters. MaterialInstances are created from Materials and can have their parameters modified independently of other instances.

Creating a MaterialInstance

MaterialInstances are created from a Material:

#include <filament/Material.h>
#include <filament/MaterialInstance.h>

Material* material = // ... create material ...
MaterialInstance* instance = material->createInstance("MyInstance");

Static Methods

duplicate

static MaterialInstance* duplicate(
    MaterialInstance const* other,
    const char* name = nullptr
) noexcept

Creates a new MaterialInstance using another MaterialInstance as a template for initialization.

other

MaterialInstance const*

required

A MaterialInstance to use as a template for initializing a new instance

name

const char*

A name for the new MaterialInstance or nullptr to use the template’s name

Returns: A new MaterialInstance. Example:

MaterialInstance* original = material->createInstance("Original");
original->setParameter("color", math::float4{1.0f, 0.0f, 0.0f, 1.0f});

MaterialInstance* copy = MaterialInstance::duplicate(original, "Copy");
// copy now has the same parameter values as original

Instance Methods

getMaterial

Material const* getMaterial() const noexcept

Returns the Material associated with this instance. Returns: Pointer to the parent Material.

getName

const char* getName() const noexcept

Returns the name associated with this instance. Returns: The instance’s name as a null-terminated string.

Parameter Methods

setParameter (Uniform)

template<typename T>
void setParameter(
    const char* name,
    size_t nameLength,
    T const& value
)

Sets a uniform by name.

name

const char*

required

Name of the parameter as defined by Material

nameLength

size_t

required

Length in characters of the name parameter

value

required

Value of the parameter to set

Supported types:

float, math::float2, math::float3, math::float4
int32_t, math::int2, math::int3, math::int4
uint32_t, math::uint2, math::uint3, math::uint4
bool, math::bool2, math::bool3, math::bool4
math::mat3f, math::mat4f

Convenience overload:

template<typename T>
void setParameter(const char* name, T const& value)

Example:

instance->setParameter("roughness", 0.5f);
instance->setParameter("baseColor", math::float4{1.0f, 0.0f, 0.0f, 1.0f});
instance->setParameter("transform", math::mat4f::identity());

setParameter (Array)

template<typename T>
void setParameter(
    const char* name,
    size_t nameLength,
    const T* values,
    size_t count
)

Sets a uniform array by name.

name

const char*

required

Name of the parameter array as defined by Material

nameLength

size_t

required

Length in characters of the name parameter

values

const T*

required

Array of values to set to the named parameter array

count

size_t

required

Size of the array to set

Convenience overload:

template<typename T>
void setParameter(const char* name, const T* values, size_t count)

Example:

math::float3 positions[10];
// ... fill positions array ...
instance->setParameter("positions", positions, 10);

setParameter (Texture)

void setParameter(
    const char* name,
    size_t nameLength,
    Texture const* texture,
    TextureSampler const& sampler
)

Sets a texture as the named parameter.

name

const char*

required

Name of the parameter as defined by Material

nameLength

size_t

required

Length in characters of the name parameter

texture

Texture const*

Texture object pointer (can be nullptr)

sampler

TextureSampler const&

required

Sampler parameters

Depth textures can’t be sampled with a linear filter unless the comparison mode is set to COMPARE_TO_TEXTURE.

Convenience overload:

void setParameter(
    const char* name,
    Texture const* texture,
    TextureSampler const& sampler
)

Example:

Texture* albedoTexture = // ... create texture ...
TextureSampler sampler(
    TextureSampler::MinFilter::LINEAR_MIPMAP_LINEAR,
    TextureSampler::MagFilter::LINEAR
);
instance->setParameter("albedo", albedoTexture, sampler);

setParameter (RGB Color)

void setParameter(
    const char* name,
    size_t nameLength,
    RgbType type,
    math::float3 color
)

Sets an RGB color as the named parameter. A conversion might occur depending on the specified type.

name

const char*

required

Name of the parameter as defined by Material

nameLength

size_t

required

Length in characters of the name parameter

type

RgbType

required

Whether the color value is encoded as Linear or sRGB

color

math::float3

required

Array of red, green, blue channel values

Convenience overload:

void setParameter(const char* name, RgbType type, math::float3 color)

RgbType enum values:

RgbType::LINEAR - Linear color space
RgbType::sRGB - sRGB color space

Example:

instance->setParameter("baseColor", RgbType::sRGB, math::float3{1.0f, 0.5f, 0.0f});

setParameter (RGBA Color)

void setParameter(
    const char* name,
    size_t nameLength,
    RgbaType type,
    math::float4 color
)

Sets an RGBA color as the named parameter. A conversion might occur depending on the specified type.

name

const char*

required

Name of the parameter as defined by Material

nameLength

size_t

required

Length in characters of the name parameter

type

RgbaType

required

Whether the color value is encoded as Linear or sRGB/A

color

math::float4

required

Array of red, green, blue, and alpha channel values

Convenience overload:

void setParameter(const char* name, RgbaType type, math::float4 color)

Example:

instance->setParameter("tint", RgbaType::sRGB, math::float4{1.0f, 0.0f, 0.0f, 0.5f});

getParameter

template<typename T>
T getParameter(const char* name, size_t nameLength) const

Gets the value of a parameter by name.

name

const char*

required

Name of the parameter as defined by Material

nameLength

size_t

required

Length in characters of the name parameter

Returns: The current value of the parameter.

Only supports non-texture parameters such as numeric and math types.

Convenience overload:

template<typename T>
T getParameter(const char* name) const

Example:

float roughness = instance->getParameter<float>("roughness");
math::float4 color = instance->getParameter<math::float4>("baseColor");

Rendering State Methods

Scissor

setScissor

void setScissor(
    uint32_t left,
    uint32_t bottom,
    uint32_t width,
    uint32_t height
) noexcept

Sets up a custom scissor rectangle; by default it is disabled.

left

uint32_t

required

Left coordinate of the scissor box relative to the viewport

bottom

uint32_t

required

Bottom coordinate of the scissor box relative to the viewport

width

uint32_t

required

Width of the scissor box

height

uint32_t

required

Height of the scissor box

The scissor is not compatible with dynamic resolution and should always be disabled when dynamic resolution is used.

unsetScissor

void unsetScissor() noexcept

Returns the scissor rectangle to its default disabled setting.

Polygon Offset

setPolygonOffset

void setPolygonOffset(float scale, float constant) noexcept

Sets a polygon offset that will be applied to all renderables drawn with this material instance.

scale

float

required

Scale factor used to create a variable depth offset for each triangle

constant

float

required

Scale factor used to create a constant depth offset for each triangle

Using a polygon offset other than zero has a significant negative performance impact, as most implementations have to disable early depth culling. DO NOT USE unless absolutely necessary.

Mask Threshold

setMaskThreshold

void setMaskThreshold(float threshold) noexcept

Overrides the minimum alpha value a fragment must have to not be discarded when the blend mode is MASKED.

threshold

float

required

Alpha threshold value between 0 and 1 (defaults to 0.4 if not set in the parent Material)

getMaskThreshold

float getMaskThreshold() const noexcept

Gets the minimum alpha value a fragment must have to not be discarded when the blend mode is MASKED. Returns: The mask threshold value.

Specular Anti-Aliasing

setSpecularAntiAliasingVariance

void setSpecularAntiAliasingVariance(float variance) noexcept

Sets the screen space variance of the filter kernel used when applying specular anti-aliasing.

variance

float

required

Variance value between 0 and 1 (default is 0.15)

getSpecularAntiAliasingVariance

float getSpecularAntiAliasingVariance() const noexcept

Gets the screen space variance of the filter kernel used when applying specular anti-aliasing. Returns: The variance value.

setSpecularAntiAliasingThreshold

void setSpecularAntiAliasingThreshold(float threshold) noexcept

Sets the clamping threshold used to suppress estimation errors when applying specular anti-aliasing.

threshold

float

required

Threshold value between 0 and 1 (default is 0.2)

getSpecularAntiAliasingThreshold

float getSpecularAntiAliasingThreshold() const noexcept

Gets the clamping threshold used to suppress estimation errors when applying specular anti-aliasing. Returns: The threshold value.

Double-Sided

setDoubleSided

void setDoubleSided(bool doubleSided) noexcept

Enables or disables double-sided lighting if the parent Material has double-sided capability.

doubleSided

bool

required

Whether to enable double-sided lighting

If double-sided lighting is enabled, backface culling is automatically disabled.

isDoubleSided

bool isDoubleSided() const noexcept

Returns whether double-sided lighting is enabled when the parent Material has double-sided capability. Returns: true if double-sided lighting is enabled.

Transparency Mode

setTransparencyMode

void setTransparencyMode(TransparencyMode mode) noexcept

Specifies how transparent objects should be rendered.

mode

TransparencyMode

required

The transparency mode to use (default is DEFAULT)

TransparencyMode enum values:

DEFAULT - Use the material’s transparency mode
TWO_PASSES_ONE_SIDE - Two-pass rendering, one side per pass
TWO_PASSES_TWO_SIDES - Two-pass rendering, both sides per pass

getTransparencyMode

TransparencyMode getTransparencyMode() const noexcept

Returns the transparency mode. Returns: The current transparency mode.

Culling Mode

setCullingMode

void setCullingMode(CullingMode culling) noexcept

Overrides the default triangle culling state that was set on the material.

culling

CullingMode

required

The culling mode to use

CullingMode enum values:

NONE - No culling
FRONT - Front-face culling
BACK - Back-face culling
FRONT_AND_BACK - Both front and back-face culling

void setCullingMode(
    CullingMode colorPassCullingMode,
    CullingMode shadowPassCullingMode
) noexcept

Overrides the default triangle culling state separately for color and shadow passes.

colorPassCullingMode

CullingMode

required

Culling mode for color passes

shadowPassCullingMode

CullingMode

required

Culling mode for shadow passes

getCullingMode

CullingMode getCullingMode() const noexcept

Returns the face culling mode. Returns: The culling mode.

getShadowCullingMode

CullingMode getShadowCullingMode() const noexcept

Returns the face culling mode for shadow passes. Returns: The shadow culling mode.

Color Write

setColorWrite

void setColorWrite(bool enable) noexcept

Overrides the default color-buffer write state that was set on the material.

enable

bool

required

Whether to enable color write

isColorWriteEnabled

bool isColorWriteEnabled() const noexcept

Returns whether color write is enabled. Returns: true if color write is enabled.

Depth Write

setDepthWrite

void setDepthWrite(bool enable) noexcept

Overrides the default depth-buffer write state that was set on the material.

enable

bool

required

Whether to enable depth write

isDepthWriteEnabled

bool isDepthWriteEnabled() const noexcept

Returns whether depth write is enabled. Returns: true if depth write is enabled.

Depth Testing

setDepthCulling

void setDepthCulling(bool enable) noexcept

Overrides the default depth testing state that was set on the material.

enable

bool

required

Whether to enable depth culling

setDepthFunc

void setDepthFunc(DepthFunc depthFunc) noexcept

Overrides the default depth function state that was set on the material.

depthFunc

DepthFunc

required

The depth comparison function to use

DepthFunc (SamplerCompareFunc) enum values:

LE - Less than or equal (default)
GE - Greater than or equal
L - Less than
G - Greater than
E - Equal
NE - Not equal
A - Always pass
N - Never pass

getDepthFunc

DepthFunc getDepthFunc() const noexcept

Returns the depth function state. Returns: The depth function.

isDepthCullingEnabled

bool isDepthCullingEnabled() const noexcept

Returns whether depth culling is enabled. Returns: true if depth culling is enabled.

Stencil Operations

setStencilWrite

void setStencilWrite(bool enable) noexcept

Overrides the default stencil-buffer write state that was set on the material.

enable

bool

required

Whether to enable stencil write

isStencilWriteEnabled

bool isStencilWriteEnabled() const noexcept

Returns whether stencil write is enabled. Returns: true if stencil write is enabled.

setStencilCompareFunction

void setStencilCompareFunction(
    StencilCompareFunc func,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the stencil comparison function (default is StencilCompareFunc::A).

func

StencilCompareFunc

required

The stencil comparison function

face

StencilFace

Which face(s) to apply the function to (default is FRONT_AND_BACK)

StencilFace enum values:

FRONT - Front-facing polygons
BACK - Back-facing polygons
FRONT_AND_BACK - Both front and back-facing polygons

setStencilOpStencilFail

void setStencilOpStencilFail(
    StencilOperation op,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the stencil fail operation (default is StencilOperation::KEEP).

StencilOperation

required

The operation to perform when stencil test fails

face

StencilFace

Which face(s) to apply the operation to

StencilOperation enum values:

KEEP - Keep current value
ZERO - Set to zero
REPLACE - Replace with reference value
INCR - Increment and clamp
INCR_WRAP - Increment and wrap
DECR - Decrement and clamp
DECR_WRAP - Decrement and wrap
INVERT - Bitwise invert

setStencilOpDepthFail

void setStencilOpDepthFail(
    StencilOperation op,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the depth fail operation (default is StencilOperation::KEEP).

StencilOperation

required

The operation to perform when depth test fails

face

StencilFace

Which face(s) to apply the operation to

setStencilOpDepthStencilPass

void setStencilOpDepthStencilPass(
    StencilOperation op,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the depth-stencil pass operation (default is StencilOperation::KEEP).

StencilOperation

required

The operation to perform when both tests pass

face

StencilFace

Which face(s) to apply the operation to

setStencilReferenceValue

void setStencilReferenceValue(
    uint8_t value,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the stencil reference value (default is 0).

value

uint8_t

required

The reference value for stencil comparison and REPLACE operation

face

StencilFace

Which face(s) to apply the value to

setStencilReadMask

void setStencilReadMask(
    uint8_t readMask,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the stencil read mask (default is 0xFF).

readMask

uint8_t

required

Mask for stencil comparison test values

face

StencilFace

Which face(s) to apply the mask to

setStencilWriteMask

void setStencilWriteMask(
    uint8_t writeMask,
    StencilFace face = StencilFace::FRONT_AND_BACK
) noexcept

Sets the stencil write mask (default is 0xFF).

writeMask

uint8_t

required

Mask for stencil buffer write operations

face

StencilFace

Which face(s) to apply the mask to

commit

void commit(Engine& engine) const

PostProcess and compute domain material instances must be committed manually. This call has no effect on surface domain materials.

engine

Engine&

required

Filament engine

Example Usage

#include <filament/Engine.h>
#include <filament/Material.h>
#include <filament/MaterialInstance.h>
#include <filament/Texture.h>

// Create material and instance
Material* material = Material::Builder()
    .package(materialData, materialSize)
    .build(*engine);

MaterialInstance* instance = material->createInstance("MyMaterial");

// Set scalar parameters
instance->setParameter("roughness", 0.5f);
instance->setParameter("metallic", 0.0f);

// Set color parameters
instance->setParameter("baseColor", RgbaType::sRGB,
    math::float4{0.8f, 0.2f, 0.2f, 1.0f});

// Set texture parameters
Texture* albedoTexture = // ... create texture ...
Texturesampler sampler(
    TextureSampler::MinFilter::LINEAR_MIPMAP_LINEAR,
    TextureSampler::MagFilter::LINEAR,
    TextureSampler::WrapMode::REPEAT
);
instance->setParameter("albedo", albedoTexture, sampler);

// Configure rendering state
instance->setDoubleSided(false);
instance->setCullingMode(CullingMode::BACK);
instance->setDepthWrite(true);

// Use with renderable
RenderableManager::Builder(1)
    .material(0, instance)
    // ... other configuration ...
    .build(*engine, entity);

// Cleanup
engine->destroy(instance);
engine->destroy(material);

Core Classes

Materials & Rendering

Lighting & Camera

Transform & Animation

Utilities

​Overview

​Creating a MaterialInstance

​Static Methods

​duplicate

​Instance Methods

​getMaterial

​getName

​Parameter Methods

​setParameter (Uniform)

​setParameter (Array)

​setParameter (Texture)

​setParameter (RGB Color)

​setParameter (RGBA Color)

​getParameter

​Rendering State Methods

​Scissor

​setScissor

​unsetScissor

​Polygon Offset

​setPolygonOffset

​Mask Threshold

​setMaskThreshold

​getMaskThreshold

​Specular Anti-Aliasing

​setSpecularAntiAliasingVariance

​getSpecularAntiAliasingVariance

​setSpecularAntiAliasingThreshold

​getSpecularAntiAliasingThreshold

​Double-Sided

​setDoubleSided

​isDoubleSided

​Transparency Mode

​setTransparencyMode

​getTransparencyMode

​Culling Mode

​setCullingMode

​getCullingMode

​getShadowCullingMode

​Color Write

​setColorWrite

​isColorWriteEnabled

​Depth Write

​setDepthWrite

​isDepthWriteEnabled

​Depth Testing

​setDepthCulling

​setDepthFunc

​getDepthFunc

​isDepthCullingEnabled

​Stencil Operations

​setStencilWrite

​isStencilWriteEnabled

​setStencilCompareFunction

​setStencilOpStencilFail

​setStencilOpDepthFail

​setStencilOpDepthStencilPass

​setStencilReferenceValue

​setStencilReadMask

​setStencilWriteMask

​commit

​Example Usage

Build docs developers (and LLMs) love

Overview

Creating a MaterialInstance

Static Methods

duplicate

Instance Methods

getMaterial

getName

Parameter Methods

setParameter (Uniform)

setParameter (Array)

setParameter (Texture)

setParameter (RGB Color)

setParameter (RGBA Color)

getParameter

Rendering State Methods

Scissor

setScissor

unsetScissor

Polygon Offset

setPolygonOffset

Mask Threshold

setMaskThreshold

getMaskThreshold

Specular Anti-Aliasing

setSpecularAntiAliasingVariance

getSpecularAntiAliasingVariance

setSpecularAntiAliasingThreshold

getSpecularAntiAliasingThreshold

Double-Sided

setDoubleSided

isDoubleSided

Transparency Mode

setTransparencyMode

getTransparencyMode

Culling Mode

setCullingMode

getCullingMode

getShadowCullingMode

Color Write

setColorWrite

isColorWriteEnabled

Depth Write

setDepthWrite

isDepthWriteEnabled

Depth Testing

setDepthCulling

setDepthFunc

getDepthFunc

isDepthCullingEnabled

Stencil Operations

setStencilWrite

isStencilWriteEnabled

setStencilCompareFunction

setStencilOpStencilFail

setStencilOpDepthFail

setStencilOpDepthStencilPass

setStencilReferenceValue

setStencilReadMask

setStencilWriteMask

commit

Example Usage