Rule 4.8

Chapter 4, Types Test

Every matCxR with C and R in 2, 3, 4 must be a type, and a square one must also answer to matN. A matrix element must be f32, or f64 on a square shape only. A two-row matrix (mat2x2, mat3x2, mat4x2) in a uniform block must be refused with the remedy, since WGSL gives its column a stride of 8 and std140 rounds every column to 16, so the two targets would place it and every later field at different offsets.

The rule text and the parts under it are the compiler's own English, as the design document writes them.

Rationale

a shape both targets lay out alike needs no ceremony, and a shape they lay out differently is refused rather than padded, because padding would make the emitted WGSL disagree with the offsets reflect() reports (Rule 6.8).

Derives from

Matrix Types (matCxR<T>, T a floating-point type) and Memory Layout (the column stride is AlignOf(vecR<T>)); PR #166, which measured the std140 stride on a WebGL2 driver and on Tint (surface §40); #149.

How it is verified

Checked by a test. A test, a gate script or a CI workflow names this rule, and the traceability check fails when a file listed below stops naming it.

Where the rule says the compiler enforces it:

MAT_TYPE_NAMES in src/compiler/ts/type-map.ts for the nine shapes and the three short spellings (TS8002 UNKNOWN_TYPE names all twelve);
TS8027 MAT_UNSUPPORTED for a non-square matCxR<f64> (mat2x3<f64> has no emulated-double form: the fp64 pass carries a square matrix of doubles only (mat2, mat3, mat4). Declare it mat2x3 and narrow, or use a square shape.);
TS8051 LAYOUT in src/compiler/ts/bindings.ts for the two-row uniform field, at the binding’s declaration and with neither target emitted ("U.m" is in a uniform: mat2x2 in std140 is not supported, a sentence that goes on to name mat2x4 and two vec2 fields as the remedies), pinned by src/compiler/ts/uniform-layout.test.ts; wgslLayout in src/core/reflect.ts throws the same sentence from src/core/std140.ts for a std140 layout built another way;
TS8003 TYPE_MISMATCH for a * b on two matrices whose dimensions do not meet, two of one non-square shape among them (Type mismatch: cannot * mat2x3 and mat2x3. WGSL's matrix product is matKxR * matCxK -> matCxR: …), pinned by src/compiler/ts/matrices.test.ts (refuses two matrices of ONE non-square shape, which have one type key) (#169);
src/compiler/ts/matrices.test.ts, src/core/reflect.test.ts, and examples/normal-matrix.shade.ts on both halves of the gate, which pin them.

The files that verify it at commit 26de7be8, each at the first line that names the rule:

Explained in

The sections of the surface document that explain this rule, at commit 26de7be8:

§40 Matrices: every matCxR

Error codes that enforce it

The diagnostic codes the rule names under Enforced by, or whose registry text names the rule:

TS8002 UNKNOWN_TYPE: A type name nothing declares, said once for the file wherever it is written (a parameter, a claim, a type argument, B<vec3<Foo>> included, an alias, an implements clause, the base a class or an interface extends, a body no call lowers), a type the library declares for TypeScript alone (Number) where the file declares none of its name, or a type this surface does not take in a position the mapper reads (Rule 2.1).
TS8003 TYPE_MISMATCH: Two types that do not fit where they meet (an operator, a condition, a declaration, a return or an argument), or a constant the compiler folds that WGSL refuses: a shift amount past 31, a divisor of 0, clamp bounds that cross or an f32 past its range.
TS8027 MAT_UNSUPPORTED: A non-square matCxR<f64>: the fp64 pass carries one df64 body per dimension (DF64MatN, matmul, matvec, transpose), so only a square matrix of doubles lowers.
TS8051 LAYOUT: A buffer binding's store type breaks one of WGSL's host-shareable rules (§51), which a struct hides from the type map and the backend only meets as emitted text: a bool, alone or in a vector, in a uniform or storage binding, as a field, a runtime array's element or the whole type (type 'bool' cannot be used in address space 'uniform' as it is non-host-shareable, and the same of vec3<bool>), a runtime-sized array<T> that is not its struct's last member, or a runtime-sized array in a uniform, whose type must be constructible.

Source

The rule at commit 26de7be8:

docs/language-design.md:319 (the design document)
reqs/rules/RULE-0408.md (its traceability item)

Edit this page Report a problem