Material Properties

This page provides a comprehensive reference for all properties available in Filament materials, organized by material model and category.

Common Properties

These properties are available across multiple material models.

Base Color

Type: float4 | Range: [0..1] | Default: (1, 1, 1, 1) Defines the perceived color of the object (albedo). The effect depends on the metallic property:

Non-metals (dielectrics): Diffuse color of the surface
Metals (conductors): Specular color of the surface

material.baseColor = vec4(1.0, 0.0, 0.0, 1.0); // Red, fully opaque
material.baseColor.rgb = materialParams.color;

Base color should be specified in linear RGB space and use pre-multiplied alpha.

Metallic

Type: float | Range: [0..1] | Default: 0.0 Defines whether the surface is metallic (1.0) or non-metallic (0.0). Should typically be used as a binary value.

0.0: Dielectric surface (plastic, wood, etc.)
1.0: Metallic surface (iron, gold, etc.)

material.metallic = 1.0; // Fully metallic
material.metallic = materialParams.metallic;

Roughness

Type: float | Range: [0..1] | Default: 1.0 Controls the perceived smoothness of the surface:

0.0: Perfectly smooth and glossy
1.0: Very rough and diffuse

material.roughness = 0.3; // Glossy surface
material.roughness = texture(materialParams_roughnessMap, uv).r;

Reflectance

Type: float | Range: [0..1] | Default: 0.5 Available in: Lit, Subsurface Not available in: Cloth, Specular Glossiness Controls the specular intensity for non-metallic surfaces. Remaps to common reflectance percentages:

Value	Reflectance	IOR	Material Examples
0.35	2%	1.33	Water
0.5	4%	1.5	Plastic, glass (default)
0.56	5%	1.58	High-quality plastic

material.reflectance = 0.5; // 4% reflectance (default)

Avoid values below 0.35 (2% reflectance) as no real-world materials have such low reflectance.

Emissive

Type: float4 | Range: rgb=[0..n], a=[0..1] | Default: (0, 0, 0, 1) Simulates light emitted by the surface:

RGB: Intensity in nits (candelas per square meter)
Alpha: Exposure weight (0 = ignore camera exposure, 1 = affected by exposure)

// 500 nit display, affected by camera exposure
material.emissive = vec4(vec3(500.0), 1.0);

// Convert from EV (f-stops)
float luminance = pow(2.0, ev - 3.0);
material.emissive = vec4(color * luminance, 1.0);

Ambient Occlusion

Type: float | Range: [0..1] | Default: 0.0 Per-pixel shadowing factor for diffuse indirect lighting:

0.0: Fully shadowed
1.0: Fully lit

material.ambientOcclusion = texture(materialParams_aoMap, uv).r;

Ambient occlusion only affects diffuse indirect lighting (IBL), not direct lights or specular.

Normal

Type: float3 | Range: [0..1] | Default: (0, 0, 1) Available in: All models except Unlit Surface normal in tangent space. Must be set before calling prepareMaterial().

vec3 normalMap = texture(materialParams_normalMap, uv).xyz;
material.normal = normalMap * 2.0 - 1.0; // Convert [0,1] to [-1,1]

prepareMaterial(material); // MUST be called after setting normal

Lit Model Properties

Clear Coat

Type: float | Range: [0..1] | Default: 0.0 Strength of the clear coat layer. Simulates multi-layer materials like car paint.

0.0: No clear coat
1.0: Full clear coat layer

material.clearCoat = 1.0;
material.clearCoatRoughness = 0.1; // Glossy clear coat

Clear coat effectively doubles the cost of specular computations. Don’t assign any value (even 0.0) if you don’t need it.

Clear Coat Roughness

Type: float | Range: [0..1] | Default: 0.0 Roughness of the clear coat layer, independent of base layer roughness.

material.clearCoat = 1.0;
material.clearCoatRoughness = 0.3;

Clear Coat Normal

Type: float3 | Range: [0..1] | Default: (0, 0, 1) Normal map for the clear coat layer, allowing different surface details for the clear coat.

vec3 clearCoatNormal = texture(materialParams_clearCoatNormal, uv).xyz;
material.clearCoatNormal = clearCoatNormal * 2.0 - 1.0;

Anisotropy

Type: float | Range: [-1..1] | Default: 0.0 Amount of anisotropic reflectance:

Positive values: Anisotropy in tangent direction
Negative values: Anisotropy in bitangent direction
0.0: Isotropic (default)

Useful for brushed metal, hair, and similar materials.

material.anisotropy = 0.8; // Brushed metal effect

