The Standard Library
wgsl_rs::std is the prelude for every #[wgsl] module. It provides WGSL
types, builtin functions, binding macros, entry-point attributes, and
runtime macros that bridge the Rust and WGSL worlds.
The glob import
Every #[wgsl] module begins with a glob import:
#![allow(unused)] fn main() { #[wgsl] pub mod my_shader { use wgsl_rs::std::*; // ... } }
The glob import is required. Only use wgsl_rs::std::* is recognized by
the transpiler; named imports from std are not supported inside #[wgsl]
modules.
What it provides
| Category | Examples | Chapter |
|---|---|---|
| WGSL types | Vec2f, Vec3f, Vec4f, Mat4f, Vec2u, ... | Scalars & Vectors, Vectors & Swizzles, Matrices |
| Constructors | vec2f(...), vec3f(...), vec4f(...), mat4x4f(...) | Matrix & Vector Functions |
| Numeric builtins | abs, sin, cos, pow, clamp, dot, cross, ... | Numeric Builtins |
| Matrix builtins | determinant, transpose | Matrix & Vector Functions |
| Texture functions | texture_sample, texture_load, texture_store, ... | Texture & Sampler Functions |
| Derivatives | dpdx, dpdy, fwidth, ... | Derivatives |
| Bitcast | bitcast_f32, bitcast_u32, bitcast_vec4i, ... | Bitcast |
| Packing | pack4x8snorm, unpack2x16float, ... | Packing |
| Synchronization | workgroup_barrier, storage_barrier, workgroup_uniform_load | Synchronization |
| Control | discard!() | discard!() |
| Binding macros | uniform!, storage!, workgroup!, texture!, sampler!, ptr! | Binding Macros |
| Entry-point attributes | #[vertex], #[fragment], #[compute] | Vertex / Fragment / Compute |
| Runtime macros | get!, get_mut!, discard!, slab_copy! | — |
| Marker types | PhantomData<T> | Generic Structs: PhantomData |
The Wgsl trait
Wgsl marks a type usable in a #[wgsl] module. Any type passed to a WGSL
function, stored in a uniform!/storage!, or returned from an entry point
must implement Wgsl. The macro and the runtime both rely on this trait to
marshal values between Rust and WGSL.
Related traits:
| Trait | Meaning |
|---|---|
Wgsl | A type usable in WGSL modules. |
WgslScalar | A scalar usable in WGSL: f32, i32, u32, bool, f16. |
WgslTextureScalar | A scalar usable as a texture texel format: f32, i32, u32 (not bool). |
WgslTextureScalar is a stricter subset of WgslScalar: only types that have
a corresponding WGSL texture format qualify, so bool is excluded.
CPU and WGSL agreement
Every builtin in wgsl_rs::std has a CPU implementation that mirrors WGSL
semantics. When you run a #[wgsl] module as ordinary Rust (e.g. under
cargo test), the builtins execute on the CPU; when the transpiler emits
WGSL, the same names map to native WGSL builtins. The
roundtrip tests verify the two worlds agree.