GlassHost class Foundations

Owns the whole proxy pipeline for one screen: it captures what is painted under the glass and hands it to every GlassSurface below it.

Put it above everything the glass is meant to show — in an application, once, above the navigator.

How it captures

Its child is the screen: the register finds the surfaces inside it, the pass reads it, and the surfaces sample the result. After each frame is painted the host records what is under the glass into one atlas, at a resolution chosen against a measured quality budget (budgetDeltaE), and publishes it; the surfaces draw it through their finish on the frame after.

The one-frame delay is structural. A capture reads the tree that was just painted, so the earliest a surface can show it is the following frame, and the first frame of any screen paints its glass without a proxy. The shaders arrive asynchronously too, which precache moves to before the first frame.

It records only when something under the glass changed (content): a still screen captures nothing, and glass moving over still content inside a GlassTravel captures nothing either. Below the top rung (tier) nothing is captured at all.

What the application declares

What the render tree does not carry, the host is told:

Each is installed into a GlassThemeData for the screen, which an inner GlassTheme can change for a subtree. The rest — maxCaptures, blurPass, resolution, maxTextureSide, shadowFilter, occlusion — are diagnostic seams and overrides that a shipping application leaves alone.

Where it goes

Above the navigator, in MaterialApp.builder (or the builder of CupertinoApp or WidgetsApp), so that a dialog, a sheet or a menu — all built in the navigator's overlay — is under it and captured like any other glass. A host inside a route would not see them.

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await GlassHost.precache();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) => MaterialApp(
    builder: (BuildContext context, Widget? child) => GlassHost(
      backdrop: const Color(0xFF101014),
      richBackdrop: true,
      minLabelContrast: kTextContrastAA,
      child: child!,
    ),
    home: const HomePage(),
  );
}

See also:

Inheritance

Constructors

GlassHost({required Widget child, GlassHardware? hardware, GlassFinish? finish, Brightness? appearance, GlassTierChoice tier = GlassTierChoice.byDefault, Color? backdrop, bool? highContrast, bool richBackdrop = false, double? minLabelContrast, GlassRipple? ripple, GlassDropMotion dropMotion = const GlassDropMotion(), GlassPress press = const GlassPress(), GlassThermalState? thermal, GlassThermalPolicy thermalPolicy = const GlassThermalPolicy(), double budgetDeltaE = ProxyResolutionPolicy.defaultDamageBudgetDeltaE, ShadowFilter? shadowFilter, OcclusionPolicy? occlusion, ProxyResolution? resolution, int? maxCaptures, int? maxTextureSide, ProxyBlurPass? blurPass, GlassContentDeclaration content = GlassContentDeclaration.byDefault, GlassAdaptive? adaptive, Key? key})
A host over child. Every other argument is optional, and its default is the shipping behaviour.
const

Properties

adaptive → GlassAdaptive?
Whether the glass reads its own backdrop, and how; null — the default — for glass that goes by what is declared (backdrop, richBackdrop, the platform's appearance).
final
appearance → Brightness?
The appearance .regular picks its branch in when finish is null, or null to follow the platform's (MediaQuery.platformBrightnessOf).
final
backdrop → Color?
What is behind the glass on this screen, on average.
final
blurPass → ProxyBlurPass?
How the residual blur reaches the atlas — and, at ProxyBlurPass.none, whether it reaches it at all. The second diagnostic on this widget, and at that value the same shape as maxCaptures: it makes the picture wrong on purpose, so it is a cost experiment and never a mode.
final
budgetDeltaE → double
The whole quality allowance, in ΔE against the same finish at full quality. 1% of the distance between two of Apple's own materials.
final
child → Widget
The screen: everything the glass under this host may show, and the glass itself. In an application, the navigator MaterialApp.builder hands over.
final
content → GlassContentDeclaration
Whether this screen may hold a proxy nothing under it has changed.
final
dropMotion → GlassDropMotion
How the held drop of the switch, the slider, the segmented control and the tab bar deforms as it launches and brakes, unless a control declares its own. GlassDropMotion.none keeps every drop round. It costs no capture; see GlassThemeData.dropMotion and GlassDropMotion.
final
finish → GlassFinish?
The optics every surface under this host wears unless it names its own.
final
hardware → GlassHardware?
Whose measurements apply. Defaults to what the platform can be asked — Apple platforms answer, everything else is GlassHardware.unmeasured, which gets the same divisor and the same merging as a declared family and a null where the price would be.
final
hashCode → int
The hash code for this object.
no setterinherited
highContrast → bool?
The platform's increase-contrast switch, or null to read it from MediaQuery.highContrastOf — which the engine sets on iOS and on Android 34+, and never on macOS, where the application has to read NSWorkspace.accessibilityDisplayShouldIncreaseContrast itself and pass it. See GlassThemeData.highContrast for what it draws.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
maxCaptures → int?
Stops recording after this many captures. Null records for ever, which is the only shipping behaviour.
final
maxTextureSide → int?
The largest texture this GPU will actually allocate, in device pixels a side. Null takes GlassHardware.maxTextureSide, which is a specification floor rather than a reading of the device.
final
minLabelContrast → double?
The least contrast a component label must reach, met by dimming the glass when the finish cannot reach it. See GlassThemeData.minLabelContrast.
final
occlusion → OcclusionPolicy?
Where the descent may stop, if the application has worked it out.
final
press → GlassPress
How a pressed GlassButton swells and leans toward a dragging finger, unless it declares its own. GlassPress.none keeps every button its size. It costs two captures a press and nothing at rest; see GlassThemeData.press and GlassPress.
final
resolution → ProxyResolution?
The proxy divisor, named by the host instead of chosen from the tables.
final
richBackdrop → bool
Whether the screen under the glass is an image rather than a colour. See GlassThemeData.richBackdrop.
final
ripple → GlassRipple?
The wave every surface below makes when touched, or null for none — the platform's behaviour. See GlassThemeData.ripple and GlassRipple.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shadowFilter → ShadowFilter?
Which shadows the capture may skip. Of the quality degradations measured, this is the cheapest by a wide margin: under 0.2 ΔE behind the glass.
final
thermal → GlassThermalState?
The device's thermal state, as the application read it — the package ships no platform code to read it. Null is nominal.
final
thermalPolicy → GlassThermalPolicy
What each thermal state may spend on staleness. GlassThermalPolicy.never keeps every frame fresh whatever the device says.
final
tier → GlassTierChoice
Which rung of the finish ladder every surface under this host draws.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<GlassHost>
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

Static Methods

precache({bool group = true, bool ripple = true}) → Future<void>
Compiles the package's shaders now, so that the first glass on screen is drawn through its optics rather than without them.