naga

README

naga

Pure Go Shader Compiler
WGSL to SPIR-V, MSL, GLSL, HLSL, and DXIL. Zero CGO.

_{Part of the GoGPU ecosystem}

---

Overview

naga is a shader compiler written entirely in Go. It compiles WGSL (WebGPU Shading Language) to multiple backend formats without requiring CGO or external dependencies.

Key Features

Category	Capabilities
Input	Full WGSL parser (120+ tokens), 48 short type aliases (vec3f, mat4x4f...), abstract constructors
Outputs	SPIR-V (checked with spirv-val in CI), MSL, GLSL, HLSL; DXIL — 172/237 IDxcValidator on the Rust naga corpus (experimental)
Compute	Storage buffers, workgroups, atomics, barriers, subgroup operations
Ray Tracing	Ray query types, acceleration structures, 7 ray query builtins
Compatibility	Tested against Rust naga's WGSL snapshot corpus (172 shaders, gfx-rs/wgpu 14328f49): every output is compared, and each known difference is recorded with its reason — see Rust Naga Compatibility
Build	Zero CGO, single binary

---

Features

• Pure Go — No CGO, no external dependencies
• WGSL Frontend — Full lexer and parser (120+ tokens), 48 short type aliases (vec3f, mat4x4f, etc.), abstract constructors (vec3(1,2,3))
• Rust Naga Compatibility — every IR, SPIR-V, MSL, GLSL and HLSL output is compared with Rust naga's on its 172-shader WGSL corpus; known differences are recorded per output with a reason. 28 own test shaders; 936 golden outputs
• IR — Complete intermediate representation (expressions, statements, types)
• Compute Shaders — Storage buffers, workgroup memory, @workgroup_size
• Atomic Operations — atomicAdd, atomicSub, atomicMin, atomicMax, atomicCompareExchangeWeak
• Barriers — workgroupBarrier, storageBarrier, textureBarrier
• Type Inference — Automatic type resolution for all expressions, including let bindings
• Type Deduplication — SPIR-V compliant unique type emission
• Array Initialization — array(1, 2, 3) shorthand with inferred type and size
• Texture Sampling — textureSample, textureLoad, textureStore, textureDimensions, textureGather, textureSampleCompare
• Swizzle Operations — Full vector swizzle support (.xyz, .rgba, .xxyy, etc.)
• Function Calls — OpFunctionCall support for modular WGSL shaders with helper functions
• SPIR-V Backend — Vulkan-compatible bytecode generation: integer div/mod safety wrappers, image bounds checking (Restrict/ReadZeroSkipWrite), ray query helpers, force loop bounding, workgroup zero-init polyfill, NonUniform decorations, capability-aware instruction emission
• MSL Backend — Metal Shading Language output for macOS/iOS, vertex pulling transform, external textures, function-scope workgroup declarations (no host setThreadgroupMemoryLength needed)
• GLSL Backend — OpenGL Shading Language for OpenGL 3.3+, ES 3.0+, dead code elimination, image bounds checking, version-aware layout(binding=N) emission (SupportsExplicitLocations for GL 4.2+/ES 3.1+), UniformInfo reflection for runtime binding fallback on older GL drivers
• HLSL Backend — High-Level Shading Language for DirectX 11/12
• DXIL Backend (experimental) — Direct DXIL generation from naga IR (172 of 237 entry points of the Rust naga test corpus pass IDxcValidator; 103 of 182 DXC roundtrip comparisons match exactly; gg production shaders: 45 of 50 entry points valid; visual: renders circles + text on D3D12). LLVM 3.7 bitcode with dx.op intrinsics, DXBC container. Vertex, fragment, compute, and mesh shaders (SM 6.0-6.5). CBV/SRV/UAV (read-only storage as SRV, read-write as UAV), atomics (i32/i64/f32 + image), barriers, ray query (35 intrinsics), wave/subgroup ops (13 intrinsics), texture sampling (8 variants), matrix scalarization, pack/unpack, helper functions. Optimization passes: DCE (mark-and-sweep), SROA (struct decomposition), mem2reg (SSA promotion), single-store local promotion, loadInput DCE (per-member backwards reachability), workgroup struct decomposition, function inlining (early-return wrapping), strength reduction (mul→shl, urem→and, sub→add), constant folding. Options.BindingMap for WGSL→DXIL (space, register) remap (wgpu root signature compatibility). Eliminates FXC/DXC dependency. dxil.Compile() API. ~50K LOC, 330+ unit tests. World's first Pure Go DXIL generator.
• Type Conversions — Scalar constructors f32(x), u32(y), i32(z) with correct SPIR-V opcodes
• Bitcast — bitcast<T>(expr) for reinterpreting bit patterns between types
• Warnings — Unused variable detection with _ prefix exception
• Validation — Type checking, semantic validation, function call argument type/count verification, @must_use enforcement, const_assert evaluation, @binding/@group pairing, array size validation, swizzle namespace enforcement, mandatory semicolons
• CLI Tool — nagac command-line compiler

