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:
- what is behind the glass: backdrop, and whether it is an image, richBackdrop;
- the accessibility the platform does not relay everywhere: highContrast, and a floor for the labels, minLabelContrast;
- the device: hardware, and its thermal state;
- the look: finish, tier, ripple, dropMotion, press, and whether the glass reads its own backdrop, adaptive.
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:
- GlassSurface, the glass that samples what the host captures.
- GlassTheme and GlassThemeData, what the host installs for its subtree.
- GlassFinish, the material named by finish.
- GlassTravel and GlassProxy, which tell the host where glass moves and how a subtree is captured.
- The host and Installation on the site.
- Inheritance
-
- Object
- DiagnosticableTree
- Widget
- StatefulWidget
- GlassHost
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
.regularpicks 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.builderhands 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 readNSWorkspace.accessibilityDisplayShouldIncreaseContrastitself 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