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
..