Material - Filament

Overview

A Material defines the visual appearance of a surface in Filament. Materials are created from a binary blob generated by the material compiler (matc). A Material acts as a template from which MaterialInstance objects can be created.

Creating a Material

Materials are created using the Builder pattern:

#include <filament/Material.h>

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

Builder

The Builder class is used to construct Material objects.

Constructor

Builder() noexcept

Creates a new Material::Builder instance.

Methods

package

Builder& package(const void* payload, size_t size)

Specifies the material data. The material data is a binary blob produced by libfilamat or by matc.

payload

const void*

required

Pointer to the material data, must stay valid until build() is called

size

size_t

required

Size of the material data pointed to by payload in bytes

Returns: Reference to this Builder for chaining calls.

constant

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

Specializes a constant parameter specified in the material definition with a concrete value.

name

const char*

required

The name of the constant parameter specified in the material definition

nameLength

size_t

required

Length in characters of the name parameter

value

required

The value to use for the constant parameter. Supported types: int32_t, float, bool

Returns: Reference to this Builder for chaining calls.

sphericalHarmonicsBandCount

Builder& sphericalHarmonicsBandCount(size_t shBandCount) noexcept

Sets the quality of the indirect lights computations. This is only taken into account if this material is lit and in the surface domain.

shBandCount

size_t

Number of spherical harmonic bands. Must be 1, 2 or 3 (default is 3)

Returns: Reference to this Builder for chaining calls.

shadowSamplingQuality

Builder& shadowSamplingQuality(ShadowSamplingQuality quality) noexcept

Sets the quality of shadow sampling. This is only taken into account if this material is lit and in the surface domain.

quality

ShadowSamplingQuality

Shadow sampling quality level

Returns: Reference to this Builder for chaining calls. ShadowSamplingQuality enum:

HARD - 2x2 PCF
LOW - 3x3 gaussian filter

uboBatching

Builder& uboBatching(UboBatchingMode uboBatchingMode) noexcept

Sets the batching mode of the instances created from this material.

uboBatchingMode

UboBatchingMode

UBO batching mode to use

Returns: Reference to this Builder for chaining calls. UboBatchingMode enum:

DEFAULT - Follows engine settings
DISABLED - Disable UBO batching for this material

build

Material* build(Engine& engine) const

Creates the Material object and returns a pointer to it.

engine

Engine&

required

Reference to the filament::Engine to associate this Material with

Returns: Pointer to the newly created Material object or nullptr if exceptions are disabled and an error occurred.

Material Methods

compile

void compile(
    CompilerPriorityQueue priority,
    UserVariantFilterMask variants,
    backend::CallbackHandler* handler = nullptr,
    utils::Invocable<void(Material*)>&& callback = {}
) noexcept

Asynchronously ensures that a subset of this Material’s variants are compiled.

priority

CompilerPriorityQueue

required

Which priority queue to use, LOW or HIGH

variants

UserVariantFilterMask

required

Variants to include in the compile command

handler

CallbackHandler*

Handler to dispatch the callback or nullptr for the default handler

callback

Invocable<void(Material*)>

Callback called on the main thread when compilation is done

createInstance

MaterialInstance* createInstance(const char* name = nullptr) const noexcept

Creates a new instance of this material. Material instances should be freed using Engine::destroy(const MaterialInstance*).

name

const char*

Optional name to associate with the material instance. If null, the instance inherits the material’s name

Returns: A pointer to the new MaterialInstance. Example:

MaterialInstance* instance = material->createInstance("MyInstance");
// ... use instance ...
engine->destroy(instance);

getName

const char* getName() const noexcept

Returns the name of this material as a null-terminated string. Returns: The material’s name.

Property Getters

getShading

Shading getShading() const noexcept

Returns the shading model of this material. Returns: The material’s Shading model. Shading enum values:

UNLIT - No lighting applied
LIT - Standard physically-based lighting
SUBSURFACE - Subsurface scattering
CLOTH - Cloth shading model
SPECULAR_GLOSSINESS - Legacy specular-glossiness model

getInterpolation

Interpolation getInterpolation() const noexcept

Returns the interpolation mode of this material. Returns: The interpolation mode.

getBlendingMode

BlendingMode getBlendingMode() const noexcept

Returns the blending mode of this material. Returns: The blending mode. BlendingMode enum values:

OPAQUE - Material is opaque
TRANSPARENT - Material is transparent
ADD - Additive blending
MASKED - Alpha-tested (masked) transparency
FADE - Fade transparency
MULTIPLY - Multiplicative blending
SCREEN - Screen blending

