gogpu/naga v0.21.0 - One Public API and Safe Zero Values

gogpu/naga v0.21.0 was published on 2 November 2026. It is described as the last planned breaking release before v1.0 (ADR-010): one public API in the shape of Rust naga, with safe zero values.

The full release notes and downloads are on the GitHub release page. This is a stable release, not a prerelease. The notes point to apidiff against v0.20.5 for the complete list of API changes. Only part of the notes is covered here, and the notes text was cut off before the end.

One entry point per stage ¶

Parsing, validation and code generation now follow the same call shape. Most of the old names are gone, so expect compile errors on upgrade.

  • Parsing: wgsl.Parse(src, wgsl.ParseOptions{}) returns *ir.Module, wgsl.ParseInfo and an error. Errors are *wgsl.ParseError with Format and Location. This replaces naga.Parse plus naga.Lower.
  • Validation: valid.Validate(m, valid.Options{...}) returns a valid.ModuleInfo. A zero Options means no optional capability. Capabilities and error types moved from ir to valid.
  • Backends: every backend exposes Compile(*ir.Module, Options) (out, TranslationInfo, error). For SPIRV that is spirv.Compile(m, spirv.Options{}). DefaultOptions() is now just the zero Options in every backend.
  • Overrides: naga.ProcessOverrides takes the ModuleInfo from your valid.Validate call and returns a new one.

Entry point selection is unified as *backend.EntryPointSelector{Stage, Name}, used in each backend’s Options.EntryPoint and in OverrideOptions. Many ir helpers and most SPIRV and HLSL builder internals are removed or made internal. If you wrapped those, plan for rewrites rather than renames.

This is the change most likely to alter output without a compile error. The project now matches Rust naga and wgpu-hal defaults.

  • Workgroup zero init is one option, ZeroInitializeWorkgroupMemory backend.ZeroInitializeWorkgroupMemoryMode, in spirv, msl, hlsl, glsl and dxil (P1-API-002). The zero value is ZeroInitWorkgroupPolyfill, which stores zero from generated code. ZeroInitWorkgroupNative is SPIRV only and an error elsewhere. ZeroInitWorkgroupNone leaves memory as is. The old msl and hlsl bools defaulted to skipping the zeroing that WebGPU requires.
  • ForceLoopBounding becomes SkipLoopBounding. SPIRV RayQueryInitTracking becomes SkipRayQueryInitTracking. An Options literal that left ForceLoopBounding unset now bounds loops.
  • spirv.UseStorageInputOutput16 stays opt in, because it needs device support.
  • Bounds checks use backend.BoundsCheckPolicies, where zero means Restrict.

The tradeoff is plain. Zero value callers get safer output and may see slightly slower shaders. Callers who want the old behavior must opt out explicitly.

Two cases that used to be silently patched now fail.

A nil binding map is still the identity mapping. A non nil map, even an empty one, must list every resource. Otherwise compile fails with an error wrapping backend.ErrMissingBinding, unless FakeMissingBindings is set. Per backend details from the notes:

  • SPIRV: RequireBindings is replaced by FakeMissingBindings. Before, a missing entry was silently kept at its WGSL binding.
  • MSL: a non nil PerEntryPointMap must cover every entry point that uses resources. Entry points left out used to get automatic slots.
  • GLSL: on versions with explicit bindings (desktop 4.20, ES 3.10) a missing resource was written without a binding and landed on the driver’s binding 0.
  • HLSL: a resource missing from a non nil map used to land at register(0, space0). A nil SamplerBufferBindingMap now places group G’s index buffer at register(tG, space255). A texture_external without an ExternalTextureBindingMap entry is an error.

Target versions are no longer raised for you. A request the target cannot satisfy returns *backend.VersionError{Space, Feature, Required, Requested}, which matches errors.Is(err, backend.ErrUnsupported). Pass the device’s real version.

The test side changed too, and it is mostly of interest to people running the corpus. A new case, calls/dce-live-local-chain-rt, covers the shape where naga 0.20.4’s DXIL output dropped blend math for two of three modes. It wrote zeros and the validator accepted it. That was fixed in 0.20.5. Corpus format 2 adds "skip": true for known failures such as GPU hangs or device loss. Format 1 cases still read.

  • Run apidiff against v0.20.5 first and work through the compile errors.
  • Audit every Options literal. Fields that flipped polarity compile cleanly and change behavior.
  • Audit non nil binding maps. Any map that omitted resources will now fail unless you set FakeMissingBindings.
  • Replace ir.SpacePushConstant (var<push_constant>) with ir.SpaceImmediate (var<immediate>). Later address space values shift by one, so do not persist the numeric values.
  • Use naga.Compact(m, naga.KeepUnusedYes) or naga.KeepUnusedNo in place of the ir.Compact* family.