utils/glass_quality_adapter library

Glass Quality Adapter

A pure-Dart state machine that drives automatic GlassQuality adaptation based on real device raster performance. Contains all logic for the three phases of GlassAdaptiveScope:

Phase 1 — Static probe (~0 ms, at scope construction):

• ImageFilter.isShaderFilterSupported == false → force minimal
• kIsWeb → cap at standard
• Otherwise → proceed to Phase 2

Phase 2 — Warm-up benchmark (first 180 measured frames ≈ 3 s at 60 fps):

• Skips the first GlassQualityAdapter.skipInitialFrames frames (default 60 ≈ 1 s) to let shader compilation and first-route transitions settle.
• Collects rasterDuration via SchedulerBinding.addTimingsCallback
• Computes the P75 raster time across the collected frames
• P75 < 20 ms → remain at GlassQuality.premium (handles Android GPU warm-up inflation)
• P75 20–28 ms → step to GlassQuality.standard
• P75 > 28 ms → step to GlassQuality.minimal
• Transitions to Phase 3 once skipInitialFrames + warmupFrames have been seen

Phase 3 — Runtime hysteresis (ongoing, very low overhead):

• Maintains a rolling ring buffer of the last 120 raster durations
• Degrades one tier when P95 > targetFrameMs × 1.5 for 3 consecutive sliding windows
• Upgrades one tier when P95 < targetFrameMs × 0.6 for 10 consecutive sliding windows (only if allowStepUp is true)
• Hard cooldown: minimum 8 seconds between any quality change
• Degradation is 3× faster than recovery — jank is noticed immediately, but quality recovery must be invisible (slow and stable)

This class is internal — do NOT export from the barrel file.

All logic is pure Dart (no widgets, no BuildContext). The adapter is owned and started/stopped by _GlassAdaptiveScopeState.

final adapter = GlassQualityAdapter(
  minQuality: GlassQuality.minimal,
  maxQuality: GlassQuality.premium,
  targetFrameMs: 16,
  allowStepUp: false,
  onQualityChanged: (from, to) { ... },
);
adapter.start(); // attaches SchedulerBinding callback
adapter.reset(); // call on AppLifecycleState.resumed
adapter.stop();  // detaches callback (dispose)

Classes

GlassQualityAdapter

Pure-Dart state machine that automatically selects and adjusts GlassQuality based on observed raster frame performance.

Enums

AdaptivePhase

Internal phase of the GlassQualityAdapter state machine.