getVertexDomain

VertexDomain getVertexDomain() const noexcept

Returns the vertex domain of this material. Returns: The vertex domain.

getSupportedVariants

UserVariantFilterMask getSupportedVariants() const noexcept

Returns the material’s supported variants. Returns: Bitmask of supported variants.

getMaterialDomain

MaterialDomain getMaterialDomain() const noexcept

Returns the material domain of this material. The material domain determines how the material is used. Returns: The material domain. MaterialDomain enum values:

SURFACE - Surface rendering
POST_PROCESS - Post-processing effect
COMPUTE - Compute shader

getCullingMode

CullingMode getCullingMode() const noexcept

Returns the default culling mode of this material. Returns: The culling mode.

getTransparencyMode

TransparencyMode getTransparencyMode() const noexcept

Returns the transparency mode of this material. This value only makes sense when the blending mode is transparent or fade. Returns: The transparency mode.

isColorWriteEnabled

bool isColorWriteEnabled() const noexcept

Indicates whether instances of this material will, by default, write to the color buffer. Returns: true if color write is enabled.

isDepthWriteEnabled

bool isDepthWriteEnabled() const noexcept

Indicates whether instances of this material will, by default, write to the depth buffer. Returns: true if depth write is enabled.

isDepthCullingEnabled

bool isDepthCullingEnabled() const noexcept

Indicates whether instances of this material will, by default, use depth testing. Returns: true if depth culling is enabled.

isDoubleSided

bool isDoubleSided() const noexcept

Indicates whether this material is double-sided. Returns: true if the material is double-sided.

isAlphaToCoverageEnabled

bool isAlphaToCoverageEnabled() const noexcept

Indicates whether this material uses alpha to coverage. Returns: true if alpha to coverage is enabled.

getMaskThreshold

float getMaskThreshold() const noexcept

Returns the alpha mask threshold used when the blending mode is set to masked. Returns: The mask threshold value.

hasShadowMultiplier

bool hasShadowMultiplier() const noexcept

Indicates whether this material uses the shadowing factor as a color multiplier. This value only makes sense when the shading mode is unlit. Returns: true if shadow multiplier is used.

hasSpecularAntiAliasing

bool hasSpecularAntiAliasing() const noexcept

Indicates whether this material has specular anti-aliasing enabled. Returns: true if specular anti-aliasing is enabled.

getSpecularAntiAliasingVariance

float getSpecularAntiAliasingVariance() const noexcept

Returns the screen-space variance for specular anti-aliasing. Returns: Variance value between 0 and 1.

getSpecularAntiAliasingThreshold

float getSpecularAntiAliasingThreshold() const noexcept

Returns the clamping threshold for specular anti-aliasing. Returns: Threshold value between 0 and 1.

getRequiredAttributes

AttributeBitset getRequiredAttributes() const noexcept

Returns the list of vertex attributes required by this material. Returns: Bitset of required vertex attributes.

getRefractionMode

RefractionMode getRefractionMode() const noexcept

Returns the refraction mode used by this material. Returns: The refraction mode.

getRefractionType

RefractionType getRefractionType() const noexcept

Returns the refraction type used by this material. Returns: The refraction type.

getReflectionMode

ReflectionMode getReflectionMode() const noexcept

Returns the reflection mode used by this material. Returns: The reflection mode.

getFeatureLevel

backend::FeatureLevel getFeatureLevel() const noexcept

Returns the minimum required feature level for this material. Returns: The feature level.

Parameter Methods

getParameterCount

size_t getParameterCount() const noexcept

Returns the number of parameters declared by this material. Returns: The number of parameters (can be 0).

getParameters

size_t getParameters(ParameterInfo* parameters, size_t count) const noexcept

Gets information about this material’s parameters.

parameters

ParameterInfo*

required

A pointer to a list of ParameterInfo. The list must be at least count large

count

size_t

required

The number of parameters to retrieve

Returns: The number of parameters written to the parameters pointer. ParameterInfo structure:

struct ParameterInfo {
    const char* name;              // Name of the parameter
    bool isSampler;                // Whether the parameter is a sampler
    bool isSubpass;                // Whether the parameter is a subpass
    union {
        ParameterType type;        // Type if not a sampler
        SamplerType samplerType;   // Type if a sampler
        SubpassType subpassType;   // Type if a subpass
    };
    uint32_t count;                // Size when parameter is an array
    Precision precision;           // Requested precision
};

