initialQuality property

GlassQuality? initialQuality
final

The quality to start at, skipping Phase 2 (the warm-up benchmark).

When non-null, the adapter jumps directly to Phase 3 (runtime hysteresis) using this quality as the starting point — eliminating the ~3-second warm-up jank window on repeat launches.

Use this to restore a persisted quality across cold starts:

// In main.dart — persist settled quality to SharedPreferences:
final prefs = await SharedPreferences.getInstance();
final saved = prefs.getString('glass_quality');
final initial = saved != null
    ? GlassQuality.values.byName(saved)
    : null; // null = run Phase 2 on first launch

runApp(LiquidGlassWidgets.wrap(
  const MyApp(),
  adaptiveQuality: true,
  adaptiveConfig: GlassAdaptiveScopeConfig(
    initialQuality: initial,
    allowStepUp: true,
    onQualityChanged: (_, to) => prefs.setString('glass_quality', to.name),
  ),
));

Within a single app process, GlassQualityAdapter._sessionSettledQuality also auto-skips Phase 2 on remounts — no extra code required.

If null, the scope will automatically determine the best starting quality:

  • All platforms (including Android) default to maxQuality for an immediate premium experience (Best Foot Forward). If a device is too slow, Phase 2 will demote it after the warmup.

Warning for Android: Forcing this to GlassQuality.premium bypasses the conservative seeding. While LiquidGlassWidgets.initialize() protects against ANRs by pre-compiling the shaders, if you explicitly disable the Impeller warm-up (warmUpImpellerPipeline: false), forcing premium on frame 1 may cause a severe stutter or ANR on GLES-only Android devices.

Implementation

final GlassQuality? initialQuality;