naga-wasm
v30.2.0
Published
naga shader translator (wgpu) compiled to WebAssembly
Maintainers
Readme
naga-wasm
The naga shader translator from wgpu, compiled to WebAssembly.
Translate between WGSL, GLSL, SPIR-V, HLSL and MSL from JavaScript, in Node or the browser, without shelling out to the naga CLI.
- Frontends: WGSL, GLSL, SPIR-V
- Backends: WGSL, GLSL, SPIR-V, HLSL, MSL
Install
npm install naga-wasmUsage
import { translate } from "naga-wasm";
const glsl = translate({
from: "wgsl",
to: "glsl",
source: wgsl,
options: { version: "300 es", stage: "fragment", entryPoint: "main" },
});In Node the WebAssembly module loads on import. In the browser, call init()
once before anything else:
import { init, translate } from "naga-wasm";
await init();init() resolves the binary next to the module, which Vite and webpack 5
handle. To host it yourself, pass a URL, Response or bytes:
await init({ module_or_path: new URL("/naga_bg.wasm", location.href) });The binary is exported as naga-wasm/naga_bg.wasm.
Handles
translate is a shortcut for the handle API. Parse once to write several
outputs:
import { parseWgsl, validate, writeGlsl, writeHlsl } from "naga-wasm";
using module = parseWgsl(source);
using info = validate(module);
const glsl = writeGlsl(module, info, {
version: "300 es",
stage: "fragment",
entryPoint: "fs_main",
});
const hlsl = writeHlsl(module, info, { shaderModel: "6_0" });Handles hold WebAssembly memory. Release them with using or free().
| Function | Returns |
| ---------------------------------------------------------------------------------------- | ------------- |
| parseWgsl(source) | Module |
| parseGlsl(source, { stage, defines? }) | Module |
| parseSpirv(words) | Module |
| validate(module) | ModuleInfo |
| writeWgsl(module, info, { flags? }) | string |
| writeGlsl(module, info, { version, stage, entryPoint, bindingMap?, flags?, reflect? }) | string |
| writeHlsl(module, info, { shaderModel?, reflect? }) | string |
| writeMsl(module, info, { langVersion?, reflect? }) | string |
| writeSpirv(module, info, { flags? }) | Uint32Array |
parseSpirv accepts a Uint8Array or Uint32Array.
GLSL reflection
naga merges each texture and sampler pair into one sampler2D and wraps
uniform buffers in blocks, both with generated names. writeGlsl returns
those names mapped back to their WGSL bindings with reflect: true, so a
WebGL host can look up uniform locations:
const { code, reflection } = writeGlsl(module, info, {
version: "300 es",
stage: "fragment",
entryPoint: "fs_main",
reflect: true,
});
reflection.textures;
// { _group_1_binding_0_fs: { texture: { group: 1, binding: 0 }, sampler: { group: 1, binding: 1 } } }
reflection.uniforms;
// { Globals_block_0Fragment: { group: 0, binding: 0 } }bindingMap assigns explicit layout(binding = N) slots on GLSL versions
that support them:
writeGlsl(module, info, {
version: "310 es",
stage: "fragment",
entryPoint: "fs_main",
bindingMap: [{ group: 1, binding: 0, slot: 3 }],
});HLSL and MSL reflection
With reflect: true, writeHlsl and writeMsl return { code, reflection }
where reflection.entryPoints maps each WGSL entry point to its written name,
or to an error when naga could not write it:
const { reflection } = writeMsl(module, info, { reflect: true });
reflection.entryPoints;
// { vs_main: { name: "vs_main" }, fs_main: { name: "fs_main" } }reflect is deprecated on all three writers because { code, reflection }
becomes the default return in the next major. translate always returns only
the code.
Writer flags
flags override naga's writer flags one at a time and keep the rest at their
defaults:
writeGlsl(module, info, {
version: "300 es",
stage: "vertex",
entryPoint: "vs_main",
flags: { forcePointSize: true },
});Errors
Failures throw a NagaError with:
kind:"parse","validation"or"write"message: a one-line summaryformatted: naga's full report, including source spans
import { NagaError, parseWgsl } from "naga-wasm";
try {
parseWgsl("fn main( {");
} catch (error) {
if (error instanceof NagaError) console.error(error.formatted);
}error: expected identifier, found "{"
┌─ wgsl:1:10
│
1 │ fn main( {
│ ^ expected identifierVersioning
The major version follows naga's major version. Minor and patch releases
belong to this package. The bundled naga version is exported as nagaVersion
and noted in each release.
License
This project is licensed under either of:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
