Skip to main content
The Material Compiler (matc) is a command-line tool that compiles material definitions (.mat files) into material packages that can be loaded by Filament at runtime.

​
Overview

Material definitions are human-readable text files that describe materials. The matc compiler processes these definitions and generates optimized binary packages containing:
  • Compiled shader variants for different platforms
  • Material metadata and parameters
  • Optimized shader code for Metal, Vulkan, OpenGL, and other backends

​
Installation

The matc tool is included in the Filament SDK. After building Filament or downloading a release: 
# The matc binary is located in the tools directory
./tools/matc --help

​
Basic Usage

Compile a material definition: 
matc -o output.filamat input.mat
This generates output.filamat, a material package that can be loaded by Filament.

​
Command-Line Options

​
Input/Output

# Specify output file
matc -o material.filamat input.mat

# Specify input file explicitly
matc -f input.mat -o output.filamat

​
Platform Targeting

By default, matc generates shaders for all supported platforms. You can target specific platforms: 
# Generate for specific platforms
matc -p mobile -o material.filamat input.mat

# Desktop platforms (OpenGL, Vulkan, Metal)
matc -p desktop -o material.filamat input.mat

# All platforms
matc -p all -o material.filamat input.mat
Platform options:
  • mobile - Android (OpenGL ES, Vulkan) and iOS (Metal)
  • desktop - Windows, macOS, Linux
  • all - All supported platforms (default)

​
Optimization Levels

# Optimize for performance (default)
matc -O performance -o material.filamat input.mat

# Optimize for size
matc -O size -o material.filamat input.mat

# No optimization (faster compilation)
matc -O none -o material.filamat input.mat

​
Variant Filtering

Reduce package size by excluding unnecessary shader variants: 
# Strip specific variants
matc --strip-variant skinning --strip-variant ssr -o material.filamat input.mat
Available variants:
  • directionalLighting - Directional lights
  • dynamicLighting - Point and spot lights
  • shadowReceiver - Shadow receiving
  • skinning - Skeletal animation
  • ssr - Screen-space reflections
  • stereo - Stereoscopic rendering
  • fog - Fog effects
  • vsm - Variance shadow maps

​
Debug Options

# Generate debug information
matc --debug -o material.filamat input.mat

# Print shader code
matc --print-shaders -o material.filamat input.mat

# Verbose output
matc --verbose -o material.filamat input.mat

​
Material Source Embedding

# Embed original material source for debugging
matc --embed-source -o material.filamat input.mat

​
Common Workflows

​
Development Build

During development, use faster compilation with debug info: 
matc -O none --debug --embed-source -o debug.filamat material.mat

​
Production Build

For production, optimize and strip unused variants: 
matc -O size \
  --strip-variant ssr \
  --strip-variant stereo \
  -o production.filamat material.mat

​
Mobile-Only Build

Optimize for mobile platforms: 
matc -p mobile -O size -o mobile.filamat material.mat

​
Material Packages

​
Loading Materials

Load compiled material packages in your application: 
#include <filament/Material.h>

// Read the material package file
std::ifstream file("material.filamat", std::ios::binary);
std::vector<uint8_t> package(
    (std::istreambuf_iterator<char>(file)),
    std::istreambuf_iterator<char>()
);

// Create the material
Material* material = Material::Builder()
    .package(package.data(), package.size())
    .build(*engine);

​
Material Instances

Create instances to set parameter values: 
// Create a material instance
MaterialInstance* instance = material->createInstance();

// Set parameters
instance->setParameter("baseColor", RgbType::LINEAR, 
    filament::math::float3{1.0f, 0.0f, 0.0f});
instance->setParameter("roughness", 0.5f);
instance->setParameter("metallic", 1.0f);

// Set texture parameters
instance->setParameter("albedoMap", texture, sampler);

​
Specialization Constants

You can specialize constant parameters when building materials: 
Material* material = Material::Builder()
    .package(package.data(), package.size())
    .constant("USE_TEXTURE", true)
    .constant("MAX_LIGHTS", 4)
    .build(*engine);
