mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-22 18:41:27 +01:00
* craft-gpu: add the GPU job traits and the shared providers.
This carries over crates/gpu, crates/gpu-wgpu, crates/gpu-null, and crates/gpu-providers from the cut-down #160 branch, with minimal workspace wiring.
None of these crates names a vendor or any app. craft-gpu defines GpuJob and ProviderRegistry. craft-gpu-null is an in-memory context for tests. craft-gpu-providers holds the shared craft.* WGSL providers. craft-gpu-wgpu is the wgpu backend, native and WebGPU.
* craft-gpu: real device wiring, device loss and async readback (RFC-0022)
Addresses skylartaylor's review gate on #663 at 138f7b2. RFC-0022 has merged
since that review. This follows its acceptance requirements.
WgpuContext now requests a real device. DeviceCaps comes from that device,
reflecting the limits and features actually enabled on it. Buffers are real
wgpu::Buffer values when a device exists. The no-adapter case still degrades
to the same staging behavior as craft-gpu-null. The RFC defines that case
explicitly as the no-adapter path. Device loss is registered via
set_device_lost_callback. It surfaces as GpuFault::DeviceLost. It never
surfaces as a panic. The recovery is stated on GpuContext's trait docs.
GpuContext::read_buffer is no longer a required method. The primitives are
request_read and poll_reads. That mirrors craft-worker-host's own
HostMessage::GpuJobs to WorkerMessage::GpuBatchDone split one level down.
read_buffer stays as a default blocking convenience. It resolves immediately
on the null and staging paths. Native wgpu blocks on
Device::poll(wait_indefinitely). On wasm32 it returns GpuFault::Operation,
since a blocking wait there would freeze the one thread map_async's own
callback needs to run on.
crates/gpu-wgpu/src/tests.rs adds a real-backend suite, gated on
adapter-probe plus non-wasm32. It runs upload, readback and device-loss
tests against a real WgpuContext. It also runs three craft-gpu-providers
CPU-stand-in providers against that same real WgpuContext. It skips with a clear message when no adapter is present.
Verified against lavapipe with mesa-vulkan-drivers, using
--features adapter-probe,native-vulkan: every test passes. That run first
caught a real wgpu panic on buffer lengths that are not a multiple of 4,
COPY_BUFFER_ALIGNMENT. The fix pads real buffers transparently. Every caller
still sees exact, unpadded bytes.
docs/gpu-backends.md and docs/gpu-providers.md are updated to match,
including named consumers (the runtime slice first, then EffectCraft and
FilmCraft) and a device-ownership note for when egui's wgpu renderer is also
running.
* craft-gpu: buffer-size guards, empty-buffer parity, read_buffer keeps other completions
Answers the six findings in CodeRabbit review 5852678306 on PR #663.
upload_buffer on the device path refuses a padded size past the device's
max_buffer_size with GpuFault::InvalidJob before creating the buffer.
request_read guards its staging copy the same way. An oversized request
used to reach wgpu as a validation error on the device's error scope.
Empty buffers are accepted everywhere, matching craft-gpu-null and the
documented staging parity. The device path resolves an empty readback
immediately (wgpu refuses an empty map range). The blanket InvalidJob on
empty upload bytes is gone.
read_buffer no longer eats completions that belong to another
outstanding request. The wgpu override re-queues them for the next
poll_reads. The null context gains an override that takes only its own
completion. The trait's default-body contract is documented: with the
default body, do not interleave read_buffer with an outstanding
request_read.
ReadbackProvider validates the storage-binding cap directly. The old
chunk_buffer call allocated a Vec of slices only to drop it.
parse_u32 and params_contain refuse an empty prefix or needle.
windows(0) panics and the crate's rule is never to crash.
The manifest guard test now also rejects *-engine dependency lines, per
docs/gpu-providers.md.
* craft-gpu: per-job batch results, wasm staging reads resolve
Two findings CodeRabbit raised against the carried copy on PR 662, fixed here where the crates live. dispatch_batch now answers per job in input order. The old first-failure abort discarded outcomes earlier providers had already produced, leaving the caller nothing to reply with and no way to name the jobs worth retrying. A job fed by a failed predecessor fails honestly on its own bad handles. On wasm32 read_buffer now serves the staging backing, whose reads resolve synchronously. The backing on that target is always staging today. The refusal remains for a read that did not resolve synchronously, guarding the future wasm device backing where blocking would hang the tab.
* Add free_buffer and device_status to GpuContext.
Two CodeRabbit findings against crates/gpu-wgpu, both answered at the
trait level since craft-gpu-null has the exact same gap.
free_buffer (lib.rs:313). Every upload_buffer call added an entry to a
backend's buffer table. So did every output buffer a provider's job
created. Nothing ever removed one. Repeated jobs retained memory for
the whole lifetime of a context. The new required method releases a
buffer's resources. A freed handle behaves as invalid afterward, the
same fault an unknown handle already produces.
device_status (lib.rs:401). poll_reads can only attach a device-lost
fault to a read it has something to attach it to. A caller whose event
loop only polls, with nothing pending when loss happens, could never
observe it. The new method, default Ok(()), covers that gap directly;
a backend with no concept of device loss needs no override.
MemContext in this crate's own tests gets the same free_buffer shape as
craft-gpu-null, to keep it compiling under the new required method.
* Implement free_buffer for NullContext.
buffers moves from Vec<Vec<u8>> to Vec<Option<Vec<u8>>>. A handle is a
stable index. Freeing a slot replaces it with None. Removing it
instead would shift every later handle's index out from under its
caller. buffer_len and request_read now reject a freed index the same
way they already reject one that never existed.
Two new tests. One frees a handle and checks another's index and bytes
stay untouched. One frees a handle twice, and a handle that never
existed, and confirms both are a harmless no-op.
* Fix the no-device caps fallback, capture allocation failures, free buffers.
Four CodeRabbit findings against this crate.
The no-device fallback in WgpuContext::new called probe_caps() again
on request_device failure (lib.rs:228). A second, successful adapter
query would then report the adapter's advertised limits as if they
came from a granted device, for a context that holds none. It now
falls back to the plain, fixed caps probe_caps's own doc comment
already promises for that case.
Allocation failures during buffer creation used to reach wgpu's
default uncaptured-error handler (lib.rs:299). That handler panics.
The size check already in place only catches a request past the
device's advertised maximum. It says nothing about whether the device
can actually allocate that many bytes right now. An error scope around
both the output-buffer and the read-staging-buffer creation converts a
failure into a GpuFault instead.
free_buffer for WgpuContext (lib.rs:313) matches the Option-wrapped
shape just added to craft-gpu-null. Both backings, staging and real
device, release a buffer's resources and make the handle behave as
invalid afterward, without shifting any other handle's index.
device_status for WgpuContext (lib.rs:401) reports device loss through
the trait method just added to GpuContext. A caller that only polls
can now observe loss even with nothing pending.
New tests cover the fixed fallback value and a regression check that
the new allocation error scope does not misfire on an ordinary
allocation. They also cover free_buffer on both the staging and the
real-device path. One more covers device_status observing a destroyed
device with nothing outstanding. A genuine out-of-memory condition is not reliably
reproducible in CI; the allocation-failure test is the honest half of
that fix this can run.
* Fix the error-scope API call and run cargo fmt.
wgpu 30.0.1's Device has no pop_error_scope method. push_error_scope
returns an ErrorScopeGuard. pop() lives on that guard. Keep the guard
from push_error_scope and call pop() on it.
Also drops an unneeded mut on a test binding that never mutates its
context. Also runs cargo fmt on the lines the Option-wrapped buffer
changes touched.
* Drop a needless return clippy flagged in the adapter-probe lane.
The fallback branch in WgpuContext::new is the function's own tail
expression once the real-device branch above it has already returned
early. The explicit return on it was redundant.
* Run cargo fmt on the no-device fallback branch.
* Pop the OOM scope before the call that would misuse a failed buffer.
upload_buffer popped its scope only after write_buffer. request_read
popped its scope only after the copy and its submission. A buffer that
failed to create is invalid. Using an invalid buffer raises a VALIDATION
error that an OutOfMemory-only scope never catches. The default
uncaptured-error handler still panicked on a failed create even with the
scope in place. Pop right after create_buffer in both paths and return
before the buffer is used again, with a separate scope around the later
write or copy.
write_buffer only queues its copy into wgpu's PendingWrites. An upload
with no following submission kept the destination and staging buffers
alive inside wgpu-core until some other submit happened. upload_buffer now
flushes with an empty queue.submit right after its own write_buffer call.
A free_buffer right after an upload can now actually release the
allocation.
* Run cargo fmt on the new ordering test.
* craft-gpu-wgpu: correct the crate docs on wasm32 read_buffer
The staging backing serves wasm32 reads synchronously since the staging-reads fix. Only a read that did not complete synchronously faults. The crate-level summary still described the old unconditional fault.
* craft-gpu: sync the docs with the implemented readback behavior
Review asked for three corrections. The backends doc, the providers doc and the trait docs now state that both bundled backends override read_buffer's default body and that wasm32 serves the staging read, with a fault only for a read that did not resolve synchronously. The runtime follow-up paragraph now records that #662 consumed it. The software Vulkan container run is described as local testing. Hosted CI coverage and the pilot consumers' browser and hardware validation remain their own requirements. Em dashes swept from both docs per the house writing rules.
* has_device: say the answer once, in this file's own shape
Clippy 1.100.0 refuses the old body under `needless_bool`. The `if` returned a
bool literal with a bare `false` after it. The cfg attribute sat on the `if`
itself. The whole statement therefore vanished without the adapter-probe
feature.
Two cfg blocks replace it, one per configuration. `probe_caps` in the same
file already has that shape. `Backing::Device` exists only under that feature.
The clippy suggestion on its own would not compile.
The plain clippy leg never saw this. The line compiles only with adapter-probe
on. The all-features leg catches it, as does any workspace build that unifies
the feature in.
564 lines
29 KiB
Rust
564 lines
29 KiB
Rust
//! wgpu-backed [`GpuContext`](craft_gpu::GpuContext).
|
|
//!
|
|
//! WebGPU on `wasm32`; native APIs when backend features are enabled. With the `adapter-probe`
|
|
//! feature (native only, pollster) and at least one `native-*` backend feature,
|
|
//! [`WgpuContext::new`] requests a real device and builds [`DeviceCaps`] from what that device
|
|
//! actually enabled (`Device::limits()` / `Device::features()`), never from the adapter's
|
|
//! advertised maximum. Without a usable adapter (the features above are off, no GPU is present,
|
|
//! or on `wasm32` where real device creation needs the async worker-init path noted in
|
|
//! `docs/gpu-backends.md`), the context degrades to the same in-memory staging behavior as
|
|
//! `craft_gpu_null::NullContext` (not a dependency of this crate; named here only for context);
|
|
//! that is RFC-0022's defined no-adapter path, not an error.
|
|
//!
|
|
//! Readback is asynchronous end to end (`request_read` + `poll_reads`), because WebGPU can only
|
|
//! map a buffer that way. Native, with a real device, drives it with `Buffer::map_async` plus
|
|
//! `Device::poll`. The blocking `read_buffer` convenience (see
|
|
//! [`GpuContext`](craft_gpu::GpuContext)'s trait docs) blocks efficiently on native by polling
|
|
//! the device while it waits. On `wasm32` the backing is always the in-memory staging store
|
|
//! today, whose reads complete synchronously, and `read_buffer` serves them; only a read that
|
|
//! did not complete synchronously returns a fault there, since blocking would freeze the one
|
|
//! thread a real map's completion callback would need to run on.
|
|
|
|
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
|
|
|
|
use craft_gpu::{DeviceCaps, GpuContext, GpuFault, HandleId, ReadOutcome, ReadRequest, WorkerKind};
|
|
|
|
#[cfg(test)]
|
|
mod tests;
|
|
|
|
fn probe_fallback(backend_name: &str, device_name: &str) -> DeviceCaps {
|
|
DeviceCaps { backend_name: backend_name.into(), device_name: device_name.into(), ..DeviceCaps::default() }
|
|
}
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
fn probe_caps_native() -> DeviceCaps {
|
|
let instance = native::instance();
|
|
let adapter = match pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default())) {
|
|
Ok(adapter) => adapter,
|
|
Err(_) => return probe_fallback("wgpu", "no-adapter"),
|
|
};
|
|
let info = adapter.get_info();
|
|
let limits = adapter.limits();
|
|
DeviceCaps {
|
|
backend_name: format!("{:?}", info.backend),
|
|
device_name: info.name,
|
|
max_storage_buffer_binding_size: limits.max_storage_buffer_binding_size,
|
|
max_buffer_size: limits.max_buffer_size,
|
|
max_texture_dimension_2d: limits.max_texture_dimension_2d,
|
|
features: Vec::new(),
|
|
}
|
|
}
|
|
|
|
/// Adapter-advertised limits, when an adapter is available; otherwise conservative defaults. This
|
|
/// is the quick, device-free probe for UI surfaces that want a number before any context exists
|
|
/// (Settings). It is advisory only: these are the adapter's maximums, not a device's granted
|
|
/// ones. [`WgpuContext::caps`] is the authoritative, device-truth source once a context exists.
|
|
pub fn probe_caps() -> DeviceCaps {
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
{
|
|
probe_caps_native()
|
|
}
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), not(feature = "adapter-probe")))]
|
|
{
|
|
probe_fallback("wgpu", "probe-not-run")
|
|
}
|
|
|
|
#[cfg(target_arch = "wasm32")]
|
|
{
|
|
probe_fallback("webgpu", "browser")
|
|
}
|
|
}
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
mod native {
|
|
use std::sync::{Arc, Mutex};
|
|
|
|
use craft_gpu::{DeviceCaps, GpuFault};
|
|
|
|
use crate::{Backing, DeviceBacking};
|
|
|
|
/// Features this context asks a device for. No provider dispatches a real WGSL job on wgpu
|
|
/// yet (`craft-gpu-providers` ships CPU stand-ins, by design, until that lands); extend this
|
|
/// as real compute providers land, and it degrades gracefully regardless: see
|
|
/// [`create_device`].
|
|
const DESIRED_FEATURES: wgpu::Features = wgpu::Features::empty();
|
|
|
|
/// An instance over whichever native backends were compiled in (`native-vulkan`,
|
|
/// `native-dx12`, `native-metal`, `native-gles`), honoring `WGPU_BACKEND` when set, so the
|
|
/// same build can be pointed at a software Vulkan adapter (lavapipe/llvmpipe) in a local container run or a CI lane.
|
|
/// `new_without_display_handle` because this context never has a window (no surface is ever
|
|
/// requested); FilmCraft's own off-screen export device uses the same constructor for the
|
|
/// same reason (`filmcraft-gpu`'s `export_renderer.rs`, see `docs/gpu-backends.md`).
|
|
pub(crate) fn instance() -> wgpu::Instance {
|
|
let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
|
|
if let Some(backends) = wgpu::Backends::from_env() {
|
|
desc.backends = backends;
|
|
}
|
|
wgpu::Instance::new(desc)
|
|
}
|
|
|
|
/// Request a real device. `None` on the defined no-adapter path (no usable adapter): the
|
|
/// caller degrades to the staging backing, identical in shape to `craft-gpu-null`.
|
|
///
|
|
/// Never panics: `required_features` is intersected with what the adapter actually
|
|
/// advertises, and `required_limits` is set to the adapter's own limits (never more), so
|
|
/// `request_device`'s documented panics ("features/limits not supported by this adapter")
|
|
/// cannot trigger here.
|
|
pub(crate) fn create_device() -> Option<(DeviceCaps, Backing)> {
|
|
let instance = instance();
|
|
let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default())).ok()?;
|
|
let features = DESIRED_FEATURES & adapter.features();
|
|
let limits = adapter.limits();
|
|
let desc =
|
|
wgpu::DeviceDescriptor { label: Some("craft-gpu-wgpu"), required_features: features, required_limits: limits, ..Default::default() };
|
|
let (device, queue) = pollster::block_on(adapter.request_device(&desc)).ok()?;
|
|
|
|
let lost = Arc::new(Mutex::new(None));
|
|
{
|
|
let lost = Arc::clone(&lost);
|
|
device.set_device_lost_callback(move |reason, message| {
|
|
if let Ok(mut slot) = lost.lock() {
|
|
*slot = Some(GpuFault::DeviceLost(format!("{reason:?}: {message}")));
|
|
}
|
|
});
|
|
}
|
|
|
|
let info = device.adapter_info();
|
|
let device_limits = device.limits();
|
|
let caps = DeviceCaps {
|
|
backend_name: format!("{:?}", info.backend),
|
|
device_name: info.name,
|
|
max_storage_buffer_binding_size: device_limits.max_storage_buffer_binding_size,
|
|
max_buffer_size: device_limits.max_buffer_size,
|
|
max_texture_dimension_2d: device_limits.max_texture_dimension_2d,
|
|
features: device.features().iter_names().map(|(name, _)| name.to_string()).collect(),
|
|
};
|
|
let backing = Backing::Device(DeviceBacking { device, queue, buffers: Vec::new(), lost, pending: Vec::new() });
|
|
Some((caps, backing))
|
|
}
|
|
}
|
|
|
|
/// No real device: buffers live on the host, exactly like `craft-gpu-null`. RFC-0022's defined
|
|
/// degrade path for "no adapter" (feature off, no GPU present, or the `wasm32` async-init gap).
|
|
/// Each slot is `None` once freed (or never allocated): handles are stable indices, so a freed
|
|
/// slot cannot simply be removed without shifting every later handle's index.
|
|
#[cfg(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")))]
|
|
enum Backing {
|
|
Staging(Vec<Option<Vec<u8>>>),
|
|
}
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
enum Backing {
|
|
Staging(Vec<Option<Vec<u8>>>),
|
|
/// A real device. `DeviceCaps` was built from it, not from the adapter it came from.
|
|
Device(DeviceBacking),
|
|
}
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
struct DeviceBacking {
|
|
device: wgpu::Device,
|
|
queue: wgpu::Queue,
|
|
/// Each buffer paired with its true, caller-given byte length. wgpu requires every buffer
|
|
/// with copy usage to be sized in multiples of [`COPY_ALIGN`]; the buffer itself is padded to
|
|
/// that, but callers (`buffer_len`, `request_read`'s returned bytes) see the true length,
|
|
/// matching the staging path and `craft-gpu-null` exactly, with no padding visible. `None`
|
|
/// once freed: see the `Backing::Staging` doc for why the slot stays rather than shifting.
|
|
buffers: Vec<Option<(wgpu::Buffer, u64)>>,
|
|
/// Set by the device-lost callback registered in [`native::create_device`]; checked before
|
|
/// every call that would otherwise touch the (now invalid) device.
|
|
lost: std::sync::Arc<std::sync::Mutex<Option<GpuFault>>>,
|
|
pending: Vec<PendingRead>,
|
|
}
|
|
|
|
/// wgpu's `COPY_BUFFER_ALIGNMENT`: every buffer with copy usage, and every `write_buffer` /
|
|
/// `copy_buffer_to_buffer` size, must be a multiple of this (4 bytes). Uploading or reading back
|
|
/// a buffer length that doesn't land on this boundary (`b"xy"`, two bytes) is a validation error
|
|
/// on native wgpu, surfaced as a panic from inside `wgpu-core`'s own uncaptured-error path unless
|
|
/// padded first; `craft-gpu-null`'s plain `Vec<u8>` has no such constraint, so this padding is
|
|
/// purely an artifact of the real backend, kept invisible to every caller of this crate.
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
const COPY_ALIGN: u64 = 4;
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
struct PendingRead {
|
|
request: ReadRequest,
|
|
handle: HandleId,
|
|
staging: wgpu::Buffer,
|
|
/// True length to truncate the mapped (padded) bytes back down to.
|
|
true_len: u64,
|
|
state: std::sync::Arc<std::sync::Mutex<Option<Result<(), String>>>>,
|
|
}
|
|
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
fn resolve_pending(pending: PendingRead) -> ReadOutcome {
|
|
let PendingRead { request, handle, staging, true_len, state } = pending;
|
|
let result = match state.lock() {
|
|
Ok(mut guard) => match guard.take() {
|
|
Some(Ok(())) => match staging.get_mapped_range(0..true_len.next_multiple_of(COPY_ALIGN)) {
|
|
Ok(view) => {
|
|
let mut bytes = view.to_vec();
|
|
drop(view);
|
|
staging.unmap();
|
|
bytes.truncate(usize::try_from(true_len).unwrap_or(usize::MAX));
|
|
Ok(bytes)
|
|
}
|
|
Err(err) => Err(GpuFault::Operation(err.to_string())),
|
|
},
|
|
Some(Err(message)) => Err(GpuFault::Operation(message)),
|
|
None => Err(GpuFault::Operation("read_buffer: map_async callback has not run yet".into())),
|
|
},
|
|
Err(_) => Err(GpuFault::Operation("read_buffer: map state lock poisoned".into())),
|
|
};
|
|
ReadOutcome { request, handle, result }
|
|
}
|
|
|
|
/// wgpu-backed context. See the module docs for the real-device-vs-staging split.
|
|
pub struct WgpuContext {
|
|
caps: DeviceCaps,
|
|
worker_kind: WorkerKind,
|
|
backing: Backing,
|
|
next_request: u64,
|
|
ready: Vec<ReadOutcome>,
|
|
}
|
|
|
|
impl WgpuContext {
|
|
pub fn new(worker_kind: WorkerKind) -> Self {
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
{
|
|
if let Some((caps, backing)) = native::create_device() {
|
|
return Self { caps, worker_kind, backing, next_request: 0, ready: Vec::new() };
|
|
}
|
|
// request_adapter and/or request_device failed: fall back to the conservative
|
|
// fallback, never probe_caps(). probe_caps() would re-query the adapter here, and a
|
|
// second, successful adapter query would report the adapter's advertised limits as
|
|
// if they came from a granted device -- the exact thing probe_caps's own doc comment
|
|
// says caps() must never do for a context with no device.
|
|
Self { caps: probe_fallback("wgpu", "no-device"), worker_kind, backing: Backing::Staging(Vec::new()), next_request: 0, ready: Vec::new() }
|
|
}
|
|
#[cfg(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")))]
|
|
Self { caps: probe_caps(), worker_kind, backing: Backing::Staging(Vec::new()), next_request: 0, ready: Vec::new() }
|
|
}
|
|
|
|
/// Force the staging (no-device) path with caller-supplied caps. For tests, and for callers
|
|
/// that intentionally want the portable path (FilmCraft's `?webgl` / `?nogpuworkers`, per
|
|
/// `docs/pilot-filmcraft.md`) rather than a real device's own caps.
|
|
pub fn with_caps(worker_kind: WorkerKind, caps: DeviceCaps) -> Self {
|
|
Self { caps, worker_kind, backing: Backing::Staging(Vec::new()), next_request: 0, ready: Vec::new() }
|
|
}
|
|
|
|
/// True when this context holds a real device (`request_device` succeeded), false on the
|
|
/// staging/no-adapter path. Settings UI can use this to show "no GPU" honestly instead of
|
|
/// implying a device that was never created; tests use it to skip rather than fail when the
|
|
/// host genuinely has no usable adapter (see `crates/gpu-wgpu/src/tests.rs`).
|
|
pub fn has_device(&self) -> bool {
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
{
|
|
matches!(self.backing, Backing::Device(_))
|
|
}
|
|
|
|
#[cfg(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")))]
|
|
{
|
|
false
|
|
}
|
|
}
|
|
|
|
/// True once the device has reported loss. Every [`DeviceCaps`] read before this point is
|
|
/// stale; see [`GpuContext`]'s trait docs for the recovery this context expects.
|
|
pub fn is_device_lost(&self) -> bool {
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
if let Backing::Device(d) = &self.backing {
|
|
return d.lost.lock().map(|g| g.is_some()).unwrap_or(false);
|
|
}
|
|
false
|
|
}
|
|
|
|
fn take_lost_fault(&self) -> Option<GpuFault> {
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
if let Backing::Device(d) = &self.backing {
|
|
return d.lost.lock().ok().and_then(|g| g.clone());
|
|
}
|
|
None
|
|
}
|
|
}
|
|
|
|
impl GpuContext for WgpuContext {
|
|
fn caps(&self) -> DeviceCaps {
|
|
self.caps.clone()
|
|
}
|
|
|
|
fn worker_kind(&self) -> WorkerKind {
|
|
self.worker_kind
|
|
}
|
|
|
|
#[cfg_attr(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")), allow(unused_variables))]
|
|
fn upload_buffer(&mut self, label: &str, bytes: &[u8]) -> Result<HandleId, GpuFault> {
|
|
if let Some(fault) = self.take_lost_fault() {
|
|
return Err(fault);
|
|
}
|
|
match &mut self.backing {
|
|
Backing::Staging(buffers) => {
|
|
let id = u32::try_from(buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?;
|
|
buffers.push(Some(bytes.to_vec()));
|
|
Ok(HandleId(id))
|
|
}
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
Backing::Device(d) => {
|
|
let true_len = bytes.len() as u64;
|
|
let padded_len = true_len.next_multiple_of(COPY_ALIGN);
|
|
if padded_len > self.caps.max_buffer_size {
|
|
return Err(GpuFault::InvalidJob(format!(
|
|
"upload_buffer: {true_len} bytes (padded to {padded_len}) exceeds the device's max_buffer_size {}",
|
|
self.caps.max_buffer_size
|
|
)));
|
|
}
|
|
// The size check above only catches a request past the device's advertised
|
|
// maximum; it proves nothing about whether the device can actually allocate
|
|
// padded_len bytes right now (free VRAM varies). wgpu 30.0.1 sends an allocation
|
|
// failure to the default uncaptured-error handler, which panics, unless a scope
|
|
// captures it first. Pop this scope immediately, before write_buffer below ever
|
|
// touches `buffer`: a buffer that failed to create is invalid, and writing to an
|
|
// invalid buffer raises its own VALIDATION error, a kind this OutOfMemory-only
|
|
// scope does not catch, so it must reach the default handler and panic regardless
|
|
// of when this scope is popped. Checking right here is what keeps that from
|
|
// happening at all.
|
|
let create_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
|
|
let buffer = d.device.create_buffer(&wgpu::BufferDescriptor {
|
|
label: Some(label),
|
|
size: padded_len,
|
|
usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST,
|
|
mapped_at_creation: false,
|
|
});
|
|
if let Some(err) = pollster::block_on(create_scope.pop()) {
|
|
return Err(GpuFault::Operation(format!("upload_buffer: device reported an allocation error creating the buffer: {err}")));
|
|
}
|
|
// write_buffer makes its own staging allocation to carry `bytes` to the device, a
|
|
// second allocation that can also run out of memory; it gets its own scope rather
|
|
// than reusing the one already closed above.
|
|
let write_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
|
|
if padded_len == true_len {
|
|
d.queue.write_buffer(&buffer, 0, bytes);
|
|
} else {
|
|
let mut padded = bytes.to_vec();
|
|
padded.resize(usize::try_from(padded_len).unwrap_or(bytes.len()), 0);
|
|
d.queue.write_buffer(&buffer, 0, &padded);
|
|
}
|
|
// write_buffer only records the copy into wgpu's PendingWrites; wgpu-core flushes
|
|
// that queue at the sooner of the caller's next real command-buffer submission or
|
|
// the next map_async on an affected buffer, and keeps the buffer named by the
|
|
// write alive internally until then. Without a submission here, a free_buffer
|
|
// right after this call could never actually release the GPU allocation behind
|
|
// it, since nothing would ever flush PendingWrites to let it go. An empty submit
|
|
// is still a submission as far as that flush is concerned, so it is enough.
|
|
d.queue.submit(std::iter::empty());
|
|
if let Some(err) = pollster::block_on(write_scope.pop()) {
|
|
return Err(GpuFault::Operation(format!("upload_buffer: device reported an allocation error writing the buffer: {err}")));
|
|
}
|
|
let id = u32::try_from(d.buffers.len()).map_err(|_| GpuFault::Operation("too many buffers".into()))?;
|
|
d.buffers.push(Some((buffer, true_len)));
|
|
Ok(HandleId(id))
|
|
}
|
|
}
|
|
}
|
|
|
|
fn buffer_len(&self, handle: HandleId) -> Result<usize, GpuFault> {
|
|
if let Some(fault) = self.take_lost_fault() {
|
|
return Err(fault);
|
|
}
|
|
match &self.backing {
|
|
Backing::Staging(buffers) => {
|
|
buffers.get(handle.0 as usize).and_then(Option::as_ref).map(Vec::len).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))
|
|
}
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
Backing::Device(d) => {
|
|
d.buffers.get(handle.0 as usize).and_then(Option::as_ref).ok_or_else(|| GpuFault::InvalidJob("bad handle".into())).and_then(
|
|
|(_, true_len)| usize::try_from(*true_len).map_err(|_| GpuFault::Operation("buffer size exceeds host address space".into())),
|
|
)
|
|
}
|
|
}
|
|
}
|
|
|
|
fn request_read(&mut self, handle: HandleId) -> Result<ReadRequest, GpuFault> {
|
|
if let Some(fault) = self.take_lost_fault() {
|
|
return Err(fault);
|
|
}
|
|
match &mut self.backing {
|
|
Backing::Staging(buffers) => {
|
|
let bytes =
|
|
buffers.get(handle.0 as usize).and_then(Option::as_ref).cloned().ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))?;
|
|
let id = self.next_request;
|
|
self.next_request = self.next_request.wrapping_add(1);
|
|
let request = ReadRequest(id);
|
|
self.ready.push(ReadOutcome { request, handle, result: Ok(bytes) });
|
|
Ok(request)
|
|
}
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
Backing::Device(d) => {
|
|
let (buffer, true_len) =
|
|
d.buffers.get(handle.0 as usize).and_then(Option::as_ref).ok_or_else(|| GpuFault::InvalidJob("bad handle".into()))?;
|
|
let true_len = *true_len;
|
|
if true_len == 0 {
|
|
// An empty buffer has nothing to copy or map (wgpu refuses an empty map
|
|
// range); resolve it immediately, same as the staging path.
|
|
let id = self.next_request;
|
|
self.next_request = self.next_request.wrapping_add(1);
|
|
let request = ReadRequest(id);
|
|
self.ready.push(ReadOutcome { request, handle, result: Ok(Vec::new()) });
|
|
return Ok(request);
|
|
}
|
|
let copy_len = true_len.next_multiple_of(COPY_ALIGN);
|
|
if copy_len > self.caps.max_buffer_size {
|
|
return Err(GpuFault::Operation(format!(
|
|
"request_read: staging copy of {copy_len} bytes exceeds the device's max_buffer_size {}",
|
|
self.caps.max_buffer_size
|
|
)));
|
|
}
|
|
// Same reasoning as upload_buffer's error scope: an allocation failure for the
|
|
// read-staging buffer must become a GpuFault, not reach the default
|
|
// uncaptured-error handler and panic. Pop immediately, before copy_buffer_to_buffer
|
|
// below ever names `staging` as a copy destination: a staging buffer that failed
|
|
// to create is invalid, and copying into an invalid buffer raises its own
|
|
// VALIDATION error, a kind this OutOfMemory-only scope does not catch, so it must
|
|
// reach the default handler and panic regardless of when this scope is popped.
|
|
let create_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
|
|
let staging = d.device.create_buffer(&wgpu::BufferDescriptor {
|
|
label: Some("craft-gpu-wgpu.read-staging"),
|
|
size: copy_len,
|
|
usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
|
|
mapped_at_creation: false,
|
|
});
|
|
if let Some(err) = pollster::block_on(create_scope.pop()) {
|
|
return Err(GpuFault::Operation(format!("request_read: device reported an allocation error creating the staging buffer: {err}")));
|
|
}
|
|
// The copy and its submission get their own scope rather than reusing the one
|
|
// already closed above, same split as upload_buffer's create vs. write.
|
|
let copy_scope = d.device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
|
|
let mut encoder = d.device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("craft-gpu-wgpu.read-copy") });
|
|
encoder.copy_buffer_to_buffer(buffer, 0, &staging, 0, copy_len);
|
|
d.queue.submit(Some(encoder.finish()));
|
|
if let Some(err) = pollster::block_on(copy_scope.pop()) {
|
|
return Err(GpuFault::Operation(format!("request_read: device reported an allocation error copying the buffer: {err}")));
|
|
}
|
|
let state = std::sync::Arc::new(std::sync::Mutex::new(None));
|
|
{
|
|
let state = std::sync::Arc::clone(&state);
|
|
staging.map_async(wgpu::MapMode::Read, 0..copy_len, move |result| {
|
|
if let Ok(mut slot) = state.lock() {
|
|
*slot = Some(result.map_err(|e| e.to_string()));
|
|
}
|
|
});
|
|
}
|
|
let id = self.next_request;
|
|
self.next_request = self.next_request.wrapping_add(1);
|
|
let request = ReadRequest(id);
|
|
d.pending.push(PendingRead { request, handle, staging, true_len, state });
|
|
Ok(request)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Replaces the slot with `None` rather than removing it: handles are stable indices, and
|
|
/// removing would shift every later handle's index out from under its caller. Dropping a
|
|
/// `Some((wgpu::Buffer, _))` here releases that buffer's GPU-side allocation.
|
|
fn free_buffer(&mut self, handle: HandleId) {
|
|
match &mut self.backing {
|
|
Backing::Staging(buffers) => {
|
|
if let Some(slot) = buffers.get_mut(handle.0 as usize) {
|
|
*slot = None;
|
|
}
|
|
}
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
Backing::Device(d) => {
|
|
if let Some(slot) = d.buffers.get_mut(handle.0 as usize) {
|
|
*slot = None;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Covers the gap `poll_reads` has when nothing is pending: that method can only attach a
|
|
/// device-lost fault to a read it has something to attach it to, so a caller whose event
|
|
/// loop only polls, with no outstanding read, could never observe loss through it alone.
|
|
fn device_status(&self) -> Result<(), GpuFault> {
|
|
if let Some(fault) = self.take_lost_fault() {
|
|
return Err(fault);
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
#[cfg_attr(not(all(not(target_arch = "wasm32"), feature = "adapter-probe")), allow(unused_mut))]
|
|
fn poll_reads(&mut self) -> Vec<ReadOutcome> {
|
|
let mut outcomes = std::mem::take(&mut self.ready);
|
|
#[cfg(all(not(target_arch = "wasm32"), feature = "adapter-probe"))]
|
|
if let Backing::Device(d) = &mut self.backing {
|
|
if let Some(fault) = d.lost.lock().ok().and_then(|g| g.clone()) {
|
|
outcomes.extend(d.pending.drain(..).map(|p| ReadOutcome { request: p.request, handle: p.handle, result: Err(fault.clone()) }));
|
|
return outcomes;
|
|
}
|
|
let _ = d.device.poll(wgpu::PollType::Poll);
|
|
let mut remaining = Vec::with_capacity(d.pending.len());
|
|
for pending in d.pending.drain(..) {
|
|
let is_ready = pending.state.lock().map(|g| g.is_some()).unwrap_or(false);
|
|
if is_ready {
|
|
outcomes.push(resolve_pending(pending));
|
|
} else {
|
|
remaining.push(pending);
|
|
}
|
|
}
|
|
d.pending = remaining;
|
|
}
|
|
outcomes
|
|
}
|
|
|
|
#[cfg(not(target_arch = "wasm32"))]
|
|
fn read_buffer(&mut self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
|
|
let request = self.request_read(handle)?;
|
|
loop {
|
|
let mut matched = None;
|
|
let mut others = Vec::new();
|
|
for outcome in self.poll_reads() {
|
|
if outcome.request == request {
|
|
matched = Some(outcome.result);
|
|
} else {
|
|
others.push(outcome);
|
|
}
|
|
}
|
|
// Completions belonging to other outstanding requests go back on the queue for the
|
|
// caller's next poll_reads instead of being dropped.
|
|
self.ready.extend(others);
|
|
if let Some(result) = matched {
|
|
return result;
|
|
}
|
|
// Block on the GPU between polls instead of busy-spinning the CPU. A no-op when
|
|
// `backing` is `Staging` (nothing to wait for; the request already resolved above)
|
|
// or when wgpu is itself WebGPU under the hood, which self-polls.
|
|
#[cfg(feature = "adapter-probe")]
|
|
if let Backing::Device(d) = &self.backing {
|
|
let _ = d.device.poll(wgpu::PollType::wait_indefinitely());
|
|
}
|
|
}
|
|
}
|
|
|
|
/// On `wasm32` the backing is always the in-memory staging store today (real device
|
|
/// creation needs the async worker-init path and does not exist on this target yet), and a
|
|
/// staging read resolves synchronously, so serving it blocks nothing. The refusal below
|
|
/// guards the future wasm device backing: WebGPU can only map a buffer asynchronously, and
|
|
/// `wasm32` is single-threaded, so blocking on a real device would stop the only thread the
|
|
/// browser needs to run `map_async`'s own completion callback on, hanging the tab. Callers
|
|
/// on a device backing drive [`request_read`](GpuContext::request_read) and
|
|
/// [`poll_reads`](GpuContext::poll_reads) from the worker's message loop instead; see
|
|
/// `docs/gpu-backends.md`.
|
|
#[cfg(target_arch = "wasm32")]
|
|
fn read_buffer(&mut self, handle: HandleId) -> Result<Vec<u8>, GpuFault> {
|
|
let request = self.request_read(handle)?;
|
|
match self.ready.iter().position(|o| o.request == request) {
|
|
Some(i) => self.ready.remove(i).result,
|
|
None => Err(GpuFault::Operation(
|
|
"read_buffer on wasm32: the read did not resolve synchronously. Use request_read + poll_reads from the worker's message loop \
|
|
instead."
|
|
.into(),
|
|
)),
|
|
}
|
|
}
|
|
}
|