@solidrt/2d 0.0.67 → 0.0.69

package/src/text.ts

@@ -0,0 +1,240 @@
+// Text runs in a sprite layer: a string drawn as one group of glyph
+// sprites, one per glyph, from a sprite font's atlas. The engine shapes
+// the text (kerning is its own), `layoutText` places the glyphs, and each
+// becomes an ordinary sprite under the run's group - so camera, tint,
+// `orderBy`, picking, transitions and bubbled pointer events already work,
+// and a run moves as one handle. A glyph whose cell is not in the atlas
+// yet is a hidden sprite at the right place; the font re-frames the run
+// when the cell lands (or every run when the atlas grew).
+//
+// The node layer only: a run is a group. Three verbs like the sprites':
+// addText, setText (re-laid out, the sprite pool reused), destroyText.
+import { addGroup, addSprite, destroyGroup, destroySprite, setGroup, setSprite } from "./layer.ts"
+import type { Sprite, SpriteGroup, SpriteLayer } from "./layer.ts"
+import type { SpriteFont } from "./font.ts"
+import { layoutText } from "./text-layout.ts"
+import type { GlyphPlacement, TextAlign, TextAnchor, TextAnchorY, TextLayout } from "./text-layout.ts"
+
+/** The run's own fields: what `addText` takes beyond the group's pose and
+ * what `setText` changes (re-laying the run out). */
+export type TextStyle = {
+  text: string
+  /** Pixels per em, layer pixels; default the font's `fontSize`. */
+  fontSize?: number
+  /** Baseline to baseline in layer pixels; default each line's own box. */
+  lineHeight?: number
+  /** Added after every glyph, layer pixels; default 0. */
+  letterSpacing?: number
+  /** Wrap at this width; unset, only `\n` breaks. */
+  maxWidth?: number
+  /** Line alignment inside the run's width (default "left"). */
+  align?: TextAlign
+  /** Where the run's x sits on its lines (default "start"). */
+  anchor?: TextAnchor
+  /** Where the run's y sits on its box (default "top"). */
+  anchorY?: TextAnchorY
+  /** The fill, RGBA 0..1 (default opaque white). */
+  tint?: [number, number, number, number]
+  /**
+   * An outline under the glyphs (an msdf font only; a mask font ignores
+   * it): its colour and width in layer pixels at the run's size. Null for
+   * none.
+   */
+  outline?: { color: [number, number, number]; width: number } | null
+  /** The draw-order key of every glyph (see SpriteOptions.renderOrder). */
+  renderOrder?: number
+}
+
+/** The run's pose: the group's. */
+export type TextPose = {
+  x?: number
+  y?: number
+  /** Radians, clockwise, about the anchor point. */
+  rotation?: number
+  visible?: boolean
+}
+
+export type AddTextOptions = TextStyle &
+  TextPose & {
+    font: SpriteFont
+    /** Mount under this group (null = the layer root). */
+    parent?: SpriteGroup | null
+  }
+
+export type TextRun = {
+  readonly layer: SpriteLayer
+  readonly font: SpriteFont
+  /** The run's group: its pose, and where glyph pointer events bubble. */
+  readonly group: SpriteGroup
+  /** The glyph sprites, in text order (one per glyph; a whitespace glyph
+   * has none). */
+  readonly sprites: readonly Sprite[]
+  /** The run's box in layer pixels at the current style. */
+  readonly width: number
+  readonly height: number
+  /** The first baseline below the box's top. */
+  readonly ascent: number
+  /** Line count. */
+  readonly lines: number
+  readonly text: string
+  _style: TextStyle
+  _layout: TextLayout
+  /** Glyph ids with no cell yet: what a landing re-frames. */
+  _pending: Set<number>
+  _reframe(grew: boolean, arrived: ReadonlySet<number>): void
+}
+
+/** The internal mutable view (the readonly fields are the public face). */
+type RunState = { -readonly [K in keyof TextRun]: TextRun[K] } & { sprites: Sprite[] }
+
+/** Add a run to a node layer, drawn from `font`'s atlas, which the layer
+ * must declare. Returns the run; its group carries the pose. */
+export function addText(layer: SpriteLayer, opts: AddTextOptions): TextRun {
+  let { font, parent, x, y, rotation, visible, ...style } = opts
+  if (!layer.atlases.includes(font.atlas)) {
+    throw new Error("addText: the layer does not declare the font's atlas; create it with the atlas in its list")
+  }
+  let group = addGroup(layer, { x, y, rotation, visible, parent })
+  let run: RunState = {
+    layer,
+    font,
+    group,
+    sprites: [],
+    width: 0,
+    height: 0,
+    ascent: 0,
+    lines: 0,
+    text: style.text,
+    _style: style,
+    _layout: { glyphs: [], lines: [], width: 0, height: 0, ascent: 0 },
+    _pending: new Set(),
+    _reframe(grew, arrived) {
+      if (!grew && ![...run._pending].some(id => arrived.has(id))) return
+      place(run)
+    },
+  }
+  relayout(run, style)
+  font._listeners.add(run)
+  return run
+}
+
+/** 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. */
+export function setText(run: TextRun, opts: Partial<TextStyle> & TextPose): void {
+  let state = run as RunState
+  if (state.group.layer === null) return
+  let { x, y, rotation, visible, ...style } = opts
+  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)
+  }
+}
+
+/** Remove the run: its group and every glyph sprite. */
+export function destroyText(run: TextRun): void {
+  let state = run as RunState
+  state.font._listeners.delete(state)
+  if (state.group.layer !== null) destroyGroup(state.group)
+  state.sprites = []
+}
+
+// Shape, break and place: the layout from the style, then the sprites.
+function relayout(run: RunState, style: TextStyle): void {
+  checkStyle(style)
+  run._style = style
+  run.text = style.text
+  let fontSize = style.fontSize ?? run.font.fontSize
+  let prepared = run.font.prepare(style.text, { fontSize, lineHeight: 0 })
+  run._layout = layoutText(prepared, {
+    maxWidth: style.maxWidth,
+    align: style.align,
+    anchor: style.anchor,
+    anchorY: style.anchorY,
+    letterSpacing: style.letterSpacing,
+    lineHeight: style.lineHeight,
+  })
+  run.width = run._layout.width
+  run.height = run._layout.height
+  run.ascent = run._layout.ascent
+  run.lines = run._layout.lines.length
+  place(run)
+}
+
+// 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 {
+  let { font, layer, group } = run
+  let style = run._style
+  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 placements = run._layout.glyphs
+  run._pending.clear()
+  let missing: number[] = []
+  // The pool: reuse sprites in order, add what is short, drop the rest.
+  let sprites = run.sprites
+  let used = 0
+  for (let p of placements) {
+    let glyph = font.glyph(p.id)
+    if (glyph === null) {
+      run._pending.add(p.id)
+      missing.push(p.id)
+    }
+    // A glyph with no cell yet, or an empty one (a space), draws nothing:
+    // its sprite stays hidden at a point, so a landing cell re-frames in
+    // place.
+    let drawn = glyph !== null && glyph.width > 0 && glyph.height > 0
+    let w = drawn ? glyph!.width * scale : 0
+    let h = drawn ? glyph!.height * scale : 0
+    let fields = {
+      x: p.x + (drawn ? glyph!.left * scale + w / 2 : 0),
+      y: p.y + (drawn ? -glyph!.top * scale + h / 2 : 0),
+      w,
+      h,
+      frame: drawn ? glyph!.frame : undefined,
+      tint,
+      renderOrder,
+      visible: drawn,
+    }
+    let sprite = sprites[used]
+    if (sprite === undefined) {
+      sprite = addSprite(layer, { ...fields, parent: group })
+      sprites.push(sprite)
+    } 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)
+    used++
+  }
+  for (let i = used; i < sprites.length; i++) destroySprite(sprites[i]!)
+  sprites.length = used
+  if (missing.length > 0) font.request(missing)
+}
+
+function checkStyle(style: TextStyle): void {
+  if (typeof style.text !== "string") throw new Error(`text: text must be a string, got ${typeof style.text}`)
+  if (style.fontSize !== undefined && !(style.fontSize > 0 && Number.isFinite(style.fontSize))) {
+    throw new Error(`text: fontSize must be a positive number, got ${style.fontSize}`)
+  }
+  if (style.outline != null) {
+    let { color, width } = style.outline
+    if (!(Array.isArray(color) && color.length === 3 && color.every(c => c >= 0 && c <= 1))) {
+      throw new Error(`text: outline.color must be [r, g, b] in 0..1, got ${JSON.stringify(color)}`)
+    }
+    if (!(width >= 0 && Number.isFinite(width))) throw new Error(`text: outline.width must be >= 0, got ${width}`)
+  }
+  if (style.tint !== undefined && !(style.tint.length === 4 && style.tint.every(c => c >= 0 && c <= 1))) {
+    throw new Error(`text: tint must be [r, g, b, a] in 0..1, got ${JSON.stringify(style.tint)}`)
+  }
+}
+
+export type { GlyphPlacement }