Anisotropic materials are more expensive to render. Only set this property if you need anisotropy.

Anisotropy Direction

Type: float3 | Range: [0..1] | Default: (1, 0, 0) Direction vector in tangent space controlling the orientation of anisotropic highlights.

vec3 direction = texture(materialParams_anisotropyDir, uv).xyz;
material.anisotropyDirection = direction;

Sheen Color

Type: float3 | Range: [0..1] | Default: (0, 0, 0) Color and strength of an optional sheen layer, useful for cloth-like appearance.

material.sheenColor = vec3(0.8, 0.6, 0.4); // Warm sheen

For dedicated cloth materials, use the Cloth model instead for better performance.

Sheen Roughness

Type: float | Range: [0..1] | Default: 0.0 Roughness of the sheen layer.

material.sheenColor = vec3(0.5);
material.sheenRoughness = 0.8;

Bent Normal

Type: float3 | Range: [0..1] | Default: (0, 0, 1) Average unoccluded direction for improved indirect lighting accuracy.

vec3 bentNormal = texture(materialParams_bentNormal, uv).xyz;
material.bentNormal = bentNormal * 2.0 - 1.0;

Post-Lighting Color

Type: float4 | Range: [0..1] | Default: (0, 0, 0, 0) Color to blend with lighting result. Blending mode controlled by postLightingBlending material option.

material.postLightingColor = vec4(debugColor, 0.5);

Refraction Properties

Available when refractionMode is set to cubemap or screenspace.

Index of Refraction (IOR)

Type: float | Range: [1..n] | Default: 1.5 Refractive index of the material:

Material	IOR
Air	1.0
Water	1.33
Glass	1.5-1.58
Diamond	2.33

material.ior = 1.33; // Water

Transmission

Type: float | Range: [0..1] | Default: 1.0 Ratio of diffuse light transmitted through the material:

0.0: No transmission, diffuse fully visible
1.0: Full transmission, only specular visible

material.transmission = 1.0; // Fully transparent

Absorption

Type: float3 | Range: [0..n] | Default: (0, 0, 0) Light absorption coefficients for transmitted light. Transmittance follows: color * exp(-absorption * distance)

// Calculate from desired color at distance
// absorption = -ln(transmittanceColor) / atDistance
vec3 greenTint = vec3(0.2, 0.8, 0.3);
float distance = 0.5;
material.absorption = -log(greenTint) / distance;

Or use the API:

filament::math::float3 absorption = 
    Color::absorptionAtDistance(transmittanceColor, distance);

Thickness

Type: float | Range: [0..n] | Default: 0.5 Used with: Solid refraction type Thickness of solid refractive objects in the normal direction. Should vary per fragment for accurate results.

material.thickness = texture(materialParams_thicknessMap, uv).r;

Micro-Thickness

Type: float | Range: [0..n] | Default: 0.0 Used with: Thin refraction type Thickness of thin refractive shells. Can typically be a constant value.

material.microThickness = 0.001; // 1mm thin shell

Dispersion

Type: float | Range: [0..n] | Default: 0.0 Used with: Solid refraction type Chromatic dispersion strength, specified as 20/Abbe number:

Material	Abbe Number	Dispersion
Rutile	9.8	2.04
Polycarbonate	32	0.625
Diamond	55	0.36
Glass	59	0.33

material.dispersion = 0.36; // Diamond

Subsurface Model Properties

Thickness

Type: float | Range: [0..n] | Default: 0.5 Thickness for subsurface scattering calculations.

material.thickness = materialParams.thickness;

Subsurface Power

Type: float | Default: 12.234 Controls the scattering falloff. Higher values create tighter scattering.

material.subsurfacePower = 10.0;

Subsurface Color

Type: float3 | Range: [0..1] | Default: (1, 1, 1) Tint of the scattered light.

material.subsurfaceColor = vec3(1.0, 0.8, 0.7); // Skin-like

Cloth Model Properties

Sheen Color

Type: float3 | Range: [0..1] | Default: sqrt(baseColor) Specular tint for two-tone fabrics. For velvet:

material.baseColor.rgb = vec3(0.1, 0.0, 0.2); // Dark base
material.sheenColor = vec3(0.8, 0.2, 0.9); // Bright sheen

For common fabrics:

material.sheenColor = vec3(luminance(baseColor)); // Natural look

Subsurface Color

Type: float3 | Range: [0..1] | Default: (0, 0, 0) Tint for scattering through the material. Use sparingly as high values can interfere with shadows.

material.subsurfaceColor = vec3(0.2, 0.1, 0.05); // Subtle scattering

