onejs-sl 0.7.0 → 0.9.0

package/src/body.ts

@@ -21,7 +21,7 @@
  * gives common subexpression elimination for free.
  */
 
-import { INT_BOUNDS, SLError, TYPE, valueAt, type InputName, type NodeRef, type StepInputName, type Program, type SLKind, type SLType, type ValueNode } from "./ir"
+import { INT_BOUNDS, SLError, TYPE, isWhole, samplingOf, valueAt, type TextureSampling, type InputName, type NodeRef, type StepInputName, type Program, type SLKind, type SLType, type ValueNode } from "./ir"
 import { libClosure, LIB_FUNCTIONS } from "./lib"
 import { LIB_HLSL } from "./lib/hlsl"
 import { SLOP } from "./ops"
@@ -55,7 +55,8 @@ export interface BodyTarget {
      * - **Filtered and wrapped by the host.** The body does neither. OneJS's
      *   hosts, the generated shader and the web backends alike, use the
      *   bound texture's own filter and wrap modes, so a host that filters by
-     *   hand draws the same picture by following the texture's settings.
+     *   hand draws the same picture by following the texture's settings. A
+     *   texture whose program sets its sampler goes to `sampleWith` instead.
      *
      * What becomes of the result is the host's: OneJS writes it to the target
      * as it is, and a host that composites premultiplied multiplies on write.
@@ -63,12 +64,50 @@ export interface BodyTarget {
     sample: (slot: number, uv: string) => string
     /**
      * A float4 sample of the texture in `slot` at `uv` from mip level `lod`, a
-     * float expression: 0 is the full size texture, 1 half, and a fraction
-     * blends two levels where the texture's filter does. Otherwise the same
-     * contract as `sample`. `tex2Dlod` in a program; HLSL's
+     * float expression: 0 is the full size texture and 1 half. The body only
+     * asks for whole levels, or for a level it cannot prove whole, floored and
+     * floored plus one, which it blends by the fraction itself; so a fraction
+     * draws the same whatever the texture's filter between levels, and a host
+     * has no blending to do. A level past the smallest reads the smallest.
+     * Otherwise the same contract as `sample`. `tex2Dlod` in a program; HLSL's
      * `tex2Dlod(s, float4(uv, 0, lod))` and Metal's `sample(s, uv, level(lod))`.
      */
     sampleLevel: (slot: number, uv: string, lod: string) => string
+    /**
+     * A float4 sample of a texture whose program sets its sampler
+     * (`[Wrap(Repeat)]`, `[Filter(Point)]`, IR 6), sampled that way whatever
+     * the bound texture's own settings: `sample` when `lod` is null, else
+     * `sampleLevel` at `lod`, with the same contract as those two in every
+     * other respect. `sampling` always has both halves (`samplingOf`):
+     *
+     * - `wrap`: `repeat` tiles, `mirror` tiles mirrored every other tile,
+     *   `clamp` holds the edge texel. The filter's footprint wraps the same
+     *   way, so a tiled texture has no seam.
+     * - `filter`: `point` reads the nearest texel and the nearest level,
+     *   `linear` blends the four nearest texels within the nearest level, as
+     *   Unity's Bilinear does.
+     *
+     * Optional, and `emitBody` refuses a program that samples such a texture
+     * when a target has none, rather than print one that samples as the
+     * bound texture is set. Unity's inline sampler states, a WebGPU sampler
+     * and a WebGL2 sampler object each say both halves.
+     */
+    sampleWith?: (slot: number, uv: string, lod: string | null, sampling: TextureSampling) => string
+    /**
+     * A float2 of the texture in `slot`'s width and height, in pixels, at full
+     * size (`textureSize(t)`, IR 6). Optional, as `previous` is.
+     */
+    size?: (slot: number) => string
+    /**
+     * A float4 of one texel of the texture in `slot`, unfiltered, at full size
+     * (`tex2Dfetch(t, pixel)`, IR 6). `pixel` is a float2 expression the body
+     * has already floored and held inside the texture with `size`, so a host
+     * converts it to an int2 and loads: HLSL's `t.Load(int3(pixel, 0))`,
+     * Metal's `t.read(uint2(pixel))`. Texel (0, 0) is the one `uv` (0, 0)
+     * samples. In the space `colour` names, as `sample` is, so an sRGB texture
+     * is decoded. Optional; needs `size` too.
+     */
+    fetch?: (slot: number, pixel: string) => string
     /**
      * A float4 of what this program drew the frame before, at `uv`, for a
      * host that keeps it (`tex2D(previous, uv)`, `Specs/SL_NEXT.md` 4).
@@ -110,7 +149,7 @@ export interface Body {
     uses: {
         /** Uniform slots the body reads, ascending. */
         uniforms: number[]
-        /** Texture slots the body samples, ascending. */
+        /** Texture slots the body samples, measures or fetches from, ascending. */
         textures: number[]
         /** Library functions the body calls, sorted: `sl_fbm`, `sl_sdfDistance`, ... `emitLibrary` prints them. */
         helpers: string[]
@@ -165,6 +204,26 @@ export function emitBody(p: Program, target: BodyTarget): Body {
         const c = p.nodes[ref]!
         return c.k === "const" ? c.v : null
     }
+    /** A texture's sampler, when its program sets one, and the target that has to honour it. */
+    const sampling = (slot: number): TextureSampling | null => {
+        const s = samplingOf(p.textures[slot]!)
+        if (s !== null && target.sampleWith === undefined) {
+            throw new SLError(`this target cannot set a texture's sampler, and the program samples ${p.textures[slot]!.name} with ${s.wrap} and ${s.filter}`)
+        }
+        return s
+    }
+    const plain = (slot: number, uv: string) => {
+        const s = sampling(slot)
+        return s === null ? target.sample(slot, uv) : target.sampleWith!(slot, uv, null, s)
+    }
+    const level = (slot: number, uv: string, lod: string) => {
+        const s = sampling(slot)
+        return s === null ? target.sampleLevel(slot, uv, lod) : target.sampleWith!(slot, uv, lod, s)
+    }
+    const size = (slot: number) => {
+        if (target.size === undefined) throw new SLError(`this target cannot measure a texture, and the program measures ${p.textures[slot]!.name}`)
+        return target.size(slot)
+    }
     const splat = (ref: number, w: SLType) => (valueAt(p.nodes, ref).type === TYPE.FLOAT && w > 1 ? ctor(w, Array(w).fill(name(ref))) : name(ref))
 
     const expr = (ref: NodeRef): string => {
@@ -331,12 +390,32 @@ export function emitBody(p: Program, target: BodyTarget): Body {
                 textures.add(slot)
                 // Where pixels part ways there are no neighbours to take a mip
                 // level from, so every backend samples level 0 there (`structure.ts`).
-                return inVaryingFlow(shape, ref) ? target.sampleLevel(slot, a[0]!, "0.0") : target.sample(slot, a[0]!)
+                return inVaryingFlow(shape, ref) ? level(slot, a[0]!, "0.0") : plain(slot, a[0]!)
             }
             case SLOP.SAMPLE_LOD: {
                 const slot = Math.round(imm[0] ?? 0)
                 textures.add(slot)
-                return target.sampleLevel(slot, a[0]!, a[1]!)
+                // A fraction blends the level below and the level above,
+                // whatever the texture's filter between levels, as the web
+                // emitters do (`isWhole`). Past the smallest level both read the
+                // smallest, as a whole level past it does.
+                if (isWhole(p.nodes, n.args[1]!)) return level(slot, a[0]!, a[1]!)
+                const below = `floor(${a[1]})`
+                return `lerp(${level(slot, a[0]!, below)}, ${level(slot, a[0]!, `${below} + 1.0`)}, frac(${a[1]}))`
+            }
+            case SLOP.TEXTURE_SIZE: {
+                const slot = Math.round(imm[0] ?? 0)
+                textures.add(slot)
+                return size(slot)
+            }
+            case SLOP.SAMPLE_FETCH: {
+                const slot = Math.round(imm[0] ?? 0)
+                textures.add(slot)
+                if (target.fetch === undefined) throw new SLError(`this target cannot fetch a texel, and the program reads ${p.textures[slot]!.name} with tex2Dfetch`)
+                // Floored and held inside, so a pixel past an edge reads the
+                // edge on every host rather than whatever a host's load returns
+                // out of range.
+                return target.fetch(slot, `clamp(floor(${a[0]}), float2(0.0, 0.0), ${size(slot)} - 1.0)`)
             }
             case SLOP.SAMPLE_PREVIOUS:
                 if (target.previous === undefined) throw new SLError("this target keeps no previous frame, and the program samples it")

package/src/core.ts

@@ -8,13 +8,14 @@
  * game never executes.
  */
 export * as sl from "./sl"
-export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, PreviousFrame, Texture } from "./sl"
+export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, PreviousFrame, Texture, TextureSamplingOptions } from "./sl"
 export {
     TYPE, INPUTS, STEP_INPUTS, PREVIOUS, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, SL_HASH_VERSION,
-    inputsUsed, readsOf, CONTROL_FIELDS, controlProblem,
+    inputsUsed, readsOf, CONTROL_FIELDS, controlProblem, samplingOf, TEXTURE_WRAPS, TEXTURE_FILTERS,
 } from "./ir"
 export type {
     SLType, InputName, StepInputName, HostInputName, SLReads, NodeRef, SLNode, Program, UniformDecl, UniformControl, TextureDecl,
+    TextureSampling, TextureWrap, TextureFilter,
 } from "./ir"
 export { SLOP, SL_ARITY, SL_NAME, INPUT_ID, isSampling, UNIFORM_SLOTS, TEXTURE_SLOTS } from "./ops"
 export type { SLOpCode } from "./ops"

package/src/hlsl.ts

@@ -15,8 +15,9 @@
  * next time it is generated.
  */
 
-import { SLError, SL_HASH_VERSION, readsOf, type Program } from "./ir"
+import { SLError, SL_HASH_VERSION, readsOf, reachable, samplingOf, type Program, type TextureSampling } from "./ir"
 import { emitBody, lit, type BodyTarget } from "./body"
+import { SLOP } from "./ops"
 
 /** The property name a uniform gets. Prefixed so it cannot collide with ours. */
 export function uniformProperty(name: string): string {
@@ -49,6 +50,7 @@ export function emitShader(p: Program, options: EmitOptions = {}): string {
     const include = options.include ?? "SLCommon.cginc"
     const body = emitFragmentBody(p)
     const reads = readsOf(p)
+    const use = textureUse(p)
 
     const props: string[] = [
         `        _Secs ("Seconds", Float) = 0`,
@@ -68,7 +70,22 @@ export function emitShader(p: Program, options: EmitOptions = {}): string {
     }
     for (const t of p.textures) {
         props.push(`        _Tex${t.slot} ("${t.name}", 2D) = "white" {}`)
-        decls.push(`            sampler2D _Tex${t.slot};`)
+        // A texture sampled as it is set is the sampler2D it always was, so
+        // every program before IR 6 prints the shader it always did. One the
+        // program sets a sampler for, or fetches from, is a Texture2D: the
+        // inline sampler state or the Load needs the texture on its own.
+        if (!use.object.has(t.slot)) decls.push(`            sampler2D _Tex${t.slot};`)
+        else {
+            decls.push(`            Texture2D _Tex${t.slot};`)
+            // Its own settings, by Unity's naming rule, for a plain sample.
+            if (use.plain.has(t.slot)) decls.push(`            SamplerState sampler_Tex${t.slot};`)
+        }
+        // Unity fills it from the bound texture: (1 / width, 1 / height, width, height).
+        if (use.sized.has(t.slot)) decls.push(`            float4 _Tex${t.slot}_TexelSize;`)
+    }
+    // Unity's inline sampler states: the name says the filter and the wrap.
+    for (const name of [...new Set(p.textures.map(samplingOf).filter((s) => s !== null).map(inlineSampler))].sort()) {
+        decls.push(`            SamplerState ${name};`)
     }
     // Only for a program that samples it, so every other program's shader is
     // the text it always was. Transparent black is the previous frame's clear
@@ -143,6 +160,7 @@ ${body}
  * shader compile, so this target always emits it.
  */
 function unityTarget(p: Program): BodyTarget {
+    const use = textureUse(p)
     return {
         // `_Res` is the TARGET's size, set by the host, not `_ScreenParams`.
         //
@@ -164,8 +182,15 @@ function unityTarget(p: Program): BodyTarget {
             deltaTime: "_Res.w",
         },
         uniform: (slot) => uniformProperty(p.uniforms[slot]!.name),
-        sample: (slot, uv) => `tex2D(_Tex${slot}, ${uv})`,
-        sampleLevel: (slot, uv, lod) => `tex2Dlod(_Tex${slot}, float4(${uv}, 0.0, ${lod}))`,
+        sample: (slot, uv) => use.object.has(slot) ? `_Tex${slot}.Sample(sampler_Tex${slot}, ${uv})` : `tex2D(_Tex${slot}, ${uv})`,
+        sampleLevel: (slot, uv, lod) => use.object.has(slot)
+            ? `_Tex${slot}.SampleLevel(sampler_Tex${slot}, ${uv}, ${lod})`
+            : `tex2Dlod(_Tex${slot}, float4(${uv}, 0.0, ${lod}))`,
+        sampleWith: (slot, uv, lod, s) => lod === null
+            ? `_Tex${slot}.Sample(${inlineSampler(s)}, ${uv})`
+            : `_Tex${slot}.SampleLevel(${inlineSampler(s)}, ${uv}, ${lod})`,
+        size: (slot) => `_Tex${slot}_TexelSize.zw`,
+        fetch: (slot, pixel) => `_Tex${slot}.Load(int3(${pixel}, 0))`,
         // Flipped as this frame flipped the uv it wrote at, so a read at a
         // pixel's own uv is that pixel whichever way the host's target runs.
         previous: (uv) => `tex2Dlod(_Prev, float4(${uv} * float2(1.0, 1.0 - 2.0 * _FlipY) + float2(0.0, _FlipY), 0.0, 0.0))`,
@@ -175,6 +200,36 @@ function unityTarget(p: Program): BodyTarget {
     }
 }
 
+/**
+ * An inline sampler state's name. Unity reads the filter and the wrap from the
+ * name itself ("point" or "linear", "clamp", "repeat" or "mirror").
+ */
+function inlineSampler(s: TextureSampling): string {
+    return `sl_sampler_${s.filter}_${s.wrap}`
+}
+
+/**
+ * How the program reaches each texture slot, which decides how the shader
+ * declares it. `object`: declared a Texture2D, because the program sets its
+ * sampler or fetches from it. `plain`: an object sampled with its own
+ * settings, which needs Unity's `sampler_` state. `sized`: reads `_TexelSize`,
+ * as `textureSize` and a fetch's bounds do.
+ */
+function textureUse(p: Program): { object: Set<number>; plain: Set<number>; sized: Set<number> } {
+    const fetched = new Set<number>(), sampled = new Set<number>(), sized = new Set<number>()
+    for (const ref of reachable(p.nodes, p.result)) {
+        const n = p.nodes[ref]!
+        if (n.k !== "call") continue
+        const slot = Math.round(n.imm?.[0] ?? 0)
+        if (n.op === SLOP.SAMPLE || n.op === SLOP.SAMPLE_LOD) sampled.add(slot)
+        else if (n.op === SLOP.TEXTURE_SIZE) sized.add(slot)
+        else if (n.op === SLOP.SAMPLE_FETCH) { fetched.add(slot); sized.add(slot) }
+    }
+    const object = new Set(p.textures.filter((t) => samplingOf(t) !== null || fetched.has(t.slot)).map((t) => t.slot))
+    const plain = new Set([...sampled].filter((slot) => object.has(slot) && samplingOf(p.textures[slot]!) === null))
+    return { object, plain, sized }
+}
+
 /** The straight line body: one local per reachable node, in order. */
 export function emitFragmentBody(p: Program): string {
     return emitBody(p, unityTarget(p)).body

package/src/index.ts

@@ -18,10 +18,10 @@
  */
 export * from "./core"
 export {
-    analyze, classify, diagnose, parse, parseUnit, preludeFunctions, tokenize, PRELUDE_SOURCE, SLParseError,
+    analyze, classify, classifyLine, diagnose, parse, parseUnit, preludeFunctions, tokenize, PRELUDE_SOURCE, SLParseError,
 } from "./lang"
 export type {
-    Checked, Expr, FuncDecl, ParseOptions, Pos, SLClassifiedToken, SLFix, SLTokenClass, Stmt, Token, Unit,
+    Checked, Expr, FuncDecl, ParseOptions, Pos, SLClassifiedToken, SLFix, SLLineState, SLTokenClass, Stmt, Token, Unit,
 } from "./lang"
 export { fromGLSL } from "./lang/glsl"
 export type { FromGLSL } from "./lang/glsl"

package/src/ir.ts

@@ -274,10 +274,45 @@ export function intUniformProblem(type: SLType, value: readonly number[]): strin
     return null
 }
 
+/** How a texture's coordinates outside 0 to 1 read: tiled, held at the edge, or tiled mirrored. */
+export type TextureWrap = "repeat" | "clamp" | "mirror"
+/** How a texture is read between texels: the nearest one, or a blend of the four around. */
+export type TextureFilter = "point" | "linear"
+
+/** The sampler a program sets for a texture, both halves filled in (`samplingOf`). */
+export interface TextureSampling {
+    wrap: TextureWrap
+    filter: TextureFilter
+}
+
+export const TEXTURE_WRAPS: readonly TextureWrap[] = ["repeat", "clamp", "mirror"]
+export const TEXTURE_FILTERS: readonly TextureFilter[] = ["point", "linear"]
+
 export interface TextureDecl {
     name: string
     /** Sampler slot, assigned in declaration order. */
     slot: number
+    /**
+     * How the program samples it, as written: `[Wrap(Repeat)]` and
+     * `[Filter(Point)]` in a `.sl` file, `sl.texture(name, { wrap, filter })`.
+     * Neither set, the texture samples as the texture bound to it is set,
+     * which is what every program did before IR 6. Either set, the program
+     * owns the sampler, and the half it leaves out is clamp or linear
+     * (`samplingOf`). Part of the hash, since the shader differs.
+     */
+    wrap?: TextureWrap
+    filter?: TextureFilter
+}
+
+/**
+ * The sampler a texture's program sets, or null when it samples as the bound
+ * texture is set. A program that names one half gets clamp or linear for the
+ * other, on every host: Unity's inline sampler states and WebGPU's samplers
+ * have no way to take one half from the texture and the other from the shader.
+ */
+export function samplingOf(t: Pick<TextureDecl, "wrap" | "filter">): TextureSampling | null {
+    if (t.wrap === undefined && t.filter === undefined) return null
+    return { wrap: t.wrap ?? "clamp", filter: t.filter ?? "linear" }
 }
 
 export interface Program {
@@ -308,8 +343,9 @@ export function tooManyUniforms(declared: number, source: "file" | "program"): s
 
 export function tooManyTextures(declared: number, source: "file" | "program"): string {
     return `this ${source} declares ${declared} textures and a program may sample ${TEXTURE_SLOTS}. ` +
-        `OneJS binds ${TEXTURE_SLOTS} textures to a program in the editor and a native player, so ` +
-        `this one would sample nothing there while a browser drew it: two pictures from one ${source}.`
+        `OneJS binds ${TEXTURE_SLOTS} textures to a program, so this one would have no slot to be ` +
+        `bound in; it is refused here rather than drawn blank. Pack two images into one texture's ` +
+        `channels, or draw in two passes.`
 }
 
 /**
@@ -323,6 +359,17 @@ export function checkCaps(p: Pick<Program, "uniforms" | "textures">): void {
     if (p.textures.length > TEXTURE_SLOTS) throw new SLError(tooManyTextures(p.textures.length, "program"))
 }
 
+/** What is wrong with a texture's sampler, or null. The one check, for the builder and `fromJSON`. */
+export function samplingProblem(s: { wrap?: unknown; filter?: unknown }): string | null {
+    if (s.wrap !== undefined && !TEXTURE_WRAPS.includes(s.wrap as TextureWrap)) {
+        return `a wrap is ${TEXTURE_WRAPS.join(", ")}, and this is ${String(s.wrap)}`
+    }
+    if (s.filter !== undefined && !TEXTURE_FILTERS.includes(s.filter as TextureFilter)) {
+        return `a filter is ${TEXTURE_FILTERS.join(" or ")}, and this is ${String(s.filter)}`
+    }
+    return null
+}
+
 /**
  * The colour as written behind a colour value: the operand of the `TO_LINEAR`
  * that reading a hex or a colour uniform applied, or null for a value computed
@@ -446,14 +493,30 @@ export class Builder {
         return this.add({ k: "uniform", type, slot })
     }
 
-    texture(name: string): number {
+    texture(name: string, sampling: Pick<TextureDecl, "wrap" | "filter"> = {}): number {
+        const problem = samplingProblem(sampling)
+        if (problem !== null) throw new SLError(`texture "${name}": ${problem}`)
         const existing = this.textures.findIndex((t) => t.name === name)
-        if (existing >= 0) return this.textures[existing].slot
+        if (existing >= 0) {
+            // A second use may say nothing about the sampler, or the same thing again.
+            const t = this.textures[existing]!
+            for (const f of ["wrap", "filter"] as const) {
+                if (sampling[f] === undefined) continue
+                if (t[f] !== undefined && t[f] !== sampling[f]) {
+                    throw new SLError(`texture "${name}" is given two different ${f}s, ${t[f]} and ${sampling[f]}`)
+                }
+                t[f] = sampling[f] as never
+            }
+            return t.slot
+        }
         if (this.textures.length >= TEXTURE_SLOTS) {
             throw new SLError(tooManyTextures(this.textures.length + 1, "program"))
         }
         const slot = this.textures.length
-        this.textures.push({ name, slot })
+        const decl: TextureDecl = { name, slot }
+        if (sampling.wrap !== undefined) decl.wrap = sampling.wrap
+        if (sampling.filter !== undefined) decl.filter = sampling.filter
+        this.textures.push(decl)
         return slot
     }
 }
@@ -461,9 +524,9 @@ export class Builder {
 /**
  * Nodes the result actually depends on, in order.
  *
- * Dead nodes are dropped rather than encoded. An author can produce them easily
+ * Dead nodes are dropped rather than emitted. An author can produce them easily
  * by computing something and not using it, and the hash already ignores them, so
- * encoding them would make the buffer disagree with its own hash about what the
+ * emitting them would make a shader disagree with its own hash about what the
  * program is.
  */
 export function reachable(nodes: SLNode[], result: NodeRef): NodeRef[] {
@@ -519,6 +582,42 @@ export function readsOf(p: Program): SLReads {
     return out
 }
 
+/** Ops whose result is a whole number whatever they are given. */
+const ALWAYS_WHOLE = new Set<number>([SLOP.FLOOR, SLOP.CEIL, SLOP.ROUND, SLOP.SIGN])
+/** Ops whose result is a whole number when every operand they read is one. */
+const KEEPS_WHOLE = new Set<number>([
+    SLOP.CAST, SLOP.ADD, SLOP.SUB, SLOP.MUL, SLOP.NEG, SLOP.ABS, SLOP.MIN, SLOP.MAX, SLOP.CLAMP, SLOP.SATURATE,
+])
+
+/**
+ * Whether a value is a whole number in every component on every pixel, as far
+ * as its node says. An int, uint or bool is; so are a constant written whole,
+ * `floor`, `ceil`, `round` and `sign`, and sums, products, minimums and the
+ * like of whole numbers (a float32 sum or product of whole numbers is whole).
+ * Anything else is not known to be, a uniform float included.
+ *
+ * The emitters read it for `tex2Dlod`: a level known whole reads that level
+ * with one sample, and any other blends the level below and the level above by
+ * the fraction, so every backend draws a fraction the same way whatever the
+ * texture's filter between levels.
+ */
+export function isWhole(nodes: readonly SLNode[], ref: NodeRef, seen = new Map<NodeRef, boolean>()): boolean {
+    const known = seen.get(ref)
+    if (known !== undefined) return known
+    const n = valueAt(nodes, ref)
+    let whole = false
+    if (n.kind !== undefined) whole = true
+    else if (n.k === "const") whole = n.v.every(Number.isInteger)
+    else if (n.k === "swizzle") whole = isWhole(nodes, n.src, seen)
+    else if (n.k === "call") {
+        if (ALWAYS_WHOLE.has(n.op)) whole = true
+        else if (KEEPS_WHOLE.has(n.op)) whole = n.args.every((a) => isWhole(nodes, a, seen))
+        else if (n.op === SLOP.CHOOSE) whole = isWhole(nodes, n.args[1]!, seen) && isWhole(nodes, n.args[2]!, seen)
+    }
+    seen.set(ref, whole)
+    return whole
+}
+
 /** Structural key for hash consing. Order matters and is fixed by the node shape. */
 function keyOf(n: SLNode): string {
     const kind = "kind" in n && n.kind !== undefined ? `@${n.kind}` : ""
@@ -651,9 +750,15 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     // includes the library's text when it compiles, and none caches a compiled
     // program by hash across a library update, so the new text reaches every
     // shader without a bump.
-    const parts: string[] = [`v${SL_HASH_VERSION}:${programVersion(nodes, result)}`, of(result)]
+    const parts: string[] = [`v${SL_HASH_VERSION}:${programVersion(nodes, result, textures)}`, of(result)]
     for (const u of uniforms) parts.push(`U:${u.name}:${u.type}:${u.value.map(fixed).join(",")}`)
-    for (const t of textures) parts.push(`T:${t.name}:${t.slot}`)
+    // A texture's sampler as the shader has it, so `[Wrap(Clamp)]` and
+    // `[Filter(Linear)]` share a hash, and a texture with neither has the
+    // part it had before IR 6.
+    for (const t of textures) {
+        const s = samplingOf(t)
+        parts.push(`T:${t.name}:${t.slot}${s === null ? "" : `:${s.wrap}:${s.filter}`}`)
+    }
     return fnv1a(parts.join("|"))
 }
 
@@ -715,8 +820,8 @@ export function controlOf(c: UniformControl): UniformControl {
  * int constant a fold used up, say), and they draw nothing. `toJSON` writes
  * only the live ones, so an older reader never meets a dead newer node.
  */
-export function programVersion(nodes: readonly SLNode[], result: NodeRef): number {
-    let v = 2
+export function programVersion(nodes: readonly SLNode[], result: NodeRef, textures: readonly TextureDecl[] = []): number {
+    let v = textures.some((t) => samplingOf(t) !== null) ? 6 : 2
     for (const ref of reachable(nodes as SLNode[], result)) v = Math.max(v, nodeVersion(nodes[ref]!))
     return v
 }
@@ -738,6 +843,9 @@ function nodeVersion(n: SLNode): number {
     if (n.k !== "call") return 2
     if (IR4_OPS.has(n.op)) return 4
     switch (n.op) {
+        case SLOP.TEXTURE_SIZE:
+        case SLOP.SAMPLE_FETCH:
+            return 6
         case SLOP.SAMPLE_PREVIOUS: return 5
         case SLOP.SAMPLE_LOD: return 3
         case SLOP.SDF:
@@ -761,6 +869,8 @@ function nodeVersion(n: SLNode): number {
  *        one immediate
  *   SAMPLE_PREVIOUS  a float4 at a float2, and no immediates: there is one
  *        previous frame, so there is no slot to name
+ *   TEXTURE_SIZE  a float2 of nothing, the slot the one immediate
+ *   SAMPLE_FETCH  a float4 at a float2 pixel, the slot the one immediate
  */
 export function formProblem(n: Extract<SLNode, { k: "call" }>, nodes: readonly SLNode[]): string | null {
     const widths = n.args.map((a) => { const v = nodes[a]!; return v.k === "if" || v.k === "loop" ? "control" : v.type }).join(",")
@@ -778,6 +888,12 @@ export function formProblem(n: Extract<SLNode, { k: "call" }>, nodes: readonly S
         case SLOP.SAMPLE_PREVIOUS:
             if (widths === "2" && n.type === 4 && n.kind === undefined && (n.imm?.length ?? 0) === 0) return null
             return "the previous frame is a float4 read at a float2"
+        case SLOP.TEXTURE_SIZE:
+            if (widths === "" && n.type === 2 && n.kind === undefined && n.imm?.length === 1) return null
+            return "a texture's size is a float2, its slot the one immediate"
+        case SLOP.SAMPLE_FETCH:
+            if (widths === "2" && n.type === 4 && n.kind === undefined && n.imm?.length === 1) return null
+            return "a fetch is a float4 read at a float2 pixel, its slot the one immediate"
         default:
             return null
     }
@@ -819,8 +935,9 @@ export const SL_HASH_VERSION = 2
  *      operands, where they were immediates
  *   4  control flow (if, loop, their params and projs), ints, uints and bools
  *   5  the previous frame (SAMPLE_PREVIOUS), and the frame and deltaTime inputs
+ *   6  TEXTURE_SIZE and SAMPLE_FETCH, and a texture's sampler (`wrap`, `filter`)
  */
-export const SL_IR_VERSION = 5
+export const SL_IR_VERSION = 6
 
 function fnv1a(s: string): string {
     let h = 0x811c9dc5

package/src/lang/README.md

@@ -41,9 +41,14 @@ player. So parity is the test to keep green, not the parser's unit tests.
 | `ast.ts` | The node shapes, all of them, which is not many |
 | `parser.ts` | Pratt parser: shape only, HLSL precedence |
 | `check.ts` | Declarations, names, statement shape, budgets, recursion |
-| `lower.ts` | AST to IR through the EDSL: SSA, unrolling, `select`, inlining |
+| `lower.ts` | AST to IR through the EDSL: SSA, unrolling, branches and loops, inlining |
 | `builtins.ts` | What each name does, keyed by the spelling `ops.ts` gives it |
-| `prelude.ts` | The standard library, written in the language |
+| `prelude.ts`, `prelude-source.ts` | The standard library, written in the language |
+| `attributes.ts` | A uniform's `[Range]`, `[Toggle]` and the rest, read into its control |
+| `words.ts` | The keywords and type names, shared by the parser and `classify` |
+| `classify.ts` | Every token with its class, for an editor's highlighting |
+| `glsl.ts` | `fromGLSL`: a pasted GLSL shader as a `.sl` file |
+| `index.ts` | This folder's exports |
 | `onejs-unity`'s `src/esbuild/sl.mjs` | The loader: `import plasma from "./plasma.sl"` |
 | `../index.ts` and `../core.ts` | The package with the parser, and without it. See below |
 
@@ -68,9 +73,11 @@ It writes two things beside the code:
   recording stays for EDSL programs and for a build older than the loader; the
   editor reads every `*.sl.json` it can find.
 
-An empty manifest is written only over one that is already there. Deleting the
-last `.sl` file has to stop its shaders being generated, and a project that has
-never had one should not find a new file beside its bundle.
+With no `.sl` files, an empty manifest is written over one that is already
+there, since deleting the last `.sl` file has to stop its shaders being
+generated, and beside a bundle carrying `onejs-sl`, which has to name its hash
+scheme. A project that uses no shader language finds no new file beside its
+bundle.
 
 ### Why the parser is compiled rather than imported
 
@@ -110,7 +117,8 @@ here is the one nothing else uses.
 **A scalar on the left of an operator broadcasts through a swizzle.** `uv * 8`
 is `uv.mul(8)`, one constant node of two components. `8 * uv` is
 `sl.float(8).mul(uv)`, a one component constant and a broadcast. Same picture,
-different graph, different hash. Write the vector on the left when it matters.
+different graph, and since 0.4.0 (`SL_HASH_VERSION` 2) the same hash. The
+vector on the left saves a node.
 
 **Literal arithmetic folds; a builtin call never does.** `2 * 3 + 1` is the
 constant 7 before the IR sees it. `sin(0.5)` is two instructions, because
@@ -161,8 +169,8 @@ recorded gap, not an oversight, and each has its own error message rather than
 | `rgb2hsv` | The opcode is numbered and **no backend implements it**; every emitter throws on it. |
 | `fbm`'s simplex base | `sl.fbm(p, octaves, "simplex")` picks the base with a string, and the language has no strings. `fbm(p, octaves)` is the value base, and `turbulence` and `ridged` are the simplex family. |
 
-A `.sl` file and the EDSL are held to the same caps, `UNIFORM_SLOTS` (16) and
-`TEXTURE_SLOTS` (4), reported at the declaration in one wording (`ir.ts`'s
+A `.sl` file and the EDSL are held to the same caps, `UNIFORM_SLOTS` (64) and
+`TEXTURE_SLOTS` (8), reported at the declaration in one wording (`ir.ts`'s
 `tooManyUniforms` and `tooManyTextures`).
 
 ## Attributes
@@ -185,6 +193,16 @@ What they produce is metadata on the uniform (`range`, `toggle`, `options`,
 `header`, `label`, `hide`), which the hash never reads. `[Color]` is the
 exception, because it changes the reads: it is the same as a hex default.
 
+A texture takes two of its own, which are not metadata: `[Wrap(Repeat)]`,
+`[Wrap(Mirror)]` or `[Wrap(Clamp)]`, and `[Filter(Point)]` or `[Filter(Linear)]`,
+read by `readTextureAttributes`. They change the shader (a sampler the program
+owns rather than the bound texture's), so they are in the hash and make a
+program IR 6; the half left out is clamp or linear (`samplingOf`). Unity's
+`Bilinear` and `WrapMode` are offered as fixes, and `Trilinear` and
+`MirrorOnce` are refused with why: no backend's per program sampler blends
+levels, and WebGPU has no mirror once. A uniform's attribute on a texture, or
+a texture's on a uniform, says which one it belongs on.
+
 ## Errors
 
 Every one carries file, line, column, offset and length, and `text`, the
@@ -201,7 +219,7 @@ Where the fix is certain, the error carries it as `fix`: a title and the text
 for the marked range, one click in an editor. A GLSL spelling that means the
 same in HLSL (`mix`, `fract`, `vec3`, `gl_FragCoord`, `iTime`, two argument
 `atan`) and a "did you mean" both have one. `mod` does not, since GLSL's floors
-and `%` truncates, and neither does `int`, since float would change what
+and `%` truncates, and neither does `ivec2`, since `float2` would change what
 dividing it does. That is Decision 1 kept as `Specs/SL_NEXT.md` 5 A has it:
 one spelling, and every hint a fix.
 
@@ -229,6 +247,13 @@ on the parser's own scanner and word lists, so the highlighting is the parser's.
 It never throws, since it runs on every keystroke. It classifies by spelling,
 not scope: a local named `circle` still reads as a builtin where it is used.
 
+`classifyLine(line, state)` is the same for an editor that colours a line at a
+time, as Monaco does: the line's tokens and the state the next line starts
+from (inside a block comment or not, and the two tokens before it). Every line
+of a file classified that way gives what `classify` gives the whole file, a
+block comment over several lines coming back as one piece per line; the corpus
+holds it to that.
+
 `SL_KEYWORDS` and `SL_TYPES` (`words.ts`) are the lists the parser reads, and a
 name may be neither. `onejs-sl/tables` carries them, and `ATTRIBUTE_NAMES`, with
 a one line description of every builtin, input, attribute and prelude function; a prelude function's is the
@@ -249,7 +274,9 @@ where they were, so the result reads as the shader it came from. What it does:
   the inputs. So do the calls that need an
   expression: `mod` floors (`a - b * floor(a / b)`, never `%`, which
   truncates), and `atan`, `inversesqrt`, `radians`, `degrees`, `exp2` and
-  `log2` become what they compute.
+  `log2` become what they compute. `texelFetch(t, p, 0)` is
+  `tex2Dfetch(t, p)` and `textureSize(t, 0)` is `textureSize(t)`; another
+  level gets a note, since both read the full size texture.
 - `mainImage` becomes `float4 main()`, with its colour parameter as a local it
   returns; `void main()` writing `gl_FragColor` or a WebGL2 `out vec4` does the
   same. Shadertoy's `uv = fragCoord / iResolution.xy` line is dropped, since
@@ -268,8 +295,10 @@ where they were, so the result reads as the shader it came from. What it does:
   the notes point at `rotate()`. A file with a `rotate` of its own is left
   alone, since the calls would reach it. `#define NAME value`
   becomes a const; any other directive is kept as a comment, with a note.
-- A name the language already means something by gets a `_` suffix, and an
-  `int` becomes a float (a for-loop counter stays an int), each with a note.
+- A name the language already means something by gets a `_` suffix, with a
+  note. `int`, `uint` and `bool` are kept, since they are types here too; their
+  vectors (`ivec2`, `uvec3`, `bvec4` and the rest) become float vectors, with a
+  note saying what changed.
 - What has no counterpart (`iFrameRate`, `texelFetch`, `dFdx`, a function
   returning nothing) is left in place with a note, for `errors` to point at.
 

package/src/lang/ast.ts

@@ -99,7 +99,10 @@ export type AttributeArg =
     | { k: "str"; text: string; pos: Pos; length: number }
     | { k: "ident"; name: string; pos: Pos; length: number }
 
-/** `[Range(0, 2)]` before a uniform: Unity's spelling of what its control is. */
+/**
+ * `[Range(0, 2)]` before a uniform, Unity's spelling of what its control is,
+ * or `[Wrap(Repeat)]` before a texture, of how it is sampled.
+ */
 export interface Attribute {
     name: string
     args: AttributeArg[]
@@ -120,6 +123,8 @@ export interface UniformDecl {
 
 export interface TextureDecl {
     name: string
+    /** `[Wrap(...)]` and `[Filter(...)]`, in the order written. */
+    attrs: Attribute[]
     pos: Pos
 }