oxicuda_webgpu/lib.rs
1//! OxiCUDA WebGPU backend — cross-platform GPU compute via `wgpu` and WGSL.
2//!
3//! Provides a [`WebGpuBackend`] that implements the [`oxicuda_backend::ComputeBackend`] trait
4//! from `oxicuda-backend`, using `wgpu` to target Vulkan, Metal, Direct3D 12,
5//! and the browser WebGPU API from a single Rust crate.
6//!
7//! # Quick Start
8//!
9//! ```rust,no_run
10//! use oxicuda_webgpu::WebGpuBackend;
11//! use oxicuda_backend::ComputeBackend;
12//!
13//! let mut backend = WebGpuBackend::new();
14//! backend.init().expect("WebGPU init failed");
15//!
16//! // Allocate 1 KiB on the GPU.
17//! let ptr = backend.alloc(1024).expect("alloc failed");
18//! backend.free(ptr).expect("free failed");
19//! ```
20//!
21//! # Architecture
22//!
23//! ```text
24//! ┌──────────────────────────────────────────┐
25//! │ WebGpuBackend │
26//! │ (implements ComputeBackend) │
27//! └──────────────┬───────────────────────────┘
28//! │
29//! ┌────────▼────────┐
30//! │ WebGpuDevice │ ← wgpu Instance + Adapter + Device + Queue
31//! └────────┬────────┘
32//! │
33//! ┌───────────▼────────────┐
34//! │ WebGpuMemoryManager │ ← buffer pool (u64 handle → wgpu::Buffer)
35//! └────────────────────────┘
36//! ```
37//!
38//! # WGSL Shader Generation
39//!
40//! The [`shader`] module provides helpers that produce WGSL source strings for
41//! common kernels (GEMM, element-wise ops, reductions). The [`shader_ext`]
42//! module adds transpose, row-wise softmax, Blelloch prefix scan, layer
43//! normalisation, warp-style subgroup reductions, and emulated-f64 arithmetic,
44//! while the [`fft`] module provides a radix-2 Cooley-Tukey FFT plan
45//! ([`WgslFftPlan`]) plus its butterfly shaders.
46//!
47//! # Dispatch Planning
48//!
49//! The [`planner`] module resolves workgroup sizes and dispatch grids from
50//! adapter [`Limits`] (auto-tuning, 2-D dispatch folding, 256-byte texture row
51//! alignment) — pure host-side arithmetic requiring no GPU.
52
53pub mod backend;
54pub mod device;
55pub mod error;
56pub mod fft;
57pub mod memory;
58pub mod planner;
59pub mod shader;
60pub mod shader_ext;
61
62// WASM target support — compiled on wasm32 or when the `wasm` feature is
63// enabled (so that native tests can exercise the module).
64#[cfg(any(target_arch = "wasm32", feature = "wasm"))]
65pub mod wasm;
66
67pub use backend::WebGpuBackend;
68pub use error::{WebGpuError, WebGpuResult};
69pub use fft::{FftDirection, WgslFftPlan};
70pub use planner::{DispatchGrid, Limits, Workgroup1D, Workgroup2D};
71pub use shader_ext::ScanKind;
72
73#[cfg(test)]
74mod naga_tests;