craft-gpu: add the GPU job traits and the shared providers.

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

None of these crates names a vendor or any app. craft-gpu defines GpuJob and ProviderRegistry. craft-gpu-null is an in-memory context for tests. craft-gpu-providers holds the shared craft.* WGSL providers. craft-gpu-wgpu is the wgpu backend, native and WebGPU.
This commit is contained in:
William Dunn committed 2026-11-07 08:38:36 -05:00
1 parent fd5e2feff6
commit 138f7b282f
28 files changed
+919

No files matched your search

Generated
+33
View File
@@ -924,6 +924,39 @@ dependencies = [
"craft-fonts-build",
]
[[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",
"pollster 0.4.0",
"wgpu",
]
[[package]]
name = "craft-i18n"
version = "0.1.0"
+7
View File
@@ -34,6 +34,10 @@ craft-font-catalog = { path = "crates/font-catalog" }
craft-font-manager = { path = "crates/font-manager" }
craft-font-store = { path = "crates/font-store" }
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-jpeg = { path = "crates/jpeg" }
craft-keymap = { path = "crates/keymap" }
@@ -62,6 +66,9 @@ serde_json = "1"
proptest = "1"
# All date/time conversion goes through chrono (no hand-rolled calendar code beyond the 400-year range extension; AGENTS.md).
chrono = { version = "0.4.45", default-features = false, features = ["std"] }
# Foundation crates for craft-gpu-wgpu. The versions match the ones the app repos already pin.
pollster = "0.4"
wgpu = { version = "30", default-features = false, features = ["std", "wgsl"] }
[workspace.lints.rust]
unsafe_code = "forbid"
+13
View File
@@ -0,0 +1,13 @@
[package]
name = "craft-gpu-null"
description = "In-memory GpuContext for CI and headless tests"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
craft-gpu = { workspace = true }
+46
View File
@@ -0,0 +1,46 @@
//! 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, WorkerKind};
/// In-memory buffer store; no GPU hardware required.
pub struct NullContext {
caps: DeviceCaps,
worker_kind: WorkerKind,
buffers: Vec<Vec<u8>>,
}
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(),
}
}
}
impl GpuContext for NullContext {
fn caps(&self) -> DeviceCaps {
self.caps.clone()
}
fn worker_kind(&self) -> WorkerKind {
self.worker_kind
}
fn upload_buffer(&mut self, _label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
let id = HandleId(u32::try_from(self.buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?);
self.buffers.push(bytes.to_vec());
Ok(id)
}
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
self.buffers.get(handle.0 as usize).map(|b| b.len()).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
fn read_buffer(&self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
self.buffers.get(handle.0 as usize).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
}
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "craft-gpu-providers"
description = "Shared GpuProvider implementations (composite, readback, …) — no app deps"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
craft-gpu = { workspace = true }
[dev-dependencies]
craft-gpu-null = { workspace = true }
+69
View File
@@ -0,0 +1,69 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
use crate::params::parse_u32;
/// CPU stand-in for FilmCraft `composite.wgsl` Normal/Dissolve premultiplied "over" until WGSL runs on wgpu.
pub struct PremulCompositeProvider;
impl GpuProvider for PremulCompositeProvider {
fn id(&self) -> &'static str {
"craft.composite.premul"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let width = parse_u32(&job.params, b"w:").unwrap_or(1).max(1) as usize;
let height = parse_u32(&job.params, b"h:").unwrap_or(1).max(1) as usize;
let len = width.saturating_mul(height).saturating_mul(4);
let (dst_h, src_h) = match job.inputs.as_slice() {
[a, b] => (a, b),
[a] => (a, a),
_ => {
return Err(GpuFault::InvalidJob("craft.composite.premul expects one or two RGBA8 inputs (backdrop, layer)".into()));
}
};
let dst_bytes = ctx.read_buffer(*dst_h)?;
let src_bytes = ctx.read_buffer(*src_h)?;
if dst_bytes.len() < len || src_bytes.len() < len {
return Err(GpuFault::InvalidJob("input buffer shorter than w*h*4".into()));
}
let mut out = vec![0u8; len];
for px in 0..width.saturating_mul(height) {
let i = px * 4;
let mut dst = straight_to_premul([dst_bytes[i], dst_bytes[i + 1], dst_bytes[i + 2], dst_bytes[i + 3]]);
let src = straight_to_premul([src_bytes[i], src_bytes[i + 1], src_bytes[i + 2], src_bytes[i + 3]]);
premul_over(&mut dst, src);
let straight = premul_to_straight(dst);
out[i..i + 4].copy_from_slice(&straight);
}
let handle = ctx.upload_buffer("craft.composite.premul.out", &out)?;
Ok(GpuJobOutcome { outputs: vec![handle], data: None })
}
}
/// Premultiplied `src` over premultiplied `dst` (`filmcraft_render` / `composite.wgsl` Normal path).
fn premul_over(dst: &mut [f32; 4], src: [f32; 4]) {
let k = 1.0 - src[3];
for c in 0..4 {
dst[c] = src[c] + dst[c] * k;
}
}
fn straight_to_premul(p: [u8; 4]) -> [f32; 4] {
let a = f32::from(p[3]) / 255.0;
let s = a / 255.0;
[f32::from(p[0]) * s, f32::from(p[1]) * s, f32::from(p[2]) * s, a]
}
fn premul_to_straight(p: [f32; 4]) -> [u8; 4] {
let a = p[3].clamp(0.0, 1.0);
if a <= f32::EPSILON {
return [0, 0, 0, 0];
}
let inv = 255.0 / a;
[
(p[0] * inv).round().clamp(0.0, 255.0) as u8,
(p[1] * inv).round().clamp(0.0, 255.0) as u8,
(p[2] * inv).round().clamp(0.0, 255.0) as u8,
(a * 255.0).round().clamp(0.0, 255.0) as u8,
]
}
+18
View File
@@ -0,0 +1,18 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
/// Concatenates job params with bytes from the first input handle (shared test / debug provider).
pub struct EchoProvider;
impl GpuProvider for EchoProvider {
fn id(&self) -> &'static str {
"craft.test.echo"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let mut data = job.params.0.clone();
if let Some(&h) = job.inputs.first() {
data.extend_from_slice(&ctx.read_buffer(h)?);
}
Ok(GpuJobOutcome { outputs: job.outputs.clone(), data: Some(data) })
}
}
+33
View File
@@ -0,0 +1,33 @@
//! Generic GPU providers extracted from app crates over time (craft-libs#7).
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod composite;
mod echo;
mod mask;
mod noop;
mod params;
mod readback;
#[cfg(test)]
mod tests;
use craft_gpu::{GpuProvider, ProviderRegistry};
pub use composite::PremulCompositeProvider;
pub use echo::EchoProvider;
pub use mask::MaskProvider;
pub use noop::NoopProvider;
pub use readback::ReadbackProvider;
/// Default shared providers for worker/runtime init (`craft.*` ids only).
pub fn register_all() -> Vec<Box<dyn GpuProvider>> {
vec![Box::new(NoopProvider), Box::new(EchoProvider), Box::new(MaskProvider), Box::new(PremulCompositeProvider), Box::new(ReadbackProvider)]
}
/// Register [`register_all`] providers into an existing registry.
pub fn register_all_into(registry: &mut ProviderRegistry) {
for provider in register_all() {
registry.register(provider);
}
}
+35
View File
@@ -0,0 +1,35 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
use crate::params::parse_u32;
/// CPU stand-in for FilmCraft mask composite until WGSL runs on wgpu.
pub struct MaskProvider;
impl GpuProvider for MaskProvider {
fn id(&self) -> &'static str {
"craft.mask"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let width = parse_u32(&job.params, b"w:").unwrap_or(1).max(1) as usize;
let height = parse_u32(&job.params, b"h:").unwrap_or(1).max(1) as usize;
let len = width.saturating_mul(height).saturating_mul(4);
let (base, mask) = match job.inputs.as_slice() {
[a, b] => (a, b),
[a] => (a, a),
_ => return Err(GpuFault::InvalidJob("craft.mask expects one or two RGBA inputs".into())),
};
let base_bytes = ctx.read_buffer(*base)?;
let mask_bytes = ctx.read_buffer(*mask)?;
if base_bytes.len() < len || mask_bytes.len() < len {
return Err(GpuFault::InvalidJob("input buffer shorter than w*h*4".into()));
}
let mut out = vec![0u8; len];
for i in 0..len {
let m = mask_bytes[i];
out[i] = ((u16::from(base_bytes[i]) * u16::from(m)) / 255) as u8;
}
let handle = ctx.upload_buffer("craft.mask.out", &out)?;
Ok(GpuJobOutcome { outputs: vec![handle], data: None })
}
}
+14
View File
@@ -0,0 +1,14 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
/// No-op dispatch for wiring tests; shared readback/composite providers live in sibling modules.
pub struct NoopProvider;
impl GpuProvider for NoopProvider {
fn id(&self) -> &'static str {
"craft.noop"
}
fn run(&self, _ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
Ok(GpuJobOutcome { outputs: job.outputs.clone(), data: None })
}
}
+13
View File
@@ -0,0 +1,13 @@
use craft_gpu::GpuJobParams;
pub(crate) fn parse_u32(params: &GpuJobParams, prefix: &[u8]) -> Option<u32> {
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 {
params.0.windows(needle.len()).any(|w| w == needle)
}
+38
View File
@@ -0,0 +1,38 @@
use craft_gpu::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider, chunk_buffer, f16_rgba_to_f32_bytes};
use crate::params::{params_contain, parse_u32};
/// CPU stand-in for accumulator/output readback (`read_accumulator` / `read_output` in FilmCraft gpu) until wgpu maps buffers.
pub struct ReadbackProvider;
impl GpuProvider for ReadbackProvider {
fn id(&self) -> &'static str {
"craft.readback"
}
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
let width = parse_u32(&job.params, b"w:").unwrap_or(0);
let height = parse_u32(&job.params, b"h:").unwrap_or(0);
let input = job.inputs.first().copied().ok_or_else(|| GpuFault::InvalidJob("craft.readback expects one input buffer".into()))?;
let raw = ctx.read_buffer(input)?;
let caps = ctx.caps();
let _chunks = chunk_buffer(&caps, &raw)?;
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 })
}
}
+127
View File
@@ -0,0 +1,127 @@
#![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-")),
"forbidden app dependency line: {t}"
);
}
}
#[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");
}
+31
View File
@@ -0,0 +1,31 @@
[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 }
+89
View File
@@ -0,0 +1,89 @@
//! wgpu-backed [`GpuContext`](craft_gpu::GpuContext).
//!
//! WebGPU on `wasm32`; native APIs when backend features are enabled. Adapter probing is
//! optional on native via the `adapter-probe` feature (pollster).
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use craft_gpu::{DeviceCaps, GpuContext, GpuFault, HandleId, WorkerKind};
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 = wgpu::Instance::default();
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,
}
}
/// Report device limits when an adapter is available; otherwise conservative defaults.
pub fn probe_caps() -> DeviceCaps {
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
{
return 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")
}
}
/// wgpu-backed context; buffer IO uses staging until full device wiring lands (craft-libs#6).
pub struct WgpuContext {
caps: DeviceCaps,
worker_kind: WorkerKind,
staging: Vec<Vec<u8>>,
}
impl WgpuContext {
pub fn new(worker_kind: WorkerKind) -> Self {
Self { caps: probe_caps(), worker_kind, staging: Vec::new() }
}
pub fn with_caps(worker_kind: WorkerKind, caps: DeviceCaps) -> Self {
Self { caps, worker_kind, staging: Vec::new() }
}
}
impl GpuContext for WgpuContext {
fn caps(&self) -> DeviceCaps {
self.caps.clone()
}
fn worker_kind(&self) -> WorkerKind {
self.worker_kind
}
fn upload_buffer(&mut self, _label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
let id = HandleId(u32::try_from(self.staging.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?);
self.staging.push(bytes.to_vec());
Ok(id)
}
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
self.staging.get(handle.0 as usize).map(|b| b.len()).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
fn read_buffer(&self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
self.staging.get(handle.0 as usize).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
}
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-gpu"
description = "Provider-neutral GPU traits, GpuJob envelope, and registry (no vendor IO)"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
[lints]
workspace = true
[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
serde_json = { workspace = true }
+23
View File
@@ -0,0 +1,23 @@
use serde::{Deserialize, Serialize};
/// Limits and labels reported to Settings UI and worker RPC (`GpuCaps`).
#[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,
}
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,
}
}
}
+11
View File
@@ -0,0 +1,11 @@
use crate::{DeviceCaps, GpuFault};
/// Split `data` into contiguous slices no larger than [`DeviceCaps::max_storage_buffer_binding_size`].
pub fn chunk_buffer<'a>(caps: &DeviceCaps, data: &'a [u8]) -> Result<Vec<&'a [u8]>, GpuFault> {
let max = usize::try_from(caps.max_storage_buffer_binding_size)
.map_err(|_| GpuFault::Operation("max_storage_buffer_binding_size exceeds host address space".into()))?;
if max == 0 {
return Err(GpuFault::Operation("max_storage_buffer_binding_size must be non-zero".into()));
}
Ok(data.chunks(max).collect())
}
+23
View File
@@ -0,0 +1,23 @@
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,
}
/// Device/queue abstraction implemented by `craft-gpu-wgpu` and `craft-gpu-null`.
pub trait GpuContext {
fn caps(&self) -> DeviceCaps;
fn worker_kind(&self) -> WorkerKind;
/// Register an opaque buffer blob; returns a handle for job graphs.
fn upload_buffer(&mut self, label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault>;
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault>;
fn read_buffer(&self, handle: HandleId) -> Result<Vec<u8>, GpuFault>;
}
+14
View File
@@ -0,0 +1,14 @@
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),
#[error("operation failed: {0}")]
Operation(String),
}
+28
View File
@@ -0,0 +1,28 @@
use serde::{Deserialize, Serialize};
/// Opaque resource handle in a job graph (resolved in the active [`GpuContext`](crate::GpuContext)).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct HandleId(pub u32);
/// Stable provider name (`craft.readback`, `effectcraft.compositor.frame`, …).
pub type ProviderId = String;
/// Versioned parameter blob; schema owned by the provider crate, not craft-gpu.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuJobParams(pub Vec<u8>);
/// Serializable work unit for generic worker dispatch.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuJob {
pub provider_id: ProviderId,
pub params: GpuJobParams,
pub inputs: Vec<HandleId>,
pub outputs: Vec<HandleId>,
}
/// Result handles or side-channel bytes (provider-defined interpretation).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuJobOutcome {
pub outputs: Vec<HandleId>,
pub data: Option<Vec<u8>>,
}
+27
View File
@@ -0,0 +1,27 @@
//! GPU traits, job envelope, and provider registry for Craft apps and the web runtime.
//!
//! Application crates register [`GpuProvider`] implementations; generic hosts dispatch
//! [`GpuJob`] values by [`ProviderId`] without importing app project types.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod caps;
mod chunk;
mod context;
mod error;
mod job;
mod provider;
mod readback;
mod registry;
#[cfg(test)]
mod tests;
pub use caps::DeviceCaps;
pub use chunk::chunk_buffer;
pub use context::{GpuContext, WorkerKind};
pub use error::GpuFault;
pub use job::{GpuJob, GpuJobOutcome, GpuJobParams, HandleId};
pub use provider::GpuProvider;
pub use readback::{f16_rgba_to_f32_bytes, f16_to_f32, f16_to_f32_fast};
pub use registry::ProviderRegistry;
+8
View File
@@ -0,0 +1,8 @@
use crate::{GpuContext, GpuFault, GpuJob, GpuJobOutcome};
/// One GPU operation family. App and generic providers implement this trait.
pub trait GpuProvider {
fn id(&self) -> &'static str;
fn run(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault>;
}
+50
View File
@@ -0,0 +1,50 @@
/// IEEE half → f32 (FilmCraft `filmcraft_gpu::f16_to_f32`), for decoding `Rgba16Float` readbacks.
pub fn f16_to_f32(h: u16) -> f32 {
let sign = ((h & 0x8000) as u32) << 16;
let exp = ((h >> 10) & 0x1f) as u32;
let mant = (h & 0x03ff) as u32;
let bits = match exp {
0 => {
if mant == 0 {
sign
} else {
let b = 31 - mant.leading_zeros();
let frac = (mant ^ (1 << b)) << (23 - b);
sign | ((103 + b) << 23) | frac
}
}
0x1f => sign | 0x7f80_0000 | (mant << 13),
_ => sign | ((exp + 112) << 23) | (mant << 13),
};
f32::from_bits(bits)
}
/// [`f16_to_f32`] with a fast path for normal numbers and zeros; subnormals and non-finite values use [`f16_to_f32`].
#[inline]
pub fn f16_to_f32_fast(h: u16) -> f32 {
let u = u32::from(h);
let sign = (u & 0x8000) << 16;
let abs = u & 0x7fff;
if (0x0400..0x7c00).contains(&abs) {
f32::from_bits(sign | ((abs + (112 << 10)) << 13))
} else if abs == 0 {
f32::from_bits(sign)
} else {
f16_to_f32(h)
}
}
/// Expand little-endian RGBA f16 texels to RGBA f32 (row-major, no padding).
pub fn f16_rgba_to_f32_bytes(src: &[u8]) -> Result<Vec<u8>, usize> {
if !src.len().is_multiple_of(8) {
return Err(src.len());
}
let mut out = Vec::with_capacity(src.len() * 2);
for chunk in src.as_chunks::<8>().0 {
for pair in chunk.as_chunks::<2>().0 {
let v = f16_to_f32_fast(u16::from_le_bytes(*pair));
out.extend_from_slice(&v.to_le_bytes());
}
}
Ok(out)
}
+39
View File
@@ -0,0 +1,39 @@
use crate::{GpuContext, GpuFault, GpuJob, GpuJobOutcome, GpuProvider};
/// Lookup table filled at worker/app init. Generic runtime code only talks to this.
pub struct ProviderRegistry {
providers: Vec<Box<dyn GpuProvider>>,
}
impl Default for ProviderRegistry {
fn default() -> Self {
Self::new()
}
}
impl ProviderRegistry {
pub fn new() -> Self {
Self { providers: Vec::new() }
}
pub fn register(&mut self, provider: Box<dyn GpuProvider>) {
self.providers.push(provider);
}
pub fn dispatch(&self, ctx: &mut dyn GpuContext, job: &GpuJob) -> Result<GpuJobOutcome, GpuFault> {
for provider in &self.providers {
if provider.id() == job.provider_id {
return provider.run(ctx, job);
}
}
Err(GpuFault::UnknownProvider(job.provider_id.clone()))
}
pub fn dispatch_batch(&self, ctx: &mut dyn GpuContext, jobs: &[GpuJob]) -> Result<Vec<GpuJobOutcome>, GpuFault> {
let mut out = Vec::with_capacity(jobs.len());
for job in jobs {
out.push(self.dispatch(ctx, job)?);
}
Ok(out)
}
}
+69
View File
@@ -0,0 +1,69 @@
#![allow(clippy::expect_used)]
use crate::{
DeviceCaps, GpuContext, GpuFault, GpuJob, GpuJobParams, HandleId, ProviderRegistry, WorkerKind, chunk_buffer, f16_rgba_to_f32_bytes, f16_to_f32,
f16_to_f32_fast,
};
struct MemContext {
caps: DeviceCaps,
buffers: Vec<Vec<u8>>,
}
impl GpuContext for MemContext {
fn caps(&self) -> DeviceCaps {
self.caps.clone()
}
fn worker_kind(&self) -> WorkerKind {
WorkerKind::Main
}
fn upload_buffer(&mut self, _label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
let id = HandleId(u32::try_from(self.buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?);
self.buffers.push(bytes.to_vec());
Ok(id)
}
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
self.buffers.get(handle.0 as usize).map(|b| b.len()).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
fn read_buffer(&self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
self.buffers.get(handle.0 as usize).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
}
}
#[test]
fn unknown_provider_is_fault() {
let registry = ProviderRegistry::new();
let mut ctx = MemContext { caps: DeviceCaps::default(), buffers: Vec::new() };
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 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"[..]]);
}
+14
View File
@@ -0,0 +1,14 @@
# 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` and fill real [`DeviceCaps`](../crates/gpu/src/caps.rs) (falls back when no GPU, e.g. CI).
- `native-vulkan`, `native-dx12`, `native-metal`, `native-gles` — enable the matching wgpu backend.
On `wasm32`, wgpu is built with the `webgpu` feature; caps probing stays browser-default until async init lands in the worker.
+14
View File
@@ -0,0 +1,14 @@
# 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`.