wgsl-uniform-vec3-alignment - SKILL.md Agent Skill

name: wgsl-uniform-vec3-alignment description: vec3 in WGSL uniform address space inherits vec4 alignment (16 bytes). When padding Rust #[repr(C)] UBO structs to match WGSL, use array<u32, N> instead of vecNu to avoid implicit alignment gaps source: auto-skill extracted_at: '2026-06-15T20:25:00.000Z'

WGSL uniform vec3 alignment footgun

In WGSL's uniform address space, vec3<T> inherits the alignment of vec4<T> (16 bytes). This means a WGSL struct like:

struct Params {
    a: u32,
    b: u32,
    c: u32,
    d: u32,
    e: u32,
    _pad: vec3u,   // WRONG — 16-byte aligned, offset padded to 32
}

...can be 48 bytes on the GPU (wgpu/naga may insert 12 bytes of padding before _pad to satisfy the 16-byte alignment) while the matching Rust struct is 32 bytes. This causes bind-group validation failures on backends that enforce uniform layout rules, or silent data corruption if validation doesn't catch the size mismatch.

Why: WGSL § alignment rules: vec3 alignment = vec4 alignment = 16 bytes in uniform address space. The Rust #[repr(C)] struct has field alignment = 4 bytes (the element alignment of [u32; 3] = 4). The two layouts diverge.

Correct fix:

    _pad: array<u32, 3>,   // CORRECT — element alignment = 4, matches Rust

array<u32, 3> has the same element alignment as the Rust [u32; 3] (4 bytes), so the structs match exactly. The array carries the same 12 bytes of data; only the alignment rule differs.

When to use vecNu at all: vec4u is safe because the alignment is the same as array<u32, 4> (both 16 bytes). vec2u alignment is 8 bytes = array<u32, 2> alignment (both 8 bytes). Only vec3 has this alignment-divergence property.

Verification: If a bind-group creation fails with a size-mismatch error on a UBO (uniform buffer), check all vec3 fields in the WGSL struct. Replace with array<T, 3>.

Affected code in Titan: vsm_allocate.wgsl VsmAllocateParams._pad was fixed from vec3u to array<u32, 3> in commit 689b4fb8 after the code review caught the latent mismatch.