diff --git a/Cargo.lock b/Cargo.lock index 1f8d8bbdf..95b9c5702 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/Cargo.toml b/Cargo.toml index 78a8d424b..c36973b4a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" diff --git a/crates/gpu-null/Cargo.toml b/crates/gpu-null/Cargo.toml new file mode 100644 index 000000000..adb907597 --- /dev/null +++ b/crates/gpu-null/Cargo.toml @@ -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 } diff --git a/crates/gpu-null/src/lib.rs b/crates/gpu-null/src/lib.rs new file mode 100644 index 000000000..a1992e474 --- /dev/null +++ b/crates/gpu-null/src/lib.rs @@ -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>>, + next_request: u64, + ready: Vec, +} + +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 { + 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 { + 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 { + 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 { + std::mem::take(&mut self.ready) + } + + fn read_buffer(&mut self, handle: HandleId) -> Result, 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::::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 + } +} diff --git a/crates/gpu-providers/Cargo.toml b/crates/gpu-providers/Cargo.toml new file mode 100644 index 000000000..b581b8112 --- /dev/null +++ b/crates/gpu-providers/Cargo.toml @@ -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 } diff --git a/crates/gpu-providers/src/composite.rs b/crates/gpu-providers/src/composite.rs new file mode 100644 index 000000000..aeda3ead0 --- /dev/null +++ b/crates/gpu-providers/src/composite.rs @@ -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 { + 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, + ] +} diff --git a/crates/gpu-providers/src/echo.rs b/crates/gpu-providers/src/echo.rs new file mode 100644 index 000000000..2fb356ceb --- /dev/null +++ b/crates/gpu-providers/src/echo.rs @@ -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 { + 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) }) + } +} diff --git a/crates/gpu-providers/src/lib.rs b/crates/gpu-providers/src/lib.rs new file mode 100644 index 000000000..c310a6c4f --- /dev/null +++ b/crates/gpu-providers/src/lib.rs @@ -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> { + 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); + } +} diff --git a/crates/gpu-providers/src/mask.rs b/crates/gpu-providers/src/mask.rs new file mode 100644 index 000000000..41957c1f7 --- /dev/null +++ b/crates/gpu-providers/src/mask.rs @@ -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 { + 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 }) + } +} diff --git a/crates/gpu-providers/src/noop.rs b/crates/gpu-providers/src/noop.rs new file mode 100644 index 000000000..4ce8aef91 --- /dev/null +++ b/crates/gpu-providers/src/noop.rs @@ -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 { + Ok(GpuJobOutcome { outputs: job.outputs.clone(), data: None }) + } +} diff --git a/crates/gpu-providers/src/params.rs b/crates/gpu-providers/src/params.rs new file mode 100644 index 000000000..7571897df --- /dev/null +++ b/crates/gpu-providers/src/params.rs @@ -0,0 +1,17 @@ +use craft_gpu::GpuJobParams; + +pub(crate) fn parse_u32(params: &GpuJobParams, prefix: &[u8]) -> Option { + // `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) +} diff --git a/crates/gpu-providers/src/readback.rs b/crates/gpu-providers/src/readback.rs new file mode 100644 index 000000000..1428fba58 --- /dev/null +++ b/crates/gpu-providers/src/readback.rs @@ -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 { + 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 }) + } +} diff --git a/crates/gpu-providers/src/tests.rs b/crates/gpu-providers/src/tests.rs new file mode 100644 index 000000000..650ae22e6 --- /dev/null +++ b/crates/gpu-providers/src/tests.rs @@ -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(¶ms, b""), None); + assert!(!crate::params::params_contain(¶ms, 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"); +} diff --git a/crates/gpu-wgpu/Cargo.toml b/crates/gpu-wgpu/Cargo.toml new file mode 100644 index 000000000..ecf45c62f --- /dev/null +++ b/crates/gpu-wgpu/Cargo.toml @@ -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 } diff --git a/crates/gpu-wgpu/src/lib.rs b/crates/gpu-wgpu/src/lib.rs new file mode 100644 index 000000000..1b26b3038 --- /dev/null +++ b/crates/gpu-wgpu/src/lib.rs @@ -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>>), +} + +#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))] +enum Backing { + Staging(Vec>>), + /// 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>, + /// 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>>, + pending: Vec, +} + +/// 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` 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>>>, +} + +#[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, +} + +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 { + #[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 { + 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 { + 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 { + 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 { + 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, 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, 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(), + )), + } + } +} diff --git a/crates/gpu-wgpu/src/tests.rs b/crates/gpu-wgpu/src/tests.rs new file mode 100644 index 000000000..6f0b74f88 --- /dev/null +++ b/crates/gpu-wgpu/src/tests.rs @@ -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 { + 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 = (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::::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::::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"); +} diff --git a/crates/gpu/Cargo.toml b/crates/gpu/Cargo.toml new file mode 100644 index 000000000..3928ad8be --- /dev/null +++ b/crates/gpu/Cargo.toml @@ -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 } diff --git a/crates/gpu/src/caps.rs b/crates/gpu/src/caps.rs new file mode 100644 index 000000000..75dcf173d --- /dev/null +++ b/crates/gpu/src/caps.rs @@ -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, +} + +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(), + } + } +} diff --git a/crates/gpu/src/chunk.rs b/crates/gpu/src/chunk.rs new file mode 100644 index 000000000..624637777 --- /dev/null +++ b/crates/gpu/src/chunk.rs @@ -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, 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()) +} diff --git a/crates/gpu/src/context.rs b/crates/gpu/src/context.rs new file mode 100644 index 000000000..8d8ccb0a2 --- /dev/null +++ b/crates/gpu/src/context.rs @@ -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, 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; + + fn buffer_len(&self, handle: HandleId) -> Result; + + /// Queue an asynchronous readback of `handle`. Completion is delivered by + /// [`poll_reads`](Self::poll_reads). + fn request_read(&mut self, handle: HandleId) -> Result; + + /// 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; + + /// 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, GpuFault> { + let request = self.request_read(handle)?; + loop { + for outcome in self.poll_reads() { + if outcome.request == request { + return outcome.result; + } + } + } + } +} diff --git a/crates/gpu/src/error.rs b/crates/gpu/src/error.rs new file mode 100644 index 000000000..794611efb --- /dev/null +++ b/crates/gpu/src/error.rs @@ -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), +} diff --git a/crates/gpu/src/job.rs b/crates/gpu/src/job.rs new file mode 100644 index 000000000..5f822b6f6 --- /dev/null +++ b/crates/gpu/src/job.rs @@ -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); + +/// 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, + pub outputs: Vec, +} + +/// Result handles or side-channel bytes (provider-defined interpretation). +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct GpuJobOutcome { + pub outputs: Vec, + pub data: Option>, +} diff --git a/crates/gpu/src/lib.rs b/crates/gpu/src/lib.rs new file mode 100644 index 000000000..58ba45ebd --- /dev/null +++ b/crates/gpu/src/lib.rs @@ -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; diff --git a/crates/gpu/src/provider.rs b/crates/gpu/src/provider.rs new file mode 100644 index 000000000..677351f57 --- /dev/null +++ b/crates/gpu/src/provider.rs @@ -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; +} diff --git a/crates/gpu/src/readback.rs b/crates/gpu/src/readback.rs new file mode 100644 index 000000000..ad02afbe8 --- /dev/null +++ b/crates/gpu/src/readback.rs @@ -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, 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) +} diff --git a/crates/gpu/src/registry.rs b/crates/gpu/src/registry.rs new file mode 100644 index 000000000..5e9d978de --- /dev/null +++ b/crates/gpu/src/registry.rs @@ -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>, +} + +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) { + self.providers.push(provider); + } + + pub fn dispatch(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result { + 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> { + jobs.iter().map(|job| self.dispatch(ctx, job)).collect() + } +} diff --git a/crates/gpu/src/tests.rs b/crates/gpu/src/tests.rs new file mode 100644 index 000000000..528b2e587 --- /dev/null +++ b/crates/gpu/src/tests.rs @@ -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>>, + next_request: u64, + ready: Vec, +} + +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 { + 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 { + 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 { + 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 { + 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 { + 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"[..]]); +} diff --git a/docs/gpu-backends.md b/docs/gpu-backends.md new file mode 100644 index 000000000..6e2246e91 --- /dev/null +++ b/docs/gpu-backends.md @@ -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>` 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. diff --git a/docs/gpu-providers.md b/docs/gpu-providers.md new file mode 100644 index 000000000..a1282b8a1 --- /dev/null +++ b/docs/gpu-providers.md @@ -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`.