Define constants in your material: 
material {
    constants : [
        { name : USE_TEXTURE, type : bool, default : false },
        { name : MAX_LIGHTS, type : int, default : 8 }
    ]
}

​
Error Handling

​
Common Errors

Shader Compilation Errors: 
Error: Fragment shader compilation failed:
  ERROR: 0:42: 'undeclaredVariable' : undeclared identifier
Fix: Check your fragment shader for typos and undefined variables. Unknown Parameter Type: 
Error: Unknown parameter type 'sampler3d'
Fix: Use supported parameter types (see creating materials). Missing Required Function: 
Error: Fragment block must define 'material' function
Fix: Ensure your fragment block has the required material() function.

​
Validation

matc performs extensive validation:
  • GLSL syntax checking
  • Parameter type validation
  • Material property compatibility
  • Shader variant generation

​
Build System Integration

​
CMake

# Find matc
find_program(MATC matc PATHS ${FILAMENT_DIR}/bin)

# Add custom command to compile materials
add_custom_command(
    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/material.filamat
    COMMAND ${MATC} 
        -o ${CMAKE_CURRENT_BINARY_DIR}/material.filamat
        ${CMAKE_CURRENT_SOURCE_DIR}/material.mat
    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/material.mat
)

# Add materials to target
add_custom_target(materials ALL
    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/material.filamat
)

​
Gradle (Android)

task compileMaterials(type: Exec) {
    def matc = "${filamentDir}/bin/matc"
    def inputDir = "src/main/materials"
    def outputDir = "${buildDir}/generated/materials"
    
    inputs.dir inputDir
    outputs.dir outputDir
    
    commandLine matc, 
        '-p', 'mobile',
        '-o', "${outputDir}/material.filamat",
        "${inputDir}/material.mat"
}

preBuild.dependsOn compileMaterials

​
Makefile

MATC := tools/matc
MAT_SRC := $(wildcard materials/*.mat)
MAT_OUT := $(patsubst materials/%.mat,build/%.filamat,$(MAT_SRC))

all: $(MAT_OUT)

build/%.filamat: materials/%.mat
	@mkdir -p build
	$(MATC) -o $@ $<

clean:
	rm -rf build/*.filamat

​
Performance Tips

​
Reduce Compilation Time

  1. Use variant filtering to skip unused variants
  2. Target specific platforms during development
  3. Disable optimization for debug builds
# Fast debug compilation
matc -p desktop -O none --strip-variant skinning -o debug.filamat material.mat

​
Reduce Package Size

  1. Optimize for size in production
  2. Strip unused variants
  3. Target only needed platforms
# Minimal production build
matc -p mobile -O size \
  --strip-variant ssr \
  --strip-variant stereo \
  --strip-variant fog \
  -o small.filamat material.mat

​
Advanced Features

​
Multiple Material Outputs

Generate platform-specific packages: 
# Desktop version
matc -p desktop -O performance -o desktop.filamat material.mat

# Mobile version
matc -p mobile -O size -o mobile.filamat material.mat

​
Shader Inspection

Inspect generated shaders: 
# Print all generated shaders
matc --print-shaders material.mat > shaders.txt

# Print with verbose output
matc --verbose --print-shaders material.mat

​
Troubleshooting

​
matc Command Not Found

Ensure matc is in your PATH or use the full path: 
# Add to PATH
export PATH=$PATH:/path/to/filament/bin

# Or use full path
/path/to/filament/bin/matc -o output.filamat input.mat

​
Compilation Failures

  1. Check GLSL syntax in your shader code
  2. Verify all parameters are properly declared
  3. Ensure material block is valid JSON-ish
  4. Use --verbose for detailed error messages

​
Runtime Loading Errors

  1. Verify the .filamat file was generated successfully
  2. Check platform compatibility
  3. Ensure the package matches your Filament version

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us