[bigmistqke]

Problem

A JavaScript number given where rmsl expects a node has no shader type of its own, and each place that takes one decided its type differently. With i an int uniform and v an int variable:

Place	What a number became
Beside an operand, i.add(2), or assigned, v.assign(2)	an integer literal of the operand's or target's type
A constructor of numbers alone, ivec2(3, 0)	an integer literal
A constructor beside a node, ivec2(i, 0)	a float, converted: ivec2(_rmsl_u0, 0.0) on GLSL, vec2<i32>(…, i32(0f)) on WGSL
An input of an Fn with a layout, next(3) for an int input	a float, so the call was refused as an argument of another type
An index, element(2)	an int literal for a vector or a matrix. A float for a uniform array or a storage buffer, converted: [int(2.0)] on GLSL, [i32(2f)] or [u32(2f)] on WGSL

The same number compiled to an integer literal in one place, a converted float in another, and was refused in a third.

Fixes #360.

What changes

A number takes the type of the place it is given: the operand beside it, the target of an assign, a constructor's component, the input of an Fn with a layout, and int for an index. It compiles to a literal of that type on every target. A fraction given for an integer is truncated toward zero, in every place, as rmsl already converts a float node, an integer value the host gives and a float index of a storage element.

const i = uniform("int");
const next = Fn(([n]) => n.add(1)).setLayout({ name: "next", type: "int", inputs: [{ name: "n", type: "int" }] });

ivec2(i, 0);                        // GLSL ivec2(_rmsl_u0, 0), WGSL vec2<i32>(…, 0i)
next(3);                            // GLSL next(3), WGSL next(3i)
uniformArray("vec4", 4).element(2); // GLSL _rmsl_u1[2], WGSL _rmsl_u1[2i]

A number for a vector input fills every component: for an Fn scale whose layout has a vec3 input and a uint input, scale(2, 3) passes vec3(2) and the uint 3. A number for a bool or matrix input is refused, as before.

Fractions and what is refused

A fraction for an integer is truncated toward zero wherever it is given: i.add(2.9) adds 2, next(2.9) passes 2, element(1.5) reads element 1, ivec2(i, 2.9) holds 2, and Loop(2.9, …) runs twice.

What no integer stands for is refused:

• A number the type cannot hold: ivec2(i, 3e9), next(3e9), i.add(3e9).
• A negative number for an unsigned type, uvec2(u, -1) or next with a uint input given -1, as before.
• A negative index, a fraction above -1 included: element(-1), element(-0.5).

Each refusal comes where the program builds the node, with an error that names the number, and the type or the element call it was given to. To fix such a call, give a number inside the type's range.

Code that behaves differently

• ivec2(i, 3e9) and uvec3(u, 1, 5e9), with u a uint uniform, compiled, and now throw.
• i.add(2.9) beside an integer, and Loop(2.9, …) for an integer index, were refused, and now truncate the fraction.
• element(-1) of a uniform array or a storage buffer compiled, and now throws. Of a vector it was already refused, as out of range.
• next(3) and next(2.9) for an int input, and scale(2, 3) for a vec3 input, were refused and now compile.
• GLSL and WGSL write a number as a literal where they wrote a converted float, so a snapshot of the generated code changes.

What TSL does

On TSL's dev branch, which three.js releases next, a plain number takes the type of the node beside it, and a number for a layout Fn's input takes the input's type. rmsl follows that, and departs from TSL in five places, each recorded in CANON.md as an exception:

• A fraction for an integer is truncated. TSL's dev branch truncates it too, so this departs from three.js r186 only, which rounds it for an input, an index or a Loop bound and keeps it a float beside an operand.
• A number outside an integer's range beside an operand is refused. On dev it changes the operation's type, so i.add(3e9) adds two floats.
• A number outside the range beside a node in a constructor is refused. TSL converts the float, int( 3000000000.0 ), which GLSL leaves undefined and WGSL clamps, so the targets disagree.
• A negative index is refused. TSL writes it as 0u and reads the first element.
• A number index is an int, the type element gives an index node. TSL builds a uint, [ 2u ]. The value is the same for every index an array holds, so only the generated text differs.

Facts about TSL

Where three.js 0.186.1 and TSL's dev branch differ, CANON.md states each version as a fact of its own, such as fact-tsl-r186-rounds-a-number-it-builds-as-an-integer and fact-tsl-r187dev-truncates-a-number-it-builds-as-an-integer, each with permalinks to the lines that do it. The TSL-parity axiom now says that a behaviour TSL changed between versions gives a TSL shader no one meaning a port could keep, so parity alone does not decide it; the fraction and out-of-range exceptions cite the fact of each version for that reason. In 0.186.1 a number beside an operand is a float constant, so i.add(2) writes i + 2.0, and a number TSL builds as an integer, for an input or an index, is rounded: generateConst in 0.186.1 writes it with Math.round. On dev a number takes its neighbour's type and is truncated: generateConst on dev writes it with Math.trunc.

Evidence

• CANON.md: spec-a-number-takes-the-type-its-place-asks-for states the rule. Its leaves are the operand specs, the constructor spec, and specs for a layout Fn's input and for an index, with the five exceptions beside them.
• src/canon/targets.test.ts and src/canon/layout-fn.test.ts: a test for each leaf and exception. The tests of a compiled number check the GLSL and WGSL text. Those that compute a value run on JavaScript, WebAssembly, GLSL in WebGL 2 and WGSL on WebGPU, and fail unless all four give the same value. Every new test fails on main, except the test of an operand out of range, which pins a refusal main already made.
• src/usage.test.ts: two tests asserted the run-time conversion of a uniform array's index, [int(2.0)] and [i32(…)], and now assert the literal.
• pnpm test: 3314 passed, 11 expected failures, 56 skipped. The expected failures are the tests marked to fail that pin known bugs already on main. pnpm type-check, pnpm type-check:demos and pnpm test:types pass. A JS draw allocation test fails now and then under the load of the full suite, unrelated to this change, tracked in The JS draw allocation test fails under the load of the full suite and passes alone #363.

Follow-ups

• Cite each TSL fact in CANON.md as a permalink, and check it against TSL's dev branch #362 gives the remaining TSL facts in CANON.md permalinks like those above, and checks each against dev.
• Add struct, a type of named members, as TSL's struct does #359 adds structs. Its constructor builds a number for a member through the same path as an operand, so once this merges it truncates a fraction for an integer member too. Add struct, a type of named members, as TSL's struct does #359's canon leaf for members then cites spec-a-number-takes-the-type-its-place-asks-for.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@random-mesh/rmsl@361

commit: 0b5ed9a