---

Installation

go get github.com/gogpu/naga

Requirements: Go 1.25+

---

Usage

As Library

package main

import (
    "fmt"
    "log"

    "github.com/gogpu/naga"
)

func main() {
    source := `
@vertex
fn main(@builtin(vertex_index) idx: u32) -> @builtin(position) vec4<f32> {
    return vec4<f32>(0.0, 0.0, 0.0, 1.0);
}
`
    // Simple compilation
    spirv, err := naga.Compile(source)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Generated %d bytes of SPIR-V\n", len(spirv))
}

With Options

opts := naga.CompileOptions{
    SPIRVVersion: spirv.Version1_3,
    Debug:        true,   // Include debug names
    Validate:     true,   // Enable IR validation
}
spirv, err := naga.CompileWithOptions(source, opts)

CLI Tool

# Install
go install github.com/gogpu/naga/cmd/nagac@latest

# Compile shader
nagac shader.wgsl -o shader.spv

# With debug info
nagac -debug shader.wgsl -o shader.spv

# Show version
nagac -version

Development Tools

# SPIR-V disassembler (debugging shader compilation)
go install github.com/gogpu/naga/cmd/spvdis@latest
spvdis shader.spv

# DXIL validator — Pure Go wrapper around Microsoft IDxcValidator (Windows)
# First Pure Go integration with dxil.dll, zero CGO. Runs a three-layer
# defensive pre-check (DXBC structural + LLVM bitcode metadata walker)
# before handing blobs to IDxcValidator::Validate.
go install github.com/gogpu/naga/cmd/dxilval@latest
dxilval shader.dxil                       # validate a single container
dxilval --wgsl shader.wgsl                # compile through naga, then validate
dxilval --corpus snapshot/testdata/rust/in/wgsl/  # walk a directory, typed-error summary

# Texture shader compile tool (testing)
go install github.com/gogpu/naga/cmd/texture_compile@latest
texture_compile shader.wgsl

Multiple Backends

// Parse and lower WGSL to IR (shared across all backends)
ast, _ := naga.Parse(source)
module, _ := naga.Lower(ast)

// Generate SPIR-V (Vulkan)
spirvBytes, _ := naga.GenerateSPIRV(module, spirv.Options{})

// Generate MSL (Metal)
mslCode, _, _ := msl.Compile(module, msl.DefaultOptions())

// Generate GLSL (OpenGL)
glslCode, _, _ := glsl.Compile(module, glsl.DefaultOptions())

// Generate HLSL (DirectX 11/12)
hlslCode, _, _ := hlsl.Compile(module, hlsl.DefaultOptions())

// Generate DXIL (DirectX 12, SM 6.0 — experimental)
dxilBytes, _ := dxil.Compile(module, dxil.DefaultOptions())

Individual Stages

// Parse WGSL to AST
ast, err := naga.Parse(source)

// Lower AST to IR
module, err := naga.Lower(ast)

// Validate IR
errors, err := naga.Validate(module)

// Generate SPIR-V
spirvOpts := spirv.Options{Version: spirv.Version1_3, Debug: true}
spirvBytes, err := naga.GenerateSPIRV(module, spirvOpts)

Pipeline Constants

override declarations get their values per pipeline. Lower once, then process the module for each pipeline before any backend (as wgpu does):

module, err := naga.Lower(ast)

pipelineModule, err := naga.ProcessOverrides(module, naga.OverrideOptions{
    Constants:  naga.PipelineConstants{"gain": 1.5, "13": 64}, // name, or @id
    EntryPoint: &naga.EntryPointSelector{Stage: ir.StageCompute, Name: "main"},
})
// errors.Is(err, naga.ErrOverrideMissingValue), *naga.PipelineConstantError, ...

