ensureAttached method

Future<bool> ensureAttached()

Attempts attach via probe. Returns whether GPU/raster path is ready.

Thrown probe errors latch usePainterFallback until retry. A soft false from the probe (env unset / not available) does not latch — auto mode stays on the painter without a scary "attach failed" log.

Implementation

Future<bool> ensureAttached() async {
  if (preferGpuSurface == false) {
    return false;
  }
  if (usePainterFallback) {
    return false;
  }
  if (gpuReady) {
    return true;
  }

  bool ok;
  try {
    ok = await probe();
  } catch (e) {
    _latchFallback('probe threw: $e');
    return false;
  }
  if (!ok) {
    // Forced prefer must latch; auto soft-decline stays retryable.
    if (preferGpuSurface == true) {
      _latchFallback('forced probe returned false');
    }
    return false;
  }
  gpuReady = true;
  // MVP: no TextureRegistrar — raster present uses textureId == -1.
  textureId = -1;
  return true;
}