onejs-sl 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.9.3
+
+A hex colour is a float3 wherever a float3 is wanted, and `lookRay(eye, target, lens)` gives the ray through this pixel from a camera. Every program that compiled before keeps its hash.
+
+- `lookRay(eye, target, lens)` returns the ray through this pixel from a y up camera at `eye` looking at `target`, as Unity's camera casts it; `lens` is `0.5 / tan(fov / 2)`
+- A hex colour is a float3 wherever a float3 is wanted: returned, passed, in `float3(...)`, or beside a float3 in an op, a choice or a builtin
+- A program that compiled before keeps its hash
+
 ## 0.9.2
 
 A fractional `tex2Dlod` level now weighs each level's colour by its alpha, so a transparent level no longer darkens the other. Every program keeps its hash; a host's generated shaders take the new text on their next build.

package/goldens/goldens.json

@@ -1,6 +1,6 @@
 {
  "generatedBy": "onejs-sl goldens/run.mjs",
- "package": "0.9.2",
+ "package": "0.9.3",
  "ir": 6,
  "target": "rgba8unorm-srgb: straight alpha, 8 bit, sRGB encoded, the stored bytes of a Linear OneJS game's element",
  "size": [

package/lib/noise2d.hlsl

@@ -9,7 +9,7 @@
 // is the kind of thing nobody notices until two effects that should match do
 // not.
 
-// MARK: hash
+// hash
 //
 // The lattice hash is integer arithmetic, and has to stay integer arithmetic.
 // A float hash, frac of a large product as most shader noise is written, is
@@ -108,7 +108,7 @@ float onejsFbm(float2 p, float seed, int octaves)
     return onejsFbm(p, seed, octaves, 2.0, 0.5);
 }
 
-// MARK: simplex
+// simplex
 //
 // Ashima/McEwan 2D simplex. Worth carrying next to the value noise because the
 // two fail differently: value noise interpolates a square grid, so at high
@@ -167,7 +167,7 @@ float onejsFbmSimplex(float2 p, float seed, int octaves, float lacunarity, float
     return sum / max(norm, 1e-4);
 }
 
-// MARK: turbulence and ridged
+// turbulence and ridged
 //
 // fBm above sums signed octaves, so octaves cancel as often as they add and the
 // field reads as cloud. Turbulence sums the ABSOLUTE value of each octave: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-sl",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "The OneJS shader language: a small typed language for per pixel programs, compiled to a portable IR and emitted as HLSL, WGSL or GLSL ES",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/lang/README.md

@@ -125,6 +125,14 @@ constant 7 before the IR sees it. `sin(0.5)` is two instructions, because
 folding it would mean a second implementation of `sin` in JavaScript, and a
 second implementation is somewhere for the two backends to disagree.
 
+**A hex colour takes the width its place wants.** Alone, `#ff8040` is a
+float4. Where a float3 is wanted (a float3's declaration, a float3 function's
+return, a float3 parameter, `float3(#ff8040)`, the other side of an op or a
+choice, or a builtin's other arguments) it is that float3, its alpha dropped.
+A choice between two hexes counts as one. A computed float4 does not fit a
+float3 this way: that is still an error, since its alpha may be meant
+(`writtenHex` and `asWidth` in `lower.ts`; `hex-width.test.ts`).
+
 **A hex default makes a uniform a colour.** `uniform float4 tint = #ff8040;`
 stores the sRGB components as its default, which is what the host sets and what
 the generated shader's Properties block shows, and every read of `tint` goes

package/src/lang/check.ts

@@ -243,7 +243,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         }
     })
 
-    // MARK: bodies
+    // bodies
 
     // The prelude's own bodies are checked once, where it is built, against a
     // unit that has no uniforms of its own. Re-checking them here would let a
@@ -492,7 +492,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         return `this can never run: every way through the ${above} above ends in a return, break or continue`
     }
 
-    // MARK: expressions
+    // expressions
 
     function checkExpr(fn: FuncDecl, e: Expr, scope: Set<string>): void {
         switch (e.k) {

package/src/lang/lower.ts

@@ -317,7 +317,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         })
     }
 
-    // MARK: declarations
+    // declarations
 
     function declareUniform(name: string, type: TypeName, c: number[], control: UniformControl): Val {
         switch (type) {
@@ -429,7 +429,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         }
     }
 
-    // MARK: functions
+    // functions
 
     /** A function's body run to its return, in `scope`, which holds its parameters. */
     function callBody(fn: FuncDecl, scope: Scope): LV {
@@ -442,7 +442,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         return frame.retval
     }
 