Unlit Model Properties

The unlit model only supports:

baseColor
emissive
postLightingColor

All lighting calculations are disabled.

fragment {
    void material(inout MaterialInputs material) {
        prepareMaterial(material);
        material.baseColor = texture(materialParams_texture, getUV0());
        material.emissive = vec4(0.0); // No additional emission
    }
}

Specular Glossiness Properties

Specular Color

Type: float3 | Range: [0..1] | Default: (0, 0, 0) Specular tint for legacy materials.

material.specularColor = vec3(0.5);

Glossiness

Type: float | Range: [0..1] | Default: 0.0 Inverse of roughness: glossiness = 1.0 - roughness

material.glossiness = 0.7; // Fairly glossy

Property Compatibility Matrix

Property	Lit	Subsurface	Cloth	Unlit	Spec/Gloss
baseColor	✓	✓	✓	✓	✓
metallic	✓	✓	✗	✗	✗
roughness	✓	✓	✓	✗	✗
reflectance	✓	✓	✗	✗	✗
clearCoat	✓	✗	✗	✗	✓
anisotropy	✓	✗	✗	✗	✓
sheenColor	✓	✗	✓	✗	✗
subsurfaceColor	✗	✓	✓	✗	✗
thickness	✓*	✓	✗	✗	✗
emissive	✓	✓	✗	✓	✓
normal	✓	✓	✓	✗	✓
specularColor	✗	✗	✗	✗	✓
glossiness	✗	✗	✗	✗	✓

* Only with refraction enabled

Best Practices

Set Properties Conditionally

Don’t set properties you don’t use - they have performance costs:

// Good - only set clear coat if needed
if (materialParams.useCoat) {
    material.clearCoat = 1.0;
    material.clearCoatRoughness = 0.1;
}

// Bad - setting to 0 still has cost
material.clearCoat = 0.0; // Don't do this

Use Proper Color Spaces

Always work in linear RGB:

// Good - already linear
material.baseColor.rgb = materialParams.color;

// Good - convert sRGB to linear
vec3 srgb = vec3(0.8, 0.2, 0.1);
material.baseColor.rgb = pow(srgb, vec3(2.2));

// Bad - using sRGB directly
material.baseColor.rgb = vec3(0.8, 0.2, 0.1); // Wrong!

Pre-multiply Alpha

For transparent materials, use pre-multiplied alpha:

vec4 color = texture(materialParams_albedo, uv);
color.rgb *= color.a; // Pre-multiply
material.baseColor = color;

Next Steps

Learn about PBR shading models
See creating materials for examples
Compile materials with matc

Getting Started

Core Concepts

Platform Guides

Material System

Rendering Features

Asset Pipeline

Tools

Advanced Topics

​Common Properties

​Base Color

​Metallic

​Roughness

​Reflectance

​Emissive

​Ambient Occlusion

​Normal

​Lit Model Properties

​Clear Coat

​Clear Coat Roughness

​Clear Coat Normal

​Anisotropy

​Anisotropy Direction

​Sheen Color

​Sheen Roughness

​Bent Normal

​Post-Lighting Color

​Refraction Properties

​Index of Refraction (IOR)

​Transmission

​Absorption

​Thickness

​Micro-Thickness

​Dispersion

​Subsurface Model Properties

​Thickness

​Subsurface Power

​Subsurface Color

​Cloth Model Properties

​Sheen Color

​Subsurface Color

​Unlit Model Properties

​Specular Glossiness Properties

​Specular Color

​Glossiness

​Property Compatibility Matrix

​Best Practices

​Set Properties Conditionally

​Use Proper Color Spaces

​Pre-multiply Alpha

​Next Steps

Build docs developers (and LLMs) love

Common Properties

Base Color

Metallic

Roughness

Reflectance

Emissive

Ambient Occlusion

Normal

Lit Model Properties

Clear Coat

Clear Coat Roughness

Clear Coat Normal

Anisotropy

Anisotropy Direction

Sheen Color

Sheen Roughness

Bent Normal

Post-Lighting Color

Refraction Properties

Index of Refraction (IOR)

Transmission

Absorption

Thickness

Micro-Thickness

Dispersion

Subsurface Model Properties

Thickness

Subsurface Power

Subsurface Color

Cloth Model Properties

Sheen Color

Subsurface Color

Unlit Model Properties

Specular Glossiness Properties

Specular Color

Glossiness

Property Compatibility Matrix

Best Practices

Set Properties Conditionally

Use Proper Color Spaces

Pre-multiply Alpha

Next Steps