@solidrt/core 0.0.70 → 0.0.71

package/agents/performance.md

@@ -102,7 +102,12 @@ Rules, in order of leverage:
    boundary node itself (or any ancestor) are hoisted out of the cache and
    applied at composite time, so animating x/y/scale/rotate/opacity of a
    boundary does NOT re-raster it (verified by A/B measurement - the damage
-   system classifies these as Transform and keeps the node's own cache).
+   system classifies these as Compose and keeps the node's own cache). One
+   exception, for crispness: a boundary holding text that comes to rest at
+   a new scale re-records once there (a snapshot boundary re-rasterizes
+   once), so its content is rasterized at the resting size instead of
+   stretched, and a scale transition with a known end rasters for that end
+   as it starts; a press scale that returns to 1 never re-rasters.
    What DOES invalidate the cache is any paint or content change inside the
    subtree - colors, path data, text, a Show toggling - so drive animation
    with transforms and keep the cached content itself static. Off a boundary,

package/examples/README.md

@@ -51,6 +51,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `gpu-texture-blend.tsx` - compositing two shader targets as stacked `<texture>` layers with `blendMode` ("plus" additive over a base pass), the alternative to a third shader that samples both. Click toggles against `"source-over"` to show why. The tree-level counterpart to blending within one draw (`gpu-particles.tsx`); without `blend: "add"` a target's own draw runs with GL blending disabled.
 - `gpu-raw-program.tsx` - the raw shading layer: compileShader/linkProgram/createRenderPipeline/createShaderTarget, one vertex stage shared by two programs, with and without the standard header.
 - `gpu-pipeline.tsx` - `createPipelineTexture`: a custom vertex+fragment pair drawing an interleaved vertex buffer (position and color attributes resolved by name), a depth-tested spinning cube whose `uTime` uniform is driven through `<texture params>` exactly like a fragment shader's.
+- `gpu-shader-chain.tsx` - a chain of targets: a plasma `createShaderTexture` bound as a cube `createPipelineTexture`'s sampler input (`textures: { uMap: plasmaId }`). Sampler bindings are live dependencies, so the app drives only the plasma's `uTime` and the cube re-renders after it every frame, in that order, with no uniform and no per-frame code of its own. The plasma shows beside the cube on the `<texture>` that carries its params.
 - `gpu-particles.tsx` - an additive particle field: `topology: "points"` with `blend: "add"`, so overlapping gaussian splats (`gl_PointSize` from the vertex stage, `gl_PointCoord` falloff, premultiplied output) accumulate into a glowing volume instead of overwriting. The tints are typed vec3 uniforms filled from 3-number array params.
 - `gpu-instancing.tsx` - instanced drawing: one 3-vertex triangle drawn hundreds of times via `instanceCount`, each instance placed and tinted on a phyllotaxis spiral from `gl_InstanceID` alone. `setDraw(id, { instanceCount })` merges into the draw range per frame (absent keys keep their values, like params), so the population breathes without touching the buffer.
 - `gpu-draw-list.tsx` - `createDrawTarget`: one render target holding an ordered, mutable LIST of draws - two orbiting triangles from different programs sharing one depth buffer (the target owns the depth storage, each pipeline the test/write behavior), a third entry added and removed live via its stable `DrawId`, and `setDrawParams` as the per-object channel.

package/examples/gpu-shader-chain.tsx

@@ -0,0 +1,135 @@
+// A chain of targets: a plasma fragment pass feeding a cube pipeline that
+// samples it. Sampler bindings are live dependencies (the model in
+// @solidrt/core/docs/reference/gpu.md): the cube's target is bound to the
+// plasma's through `textures`, so whenever the plasma re-renders, the cube
+// re-renders after it in the same frame, in that order. The app therefore
+// drives only the first pass: the plasma's uTime through the <texture>
+// params prop, as in gpu-shader.tsx. The cube has no uniform of its own
+// and no per-frame code; its view is fixed in the vertex shader, and its
+// faces move because what they sample moves.
+//
+// The plasma is shown beside the cube because that <texture> is where its
+// params prop lives. A source pass that is not on screen is driven the same
+// way from any <texture> of its id. The cube's buffers and index buffer are
+// the gpu-pipeline.tsx mesh with a UV per corner in place of a color.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createBuffer, createPipelineTexture, createShaderTexture, glsl } from "@solidrt/core/gpu"
+
+// The plasma target's side: what the cube's faces sample.
+let PLASMA_SIZE = 256
+// The cube target's side: what the window shows.
+let CUBE_SIZE = 512
+
+// Pass 1: a plasma, the only thing the app animates.
+let PLASMA = glsl`
+  uniform float uTime;
+  void main() {
+    vec2 uv = vUV * 6.0;
+    float t = uTime;
+    float v = sin(uv.x + t) + sin(uv.y + t * 0.8) + sin((uv.x + uv.y) * 0.7 + t * 1.3)
+      + sin(length(uv - 3.0) * 1.5 - t);
+    vec3 col = 0.5 + 0.5 * cos(v * 1.2 + vec3(0.0, 2.1, 4.2));
+    fragColor = vec4(col, 1.0);
+  }
+`
+
+// Pass 2: the cube, viewed from one fixed angle. The projection rig and the
+// clip-y flip are gpu-pipeline.tsx's.
+let VERTEX = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vTex;
+
+  void main() {
+    float cy = cos(0.7), sy = sin(0.7);
+    float cx = cos(0.5), sx = sin(0.5);
+    mat3 rotY = mat3(cy, 0.0, -sy, 0.0, 1.0, 0.0, sy, 0.0, cy);
+    mat3 rotX = mat3(1.0, 0.0, 0.0, 0.0, cx, sx, 0.0, -sx, cx);
+    vec3 p = rotX * (rotY * aPos);
+    p.z -= 2.5;
+    float w = -p.z;
+    float f = 2.0;
+    float a = 11.0 / 9.0;
+    float b = -20.0 / 9.0;
+    gl_Position = vec4(p.x * f, -p.y * f, w * a + b, w);
+    vTex = aUV;
+  }
+`
+
+// The sampler is the chain: uMap is bound to the plasma target below.
+let FRAGMENT = glsl`
+  in vec2 vTex;
+  uniform sampler2D uMap;
+  void main() {
+    fragColor = texture(uMap, vTex);
+  }
+`
+
+// Interleaved [pos vec3, uv vec2]: 24 vertices, 4 per face, each face the
+// whole plasma once. Every face winds counter-clockwise seen from outside.
+function cubeVertices(): Float32Array {
+  type Vec3 = [number, number, number]
+  let verts: number[] = []
+  let quad = (a: Vec3, b: Vec3, c: Vec3, d: Vec3) => {
+    let uvs = [[0, 1], [1, 1], [1, 0], [0, 0]]
+    for (let [i, p] of [a, b, c, d].entries()) verts.push(p[0], p[1], p[2], uvs[i]![0]!, uvs[i]![1]!)
+  }
+  let s = 0.5
+  quad([-s, -s, s], [s, -s, s], [s, s, s], [-s, s, s]) // front
+  quad([s, -s, -s], [-s, -s, -s], [-s, s, -s], [s, s, -s]) // back
+  quad([s, -s, s], [s, -s, -s], [s, s, -s], [s, s, s]) // right
+  quad([-s, -s, -s], [-s, -s, s], [-s, s, s], [-s, s, -s]) // left
+  quad([-s, s, s], [s, s, s], [s, s, -s], [-s, s, -s]) // top
+  quad([-s, -s, -s], [s, -s, -s], [s, -s, s], [-s, -s, s]) // bottom
+  return new Float32Array(verts)
+}
+
+// Two triangles per face over its 4 shared vertices: 36 uint16 indices.
+function cubeIndices(): Uint16Array {
+  let indices: number[] = []
+  for (let face = 0; face < 6; face++) {
+    let v = face * 4
+    indices.push(v, v + 1, v + 2, v, v + 2, v + 3)
+  }
+  return new Uint16Array(indices)
+}
+
+function App() {
+  let plasmaId = createShaderTexture(PLASMA, PLASMA_SIZE, PLASMA_SIZE, { uTime: 0 }, { label: "plasma" })
+  let bufferId = createBuffer(cubeVertices(), { label: "cube-verts" })
+  let indexId = createBuffer(cubeIndices(), { label: "cube-indices" })
+  // No params: nothing of the cube's is ever written. Its one input is the
+  // plasma target, and that binding is what re-renders it.
+  let cubeId = createPipelineTexture(VERTEX, FRAGMENT, CUBE_SIZE, CUBE_SIZE, null, {
+    label: "cube",
+    textures: { uMap: plasmaId },
+    buffers: [
+      {
+        attributes: [
+          { name: "aPos", format: "float32x3" },
+          { name: "aUV", format: "float32x2" },
+        ],
+        buffer: bufferId,
+      },
+    ],
+    indexBuffer: indexId,
+    indexFormat: "uint16",
+    depth: true,
+    cull: "back",
+    clearColor: [0.08, 0.08, 0.12, 1],
+  })
+  let [time, setTime] = createSignal(0)
+  onFrame((tick) => setTime(tick / 1000))
+
+  return (
+    <window alignItems="center" justifyContent="center" flexDirection="row" gap={24}>
+      <texture src={cubeId} width={CUBE_SIZE} height={CUBE_SIZE} />
+      <view flexDirection="column" alignItems="center" gap={8}>
+        <texture src={plasmaId} params={{ uTime: time() }} width={PLASMA_SIZE} height={PLASMA_SIZE} />
+        <text fontSize={14} color="#888">the plasma pass, the only one driven</text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.70",
+  "version": "0.0.71",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -33,8 +33,8 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.70",
-    "@solidrt/test": "0.0.70"
+    "@solidrt/flux-types": "0.0.71",
+    "@solidrt/test": "0.0.71"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",

package/src/core.ts

@@ -391,15 +391,18 @@ export function prepareText(text: string, options?: tree.MeasureTextOptions): tr
 }
 
 /**
- * Makes the glyph cells of printable ASCII for these font styles ahead of
- * their first use, off the frame: call it at startup with the type scale
- * the app draws in (the components' Window does it for the theme's), so a
- * screen's first paint in any of them never waits for cells. Glyphs outside
- * ASCII are made at first use. Each entry names a font as a <text> would;
- * line height and maxLines are ignored.
+ * Makes glyph cells ahead of their first use, off the frame: call it at
+ * startup with the type scale the app draws in (the components' Window
+ * does it for the theme's), so a screen's first paint in any of them never
+ * waits for cells. Each entry names a font as a <text> would (line height
+ * and maxLines are ignored) and warms its printable ASCII; an entry with a
+ * `text` also warms the glyphs that string shapes to in the font (a
+ * ligature, a curly quote, a letter beyond ASCII), so a headline or a
+ * label the app knows it will draw is warm too. Anything else is made at
+ * first use.
  */
-export function warmText(styles: tree.MeasureTextOptions[]): void {
-  tree.warmText(styles)
+export function warmText(entries: tree.WarmTextEntry[]): void {
+  tree.warmText(entries)
 }
 
 export type TextRenderingOptions = tree.TextRenderingOptions

package/src/gpu.ts

@@ -753,6 +753,128 @@ export function writeBuffer(id: gpu.BufferId, data: ArrayBuffer | ArrayBufferVie
   gpu.writeBuffer(id, toUint8(data), byteOffset)
 }
 
+/**
+ * A stream of fixed-size records with a GPU buffer, a CPU mirror and a
+ * dirty range: the publish model shared by every JS-stepped population
+ * (a 2d sprite layer's records, a 3d mesh's instance streams). Write the
+ * mirror, `mark` the records written, then `publish` at the flush: the
+ * dirty range goes out as one `writeBuffer` at its byte offset, or the
+ * drawn prefix whole through the write lease when the buffer carries an
+ * instance order (the engine gathers the copy into key order, and a byte
+ * range has no stable position under a permutation). Growth replaces the
+ * buffer and the mirror (never a resize) and marks what the mirror held,
+ * so the next publish fills the replacement; the old buffer is the
+ * caller's to destroy once nothing binds it. Read `buffer` and `bytes` at
+ * use time: both are replaced by growth.
+ */
+export type RecordStream = {
+  /** The GPU buffer the records publish to; replaced by `grow`. */
+  readonly buffer: gpu.BufferId
+  /** The mirror, `capacity * stride` bytes; replaced by `grow`. View it as
+   * the record layout wants (a Float32Array over it for an all-float
+   * record). */
+  readonly bytes: Uint8Array<ArrayBuffer>
+  /** Bytes per record. */
+  readonly stride: number
+  /** Records the mirror and the buffer hold. */
+  readonly capacity: number
+  /** Whether any record is marked since the last publish. */
+  readonly dirty: boolean
+  /** Extend the dirty range over records [first, last). */
+  mark(first: number, last: number): void
+  /** Send what is dirty and clear the mark. `whole`: the first `limit`
+   * records go out through the lease regardless of the range (the
+   * ordered form, and a replacement buffer's first fill); otherwise the
+   * dirty range, clipped to `limit` records (the live sprites, or the
+   * capacity when records are written ahead of their count). Nothing is
+   * sent for an empty range or a zero `limit`. */
+  publish(whole: boolean, limit: number): void
+  /** Replace the buffer and the mirror with room for `capacity` records,
+   * the old contents copied over and marked whole; returns the OLD buffer
+   * for the caller to destroy once its draws point at the new one. */
+  grow(capacity: number): gpu.BufferId
+  /** Free the buffer. Safe to call more than once. */
+  destroy(): void
+}
+
+/**
+ * Creates a record stream of `capacity` records of `stride` bytes (see
+ * {@link RecordStream}): a sized, unwritten GPU buffer and a zeroed
+ * mirror. Freed with the reactive owner like a buffer (opt out with
+ * `{ autoFree: false }` and call `destroy`).
+ */
+export function createRecordStream(stride: number, capacity: number, opts?: CreateOptions): RecordStream {
+  if (!(Number.isInteger(stride) && stride > 0)) throw new Error("createRecordStream: stride must be a positive integer, got " + stride)
+  if (!(Number.isInteger(capacity) && capacity > 0)) throw new Error("createRecordStream: capacity must be a positive integer, got " + capacity)
+  let buffer = createBuffer(capacity * stride, { label: opts?.label, autoFree: false })
+  let bytes = new Uint8Array(capacity * stride)
+  let dirty: [number, number] | null = null
+  let destroyed = false
+  let stream: RecordStream = {
+    get buffer() {
+      return buffer
+    },
+    get bytes() {
+      return bytes
+    },
+    stride,
+    get capacity() {
+      return bytes.length / stride
+    },
+    get dirty() {
+      return dirty !== null
+    },
+    mark(first, last) {
+      let capacity = bytes.length / stride
+      if (!Number.isInteger(first) || !Number.isInteger(last) || first < 0 || last > capacity || first > last) {
+        throw new Error("RecordStream.mark: range [" + first + ", " + last + ") is outside the stream's " + capacity + " records")
+      }
+      if (first === last) return
+      if (dirty === null) dirty = [first, last]
+      else {
+        if (first < dirty[0]) dirty[0] = first
+        if (last > dirty[1]) dirty[1] = last
+      }
+    },
+    publish(whole, limit) {
+      let range = dirty
+      dirty = null
+      if (whole) {
+        let byteLength = Math.min(limit, bytes.length / stride) * stride
+        if (byteLength <= 0) return
+        let out = beginBufferWrite(buffer)
+        new Uint8Array(out.buffer, 0, byteLength).set(bytes.subarray(0, byteLength))
+        gpu.endBufferWrite(buffer, byteLength)
+        return
+      }
+      if (range === null) return
+      let lo = range[0]
+      let hi = Math.min(range[1], limit)
+      if (hi > lo) writeBuffer(buffer, bytes.subarray(lo * stride, hi * stride), lo * stride)
+    },
+    grow(next) {
+      let previous = bytes.length / stride
+      if (!(Number.isInteger(next) && next > previous)) {
+        throw new Error("RecordStream.grow: capacity must be an integer above the current " + previous + ", got " + next)
+      }
+      let old = buffer
+      buffer = createBuffer(next * stride, { label: opts?.label, autoFree: false })
+      let grown = new Uint8Array(next * stride)
+      grown.set(bytes)
+      bytes = grown
+      dirty = [0, previous]
+      return old
+    },
+    destroy() {
+      if (destroyed) return
+      destroyed = true
+      gpu.destroyBuffer(buffer)
+    },
+  }
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => stream.destroy())
+  return stream
+}
+
 /**
  * Hands an ordered instance buffer's full record set to the engine - the
  * write-once form: the engine keeps the one CPU copy and sorts,

package/src/index.ts

@@ -94,7 +94,7 @@ export type {
   Color,
   Pct,
 } from "./types"
-export type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit } from "flux:rendertree"
+export type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit, WarmTextEntry } from "flux:rendertree"
 
 // A percentage value for dimensional props (e.g. transformOrigin): `pct(50)` is
 // half the element box. Keeps percentages a first-class branded value rather