Naga processing passes

naga/src/proc/ holds the IR processing machinery: type inference, constant evaluation, indexer for arrays, layouter for memory layouts, and helpers for emitting expressions.

Modules

naga/src/proc/
├── mod.rs                    BoundsCheckPolicies, helpers (~39 KB)
├── constant_evaluator.rs     compile-time evaluation (~189 KB)
├── emitter.rs                tracks "emitted" expressions
├── index.rs                  array index/access analysis
├── keyword_set.rs            keyword reservation for backends
├── layouter.rs               struct member layout
├── namer.rs                  unique-name generation for backends
├── overloads/                builtin function overload resolution
├── terminator.rs             function-terminator pass
├── type_methods.rs           Type predicates + helpers
└── typifier.rs               expression type inference (~36 KB)

Key passes

Constant evaluator (constant_evaluator.rs)

Folds constant expressions at compile time. Used heavily by the WGSL frontend during lowering, and by naga::compact::compact to remove dead constants.

AGENTS.md documents specific notes about this file:

• cast() (~line 2256) — handles Expression::As with convert: Some(width).
• bitcast() (~line 2449) — handles Expression::As with convert: None. Target width equals source width.
• gen_component_wise_extractor! and friends — generate functions for component-wise scalar/vector ops.
• Recursive borrow patterns — extract data from self before recursive calls; clone vectors before iterating if you need &mut self.

The file is the single largest in naga/src/proc/ (~189 KB) and growing. Most additions cover new built-in functions or new component-wise math.

Typifier (typifier.rs)

Computes the TypeInner of every expression in a function. Used by the validator and by backends that need type info to emit code.

let mut typifier = Typifier::new();
typifier.grow(expr_handle, &expressions, &mut self.resolver, ...)?;
let type_inner = typifier.get(expr_handle, &types);

Once an expression's type has been computed, calling grow with the same handle is a no-op. Many passes call it lazily.

Emitter (emitter.rs)

Tracks which expressions a Block::Emit statement makes available. Naga's IR separates expression creation (in the arena) from expression availability (the moment the program is allowed to read it). The emitter groups expressions into Range<Expression> ranges that backends emit before the next non-emit statement.

Layouter (layouter.rs)

Computes the size and alignment of every Type in the module under each address space's rules. Used by:

• The WGSL frontend (to honor @align/@size and to compute arrayLength()).
• Backends that need explicit layout (naga::back::hlsl for cbuffers, naga::back::msl for stage_in structs).
• The validator (to check that struct members have the right alignments for their address spaces).

Namer (namer.rs)

Generates unique, language-appropriate identifier names. Each backend has its own keyword set (naga/src/keywords/); the namer ensures user-named items don't collide with target-language reserved words.

Bounds-check policies (mod.rs)

BoundsCheckPolicies lets the caller specify how out-of-range array/storage-buffer accesses are handled per address space:

pub struct BoundsCheckPolicies {
    pub index: BoundsCheckPolicy,
    pub buffer: BoundsCheckPolicy,
    pub image_load: BoundsCheckPolicy,
    pub binding_array: BoundsCheckPolicy,
}

Possible policies: Restrict (clamp), ReadZeroSkipWrite, Unchecked. wgpu-naga-bridge picks the policies appropriate to the target backend and to the device's ShaderRuntimeChecks setting.

Index analysis (index.rs)

Tracks which array accesses are statically in-bounds and which need runtime checks. Lets backends emit cheaper code where possible.

Overloads (overloads/)

Resolves WGSL built-in function overloads. WGSL's dot, mix, clamp, etc. accept many type combinations; the overload module picks the right specialization given the argument types.

How they fit together

graph TD
    Front[Frontend] -->|raw IR| Mod[Module]
    Mod --> Typifier[Typifier<br/>computes types]
    Mod --> Layouter[Layouter<br/>computes sizes]
    Mod --> ConstEval[Constant evaluator]
    Mod --> Index[Index analysis]
    ConstEval --> Mod
    Typifier --> Valid[Validator]
    Layouter --> Valid
    Index --> Back[Backend]
    Typifier --> Back
    Layouter --> Back
    Valid --> Back

Modifying processing passes

• A new constant-folding case — add to constant_evaluator.rs. Watch the borrow patterns. Add a snapshot test under naga/tests/in/wgsl/const-exprs.wgsl per AGENTS.md's note.
• A new layout rule — layouter.rs is the central place. Make sure you also update the validator's expectation in naga/src/valid/handles.rs and type.rs.
• A new built-in function — extend the WGSL parser's intrinsic table, add overload entries in proc/overloads/, add typing in typifier.rs, add code emission in each relevant backend.
• A new bounds-check policy — extend BoundsCheckPolicy and propagate through every backend's index/access path.