code, _, err := msl.Compile(pipelineModule, msl.DefaultOptions())

naga.Compile applies the defaults. A backend given a module that still uses overrides returns an error wrapping ir.ErrUnresolvedOverride.

---

Architecture

naga/                              ~323K LOC total
├── wgsl/              # WGSL frontend (~19.5K LOC)
│   ├── token.go       # Token types (120+)
│   ├── lexer.go       # Tokenizer
│   ├── ast.go         # AST types
│   ├── parser.go      # Recursive descent parser
│   └── lower.go       # AST → IR converter
├── ir/                # Intermediate representation (~6.5K LOC)
│   ├── ir.go          # Core types (Module, Type, Function)
│   ├── expression.go  # 30+ expression kinds
│   ├── statement.go   # 20+ statement kinds
│   ├── validate.go    # IR validation
│   ├── resolve.go     # Type inference
│   └── registry.go    # Type deduplication
├── spirv/             # SPIR-V backend (~10.8K LOC)
│   ├── spirv.go       # SPIR-V constants and opcodes
│   ├── block.go       # Block ownership model (Rust naga pattern)
│   ├── writer.go      # Binary module builder
│   ├── backend.go     # IR → SPIR-V translator
│   └── ray_query.go   # Ray query helper functions
├── msl/               # MSL backend (~14.2K LOC)
│   ├── backend.go     # Public API, Options, Compile()
│   ├── writer.go      # MSL code writer
│   ├── types.go       # Type generation
│   ├── expressions.go # Expression codegen
│   ├── statements.go  # Statement codegen
│   ├── functions.go   # Entry points and functions
│   └── keywords.go    # MSL/C++ reserved words
├── glsl/              # GLSL backend (~7.8K LOC)
│   ├── backend.go     # Public API, version targeting
│   ├── writer.go      # GLSL code writer
│   ├── types.go       # Type generation
│   ├── expressions.go # Expression codegen
│   ├── statements.go  # Statement codegen
│   └── keywords.go    # Reserved word escaping
├── hlsl/              # HLSL backend (~13.6K LOC)
│   ├── backend.go     # Public API, Options, Compile()
│   ├── writer.go      # HLSL code writer
│   ├── types.go       # Type generation
│   ├── expressions.go # Expression codegen
│   ├── statements.go  # Statement codegen
│   ├── storage.go     # Buffer/atomic operations
│   ├── functions.go   # Entry points with semantics
│   └── keywords.go    # HLSL reserved words
├── dxil/              # DXIL backend (~50K LOC, 172/237 IDxcValidator)
│   ├── dxil.go        # Public API: Compile(), DefaultOptions()
│   └── internal/      # All implementation internal
│       ├── bitcode/   # LLVM 3.7 bit-level writer
│       ├── module/    # DXIL module + bitcode serialization
│       ├── container/ # DXBC container (ISG1/OSG1/PSG1/PSV0/SFI0/HASH)
│       └── emit/      # naga IR → DXIL lowering (all shader stages)
├── naga.go            # Public API
└── cmd/
    ├── nagac/         # CLI compiler
    ├── spvdis/        # SPIR-V disassembler
    └── texture_compile/ # Texture shader testing

Supported WGSL Features

Types

• Scalars: f16, f32, f64, i32, u32, i64, u64, bool
• Vectors: vec2<T>, vec3<T>, vec4<T> (and short aliases: vec2f, vec3i, vec4u, etc.)
• Matrices: mat2x2<f32> ... mat4x4<f32> (and short aliases: mat2x2f, mat4x4f, etc.)
• Arrays: array<T, N>, array<T> (runtime-sized, storage buffers)
• Structs: struct { ... } (with constructor syntax: StructName(field1, field2))
• Atomics: atomic<u32>, atomic<i32>
• Textures: texture_2d<f32>, texture_3d<f32>, texture_cube<f32>, texture_depth_2d_array
• Samplers: sampler, sampler_comparison
• Binding arrays: binding_array<T, N>
• Ray tracing: acceleration_structure, ray_query
• Abstract constructors: vec3(1,2,3), mat2x2(...), array(...) (without explicit template parameters)
• Type aliases: alias FVec3 = vec3<f32>;

Shader Stages

• @vertex — Vertex shaders with @builtin(position) output
• @fragment — Fragment shaders with @location(N) outputs
• @compute — Compute shaders with @workgroup_size(X, Y, Z)

