wgpu-naga-bridge

wgpu-naga-bridge (wgpu-naga-bridge/) is a small crate that mediates between wgpu-core and naga. It was extracted from wgpu-core on 2026-03-13 to give the project room to swap or version-pin naga independently.

Purpose

• Translate user-supplied shader source (WGSL, GLSL, SPIR-V) into a validated naga::Module.
• Run naga::valid::Validator with the right Capabilities for the active device.
• Hand the validated module to whichever naga backend matches the active wgpu-hal backend (SPIR-V for Vulkan, MSL for Metal, HLSL for DX12, GLSL for GLES).
• Decouple wgpu-core from naga's API surface so naga can move at its own pace.

Directory layout

wgpu-naga-bridge/
├── Cargo.toml
└── src/                # small, single-purpose crate

How it works

graph LR
    UserSource["User shader<br/>(WGSL / GLSL / SPIR-V)"] --> Front[naga::front::*]
    Front --> Module[naga::Module]
    Module --> Validator[naga::valid::Validator]
    Validator --> ValidatedModule[ModuleInfo + Module]
    ValidatedModule --> Back[naga::back::*]
    Back -->|SPIR-V| Vk[Vulkan backend]
    Back -->|MSL| Mt[Metal backend]
    Back -->|HLSL| Dx[DX12 backend]
    Back -->|GLSL| Gl[GLES backend]

wgpu-core::pipeline::ShaderModule::create calls into wgpu-naga-bridge to run the front-validate-back pipeline. The bridge exposes the result in a form wgpu-core can store and later use to build RenderPipeline / ComputePipeline objects without touching naga's types directly.

Capabilities mapping

naga::valid::Capabilities is computed from the active wgt::Features. For example, Features::SHADER_F64 enables Capabilities::FLOAT64, Features::SUBGROUP* unlocks subgroup operations, and Features::SHADER_INT64 unlocks 64-bit integer support. The mapping lives in this crate; before March 2026 it was inside wgpu-core/src/validation.rs.

Why a separate crate

Three motivations:

1. API decoupling — naga's public types (naga::Module, naga::valid::ModuleInfo) are not part of wgpu's stable surface. Putting the integration in a separate crate lets wgpu-core consume only what wgpu-naga-bridge re-exports.
2. Version pinning — A future plan involves letting downstream embedders bring their own naga version. The bridge crate can implement the feature-detection logic against multiple naga versions.
3. Build time — naga's default-features = false plus selective feature enables are clearer when concentrated in one crate.

Integration points

• Above: wgpu-core::pipeline, wgpu-core::validation.
• Below: naga (with the relevant wgsl-in, glsl-in, spv-in, wgsl-out, spv-out, msl-out, hlsl-out, glsl-out features enabled).
• Adjacent: wgpu-types for Features/Limits to drive capability mapping.

Entry points for modification

• A new shader frontend — wire it through here so all of wgpu-core can use it without depending on the new naga module directly.
• A new feature → capability mapping — when adding a new Features::SHADER_* bit, add the corresponding Capabilities mapping in this crate, not in wgpu-core.
• A naga API change — adapt the bridge first; then bump the version in [workspace.dependencies].