MaterialBuilder
MaterialBuilder compiles Filament material source code into binary packages.
MaterialBuilder takes high-level material definitions and generates optimized shaders for multiple backends (OpenGL, Vulkan, Metal, WebGPU). The resulting MaterialPackage can be loaded by Filament's Material system.
Initialization: Call MaterialBuilder.init before building any material, and MaterialBuilder.shutdown when finished.
Compilation: Configure material properties using methods like name(), shading(), blendingMode(), etc., then call build() to generate the package.
See also
Types
A vertex attribute a material can require: its name, shader type and slot, and the names shaders use for it (attributeName, e.g. mesh_uv0, and defineName, e.g. HAS_ATTRIBUTE_UV0).
A blend factor, for customBlendFunctions.
Blending modes determine how material color combines with background color.
Type of a specialization constant.
Which triangle faces are culled before rasterization.
Vertex attribute interpolation in the fragment shader.
Which pipeline stage the material targets.
Shader optimization level applied at compile time.
Attachment a post-process output writes.
Type of a post-process output.
Precision level for numeric parameters.
Platform class to generate shaders for.
Source of reflections for the material.
Source of refracted light for refractive materials.
Geometry model used to compute refraction.
Data format for sampler parameters.
Sampler types for texture parameters.
Shader quality: lower trades accuracy for speed. DEFAULT picks per platform.
A shader stage, for the stages a sampler parameter is visible to.
Shading model determines how light interacts with the material surface.
How ambient occlusion is applied to specular indirect lighting.
Graphics API(s) to generate shaders for.
How transparent objects are rendered (BlendingMode.TRANSPARENT/BlendingMode.FADE only).
Uniform variable types in material parameters.
Custom vertex attribute variable slots.
Qualifier of a post-process output.
Coordinate space the vertex shader's material() output is expressed in.
Driver workarounds baked into the shaders.
Functions
Converts fragment alpha to MSAA coverage; smoother BlendingMode.MASKED edges under MSAA.
Sets how the material blends with the render target (BlendingMode.OPAQUE by default).
Compiles the material and returns the resulting package (check MaterialPackage.isValid before use).
Makes the clear coat layer's IOR affect the base layer (physically correct; default: true).
Enables colored shadow penumbras for this material's transparent shadows.
Enables/disables writes to the color buffer (default: true).
Records the compiler parameters (matc's command line) in the package.
Declares a specialization constant with its default value, settable per material instance.
Sets face culling (CullingMode.BACK by default).
The blend factors of BlendingMode.CUSTOM.
Enables custom surface shading: the material provides its own surfaceShading() function.
Enables/disables depth testing (default: true).
Enables/disables writes to the depth buffer (default: true, except for blended modes).
Renders both faces and flips the normal on back faces; implies CullingMode.NONE.
Lets post-process materials read the framebuffer they write.
Sets the minimum feature level the material needs.
Flips the V texture coordinate at compile time (default: true, matching Filament's convention).
Includes debug info in the generated SPIR-V.
Also generates ESSL 1.0 shaders, for feature level 0.
Enables instanced rendering: shaders get the instance index.
Sets the interpolation of the shading normal (default: SMOOTH).
Computes fog linearly rather than exponentially, a cheaper approximation.
Sets the alpha cutoff for BlendingMode.MASKED (default: 0.4).
Sets the material domain (MaterialDomain.SURFACE by default).
Records the material's .mat source in the package.
Simulates extra light bounces in occluded areas to reduce over-darkening from AO.
Sets the material's name (shown in tooling and debug output).
Skips validating samplers against the feature level's limits.
Sets the shader optimization level (Optimization.PERFORMANCE by default).
Adds a fragment shader output; post-process materials only. location -1 lets filamat pick.
Declares a uniform parameter, settable via MaterialInstance.setParameter.
Declares a uniform array parameter of size elements.
Declares a texture sampler parameter, settable via MaterialInstance.setParameter. transformName names a mat3 uniform transforming its UVs; stages limits the shader stages that see it (all when null).
Selects the platform class to generate shaders for (Platform.ALL to cover everything).
Sets how the post-lighting color blends with the lit result.
Prints the generated shaders to the log.
Sets the shader quality (ShaderQuality.DEFAULT by default).
Sets where reflections are sampled from (ReflectionMode.DEFAULT by default).
Sets where refracted light is sampled from (RefractionMode.NONE by default).
Sets the refraction geometry model (RefractionType.SOLID by default).
Requires the given vertex attribute to be present in rendered geometry (e.g. UV1, COLOR).
Saves each variant's raw shader text, for debugging.
Sets the API level the material is compiled against (default: 1).
Adds a preprocessor define to the material's shader code.
Sets the shading model (LIT, UNLIT, SUBSURFACE, CLOTH, SPECULAR_GLOSSINESS).
Fades shadows out towards the shadow far plane.
UNLIT only: multiplies the final color by the shadowing factor, for shadow-receiver planes.
Sets how AO is applied to specular lighting (SpecularAmbientOcclusion.NONE by default).
Reduces specular shimmering/aliasing on curved geometry (LIT models only).
Clamping threshold of the specular AA roughness increase, in [0, 1] (default: 0.2).
Screen-space variance of the specular AA filter kernel, in [0, 1] (default: 0.15).
Sets how many eyes stereoscopic rendering draws.
Sets the stereoscopic technique the shaders support.
Selects the graphics API(s) to generate shaders for; fewer APIs → smaller package.
Sets the transparency rendering strategy (TransparencyMode.DEFAULT by default).
Makes this transparent material cast (dithered) transparent shadows.
Uses Filament's default depth variant, skipping a custom vertex shader in depth-only passes.
Uses the legacy (non-CPU-skinning-aware) morph target implementation.
Names a custom interpolant (Variable slot) passed from the vertex to the fragment stage.
Names a custom interpolant with an explicit precision.
Bitmask of shader variants to exclude from compilation, shrinking the package.
Sets the coordinate space of the vertex output (VertexDomain.OBJECT by default).
Applies the view's TAA jitter to VertexDomain.DEVICE positions.
Sets the driver workarounds baked into the shaders.