onejs-sl 0.8.0 → 0.9.0

package/src/ops.ts

@@ -26,16 +26,21 @@
  * for a host to read.
  *
  * They are what OneJS draws a program with. It keeps a program's uniforms in
- * 16 slots in the editor, a native player and a browser alike
- * (`SLProgramBridge.MaxUniforms`, the web frame's `sl_U`), and binds four
- * textures in the editor and a native player (`_Tex0` to `_Tex3`). A program
- * past either has something with no slot of its own, which one host would drop
- * and another would draw, so the parser and the builder both refuse it at the
- * declaration, the parser with a file and a line. `Specs/SL_NEXT.md` section 8
- * proposes raising both.
+ * 64 slots in the editor, a native player and a browser alike
+ * (`SLProgramBridge.MaxUniforms`, the web frame's `sl_U`), and binds eight
+ * textures everywhere (`_Tex0` to `_Tex7`). A program past either has
+ * something with no slot of its own, which one host would drop and another
+ * would draw, so the parser and the builder both refuse it at the declaration,
+ * the parser with a file and a line.
+ *
+ * Both sit inside every backend's minimum (`Specs/SL_NEXT.md` 8). Eight
+ * textures and the previous frame are nine sampled textures and at most nine
+ * samplers, where WebGPU, WebGL2, OpenGL ES 3 and Direct3D 11 all guarantee 16
+ * a fragment stage. 64 float4s are 1 KB of uniforms, where WebGL2 and OpenGL
+ * ES 3 guarantee 224 vectors and WebGPU 64 KB.
  */
-export const UNIFORM_SLOTS = 16
-export const TEXTURE_SLOTS = 4
+export const UNIFORM_SLOTS = 64
+export const TEXTURE_SLOTS = 8
 
 /** Input ids, which the web emitter switches on. */
 export const INPUT_ID: Record<string, number> = {
@@ -149,6 +154,11 @@ export const SLOP = {
     // What this program drew the frame before, at a uv (IR 5). No slot: the
     // host keeps it, and a program that never reads it has none.
     SAMPLE_PREVIOUS: 146,
+    // IR 6. A texture's size in pixels, a float2, its slot the one immediate.
+    TEXTURE_SIZE: 147,
+    // IR 6. One texel, unfiltered, at a float2 pixel: floored and held inside
+    // the texture, so every backend reads the same texel at every pixel.
+    SAMPLE_FETCH: 148,
 } as const
 
 export type SLOpCode = (typeof SLOP)[keyof typeof SLOP]
@@ -191,6 +201,7 @@ export const SL_ARITY: Record<number, number> = {
     [SLOP.VORONOI]: 1, [SLOP.TURBULENCE]: -1, [SLOP.RIDGED]: -1,
 
     [SLOP.SAMPLE]: 1, [SLOP.SAMPLE_LOD]: 2, [SLOP.SAMPLE_PREVIOUS]: 1,
+    [SLOP.TEXTURE_SIZE]: 0, [SLOP.SAMPLE_FETCH]: 1,
 }
 
 /** Name per opcode, for error messages and for the HLSL emitter's comments. */
@@ -316,6 +327,8 @@ export const SL_HLSL: Record<number, SLSurface> = {
     [SLOP.SAMPLE]: { call: "tex2D" },
     [SLOP.SAMPLE_LOD]: { call: "tex2Dlod" },
     [SLOP.SAMPLE_PREVIOUS]: { syntax: "tex2D(previous, uv)" },
+    [SLOP.TEXTURE_SIZE]: { call: "textureSize" },
+    [SLOP.SAMPLE_FETCH]: { call: "tex2Dfetch" },
 }
 
 /**
@@ -347,6 +360,7 @@ export const SL_GLSL_HINT: Record<string, string> = {
     mod: "%",
     texture: "tex2D",
     textureLod: "tex2Dlod",
+    texelFetch: "tex2Dfetch",
     vec2: "float2",
     vec3: "float3",
     vec4: "float4",

package/src/params.ts

@@ -21,7 +21,7 @@ import { LIB_FUNCTIONS, SDF_CALLS } from "./lib/table"
 import { LIB_PARAM_NAMES } from "./lib/names"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
 import type { PREVIOUS, SourceInputName } from "./ir"
-import type { AttributeName } from "./lang/attributes"
+import type { AttributeName, TextureAttributeName } from "./lang/attributes"
 
 /** One function of the helper library, as its source declares it. */
 export interface LibSignature {
@@ -55,6 +55,8 @@ const INTRINSIC: Record<string, readonly string[]> = {
     lerp: ["x", "y", "s"], step: ["y", "x"], smoothstep: ["min", "max", "x"],
     tex2D: ["s", "t"],
     tex2Dlod: ["s", "t", "lod"],
+    textureSize: ["s"],
+    tex2Dfetch: ["s", "pixel"],
 }
 
 /**
@@ -163,6 +165,8 @@ export const BUILTIN_DOCS: Readonly<Record<string, string>> = {
     ridged: "Turbulence made bright at its creases: ridges, lightning, cracks.",
     tex2D: "The colour of texture s at the uv t, with straight alpha.",
     tex2Dlod: "Texture s at uv t from mip level lod: 0 is full size, 1 half, and a fraction blends the two.",
+    textureSize: "The width and height of texture s in pixels, at full size, as a float2.",
+    tex2Dfetch: "One texel of texture s at pixel, unfiltered; a pixel past an edge reads the edge.",
     sdf: "The signed distance from p to a shape, negative inside: `sdf.circle(p, r)`.",
     ramp: "t mapped through evenly spaced colour stops, from the first at 0 to the last at 1.",
 }
@@ -181,6 +185,12 @@ export const ATTRIBUTE_DOCS: Readonly<Record<AttributeName, string>> = {
     Hide: "No control: the host sets this uniform from code.",
 }
 
+/** One line on each texture attribute, for the same tooltips. */
+export const TEXTURE_ATTRIBUTE_DOCS: Readonly<Record<TextureAttributeName, string>> = {
+    Wrap: "How uv outside 0 to 1 reads: [Wrap(Repeat)] tiles, [Wrap(Mirror)] tiles mirrored, [Wrap(Clamp)] holds the edge.",
+    Filter: "How the texture reads between texels: [Filter(Point)] the nearest, [Filter(Linear)] a blend of four.",
+}
+
 /**
  * One line on each input, for the same tooltips. In the words of no one host:
  * the output is a UI element in OneJS and an image on a Magerie board, and the

package/src/serial.ts

@@ -10,10 +10,13 @@
  */
 import {
     INPUTS, STEP_INPUTS, SLError, SL_HASH_VERSION, SL_IR_VERSION, TYPE, checkCaps, controlOf, controlProblem, formProblem, hashProgram, intUniformProblem,
-    programVersion, type HostInputName, type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
+    programVersion, samplingProblem, type HostInputName, type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
 } from "./ir"
 import { SLOP, SL_ARITY, SL_NAME } from "./ops"
 
+/** The ops that name a texture slot in their first immediate. */
+const TEXTURE_OPS = new Set<number>([SLOP.SAMPLE, SLOP.SAMPLE_LOD, SLOP.TEXTURE_SIZE, SLOP.SAMPLE_FETCH])
+
 const HOST_INPUTS: Readonly<Record<HostInputName, SLType>> = { ...INPUTS, ...STEP_INPUTS }
 
 export interface ProgramJSON {
@@ -54,7 +57,8 @@ export function fromJSON(json: unknown): Program {
     // as they are) or was edited. One that claims less than its nodes need
     // holds something its version never had, and a version 1 file has
     // nothing IR 3 added.
-    const needs = programVersion(written, j.result!)
+    const textures = (j.textures ?? []).map(texture)
+    const needs = programVersion(written, j.result!, textures)
     if (v < needs && (v >= 2 || needs >= 3)) fail(`it says IR version ${v} and holds nodes version ${needs} added; it was changed after it was written`)
     const { nodes, result } = v < 3 ? toOperands(written, j.result!) : { nodes: written, result: j.result! }
     nodes.forEach((n, i) => {
@@ -64,12 +68,14 @@ export function fromJSON(json: unknown): Program {
     const out = nodes[result]!
     if (out.k === "if" || out.k === "loop" || out.type !== TYPE.VEC4 || out.kind !== undefined) fail("its result is not a float4")
     const uniforms = (j.uniforms ?? []).map(uniform)
-    const textures = (j.textures ?? []).map(texture)
     checkCaps({ uniforms, textures })
     for (const n of nodes) {
         if (n.k === "uniform" && n.slot >= uniforms.length) fail(`a node reads uniform slot ${n.slot}, which is not declared`)
+        if (n.k === "call" && TEXTURE_OPS.has(n.op) && !(n.imm !== undefined && n.imm[0]! < textures.length)) {
+            fail(`a node reads texture slot ${String(n.imm?.[0])}, which is not declared`)
+        }
     }
-    const version = programVersion(nodes, result)
+    const version = programVersion(nodes, result, textures)
     const hash = hashProgram(nodes, result, uniforms, textures)
     // The same IR version and hash scheme, so the same hash; a different one
     // means the file was edited or damaged, and its cached shader belongs to
@@ -245,7 +251,12 @@ function uniform(u: unknown, i: number): UniformDecl {
 function texture(t: unknown, i: number): TextureDecl {
     const x = (t ?? {}) as Partial<TextureDecl>
     if (typeof x.name !== "string" || x.slot !== i) fail(`texture ${i} needs a name and slot ${i}`)
-    return { name: x.name!, slot: i }
+    const problem = samplingProblem(x)
+    if (problem !== null) fail(`texture ${i}: ${problem}`)
+    const out: TextureDecl = { name: x.name!, slot: i }
+    if (x.wrap !== undefined) out.wrap = x.wrap
+    if (x.filter !== undefined) out.filter = x.filter
+    return out
 }
 
 function fail(why: string): never {

package/src/sl.ts

@@ -25,7 +25,8 @@
 import { parseColor as parseHex } from "./color"
 import {
     Builder, INPUTS, RAMP_STOP_COMPUTED, STEP_INPUTS, SLError, TYPE, hashProgram, programVersion, truncateHeld, widthName, writtenColour,
-    type HostInputName, type InputName, type NodeRef, type Program, type SLKind, type SLNode, type SLType, type UniformControl,
+    type HostInputName, type InputName, type NodeRef, type Program, type SLKind, type SLNode, type SLType, type TextureFilter,
+    type TextureWrap, type UniformControl,
 } from "./ir"
 import { SLOP, SL_HLSL, SL_NAME, type SLOpCode } from "./ops"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
@@ -561,7 +562,7 @@ export function program(fn: (inputs: ProgramInputs) => Vec4): Program {
         }
         const nodes: SLNode[] = b.nodes.slice()
         return {
-            version: programVersion(nodes, out.ref),
+            version: programVersion(nodes, out.ref, b.textures),
             nodes,
             result: out.ref,
             uniforms: b.uniforms.slice(),
@@ -1033,7 +1034,10 @@ export const uniform = {
 }
 
 export interface Texture {
-    /** The colour at `uv`, filtered as the texture's own settings say. */
+    /**
+     * The colour at `uv`, filtered and wrapped as the texture's own settings
+     * say, or as `sl.texture`'s sampling says when it was given one.
+     */
     sample(uv: Vec2): Vec4
     /**
      * The colour at `uv` from mip level `lod`: 0 is the full size texture, 1
@@ -1041,11 +1045,31 @@ export interface Texture {
      * texture's filter mode. A texture with no mips has only level 0.
      */
     sampleLevel(uv: Vec2, lod: Num): Vec4
+    /** The texture's width and height in pixels, at full size. `textureSize(t)` in a `.sl` file. */
+    size(): Vec2
+    /**
+     * One texel, unfiltered, at a pixel: (0, 0) is the texel `uv` (0, 0)
+     * samples. The pixel is floored and held inside the texture, so a pixel
+     * past an edge reads the edge on every host. Full size only, and the
+     * sampling settings do not apply. `tex2Dfetch(t, pixel)` in a `.sl` file.
+     */
+    fetch(pixel: Vec2): Vec4
 }
 
-export function texture(name: string): Texture {
+/**
+ * How a program samples a texture, when it should not follow the bound
+ * texture's own settings. Either half set, the program owns the sampler and
+ * the other half is clamp or linear. `[Wrap(Repeat)]` and `[Filter(Point)]`
+ * in a `.sl` file.
+ */
+export interface TextureSamplingOptions {
+    wrap?: TextureWrap
+    filter?: TextureFilter
+}
+
+export function texture(name: string, sampling: TextureSamplingOptions = {}): Texture {
     const b = ctx()
-    const slot = b.texture(name)
+    const slot = b.texture(name, sampling)
     return {
         sample(uv: Vec2): Vec4 {
             if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
@@ -1060,6 +1084,16 @@ export function texture(name: string): Texture {
             }
             return mk(b, b.call(SLOP.SAMPLE_LOD, TYPE.VEC4, [uv.ref, typeof level === "number" ? level : level.ref], [slot]), TYPE.VEC4)
         },
+        size(): Vec2 {
+            return mk(b, b.call(SLOP.TEXTURE_SIZE, TYPE.VEC2, [], [slot]), TYPE.VEC2)
+        },
+        fetch(pixel: Vec2): Vec4 {
+            if (pixel.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+            if (pixel.width !== TYPE.VEC2 || pixel.kind !== undefined) {
+                throw new SLError(`a texel is fetched at a float2 pixel, and this is ${pixel.kind === undefined ? `a ${widthName(pixel.width)}` : `an ${pixel.kind}`}`)
+            }
+            return mk(b, b.call(SLOP.SAMPLE_FETCH, TYPE.VEC4, [pixel.ref], [slot]), TYPE.VEC4)
+        },
     }
 }
 

package/src/tables.ts

@@ -16,9 +16,11 @@ export type { SLSurface } from "./ops"
 export { DERIVED_INPUTS, INPUTS, PREVIOUS, SOURCE_INPUTS, STEP_INPUTS } from "./ir"
 export type { DerivedInputName, HostInputName, InputName, SourceInputName, StepInputName } from "./ir"
 export { SL_SDF_SHAPES, SL_SDF_PARAMS } from "./shapes"
-export { ATTRIBUTE_DOCS, BUILTIN_DOCS, BUILTIN_PARAMS, INPUT_DOCS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES } from "./params"
-export { ATTRIBUTE_NAMES } from "./lang/attributes"
-export type { AttributeName } from "./lang/attributes"
+export {
+    ATTRIBUTE_DOCS, BUILTIN_DOCS, BUILTIN_PARAMS, INPUT_DOCS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES, TEXTURE_ATTRIBUTE_DOCS,
+} from "./params"
+export { ATTRIBUTE_NAMES, TEXTURE_ATTRIBUTE_NAMES } from "./lang/attributes"
+export type { AttributeName, TextureAttributeName } from "./lang/attributes"
 export { PRELUDE_DOCS, PRELUDE_NAMES } from "./lang/prelude-source"
 export { SL_KEYWORDS, SL_TYPES } from "./lang/words"
 export { TYPE_WIDTH } from "./lang/ast"

package/src/web.ts

@@ -14,11 +14,23 @@
  *
  *   sl_Res   (target width, target height, seconds, frame)
  *   sl_Opt   (1 in a Linear colour space project else 0, 1 to flip uv.y, deltaTime, 0)
- *   sl_U[16] uniform slots, each a vec4, in the program's slot order
+ *   sl_U     uniform slots, each a vec4, in the program's slot order: 16 of
+ *            them, or WEB_UNIFORM_SLOTS for a program with more than 16
+ *            uniforms. A host fills WEB_UNIFORM_SLOTS whatever the program
+ *            declares, which both languages allow.
  *   textures by slot: GLSL `sl_Tex<slot>`; WGSL `sl_tex<slot>` at binding
  *            2 + 2 * slot with its own sampler `sl_samp<slot>` at 1 + 2 * slot,
  *            all in group 0 beside the frame block at binding 0. Only the
- *            slots the program samples are declared.
+ *            slots the program reads are declared, and in WGSL a slot's
+ *            sampler only when the program samples it, rather than only
+ *            measuring it (`textureSize`) or fetching from it (`tex2Dfetch`).
+ *   a texture's sampler, when its program sets one (`[Wrap(Repeat)]`,
+ *            `[Filter(Point)]`, IR 6): its declaration line ends
+ *            `// sampler <wrap> <filter>`, the sampler's in WGSL and the
+ *            sampler2D's in GLSL, wrap one of repeat, clamp, mirror and filter
+ *            point or linear. The host samples that slot so, whatever the
+ *            bound texture's own settings; with no such comment, as those
+ *            settings say. `samplingOf` in ir.ts says what each word means.
  *   the previous frame, only for a program that samples it: GLSL `sl_Prev`;
  *            WGSL `sl_prev` with its sampler `sl_prevSamp`, at the two
  *            bindings after the last texture slot's, whatever the program
@@ -34,7 +46,7 @@
  */
 
 import { INT_LIMITS } from "./body"
-import { SLError, TYPE, isWhole, valueAt, type NodeRef, type Program, type SLKind, type SLType, type ValueNode } from "./ir"
+import { SLError, TYPE, isWhole, samplingOf, valueAt, type NodeRef, type Program, type TextureDecl, type SLKind, type SLType, type ValueNode } from "./ir"
 import { inVaryingFlow, local, printBody, structure, type Syntax } from "./structure"
 import { libClosure, libIndex, LIB_FUNCTIONS, SDF_CALLS } from "./lib"
 import { LIB_GLSL } from "./lib/glsl"
@@ -43,9 +55,21 @@ import { INPUT_ID, SLOP, TEXTURE_SLOTS, UNIFORM_SLOTS } from "./ops"
 
 export type WebLanguage = "glsl" | "wgsl"
 
-/** Uniform slots the host always provides, so every program shares one layout. */
+/** Uniform slots a host provides, so one buffer fits every program. */
 export const WEB_UNIFORM_SLOTS = UNIFORM_SLOTS
 
+/**
+ * The block a program with 16 uniforms or fewer declares: the size it had
+ * before onejs-sl 0.9 raised the cap. A WebGPU host before then (OneJS 3.9.8)
+ * binds a buffer of exactly this many slots, which a larger block fails to
+ * validate against, so a program that fits keeps drawing there.
+ */
+const BASE_UNIFORM_SLOTS = 16
+
+function uniformBlock(p: Program): number {
+    return p.uniforms.length > BASE_UNIFORM_SLOTS ? WEB_UNIFORM_SLOTS : BASE_UNIFORM_SLOTS
+}
+
 export function emitGLSL(p: Program): string {
     return emitWeb(p, "glsl")
 }
@@ -59,9 +83,12 @@ function emitWeb(p: Program, lang: WebLanguage): string {
     const need = new Set<number>()
     const smoothsteps = new Set<SLType>()
     const sampled = new Set<number>()
+    /** Slots read without a sampler: measured or fetched from. */
+    const loaded = new Set<number>()
     /** Whether the body samples the previous frame, which declares its binding. */
     let previous = false
     const shape = structure(p)
+    const size = (slot: number) => W ? `vec2f(textureDimensions(sl_tex${slot}))` : `vec2(textureSize(sl_Tex${slot}, 0))`
     const T = (t: SLType) => (W ? (t === 1 ? "f32" : `vec${t}f`) : t === 1 ? "float" : `vec${t}`)
     /** A value's type in this language, its kind included. */
     const typeName = (n: { type: SLType; kind?: SLKind }): string => {
@@ -272,6 +299,20 @@ function emitWeb(p: Program, lang: WebLanguage): string {
                 const below = `floor(${a[1]})`
                 return `mix(${at(below)}, ${at(`${below} + 1.0`)}, fract(${a[1]}))`
             }
+            case SLOP.TEXTURE_SIZE: {
+                const slot = Math.round(imm[0] ?? 0)
+                loaded.add(slot)
+                return size(slot)
+            }
+            case SLOP.SAMPLE_FETCH: {
+                const slot = Math.round(imm[0] ?? 0)
+                loaded.add(slot)
+                // Floored and held inside, as the HLSL body does: a load out of
+                // range is undefined in GLSL and implementation defined in WGSL.
+                return W
+                    ? `textureLoad(sl_tex${slot}, vec2i(clamp(floor(${a[0]}), vec2f(0.0), ${size(slot)} - 1.0)), 0)`
+                    : `texelFetch(sl_Tex${slot}, ivec2(clamp(floor(${a[0]}), vec2(0.0), ${size(slot)} - 1.0)), 0)`
+            }
             case SLOP.SAMPLE_PREVIOUS:
                 previous = true
                 // Flipped as this frame flipped the uv it wrote at, so a read at
@@ -363,21 +404,26 @@ function emitWeb(p: Program, lang: WebLanguage): string {
     const body = printBody(p, shape, syntax, expr, "    ").join("\n")
     const library = [...[...smoothsteps].sort().map((w) => smoothstep(w, lang)), ...librarySource(need, lang)].join("\n")
     const header = `// GENERATED from a shader language program (${p.hash}). Do not edit.`
-    // Only the textures the program samples. WebGPU's automatic layout leaves
-    // out a binding the shader never reads, and a bind group that supplies one
-    // anyway does not validate; the host reads these declarations back to know
-    // which slots to bind.
-    const textures = p.textures.filter((t) => sampled.has(t.slot))
+    // Only the textures the program reads, and in WGSL only the samplers it
+    // samples with. WebGPU's automatic layout leaves out a binding the shader
+    // never reads, and a bind group that supplies one anyway does not
+    // validate; the host reads these declarations back to know what to bind.
+    const textures = p.textures.filter((t) => sampled.has(t.slot) || loaded.has(t.slot))
+    /** The comment that says a texture's sampler is the program's own, for a slot it samples. */
+    const samplerNote = (t: TextureDecl) => {
+        const s = sampled.has(t.slot) ? samplingOf(t) : null
+        return s === null ? "" : ` // sampler ${s.wrap} ${s.filter}`
+    }
 
     if (W) {
         const bindings = [...textures.map((t) =>
-            `@group(0) @binding(${1 + 2 * t.slot}) var sl_samp${t.slot}: sampler;\n` +
+            (sampled.has(t.slot) ? `@group(0) @binding(${1 + 2 * t.slot}) var sl_samp${t.slot}: sampler;${samplerNote(t)}\n` : "") +
             `@group(0) @binding(${2 + 2 * t.slot}) var sl_tex${t.slot}: texture_2d<f32>;`),
         ...previous ? [
             `@group(0) @binding(${1 + 2 * TEXTURE_SLOTS}) var sl_prevSamp: sampler;\n` +
             `@group(0) @binding(${2 + 2 * TEXTURE_SLOTS}) var sl_prev: texture_2d<f32>;`] : []].join("\n")
         return `${header}
-struct SLFrame { res: vec4f, opt: vec4f, u: array<vec4f, ${WEB_UNIFORM_SLOTS}> }
+struct SLFrame { res: vec4f, opt: vec4f, u: array<vec4f, ${uniformBlock(p)}> }
 @group(0) @binding(0) var<uniform> sl: SLFrame;
 ${bindings}
 ${library}
@@ -393,14 +439,14 @@ ${body}
 }
 `
     }
-    const samplers = [...textures.map((t) => `uniform sampler2D sl_Tex${t.slot};`), ...previous ? ["uniform sampler2D sl_Prev;"] : []].join("\n")
+    const samplers = [...textures.map((t) => `uniform sampler2D sl_Tex${t.slot};${samplerNote(t)}`), ...previous ? ["uniform sampler2D sl_Prev;"] : []].join("\n")
     return `#version 300 es
 ${header}
 precision highp float;
 precision highp int;
 uniform vec4 sl_Res;
 uniform vec4 sl_Opt;
-uniform vec4 sl_U[${WEB_UNIFORM_SLOTS}];
+uniform vec4 sl_U[${uniformBlock(p)}];
 ${samplers}
 out vec4 sl_Out;
 ${library}