ProgressiveBlur class

A progressive (graduated) backdrop blur — the Signal / iOS-26 header look: a clean gaussian frost that is strongest at one edge and eases to perfectly sharp at the opposite edge. Stack it behind a translucent app bar so content dissolves beneath it instead of ending on a hard cut-off.

This is the graduated-blur primitive the rest of the library does not provide (glass surfaces apply a uniform blur). It is self-contained — it needs no LiquidGlassLayer or glass ancestor — so it can back any bar.

How it works — a single GPU pass that samples the backdrop

The naive "blur then fade with a ShaderMask" recipe does NOT work: a BackdropFilter's captured backdrop is not included in an ancestor ShaderMask's layer on Impeller, so the mask reveals nothing and iOS shows no blur at all. Instead this uses ui.ImageFilter.shader: a fragment shader runs as the ui.ImageFilter of a BackdropFilter, so the engine binds the captured backdrop to the shader's sampler — sampling it reliably on every backend. shaders/progressive_blur.frag reads that backdrop with an importance-sampled gaussian whose sigma follows the gradient (normalised over the widget's own device-pixel rectangle, since the bound texture is the whole screen), giving a smooth, band-free dissolve in one backdrop capture + one draw.

Drive maxSigma from a scroll offset to fade the blur in/out (0 → sharp).

Stack(
  children: [
    const Positioned(top: 0, left: 0, right: 0, height: 96,
      child: ProgressiveBlur(maxSigma: 20)),
    // ... your translucent app bar on top ...
  ],
)

Call preload once from main() (after the binding is initialised) to pre-compile the shader so the first bar paint already has it.

Inheritance

Constructors

ProgressiveBlur({Key? key, double maxSigma = 18, ProgressiveBlurDirection direction = ProgressiveBlurDirection.topToBottom, double falloff = 1.2}): const

Properties

direction → ProgressiveBlurDirection: Which edge the blur is strongest at (it eases to sharp at the opposite edge). Defaults to ProgressiveBlurDirection.topToBottom.
final
falloff → double: Gradient gamma. >1 keeps the blur strong across the strong edge then eases to sharp near the opposite edge.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
maxSigma → double: Blur sigma (logical px) at the strong edge. 0 ⇒ no blur (passthrough). Optional — defaults to a moderate 18.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

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

preload() → Future<void>: Pre-compiles the blur shader so the first bar paint already has it. Safe to call repeatedly (compiled once). Call from main() after the binding is initialized. Never throws — on failure the widget falls back to a uniform blur.