matc

​

Usage

matc [options] <input-file>

​

Supported Input Formats

• Filament material definition (.mat)

​

Common Options

​

Output

• --output, -o <path> - Specify path to output file
• --output-format, -f <format> - Specify output format: blob (default), header, or mat
  • When specifying mat, returns a material with #include directives resolved

​

Platform and API

• --platform, -p <platform> - Shader family to generate: desktop, mobile, or all (default)
• --api, -a <api> - Specify target API: opengl (default), vulkan, metal, or all
  • Can be repeated to individually select APIs:
    matc --api opengl --api metal material.mat
    

​

Feature Level

• --feature-level, -l <level> - Specify maximum feature level allowed (default is 3)
• --no-essl1, -1 - Don’t generate ESSL 1.0 code even for Feature Level 0 mobile shaders

​

Optimization

• --optimize-size, -S, -Os - Optimize generated shader code for size instead of performance
• --optimize-none, -g, -O0 - Disable all shader optimizations (for debugging)

​

Preprocessor and Templates

​

Defines

• --define, -D <macro>=<value> - Add a preprocessor define macro. Value defaults to 1 if omitted
  matc -Dfoo=1 -Dbar -Dbuzz=100 material.mat
  

​

Templates

• --template, -T <macro>=<string> - Replaces ${MACRO} with specified string before parsing
  • Unlike --define, this applies to the material specification, not GLSL
  matc -TBLENDING=fade -TDOUBLESIDED=false material.mat
  

​

Material Parameters

• --material-parameter, -P <key>=<value> - Set material property to specified value
  • Overwrites the value configured in the material file
  • Array-type properties are not supported
  matc -PflipUV=false -PshadingModel=lit -Pname=myMat material.mat
  

​

Variant Filtering

• --variant-filter, -V <filter> - Filter out specified comma-separated variants:
  • directionalLighting
  • dynamicLighting
  • shadowReceiver
  • skinning
  • vsm
  • fog
  • ssr (screen-space reflections)
  • stereo

​

Reflection

• --reflect, -r - Reflect specified metadata as JSON: parameters

​

Workarounds

• --workarounds, -W <mode> - Workarounds to apply: all or none (default)

​

Debugging Options

• --debug, -d - Generate extra data for debugging
• --print, -t - Print generated shaders for debugging
• --save-raw-variants, -R - Write raw generated GLSL for each variant to text files
• --preprocessor-only, -E - Optimize shaders by running only the preprocessor

​

Advanced Options

• --no-sampler-validation, -F - Skip validation of number of samplers used
• --raw, -w - Compile a raw GLSL shader into a SPIRV binary chunk
• --no-insert-line-directives - Omit #line directives before/after each #include
• --no-insert-line-directive-check - Don’t surround line directives with #if defined(GL_GOOGLE_cpp_style_line_directive)
• --include-source-mat - Embed the source ASCII material definition

​

Examples

​

Basic compilation

matc -o output.filamat material.mat

​

Compile for specific platform and API

matc -p mobile -a vulkan -o mobile.filamat material.mat

​

Optimize for size with variant filtering

matc -S -V skinning,fog -o optimized.filamat material.mat

​

Multiple APIs with preprocessor defines

matc --api opengl --api metal -DUSE_HDR=1 -o material.filamat material.mat

​

Generate C header output

matc -f header -o material.h material.mat

​

Version

• --version, -v - Print the material version number
• --license - Print copyright and license information
• --help, -h - Print help message