Bindings

• @builtin(position), @builtin(vertex_index), @builtin(instance_index)
• @builtin(global_invocation_id) — Compute shader invocation ID
• @location(N) — Vertex attributes and fragment outputs
• @group(G) @binding(B) — Resource bindings

Address Spaces

• var<uniform> — Uniform buffer
• var<storage, read> — Read-only storage buffer
• var<storage, read_write> — Read-write storage buffer
• var<workgroup> — Workgroup shared memory

Statements

• Variable declarations: var, let, const
• Override declarations: @id(N) override name: type = default;
• Compile-time assertions: const_assert expr;
• Control flow: if, else, for, while, loop, switch, case, default
• Loop control: break, continue, break if (continuing blocks)
• Functions: return, discard
• Assignment: =, +=, -=, *=, /=

Built-in Functions (100+)

• Math: abs, min, max, clamp, saturate, sign, fma, modf, frexp, ldexp, quantizeToF16
• Trigonometric: sin, cos, tan, asin, acos, atan, atan2, sinh, cosh, tanh, asinh, acosh, atanh
• Angle: radians, degrees
• Exponential: exp, exp2, log, log2, pow, sqrt, inverseSqrt
• Decomposition: ceil, floor, round, fract, trunc
• Geometric: dot, cross, length, distance, normalize, faceForward, reflect, refract, outerProduct
• Interpolation: mix, step, smoothstep
• Matrix: transpose, determinant, inverse
• Relational: all, any, isnan, isinf
• Bit: countTrailingZeros, countLeadingZeros, countOneBits, reverseBits, extractBits, insertBits, firstTrailingBit, firstLeadingBit
• Packing: pack4x8snorm, pack4x8unorm, pack2x16snorm, pack2x16unorm, pack2x16float, pack4xI8, pack4xU8, pack4xI8Clamp, pack4xU8Clamp, unpack4x8snorm, unpack4x8unorm, unpack2x16snorm, unpack2x16unorm, unpack2x16float, unpack4xI8, unpack4xU8
• Selection: select
• Derivatives: dpdx, dpdy, fwidth, dpdxCoarse, dpdyCoarse, fwidthCoarse, dpdxFine, dpdyFine, fwidthFine
• Atomic: atomicAdd, atomicSub, atomicMin, atomicMax, atomicAnd, atomicOr, atomicXor, atomicExchange, atomicCompareExchangeWeak
• Barriers: workgroupBarrier, storageBarrier, textureBarrier, subgroupBarrier
• Subgroup: subgroupBallot, subgroupAll, subgroupAny, subgroupAdd/Mul/Min/Max/And/Or/Xor, subgroupBroadcast/First, subgroupShuffle/XOR/Up/Down, quadSwap/Broadcast
• Ray Query: rayQueryInitialize, rayQueryProceed, rayQueryGetCommittedIntersection, rayQueryGetCandidateIntersection, rayQueryTerminate
• Uniform Load: workgroupUniformLoad
• Array: arrayLength

---

Status

Current Version: See CHANGELOG.md for release history.

Backend	Status	Target Platform
SPIR-V	✅ Stable, spirv-val in CI	Vulkan
MSL	✅ Stable	Metal (macOS/iOS)
GLSL	✅ Stable, version-aware binding	OpenGL 3.3+, ES 3.0+
HLSL	✅ Stable	DirectX 11/12
DXIL	172/237 IDxcValidator (Rust naga corpus), 103/182 DXC golden	DirectX 12 (SM 6.0-6.5, experimental)

See ROADMAP.md for detailed development plans.

Test Coverage

~60% overall (62K tracked lines). 12/18 packages at ≥80%. Enterprise-quality tests with output verification, edge cases, regression protection, and hand-crafted IR for specialized paths.

Package	Coverage
internal/textutil, dxil/module	100%
internal/backend	96.6%
dxil/passes (dce/mem2reg/sroa)	83-93%
ir, glsl, wgsl/parser, dxil/bitcode/container/viewid	80-84%
spirv	76.5%
hlsl	70.6%
internal/registry	75.2%
wgsl/lower	65.3%
msl	64.2%

Architecture

All backends follow the DXIL internal package pattern — implementation in internal/codegen/, thin public API with real types (not aliases). Zero panics in error paths.

