Files
William Dunn 4141fe7a9f craft-gpu: provider-neutral GPU job traits and the wgpu backend (#663)
* craft-gpu: add the GPU job traits and the shared providers.

This carries over crates/gpu, crates/gpu-wgpu, crates/gpu-null, and crates/gpu-providers from the cut-down #160 branch, with minimal workspace wiring.

None of these crates names a vendor or any app. craft-gpu defines GpuJob and ProviderRegistry. craft-gpu-null is an in-memory context for tests. craft-gpu-providers holds the shared craft.* WGSL providers. craft-gpu-wgpu is the wgpu backend, native and WebGPU.

* craft-gpu: real device wiring, device loss and async readback (RFC-0022)

Addresses skylartaylor's review gate on #663 at 138f7b2. RFC-0022 has merged
since that review. This follows its acceptance requirements.

WgpuContext now requests a real device. DeviceCaps comes from that device,
reflecting the limits and features actually enabled on it. Buffers are real
wgpu::Buffer values when a device exists. The no-adapter case still degrades
to the same staging behavior as craft-gpu-null. The RFC defines that case
explicitly as the no-adapter path. Device loss is registered via
set_device_lost_callback. It surfaces as GpuFault::DeviceLost. It never
surfaces as a panic. The recovery is stated on GpuContext's trait docs.

GpuContext::read_buffer is no longer a required method. The primitives are
request_read and poll_reads. That mirrors craft-worker-host's own
HostMessage::GpuJobs to WorkerMessage::GpuBatchDone split one level down.
read_buffer stays as a default blocking convenience. It resolves immediately
on the null and staging paths. Native wgpu blocks on
Device::poll(wait_indefinitely). On wasm32 it returns GpuFault::Operation,
since a blocking wait there would freeze the one thread map_async's own
callback needs to run on.

crates/gpu-wgpu/src/tests.rs adds a real-backend suite, gated on
adapter-probe plus non-wasm32. It runs upload, readback and device-loss
tests against a real WgpuContext. It also runs three craft-gpu-providers
CPU-stand-in providers against that same real WgpuContext. It skips with a clear message when no adapter is present.
Verified against lavapipe with mesa-vulkan-drivers, using
--features adapter-probe,native-vulkan: every test passes. That run first
caught a real wgpu panic on buffer lengths that are not a multiple of 4,
COPY_BUFFER_ALIGNMENT. The fix pads real buffers transparently. Every caller
still sees exact, unpadded bytes.

docs/gpu-backends.md and docs/gpu-providers.md are updated to match,
including named consumers (the runtime slice first, then EffectCraft and
FilmCraft) and a device-ownership note for when egui's wgpu renderer is also
running.

* craft-gpu: buffer-size guards, empty-buffer parity, read_buffer keeps other completions

Answers the six findings in CodeRabbit review 5852678306 on PR #663.

upload_buffer on the device path refuses a padded size past the device's
max_buffer_size with GpuFault::InvalidJob before creating the buffer.
request_read guards its staging copy the same way. An oversized request
used to reach wgpu as a validation error on the device's error scope.

Empty buffers are accepted everywhere, matching craft-gpu-null and the
documented staging parity. The device path resolves an empty readback
immediately (wgpu refuses an empty map range). The blanket InvalidJob on
empty upload bytes is gone.

read_buffer no longer eats completions that belong to another
outstanding request. The wgpu override re-queues them for the next
poll_reads. The null context gains an override that takes only its own
completion. The trait's default-body contract is documented: with the
default body, do not interleave read_buffer with an outstanding
request_read.

ReadbackProvider validates the storage-binding cap directly. The old
chunk_buffer call allocated a Vec of slices only to drop it.

parse_u32 and params_contain refuse an empty prefix or needle.
windows(0) panics and the crate's rule is never to crash.

The manifest guard test now also rejects *-engine dependency lines, per
docs/gpu-providers.md.

* craft-gpu: per-job batch results, wasm staging reads resolve

Two findings CodeRabbit raised against the carried copy on PR 662, fixed here where the crates live. dispatch_batch now answers per job in input order. The old first-failure abort discarded outcomes earlier providers had already produced, leaving the caller nothing to reply with and no way to name the jobs worth retrying. A job fed by a failed predecessor fails honestly on its own bad handles. On wasm32 read_buffer now serves the staging backing, whose reads resolve synchronously. The backing on that target is always staging today. The refusal remains for a read that did not resolve synchronously, guarding the future wasm device backing where blocking would hang the tab.

* Add free_buffer and device_status to GpuContext.

Two CodeRabbit findings against crates/gpu-wgpu, both answered at the
trait level since craft-gpu-null has the exact same gap.

free_buffer (lib.rs:313). Every upload_buffer call added an entry to a
backend's buffer table. So did every output buffer a provider's job
created. Nothing ever removed one. Repeated jobs retained memory for
the whole lifetime of a context. The new required method releases a
buffer's resources. A freed handle behaves as invalid afterward, the
same fault an unknown handle already produces.

device_status (lib.rs:401). poll_reads can only attach a device-lost
fault to a read it has something to attach it to. A caller whose event
loop only polls, with nothing pending when loss happens, could never
observe it. The new method, default Ok(()), covers that gap directly;
a backend with no concept of device loss needs no override.

MemContext in this crate's own tests gets the same free_buffer shape as
craft-gpu-null, to keep it compiling under the new required method.

* Implement free_buffer for NullContext.

buffers moves from Vec<Vec<u8>> to Vec<Option<Vec<u8>>>. A handle is a
stable index. Freeing a slot replaces it with None. Removing it
instead would shift every later handle's index out from under its
caller. buffer_len and request_read now reject a freed index the same
way they already reject one that never existed.

Two new tests. One frees a handle and checks another's index and bytes
stay untouched. One frees a handle twice, and a handle that never
existed, and confirms both are a harmless no-op.

* Fix the no-device caps fallback, capture allocation failures, free buffers.

Four CodeRabbit findings against this crate.

The no-device fallback in WgpuContext::new called probe_caps() again
on request_device failure (lib.rs:228). A second, successful adapter
query would then report the adapter's advertised limits as if they
came from a granted device, for a context that holds none. It now
falls back to the plain, fixed caps probe_caps's own doc comment
already promises for that case.

Allocation failures during buffer creation used to reach wgpu's
default uncaptured-error handler (lib.rs:299). That handler panics.
The size check already in place only catches a request past the
device's advertised maximum. It says nothing about whether the device
can actually allocate that many bytes right now. An error scope around
both the output-buffer and the read-staging-buffer creation converts a
failure into a GpuFault instead.

free_buffer for WgpuContext (lib.rs:313) matches the Option-wrapped
shape just added to craft-gpu-null. Both backings, staging and real
device, release a buffer's resources and make the handle behave as
invalid afterward, without shifting any other handle's index.

device_status for WgpuContext (lib.rs:401) reports device loss through
the trait method just added to GpuContext. A caller that only polls
can now observe loss even with nothing pending.

New tests cover the fixed fallback value and a regression check that
the new allocation error scope does not misfire on an ordinary
allocation. They also cover free_buffer on both the staging and the
real-device path. One more covers device_status observing a destroyed
device with nothing outstanding. A genuine out-of-memory condition is not reliably
reproducible in CI; the allocation-failure test is the honest half of
that fix this can run.

* Fix the error-scope API call and run cargo fmt.

wgpu 30.0.1's Device has no pop_error_scope method. push_error_scope
returns an ErrorScopeGuard. pop() lives on that guard. Keep the guard
from push_error_scope and call pop() on it.

Also drops an unneeded mut on a test binding that never mutates its
context. Also runs cargo fmt on the lines the Option-wrapped buffer
changes touched.

* Drop a needless return clippy flagged in the adapter-probe lane.

The fallback branch in WgpuContext::new is the function's own tail
expression once the real-device branch above it has already returned
early. The explicit return on it was redundant.

* Run cargo fmt on the no-device fallback branch.

* Pop the OOM scope before the call that would misuse a failed buffer.

upload_buffer popped its scope only after write_buffer. request_read
popped its scope only after the copy and its submission. A buffer that
failed to create is invalid. Using an invalid buffer raises a VALIDATION
error that an OutOfMemory-only scope never catches. The default
uncaptured-error handler still panicked on a failed create even with the
scope in place. Pop right after create_buffer in both paths and return
before the buffer is used again, with a separate scope around the later
write or copy.

write_buffer only queues its copy into wgpu's PendingWrites. An upload
with no following submission kept the destination and staging buffers
alive inside wgpu-core until some other submit happened. upload_buffer now
flushes with an empty queue.submit right after its own write_buffer call.
A free_buffer right after an upload can now actually release the
allocation.

* Run cargo fmt on the new ordering test.

* craft-gpu-wgpu: correct the crate docs on wasm32 read_buffer

The staging backing serves wasm32 reads synchronously since the staging-reads fix. Only a read that did not complete synchronously faults. The crate-level summary still described the old unconditional fault.

* craft-gpu: sync the docs with the implemented readback behavior

Review asked for three corrections. The backends doc, the providers doc and the trait docs now state that both bundled backends override read_buffer's default body and that wasm32 serves the staging read, with a fault only for a read that did not resolve synchronously. The runtime follow-up paragraph now records that #662 consumed it. The software Vulkan container run is described as local testing. Hosted CI coverage and the pilot consumers' browser and hardware validation remain their own requirements. Em dashes swept from both docs per the house writing rules.

* has_device: say the answer once, in this file's own shape

Clippy 1.100.0 refuses the old body under `needless_bool`. The `if` returned a
bool literal with a bare `false` after it. The cfg attribute sat on the `if`
itself. The whole statement therefore vanished without the adapter-probe
feature.

Two cfg blocks replace it, one per configuration. `probe_caps` in the same
file already has that shape. `Backing::Device` exists only under that feature.
The clippy suggestion on its own would not compile.

The plain clippy leg never saw this. The line compiles only with adapter-probe
on. The all-features leg catches it, as does any workspace build that unifies
the feature in.
2026-11-18 19:05:00 -06:00

9.2 KiB

GPU backends

Crate Role
craft-gpu Traits, GpuJob, ProviderRegistry
craft-gpu-wgpu wgpu → WebGPU (wasm) / Vulkan·DX12·Metal (native)
craft-gpu-null In-memory context for CI

Feature flags on craft-gpu-wgpu:

  • adapter-probe: native only; uses pollster to request_adapter/request_device and build real DeviceCaps from the created device (falls back to the staging path when no GPU, e.g. CI with no backend feature enabled).
  • native-vulkan, native-dx12, native-metal, native-gles: enable the matching wgpu backend. adapter-probe alone compiles the probing code but finds no adapter unless at least one of these is also on.

Real device, device-truth caps (RFC-0022 requirement 1)

With adapter-probe and a native-* backend, WgpuContext::new calls Adapter::request_device after request_adapter, creating a real device. DeviceCaps is built from the created Device's own limits() / features(), never from the adapter's advertised maximum: an adapter can advertise more than a device grants. required_features is the adapter's features intersected with what this context asks for (currently nothing, since no provider dispatches a real WGSL job yet, see gpu-providers.md); required_limits is the adapter's own limits. Both choices mean request_device cannot panic on an unsupported feature or limit here.

Buffers are real wgpu::Buffers (STORAGE | COPY_SRC | COPY_DST). The host-staged Vec<Vec<u8>> form survives only on the no-device path.

The no-adapter path is still a defined path. Without a usable adapter (adapter-probe off, no backend feature on, no GPU present, or wasm32, see below), WgpuContext degrades to the same in-memory staging behavior as craft-gpu-null. WgpuContext::has_device() tells a caller which path it got; probe_caps() (no context) stays the quick, adapter-only, advisory estimate it always was.

wasm32 gap, acknowledged, not hidden. RFC-0022 itself describes browser capability probing moving "from static defaults to real adapter queries once async initialization lands in the worker". That landing hasn't happened yet. request_adapter/request_device are JS promises. Driving them synchronously the way pollster::block_on does natively is unavailable on wasm32. Wiring the async worker-init path is a larger, separate piece of work. Until then, WgpuContext on wasm32 reports the same conservative, adapter-free defaults it always has. This is the RFC's own acknowledged follow-up, not new scope invented for this PR.

Device loss (RFC-0022 requirement 1)

WgpuContext registers Device::set_device_lost_callback when it creates a real device. Loss (a driver reset, OS-level eviction, or an explicit destroy()) surfaces as GpuFault::DeviceLost, from the next buffer call and from poll_reads(), never as a panic.

Once a context has reported GpuFault::DeviceLost, every DeviceCaps it reported before that point is stale. The stated recovery, per the trait docs on GpuContext:

  1. fall back to the portable path for the rest of the session, or
  2. construct a fresh GpuContext and re-probe caps() before resuming GPU jobs.

No backend here supports continuing to dispatch jobs against a context that already reported loss, using caps read before it.

Async readback (RFC-0022 requirement 3)

GpuContext::read_buffer used to be synchronous. WebGPU can only map a buffer asynchronously (map_async), so the trait's real primitives are now request_read (queue a readback, get a ReadRequest) and poll_reads (drain completions). This mirrors craft-worker-host's own async shape: a HostMessage::GpuJobs { batch_id, .. } is answered later by WorkerMessage::GpuBatchDone { batch_id, outcomes }, not inline; request_read/poll_reads is the same split one level down, for one buffer instead of one job batch.

read_buffer stays as a blocking convenience with a default body built on those two primitives, for callers that need bytes now (the CPU-stand-in providers in craft-gpu-providers). Both bundled backends override that default body. The default has nowhere to put completions belonging to other outstanding requests. The overrides keep those queued for the next poll_reads:

  • craft-gpu-null: overrides to take only its own completion; every request resolves immediately, with nothing to wait for.
  • craft-gpu-wgpu, native, with a real device: overrides to block by calling Device::poll(PollType::wait_indefinitely()) between polls. It waits on the GPU without busy-spinning the CPU, re-queuing other requests' completions.
  • craft-gpu-wgpu, native, staging path (no device): resolves immediately, same as the null context.
  • craft-gpu-wgpu, wasm32: serves the staging read. The only backing on this target today is the in-memory staging store, since real device creation needs the async worker-init path that has not landed. Staging reads resolve synchronously. read_buffer returns their bytes. Only a read that did not resolve synchronously returns GpuFault::Operation. That refusal will matter once a real device backing exists there: wasm32 is single-threaded and blocking the one thread the browser needs to run map_async's own completion callback on would hang the tab. A caller on a future device backing must drive request_read + poll_reads from the worker's own message loop.

Consumed on craft-libs#662. That branch's RuntimeContext wrapper now forwards request_read, poll_reads, free_buffer and device_status to its inner context. It forwards read_buffer too, letting the inner backend's completion-preserving override apply. No logic in craft-worker-host or the runtime facade changed shape beyond that: HostMessage::GpuJobs still dispatches a whole batch synchronously today, answered per job.

Named consumers (RFC-0022's "what this RFC decides")

  • First: the runtime slice, craft-libs#662 (craft-worker-host, the worker-host executing GpuJob batches; craft-runtime, the facade RuntimeBuilder/Runtime build on top of GpuContext).
  • Second: the render-path apps, EffectCraft and FilmCraft. Neither has adopted these crates yet (see docs/pilot-effectcraft.md, docs/pilot-filmcraft.md); both already carry their own hand-rolled wgpu code today:
    • FilmCraft (storytold/filmcraft, crates/gpu = filmcraft-gpu): a monitor/preview GpuCompositor over composite.wgsl, mask.rs/mask.wgsl, lut.rs/lut.wgsl, transition.rs/transition.wgsl, plus its own adapter-selection policy (adapter.rs, see device ownership below) and a separate off-screen ExportRenderer. The pilot doc orders craft.mask, craft.lut, craft.transition, then craft.composite/craft.readback as the extraction sequence into craft-gpu-providers.
    • EffectCraft (storytold/effectcraft, apps/effectcraft-web): its own store.rs/persist.rs/diskcache.rs and dedicated-worker GPU dispatch (worker.rs, frames.rs); app-specific jobs route through effectcraft.* provider ids once it adopts craft-runtime, with the shared craft.* ids from this slice used alongside them.

Device ownership, when egui's wgpu renderer is also running

The question that decides whether a render-path app can adopt WgpuContext as-is: who owns the Device/Queue when egui (via eframe/egui-wgpu) is also drawing?

FilmCraft's answer today is "it depends on which device." Its on-screen monitor compositor adopts egui's own device: both the native desktop app and the web app call app.set_wgpu(cc.wgpu_render_state.clone()) (or the equivalent on native), so the compositor draws through the exact Device/Queue eframe's RenderState already created. One device, shared, no second adapter opened for the window. Its export path is deliberately the opposite: a separate, off-screen wgpu::Device with no surface, created once and kept for the process (export_renderer.rs), specifically because export runs independent of the UI's lifecycle (worker threads, no window) and must keep working even if the UI's device were ever lost or recreated.

WgpuContext::new in this PR always opens its own device (or degrades to staging) and has no constructor that accepts an externally-supplied (Device, Queue). That is documented here as the named follow-up, not implemented in this PR: accepting an existing device/queue pair (with DeviceCaps built from that pair, the same device-truth way create_device builds it today) is a small, additive constructor that does not change GpuContext's trait shape, but it needs a decision this PR's scope doesn't force: whether the shared constructor should require the caller to prove the features/limits it needs were already granted (since a second caller can't call request_device again on a device that already exists), or whether it should accept whatever was granted and fail a job if it needs more. FilmCraft's own split (share for render, separate for export) is a reasonable default for this layer too: a render-path app wanting GPU compute on the same frame it draws with egui should share; a worker-isolated batch job (the first named consumer, craft-libs#662's worker-host) has no window and no reason to share, and keeps its own device exactly as implemented here.