WGSL front end
WGSL front end
github.com/go-gfx/wgsl is a pure-Go front
end for the WebGPU Shading Language: lexer,
parser, AST, printer, name resolution and type checking. It implements the
Candidate Recommendation Draft of 26 October 2026, with no cgo and only the
standard library.
m, err := wgsl.Parse(src) // *wgsl.Error with line and column on failure
text := wgsl.Print(m) // canonical WGSL; parses back to an equal AST
info, errs := wgsl.Check(m) // types, resolved names, struct layouts, entry points
err = wgsl.Validate(src) // Parse + Checkwgsl check shader.wgsl # exit 1 on the first invalid file
wgsl fmt -w shader.wgslWhy
- Silent failures. A guest shader that uses a reserved word (
meta) fails inside the browser without a usable message.Validaterejects it at the host, with the position. - Rewrites. Parse, change the AST, print valid WGSL again. This is the base for host-side limits such as bounding loop iterations.
- Other back ends.
Infocarries types, resolved declarations, struct layouts and entry points, so a WGSL to MSL emitter can be built on it.
Loop budgets
transform.LoopBudget (and wgsl transform) rewrites every loop, for and
while so that it counts iterations against a budget taken from an override
or a uniform u32. Past the budget the loop sets an atomic<u32> flag in a
storage buffer and breaks, so the host can tell a truncated run from a complete
one. The rewrite works on the parse tree only, never on the checker’s verdict.
It was run on an Apple GPU through Chrome WebGPU: a 10^8-iteration loop is cut
at the budget with the flag set, and a short loop is unchanged.
wgsl check is not yet a
security boundary: against the CTS it still wrongly accepts 88 invalid cases
(uniformity analysis is missing, so its 91,497 cases are skipped) and wrongly
rejects none of the 130,057 valid ones.Metal Shading Language
Since v0.5.0, package msl emits MSL for named functions of a checked
module, with every function they call and the structures they use:
m, _ := wgsl.Parse(src)
info, _ := wgsl.Check(m)
out, err := msl.Functions(m, info, "coverage")Scope. It covers plain functions over bool, i32, u32 and f32,
their vectors, and structures of those. Anything else is refused with its
position, never emitted approximately: entry points, module-scope variables,
loops, arrays, textures.
WGSL’s semantics, not Metal’s defaults. Each rule is sourced in the repository’s docs/MSL.md from the two specifications:
- fast math is off for the file;
- library calls are the
precise::ones; - signed
+,-,*and<<wrap; /and%give WGSL’s results for a zero divisor andMIN / -1;- shift counts are taken modulo 32, and
>>oni32is arithmetic; bitcastkeeps the bits.
Checked on the GPU. A test runs the emitted code on a Mac’s GPU against WGSL’s definitions computed in Go:
- 13 integer operations over 361 edge pairs;
clamp,length,select,abs,minandmax, with the subnormal flush-to-zero WGSL allows.
With Metal’s plain division, 1 / 0 comes back −1, where WGSL defines 1.
go-gfx/gpu2d’s Metal kernel generates its coverage functions this way.
SPIR-V
Since v0.9.0, spirv.Module(module, info, spirv.Options{}, entries...) emits
a SPIR-V 1.5 module (the Vulkan 1.2 environment) for compute entry points:
storage and uniform buffers of group 0, scalar and vector arithmetic, and
if, for, while and loop with break and continue. It is the subset a
fill kernel needs; the rest is refused as a *spirv.Error with its position.
docs/SPIRV.md lists
both, with the specification sections used.
- The numbers come from Khronos’s
spirv.core.grammar.json, through a generator. - A decoder checks every module on every platform (logical layout, structured control flow, the entry-point interface) and must refuse ten mutated ones.
spirv-valvalidates the output in CI. It has not been run on a GPU by this package; go-gfx/gpu2d’svulkanback-end runs it on lavapipe.
HLSL
Since v0.9.0, hlsl.Module(module, info, entries...) emits High-Level Shading
Language for Shader Model 5.0, to be compiled for cs_5_0 with D3DCompile
and D3DCOMPILE_IEEE_STRICTNESS: compute entry points, read storage arrays
as StructuredBuffer at t<binding>, read_write ones as
RWStructuredBuffer at u<binding>, a uniform as a cbuffer, WGSL’s integer
and float rules, and every float operation kept precise (no fused mad). It
takes the whole of gpu2d’s kernel.wgsl; the rest is refused as a
*hlsl.Error with its position
(docs/HLSL.md).
- The emitted kernel and 24 refusals are checked on every platform.
- On Direct3D 11 WARP (a nested module on
windows-latest, through go-mswin/d3d11) every emitted file is compiled byD3DCompileand the integer, float and conversion edge cases are held to WGSL’s definition; two break checks show the tests can fail. No GPU has run it.
Bounds
Limits caps the source size, the token count and the nesting depth. Deeply
nested input is refused with a positioned error; it does not overflow the
stack.
Conformance
The checker runs the W3C gpuweb CTS validation cases (webgpu:shader,validation,*),
executed under Node with the GPU stubbed so that the parametrised tests expand
to 384,053 distinct (source, verdict) pairs. See
CONFORMANCE.md
for the per-directory table.
Not yet implemented: uniformity analysis (those cases are counted as skipped),
alias analysis of pointer arguments, the buffer_view and swizzle_assignment
extensions.