---

References

• WGSL Specification
• SPIR-V Specification
• naga (Rust) — the Rust implementation this project was ported from (see UPSTREAM)

Rust Naga Compatibility

naga is tested against the WGSL snapshot corpus of Rust naga: 172 shaders with their test parameters and reference outputs, vendored from gfx-rs/wgpu at commit 14328f49 (snapshot/testdata/rust/, with a manifest of every file). Every output Rust's snapshot driver writes — IR, SPIR-V, MSL, GLSL, HLSL — is compared with ours. An output that does not match is a test failure unless it is recorded in snapshot/rust_deviations_test.go with its reason and a fingerprint of the difference; most records name the upstream commits not ported yet, and some are bugs being fixed. SPIR-V is still compared by instruction counts rather than exactly. Shaders using features we do not support yet (cooperative matrices, debugPrintf, 16-bit integers, ray tracing pipelines) are listed with their expected error. In addition, 28 own test shaders and 936 golden outputs guard against unintended changes.

---

Ecosystem

naga is the shader compiler for the GoGPU ecosystem.

Project	Description
gogpu/gogpu	GPU framework with windowing and input
gogpu/wgpu	Pure Go WebGPU implementation
gogpu/naga	Shader compiler (this repo)
gogpu/gg	2D graphics library
gogpu/ui	GUI toolkit (22 widgets, M3/Fluent/Cupertino)

---

Documentation

• ARCHITECTURE.md — Compiler architecture, pipeline, IR design
• ROADMAP.md — Development milestones
• CHANGELOG.md — Release notes
• pkg.go.dev — API reference

---

Contributing

We welcome contributions! Areas where help is needed:

• Additional WGSL features
• Test cases from real shaders
• Backend optimizations
• Documentation improvements

Star History

License

MIT License — see LICENSE for details.

---

naga — Shaders in Pure Go

Documentation

Overview

Package naga provides a Pure Go shader compiler.

naga compiles WGSL (WebGPU Shading Language) source code to multiple output formats:

• SPIR-V — Binary format for Vulkan
• MSL — Metal Shading Language for macOS/iOS
• GLSL — OpenGL Shading Language for OpenGL 3.3+, ES 3.0+
• HLSL — High Level Shading Language for DirectX

The package provides a simple, high-level API for shader compilation as well as lower-level access to individual compilation stages.

Example usage (SPIR-V):

source := `
@vertex
fn main(@builtin(vertex_index) idx: u32) -> @builtin(position) vec4<f32> {
    return vec4<f32>(0.0, 0.0, 0.0, 1.0);
}
`
spirv, err := naga.Compile(source)
if err != nil {
    log.Fatal(err)
}

For MSL output, use the msl package:

module, _ := naga.Lower(ast)
mslCode, info, err := msl.Compile(module, msl.DefaultOptions())

For GLSL output, use the glsl package:

module, _ := naga.Lower(ast)
glslCode, info, err := glsl.Compile(module, glsl.DefaultOptions())

Index

• Constants
• Variables
• func Compile(source string) ([]byte, error)
• func CompileWithOptions(source string, opts CompileOptions) ([]byte, error)
• func GenerateSPIRV(module *ir.Module, opts spirv.Options) ([]byte, error)
• func Lower(ast *wgsl.Module) (*ir.Module, error)
• func LowerWithCapabilities(ast *wgsl.Module, source string, caps ir.Capabilities) (*ir.Module, error)
• func LowerWithSource(ast *wgsl.Module, source string) (*ir.Module, error)
• func Parse(source string) (*wgsl.Module, error)
• func ProcessOverrides(module *ir.Module, opts OverrideOptions) (*ir.Module, error)
• func Validate(module *ir.Module) ([]ir.ValidationError, error)
• type CompileOptions
  • func DefaultOptions() CompileOptions
• type EntryPointSelector
• type OverrideOptions
• type PipelineConstantError
  • func (e *PipelineConstantError) Error() string
  • func (e *PipelineConstantError) Unwrap() error
• type PipelineConstants

Constants

const (
	// CapFloat64 enables f64 scalar type.
	CapFloat64 = ir.CapFloat64

	// CapShaderInt64 enables i64 and u64 scalar types.
	CapShaderInt64 = ir.CapShaderInt64

	// CapShaderFloat16 enables f16 scalar type.
	CapShaderFloat16 = ir.CapShaderFloat16

	// CapAll enables all capabilities.
	CapAll = ir.CapAll
)