-    // MARK: statements
+    // statements
 
     /**
      * Runs a body. What it does to the locals is in their bindings and what it
@@ -570,7 +570,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             case "switch": exec([switchAsIf(s, scope)], scope, frame); break
             case "block": exec(s.body, new Scope(scope), frame); break
             case "return": {
-                const v = lowerExpr(s.value, scope, want(frame.ret))
+                const v = asWidth(lowerExpr(s.value, scope, want(frame.ret)), s.value, frame.ret.width, s.pos)
                 frame.retval = returned(v, frame, s.pos)
                 frame.returned = true
                 break
@@ -606,6 +606,25 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         b.value = fit(v, b, name, s.pos)
     }
 
+    /**
+     * A colour written as a hex, `#ff8000`, or a choice between two. It has
+     * no width of its own: alone it is a float4, and where a float3 is wanted
+     * (a float3's declaration, return or argument, the other side of an op or
+     * a choice, a builtin's other arguments) it is that float3, its alpha
+     * dropped. Before, only a declaration dropped it, and returning one from a
+     * float3 function, passing one, or mixing one with a float3 was an error
+     * (learn Mac, 6 Nov 2026, lessons 7 and 8).
+     */
+    function writtenHex(e: Expr): boolean {
+        return e.k === "hex" || (e.k === "cond" && writtenHex(e.then) && writtenHex(e.else))
+    }
+
+    /** `v`, lowered from `e`, as the float3 a place wants when `e` is a written hex; otherwise as it is. */
+    function asWidth(v: LV, e: Expr, width: number, pos: Pos): LV {
+        if (width !== 3 || widthOf(v) !== 4 || !writtenHex(e)) return v
+        return at(pos, () => asVal(v).swz("xyz") as unknown as Val)
+    }
+
     /** A return's value as the function's type. Only the kind converts; a width has to match. */
     function returned(v: LV, frame: Frame, pos: Pos): LV {
         const fn = frame.fn
@@ -621,7 +640,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         return fit(v, t, `${fn.name}'s result`, pos)
     }
 
-    // MARK: loops
+    // loops
 
     function runLoop(s: Extract<Stmt, { k: "for" | "while" }>, scope: Scope, frame: Frame): void {
         const loopScope = new Scope(scope)
@@ -765,7 +784,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         return r === undefined ? null : { min: r.min, max: r.max }
     }
 
