GlassAdaptiveScope class

Automatically adjusts GlassQuality for its subtree based on real device raster performance, handling three scenarios developers can't easily test:

  • Broken/slow shader drivers (Pixel 4a, Galaxy A22 class devices): detected in Phase 1 (static probe) and capped immediately.
  • Warm-up jank ("wrong quality at startup"): resolved by Phase 2 benchmark over the first 180 frames.
  • Thermal throttling ("fine at launch, janky after 10 minutes"): detected and corrected by Phase 3 runtime hysteresis.

The scope acts as a quality ceiling — it only caps inherited quality, never overrides explicit quality: widget parameters. See the file-level documentation for the complete architecture description.

Experimental — available in 0.8.0 for community feedback. The Phase 2 timing thresholds (P75 < 20 ms → premium, 20–28 ms → standard, > 28 ms → minimal) were updated in 0.9.6 based on real-device community data showing that Android GPU clock-scaling and shader-cache inflation can raise P75 by 4–6 ms on capable mid-range devices during the warmup window. If you observe unexpected behaviour, please file an issue with your device model and raster timings.

GlassAdaptiveScope(
  child: MaterialApp(home: MyHome()),
)
Inheritance
Annotations
  • @experimental

Constructors

GlassAdaptiveScope({required Widget child, GlassQuality minQuality = GlassQuality.minimal, GlassQuality maxQuality = GlassQuality.premium, GlassQuality? initialQuality, int targetFrameMs = 16, bool allowStepUp = true, double warmupPremiumThresholdMs = 20.0, double warmupStandardThresholdMs = 28.0, void onQualityChanged(GlassQuality from, GlassQuality to)?, void onDiagnostic(GlassAdaptiveDiagnostic)?, bool debugLogDiagnostics = false, Key? key})
Creates a GlassAdaptiveScope.
const

Properties

allowStepUp → bool
When true, the scope may step quality up to maxQuality after a sustained period of good performance (e.g. after thermal recovery or a conservative Phase 2 warmup decision).
final
child → Widget
The widget subtree that will have its glass quality automatically managed.
final
debugLogDiagnostics → bool
When true, prints a structured diagnostic log on every quality change in debug builds (no-op in profile/release).
final
hashCode → int
The hash code for this object.
no setterinherited
initialQuality → GlassQuality?
The quality to start at, skipping Phase 2 (the warm-up benchmark).
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
maxQuality → GlassQuality
The highest quality tier the scope may use.
final
minQuality → GlassQuality
The lowest quality tier the scope will ever enforce.
final
onDiagnostic → void Function(GlassAdaptiveDiagnostic)?
Called with a GlassAdaptiveDiagnostic whenever the effective quality changes. Provides P75/P95 raster timings, change reason, phase, and frame count — everything needed for bug reports and analytics.
final
onQualityChanged → void Function(GlassQuality from, GlassQuality to)?
Called on the main thread whenever the effective quality changes.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
targetFrameMs → int
The raster frame duration target in milliseconds.
final
warmupPremiumThresholdMs → double
The P75 warmup threshold (ms) below which the device is classified as capable of GlassQuality.premium. Defaults to 20.0.
final
warmupStandardThresholdMs → double
The P75 warmup threshold (ms) at or below which the device is classified as capable of GlassQuality.standard (when above warmupPremiumThresholdMs). Defaults to 28.0.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<GlassAdaptiveScope>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited