Minimizing Filament Startup Time on iOS by Precompiling Metal Shaders

[ArMuSebastian]

Hi there!

I wanted to ask if it's possible to compile Filament with the Metal backend in such a way that precompiled .metallib shaders are embedded to help reduce application startup time.

Context:
I'm using Filament on iOS with the Metal backend to render glTF models in an ARKit context. I’ve noticed that the first time a model is added to the scene, there's a noticeable stutter (~200ms) that temporarily freezes the camera feed. After some investigation, it seems that this happens due to on-the-fly Metal shader compilation.

Calling Material::compile() on the materials from a GLTFAsset ahead of time does help eliminate the runtime stutter — but doing this adds delay presenting a model for a time i cannot afford.

What I’ve tried:
I’ve experimented with exposing and compiling all materials early(in runtime), but startup times became impractical (~2–3 minutes).

I came across MATEDIT and its external-compile command, which seems to allow replacing text-based shaders with precompiled binaries, but I found it a bit hard to wrap my head around.

I also noticed a preferredShaderLanguage option on the Engine, which made me wonder if there’s a recommended way to bake in .metallib shaders.

I'm especially interested in precompiling the core ubershaders (from Filament’s standard glTF material set), but ideally would also like to precompile the post-processing shaders (e.g., SSAO, Bloom, TAA) if possible.

Questions:
1 What is the recommended way to minimize Filament startup time on iOS with the Metal backend?

2 Is embedding precompiled .metallib shaders into .mat or .filamat files officially supported (targeting just metal be or metal + other)?

3 Will such materials fully skip the runtime Metal shader compilation step?

4 Can post-processing shaders (like SSAO, Bloom, TAA) be handled the same way?

5 Is it possible (and recommended) to customize the Filament CMake build to automate the external .metallib generation and embedding? If so, where should I start?

Thanks for your work and any guidance you can share — I really appreciate it!

[bejado]

Hi Sebastian,

1. What is the recommended way to minimize Filament startup time on iOS with the Metal backend?

Precompiling Metal shaders is a good low-hanging fruit to start with.

2. Is embedding precompiled .metallib shaders into .mat or .filamat files officially supported (targeting just metal be or metal + other)?

Yes, this is supported with the matedit tool (see below on instructions for use). Right now it only makes sense for the Metal backend.

3. Will such materials fully skip the runtime Metal shader compilation step?

They will skip the expensive part, yes. Precompiled .metallib binaries still need to be transformed (by Metal) to a GPU-specific binary, but this step is much faster.

4. Can post-processing shaders (like SSAO, Bloom, TAA) be handled the same way?

Yes.

5. Is it possible (and recommended) to customize the Filament CMake build to automate the external .metallib generation and embedding? If so, where should I start?

We haven't done this, but it's certainly possible. This bit of CMake inside filament/CMakeLists.txt handles compiling internal Filament materials. We do something similar here for materials embedded in the samples. Finally, here we compile materials for gltfio.

Essentially, what you'll want to do is check that you're on a macOS host add another chained add_custom_command that invokes matedit.

I came across MATEDIT and its external-compile command, which seems to allow replacing text-based shaders with precompiled binaries, but I found it a bit hard to wrap my head around.

See below.

Using matedit

You can invoke matedit on a compiled material like so:

matedit -o precompiled.cmat -i material.cmat external-compile -- my_compile_script.sh

my_compile_script.sh might look like this:

#!/bin/bash
set -e

INPUT="$1"
OUTPUT="$2"
STAGE="$3"
PLATFORM="$4"
shift 4

# Create temporary intermediate .air file
TMP_AIR=$(mktemp /tmp/tmp_shader_air.XXXXXX.air)

# Compile .metal to .air
xcrun -sdk macosx metal -c "$INPUT" -o "$TMP_AIR"

# Link .air to .metallib
xcrun -sdk macosx metallib "$TMP_AIR" -o "$OUTPUT"

# Clean up
rm -f "$TMP_AIR"

After running matedit, precompiled.cmat will only contain the compiled .metallib binaries. At runtime Filament will attempt to load those. preferredShaderLanguage is only necessary if both MSL and .metallib binaries are present in a material. This is not recommended in production, but might be useful for debugging, since .metallib binaries cannot be inspected in an Xcode frame capture.

[ArMuSebastian]

Thank you!