-    // MARK: switch
+    // switch
 
     /**
      * A switch as the if chain it means: `x == 1 || x == 2` per case, in order,
@@ -801,7 +820,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         return out[0] ?? { k: "if", cond: { k: "bool", value: true, pos: s.pos }, then: [], else: [], pos: s.pos }
     }
 
-    // MARK: conversions
+    // conversions
 
     /**
      * A value as a declared type, as a declaration, an assignment and a
@@ -919,7 +938,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         return b.width === 1 ? parts[0]! : at(pos, () => compose(b.width, parts))
     }
 
-    // MARK: expressions
+    // expressions
 
     /**
      * `want` is the kind the value is going into, an int or a uint, which makes
@@ -993,6 +1012,8 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
 
     /** A binary op on operands already lowered from `ea` and `eb`. */
     function combine(op: BinaryOp, a: LV, b: LV, ea: Expr, eb: Expr, scope: Scope, pos: Pos): LV {
+        a = asWidth(a, ea, widthOf(b), pos)
+        b = asWidth(b, eb, widthOf(a), pos)
         // A whole number beside an int is an int: `i < 10`, `i % 3`.
         if (isIntLike(a) && typeof b === "number" && wholeExpr(eb)) b = lowerExpr(eb, scope, kindWant(a))
         if (isIntLike(b) && typeof a === "number" && wholeExpr(ea)) a = lowerExpr(ea, scope, kindWant(b))
@@ -1134,6 +1155,8 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         if (cond instanceof Test) void cond.float
         let t = lowerExpr(e.then, scope, want)
         let f = lowerExpr(e.else, scope, want)
+        t = asWidth(t, e.then, widthOf(f), e.pos)
+        f = asWidth(f, e.else, widthOf(t), e.pos)
         if (isIntLike(t) && typeof f === "number" && wholeExpr(e.else)) f = lowerExpr(e.else, scope, kindWant(t))
         if (isIntLike(f) && typeof t === "number" && wholeExpr(e.then)) t = lowerExpr(e.then, scope, kindWant(f))
         const kinded = [t, f].some((v) => typeof v === "bigint" || v instanceof Uint || typeof v === "boolean" || (v instanceof Val && v.kind !== undefined))
@@ -1163,7 +1186,11 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         const n = (callee as Extract<Expr, { k: "ident" }>).name
 
         if (n === "int" || n === "uint" || n === "bool") return convert(n, e, scope)
-        if (n in TYPE_WIDTH) return construct(n as TypeName, floats(e.args), e.pos)
+        if (n in TYPE_WIDTH) {
+            // float3(#ff8000) is the colour's rgb, as a float3 declared from it is.
+            const one = e.args.length === 1 ? asWidth(toFloat(lowerExpr(e.args[0]!, scope), e.args[0]!.pos), e.args[0]!, TYPE_WIDTH[n as TypeName], e.pos) : null
+            return construct(n as TypeName, one !== null ? [one as number | Val] : floats(e.args), e.pos)
+        }
 
         if (n === "textureSize" || n === "tex2Dfetch") {
             const tex = samplers.get((e.args[0] as Extract<Expr, { k: "ident" }>).name)!
@@ -1210,6 +1237,9 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
         const builtin = BUILTINS[n]
         if (builtin !== undefined) {
             let args = e.args.map((a) => lowerExpr(a, scope))
+            // A hex among float3s is a float3: lerp(#ff8000, sky, t).
+            const others = Math.max(0, ...args.filter((_, i) => !writtenHex(e.args[i]!)).map(widthOf))
+            args = args.map((v, i) => asWidth(v, e.args[i]!, others, e.args[i]!.pos))
             // min, max, abs and clamp keep ints ints; everything else takes floats.
             if (INT_BUILTINS.has(n) && args.some(isIntLike) && args.every((v, i) => isIntLike(v) || (typeof v === "number" && wholeExpr(e.args[i]!)))) {
                 const k = kindWant(args.find(isIntLike)!)
@@ -1264,7 +1294,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             const arg = e.args[i]!
             // In the caller's scope, where the argument is written; as the
             // parameter's kind, so a whole number passed to an int is one.
-            const v = lowerExpr(arg, caller, want(t))
+            const v = asWidth(lowerExpr(arg, caller, want(t)), arg, t.width, arg.pos)
             const got = widthOf(v)
             if (got !== t.width) {
                 fail(
@@ -1307,7 +1337,7 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
     }
 }
 
-// MARK: tables and small helpers
+// tables and small helpers
 
 type ArithOp = "+" | "-" | "*" | "/" | "%"
 type BitOp = "&" | "|" | "^" | "<<" | ">>"

package/src/lang/parser.ts

@@ -82,7 +82,7 @@ class Parser {
         private readonly errors?: SLParseError[],
     ) {}
 
-    // MARK: token plumbing
+    // token plumbing
 
     private peek(n = 0): Token { return this.tokens[Math.min(this.i + n, this.tokens.length - 1)]! }
     private next(): Token { return this.tokens[this.i++]! }
@@ -107,7 +107,7 @@ class Parser {
         this.errors.push(e)
     }
 
-    // MARK: recovery
+    // recovery
 
     /**
      * Runs one statement's or one declaration's parse. Collecting, an error is
@@ -184,7 +184,7 @@ class Parser {
         this.fail(`"${t.text}" is not a type; the types are float, float2, float3, float4, int, uint and bool`, t)
     }
 
-    // MARK: the file
+    // the file
 
     parseUnit(): Unit {
         const unit: Unit = {
@@ -328,7 +328,7 @@ class Parser {
         return { name: name.text, ret, params, body, pos: start, prelude: false }
     }
 
-    // MARK: statements
+    // statements
 
     private parseBlock(): Stmt[] {
         this.expect("{", "to open a body")
@@ -538,7 +538,7 @@ class Parser {
         return { k: "switch", value, cases, pos: kw }
     }
 
-    // MARK: expressions
+    // expressions
 
     parseExpr(): Expr { return this.parseBinary(0) }
 

package/src/lang/prelude-source.ts

@@ -40,6 +40,14 @@ float2 tile(float2 p, float n) {
 float3 palette(float t, float3 a, float3 b, float3 c, float3 d) {
     return a + b * cos(6.28318530718 * (c * t + d));
 }
+
+// This pixel's ray from eye toward target, as Unity's camera casts it. lens is 0.5 / tan(fov / 2).
+float3 lookRay(float3 eye, float3 target, float lens) {
+    float3 forward = normalize(target - eye);
+    float3 right = normalize(cross(float3(0, 1, 0), forward));
+    float3 up = cross(forward, right);
+    return normalize(forward * lens + right * centered.x + up * centered.y);
+}
 `
 
 /** Each prelude function's name, in the order the source declares them. */

package/src/sl.ts

@@ -31,7 +31,7 @@ import {
 import { SLOP, SL_HLSL, SL_NAME, type SLOpCode } from "./ops"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
 
-// MARK: values
+// values
 
 type Swz = "x" | "y" | "z" | "w" | "r" | "g" | "b" | "a"
 const CHAN: Record<string, number> = { x: 0, y: 1, z: 2, w: 3, r: 0, g: 1, b: 2, a: 3 }
@@ -202,7 +202,7 @@ function withKind<T extends SLNode>(n: T, kind: SLKind | undefined): T {
     return kind === undefined ? n : { ...n, kind }
 }
 
-// MARK: recording context
+// recording context
 
 let current: Builder | null = null
 
@@ -288,7 +288,7 @@ function un(op: SLOpCode, a: Val): Val {
     return mk(a.owner, a.owner.call(op, a.width, [a.ref]), a.width)
 }
 
-// MARK: kinds (IR 4)
+// kinds (IR 4)
 
 /** The ops an int or a uint keeps its kind through. Anything else takes it as a float. */
 const INT_OPS = new Set<number>([SLOP.ADD, SLOP.SUB, SLOP.MUL, SLOP.DIV, SLOP.MOD, SLOP.MIN, SLOP.MAX, SLOP.CLAMP])
@@ -486,7 +486,7 @@ function typed(b: Builder, v: Num, t: ValType): NodeRef {
     return v.ref
 }
 
-// MARK: the public surface
+// the public surface
 
 export interface ProgramInputs {
     uv: Vec2