package/src/tiles.ts

@@ -5,26 +5,30 @@
 // chunk textures, and scrolling is a transform on the composited world
 // (see <TileLayer> in components/tile-layer.tsx), never a repaint.
 //
-// Each chunk is a small copy of the sprite pipeline (shaders.ts) with fixed
-// record slots - record localRow * chunkTiles + localCol IS that tile, an
-// empty tile is a zero-size quad, instance count is constant per chunk.
-// Records hold WORLD pixel coordinates; the chunk target's uCamera is its
-// pixel origin, so the shared vertex stage does the chunk-local mapping
-// (the same mechanism a camera pass uses, pointed at a chunk rect).
+// Each chunk is a manual target over the layer's ONE sprite pipeline
+// (shaders.ts, compiled once per layer for its atlases) with fixed record
+// slots - record localRow * chunkTiles + localCol IS that tile, an empty
+// tile is a zero-size quad, instance count is constant per chunk. Records
+// hold WORLD pixel coordinates; the chunk target's uCamera is its pixel
+// origin, so the shared vertex stage does the chunk-local mapping (the
+// same mechanism a camera pass uses, pointed at a chunk rect). A cell's
+// frame names its atlas like a sprite's (the record's atlas index), so a
+// tile world draws from several tilesets in one bake.
 //
 // Chunks allocate lazily on the first setTile that gives them content: an
 // empty chunk costs nothing - no records, no buffer, no texture - so a
 // sparse world is bounded by its content, and world size is bounded by