Capability constants re-exported from ir for convenience. See ir.Capabilities for full documentation.

Variables

var (
	// ErrOverrideNotFound: a key names no override of the module.
	ErrOverrideNotFound = overrides.ErrNotFound
	// ErrOverrideMissingValue: an override an entry point uses has no value
	// and no default.
	ErrOverrideMissingValue = overrides.ErrMissingValue
	// ErrOverrideValueNotFinite: NaN or an infinity for a numeric override.
	ErrOverrideValueNotFinite = overrides.ErrValueNotFinite
	// ErrOverrideValueOutOfRange: the value does not fit the override's type.
	ErrOverrideValueOutOfRange = overrides.ErrValueOutOfRange
	// ErrNegativeWorkgroupSize: a workgroup size given by an override is not
	// positive.
	ErrNegativeWorkgroupSize = overrides.ErrNegativeWorkgroupSize
	// ErrNegativeMeshOutputMax: a mesh output limit given by an override is
	// negative.
	ErrNegativeMeshOutputMax = overrides.ErrNegativeMeshOutputMax
	// ErrEntryPointNotFound: OverrideOptions.EntryPoint selects no entry point.
	ErrEntryPointNotFound = overrides.ErrEntryPointNotFound
)

Pipeline-constant errors.

Functions

func Compile

func Compile(source string) ([]byte, error)

Compile compiles WGSL source code to SPIR-V binary using default options.

This is the simplest way to compile a shader. For more control, use CompileWithOptions or the individual Parse/Lower/Generate functions.

func CompileWithOptions

func CompileWithOptions(source string, opts CompileOptions) ([]byte, error)

CompileWithOptions compiles WGSL source code to SPIR-V binary with custom options.

The compilation pipeline is:

1. Parse WGSL source to AST
2. Lower AST to IR (intermediate representation)
3. Validate IR (if enabled)
4. Replace overrides by their defaults (ProcessOverrides with no pipeline constants), as Rust naga's CLI does; an override without a default is an error. For pipeline constants use Parse, Lower, ProcessOverrides and a backend.
5. Generate SPIR-V binary

func GenerateSPIRV

func GenerateSPIRV(module *ir.Module, opts spirv.Options) ([]byte, error)

GenerateSPIRV generates SPIR-V binary from IR module.

This is the final stage of compilation. The output is a binary blob that can be directly consumed by Vulkan or other SPIR-V consumers.

func Lower

func Lower(ast *wgsl.Module) (*ir.Module, error)

Lower converts WGSL AST to IR (Intermediate Representation). All capabilities are enabled (permissive mode for tools and tests). For strict capability validation, use LowerWithCapabilities.

The IR is a lower-level representation that includes type information, resolved identifiers, and a simpler structure suitable for code generation.

func LowerWithCapabilities

func LowerWithCapabilities(ast *wgsl.Module, source string, caps ir.Capabilities) (*ir.Module, error)

LowerWithCapabilities converts WGSL AST to IR with explicit capability control. The lowerer is always permissive; capability validation is performed by the validator after lowering. Types that require specific capabilities (f64, i64, u64, f16) produce validation errors unless the corresponding flag is set.

func LowerWithSource

func LowerWithSource(ast *wgsl.Module, source string) (*ir.Module, error)

LowerWithSource converts WGSL AST to IR, keeping source for error messages. All capabilities are enabled (permissive mode for tools and tests). For strict capability validation, use LowerWithCapabilities.

When source is provided, errors will include line:column information and can show source context using ErrorList.FormatAll().

func Parse

func Parse(source string) (*wgsl.Module, error)

Parse parses WGSL source code to AST (Abstract Syntax Tree).

This is the first stage of compilation. The AST represents the syntactic structure of the shader but does not include semantic information like types.

func ProcessOverrides

func ProcessOverrides(module *ir.Module, opts OverrideOptions) (*ir.Module, error)

ProcessOverrides returns module with every override expression replaced by a constant holding its pipeline value or default, every expression that becomes constant evaluated, and workgroup sizes given by overrides resolved — Rust naga's back::pipeline_constants::process_overrides. Call it before a backend; naga.Compile calls it with the defaults.

