initialize static method

Future<void> initialize({ bool enablePerformanceMonitor = true, @Deprecated('warmUpImpellerPipeline is deprecated and has no effect. ' 'GPU warm-up is now handled non-blockingly by GlassAdaptiveScope. ' 'Will be removed in v1.0.') bool warmUpImpellerPipeline = true, GlassWarmUpMode warmUpMode = GlassWarmUpMode.auto, })

Initializes platform-level resources for the Liquid Glass library.

Responsibility: async platform / engine setup only. Call once in main() before runApp. All behavioral configuration belongs in wrap.

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await LiquidGlassWidgets.initialize();
  runApp(LiquidGlassWidgets.wrap(const MyApp()));
}

Parameters

enablePerformanceMonitor (default true)
In debug and profile builds, the library registers a SchedulerBinding.addTimingsCallback that watches raster durations while GlassQuality.premium surfaces are mounted. When frames consistently exceed the GPU budget, a single FlutterError is emitted with actionable guidance. The monitor is automatically disabled in release builds — zero overhead in shipped apps. Set to false to suppress it during profiling sessions where the warning would be a false positive.

Tasks performed

1. Pre-warms / precaches the lightweight fragment shader.
2. Pre-warms the interactive indicator shader (custom refraction).
3. Pre-warms the Impeller rendering pipeline (iOS / Android / macOS).
4. Optionally registers the debug performance monitor.

Shaders pre-warmed

Shader	Role
lightweight_glass.frag	Minimal glass layer
interactive_indicator.frag	Custom refraction effect
liquid_glass_geometry_blended.frag	Geometry / SDF pass
liquid_glass_final_render.frag	Final composite pass
Controls shader preloading and warm-up behaviour during initialize.

Implementation

static Future<void> initialize({
  bool enablePerformanceMonitor = true,
  @Deprecated(
    'warmUpImpellerPipeline is deprecated and has no effect. '
    'GPU warm-up is now handled non-blockingly by GlassAdaptiveScope. '
    'Will be removed in v1.0.',
  )
  bool warmUpImpellerPipeline = true,
  GlassWarmUpMode warmUpMode = GlassWarmUpMode.auto,
}) async {
  debugPrint('[LiquidGlass] Initializing library...');

  // 1. Pre-warm shader programs in parallel — fast, async disk I/O only.
  // Loads FragmentProgram objects into RAM so widgets render without
  // placeholder frames / white flash.
  final precacheFutures = <Future<void>>[
    LightweightLiquidGlass.preWarm(),
    GlassEffect.preWarm(),
    ProgressiveBlur.preload(),
  ];

  // On platforms that support premium glass rendering (iOS Metal, macOS Metal,
  // Android Vulkan/GLES), preload the multi-pass shaders as well.
  // Web, Windows, and Linux skip premium preload by default as they are
  // capped at standard quality by the GlassAdaptiveScope static probe.
  final bool shouldPreloadPremium = warmUpMode == GlassWarmUpMode.always ||
      (warmUpMode == GlassWarmUpMode.auto && !_shouldSkipPremiumPreload());

  if (shouldPreloadPremium) {
    precacheFutures.add(
      MultiShaderBuilder.precacheShaders([
        ShaderKeys.blendedGeometry,
        ShaderKeys.liquidGlassRender,
      ]),
    );
  }

  await Future.wait(precacheFutures);

  // 2. Register the debug performance monitor (no-op in release builds).
  if (enablePerformanceMonitor && !kReleaseMode) {
    GlassPerformanceMonitor.start();
  }

  debugPrint('[LiquidGlass] Initialization complete.');
}