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.
This commit is contained in:
William Dunn authored and GitHub committed 2026-11-18 19:05:00 -06:00
1 parent 9da45ec561
commit 4141fe7a9f
29 files changed
+2130

No files matched your search

Generated
+34
View File
@@ -2232,6 +2232,40 @@ dependencies = [
"image",
]
[[package]]
name = "craft-gpu"
version = "0.1.0"
dependencies = [
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-gpu-null"
version = "0.1.0"
dependencies = [
"craft-gpu",
]
[[package]]
name = "craft-gpu-providers"
version = "0.1.0"
dependencies = [
"craft-gpu",
"craft-gpu-null",
]
[[package]]
name = "craft-gpu-wgpu"
version = "0.1.0"
dependencies = [
"craft-gpu",
"craft-gpu-providers",
"pollster 0.4.0",
"wgpu",
]
[[package]]
name = "craft-gridcraft-format"
version = "0.1.0"
+7
View File
@@ -118,6 +118,10 @@ craft-ipp = { path = "crates/ipp" }
craft-heif = { path = "crates/heif" }
craft-fig = { path = "crates/fig" }
craft-fonts-build = { path = "crates/fonts-build" }
craft-gpu = { path = "crates/gpu" }
craft-gpu-null = { path = "crates/gpu-null" }
craft-gpu-providers = { path = "crates/gpu-providers" }
craft-gpu-wgpu = { path = "crates/gpu-wgpu" }
craft-i18n = { path = "crates/i18n" }
craft-ipc = { path = "crates/ipc" }
craft-idml = { path = "crates/idml" }
@@ -232,6 +236,9 @@ proptest = "1"
encoding_rs = "0.8"
# All date/time conversion goes through chrono (no hand-rolled calendar code beyond the 400-year range extension; AGENTS.md).
chrono = { version = "0.4.45", default-features = false, features = ["std"] }
# Foundation crates for craft-gpu-wgpu. The versions match the ones the app repos already pin.
pollster = "0.4"
wgpu = { version = "30", default-features = false, features = ["std", "wgsl"] }
[workspace.lints.rust]
unsafe_code = "forbid"
+13
View File
@@ -0,0 +1,13 @@
[package]
name = "craft-gpu-null"
description = "In-memory GpuContext for CI and headless tests"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
craft-gpu = { workspace = true }
+156
View File
@@ -0,0 +1,156 @@
//! CPU-only [`GpuContext`](craft_gpu::GpuContext) for tests and CI.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use craft_gpu::{DeviceCaps, GpuContext, GpuFault, HandleId, ReadOutcome, ReadRequest, WorkerKind};
/// In-memory buffer store; no GPU hardware required. Reads resolve synchronously (there is
/// nothing to wait for), so [`request_read`](GpuContext::request_read) and
/// [`poll_reads`](GpuContext::poll_reads) satisfy the trait trivially.
/// [`read_buffer`](GpuContext::read_buffer) is overridden to take only its own completion,
/// leaving completions for other outstanding requests queued for the next
/// [`poll_reads`](GpuContext::poll_reads).
pub struct NullContext {
caps: DeviceCaps,
worker_kind: WorkerKind,
/// `None` means freed (or never allocated): handles are stable indices into this Vec, so a
/// freed slot cannot simply be removed without shifting every later handle's index.
buffers: Vec<Option<Vec<u8>>>,
next_request: u64,
ready: Vec<ReadOutcome>,
}
impl NullContext {
pub fn new(worker_kind: WorkerKind) -> Self {
Self {
caps: DeviceCaps { backend_name: "null".into(), device_name: "null".into(), ..DeviceCaps::default() },
worker_kind,
buffers: Vec::new(),
next_request: 0,
ready: Vec::new(),
}
}
}
impl GpuContext for NullContext {
fn caps(&self) -> DeviceCaps {
self.caps.clone()
}
fn worker_kind(&self) -> WorkerKind {
self.worker_kind
}
fn upload_buffer(&mut self, _label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
let id = HandleId(u32::try_from(self.buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?);
self.buffers.push(Some(bytes.to_vec()));
Ok(id)
}
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
self.buffers.get(handle.0 as usize).and_then(Option::as_ref).map(Vec::len).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
fn request_read(&mut self, handle: HandleId) -> Result<ReadRequest, GpuFault> {
let bytes = self.buffers.get(handle.0 as usize).and_then(Option::as_ref).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))?;
let request = ReadRequest(self.next_request);
self.next_request = self.next_request.wrapping_add(1);
self.ready.push(ReadOutcome { request, handle, result: Ok(bytes) });
Ok(request)
}
fn poll_reads(&mut self) -> Vec<ReadOutcome> {
std::mem::take(&mut self.ready)
}
fn read_buffer(&mut self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
let request = self.request_read(handle)?;
match self.ready.iter().position(|o| o.request == request) {
Some(i) => self.ready.remove(i).result,
None => Err(GpuFault::Operation("request_read did not resolve synchronously".into())),
}
}
/// Replaces the slot with `None` rather than removing it: handles are stable indices, and
/// removing would shift every later handle's index out from under its caller.
fn free_buffer(&mut self, handle: HandleId) {
if let Some(slot) = self.buffers.get_mut(handle.0 as usize) {
*slot = None;
}
}
}
#[cfg(test)]
mod tests {
use craft_gpu::{GpuContext, GpuFault, HandleId, WorkerKind};
use super::NullContext;
#[test]
fn request_read_then_poll_reads_delivers_the_same_bytes_as_read_buffer() {
let mut ctx = NullContext::new(WorkerKind::Main);
let handle = ctx.upload_buffer("in", b"abc").expect("upload_buffer");
let request = ctx.request_read(handle).expect("request_read");
let outcomes = ctx.poll_reads();
assert_eq!(outcomes.len(), 1);
assert_eq!(outcomes[0].request, request);
assert_eq!(outcomes[0].handle, handle);
assert_eq!(outcomes[0].result.as_deref(), Ok(b"abc".as_slice()));
}
#[test]
fn read_buffer_default_still_works() {
let mut ctx = NullContext::new(WorkerKind::SharedWorker);
let handle = ctx.upload_buffer("in", b"xyz").expect("upload_buffer");
assert_eq!(ctx.read_buffer(handle).expect("read_buffer"), b"xyz".to_vec());
}
#[test]
fn read_buffer_keeps_another_outstanding_requests_completion_queued() {
let mut ctx = NullContext::new(WorkerKind::Main);
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
let b = ctx.upload_buffer("b", b"bb").expect("upload b");
let request_a = ctx.request_read(a).expect("request_read a");
assert_eq!(ctx.read_buffer(b).expect("read_buffer b"), b"bb".to_vec());
let outcomes = ctx.poll_reads();
assert_eq!(outcomes.len(), 1, "a's completion must survive b's read_buffer");
assert_eq!(outcomes[0].request, request_a);
assert_eq!(outcomes[0].result.as_deref(), Ok(b"aa".as_slice()));
}
#[test]
fn an_empty_buffer_uploads_and_reads_back_empty() {
let mut ctx = NullContext::new(WorkerKind::Main);
let handle = ctx.upload_buffer("empty", b"").expect("upload empty");
assert_eq!(ctx.buffer_len(handle).expect("buffer_len"), 0);
assert_eq!(ctx.read_buffer(handle).expect("read_buffer"), Vec::<u8>::new());
}
/// CodeRabbit finding on gpu-wgpu/src/lib.rs:313: nothing released an uploaded buffer's
/// resources, so a backend's buffer table could only ever grow. free_buffer must actually
/// reclaim the payload and make the handle behave as invalid afterward, not just forget it
/// exists while still holding its bytes.
#[test]
fn free_buffer_invalidates_the_handle_and_does_not_shift_other_handles() {
let mut ctx = NullContext::new(WorkerKind::Main);
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
let b = ctx.upload_buffer("b", b"bb").expect("upload b");
ctx.free_buffer(a);
assert!(matches!(ctx.buffer_len(a), Err(GpuFault::InvalidJob(_))), "a freed handle must behave as invalid");
assert_eq!(ctx.buffer_len(b).expect("b must be unaffected by freeing a"), 2);
assert_eq!(ctx.read_buffer(b).expect("read_buffer b"), b"bb".to_vec(), "b's own index must not have shifted");
}
/// Freeing a handle twice, or a handle that never existed, is a no-op: callers are not
/// expected to track whether they already freed one.
#[test]
fn free_buffer_is_a_harmless_no_op_when_repeated_or_given_an_unknown_handle() {
let mut ctx = NullContext::new(WorkerKind::Main);
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
ctx.free_buffer(a);
ctx.free_buffer(a); // already freed
ctx.free_buffer(HandleId(999)); // never existed
}
}
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "craft-gpu-providers"
description = "Shared GpuProvider implementations (composite, readback, …) — no app deps"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
craft-gpu = { workspace = true }
[dev-dependencies]
craft-gpu-null = { workspace = true }
+69
View File
@@ -0,0 +1,69 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
use crate::params::parse_u32;
/// CPU stand-in for FilmCraft `composite.wgsl` Normal/Dissolve premultiplied "over" until WGSL runs on wgpu.
pub struct PremulCompositeProvider;
impl GpuProvider for PremulCompositeProvider {
fn id(&self) -> &'static str {
"craft.composite.premul"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let width = parse_u32(&job.params, b"w:").unwrap_or(1).max(1) as usize;
let height = parse_u32(&job.params, b"h:").unwrap_or(1).max(1) as usize;
let len = width.saturating_mul(height).saturating_mul(4);
let (dst_h, src_h) = match job.inputs.as_slice() {
[a, b] => (a, b),
[a] => (a, a),
_ => {
return Err(GpuFault::InvalidJob("craft.composite.premul expects one or two RGBA8 inputs (backdrop, layer)".into()));
}
};
let dst_bytes = ctx.read_buffer(*dst_h)?;
let src_bytes = ctx.read_buffer(*src_h)?;
if dst_bytes.len() < len || src_bytes.len() < len {
return Err(GpuFault::InvalidJob("input buffer shorter than w*h*4".into()));
}
let mut out = vec![0u8; len];
for px in 0..width.saturating_mul(height) {
let i = px * 4;
let mut dst = straight_to_premul([dst_bytes[i], dst_bytes[i + 1], dst_bytes[i + 2], dst_bytes[i + 3]]);
let src = straight_to_premul([src_bytes[i], src_bytes[i + 1], src_bytes[i + 2], src_bytes[i + 3]]);
premul_over(&mut dst, src);
let straight = premul_to_straight(dst);
out[i..i + 4].copy_from_slice(&straight);
}
let handle = ctx.upload_buffer("craft.composite.premul.out", &out)?;
Ok(GpuJobOutcome { outputs: vec![handle], data: None })
}
}
/// Premultiplied `src` over premultiplied `dst` (`filmcraft_render` / `composite.wgsl` Normal path).
fn premul_over(dst: &mut [f32; 4], src: [f32; 4]) {
let k = 1.0 - src[3];
for c in 0..4 {
dst[c] = src[c] + dst[c] * k;
}
}
fn straight_to_premul(p: [u8; 4]) -> [f32; 4] {
let a = f32::from(p[3]) / 255.0;
let s = a / 255.0;
[f32::from(p[0]) * s, f32::from(p[1]) * s, f32::from(p[2]) * s, a]
}
fn premul_to_straight(p: [f32; 4]) -> [u8; 4] {
let a = p[3].clamp(0.0, 1.0);
if a <= f32::EPSILON {
return [0, 0, 0, 0];
}
let inv = 255.0 / a;
[
(p[0] * inv).round().clamp(0.0, 255.0) as u8,
(p[1] * inv).round().clamp(0.0, 255.0) as u8,
(p[2] * inv).round().clamp(0.0, 255.0) as u8,
(a * 255.0).round().clamp(0.0, 255.0) as u8,
]
}
+18
View File
@@ -0,0 +1,18 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
/// Concatenates job params with bytes from the first input handle (shared test / debug provider).
pub struct EchoProvider;
impl GpuProvider for EchoProvider {
fn id(&self) -> &'static str {
"craft.test.echo"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let mut data = job.params.0.clone();
if let Some(&h) = job.inputs.first() {
data.extend_from_slice(&ctx.read_buffer(h)?);
}
Ok(GpuJobOutcome { outputs: job.outputs.clone(), data: Some(data) })
}
}
+33
View File
@@ -0,0 +1,33 @@
//! Generic GPU providers extracted from app crates over time (craft-libs#7).
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod composite;
mod echo;
mod mask;
mod noop;
mod params;
mod readback;
#[cfg(test)]
mod tests;
use craft_gpu::{GpuProvider, ProviderRegistry};
pub use composite::PremulCompositeProvider;
pub use echo::EchoProvider;
pub use mask::MaskProvider;
pub use noop::NoopProvider;
pub use readback::ReadbackProvider;
/// Default shared providers for worker/runtime init (`craft.*` ids only).
pub fn register_all() -> Vec<Box<dyn GpuProvider>> {
vec![Box::new(NoopProvider), Box::new(EchoProvider), Box::new(MaskProvider), Box::new(PremulCompositeProvider), Box::new(ReadbackProvider)]
}
/// Register [`register_all`] providers into an existing registry.
pub fn register_all_into(registry: &mut ProviderRegistry) {
for provider in register_all() {
registry.register(provider);
}
}
+35
View File
@@ -0,0 +1,35 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
use crate::params::parse_u32;
/// CPU stand-in for FilmCraft mask composite until WGSL runs on wgpu.
pub struct MaskProvider;
impl GpuProvider for MaskProvider {
fn id(&self) -> &'static str {
"craft.mask"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let width = parse_u32(&job.params, b"w:").unwrap_or(1).max(1) as usize;
let height = parse_u32(&job.params, b"h:").unwrap_or(1).max(1) as usize;
let len = width.saturating_mul(height).saturating_mul(4);
let (base, mask) = match job.inputs.as_slice() {
[a, b] => (a, b),
[a] => (a, a),
_ => return Err(GpuFault::InvalidJob("craft.mask expects one or two RGBA inputs".into())),
};
let base_bytes = ctx.read_buffer(*base)?;
let mask_bytes = ctx.read_buffer(*mask)?;
if base_bytes.len() < len || mask_bytes.len() < len {
return Err(GpuFault::InvalidJob("input buffer shorter than w*h*4".into()));
}
let mut out = vec![0u8; len];
for i in 0..len {
let m = mask_bytes[i];
out[i] = ((u16::from(base_bytes[i]) * u16::from(m)) / 255) as u8;
}
let handle = ctx.upload_buffer("craft.mask.out", &out)?;
Ok(GpuJobOutcome { outputs: vec![handle], data: None })
}
}
+14
View File
@@ -0,0 +1,14 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
/// No-op dispatch for wiring tests; shared readback/composite providers live in sibling modules.
pub struct NoopProvider;
impl GpuProvider for NoopProvider {
fn id(&self) -> &'static str {
"craft.noop"
}
fn run(&self, _ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
Ok(GpuJobOutcome { outputs: job.outputs.clone(), data: None })
}
}
+17
View File
@@ -0,0 +1,17 @@
use craft_gpu::GpuJobParams;
pub(crate) fn parse_u32(params: &GpuJobParams, prefix: &[u8]) -> Option<u32> {
// `windows(0)` panics; an empty prefix is a caller bug, answered with None, not a crash.
if prefix.is_empty() {
return None;
}
let bytes = params.0.as_slice();
let start = bytes.windows(prefix.len()).position(|w| w == prefix)? + prefix.len();
let rest = &bytes[start..];
let end = rest.iter().position(|&b| b == b',' || b == b';').unwrap_or(rest.len());
std::str::from_utf8(&rest[..end]).ok()?.parse().ok()
}
pub(crate) fn params_contain(params: &GpuJobParams, needle: &[u8]) -> bool {
!needle.is_empty() && params.0.windows(needle.len()).any(|w| w == needle)
}
+42
View File
@@ -0,0 +1,42 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider, f16_rgba_to_f32_bytes};
use crate::params::{params_contain, parse_u32};
/// CPU stand-in for accumulator/output readback (`read_accumulator` / `read_output` in FilmCraft gpu) until wgpu maps buffers.
pub struct ReadbackProvider;
impl GpuProvider for ReadbackProvider {
fn id(&self) -> &'static str {
"craft.readback"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let width = parse_u32(&job.params, b"w:").unwrap_or(0);
let height = parse_u32(&job.params, b"h:").unwrap_or(0);
let input = job.inputs.first().copied().ok_or_else(|| GpuFault::InvalidJob("craft.readback expects one input buffer".into()))?;
let raw = ctx.read_buffer(input)?;
// A real GPU provider binds the input as a storage buffer. Refuse a caps report no
// device path could satisfy, instead of pretending this stand-in's readback would have
// worked there.
if ctx.caps().max_storage_buffer_binding_size == 0 {
return Err(GpuFault::Operation("max_storage_buffer_binding_size must be non-zero".into()));
}
let out_bytes = if params_contain(&job.params, b"fmt:u8") {
let need = usize::try_from(width.saturating_mul(height).saturating_mul(4)).map_err(|_| GpuFault::InvalidJob("w*h overflow".into()))?;
if need == 0 || raw.len() < need {
return Err(GpuFault::InvalidJob("rgba8 readback shorter than w*h*4".into()));
}
raw[..need].to_vec()
} else {
let need = usize::try_from(width.saturating_mul(height).saturating_mul(8)).map_err(|_| GpuFault::InvalidJob("w*h overflow".into()))?;
if need == 0 || raw.len() < need {
return Err(GpuFault::InvalidJob("f16 rgba readback shorter than w*h*8".into()));
}
f16_rgba_to_f32_bytes(&raw[..need]).map_err(|len| GpuFault::InvalidJob(format!("f16 rgba length {len} not multiple of 8")))?
};
let handle = ctx.upload_buffer("craft.readback.out", &out_bytes)?;
Ok(GpuJobOutcome { outputs: vec![handle], data: None })
}
}
+140
View File
@@ -0,0 +1,140 @@
#![allow(clippy::expect_used)]
use craft_gpu::{GpuContext, GpuJob, GpuJobParams, ProviderRegistry, WorkerKind, f16_to_f32, f16_to_f32_fast};
use craft_gpu_null::NullContext;
use crate::{EchoProvider, MaskProvider, NoopProvider, PremulCompositeProvider, ReadbackProvider, register_all, register_all_into};
#[test]
fn noop_provider_registered_by_id() {
let mut registry = ProviderRegistry::new();
registry.register(Box::new(NoopProvider));
let mut ctx = NullContext::new(WorkerKind::Main);
let job = GpuJob { provider_id: "craft.noop".into(), params: GpuJobParams(Vec::new()), inputs: vec![], outputs: vec![] };
let out = registry.dispatch(&mut ctx, &job).expect("noop dispatch");
assert!(out.data.is_none());
}
#[test]
fn echo_provider_concatenates_params_and_first_input() {
let mut registry = ProviderRegistry::new();
registry.register(Box::new(EchoProvider));
let mut ctx = NullContext::new(WorkerKind::Main);
let h = ctx.upload_buffer("in", b"xy").expect("upload_buffer in test");
let job = GpuJob { provider_id: "craft.test.echo".into(), params: GpuJobParams(b"a".to_vec()), inputs: vec![h], outputs: vec![] };
let out = registry.dispatch(&mut ctx, &job).expect("echo dispatch");
assert_eq!(out.data.as_deref(), Some(b"axy".as_slice()));
}
#[test]
fn register_all_lists_shared_providers() {
let ids: Vec<_> = register_all().iter().map(|p| p.id()).collect();
assert_eq!(ids, vec!["craft.noop", "craft.test.echo", "craft.mask", "craft.composite.premul", "craft.readback",]);
}
#[test]
fn gpu_providers_cargo_has_no_app_deps() {
let manifest = include_str!("../Cargo.toml");
for line in manifest.lines() {
let t = line.trim();
assert!(
!(t.starts_with("effectcraft")
|| t.starts_with("filmcraft")
|| t.contains("effectcraft-")
|| t.contains("filmcraft-")
|| t.contains("-engine =")
|| t.contains("-engine.")
|| t.contains("-engine\"")),
"forbidden app dependency line: {t}"
);
}
}
#[test]
fn empty_param_prefix_and_needle_are_refused_not_a_panic() {
let params = GpuJobParams(b"w:3,h:2".to_vec());
assert_eq!(crate::params::parse_u32(&params, b""), None);
assert!(!crate::params::params_contain(&params, b""));
}
#[test]
fn mask_provider_multiplies_rgba_by_mask_on_cpu() {
let mut registry = ProviderRegistry::new();
registry.register(Box::new(MaskProvider));
let mut ctx = NullContext::new(WorkerKind::Main);
let base = ctx.upload_buffer("base", &[255u8, 0, 0, 255, 100, 100, 100, 255]).expect("upload base");
let mask = ctx.upload_buffer("mask", &[128u8, 255, 255, 255, 0, 255, 255, 255]).expect("upload mask");
let job =
craft_gpu::GpuJob { provider_id: "craft.mask".into(), params: GpuJobParams(b"w:1,h:2".to_vec()), inputs: vec![base, mask], outputs: vec![] };
let out = registry.dispatch(&mut ctx, &job).expect("mask dispatch");
let handle = out.outputs[0];
let bytes = ctx.read_buffer(handle).expect("read mask out");
assert_eq!(bytes[0], 128);
assert_eq!(bytes[4], 0);
}
#[test]
fn premul_composite_over_on_cpu() {
let mut registry = ProviderRegistry::new();
registry.register(Box::new(PremulCompositeProvider));
let mut ctx = NullContext::new(WorkerKind::Main);
// backdrop: green opaque; layer: half-alpha blue
let dst = ctx.upload_buffer("dst", &[0, 255, 0, 255]).expect("upload dst");
let src = ctx.upload_buffer("src", &[0, 0, 255, 128]).expect("upload src");
let job =
GpuJob { provider_id: "craft.composite.premul".into(), params: GpuJobParams(b"w:1,h:1".to_vec()), inputs: vec![dst, src], outputs: vec![] };
let out = registry.dispatch(&mut ctx, &job).expect("premul composite");
let bytes = ctx.read_buffer(out.outputs[0]).expect("read out");
assert_eq!(bytes[0], 0);
assert_eq!(bytes[1], 127);
assert_eq!(bytes[2], 128);
assert_eq!(bytes[3], 255);
}
#[test]
fn readback_decodes_f16_rgba_to_f32() {
let mut registry = ProviderRegistry::new();
registry.register(Box::new(ReadbackProvider));
let mut ctx = NullContext::new(WorkerKind::Main);
let h = half_float_one();
let mut raw = Vec::new();
raw.extend_from_slice(&h.to_le_bytes());
raw.extend_from_slice(&h.to_le_bytes());
raw.extend_from_slice(&h.to_le_bytes());
raw.extend_from_slice(&0u16.to_le_bytes());
let inp = ctx.upload_buffer("accum", &raw).expect("upload f16");
let job = GpuJob { provider_id: "craft.readback".into(), params: GpuJobParams(b"w:1,h:1".to_vec()), inputs: vec![inp], outputs: vec![] };
let out = registry.dispatch(&mut ctx, &job).expect("readback");
let decoded = ctx.read_buffer(out.outputs[0]).expect("read f32 out");
assert_eq!(decoded.len(), 16);
let r = f32::from_le_bytes(decoded[0..4].try_into().expect("r"));
assert!((r - 1.0).abs() < 1e-3);
assert_eq!(f16_to_f32(h), f16_to_f32_fast(h));
}
fn half_float_one() -> u16 {
f32_to_f16(1.0)
}
fn f32_to_f16(v: f32) -> u16 {
let bits = v.to_bits();
let sign = ((bits >> 31) & 1) as u16;
let exp = ((bits >> 23) & 0xff) as i32 - 127 + 15;
let mant = bits & 0x007f_ffff;
if exp <= 0 {
return sign << 15;
}
if exp >= 0x1f {
return (sign << 15) | 0x7c00;
}
(sign << 15) | ((exp as u16) << 10) | ((mant >> 13) as u16)
}
#[test]
fn register_all_into_populates_registry() {
let mut registry = ProviderRegistry::new();
register_all_into(&mut registry);
let mut ctx = NullContext::new(WorkerKind::SharedWorker);
let job = GpuJob { provider_id: "craft.noop".into(), params: GpuJobParams(Vec::new()), inputs: vec![], outputs: vec![] };
registry.dispatch(&mut ctx, &job).expect("noop via register_all_into");
}
+35
View File
@@ -0,0 +1,35 @@
[package]
name = "craft-gpu-wgpu"
description = "craft-gpu backend using wgpu (WebGPU on wasm32, native APIs on desktop)"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
craft-gpu = { workspace = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
wgpu = { workspace = true, features = ["webgpu"] }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
pollster = { workspace = true, optional = true }
wgpu = { workspace = true }
[features]
default = []
adapter-probe = ["dep:pollster"]
native-vulkan = ["wgpu/vulkan"]
native-dx12 = ["wgpu/dx12"]
native-metal = ["wgpu/metal"]
native-gles = ["wgpu/gles"]
[dev-dependencies]
pollster = { workspace = true }
# Real-backend test (crates/gpu-wgpu/src/tests.rs): dispatches craft-gpu-providers' CPU-stand-in
# providers against a real WgpuContext, not just craft-gpu-null, per RFC-0022 acceptance
# requirement 2. Dev-only: no cycle (craft-gpu-providers never depends on craft-gpu-wgpu).
craft-gpu-providers = { workspace = true }
+563
View File
@@ -0,0 +1,563 @@
//! wgpu-backed [`GpuContext`](craft_gpu::GpuContext).
//!
//! WebGPU on `wasm32`; native APIs when backend features are enabled. With the `adapter-probe`
//! feature (native only, pollster) and at least one `native-*` backend feature,
//! [`WgpuContext::new`] requests a real device and builds [`DeviceCaps`] from what that device
//! actually enabled (`Device::limits()` / `Device::features()`), never from the adapter's
//! advertised maximum. Without a usable adapter (the features above are off, no GPU is present,
//! or on `wasm32` where real device creation needs the async worker-init path noted in
//! `docs/gpu-backends.md`), the context degrades to the same in-memory staging behavior as
//! `craft_gpu_null::NullContext` (not a dependency of this crate; named here only for context);
//! that is RFC-0022's defined no-adapter path, not an error.
//!
//! Readback is asynchronous end to end (`request_read` + `poll_reads`), because WebGPU can only
//! map a buffer that way. Native, with a real device, drives it with `Buffer::map_async` plus
//! `Device::poll`. The blocking `read_buffer` convenience (see
//! [`GpuContext`](craft_gpu::GpuContext)'s trait docs) blocks efficiently on native by polling
//! the device while it waits. On `wasm32` the backing is always the in-memory staging store
//! today, whose reads complete synchronously, and `read_buffer` serves them; only a read that
//! did not complete synchronously returns a fault there, since blocking would freeze the one
//! thread a real map's completion callback would need to run on.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use craft_gpu::{DeviceCaps, GpuContext, GpuFault, HandleId, ReadOutcome, ReadRequest, WorkerKind};
#[cfg(test)]
mod tests;
fn probe_fallback(backend_name: &str, device_name: &str) -> DeviceCaps {
DeviceCaps { backend_name: backend_name.into(), device_name: device_name.into(), ..DeviceCaps::default() }
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
fn probe_caps_native() -> DeviceCaps {
let instance = native::instance();
let adapter = match pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default())) {
Ok(adapter) => adapter,
Err(_) => return probe_fallback("wgpu", "no-adapter"),
};
let info = adapter.get_info();
let limits = adapter.limits();
DeviceCaps {
backend_name: format!("{:?}", info.backend),
device_name: info.name,
max_storage_buffer_binding_size: limits.max_storage_buffer_binding_size,
max_buffer_size: limits.max_buffer_size,
max_texture_dimension_2d: limits.max_texture_dimension_2d,
features: Vec::new(),
}
}
/// Adapter-advertised limits, when an adapter is available; otherwise conservative defaults. This
/// is the quick, device-free probe for UI surfaces that want a number before any context exists
/// (Settings). It is advisory only: these are the adapter's maximums, not a device's granted
/// ones. [`WgpuContext::caps`] is the authoritative, device-truth source once a context exists.
pub fn probe_caps() -> DeviceCaps {
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
{
probe_caps_native()
}
#[cfg(all(not(target_arch = "wasm32"), not(feature = "adapter-probe")))]
{
probe_fallback("wgpu", "probe-not-run")
}
#[cfg(target_arch = "wasm32")]
{
probe_fallback("webgpu", "browser")
}
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
mod native {
use std::sync::{Arc, Mutex};
use craft_gpu::{DeviceCaps, GpuFault};
use crate::{Backing, DeviceBacking};
/// Features this context asks a device for. No provider dispatches a real WGSL job on wgpu
/// yet (`craft-gpu-providers` ships CPU stand-ins, by design, until that lands); extend this
/// as real compute providers land, and it degrades gracefully regardless: see
/// [`create_device`].
const DESIRED_FEATURES: wgpu::Features = wgpu::Features::empty();
/// An instance over whichever native backends were compiled in (`native-vulkan`,
/// `native-dx12`, `native-metal`, `native-gles`), honoring `WGPU_BACKEND` when set, so the
/// same build can be pointed at a software Vulkan adapter (lavapipe/llvmpipe) in a local container run or a CI lane.
/// `new_without_display_handle` because this context never has a window (no surface is ever
/// requested); FilmCraft's own off-screen export device uses the same constructor for the
/// same reason (`filmcraft-gpu`'s `export_renderer.rs`, see `docs/gpu-backends.md`).
pub(crate) fn instance() -> wgpu::Instance {
let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
if let Some(backends) = wgpu::Backends::from_env() {
desc.backends = backends;
}
wgpu::Instance::new(desc)
}
/// Request a real device. `None` on the defined no-adapter path (no usable adapter): the
/// caller degrades to the staging backing, identical in shape to `craft-gpu-null`.
///
/// Never panics: `required_features` is intersected with what the adapter actually
/// advertises, and `required_limits` is set to the adapter's own limits (never more), so
/// `request_device`'s documented panics ("features/limits not supported by this adapter")
/// cannot trigger here.
pub(crate) fn create_device() -> Option<(DeviceCaps, Backing)> {
let instance = instance();
let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default())).ok()?;
let features = DESIRED_FEATURES & adapter.features();
let limits = adapter.limits();
let desc =
wgpu::DeviceDescriptor { label: Some("craft-gpu-wgpu"), required_features: features, required_limits: limits, ..Default::default() };
let (device, queue) = pollster::block_on(adapter.request_device(&desc)).ok()?;
let lost = Arc::new(Mutex::new(None));
{
let lost = Arc::clone(&lost);
device.set_device_lost_callback(move |reason, message| {
if let Ok(mut slot) = lost.lock() {
*slot = Some(GpuFault::DeviceLost(format!("{reason:?}: {message}")));
}
});
}
let info = device.adapter_info();
let device_limits = device.limits();
let caps = DeviceCaps {
backend_name: format!("{:?}", info.backend),
device_name: info.name,
max_storage_buffer_binding_size: device_limits.max_storage_buffer_binding_size,
max_buffer_size: device_limits.max_buffer_size,
max_texture_dimension_2d: device_limits.max_texture_dimension_2d,
features: device.features().iter_names().map(|(name, _)| name.to_string()).collect(),
};
let backing = Backing::Device(DeviceBacking { device, queue, buffers: Vec::new(), lost, pending: Vec::new() });
Some((caps, backing))
}
}
/// No real device: buffers live on the host, exactly like `craft-gpu-null`. RFC-0022's defined
/// degrade path for "no adapter" (feature off, no GPU present, or the `wasm32` async-init gap).
/// Each slot is `None` once freed (or never allocated): handles are stable indices, so a freed
/// slot cannot simply be removed without shifting every later handle's index.
#[cfg(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")))]
enum Backing {
Staging(Vec<Option<Vec<u8>>>),
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
enum Backing {
Staging(Vec<Option<Vec<u8>>>),
/// A real device. `DeviceCaps` was built from it, not from the adapter it came from.
Device(DeviceBacking),
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
struct DeviceBacking {
device: wgpu::Device,
queue: wgpu::Queue,
/// Each buffer paired with its true, caller-given byte length. wgpu requires every buffer
/// with copy usage to be sized in multiples of [`COPY_ALIGN`]; the buffer itself is padded to
/// that, but callers (`buffer_len`, `request_read`'s returned bytes) see the true length,
/// matching the staging path and `craft-gpu-null` exactly, with no padding visible. `None`
/// once freed: see the `Backing::Staging` doc for why the slot stays rather than shifting.
buffers: Vec<Option<(wgpu::Buffer, u64)>>,
/// Set by the device-lost callback registered in [`native::create_device`]; checked before
/// every call that would otherwise touch the (now invalid) device.
lost: std::sync::Arc<std::sync::Mutex<Option<GpuFault>>>,
pending: Vec<PendingRead>,
}
/// wgpu's `COPY_BUFFER_ALIGNMENT`: every buffer with copy usage, and every `write_buffer` /
/// `copy_buffer_to_buffer` size, must be a multiple of this (4 bytes). Uploading or reading back
/// a buffer length that doesn't land on this boundary (`b"xy"`, two bytes) is a validation error
/// on native wgpu, surfaced as a panic from inside `wgpu-core`'s own uncaptured-error path unless
/// padded first; `craft-gpu-null`'s plain `Vec<u8>` has no such constraint, so this padding is
/// purely an artifact of the real backend, kept invisible to every caller of this crate.
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
const COPY_ALIGN: u64 = 4;
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
struct PendingRead {
request: ReadRequest,
handle: HandleId,
staging: wgpu::Buffer,
/// True length to truncate the mapped (padded) bytes back down to.
true_len: u64,
state: std::sync::Arc<std::sync::Mutex<Option<Result<(), String>>>>,
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
fn resolve_pending(pending: PendingRead) -> ReadOutcome {
let PendingRead { request, handle, staging, true_len, state } = pending;
let result = match state.lock() {
Ok(mut guard) => match guard.take() {
Some(Ok(())) => match staging.get_mapped_range(0..true_len.next_multiple_of(COPY_ALIGN)) {
Ok(view) => {
let mut bytes = view.to_vec();
drop(view);
staging.unmap();
bytes.truncate(usize::try_from(true_len).unwrap_or(usize::MAX));
Ok(bytes)
}
Err(err) => Err(GpuFault::Operation(err.to_string())),
},
Some(Err(message)) => Err(GpuFault::Operation(message)),
None => Err(GpuFault::Operation("read_buffer: map_async callback has not run yet".into())),
},
Err(_) => Err(GpuFault::Operation("read_buffer: map state lock poisoned".into())),
};
ReadOutcome { request, handle, result }
}
/// wgpu-backed context. See the module docs for the real-device-vs-staging split.
pub struct WgpuContext {
caps: DeviceCaps,
worker_kind: WorkerKind,
backing: Backing,
next_request: u64,
ready: Vec<ReadOutcome>,
}
impl WgpuContext {
pub fn new(worker_kind: WorkerKind) -> Self {
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
{
if let Some((caps, backing)) = native::create_device() {
return Self { caps, worker_kind, backing, next_request: 0, ready: Vec::new() };
}
// request_adapter and/or request_device failed: fall back to the conservative
// fallback, never probe_caps(). probe_caps() would re-query the adapter here, and a
// second, successful adapter query would report the adapter's advertised limits as
// if they came from a granted device -- the exact thing probe_caps's own doc comment
// says caps() must never do for a context with no device.
Self { caps: probe_fallback("wgpu", "no-device"), worker_kind, backing: Backing::Staging(Vec::new()), next_request: 0, ready: Vec::new() }
}
#[cfg(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")))]
Self { caps: probe_caps(), worker_kind, backing: Backing::Staging(Vec::new()), next_request: 0, ready: Vec::new() }
}
/// Force the staging (no-device) path with caller-supplied caps. For tests, and for callers
/// that intentionally want the portable path (FilmCraft's `?webgl` / `?nogpuworkers`, per
/// `docs/pilot-filmcraft.md`) rather than a real device's own caps.
pub fn with_caps(worker_kind: WorkerKind, caps: DeviceCaps) -> Self {
Self { caps, worker_kind, backing: Backing::Staging(Vec::new()), next_request: 0, ready: Vec::new() }
}
/// True when this context holds a real device (`request_device` succeeded), false on the
/// staging/no-adapter path. Settings UI can use this to show "no GPU" honestly instead of
/// implying a device that was never created; tests use it to skip rather than fail when the
/// host genuinely has no usable adapter (see `crates/gpu-wgpu/src/tests.rs`).
pub fn has_device(&self) -> bool {
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
{
matches!(self.backing, Backing::Device(_))
}
#[cfg(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")))]
{
false
}
}
/// True once the device has reported loss. Every [`DeviceCaps`] read before this point is
/// stale; see [`GpuContext`]'s trait docs for the recovery this context expects.
pub fn is_device_lost(&self) -> bool {
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
if let Backing::Device(d) = &self.backing {
return d.lost.lock().map(|g| g.is_some()).unwrap_or(false);
}
false
}
fn take_lost_fault(&self) -> Option<GpuFault> {
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
if let Backing::Device(d) = &self.backing {
return d.lost.lock().ok().and_then(|g| g.clone());
}
None
}
}
impl GpuContext for WgpuContext {
fn caps(&self) -> DeviceCaps {
self.caps.clone()
}
fn worker_kind(&self) -> WorkerKind {
self.worker_kind
}
#[cfg_attr(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")), allow(unused_variables))]
fn upload_buffer(&mut self, label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
if let Some(fault) = self.take_lost_fault() {
return Err(fault);
}
match &mut self.backing {
Backing::Staging(buffers) => {
let id = u32::try_from(buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?;
buffers.push(Some(bytes.to_vec()));
Ok(HandleId(id))
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
Backing::Device(d) => {
let true_len = bytes.len() as u64;
let padded_len = true_len.next_multiple_of(COPY_ALIGN);
if padded_len > self.caps.max_buffer_size {
return Err(GpuFault::InvalidJob(format!(
"upload_buffer: {true_len} bytes (padded to {padded_len}) exceeds the device's max_buffer_size {}",
self.caps.max_buffer_size
)));
}
// The size check above only catches a request past the device's advertised
// maximum; it proves nothing about whether the device can actually allocate
// padded_len bytes right now (free VRAM varies). wgpu 30.0.1 sends an allocation
// failure to the default uncaptured-error handler, which panics, unless a scope
// captures it first. Pop this scope immediately, before write_buffer below ever
// touches `buffer`: a buffer that failed to create is invalid, and writing to an
// invalid buffer raises its own VALIDATION error, a kind this OutOfMemory-only
// scope does not catch, so it must reach the default handler and panic regardless
// of when this scope is popped. Checking right here is what keeps that from
// happening at all.
let create_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
let buffer = d.device.create_buffer(&wgpu::BufferDescriptor {
label: Some(label),
size: padded_len,
usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
if let Some(err) = pollster::block_on(create_scope.pop()) {
return Err(GpuFault::Operation(format!("upload_buffer: device reported an allocation error creating the buffer: {err}")));
}
// write_buffer makes its own staging allocation to carry `bytes` to the device, a
// second allocation that can also run out of memory; it gets its own scope rather
// than reusing the one already closed above.
let write_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
if padded_len == true_len {
d.queue.write_buffer(&buffer, 0, bytes);
} else {
let mut padded = bytes.to_vec();
padded.resize(usize::try_from(padded_len).unwrap_or(bytes.len()), 0);
d.queue.write_buffer(&buffer, 0, &padded);
}
// write_buffer only records the copy into wgpu's PendingWrites; wgpu-core flushes
// that queue at the sooner of the caller's next real command-buffer submission or
// the next map_async on an affected buffer, and keeps the buffer named by the
// write alive internally until then. Without a submission here, a free_buffer
// right after this call could never actually release the GPU allocation behind
// it, since nothing would ever flush PendingWrites to let it go. An empty submit
// is still a submission as far as that flush is concerned, so it is enough.
d.queue.submit(std::iter::empty());
if let Some(err) = pollster::block_on(write_scope.pop()) {
return Err(GpuFault::Operation(format!("upload_buffer: device reported an allocation error writing the buffer: {err}")));
}
let id = u32::try_from(d.buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?;
d.buffers.push(Some((buffer, true_len)));
Ok(HandleId(id))
}
}
}
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
if let Some(fault) = self.take_lost_fault() {
return Err(fault);
}
match &self.backing {
Backing::Staging(buffers) => {
buffers.get(handle.0 as usize).and_then(Option::as_ref).map(Vec::len).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
Backing::Device(d) => {
d.buffers.get(handle.0 as usize).and_then(Option::as_ref).ok_or_else(|| GpuFault::InvalidJob("bad handle".into())).and_then(
|(_, true_len)| usize::try_from(*true_len).map_err(|_| GpuFault::Operation("buffer size exceeds host address space".into())),
)
}
}
}
fn request_read(&mut self, handle: HandleId) -> Result<ReadRequest, GpuFault> {
if let Some(fault) = self.take_lost_fault() {
return Err(fault);
}
match &mut self.backing {
Backing::Staging(buffers) => {
let bytes =
buffers.get(handle.0 as usize).and_then(Option::as_ref).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))?;
let id = self.next_request;
self.next_request = self.next_request.wrapping_add(1);
let request = ReadRequest(id);
self.ready.push(ReadOutcome { request, handle, result: Ok(bytes) });
Ok(request)
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
Backing::Device(d) => {
let (buffer, true_len) =
d.buffers.get(handle.0 as usize).and_then(Option::as_ref).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))?;
let true_len = *true_len;
if true_len == 0 {
// An empty buffer has nothing to copy or map (wgpu refuses an empty map
// range); resolve it immediately, same as the staging path.
let id = self.next_request;
self.next_request = self.next_request.wrapping_add(1);
let request = ReadRequest(id);
self.ready.push(ReadOutcome { request, handle, result: Ok(Vec::new()) });
return Ok(request);
}
let copy_len = true_len.next_multiple_of(COPY_ALIGN);
if copy_len > self.caps.max_buffer_size {
return Err(GpuFault::Operation(format!(
"request_read: staging copy of {copy_len} bytes exceeds the device's max_buffer_size {}",
self.caps.max_buffer_size
)));
}
// Same reasoning as upload_buffer's error scope: an allocation failure for the
// read-staging buffer must become a GpuFault, not reach the default
// uncaptured-error handler and panic. Pop immediately, before copy_buffer_to_buffer
// below ever names `staging` as a copy destination: a staging buffer that failed
// to create is invalid, and copying into an invalid buffer raises its own
// VALIDATION error, a kind this OutOfMemory-only scope does not catch, so it must
// reach the default handler and panic regardless of when this scope is popped.
let create_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
let staging = d.device.create_buffer(&wgpu::BufferDescriptor {
label: Some("craft-gpu-wgpu.read-staging"),
size: copy_len,
usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
if let Some(err) = pollster::block_on(create_scope.pop()) {
return Err(GpuFault::Operation(format!("request_read: device reported an allocation error creating the staging buffer: {err}")));
}
// The copy and its submission get their own scope rather than reusing the one
// already closed above, same split as upload_buffer's create vs. write.
let copy_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
let mut encoder = d.device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("craft-gpu-wgpu.read-copy") });
encoder.copy_buffer_to_buffer(buffer, 0, &staging, 0, copy_len);
d.queue.submit(Some(encoder.finish()));
if let Some(err) = pollster::block_on(copy_scope.pop()) {
return Err(GpuFault::Operation(format!("request_read: device reported an allocation error copying the buffer: {err}")));
}
let state = std::sync::Arc::new(std::sync::Mutex::new(None));
{
let state = std::sync::Arc::clone(&state);
staging.map_async(wgpu::MapMode::Read, 0..copy_len, move |result| {
if let Ok(mut slot) = state.lock() {
*slot = Some(result.map_err(|e| e.to_string()));
}
});
}
let id = self.next_request;
self.next_request = self.next_request.wrapping_add(1);
let request = ReadRequest(id);
d.pending.push(PendingRead { request, handle, staging, true_len, state });
Ok(request)
}
}
}
/// Replaces the slot with `None` rather than removing it: handles are stable indices, and
/// removing would shift every later handle's index out from under its caller. Dropping a
/// `Some((wgpu::Buffer, _))` here releases that buffer's GPU-side allocation.
fn free_buffer(&mut self, handle: HandleId) {
match &mut self.backing {
Backing::Staging(buffers) => {
if let Some(slot) = buffers.get_mut(handle.0 as usize) {
*slot = None;
}
}
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
Backing::Device(d) => {
if let Some(slot) = d.buffers.get_mut(handle.0 as usize) {
*slot = None;
}
}
}
}
/// Covers the gap `poll_reads` has when nothing is pending: that method can only attach a
/// device-lost fault to a read it has something to attach it to, so a caller whose event
/// loop only polls, with no outstanding read, could never observe loss through it alone.
fn device_status(&self) -> Result<(), GpuFault> {
if let Some(fault) = self.take_lost_fault() {
return Err(fault);
}
Ok(())
}
#[cfg_attr(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")), allow(unused_mut))]
fn poll_reads(&mut self) -> Vec<ReadOutcome> {
let mut outcomes = std::mem::take(&mut self.ready);
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
if let Backing::Device(d) = &mut self.backing {
if let Some(fault) = d.lost.lock().ok().and_then(|g| g.clone()) {
outcomes.extend(d.pending.drain(..).map(|p| ReadOutcome { request: p.request, handle: p.handle, result: Err(fault.clone()) }));
return outcomes;
}
let _ = d.device.poll(wgpu::PollType::Poll);
let mut remaining = Vec::with_capacity(d.pending.len());
for pending in d.pending.drain(..) {
let is_ready = pending.state.lock().map(|g| g.is_some()).unwrap_or(false);
if is_ready {
outcomes.push(resolve_pending(pending));
} else {
remaining.push(pending);
}
}
d.pending = remaining;
}
outcomes
}
#[cfg(not(target_arch = "wasm32"))]
fn read_buffer(&mut self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
let request = self.request_read(handle)?;
loop {
let mut matched = None;
let mut others = Vec::new();
for outcome in self.poll_reads() {
if outcome.request == request {
matched = Some(outcome.result);
} else {
others.push(outcome);
}
}
// Completions belonging to other outstanding requests go back on the queue for the
// caller's next poll_reads instead of being dropped.
self.ready.extend(others);
if let Some(result) = matched {
return result;
}
// Block on the GPU between polls instead of busy-spinning the CPU. A no-op when
// `backing` is `Staging` (nothing to wait for; the request already resolved above)
// or when wgpu is itself WebGPU under the hood, which self-polls.
#[cfg(feature = "adapter-probe")]
if let Backing::Device(d) = &self.backing {
let _ = d.device.poll(wgpu::PollType::wait_indefinitely());
}
}
}
/// On `wasm32` the backing is always the in-memory staging store today (real device
/// creation needs the async worker-init path and does not exist on this target yet), and a
/// staging read resolves synchronously, so serving it blocks nothing. The refusal below
/// guards the future wasm device backing: WebGPU can only map a buffer asynchronously, and
/// `wasm32` is single-threaded, so blocking on a real device would stop the only thread the
/// browser needs to run `map_async`'s own completion callback on, hanging the tab. Callers
/// on a device backing drive [`request_read`](GpuContext::request_read) and
/// [`poll_reads`](GpuContext::poll_reads) from the worker's message loop instead; see
/// `docs/gpu-backends.md`.
#[cfg(target_arch = "wasm32")]
fn read_buffer(&mut self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
let request = self.request_read(handle)?;
match self.ready.iter().position(|o| o.request == request) {
Some(i) => self.ready.remove(i).result,
None => Err(GpuFault::Operation(
"read_buffer on wasm32: the read did not resolve synchronously. Use request_read + poll_reads from the worker's message loop \
instead."
.into(),
)),
}
}
}
+367
View File
@@ -0,0 +1,367 @@
#![allow(clippy::expect_used)]
//! RFC-0022 acceptance requirement 2: real backends beside the null one. `craft-gpu-null` stays
//! mandatory for every consumer (it cannot validate shader compilation, resource rules, or
//! numerical results), so these tests run representative jobs on a real wgpu device when one is
//! available. Runs against a software Vulkan adapter in a local container are local testing, not
//! hosted CI coverage: hosted lanes and the pilot consumers' browser and hardware validation
//! remain their own, separate requirements. The suite skips loudly when the host has no adapter
//! (`cargo test` without `--features adapter-probe,native-vulkan` already exercises the masked
//! path: no adapter is ever requested, and every context here falls back to the staging path,
//! same shape as `craft-gpu-null`).
//!
//! Tolerance: every job below is byte/structural equality, not a numeric comparison with slack.
//! That is honest for what runs today: no provider dispatches a real WGSL compute job yet
//! (`craft-gpu-providers` ships CPU stand-ins by design; see `docs/gpu-providers.md`), so the only
//! thing a real device adds over the null one here is the upload → real `wgpu::Buffer` → copy →
//! `map_async` → read round trip itself. A provider that dispatches actual WGSL will need a
//! stated numeric tolerance of its own when it lands; this suite is not that provider.
use craft_gpu::{GpuContext, GpuJob, GpuJobParams, GpuProvider, WorkerKind};
use craft_gpu_providers::{EchoProvider, PremulCompositeProvider, ReadbackProvider};
use crate::WgpuContext;
/// A real device if this host has one; otherwise `None` with a loud, honest message instead of a
/// failed assertion. Call at the top of every test in this module.
fn real_context_or_skip(test_name: &str) -> Option<WgpuContext> {
let ctx = WgpuContext::new(WorkerKind::Main);
if ctx.has_device() {
return Some(ctx);
}
eprintln!(
"SKIP {test_name}: no real wgpu device in this environment (no backend feature compiled \
in, or `request_adapter` found nothing). This is RFC-0022's defined no-adapter path, not \
a failure; craft-gpu-null already covers the portable contract. Run with \
`--features adapter-probe,native-vulkan` against a Vulkan adapter (a software one, such \
as lavapipe/llvmpipe via mesa-vulkan-drivers, is enough) to exercise this suite for real."
);
None
}
#[test]
fn real_device_reports_a_non_null_backend_and_empty_features_it_actually_requested() {
let Some(ctx) = real_context_or_skip("real_device_reports_a_non_null_backend_and_empty_features_it_actually_requested") else {
return;
};
let caps = ctx.caps();
assert_ne!(caps.backend_name, "null", "a real device must not report the null backend name");
assert_ne!(caps.device_name, "no-adapter", "has_device() was true; caps must not be the no-adapter fallback");
assert_ne!(caps.device_name, "probe-not-run", "has_device() was true; caps must not be the probe-skipped fallback");
// This context asks the device for no features yet (no provider dispatches real WGSL): the
// device reports exactly what was requested, per `Device::features`' own contract, so this is
// device-truth agreeing with an intentionally empty request, not an unprobed default.
assert!(caps.features.is_empty(), "no feature was requested, so none should be reported enabled: {:?}", caps.features);
}
#[test]
fn real_device_upload_and_async_readback_round_trips_bytes_exactly() {
let Some(mut ctx) = real_context_or_skip("real_device_upload_and_async_readback_round_trips_bytes_exactly") else {
return;
};
let payload: Vec<u8> = (0..256u32).map(|b| b as u8).collect();
let handle = ctx.upload_buffer("round-trip", &payload).expect("upload_buffer on a real device");
assert_eq!(ctx.buffer_len(handle).expect("buffer_len"), payload.len());
// Exercise request_read + poll_reads directly (the primitive every backend implements),
// not just the read_buffer convenience, so the async shape itself is under test.
let request = ctx.request_read(handle).expect("request_read");
let mut got = None;
// Non-blocking poll_reads() in a bounded loop, exercising the exact primitive a worker's own
// message/poll loop would call; read_buffer_convenience (a separate test) covers the blocking
// path. The bound is generous for a software rasterizer on a 256-byte buffer, never relying
// on wall-clock sleeps.
for _ in 0..1_000_000 {
if let Some(outcome) = ctx.poll_reads().into_iter().find(|o| o.request == request) {
got = Some(outcome.result.expect("map_async + Device::poll round trip"));
break;
}
}
assert_eq!(got.expect("the real device never completed the mapped read within the bounded poll loop"), payload);
}
#[test]
fn real_device_read_buffer_convenience_blocks_to_completion() {
let Some(mut ctx) = real_context_or_skip("real_device_read_buffer_convenience_blocks_to_completion") else {
return;
};
let handle = ctx.upload_buffer("blocking-read", b"craft-gpu-wgpu").expect("upload_buffer");
assert_eq!(ctx.read_buffer(handle).expect("read_buffer"), b"craft-gpu-wgpu".to_vec());
}
/// RFC-0022 requirement 2's "representative jobs": the same `craft-gpu-providers` CPU stand-ins
/// `craft-runtime` dispatches against the null context in CI also run, unmodified, against a
/// real device, through the same `&mut dyn GpuContext` seam.
#[test]
fn shared_providers_run_against_a_real_device_through_the_same_seam_as_the_null_context() {
let Some(mut ctx) = real_context_or_skip("shared_providers_run_against_a_real_device_through_the_same_seam_as_the_null_context") else {
return;
};
let echo = EchoProvider;
let input = ctx.upload_buffer("echo-in", b"xy").expect("upload_buffer");
let job = GpuJob { provider_id: "craft.test.echo".into(), params: GpuJobParams(b"a".to_vec()), inputs: vec![input], outputs: vec![] };
let out = echo.run(&mut ctx, &job).expect("craft.test.echo on a real device");
assert_eq!(out.data.as_deref(), Some(b"axy".as_slice()));
let composite = PremulCompositeProvider;
let dst = ctx.upload_buffer("dst", &[0, 255, 0, 255]).expect("upload dst");
let src = ctx.upload_buffer("src", &[0, 0, 255, 128]).expect("upload src");
let job =
GpuJob { provider_id: "craft.composite.premul".into(), params: GpuJobParams(b"w:1,h:1".to_vec()), inputs: vec![dst, src], outputs: vec![] };
let out = composite.run(&mut ctx, &job).expect("craft.composite.premul on a real device");
let bytes = ctx.read_buffer(out.outputs[0]).expect("read composite output off a real device");
assert_eq!(bytes, vec![0, 127, 128, 255]);
let readback = ReadbackProvider;
let rgba = ctx.upload_buffer("rgba", &[10, 20, 30, 40]).expect("upload rgba");
let job = GpuJob { provider_id: "craft.readback".into(), params: GpuJobParams(b"w:1,h:1,fmt:u8".to_vec()), inputs: vec![rgba], outputs: vec![] };
let out = readback.run(&mut ctx, &job).expect("craft.readback fmt:u8 on a real device");
let bytes = ctx.read_buffer(out.outputs[0]).expect("read readback output off a real device");
assert_eq!(bytes, vec![10, 20, 30, 40]);
}
/// RFC-0022 requirement 1's device-loss half: a stated fault, not a panic, and a documented
/// recovery. `Backing`/`DeviceBacking` are crate-private, so this test reaches `ctx.backing`
/// directly to force the one cause it can trigger deterministically (`device.destroy()`) rather
/// than waiting on a real driver reset.
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
#[test]
fn device_destroy_surfaces_as_device_lost_and_stops_further_buffer_calls() {
use craft_gpu::GpuFault;
use crate::Backing;
let Some(mut ctx) = real_context_or_skip("device_destroy_surfaces_as_device_lost_and_stops_further_buffer_calls") else {
return;
};
assert!(!ctx.is_device_lost(), "a freshly created device must not already report loss");
if let Backing::Device(d) = &ctx.backing {
d.device.destroy();
// The lost closure can run during destroy() or on the next poll, depending on backend;
// give it the chance either way.
let _ = d.device.poll(wgpu::PollType::Poll);
}
// poll_reads() is the other place the trait docs promise this surfaces, for a caller that
// polls instead of issuing a buffer call first.
let _ = ctx.poll_reads();
assert!(ctx.is_device_lost(), "device.destroy() must surface through is_device_lost(), per the GpuContext trait docs");
let after = ctx.upload_buffer("after-loss", b"x");
assert!(matches!(after, Err(GpuFault::DeviceLost(_))), "a call after device loss must return GpuFault::DeviceLost, got {after:?}");
}
/// The staging path promises "same shape as `craft-gpu-null`": an empty upload is accepted and
/// reads back empty rather than being refused.
#[test]
fn staging_path_accepts_an_empty_buffer_and_reads_it_back_empty() {
let mut ctx = WgpuContext::with_caps(WorkerKind::Main, craft_gpu::DeviceCaps::default());
let handle = ctx.upload_buffer("empty", b"").expect("upload empty");
assert_eq!(ctx.buffer_len(handle).expect("buffer_len"), 0);
assert_eq!(ctx.read_buffer(handle).expect("read_buffer"), Vec::<u8>::new());
}
/// `read_buffer` must not eat completions that belong to another outstanding `request_read`.
#[test]
fn staging_read_buffer_keeps_another_outstanding_requests_completion_queued() {
let mut ctx = WgpuContext::with_caps(WorkerKind::Main, craft_gpu::DeviceCaps::default());
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
let b = ctx.upload_buffer("b", b"bb").expect("upload b");
let request_a = ctx.request_read(a).expect("request_read a");
assert_eq!(ctx.read_buffer(b).expect("read_buffer b"), b"bb".to_vec());
let outcomes = ctx.poll_reads();
assert_eq!(outcomes.len(), 1, "a's completion must survive b's read_buffer");
assert_eq!(outcomes[0].request, request_a);
assert_eq!(outcomes[0].result.as_deref(), Ok(b"aa".as_slice()));
}
/// CodeRabbit finding on lib.rs:228: if `request_adapter` succeeds but `request_device` fails,
/// the fallback must be the conservative fixed value, never a second, successful `probe_caps()`
/// adapter query -- which would report the adapter's advertised limits as if they came from a
/// granted device, for a context that holds none. Forcing `request_device` itself to fail is
/// hardware-dependent and not reliably reproducible in CI, so this tests the fallback value
/// `WgpuContext::new` falls back to directly: it must be the plain, fixed value, never one that
/// looks like a real probe result.
#[test]
fn the_no_device_fallback_caps_are_the_plain_fixed_value_not_a_probe_result() {
let caps = crate::probe_fallback("wgpu", "no-device");
assert_eq!(caps.backend_name, "wgpu");
assert_eq!(caps.device_name, "no-device");
assert_eq!(caps, craft_gpu::DeviceCaps { backend_name: "wgpu".into(), device_name: "no-device".into(), ..craft_gpu::DeviceCaps::default() });
}
/// CodeRabbit finding on lib.rs:299: an allocation failure used to be able to reach wgpu's
/// default uncaptured-error handler, which panics. An error scope around buffer creation now
/// converts that into a `GpuFault` instead. A genuine out-of-memory condition is not reliably
/// reproducible in CI (it depends on how much free VRAM the host actually has), so this is the
/// regression half: the added error scope must not misfire on an entirely ordinary allocation,
/// across both the create scope and the write scope that now follows it (see the next doc
/// comment for why those are two separate scopes rather than one spanning both calls).
#[test]
fn upload_buffer_succeeds_normally_with_the_allocation_error_scope_in_place() {
let Some(mut ctx) = real_context_or_skip("upload_buffer_succeeds_normally_with_the_allocation_error_scope_in_place") else {
return;
};
let handle = ctx.upload_buffer("scope-regression", b"ok").expect("a normal allocation must not report a false allocation error");
assert_eq!(ctx.read_buffer(handle).expect("read back"), b"ok".to_vec());
}
/// CodeRabbit finding on lib.rs:329 (upload_buffer) and lib.rs:404 (request_read): the original
/// code popped its single error scope only after write_buffer (respectively, after the copy and
/// its submission), so a failed create_buffer would leave an invalid buffer in play across the
/// later call that used it. write_buffer against an invalid buffer raises a VALIDATION error, a
/// kind the OutOfMemory-only scope never catches, so it would reach wgpu's default
/// uncaptured-error handler and panic there instead of surfacing as a `GpuFault` -- the same
/// crash the scope was added to prevent in the first place.
///
/// A genuine allocation failure is not reliably reproducible in CI (it depends on how much free
/// VRAM/host memory lavapipe actually has to give), so this cannot be a runtime test that forces
/// `create_buffer` to fail and then observes `write_buffer` never ran. What can be verified
/// honestly, and is verified here, is the ordering itself: `upload_buffer`'s source now pops the
/// create scope and returns on error strictly before it pushes the write scope or calls
/// `write_buffer`, and `request_read`'s source pops the staging-buffer create scope and returns
/// on error strictly before it creates the copy encoder or calls `queue.submit`. Both orderings
/// are asserted directly against the source text below rather than left as an unverified claim in
/// a comment; the success-path test above is the runtime half, proving the added scope split does
/// not misfire on the ordinary case.
#[test]
fn a_failed_allocation_scope_pop_is_ordered_strictly_before_the_call_that_would_use_the_buffer() {
let source = include_str!("lib.rs");
let upload_create_pop = source.find("create_scope.pop()").expect("upload_buffer must pop a create scope");
let upload_write_scope_push = source.find("let write_scope = d.device.push_error_scope").expect("upload_buffer must push a separate write scope");
assert!(
upload_create_pop < upload_write_scope_push,
"upload_buffer must check the create scope's result before it ever pushes the write scope or calls write_buffer"
);
let read_create_pop =
source.rfind("device reported an allocation error creating the staging buffer").expect("request_read must pop a create scope");
let read_copy_scope_push = source.rfind("let copy_scope = d.device.push_error_scope").expect("request_read must push a separate copy scope");
assert!(
read_create_pop < read_copy_scope_push,
"request_read must check the staging-buffer create scope's result before it ever pushes the copy scope or touches the encoder"
);
}
/// CodeRabbit finding on lib.rs:313: nothing released an uploaded buffer's resources, so the
/// buffer table (and the GPU memory behind it) could only ever grow. free_buffer must actually
/// make the handle behave as invalid afterward, and must not disturb any other handle's index.
#[test]
fn staging_free_buffer_invalidates_the_handle_without_shifting_others() {
let mut ctx = WgpuContext::with_caps(WorkerKind::Main, craft_gpu::DeviceCaps::default());
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
let b = ctx.upload_buffer("b", b"bb").expect("upload b");
ctx.free_buffer(a);
assert!(matches!(ctx.buffer_len(a), Err(craft_gpu::GpuFault::InvalidJob(_))), "a freed handle must behave as invalid");
assert_eq!(ctx.read_buffer(b).expect("b must be unaffected by freeing a"), b"bb".to_vec());
}
/// The same guarantee on a real device: freeing one handle must not disturb another's index or
/// its own buffer.
#[test]
fn real_device_free_buffer_invalidates_the_handle_without_shifting_others() {
let Some(mut ctx) = real_context_or_skip("real_device_free_buffer_invalidates_the_handle_without_shifting_others") else {
return;
};
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
let b = ctx.upload_buffer("b", b"bb").expect("upload b");
ctx.free_buffer(a);
assert!(matches!(ctx.buffer_len(a), Err(craft_gpu::GpuFault::InvalidJob(_))), "a freed handle must behave as invalid on a real device too");
assert_eq!(ctx.read_buffer(b).expect("b must be unaffected by freeing a"), b"bb".to_vec());
}
/// CodeRabbit finding on lib.rs:438: `queue.write_buffer` only records its copy in wgpu's
/// PendingWrites; without some submission to flush that queue, wgpu-core keeps the destination
/// buffer (and the staging buffer `write_buffer` made internally) alive on its own, so repeated
/// upload_buffer/free_buffer cycles would retain GPU allocations with nothing ever releasing
/// them. `upload_buffer` now flushes with an empty `queue.submit` right after its own
/// write_buffer call. This cannot assert freed VRAM directly (wgpu exposes no such counter), so
/// it instead proves the behavioral guarantee this fix is actually for: many upload/free cycles
/// in a row complete without panicking and without ever running out of handles, which is exactly
/// what an unbounded, unflushed retention would eventually threaten on a long-lived worker.
#[test]
fn real_device_upload_and_free_many_cycles_in_a_row_does_not_panic_or_leak_a_growing_table() {
let Some(mut ctx) = real_context_or_skip("real_device_upload_and_free_many_cycles_in_a_row_does_not_panic_or_leak_a_growing_table") else {
return;
};
for i in 0..256u32 {
let bytes = i.to_le_bytes();
let handle = ctx.upload_buffer("cycle", &bytes).expect("each upload in the cycle must succeed");
assert_eq!(ctx.read_buffer(handle).expect("read back this cycle's buffer"), bytes.to_vec());
ctx.free_buffer(handle);
}
}
/// Freeing a handle twice, or a handle that never existed, is a no-op: callers are not expected
/// to track whether they already freed one.
#[test]
fn free_buffer_is_a_harmless_no_op_when_repeated_or_given_an_unknown_handle() {
let mut ctx = WgpuContext::with_caps(WorkerKind::Main, craft_gpu::DeviceCaps::default());
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
ctx.free_buffer(a);
ctx.free_buffer(a);
ctx.free_buffer(craft_gpu::HandleId(999));
}
/// CodeRabbit finding on lib.rs:401: `poll_reads` can only attach a device-lost fault to a read
/// it has something to attach it to, so a caller whose event loop only polls, with nothing
/// outstanding, could never observe loss through it alone. `device_status` covers exactly that
/// gap: it is checked here with no buffer call and no pending read at all after the device is
/// destroyed.
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
#[test]
fn device_status_surfaces_loss_even_with_nothing_pending() {
use craft_gpu::GpuFault;
use crate::Backing;
let Some(ctx) = real_context_or_skip("device_status_surfaces_loss_even_with_nothing_pending") else {
return;
};
assert_eq!(ctx.device_status(), Ok(()), "a freshly created device must not already report loss");
if let Backing::Device(d) = &ctx.backing {
d.device.destroy();
let _ = d.device.poll(wgpu::PollType::Poll);
}
// No upload_buffer, no request_read, no poll_reads: device_status() alone must observe it.
assert!(matches!(ctx.device_status(), Err(GpuFault::DeviceLost(_))), "device.destroy() must surface through device_status() alone");
}
/// Same two guarantees on a real device: empty buffers round-trip (the readback resolves without
/// mapping, since wgpu refuses an empty map range) and `read_buffer` re-queues completions that
/// belong to another outstanding request.
#[test]
fn real_device_empty_buffer_and_interleaved_read_buffer_behave_like_staging() {
let Some(mut ctx) = real_context_or_skip("real_device_empty_buffer_and_interleaved_read_buffer_behave_like_staging") else {
return;
};
let empty = ctx.upload_buffer("empty", b"").expect("upload empty");
assert_eq!(ctx.buffer_len(empty).expect("buffer_len"), 0);
assert_eq!(ctx.read_buffer(empty).expect("read_buffer empty"), Vec::<u8>::new());
let a = ctx.upload_buffer("a", b"aa").expect("upload a");
let b = ctx.upload_buffer("b", b"bb").expect("upload b");
let request_a = ctx.request_read(a).expect("request_read a");
assert_eq!(ctx.read_buffer(b).expect("read_buffer b"), b"bb".to_vec());
let mut seen_a = false;
for _ in 0..1000 {
for outcome in ctx.poll_reads() {
if outcome.request == request_a {
assert_eq!(outcome.result.as_deref(), Ok(b"aa".as_slice()));
seen_a = true;
}
}
if seen_a {
break;
}
}
assert!(seen_a, "a's completion must still arrive through poll_reads after b's read_buffer");
}
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-gpu"
description = "Provider-neutral GPU traits, GpuJob envelope, and registry (no vendor IO)"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
serde_json = { workspace = true }
+36
View File
@@ -0,0 +1,36 @@
use serde::{Deserialize, Serialize};
/// Limits and labels reported to Settings UI and worker RPC (`GpuCaps`).
///
/// Per RFC-0022's acceptance requirements, a backend that has a device fills every field here
/// from that created device, never from the adapter it was created on: an adapter advertises more
/// than a device may grant (`required_features`/`required_limits` at `request_device` time narrow
/// both). `craft-gpu-wgpu` reports [`Default`]-shaped conservative values only on the defined
/// no-adapter path (no GPU present, the feature compiled out, or the `wasm32` worker-init gap
/// described in `docs/gpu-backends.md`), never as a stand-in for a real device's own caps.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeviceCaps {
pub backend_name: String,
pub device_name: String,
pub max_storage_buffer_binding_size: u64,
pub max_buffer_size: u64,
pub max_texture_dimension_2d: u32,
/// Feature names actually enabled on the created device (`wgpu::Features::iter_names` on
/// native wgpu), empty on backends with no device. A fast path gates on membership here,
/// never on what the adapter merely advertised.
#[serde(default)]
pub features: Vec<String>,
}
impl Default for DeviceCaps {
fn default() -> Self {
Self {
backend_name: "null".into(),
device_name: "null".into(),
max_storage_buffer_binding_size: 128 * 1024 * 1024,
max_buffer_size: 256 * 1024 * 1024,
max_texture_dimension_2d: 8192,
features: Vec::new(),
}
}
}
+11
View File
@@ -0,0 +1,11 @@
use crate::{DeviceCaps, GpuFault};
/// Split `data` into contiguous slices no larger than [`DeviceCaps::max_storage_buffer_binding_size`].
pub fn chunk_buffer<'a>(caps: &DeviceCaps, data: &'a [u8]) -> Result<Vec<&'a [u8]>, GpuFault> {
let max = usize::try_from(caps.max_storage_buffer_binding_size)
.map_err(|_| GpuFault::Operation("max_storage_buffer_binding_size exceeds host address space".into()))?;
if max == 0 {
return Err(GpuFault::Operation("max_storage_buffer_binding_size must be non-zero".into()));
}
Ok(data.chunks(max).collect())
}
+128
View File
@@ -0,0 +1,128 @@
use crate::{DeviceCaps, GpuFault, HandleId};
/// Where the context was created (main thread vs worker).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum WorkerKind {
Main,
DedicatedWorker,
SharedWorker,
}
/// Opaque in-flight readback request handed out by [`GpuContext::request_read`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct ReadRequest(pub u64);
/// One completed (or failed) readback, delivered by [`GpuContext::poll_reads`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ReadOutcome {
pub request: ReadRequest,
pub handle: HandleId,
pub result: Result<Vec<u8>, GpuFault>,
}
/// Device/queue abstraction implemented by `craft-gpu-wgpu` and `craft-gpu-null`.
///
/// ## Device loss
///
/// A context can lose its device at any time: a driver reset, OS-level eviction under memory
/// pressure, or an explicit `device.destroy()`. Device loss surfaces as a fault and never panics. It arrives
/// through [`GpuFault::DeviceLost`] from the next call that would otherwise touch the device.
/// It also arrives through [`poll_reads`](Self::poll_reads), letting a host's event loop observe
/// it even between buffer calls. Once a context has reported [`GpuFault::DeviceLost`], every
/// [`DeviceCaps`] it reported before that point is stale. The consumer's recovery, per RFC-0022,
/// is one of:
///
/// - fall back to the portable path (a [`DeviceCaps`]-gated path with no fast-path features, or a
/// different, CPU-backed [`GpuContext`]) for the rest of the session, or
/// - re-acquire a device, meaning construct a fresh [`GpuContext`], and re-probe
/// [`caps`](Self::caps) before resuming GPU jobs.
///
/// No backend here supports continuing to dispatch jobs against a context that has already
/// reported device loss, using caps read before the loss.
///
/// ## Readback
///
/// [`read_buffer`](Self::read_buffer) is a blocking convenience built on
/// [`request_read`](Self::request_read) and [`poll_reads`](Self::poll_reads): those two are the
/// primitives every backend implements directly, because WebGPU (and therefore native wgpu's
/// `buffer.map_async`) can only map a buffer asynchronously. The completion is delivered the same
/// way a `GpuJob` batch's outcome is delivered to a worker's host: queued, then collected on a
/// later poll, analogous to `craft-worker-host`'s `HostMessage::GpuJobs` being answered later by
/// `WorkerMessage::GpuBatchDone`.
///
/// Both bundled backends override `read_buffer`'s default body, since the default has nowhere
/// to put completions belonging to other outstanding requests: the null context takes only its
/// own completion, and the wgpu context re-queues the others while blocking efficiently on a
/// native device. On `wasm32` the wgpu context's only backing today is the in-memory staging
/// store, whose reads resolve synchronously and are served; only a read that did not resolve
/// synchronously returns [`GpuFault::Operation`] there, the refusal a future real device backing
/// will need, because a map on that target completes only via the browser's own event loop and
/// blocking for it would freeze the one thread that loop runs on. Callers on such a backing
/// drive `request_read` and `poll_reads` from the worker's own message loop. See
/// `docs/gpu-backends.md` for which backend does which.
pub trait GpuContext {
fn caps(&self) -> DeviceCaps;
fn worker_kind(&self) -> WorkerKind;
/// Register an opaque buffer blob; returns a handle for job graphs.
fn upload_buffer(&mut self, label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault>;
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault>;
/// Queue an asynchronous readback of `handle`. Completion is delivered by
/// [`poll_reads`](Self::poll_reads).
fn request_read(&mut self, handle: HandleId) -> Result<ReadRequest, GpuFault>;
/// Drain every read completed (or failed) since the last call. Also where a device-lost
/// fault surfaces for callers that are polling rather than issuing buffer calls. A context
/// that resolves reads synchronously (the null context; native wgpu with no device) may
/// resolve a request on the very next call after [`request_read`](Self::request_read).
///
/// This can only attach a device-lost fault to a read it has something to attach it to: when
/// nothing is outstanding, there is no [`ReadOutcome`] to fabricate one onto. A caller whose
/// event loop only polls, with no buffer calls and no outstanding read, uses
/// [`device_status`](Self::device_status) for that gap.
fn poll_reads(&mut self) -> Vec<ReadOutcome>;
/// Device loss observable independent of any specific read or buffer call, covering the gap
/// [`poll_reads`](Self::poll_reads) has when nothing is outstanding to attach the fault to.
/// The default is `Ok(())`: correct for any backend with no concept of device loss (the null
/// context; the staging/no-device path here). A backend that can lose a device overrides
/// this to report it.
fn device_status(&self) -> Result<(), GpuFault> {
Ok(())
}
/// Release a previously uploaded buffer's resources. A no-op, not an error, for a handle
/// that is already invalid or was already freed: callers are never required to track
/// whether they already freed one. A freed handle behaves as invalid afterward (the same
/// fault a never-issued handle would produce) from every other method on this trait.
///
/// Without this, a backend's buffer table -- and the memory behind it -- can only ever grow
/// for the context's lifetime: every `upload_buffer`, and every output buffer a provider's
/// job creates, adds an entry nothing removes. Repeated jobs then retain GPU (or host, for
/// the null context) memory long after every caller is done with every handle it created.
fn free_buffer(&mut self, handle: HandleId);
/// Blocking convenience for callers that need bytes now, such as the CPU-stand-in providers
/// in `craft-gpu-providers`. The default drains [`request_read`](Self::request_read) and
/// [`poll_reads`](Self::poll_reads) in a loop; see the trait docs for which backends honestly
/// support blocking here and which override this to fail instead of hanging.
///
/// The default body has nowhere to put completions that belong to other requests, so it
/// drops them: with the default body, never call this while another
/// [`request_read`](Self::request_read) is outstanding. A backend that stores completions
/// overrides this to put the other requests' outcomes back for the next
/// [`poll_reads`](Self::poll_reads); both bundled backends do.
fn read_buffer(&mut self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
let request = self.request_read(handle)?;
loop {
for outcome in self.poll_reads() {
if outcome.request == request {
return outcome.result;
}
}
}
}
}
+20
View File
@@ -0,0 +1,20 @@
use thiserror::Error;
/// Neutral GPU failure (no wgpu/WebGPU types cross this boundary).
#[derive(Clone, Debug, PartialEq, Eq, Error)]
pub enum GpuFault {
#[error("provider not registered: {0}")]
UnknownProvider(String),
#[error("invalid job: {0}")]
InvalidJob(String),
#[error("device unavailable: {0}")]
DeviceUnavailable(String),
/// The device was lost (driver reset, OS eviction, explicit `destroy()`) after it was
/// created. Every [`crate::DeviceCaps`] read before this point is stale: per
/// [`crate::GpuContext`]'s trait docs, fall back to the portable path or re-acquire a device
/// and re-probe caps. Never keep dispatching jobs against a context that reported this.
#[error("device lost: {0}")]
DeviceLost(String),
#[error("operation failed: {0}")]
Operation(String),
}
+28
View File
@@ -0,0 +1,28 @@
use serde::{Deserialize, Serialize};
/// Opaque resource handle in a job graph (resolved in the active [`GpuContext`](crate::GpuContext)).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct HandleId(pub u32);
/// Stable provider name (`craft.readback`, `effectcraft.compositor.frame`, …).
pub type ProviderId = String;
/// Versioned parameter blob; schema owned by the provider crate, not craft-gpu.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuJobParams(pub Vec<u8>);
/// Serializable work unit for generic worker dispatch.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuJob {
pub provider_id: ProviderId,
pub params: GpuJobParams,
pub inputs: Vec<HandleId>,
pub outputs: Vec<HandleId>,
}
/// Result handles or side-channel bytes (provider-defined interpretation).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuJobOutcome {
pub outputs: Vec<HandleId>,
pub data: Option<Vec<u8>>,
}
+27
View File
@@ -0,0 +1,27 @@
//! GPU traits, job envelope, and provider registry for Craft apps and the web runtime.
//!
//! Application crates register [`GpuProvider`] implementations; generic hosts dispatch
//! [`GpuJob`] values by [`ProviderId`] without importing app project types.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod caps;
mod chunk;
mod context;
mod error;
mod job;
mod provider;
mod readback;
mod registry;
#[cfg(test)]
mod tests;
pub use caps::DeviceCaps;
pub use chunk::chunk_buffer;
pub use context::{GpuContext, ReadOutcome, ReadRequest, WorkerKind};
pub use error::GpuFault;
pub use job::{GpuJob, GpuJobOutcome, GpuJobParams, HandleId};
pub use provider::GpuProvider;
pub use readback::{f16_rgba_to_f32_bytes, f16_to_f32, f16_to_f32_fast};
pub use registry::ProviderRegistry;
+8
View File
@@ -0,0 +1,8 @@
use crate::{GpuContext, GpuFault, GpuJob, GpuJobOutcome};
/// One GPU operation family. App and generic providers implement this trait.
pub trait GpuProvider {
fn id(&self) -> &'static str;
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault>;
}
+50
View File
@@ -0,0 +1,50 @@
/// IEEE half → f32 (FilmCraft `filmcraft_gpu::f16_to_f32`), for decoding `Rgba16Float` readbacks.
pub fn f16_to_f32(h: u16) -> f32 {
let sign = ((h & 0x8000) as u32) << 16;
let exp = ((h >> 10) & 0x1f) as u32;
let mant = (h & 0x03ff) as u32;
let bits = match exp {
0 => {
if mant == 0 {
sign
} else {
let b = 31 - mant.leading_zeros();
let frac = (mant ^ (1 << b)) << (23 - b);
sign | ((103 + b) << 23) | frac
}
}
0x1f => sign | 0x7f80_0000 | (mant << 13),
_ => sign | ((exp + 112) << 23) | (mant << 13),
};
f32::from_bits(bits)
}
/// [`f16_to_f32`] with a fast path for normal numbers and zeros; subnormals and non-finite values use [`f16_to_f32`].
#[inline]
pub fn f16_to_f32_fast(h: u16) -> f32 {
let u = u32::from(h);
let sign = (u & 0x8000) << 16;
let abs = u & 0x7fff;
if (0x0400..0x7c00).contains(&abs) {
f32::from_bits(sign | ((abs + (112 << 10)) << 13))
} else if abs == 0 {
f32::from_bits(sign)
} else {
f16_to_f32(h)
}
}
/// Expand little-endian RGBA f16 texels to RGBA f32 (row-major, no padding).
pub fn f16_rgba_to_f32_bytes(src: &[u8]) -> Result<Vec<u8>, usize> {
if !src.len().is_multiple_of(8) {
return Err(src.len());
}
let mut out = Vec::with_capacity(src.len() * 2);
for chunk in src.as_chunks::<8>().0 {
for pair in chunk.as_chunks::<2>().0 {
let v = f16_to_f32_fast(u16::from_le_bytes(*pair));
out.extend_from_slice(&v.to_le_bytes());
}
}
Ok(out)
}
+39
View File
@@ -0,0 +1,39 @@
use crate::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
/// Lookup table filled at worker/app init. Generic runtime code only talks to this.
pub struct ProviderRegistry {
providers: Vec<Box<dyn GpuProvider>>,
}
impl Default for ProviderRegistry {
fn default() -> Self {
Self::new()
}
}
impl ProviderRegistry {
pub fn new() -> Self {
Self { providers: Vec::new() }
}
pub fn register(&mut self, provider: Box<dyn GpuProvider>) {
self.providers.push(provider);
}
pub fn dispatch(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
for provider in &self.providers {
if provider.id() == job.provider_id {
return provider.run(ctx, job);
}
}
Err(GpuFault::UnknownProvider(job.provider_id.clone()))
}
/// Run every job in order and answer per job, in input order. A later job's failure never
/// discards outcomes earlier providers already produced: the caller replies per job and can
/// retry exactly the failed ones. A job whose inputs came from a failed earlier job fails
/// honestly on its own bad handles.
pub fn dispatch_batch(&self, ctx: &mut dyn GpuContext, jobs: &[GpuJob]) -> Vec<Result<GpuJobOutcome, GpuFault>> {
jobs.iter().map(|job| self.dispatch(ctx, job)).collect()
}
}
+128
View File
@@ -0,0 +1,128 @@
#![allow(clippy::expect_used)]
use crate::{
DeviceCaps, GpuContext, GpuFault, GpuJob, GpuJobParams, HandleId, ProviderRegistry, ReadOutcome, ReadRequest, WorkerKind, chunk_buffer,
f16_rgba_to_f32_bytes, f16_to_f32, f16_to_f32_fast,
};
struct MemContext {
caps: DeviceCaps,
/// `None` means freed (or never allocated): handles are stable indices, so a freed slot
/// cannot simply be removed without shifting every later handle's index.
buffers: Vec<Option<Vec<u8>>>,
next_request: u64,
ready: Vec<ReadOutcome>,
}
impl GpuContext for MemContext {
fn caps(&self) -> DeviceCaps {
self.caps.clone()
}
fn worker_kind(&self) -> WorkerKind {
WorkerKind::Main
}
fn upload_buffer(&mut self, _label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
let id = HandleId(u32::try_from(self.buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?);
self.buffers.push(Some(bytes.to_vec()));
Ok(id)
}
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
self.buffers.get(handle.0 as usize).and_then(Option::as_ref).map(Vec::len).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
fn request_read(&mut self, handle: HandleId) -> Result<ReadRequest, GpuFault> {
let bytes = self.buffers.get(handle.0 as usize).and_then(Option::as_ref).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))?;
let request = ReadRequest(self.next_request);
self.next_request = self.next_request.wrapping_add(1);
self.ready.push(ReadOutcome { request, handle, result: Ok(bytes) });
Ok(request)
}
fn poll_reads(&mut self) -> Vec<ReadOutcome> {
std::mem::take(&mut self.ready)
}
fn free_buffer(&mut self, handle: HandleId) {
if let Some(slot) = self.buffers.get_mut(handle.0 as usize) {
*slot = None;
}
}
}
fn mem_context() -> MemContext {
MemContext { caps: DeviceCaps::default(), buffers: Vec::new(), next_request: 0, ready: Vec::new() }
}
#[test]
fn unknown_provider_is_fault() {
let registry = ProviderRegistry::new();
let mut ctx = mem_context();
let job = GpuJob { provider_id: "missing".into(), params: GpuJobParams(Vec::new()), inputs: vec![], outputs: vec![] };
assert!(matches!(registry.dispatch(&mut ctx, &job), Err(GpuFault::UnknownProvider(_))));
}
#[test]
fn dispatch_batch_keeps_completed_outcomes_when_a_later_job_fails() {
struct Echo;
impl crate::GpuProvider for Echo {
fn id(&self) -> &'static str {
"test.echo"
}
fn run(&self, _ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<crate::GpuJobOutcome, GpuFault> {
Ok(crate::GpuJobOutcome { outputs: vec![], data: Some(job.params.0.clone()) })
}
}
let mut registry = ProviderRegistry::new();
registry.register(Box::new(Echo));
let mut ctx = mem_context();
let ok = GpuJob { provider_id: "test.echo".into(), params: GpuJobParams(b"first".to_vec()), inputs: vec![], outputs: vec![] };
let bad = GpuJob { provider_id: "missing".into(), params: GpuJobParams(Vec::new()), inputs: vec![], outputs: vec![] };
let ok2 = GpuJob { provider_id: "test.echo".into(), params: GpuJobParams(b"third".to_vec()), inputs: vec![], outputs: vec![] };
let results = registry.dispatch_batch(&mut ctx, &[ok, bad, ok2]);
assert_eq!(results.len(), 3, "one entry per job, in input order");
assert_eq!(results[0].as_ref().expect("first job succeeded").data.as_deref(), Some(b"first".as_slice()));
assert!(matches!(results[1], Err(GpuFault::UnknownProvider(_))));
assert_eq!(results[2].as_ref().expect("job after the failure still ran").data.as_deref(), Some(b"third".as_slice()));
}
#[test]
fn read_buffer_default_resolves_against_request_read_and_poll_reads() {
let mut ctx = mem_context();
let handle = ctx.upload_buffer("in", b"hello").expect("upload_buffer");
assert_eq!(ctx.read_buffer(handle).expect("read_buffer"), b"hello".to_vec());
}
#[test]
fn request_read_on_bad_handle_is_invalid_job() {
let mut ctx = mem_context();
assert!(matches!(ctx.request_read(HandleId(99)), Err(GpuFault::InvalidJob(_))));
}
#[test]
fn f16_to_f32_matches_fast_for_one() {
let h = 0x3c00u16;
assert!((f16_to_f32(h) - 1.0).abs() < 1e-6);
assert_eq!(f16_to_f32(h).to_bits(), f16_to_f32_fast(h).to_bits());
}
#[test]
fn f16_rgba_to_f32_bytes_expands_texels() {
let src = 0x3c00u16.to_le_bytes();
let mut raw = Vec::new();
for _ in 0..4 {
raw.extend_from_slice(&src);
}
let out = f16_rgba_to_f32_bytes(&raw).expect("decode");
assert_eq!(out.len(), 16);
assert!((f32::from_le_bytes(out[0..4].try_into().expect("le")) - 1.0).abs() < 1e-6);
}
#[test]
fn chunk_buffer_splits_on_storage_binding_limit() {
let caps = DeviceCaps { max_storage_buffer_binding_size: 4, ..DeviceCaps::default() };
let chunks = chunk_buffer(&caps, b"abcdef").expect("chunk_buffer");
assert_eq!(chunks, vec![&b"abcd"[..], &b"ef"[..]]);
}
+61
View File
@@ -0,0 +1,61 @@
# 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`](../crates/gpu/src/caps.rs) 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](./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::Buffer`s (`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`](../crates/gpu/src/context.rs):
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.
+18
View File
@@ -0,0 +1,18 @@
# GPU providers
Provider ids:
- `craft.*`: shared ops in **craft-gpu-providers** (no app crate deps)
- `craft.noop`, `craft.test.echo`, `craft.mask`, `craft.composite.premul`, `craft.readback`: registered by [`register_all()`](../crates/gpu-providers/src/lib.rs) for worker/runtime init
- `craft.mask`: CPU stand-in for FilmCraft mask composite until WGSL lands on wgpu
- `craft.composite.premul`: CPU premultiplied "over" (Normal path from `composite.wgsl`) until WGSL lands on wgpu
- `craft.readback`: CPU decode of staging buffers (`f16` RGBA → `f32`, or `fmt:u8` passthrough); uses [`chunk_buffer`](../crates/gpu/src/chunk.rs) against device caps and [`f16_to_f32*`](../crates/gpu/src/readback.rs) from **craft-gpu**
- `{app}.*`: registered by application wasm at init
Generic worker code must only call `ProviderRegistry::dispatch`: never import app gpu crates.
Dependency lint: **craft-gpu-providers** must not depend on `effectcraft-*`, `filmcraft-*`, or `*-engine`.
## Readback is async underneath; these providers don't see it
`GpuContext::read_buffer`, the method every provider above calls, is a blocking convenience over the trait's real primitives, `request_read` + `poll_reads` (see [gpu-backends.md](./gpu-backends.md)). Nothing in this crate changed for that. `craft-gpu-null` still resolves `read_buffer` immediately. `craft-gpu-wgpu`'s native path now does too, blocking on the device between polls. `crates/gpu-wgpu/src/tests.rs` runs these same providers (`craft.test.echo`, `craft.composite.premul`, `craft.readback`) against a real `WgpuContext` as well as the null one, when a real adapter is available (RFC-0022 requirement 2). A provider dispatching a real WGSL job will be the one that actually needs the non-blocking `request_read`/`poll_reads` shape directly. On `wasm32` today `read_buffer` serves the staging read, the only backing on that target. A read that did not resolve synchronously faults. A future real device backing there will refuse blocking outright, per `gpu-backends.md`.