ironaccelerator_webgpu/lib.rs
1//! # `ironaccelerator-webgpu`
2//!
3//! WebGPU backend for the browser. This is the WASM compute path, and only
4//! that: on native targets, Vulkan, Metal, D3D12, and OpenGL reach the same
5//! hardware directly, so routing through a portability layer would add a
6//! translation step without adding coverage.
7//!
8//! ## How it works
9//!
10//! WebGPU adapter negotiation is asynchronous and
11//! [`Backend`](ironaccelerator_core::Backend) is not, so this crate does not
12//! negotiate. The host awaits `requestAdapter()` / `requestDevice()`, keeps the
13//! resulting `GPUDevice`, and describes it once via [`drv::bind_adapter`].
14//! From then on the adapter shows up in `Runtime::devices()` alongside every
15//! native backend.
16//!
17//! ```
18//! use ironaccelerator_webgpu::drv::{bind_adapter, AdapterInfo};
19//!
20//! // After `requestDevice()` resolves, from whatever binding layer you use:
21//! bind_adapter(AdapterInfo {
22//! vendor: "nvidia".into(),
23//! architecture: "ampere".into(),
24//! shader_f16: true,
25//! max_buffer_size: 1 << 28,
26//! ..Default::default()
27//! });
28//! ```
29//!
30//! ## What it deliberately does not do
31//!
32//! No buffers, pipelines, or dispatch. Those need a live `GPUDevice`, which
33//! stays with the host, and wrapping them would mean re-exporting a binding
34//! crate's types through this API — the coupling that made the previous
35//! `wgpu`-based version 98 transitive dependencies deep. The host already
36//! holds the device and can call WebGPU directly.
37//!
38//! Consequently this crate has no dependencies beyond
39//! [`ironaccelerator-core`](ironaccelerator_core) and compiles for every
40//! target, `wasm32-unknown-unknown` included, with no feature flags and no
41//! `--cfg` requirements.
42
43pub mod backend;
44pub mod drv;
45
46pub use backend::{WebGpuBackend, WEBGPU_BACKEND};
47pub use drv::{bind_adapter, bound_adapter, unbind_adapter, AdapterInfo};
48
49/// Register the WebGPU backend into the given registry. Idempotent.
50///
51/// Registering before [`bind_adapter`] is fine — the backend simply reports
52/// unavailable until a host binds one.
53pub fn register(reg: &mut ironaccelerator_core::BackendRegistry) {
54 reg.register(&WEBGPU_BACKEND);
55}