Module lifecycle 

Surface lifecycle state machine.

Android destroys and recreates the GPU surface on rotation and backgrounding — wgpu surfaces raise ERROR_SURFACE_LOST_KHR and panic on configure-after-resume if this is handled ad hoc. Frust therefore makes surface state a first-class machine, driven by the platform shells’ surfaceCreated/surfaceChanged/surfaceDestroyed callbacks (Android) and resumed/Resized/suspended events (desktop).

This module holds only the decisions and the two raw-pointer surface constructors; the renderer that owns the swapchain texture and drives them lives a layer above, so everything here is host-testable with no GPU and no window server in the loop.

States

           on_surface_created                 acquire == Lost
  NoSurface ───────────────▶ SurfaceReady ──────────────────▶ SurfaceLost
      ▲   on_surface_destroyed  │  ▲  on_surface_changed          │
      └───────────────────────┘  └── (resize, stays Ready)       │
      ▲                                on_surface_destroyed       │
      └──────────────────────────────────────────────────────────┘
                             on_surface_created (recreate)

Invariants the driving renderer must uphold

• No SurfaceTexture outlives a surface transition: a render call acquires and presents within a single call and stores nothing across one.
• Surface::configure runs only from SurfacePhase::SurfaceReady (on entry via on_surface_created/on_surface_changed, or on an Outdated acquire).
• Frame requests in SurfacePhase::NoSurface/SurfacePhase::SurfaceLost are dropped — the render call reports FrameOutcome::Skipped, never panicking and never queueing.

The pure decision logic (next_phase, SurfacePhase::can_render, decide_acquire, next_invalid_streak) is separated from the wgpu calls so it is unit-testable without a GPU.

Enums

AcquireAction

What the renderer should do after an acquire attempt.

AcquireOutcome

The outcome of a single acquire call — the first half of the two-phase present seam (acquire + submit), itself the second phase of the render pipeline after encode.

AcquireStatus

wgpu-independent classification of a swapchain-acquire attempt.

EncodeOutcome

The outcome of a single encode call — the first phase of the two-phase render seam (encode + present).

FrameOutcome

The outcome of a single render call.

SurfaceEvent

A platform lifecycle event that drives a phase transition.

SurfacePhase

Which lifecycle state the surface is in.

Constants

MAX_INVALID_RECONFIGURES

Cap on consecutive Invalid-acquire reconfigure retries before the machine gives up and transitions to SurfacePhase::SurfaceLost.

Functions

create_android_surface^⚠

Builds a wgpu::Surface from a raw ANativeWindow pointer.

decide_acquire

Pure acquire-error policy.

next_invalid_streak

Given the just-observed acquire status and the AcquireAction decide_acquire chose for it, returns the next consecutive-Invalid streak count the renderer should store.

next_phase

Pure phase-transition table.