module is never modified, and ProcessOverrides may be called concurrently on the same module. The result may be module itself when there is nothing to do (no overrides, and no EntryPoint or at most one entry point); treat it as read-only. Handles in the result are not stable relative to module.

A module produced by the WGSL frontend with no overrides (len(Overrides) == 0) has no override expressions, override workgroup sizes or override-sized arrays and needs no processing, but call ProcessOverrides anyway when Constants is not empty: a key that names no override is an error (ErrOverrideNotFound).

With EntryPoint, globals the entry point does not use are removed. A backend that numbers resources by their position in the module (MSL without msl.Options.PerEntryPointMap) can then give them other slots.

The result keeps the overrides arena, with each initializer evaluated, and override-sized arrays stay pending (ir.ArraySize.Resolve sizes them; backends do), as in Rust. With EntryPoint the selected entry point is EntryPoints[0]. Processing a processed module again with other constants is not supported: process the module from the frontend for every pipeline.

Errors: a *PipelineConstantError for a constant (errors.Is with ErrOverrideNotFound, ErrOverrideMissingValue, ErrOverrideValueNotFinite, ErrOverrideValueOutOfRange); ErrEntryPointNotFound; ErrNegativeWorkgroupSize; ErrNegativeMeshOutputMax; an evaluation error of an expression that becomes constant (for example a division by zero after substitution); or an invalid processed module. Keys are checked in sorted order, so the same input reports the same key.

func Validate

func Validate(module *ir.Module) ([]ir.ValidationError, error)

Validate validates an IR module for correctness with all capabilities enabled.

Validation checks include:

• Type consistency
• Reference validity (all handles point to valid objects)
• Control flow validity (structured control flow rules)
• Binding uniqueness (no duplicate @group/@binding)

For capability-restricted validation, use ir.ValidateWithCapabilities directly. Returns a slice of validation errors. If the slice is empty, validation passed.

Types

type CompileOptions

type CompileOptions struct {
	// SPIRVVersion is the target SPIR-V version (default: 1.3)
	SPIRVVersion spirv.Version

	// Debug enables debug info in output (OpName, OpLine, etc.)
	Debug bool

	// Validate enables IR validation before code generation
	Validate bool

	// Capabilities controls which extended scalar types are allowed.
	// Zero value rejects f64/i64/u64/f16 (matching Rust naga defaults).
	// Use [CapFloat64], [CapShaderInt64], [CapShaderFloat16] to enable specific types,
	// or [CapAll] to permit everything.
	Capabilities ir.Capabilities

	// BoundsCheckPolicies selects how the generated SPIR-V handles indices
	// that are out of bounds. The zero value adds no checks. A WebGPU
	// implementation needs at least Restrict for Index (and for Buffer and
	// ImageLoad when the device has no robust buffer and image access), as
	// Rust wgpu-hal's Vulkan backend configures naga.
	BoundsCheckPolicies spirv.BoundsCheckPolicies
}

CompileOptions configures shader compilation.

func DefaultOptions

func DefaultOptions() CompileOptions

DefaultOptions returns sensible default options.

type EntryPointSelector

type EntryPointSelector struct {
	Stage ir.ShaderStage
	Name  string
}

EntryPointSelector selects one entry point by stage and name. It is not ir.EntryPoint.

type OverrideOptions

type OverrideOptions struct {
	// Constants are the pipeline-constant values.
	Constants PipelineConstants
	// EntryPoint, if not nil, keeps only that entry point; only overrides it
	// uses need a value.
	EntryPoint *EntryPointSelector
}

OverrideOptions configure ProcessOverrides. The zero value processes every entry point with no pipeline constants: every override takes its default.

type PipelineConstantError

type PipelineConstantError struct {
	Key string // the pipeline-constant key, or the override's identifier string
	Err error
}

PipelineConstantError is an error about one pipeline constant or override (Rust naga's PipelineConstantError). Err is one of the ErrOverride* sentinels; Error is Rust's message.

func (*PipelineConstantError) Error

func (e *PipelineConstantError) Error() string

func (*PipelineConstantError) Unwrap

func (e *PipelineConstantError) Unwrap() error

Unwrap returns Err, for errors.Is.

type PipelineConstants

type PipelineConstants map[string]float64

PipelineConstants are the values of pipeline-overridable constants (WebGPU GPUProgrammableStage.constants). A key is an override's @id as a decimal string, or its name if it has no @id; keys are compared exactly, as WGSL identifiers.