hasParameter

bool hasParameter(const char* name) const noexcept

Indicates whether a parameter of the given name exists on this material.

name

const char*

required

The parameter name to check

Returns: true if the parameter exists.

isSampler

bool isSampler(const char* name) const noexcept

Indicates whether an existing parameter is a sampler or not.

name

const char*

required

The parameter name to check

Returns: true if the parameter is a sampler.

getSource

std::string_view getSource() const noexcept

Returns a view of the material source (.mat file) string, if it has been set. Otherwise, returns a view of an empty string. Returns: String view of the material source.

getParameterTransformName

const char* getParameterTransformName(const char* samplerName) const noexcept

Gets the name of the transform field associated with the given sampler parameter.

samplerName

const char*

required

The name of the sampler parameter to query

Returns: The transform name value if it exists, nullptr otherwise.

Default Instance Methods

setDefaultParameter

template <typename T>
void setDefaultParameter(const char* name, T value) noexcept

Sets the value of the given parameter on this material’s default instance.

name

const char*

required

The name of the material parameter

value

required

The value of the material parameter

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

Sets a texture and sampler parameters on this material’s default instance.

name

const char*

required

The name of the material texture parameter

texture

Texture const*

required

The texture to set as parameter

sampler

TextureSampler const&

required

The sampler to be used with this texture

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

Sets the color of the given parameter on this material’s default instance.

name

const char*

required

The name of the material color parameter

type

RgbType

required

Whether the color is specified in the linear or sRGB space

color

math::float3

required

The color as a floating point red, green, blue tuple

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

Sets the RGBA color of the given parameter on this material’s default instance.

name

const char*

required

The name of the material color parameter

type

RgbaType

required

Whether the color is specified in the linear or sRGB/A space

color

math::float4

required

The color as a floating point red, green, blue, alpha tuple

getDefaultInstance

MaterialInstance* getDefaultInstance() noexcept
MaterialInstance const* getDefaultInstance() const noexcept

Returns this material’s default instance. Returns: Pointer to the default MaterialInstance.

Example Usage

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

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

// Create an instance
MaterialInstance* instance = material->createInstance();

// Set parameters on the instance
instance->setParameter("baseColor", math::float4{1.0f, 0.0f, 0.0f, 1.0f});
instance->setParameter("roughness", 0.5f);
instance->setParameter("metallic", 0.0f);

// Use the instance with a 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 Material

​Builder

​Constructor

​Methods

​package

​constant

​sphericalHarmonicsBandCount

​shadowSamplingQuality

​uboBatching

​build

​Material Methods

​compile

​createInstance

​getName

​Property Getters

​getShading

​getInterpolation

​getBlendingMode

​getVertexDomain

​getSupportedVariants

​getMaterialDomain

​getCullingMode

​getTransparencyMode

​isColorWriteEnabled

​isDepthWriteEnabled

​isDepthCullingEnabled

​isDoubleSided

​isAlphaToCoverageEnabled

​getMaskThreshold

​hasShadowMultiplier

​hasSpecularAntiAliasing

​getSpecularAntiAliasingVariance

​getSpecularAntiAliasingThreshold

​getRequiredAttributes

​getRefractionMode

​getRefractionType

​getReflectionMode

​getFeatureLevel

​Parameter Methods

​getParameterCount

​getParameters

​hasParameter

​isSampler

​getSource

​getParameterTransformName

​Default Instance Methods

​setDefaultParameter

​getDefaultInstance

​Example Usage

Build docs developers (and LLMs) love

Overview

Creating a Material

Builder

Constructor

Methods

package

constant

sphericalHarmonicsBandCount

shadowSamplingQuality

uboBatching

build

Material Methods

compile

createInstance

getName

Property Getters

getShading

getInterpolation

getBlendingMode

getVertexDomain

getSupportedVariants

getMaterialDomain

getCullingMode

getTransparencyMode

isColorWriteEnabled

isDepthWriteEnabled

isDepthCullingEnabled

isDoubleSided

isAlphaToCoverageEnabled

getMaskThreshold

hasShadowMultiplier

hasSpecularAntiAliasing

getSpecularAntiAliasingVariance

getSpecularAntiAliasingThreshold

getRequiredAttributes

getRefractionMode

getRefractionType

getReflectionMode

getFeatureLevel

Parameter Methods

getParameterCount

getParameters

hasParameter

isSampler

getSource

getParameterTransformName

Default Instance Methods

setDefaultParameter

getDefaultInstance

Example Usage