Which shader warm‑up strategy yields the lowest first‑frame latency in Flutter?

Answer

The combination that consistently gives the lowest first‑frame latency on both Android and iOS is:

• Enable Impeller (flutter.enableImpeller=true)
• Bundle a pre‑compiled shader cache with the app
• Optionally warm up a small, critical set of shaders via FlutterEngine.runWithEntrypoint before the first frame is rendered

Why this works

Impeller’s built‑in shader pre‑compilation covers the vast majority of shaders used by most widgets, eliminating the on‑demand compile spike. Adding a cached shader asset removes the need for Impeller to compile any shader at launch, further reducing latency. The runWithEntrypoint warm‑up only needs to target the few shaders that Impeller’s broad pre‑compile set does not cover (e.g., custom shaders or rarely used widget styles). The incremental launch cost of this last step is usually small compared to the benefit on low‑end GPUs.

Implementation Steps

1. Enable Impeller
   • Android: add flutter.enableImpeller=true to android/app/build.gradle.
   • iOS: add flutter.enableImpeller=true to ios/Runner/Info.plist.
2. Generate a shader cache asset
   • Run the release build on a target device: flutter run --release --profile.
   • After launch, locate the shader_cache directory in the app bundle (Android: /data/data/<package>/flutter_assets/shader_cache; iOS: Runner.app/Contents/Resources/flutter_assets/shader_cache).
   • Copy the entire shader_cache folder into your Flutter project’s assets directory.
   • Declare the asset in pubspec.yaml:

     flutter:
       assets:
         - assets/shader_cache/
     

3. Configure the engine to use the bundled cache
   • In native code, before the first frame is drawn, call:

     FlutterEngine *engine = ...;
     [engine setShaderCacheDirectory:[[NSBundle mainBundle] pathForResource:@"shader_cache" ofType:nil]];
     

4. Optional runWithEntrypoint warm‑up
   • Identify the handful of high‑impact shaders (e.g., custom ShaderMask or CustomPaint shaders).
   • Call FlutterEngine.runWithEntrypoint('main', @[@"--warmupShader","shaderName"]) before the first frame is rendered. The exact arguments depend on your app’s shader pre‑loading API; consult the latest FlutterEngine docs for the supported flags.
5. Measure and iterate
   • Use Android Studio Profiler or Xcode Instruments to capture the first‑frame latency for the three scenarios: Impeller only, Impeller + cache, Impeller + cache + runWithEntrypoint.
   • Adjust the shader list for runWithEntrypoint if you notice residual spikes on specific devices.

What if Impeller isn’t enabled?

If you cannot use Impeller (e.g., targeting older devices or a stable release channel where Impeller is experimental), the best fallback is to bundle the shader cache and perform a targeted runWithEntrypoint warm‑up. This still removes most on‑demand compilation spikes, though the absolute latency will be higher than the Impeller + cache combination.

Key Takeaway

For the lowest first‑frame latency across a wide range of devices, enable Impeller, ship a pre‑compiled shader cache, and optionally warm up a minimal set of critical shaders via FlutterEngine.runWithEntrypoint before the first frame.