GpuSurfaceController class

Capability probe and attach lifecycle for the GPU / Rust-raster present path.

null — auto: probe once and use GPU/raster when available
true — force attempt (still runs probe)
false — force CustomPainter path; never probes

On probe/attach failure, latches usePainterFallback until retry.

Embedder spike (Task 10)

True Flutter external Texture registration:

Linux: FlPixelBufferTexture / FlTextureGL via FlTextureRegistrar (GTK embedder).
macOS: FlutterTextureRegistry + pixel-buffer or IOSurface texture.
Windows: FlutterDesktopTextureRegistrarRegisterExternalTexture.

This package's rust_lib_flutter_alacritty is an ffiPlugin (cargokit-only CMake/pod glue) with no texture-registrar hooks, and FRB does not expose TextureRegistry. MVP therefore uses Rust-raster present: Rust fills a retained RGBA pixmap; Dart uploads to ui.Image and draws it in a thin CustomPaint (skips the MirrorGrid cell paint loop). Set textureId only when a real external texture exists (>= 0); raster path keeps textureId at -1 and sets gpuReady so shouldUseGpuSurface is true.

Constructors

GpuSurfaceController({bool? preferGpuSurface, Future<bool> probe()?})

Properties

gpuReady ↔ bool: True after a successful ensureAttached (probe passed).
getter/setter pair
hashCode → int: The hash code for this object.
no setterinherited
preferGpuSurface → bool?: Host preference: null=auto, true=force attempt, false=force painter.
final
probe → Future<bool> Function(): Returns true when Rust-raster present (or a future Texture) can attach.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
shouldUseGpuSurface → bool: Whether the view should prefer the GPU/raster path (not cell painter).
no setter
textureId ↔ int: External Flutter texture id when registered; -1 means Rust-raster ui.Image path (not a real Texture widget).
getter/setter pair
usePainterFallback ↔ bool: Latched after a failed probe/attach; cleared only by retry.
getter/setter pair
useRasterPresent → bool: True when using Rust-raster → ui.Image (not an external Texture id).
no setter

Methods

ensureAttached() → Future<bool>: Attempts attach via probe. Returns whether GPU/raster path is ready.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
retry() → void: Clears the fallback latch so the next ensureAttached re-probes.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

defaultProbe() → Future<bool>: Probe: FLUTTER_ALACRITTY_GPU=1, or desktop VM (non-web) when the host forced preferGpuSurface — see TerminalView custom probe. Default auto without the env var stays false so widget tests keep the painter.