Crate frust_render 

Layer 4: GPU backend — wgpu 30 over the frust-owned frust-engine strip pipeline.

Consumes the renderer-agnostic frust_scene::Scene display list and renders it into a window’s swapchain. frust-engine draws through ordinary render passes into the acquired swapchain texture — no compute pass, no storage write, no intermediate and no blit — so the surface needs only RENDER_ATTACHMENT in whatever format the platform reports, plus the depth attachment the surface carries alongside it. The one variation is a swapchain whose compositor genuinely reads STRAIGHT alpha: there the frame lands in a surface-owned intermediate and one fragment pass un-premultiplies it into the swapchain. Both presentation models live in RenderContext / SurfaceRenderer.

wgpu types are kept out of the public API except at one deliberate seam: SurfaceRenderer::on_surface_created takes a wgpu::SurfaceTarget (the shell must hand over a window). There is no renderer to select: the engine is the only one this crate contains, so what was a tier probe is now a plain capability gate (engine_support over TierCaps, against ENGINE_REQUIRED_DOWNLEVEL_FLAGS) that refuses an adapter which cannot run it. The cargo feature that gated the engine, the env-var/CLI override that picked a renderer, and the vello-classic/vello_cpu tiers they chose between are all gone.

HeadlessRenderer renders the same scenes with no surface at all — the offscreen harness this crate’s pixel-regression tests compare against, resolving its adapter and limits exactly as a real device does and asking the same capability gate.

external_pass is the third wgpu-typed seam, and the one that points outward: an app or a crate beside the facade registers an ExternalPass, and SurfaceRenderer hands it the frame’s own device, queue and encoder ahead of the scene pass so it can render into a target of its own and bind the result for a Command::SceneTexture to composite. See that module’s docs for the contract; HeadlessRenderer does not drain that registry.

Surface lifecycle is a first-class state machine: see SurfaceRenderer and SurfacePhase/FrameOutcome, whose pure transition tables live in frust_gpu::lifecycle and are re-exported here.

Where the foundation lives

The wgpu instance, the lazily created logical device, the surface factory and its cross-thread DetachedSurface hand-off, the surface lifecycle state machine, the persisted pipeline-cache framing and the offscreen shader-effect pipelines are all frust-gpu’s (frust_gpu::context::RenderContext, frust_gpu::surface, frust_gpu::lifecycle, frust_gpu::pipeline_cache, frust_gpu::effects) — one copy, shared with every other consumer of that crate. The context/surface/lifecycle types a shell touches are re-exported here under the names they have always had, so frust_render::RenderContext keeps working; the pipeline-cache framing and the shader-effect pipelines were never public under this crate and are reached as frust_gpu::pipeline_cache/frust_gpu::effects directly. What is genuinely this crate’s own is the renderer: the render-path decision, the engine resources each arm owns, the engine’s own capability gate, and SurfaceRenderer itself.

Re-exports

pub use external_pass::ExternalFrame;

pub use external_pass::ExternalPass;

pub use external_pass::register_external_pass;

pub use external_pass::unregister_external_pass;

Modules

external_pass

The seam an app — or a crate sitting beside the facade, a 3D renderer being the motivating one — records its own GPU work through, ahead of the engine’s scene pass and into the engine’s own frame encoder.

Structs

DeferredPresent

A frame that has been rendered and queue-submitted but not yet presented — the deferred half of SurfaceRenderer::submit_deferred.

DetachedSurface

A created-but-not-yet-configured wgpu::Surface, produced by SurfaceFactory::create_detached_surface on the windowing thread and configured on the render thread.

EngineUnsupported

An adapter that cannot run the engine: the refusal engine_support returns, naming the adapter and the flags it is missing.

HeadlessImage

The pixels of one headless render, plus the provenance of the GPU that produced them.

HeadlessMeta

Which GPU actually produced an image — the provenance every promoted baseline and every failing artifact has to record (docs/TESTING.md § GPU Run Metadata).

HeadlessOptions

How a HeadlessRenderer should pick, and then verify, its GPU.

HeadlessRenderer

A reusable offscreen engine renderer: one adapter, one device, one frust_engine::EngineRenderer and one size-matched frust_gpu::HeadlessTarget, across any number of renders.

HeadlessSpec

One offscreen render’s parameters.

RenderContext

Owns the wgpu::Instance and the single logical device this crate’s consumers render with.

SurfaceFactory

A cheap, cloneable handle to a wgpu::Instance used to create a surface on a different thread than the one that owns the renderer.

SurfaceRenderer

Per-surface renderer and lifecycle state machine.

TierCaps

Plain-data capability inputs engine_support probes. Built from a real wgpu::Adapter at the surface-creation call site (context::create_engine_surface), but constructible by hand in tests with no GPU.

Enums

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.

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.

SurfaceAlphaRequest

What a caller wants of the surface’s alpha, expressed without naming a wgpu type — the public, platform-independent request a shell makes.

SurfacePhase

Which lifecycle state the surface is in.

Constants

ENGINE_REQUIRED_DOWNLEVEL_FLAGS

The wgpu::DownlevelFlags the engine (frust-engine) cannot run without: none of them.

GOLDEN_EXPECT_ADAPTER_ENV_VAR

Environment variable naming the adapter a golden/oracle run must have resolved. Case-insensitive substring match on the adapter name, the same shape WGPU_ADAPTER_NAME itself matches by — T400 accepts NVIDIA T400 4GB.

GOLDEN_EXPECT_BACKEND_ENV_VAR

Environment variable naming the wgpu backend a golden/oracle run must have resolved (vulkan, metal, dx12, gl, …; case-insensitive, matched whole). The backend counterpart of GOLDEN_EXPECT_ADAPTER_ENV_VAR.

Functions

engine_support

Whether caps can run the engine.