-// memory, not maxTextureSize. setTile and setTiles batch to a microtask;
-// the flush publishes and re-bakes ONLY dirty chunks. A layer nobody edits
+// memory, not maxTextureSize. setTile and setTiles batch; the flush (ahead
+// of the frame's paint, or at a microtask outside a frame) publishes and
+// re-bakes ONLY dirty chunks. A layer nobody edits
 // publishes nothing, renders nothing, and costs nothing per frame.
 // Camera-driven residency (bake far chunks on approach, evict them) is
 // deliberately not here yet - see okf/backlog/2d-baked-layers.md.
-import { getOwner, onCleanup } from "@solidrt/core"
+import { getOwner, onBeforeRender, onCleanup, runWithOwner } from "@solidrt/core"
 import {
   beginBufferWrite,
   createBuffer,
-  createPipelineTexture,
+  createShaderTarget,
   destroyBuffer,
   destroyTexture,
   endBufferWrite,
@@ -33,12 +37,15 @@ import {
   setTargetParams,
   setTargetSize,
 } from "@solidrt/core/gpu"
-import type { BufferId, FilterMode, TextureId } from "@solidrt/core/gpu"
+import type { BlendMode, BufferId, FilterMode, TextureId } from "@solidrt/core/gpu"
+import { checkAtlases, frameIndex } from "./atlas.ts"
+import type { Atlas } from "./atlas.ts"
+import { isFrame } from "./frames.ts"
 import type { Frame } from "./frames.ts"
 import { checkTint } from "./layer.ts"
 import { checkOversample, thrashSentinel } from "./oversample.ts"
-import { FLOATS_PER_SPRITE } from "./records.ts"
-import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+import { INSTANCE_FLOATS } from "./records.ts"
+import { atlasBindings, createSpritePipeline, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
 import { checkCell, checkRect, chunkOf, eachChunkSlice, slotOf } from "./tiles-math.ts"
 
 const RESOLVED = Promise.resolve()
@@ -52,12 +59,10 @@ const CLEAR_INDEX = 0xffff
 
 export type Tint = [number, number, number, number]
 
-// Whether a value is a frame: four numeric UVs (the validation both write
-// paths run before touching a record).
-let isFrame = (f: unknown): f is Frame => {
-  let o = f as Frame | null
-  return typeof o === "object" && o !== null && typeof o.u0 === "number" && typeof o.v0 === "number" && typeof o.u1 === "number" && typeof o.v1 === "number"
-}
+// Floats per frames-table entry: the four UVs plus the atlas index.
+const TABLE_FLOATS = 5
+// Float offset of the atlas sampler index in a record (records.ts layout).
+const ATLAS_FIELD_OFFSET = 15
 
 export type TileLayerOptions = {
   /** Per-chunk clear color (the name says the scope: chunks that never
@@ -71,6 +76,13 @@ export type TileLayerOptions = {
    * widths at a fractional scale.
    */
   filter?: FilterMode
+  /**
+   * How the cells blend into their chunk bakes, core gpu's BlendMode;
+   * default "alpha". "add" for a glow or light map baked over the
+   * transparent chunk clear, "multiply" to darken. Pipeline state, fixed
+   * at creation.
+   */
+  blend?: BlendMode
   /**
    * Target texels per world pixel in the baked chunks (positive integer,
    * default 1); see TileLayer.setOversample. `<TileLayer>` picks it from
@@ -87,9 +99,10 @@ export type TileLayerOptions = {
   tint?: [number, number, number, number]
   /**
    * The frames table setTiles' index cells name - a tileset: `grid()`'s
-   * array, or any Frame[] (up to 65535 entries), so a generated world is
-   * a Uint16Array of indices and never an array of frame objects. Fixed
-   * at creation; setTile takes frames directly either way.
+   * array, or any Frame[] (up to 65535 entries, from any of the layer's
+   * atlases), so a generated world is a Uint16Array of indices and never
+   * an array of frame objects. Fixed at creation; setTile takes frames
+   * directly either way.
    */
   frames?: Frame[]
   label?: string
@@ -108,6 +121,9 @@ export type TileChunk = {
 }
 
 export type TileLayer = {
+  /** The atlases the layer bakes from, as declared at creation: every
+   * frame set names one of their textures (see LayerBase.atlases). */
+  readonly atlases: readonly Atlas[]
   /** Grid shape, fixed at creation. */
   cols: number
   rows: number
@@ -144,8 +160,9 @@ export type TileLayer = {
    * an absent cell has no tint, it draws nothing). `tint` multiplies the
    * cell's sampled texels like a sprite's tint; absent it keeps the cell's
    * current tint (a cell being set from empty starts at [1, 1, 1, 1]).
-   * Batched; the microtask flush publishes and re-bakes ONLY the chunks
-   * that changed, however many tiles did.
+   * Batched; the flush ahead of the frame's paint (the microtask, outside
+   * a frame) publishes and re-bakes ONLY the chunks that changed, however
+   * many tiles did.
    */
   setTile(col: number, row: number, frame: Frame | null, opts?: { tint?: Tint }): void
   /**
@@ -193,18 +210,21 @@ type Chunk = TileChunk & {
  * sized at creation - that is the contract, not a provisional limit:
  * recreate the layer to resize, and for a huge sparse world just pick big
  * numbers, since a chunk nobody writes costs nothing (no records, no
- * texture) and the grid bound is bookkeeping, not allocation. Disposed
- * automatically with the owning reactive scope (opt out with `{ autoFree:
- * false }`); the atlas is NOT owned - dispose it yourself.
+ * texture) and the grid bound is bookkeeping, not allocation. `atlases`
+ * is the list of tilesets the cells draw from, bound together in every
+ * chunk bake (see createSpriteLayer). Disposed automatically with the
+ * owning reactive scope (opt out with `{ autoFree: false }`); the atlases
+ * are NOT owned - dispose them yourself.
  */
 export function createTileLayer(
   cols: number,
   rows: number,
   tileW: number,
   tileH: number,
-  atlas: TextureId,
+  atlases: Atlas[],
   opts?: TileLayerOptions,
 ): TileLayer {
+  let atlasIndex = checkAtlases("createTileLayer", atlases)
   if (!(cols > 0 && rows > 0 && Number.isInteger(cols) && Number.isInteger(rows))) {
     throw new Error(`createTileLayer: cols and rows must be positive integers, got ${cols} x ${rows}`)
   }
@@ -223,25 +243,28 @@ export function createTileLayer(
     )
   }
   let label = opts?.label ?? "tiles"
+  let blend: BlendMode = opts?.blend ?? "alpha"
   let tint: Tint = opts?.tint ?? [1, 1, 1, 1]
   checkTint("createTileLayer", tint)
   // The frames table, copied (the caller's array may move on) and checked
-  // once, plus its UVs as four floats per entry: an index write copies by
-  // offset instead of reading a frame object per cell.
+  // once, plus its UVs and atlas index as five floats per entry: an index
+  // write copies by offset instead of reading a frame object per cell.
   let frames: Frame[] | null = opts?.frames ? opts.frames.slice() : null
-  let tableUv: Float32Array | null = null
+  let table: Float32Array | null = null
   if (frames !== null) {
     if (frames.length >= CLEAR_INDEX) {
       throw new Error(`createTileLayer: a frames table holds at most ${CLEAR_INDEX - 1} frames, got ${frames.length}`)
     }
-    tableUv = new Float32Array(frames.length * 4)
+    table = new Float32Array(frames.length * TABLE_FLOATS)
     for (let i = 0; i < frames.length; i++) {
       let f = frames[i]!
       if (!isFrame(f)) throw new Error(`createTileLayer: frames[${i}] is not a frame, got ${JSON.stringify(f)}`)
-      tableUv[i * 4] = f.u0
-      tableUv[i * 4 + 1] = f.v0
-      tableUv[i * 4 + 2] = f.u1
-      tableUv[i * 4 + 3] = f.v1
+      let at = i * TABLE_FLOATS
+      table[at] = f.u0
+      table[at + 1] = f.v0
+      table[at + 2] = f.u1
+      table[at + 3] = f.v1
+      table[at + 4] = frameIndex(`createTileLayer: frames[${i}]`, atlasIndex, f)
     }
   }
   let oversample = opts?.oversample ?? 1
@@ -249,14 +272,26 @@ export function createTileLayer(
   let thrash = thrashSentinel(`tile layer "${label}"`)
   let chunkCols = Math.ceil(cols / chunkTiles)
   let perChunk = chunkTiles * chunkTiles
-  // One unit quad (triangle strip), shared by every chunk's pipeline.
-  let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
-    label: `${label}-quad`,
-    autoFree: false,
-  })
+  // The one pipeline (and unit quad) every chunk target draws with:
+  // compiled once per layer, however many chunks allocate.
+  let gpu = createSpritePipeline(label, VERTEX, [INSTANCE_ATTRIBUTES], blend, atlases)
+  let textures = atlasBindings(atlases.map(a => a.texture))
 
   let disposed = false
   let scheduled = false
+  // The publish pass of every frame runs the pending flush ahead of the
+  // paint, so a tile set anywhere in the frame's JS is baked for that
+  // frame's picture; the microtask stays for writes made outside a frame.
+  // Registered outside any owner: dispose unhooks it (an autoFree: false
+  // layer outlives the owner it was created in).
+  let unhook = runWithOwner(null, () =>
+    onBeforeRender(
+      () => {
+        if (scheduled) flush()
+      },
+      { publish: true },
+    ),
+  )
   // Chunk index (chunkRow * chunkCols + chunkCol) -> resident chunk.
   let resident = new Map<number, Chunk>()
   let dirtyChunks: Chunk[] = []
@@ -291,11 +326,10 @@ export function createTileLayer(
   let allocate = (index: number): Chunk => {
     let x = (index % chunkCols) * chunkW
     let y = Math.floor(index / chunkCols) * chunkH
-    let records = new Float32Array(perChunk * FLOATS_PER_SPRITE)
+    let records = new Float32Array(perChunk * INSTANCE_FLOATS)
     let buffer = createBuffer(records.byteLength, { label: `${label}-chunk-records`, autoFree: false })
-    let texture = createPipelineTexture(
-      VERTEX,
-      FRAGMENT,
+    let texture = createShaderTarget(
+      gpu.pipeline,
       chunkW * oversample,
       chunkH * oversample,
       // Bake targets pin the camera rotation to identity: the tile camera
@@ -303,15 +337,10 @@ export function createTileLayer(
       { uViewport: [chunkW, chunkH], uCamera: [x, y, 1, 1], uCameraRot: [1, 0, 0, 0], uTint: tint },
       {
         label: `${label}-chunk`,
-        topology: "triangle-strip",
+        buffers: [gpu.quad, buffer],
         vertexCount: 4,
-        buffers: [
-          { attributes: [{ name: "aPos", format: "float32x2" }], buffer: quad },
-          { stepMode: "instance", attributes: INSTANCE_ATTRIBUTES, buffer },
-        ],
         instanceCount: perChunk,
-        blend: "alpha",
-        textures: { uAtlas: atlas },
+        textures,
         clearColor: opts?.chunkClearColor ?? [0, 0, 0, 0],
         filter: opts?.filter,
         render: "manual",
@@ -328,12 +357,12 @@ export function createTileLayer(
   // A cell's chunk index, and its record offset inside that chunk
   // (tiles-math.ts, bound to this layer's grid).
   let chunkAt = (col: number, row: number): number => chunkOf(col, row, chunkTiles, chunkCols)
-  let slot = (col: number, row: number): number => slotOf(col, row, chunkTiles, FLOATS_PER_SPRITE)
-  // Write one cell's record: the quad at the cell, the frame's UVs, and
-  // the tint - the one given, else the default when the cell comes up from
-  // empty (a re-set keeps its tint: absent keys keep their values, like
-  // every options object here).
-  let writeCell = (r: Float32Array, at: number, col: number, row: number, u0: number, v0: number, u1: number, v1: number, cellTint: Tint | undefined): void => {
+  let slot = (col: number, row: number): number => slotOf(col, row, chunkTiles, INSTANCE_FLOATS)
+  // Write one cell's record: the quad at the cell, the frame's UVs and
+  // atlas index, and the tint - the one given, else the default when the
+  // cell comes up from empty (a re-set keeps its tint: absent keys keep
+  // their values, like every options object here).
+  let writeCell = (r: Float32Array, at: number, col: number, row: number, u0: number, v0: number, u1: number, v1: number, atlas: number, cellTint: Tint | undefined): void => {
     let fresh = r[at + 2] === 0
     r[at] = (col + 0.5) * tileW
     r[at + 1] = (row + 0.5) * tileH
@@ -343,6 +372,7 @@ export function createTileLayer(
     r[at + 5] = v0
     r[at + 6] = u1
     r[at + 7] = v1
+    r[at + ATLAS_FIELD_OFFSET] = atlas
     if (cellTint !== undefined) {
       r[at + 9] = cellTint[0]
       r[at + 10] = cellTint[1]
@@ -363,6 +393,7 @@ export function createTileLayer(
   }
 
   let layer: TileLayer = {
+    atlases,
     cols,
     rows,
     tileW,
@@ -401,8 +432,9 @@ export function createTileLayer(
       } else {
         if (!isFrame(frame)) throw new Error(`setTile: not a frame, got ${JSON.stringify(frame)}`)
         if (opts?.tint !== undefined) checkTint("setTile", opts.tint)
+        let atlas = frameIndex("setTile", atlasIndex, frame)
         chunk ??= allocate(index)
-        writeCell(chunk.records, at, col, row, frame.u0, frame.v0, frame.u1, frame.v1, opts?.tint)
+        writeCell(chunk.records, at, col, row, frame.u0, frame.v0, frame.u1, frame.v1, atlas, opts?.tint)
       }
       touch(chunk)
     },
@@ -413,9 +445,11 @@ export function createTileLayer(
       if (opts?.tint !== undefined) checkTint("setTiles", opts.tint)
       let cellTint = opts?.tint
       // The two forms: indices into the table, or frames. Every entry is
-      // checked before the first write, so a bad one changes nothing.
+      // checked (and a frame resolved to its atlas) before the first write,
+      // so a bad one changes nothing.
       let idx = typeof cells[0] === "number" ? (cells as ArrayLike<number>) : null
       let objs = idx === null ? (cells as ArrayLike<Frame | null>) : null
+      let objAtlas: Float32Array | null = null
       if (idx !== null) {
         if (frames === null) throw new Error("setTiles: index cells need a frames table (createTileLayer's frames option)")
         let count = frames.length
@@ -425,12 +459,14 @@ export function createTileLayer(
           if (!(Number.isInteger(k) && k >= 0 && k < count)) throw new Error(`setTiles: index ${k} at cell ${i} outside the ${count}-frame table`)
         }
       } else {
+        objAtlas = new Float32Array(objs!.length)
         for (let i = 0; i < objs!.length; i++) {
           let f = objs![i]
-          if (f !== null && f !== undefined && !isFrame(f)) throw new Error(`setTiles: cell ${i} is neither a frame nor null, got ${JSON.stringify(f)}`)
+          if (f === null || f === undefined) continue
+          if (!isFrame(f)) throw new Error(`setTiles: cell ${i} is neither a frame nor null, got ${JSON.stringify(f)}`)
+          objAtlas[i] = frameIndex(`setTiles: cell ${i}`, atlasIndex, f)
         }
       }
-      let uv = tableUv
       // Chunk by chunk over the rect: each chunk's slice of the rect is a
       // sub-rect walked row by row with the record offset advancing, one
       // dirty mark at the end. A chunk the slice only clears is never
@@ -441,22 +477,24 @@ export function createTileLayer(
         for (let y = rowA; y < rowB; y++) {
           let at = slot(colA, y)
           let i = (y - row) * w + (colA - col)
-          for (let x = colA; x < colB; x++, at += FLOATS_PER_SPRITE, i++) {
+          for (let x = colA; x < colB; x++, at += INSTANCE_FLOATS, i++) {
             let u0: number
             let v0: number
             let u1: number
             let v1: number
+            let atlas: number
             if (idx !== null) {
               let k = idx[i]!
               if (k === -1 || k === CLEAR_INDEX) {
                 if (r !== null) clearCell(r, at)
                 continue
               }
-              let b = k * 4
-              u0 = uv![b]!
-              v0 = uv![b + 1]!
-              u1 = uv![b + 2]!
-              v1 = uv![b + 3]!
+              let b = k * TABLE_FLOATS
+              u0 = table![b]!
+              v0 = table![b + 1]!
+              u1 = table![b + 2]!
+              v1 = table![b + 3]!
+              atlas = table![b + 4]!
             } else {
               let f = objs![i]
               if (f === null || f === undefined) {
@@ -467,12 +505,13 @@ export function createTileLayer(
               v0 = f.v0
               u1 = f.u1
               v1 = f.v1
+              atlas = objAtlas![i]!
             }
             if (r === null) {
               chunk = allocate(index)
               r = chunk.records
             }
-            writeCell(r, at, x, y, u0, v0, u1, v1, cellTint)
+            writeCell(r, at, x, y, u0, v0, u1, v1, atlas, cellTint)
           }
         }
         if (chunk) touch(chunk)
@@ -484,7 +523,7 @@ export function createTileLayer(
       let at = slot(col, row)
       if (!chunk || chunk.records[at + 2] === 0) return null
       let r = chunk.records
-      return { u0: r[at + 4]!, v0: r[at + 5]!, u1: r[at + 6]!, v1: r[at + 7]! }
+      return { texture: atlases[r[at + ATLAS_FIELD_OFFSET]!]!.texture, u0: r[at + 4]!, v0: r[at + 5]!, u1: r[at + 6]!, v1: r[at + 7]! }
     },
     frames,
     setTint(next) {
@@ -500,13 +539,14 @@ export function createTileLayer(
     dispose() {
       if (disposed) return
       disposed = true
+      unhook()
       for (let chunk of resident.values()) {
         destroyTexture(chunk.texture)
         destroyBuffer(chunk.buffer)
       }
       resident.clear()
       layer.chunks.length = 0
-      destroyBuffer(quad)
+      gpu.dispose()
     },
   }