liquid_glass_renderer

The liquid glass effect works by distorting the pixels of the content located behind the glass widget. To make the effect visible, you must place your glass widgets on top of other content, typically using a Stack.

Basic Implementation Pattern

1. Place your background content in a Stack.
2. Add a LiquidGlassLayer to manage the rendering.
3. Place LiquidGlass widgets inside the layer.

Stack(
  children: [
    // 1. Background content
    MyBackgroundContent(),

    // 2. Layer for glass effects
    LiquidGlassLayer(
      // 3. Glass widgets
      child: LiquidGlass(
        shape: LiquidRoundedSuperellipse(borderRadius: 30),
        child: const SizedBox.square(dimension: 100),
      ),
    ),
  ],
)

Stack(
  children: [
    // 1. Your background content goes here
    MyBackgroundContent(),

    // 2. Create a layer for liquid glass effects
    LiquidGlassLayer(
      // 3. Add your LiquidGlass widgets here
      child: LiquidGlass(
        shape: LiquidRoundedSuperellipse(borderRadius: 30),
        child: const SizedBox.square(dimension: 100),
      ),
    ),
  ],
)

The liquid glass effect is computationally intensive and requires the Impeller rendering engine. Skia is currently unsupported.

Critical Limitations

• Platform Support: Only works on Impeller. Web, Windows, and Linux are unsupported.
• Memory: Animating shapes can cause temporary memory spikes due to a Flutter bug regarding texture disposal.
• Blending Limits: A LiquidGlassBlendGroup supports a maximum of 16 shapes. Performance degrades significantly as you approach this limit.
• Blur Artifacts: Blurring can introduce artifacts when blending shapes.

Optimization Tips

• Reuse Layers: Use a single LiquidGlassLayer for shapes that share the same settings. Creating many individual layers is expensive.
• Minimize Area: Keep the area covered by LiquidGlassLayer and LiquidGlassBlendGroup as small as possible. If you have sparse shapes over a large area, split them into multiple smaller layers/groups.
• Limit Animations: Moving shapes forces a re-render of the glass effect every frame. In a LiquidGlassBlendGroup, moving any shape forces all shapes in that group to re-render.
• Use FakeGlass: For non-critical UI elements, swap LiquidGlass with FakeGlass to avoid expensive shaders.

To achieve the liquid glass effect, the library uses a layered architecture:

• LiquidGlassLayer: The top-level container that manages the rendering context for the glass effect. For optimal performance, you should wrap multiple LiquidGlass shapes in a single LiquidGlassLayer rather than giving each shape its own layer.
• LiquidGlassBlendGroup: A specialized container used to group multiple LiquidGlass shapes so they can be blended together. This is required when using the LiquidGlass.grouped() constructor.
• LiquidGlass.auto(): A convenience constructor that bridges the gap by searching for an existing LiquidGlassLayer or creating one if none is found.

Performance Tip: Prefer placing a single LiquidGlassLayer ancestor in your widget tree and using the standard LiquidGlass constructor for all shapes within it to minimize the overhead of creating multiple layers.

You can customize the appearance of glass widgets by providing LiquidGlassSettings to a LiquidGlassLayer, LiquidGlass.withOwnLayer(), or LiquidGlass.auto(). All glass widgets within that layer will share these settings.

Key properties include:

• glassColor: The color tint of the glass (alpha controls intensity).
• thickness: Amount of background refraction (higher = more distortion).
• blur: Background blur strength (0 = no blur).
• refractiveIndex: Material refractive index (1.0 = no refraction, ~1.5 = realistic glass).
• lightAngle & lightIntensity: Control the virtual light source direction and brightness.
• ambientStrength: Intensity of ambient light on the glass.
• outlineIntensity: Visibility of the glass edge.
• saturation: Adjusts background color saturation (1.0 = no change, <1.0 = desaturated, >1.0 = more saturated).

LiquidGlassLayer(
  settings: const LiquidGlassSettings(
    thickness: 10,
    glassColor: Color(0x1AFFFFFF),
    lightIntensity: 1.5,
    outlineIntensity: 0.5,
    saturation: 1.2,
  ),
  child: LiquidGlassBlendGroup(
    blend: 40, // Note: blend is on LiquidGlassBlendGroup, not settings
    child: // ... your LiquidGlass.grouped widgets
  ),
)

The LiquidGlassLayer is the primary container for rendering liquid glass effects. It automatically detects and renders all LiquidGlass or LiquidGlassBlendGroup widgets within its subtree.

Important Usage Rules:

1. Layering: Do not place any other widgets between the LiquidGlassLayer and its LiquidGlass children. If you do, the glass effect will be rendered behind those widgets.
2. Settings: All shapes within a single LiquidGlassLayer share the same LiquidGlassSettings.
3. Performance: If you have multiple layers that share the same background blur, set useBackdropGroup: true to allow them to share a single BackdropGroup, which improves performance.
4. Compatibility: The high-fidelity liquid glass effect requires Impeller. If you are using Skia, the layer will automatically fall back to FakeGlass effects, or you can manually set fake: true to avoid warnings.

Widget build(BuildContext context) {
  return LiquidGlassLayer(
    settings: const LiquidGlassSettings(), // Shared settings for all shapes in this layer
    useBackdropGroup: true,               // Optimization for sharing blur
    child: Column(
      children: [
        LiquidGlass(
          shape: LiquidRoundedSuperellipse(borderRadius: 10),
          child: const SizedBox.square(dimension: 100),
        ),
        LiquidGlassBlendGroup(
          blend: 20,
          child: Row(
            children: [
              LiquidGlass.grouped(
                shape: const LiquidOval(),
                child: const SizedBox.square(dimension: 100),
              ),
              LiquidGlass.grouped(
                shape: const LiquidRoundedSuperellipse(borderRadius: 20),
                child: const SizedBox.square(dimension: 100),
              ),
            ],
          ),
        ),
      ],
    ),
  );
}