@solidrt/2d 0.0.70 → 0.0.71

package/AGENTS.md

@@ -267,7 +267,20 @@ mark their own record, so a `setSprite` here publishes one record, not
 the prefix. The POPULATION verbs differ by kind and stay so: a record
 mesh's records are opaque data (`setRecords` copies in and grows), a
 record layer's are sprites (`addSprite`/`destroySprite`), so the copy-in
-here is `records(layer).set(src)` then `updateRecords(layer)`. It is the
+here is `records(layer).set(src)` then `updateRecords(layer)`. The
+publish itself is the core's record stream (`createRecordStream` in
+`@solidrt/core/gpu`: the GPU buffer, the byte mirror, the dirty range,
+the range-or-whole publish, growth into a replacement), the one model
+the 3d instance streams run on too; this file only decides what to
+mark and when to flush. The node layer speaks the same two verbs over
+its STYLE records: `records(spriteLayer)` is the style mirror
+(`STYLE_FLOATS` floats per slot: `[u0, v0, u1, v1, tint rgba,
+renderOrder, minScreenPx, maxScreenPx, atlas, outline rgb,
+outlineWidth]`, slot-indexed, poses stay the core's) and
+`updateRecords(spriteLayer, { first?, count? })` publishes the slot
+range, so a bulk restyle (a palette cycle over thousands of sprites) is
+one loop and one range write instead of a setSprite each - the 3d
+`records(instancedMesh)` pairing, one dimension down. It is the
 escape hatch for motion only JS can compute at scale (measured 30k
 sprites: 12.9ms raw records vs 30.8ms via setSprite; both figures are
 the WRITE path only - whatever computes the motion is excluded and is

package/package.json

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

package/src/layer.ts

@@ -35,8 +35,8 @@
 // (dispatch.ts) undoes it with unprojectCamera.
 import { getOwner, onBeforeRender, onCleanup, runWithOwner } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
-import { beginBufferWrite, checkScreenSize, createBuffer, destroyBuffer, endBufferWrite, screenSizeScale } from "@solidrt/core/gpu"
-import type { BlendMode, BufferId, TextureId } from "@solidrt/core/gpu"
+import { checkScreenSize, createBuffer, createRecordStream, destroyBuffer, screenSizeScale } from "@solidrt/core/gpu"
+import type { BlendMode, BufferId, RecordStream, TextureId } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type {
   Impact as CoreImpact,
@@ -591,6 +591,13 @@ export type LayerBase = {
   _read(sprite: Sprite): Required<SpriteOptions>
   _destroy(sprite: SpriteState): void
   _schedule(): void
+  /** The layer's JS-owned record stream, what records()/updateRecords
+   * read and mark: a records layer's whole records, a node layer's style
+   * records (its poses are the core's). Internal. */
+  _stream: RecordStream
+  /** The stream's mirror as floats, re-pointed by growth; records() hands
+   * it out. Internal. */
+  _records: Float32Array
 }
 
 /** A query volume for overlap/sweep/moveAndSlide, in layer pixels: a
@@ -827,7 +834,12 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   let tint = opts?.tint ?? [1, 1, 1, 1]
   checkTint("createSpriteLayer", tint)
   let pose: BufferId = createBuffer(capacity * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
-  let style: BufferId = createBuffer(capacity * STYLE_FLOATS * 4, { label: `${label}-style`, autoFree: false })
+  // The style records: JS-written through the sprite verbs (writeStyle),
+  // records()/updateRecords for a bulk restyle, published by the flush as
+  // the dirty slot range, or the used prefix whole under an order (the
+  // core gathers both buffers under the one permutation).
+  let style = createRecordStream(STYLE_FLOATS * 4, capacity, { label: `${label}-style`, autoFree: false })
+  let ordered = opts?.orderBy !== undefined
   let gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_LAYOUTS_SPLIT, opts?.blend ?? "alpha", atlases)
   // The sprites with a screen-size clamp (either bound on), and the
   // furthest any of them reaches from its center at its floor (floorReach,
@@ -853,7 +865,6 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
 
   let disposed = false
   let scheduled = false
-  let styleDirty = false
   let published = 0
   // The publish pass of every frame runs the pending flush ahead of the
   // paint, so a write made anywhere in the frame's JS is in that frame's
@@ -878,7 +889,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   // slot stays taken until the core says it is gone; dispose frees them.
   let leaving = new Set<NodeId>()
   let gpuCapacity = capacity
-  let styleData = new Float32Array(capacity * STYLE_FLOATS)
+  let styleData = new Float32Array(style.bytes.buffer)
   let byNode = new Map<NodeId, SpriteState>()
   // The layer's root node (identity): parentless sprites and groups hang
   // off it, so a query scoped to it sees exactly this layer.
@@ -909,12 +920,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   let flush = () => {
     scheduled = false
     if (disposed) return
-    if (styleDirty) {
-      styleDirty = false
-      let out = beginBufferWrite(style)
-      out.set(styleData.subarray(0, highWater * STYLE_FLOATS))
-      endBufferWrite(style, highWater * STYLE_FLOATS * 4)
-    }
+    if (style.dirty) style.publish(ordered, highWater)
     if (published !== highWater) {
       views.setCount(highWater)
       published = highWater
@@ -926,23 +932,19 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
 
   // Grow both instance buffers to `next` slots: the pose sinks move in one
   // retargetRecords call (the whole used range republishes at the next
-  // flush), the style mirror grows in JS and republishes through the lease.
-  // The entries hold the old buffers alive until the swaps land, so the
-  // destroys are safe to issue right after.
+  // flush), the style stream grows into a replacement marked whole, which
+  // the next flush publishes. The entries hold the old buffers alive until
+  // the swaps land, so the destroys are safe to issue right after.
   let grow = (next: number) => {
     let newPose = createBuffer(next * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
-    let newStyle = createBuffer(next * STYLE_FLOATS * 4, { label: `${label}-style`, autoFree: false })
     spatial.retargetRecords(pose, newPose)
-    let grownStyle = new Float32Array(next * STYLE_FLOATS)
-    grownStyle.set(styleData)
-    styleData = grownStyle
-    views.setBuffers([newPose, newStyle])
+    let oldStyle = style.grow(next)
+    styleData = new Float32Array(style.bytes.buffer)
+    views.setBuffers([newPose, style.buffer])
     destroyBuffer(pose)
-    destroyBuffer(style)
+    destroyBuffer(oldStyle)
     pose = newPose
-    style = newStyle
     gpuCapacity = next
-    styleDirty = true
   }
 
   // A frame's atlas index, or a throw: run before ANY field of a write
@@ -956,6 +958,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
 
   let writeStyle = (sprite: SpriteState, opts: SpriteOptions, atlas: number) => {
     let at = sprite._slot * STYLE_FLOATS
+    let changed = false
     let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
     let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
     if (flipX) sprite._flipX = !sprite._flipX
@@ -964,31 +967,32 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       let f = opts.frame
       writeFrame(styleData, at, f.u0, f.v0, f.u1, f.v1, sprite._flipX, sprite._flipY)
       styleData[at + STYLE_ATLAS_FIELD] = atlas
-      styleDirty = true
+      changed = true
     } else if (flipX || flipY) {
       // No new frame: toggle the changed axes on the stored UVs.
       writeFrame(styleData, at, styleData[at]!, styleData[at + 1]!, styleData[at + 2]!, styleData[at + 3]!, flipX, flipY)
-      styleDirty = true
+      changed = true
     }
     if (opts.tint !== undefined) {
       styleData[at + 4] = opts.tint[0]
       styleData[at + 5] = opts.tint[1]
       styleData[at + 6] = opts.tint[2]
       styleData[at + 7] = opts.tint[3]
-      styleDirty = true
+      changed = true
     }
     if (opts.renderOrder !== undefined) {
       styleData[at + STYLE_KEY_FIELD] = opts.renderOrder
-      styleDirty = true
+      changed = true
     }
     if (opts.minScreenPx !== undefined) {
       styleData[at + STYLE_MIN_PX_FIELD] = opts.minScreenPx
-      styleDirty = true
+      changed = true
     }
     if (opts.maxScreenPx !== undefined) {
       styleData[at + STYLE_MAX_PX_FIELD] = opts.maxScreenPx
-      styleDirty = true
+      changed = true
     }
+    if (changed) style.mark(sprite._slot, sprite._slot + 1)
     let min = styleData[at + STYLE_MIN_PX_FIELD]!
     if (min > 0 || styleData[at + STYLE_MAX_PX_FIELD]! > 0) {
       clamped.add(sprite)
@@ -1005,7 +1009,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     pipeline: gpu.pipeline,
     quad: gpu.quad,
     atlases: atlases.map(a => a.texture),
-    buffers: () => [pose, style],
+    buffers: () => [pose, style.buffer],
     count: () => published,
     tint: () => tint,
     pick: (x, y, zoom) => layer.pick(x, y, zoom),
@@ -1195,7 +1199,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       spatial.flush()
       views.dispose()
       destroyBuffer(pose)
-      destroyBuffer(style)
+      style.destroy()
       gpu.dispose()
     },
     _add(opts) {
@@ -1257,7 +1261,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       styleData[at + 1] = g
       styleData[at + 2] = b
       styleData[at + 3] = width
-      styleDirty = true
+      style.mark(sprite._slot, sprite._slot + 1)
       layer._schedule()
     },
     _write(sprite, opts) {
@@ -1287,7 +1291,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       ) {
         writeStyle(sprite, opts, atlas)
       }
-      if (moved || styleDirty) layer._schedule()
+      if (moved || style.dirty) layer._schedule()
     },
     _read(sprite) {
       let at = sprite._slot * STYLE_FLOATS
@@ -1354,6 +1358,10 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     },
     _groups: new Set(),
     _root: root,
+    _stream: style,
+    get _records() {
+      return styleData
+    },
   }
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
   return layer

package/src/records.ts

@@ -5,12 +5,14 @@
 // algorithm, later over earlier; `orderBy` swaps that for a core-produced
 // key order at publish, records untouched); mutations batch, and the flush
 // (ahead of the frame's paint, or at a microtask outside a frame)
-// publishes what changed: the dirty record range as one buffer write, or
-// under `orderBy` the drawn prefix whole through the zero-copy write lease
-// (the core gathers it into key order during the copy, and a byte range
-// has no stable position under a permutation). A moved sprite is 20 float
-// stores plus its share of one memcpy per dirty frame; a static layer
-// publishes nothing and therefore costs nothing.
+// publishes what changed through the core's record stream
+// (`createRecordStream` in @solidrt/core/gpu, the publish model every
+// JS-stepped population shares): the dirty record range as one buffer
+// write, or under `orderBy` the drawn prefix whole through the zero-copy
+// write lease (the core gathers it into key order during the copy, and a
+// byte range has no stable position under a permutation). A moved sprite
+// is 20 float stores plus its share of one memcpy per dirty frame; a
+// static layer publishes nothing and therefore costs nothing.
 //
 // The record vocabulary is @solidrt/3d's record mesh's, one dimension
 // down: `records(layer)` is the mirror, `updateRecords(layer, { first?,
@@ -32,13 +34,13 @@
 // (addSprite/setSprite/...) are shared with the node layer; picking here is
 // the JS reverse walk (pointInSprite), since records have no nodes.
 import { getOwner, onBeforeRender, onCleanup, runWithOwner } from "@solidrt/core"
-import { beginBufferWrite, checkScreenSize, createBuffer, destroyBuffer, endBufferWrite, screenSizeScale, writeBuffer } from "@solidrt/core/gpu"
+import { checkScreenSize, createRecordStream, destroyBuffer, screenSizeScale } from "@solidrt/core/gpu"
 import type { BufferId } from "@solidrt/core/gpu"
 import { checkAtlases, frameIndex } from "./atlas.ts"
 import type { Atlas } from "./atlas.ts"
 import { fullFrame, isFrame, writeFrame } from "./frames.ts"
 import { checkTint, readFrame } from "./layer.ts"
-import type { LayerBase, Sprite, SpriteLayerOptions, SpriteOptions, SpriteState } from "./layer.ts"
+import type { LayerBase, Sprite, SpriteLayer, SpriteLayerOptions, SpriteOptions, SpriteState } from "./layer.ts"
 import { pointInSprite } from "./pick.ts"
 import { createSpritePipeline, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
 import { createViews } from "./views.ts"
@@ -83,10 +85,6 @@ export type RecordLayerOptions = Omit<SpriteLayerOptions, "orderBy"> & {
 }
 
 export type RecordLayer = LayerBase & {
-  /** The record mirror; read it through records(). Replaced by growth. */
-  _records: Float32Array
-  /** The record range [lo, hi) written since the last publish, or null. */
-  _dirty: [number, number] | null
   /** The count dial (setRecordCount): how many leading sprites draw and
    * pick; Infinity (the identity of the min against the live count)
    * until a dial is set. */
@@ -99,21 +97,34 @@ export type RecordLayer = LayerBase & {
 export type UpdateRecordsOptions = { first?: number; count?: number }
 
 /**
- * The layer's record mirror - the raw power path. Layout per sprite is
- * INSTANCE_FLOATS floats: [cx, cy, w, h, u0, v0, u1, v1, rot, tintR,
- * tintG, tintB, tintA, minScreenPx, maxScreenPx, atlas, outlineR,
- * outlineG, outlineB, outlineWidth], record i at i * INSTANCE_FLOATS;
- * `atlas` is the frame's texture as its index in the layer's `atlases`
- * list, and the outline is read only by a distance-field atlas (see
- * `Atlas.sdf`): rgb in 0..1 and a width in world pixels, zero for none. Record order is draw order - unless the
+ * The layer's record mirror - the raw power path. On a records layer the
+ * layout per sprite is INSTANCE_FLOATS floats: [cx, cy, w, h, u0, v0, u1,
+ * v1, rot, tintR, tintG, tintB, tintA, minScreenPx, maxScreenPx, atlas,
+ * outlineR, outlineG, outlineB, outlineWidth], record i at i *
+ * INSTANCE_FLOATS; `atlas` is the frame's texture as its index in the
+ * layer's `atlases` list, and the outline is read only by a
+ * distance-field atlas (see `Atlas.sdf`): rgb in 0..1 and a width in
+ * world pixels, zero for none. Record order is draw order - unless the
  * layer was created with `orderBy`, which draws in key order while record
- * i keeps meaning sprite i. Write fields directly for large per-frame
- * populations, then updateRecords the range. Read it AT USE TIME: addSprite
- * past capacity replaces the array, and a hoisted reference becomes a dead
- * copy whose writes publish nothing. Do not cache indices across
- * destroySprite - records shift. @solidrt/3d's records(mesh).
+ * i keeps meaning sprite i. Do not cache indices across destroySprite -
+ * records shift.
+ *
+ * On a node layer (createSpriteLayer) the records are its STYLE records,
+ * STYLE_FLOATS floats per sprite slot: [u0, v0, u1, v1, tintR, tintG,
+ * tintB, tintA, renderOrder, minScreenPx, maxScreenPx, atlas, outlineR,
+ * outlineG, outlineB, outlineWidth], slot i at i * STYLE_FLOATS (a
+ * sprite's slot is fixed for its life; a freed slot recycles) - the pose
+ * lives in the core and is written through setSprite. The 3d
+ * `records(instancedMesh)`, one dimension down: a bulk restyle (a palette
+ * cycle over thousands of sprites) is one loop over this and one
+ * updateRecords.
+ *
+ * Write fields directly for large per-frame populations, then
+ * updateRecords the range. Read it AT USE TIME: an add past capacity
+ * replaces the array, and a hoisted reference becomes a dead copy whose
+ * writes publish nothing. @solidrt/3d's records(mesh).
  */
-export function records(layer: RecordLayer): Float32Array {
+export function records(layer: RecordLayer | SpriteLayer): Float32Array {
   return layer._records
 }
 
@@ -123,13 +134,14 @@ export function records(layer: RecordLayer): Float32Array {
  * moved records of ten thousand cost ten); the whole mirror by default.
  * Write the mirror first, through records(), then call this. The range
  * is against the mirror's capacity, not the live sprites: a record past
- * the last live sprite is accepted and never drawn. Under `orderBy` any
- * range republishes the drawn prefix whole - the core gathers it into
- * key order, and a byte range has no stable position under a
- * permutation. @solidrt/3d's updateRecords(mesh).
+ * the last live sprite (on a node layer, past the highest slot in use)
+ * is accepted and never drawn. Under `orderBy` any range republishes the
+ * drawn prefix whole - the core gathers it into key order, and a byte
+ * range has no stable position under a permutation. @solidrt/3d's
+ * updateRecords(mesh).
  */
-export function updateRecords(layer: RecordLayer, options: UpdateRecordsOptions = {}): void {
-  let capacity = layer._records.length / INSTANCE_FLOATS
+export function updateRecords(layer: RecordLayer | SpriteLayer, options: UpdateRecordsOptions = {}): void {
+  let capacity = layer._stream.capacity
   let first = options.first ?? 0
   let count = options.count ?? capacity - first
   if (!Number.isInteger(first) || !Number.isInteger(count) || first < 0 || count < 0 || first + count > capacity) {
@@ -154,14 +166,10 @@ export function setRecordCount(layer: RecordLayer, count: number): void {
   layer._schedule()
 }
 
-// Extend the layer's dirty range over records [lo, hi) and schedule the
-// flush that publishes it.
-function markRecords(layer: RecordLayer, lo: number, hi: number): void {
-  if (layer._dirty === null) layer._dirty = [lo, hi]
-  else {
-    if (lo < layer._dirty[0]) layer._dirty[0] = lo
-    if (hi > layer._dirty[1]) layer._dirty[1] = hi
-  }
+// Mark records [lo, hi) of the layer's stream and schedule the flush that
+// publishes them.
+function markRecords(layer: RecordLayer | SpriteLayer, lo: number, hi: number): void {
+  layer._stream.mark(lo, hi)
   layer._schedule()
 }
 
@@ -179,10 +187,7 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
     throw new Error(`createRecordLayer: capacity must be a positive integer, got ${capacity}`)
   }
   let label = opts?.label ?? "sprites"
-  let buffer: BufferId = createBuffer(capacity * RECORD_BYTES, {
-    label: `${label}-records`,
-    autoFree: false,
-  })
+  let stream = createRecordStream(RECORD_BYTES, capacity, { label: `${label}-records`, autoFree: false })
   let tint = opts?.tint ?? [1, 1, 1, 1]
   checkTint("createRecordLayer", tint)
   let orderBy = opts?.orderBy
@@ -215,60 +220,45 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
 
   // How many leading sprites draw: the dial against the live count.
   let drawn = () => Math.min(layer._dial, layer._order.length)
-  // Publish the first `n` records whole through the write lease: a
-  // replacement buffer's first fill (its contents are unspecified), and
-  // every publish of an ordered layer (the gather runs in the copy).
-  let publishWhole = (target: BufferId, n: number) => {
-    let out = beginBufferWrite(target)
-    out.set(layer._records.subarray(0, n * INSTANCE_FLOATS))
-    endBufferWrite(target, n * RECORD_BYTES)
-  }
 
-  // The GPU buffer's record capacity; the mirror grows ahead of it
-  // (addSprite) and the flush catches the buffer up: a larger buffer is
-  // created, written in full, swapped in, and the old one destroyed. The
-  // entries hold the old buffer alive until the swaps land, so the destroy
-  // is safe to issue right after.
-  let gpuCapacity = capacity
+  // The buffers growth replaced since the last flush (addSprite grows the
+  // stream at once; the views still draw from the first of these until the
+  // flush swaps the replacement in). The entries hold a swapped-out buffer
+  // alive until the swap lands, so the destroys are safe to issue right
+  // after.
+  let grownFrom: BufferId[] = []
   let flush = () => {
     scheduled = false
     if (disposed) return
-    let dirty = layer._dirty
-    layer._dirty = null
-    let mirror = layer._records
     let live = layer._order.length
     let count = drawn()
-    if (mirror.length > gpuCapacity * INSTANCE_FLOATS) {
-      gpuCapacity = mirror.length / INSTANCE_FLOATS
-      let grown = createBuffer(mirror.length * Float32Array.BYTES_PER_ELEMENT, { label: `${label}-records`, autoFree: false })
+    if (grownFrom.length > 0) {
       // The replacement is filled whole before the swap (the entry must
       // never point at an unwritten buffer): the live prefix, or under
       // orderBy the drawn one, which is all the gather may see.
-      publishWhole(grown, ordered ? count : live)
-      views.setBuffers([grown])
+      stream.publish(true, ordered ? count : live)
+      views.setBuffers([stream.buffer])
       views.setCount(count)
       if (ordered) {
         // That publish landed BEFORE the swap, so the order had not yet
         // followed to the grown buffer and it went out ungathered. One
         // more publish, now under the swapped-in order, restores key
         // order - growth frames only.
-        publishWhole(grown, count)
+        stream.publish(true, count)
       }
-      destroyBuffer(buffer)
-      buffer = grown
+      for (let old of grownFrom) destroyBuffer(old)
+      grownFrom.length = 0
       published = count
       return
     }
     if (ordered) {
       // The gathered set IS the drawn prefix: a dirty record or a moved
       // dial republishes it whole.
-      if (dirty !== null || count !== published) publishWhole(buffer, count)
-    } else if (dirty !== null) {
+      if (stream.dirty || count !== published) stream.publish(true, count)
+    } else {
       // The dirty range, clipped to the live sprites (a record past them
       // is never drawn): one partial write at its byte offset.
-      let lo = dirty[0]
-      let hi = Math.min(dirty[1], live)
-      if (hi > lo) writeBuffer(buffer, mirror.subarray(lo * INSTANCE_FLOATS, hi * INSTANCE_FLOATS), lo * RECORD_BYTES)
+      stream.publish(false, live)
     }
     if (count !== published) {
       views.setCount(count)
@@ -335,7 +325,7 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
     pipeline: gpu.pipeline,
     quad: gpu.quad,
     atlases: atlases.map(a => a.texture),
-    buffers: () => [buffer],
+    buffers: () => [stream.buffer],
     count: () => published,
     tint: () => tint,
     pick: (x, y, zoom) => layer.pick(x, y, zoom),
@@ -383,7 +373,9 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       for (let sprite of layer._order) sprite.layer = null
       layer._order.length = 0
       views.dispose()
-      destroyBuffer(buffer)
+      for (let old of grownFrom) destroyBuffer(old)
+      grownFrom.length = 0
+      stream.destroy()
       gpu.dispose()
     },
     _add(opts) {
@@ -407,12 +399,11 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       }
       let atlas = checkWrite("addSprite", record)
       let index = layer._order.length
-      if ((index + 1) * INSTANCE_FLOATS > layer._records.length) {
-        // Growth replaces the mirror (doubling); the flush catches the GPU
-        // buffer up with a whole publish.
-        let next = new Float32Array(layer._records.length * 2)
-        next.set(layer._records)
-        layer._records = next
+      if (index + 1 > stream.capacity) {
+        // Growth replaces the mirror and the buffer (doubling); the flush
+        // fills the replacement whole and swaps it in.
+        grownFrom.push(stream.grow(stream.capacity * 2))
+        layer._records = new Float32Array(stream.bytes.buffer)
       }
       let sprite: SpriteState = { layer, node: null, _slot: index, _x: 0, _y: 0, _w: 0, _h: 0, _rot: 0, _flipX: false, _flipY: false, _visible: true, _parent: null }
       layer._order.push(sprite)
@@ -469,8 +460,8 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       scheduled = true
       RESOLVED.then(flush)
     },
-    _records: new Float32Array(capacity * INSTANCE_FLOATS),
-    _dirty: null,
+    _stream: stream,
+    _records: new Float32Array(stream.bytes.buffer),
     _dial: Infinity,
     _order: [],
   }

package/src/text.ts

@@ -9,6 +9,9 @@
 //
 // The node layer only: a run is a group. Three verbs like the sprites':
 // addText, setText (re-laid out, the sprite pool reused), destroyText.
+// A setText that changes only the paint (tint, outline, renderOrder)
+// re-writes the glyph sprites without shaping: a fade is sprite writes,
+// not an engine call per frame.
 import { addGroup, addSprite, destroyGroup, destroySprite, setGroup, setSprite } from "./layer.ts"
 import type { Sprite, SpriteGroup, SpriteLayer } from "./layer.ts"
 import type { SpriteFont } from "./font.ts"
@@ -119,7 +122,9 @@ export function addText(layer: SpriteLayer, opts: AddTextOptions): TextRun {
 }
 
 /** Change a run: the style fields re-lay it out (the sprite pool is
- * reused), the pose fields move its group. Absent keys keep values. */
+ * reused), the pose fields move its group. Absent keys keep values, and so
+ * does a key passed with its current value; a change to only tint,
+ * outline or renderOrder re-writes the glyph sprites without shaping. */
 export function setText(run: TextRun, opts: Partial<TextStyle> & TextPose): void {
   let state = run as RunState
   if (state.group.layer === null) return
@@ -127,12 +132,42 @@ export function setText(run: TextRun, opts: Partial<TextStyle> & TextPose): void
   if (x !== undefined || y !== undefined || rotation !== undefined || visible !== undefined) {
     setGroup(state.group, { x, y, rotation, visible })
   }
-  let keys = Object.keys(style) as (keyof TextStyle)[]
-  if (keys.some(k => style[k] !== undefined)) {
-    let next: TextStyle = { ...state._style }
-    for (let k of keys) if (style[k] !== undefined) (next as Record<string, unknown>)[k] = style[k]
-    relayout(state, next)
+  // Compare by value, not by presence: a component effect passes every
+  // style key on any change, and only a key that differs costs anything.
+  let current = state._style
+  let next: TextStyle = { ...current }
+  let reshape = false
+  let repaint = false
+  for (let k of Object.keys(style) as (keyof TextStyle)[]) {
+    let value = style[k]
+    if (value === undefined || sameStyleValue(k, value, current[k])) continue
+    ;(next as Record<string, unknown>)[k] = value
+    if (PAINT_KEYS.has(k)) repaint = true
+    else reshape = true
   }
+  if (reshape) relayout(state, next)
+  else if (repaint) {
+    checkStyle(next)
+    state._style = next
+    paint(state)
+  }
+}
+
+// The style keys that change only how a glyph sprite is drawn, never which
+// glyphs or where: every other key re-shapes.
+const PAINT_KEYS: ReadonlySet<keyof TextStyle> = new Set<keyof TextStyle>(["tint", "outline", "renderOrder"])
+
+// Equal as a style value: tint by channel, outline by colour and width,
+// the rest by identity.
+function sameStyleValue(key: keyof TextStyle, a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (key === "tint" && Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((c, i) => c === b[i])
+  if (key === "outline" && a != null && b != null) {
+    let { color: ca, width: wa } = a as NonNullable<TextStyle["outline"]>
+    let { color: cb, width: wb } = b as NonNullable<TextStyle["outline"]>
+    return wa === wb && ca[0] === cb[0] && ca[1] === cb[1] && ca[2] === cb[2]
+  }
+  return false
 }
 
 /** Remove the run: its group and every glyph sprite. */
@@ -164,6 +199,27 @@ function relayout(run: RunState, style: TextStyle): void {
   place(run)
 }
 
+// The paint fields of the run's style, as every glyph sprite takes them.
+function paintOf(style: TextStyle) {
+  return { tint: style.tint ?? [1, 1, 1, 1], outline: style.outline ?? null, renderOrder: style.renderOrder ?? 0 }
+}
+
+// Write a sprite's outline from the style (none clears it).
+function writeOutline(layer: SpriteLayer, sprite: Sprite, outline: TextStyle["outline"]): void {
+  if (outline != null) layer._outline(sprite, outline.color[0], outline.color[1], outline.color[2], outline.width)
+  else layer._outline(sprite, 0, 0, 0, 0)
+}
+
+// Re-paint the glyph sprites in place: the layout, the pool and the
+// pending cells all stand, only tint, outline and order are written.
+function paint(run: RunState): void {
+  let { tint, outline, renderOrder } = paintOf(run._style)
+  for (let sprite of run.sprites) {
+    setSprite(sprite, { tint, renderOrder })
+    writeOutline(run.layer, sprite, outline)
+  }
+}
+
 // Write every glyph sprite from the layout and the font's cells: a cell
 // the atlas lacks leaves its sprite hidden and asks the font for it.
 function place(run: RunState): void {
@@ -172,9 +228,7 @@ function place(run: RunState): void {
   let fontSize = style.fontSize ?? font.fontSize
   // Cells are made at `font.size` texels per em; the run draws at fontSize.
   let scale = fontSize / font.size
-  let tint = style.tint ?? [1, 1, 1, 1]
-  let outline = style.outline ?? null
-  let renderOrder = style.renderOrder ?? 0
+  let { tint, outline, renderOrder } = paintOf(style)
   let placements = run._layout.glyphs
   run._pending.clear()
   let missing: number[] = []
@@ -210,8 +264,7 @@ function place(run: RunState): void {
     } else {
       setSprite(sprite, fields)
     }
-    if (outline !== null) layer._outline(sprite, outline.color[0], outline.color[1], outline.color[2], outline.width)
-    else layer._outline(sprite, 0, 0, 0, 0)
+    writeOutline(layer, sprite, outline)
     used++
   }
   for (let i = used; i < sprites.length; i++) destroySprite(sprites[i]!)