@solidrt/2d 0.0.67 → 0.0.68

package/src/components/text2d.tsx

@@ -0,0 +1,77 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { setGroupTransition } from "../layer.ts"
+import type { SpritePointerEvent, SpriteTapEvent, SpriteTransition, SpriteWheelEvent, TransitionEndEvent } from "../layer.ts"
+import { addText, destroyText, setText } from "../text.ts"
+import type { AddTextOptions, TextRun } from "../text.ts"
+import { GroupContext, LayerContext } from "./context.ts"
+
+export type Text2dProps = Omit<AddTextOptions, "parent"> & {
+  /** Bubbled from a hit glyph sprite to the run's group (see
+   * SpritePointerProps); a run never receives enter/leave. */
+  onPointerDown?: (event: SpritePointerEvent) => void
+  onPointerMove?: (event: SpritePointerEvent) => void
+  onPointerUp?: (event: SpritePointerEvent) => void
+  onPointerCancel?: (event: SpritePointerEvent) => void
+  onWheel?: (event: SpriteWheelEvent) => void
+  onTap?: (event: SpriteTapEvent) => void
+  /** How pose-prop changes animate (the run's group; see
+   * setGroupTransition). The mount pose snaps. */
+  transition?: SpriteTransition | string | null
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+  ref?: (run: TextRun) => void
+}
+
+/**
+ * A text run in the enclosing `<SpriteLayer>` (under the enclosing
+ * `<Group>` when there is one): `text` drawn from `font`'s atlas as glyph
+ * sprites, at `x`/`y` in the group's frame, the style props re-laying it
+ * out when they change. The layer must declare `font.atlas`. Renders
+ * nothing itself; `Camera2d`, picking and `orderBy` see the glyphs as
+ * sprites.
+ */
+export let Text2d: VoidComponent<Text2dProps> = props => {
+  let layer = useContext(LayerContext)
+  let parent = useContext(GroupContext)
+  let run = untrack(() =>
+    addText(layer, {
+      font: props.font,
+      text: props.text,
+      x: props.x,
+      y: props.y,
+      rotation: props.rotation,
+      visible: props.visible,
+      parent,
+    }),
+  )
+  createEffect(
+    () => [props.x, props.y, props.rotation, props.visible] as const,
+    ([x, y, rotation, visible]) => setText(run, { x, y, rotation, visible: visible !== false }),
+  )
+  createEffect(
+    () =>
+      [props.text, props.fontSize, props.lineHeight, props.letterSpacing, props.maxWidth, props.align, props.anchor, props.anchorY, props.tint, props.outline, props.renderOrder] as const,
+    ([text, fontSize, lineHeight, letterSpacing, maxWidth, align, anchor, anchorY, tint, outline, renderOrder]) =>
+      setText(run, { text, fontSize, lineHeight, letterSpacing, maxWidth, align, anchor, anchorY, tint, outline, renderOrder }),
+  )
+  // After the pose effect, so the mount pose snaps before writes animate.
+  createEffect(
+    () => props.transition,
+    transition => setGroupTransition(run.group, transition ?? null),
+  )
+  createEffect(
+    () => [props.onPointerDown, props.onPointerMove, props.onPointerUp, props.onPointerCancel, props.onWheel, props.onTap, props.onTransitionEnd] as const,
+    ([down, move, up, cancel, wheel, tap, end]) => {
+      run.group.onPointerDown = down
+      run.group.onPointerMove = move
+      run.group.onPointerUp = up
+      run.group.onPointerCancel = cancel
+      run.group.onWheel = wheel
+      run.group.onTap = tap
+      run.group.onTransitionEnd = end
+    },
+  )
+  untrack(() => props.ref)?.(run)
+  onCleanup(() => destroyText(run))
+  return null
+}

package/src/components/tile-layer.tsx

@@ -1,6 +1,7 @@
 import { createEffect, createSignal, displayScale, For, getBoundingBoxViewport, onLayout, untrack } from "@solidrt/core"
-import type { TextureId, VoidComponent } from "@solidrt/core"
-import type { FilterMode } from "@solidrt/core/gpu"
+import type { VoidComponent } from "@solidrt/core"
+import type { BlendMode, FilterMode } from "@solidrt/core/gpu"
+import type { Atlas } from "../atlas.ts"
 import type { CameraUpdate } from "../camera.ts"
 import type { Frame } from "../frames.ts"
 import { tileWorldScale } from "../oversample-math.ts"
@@ -24,8 +25,9 @@ export type TileLayerProps = {
   rows: number
   tileW: number
   tileH: number
-  /** The atlas texture every tile samples (create with createAtlas). */
-  atlas: TextureId
+  /** The tilesets the cells draw from (createAtlas records), bound as one
+   * bake; every frame set names one of them. Fixed at mount. */
+  atlases: Atlas[]
   /** The frames table `setTiles`' index cells name (a tileset, `grid()`'s
    * array); see TileLayerOptions. Fixed at creation. */
   frames?: Frame[]
@@ -33,6 +35,9 @@ export type TileLayerProps = {
    * have no chunk and render nothing, so a full-bleed ground color belongs
    * on the container behind the layer). */
   chunkClearColor?: [number, number, number, number]
+  /** How the cells blend into their chunk bakes (see
+   * TileLayerOptions.blend); default "alpha". Fixed at mount. */
+  blend?: BlendMode
   /** Sampler filter for the baked chunk textures at composite time; default
    * "linear" (hard pixels belong to the atlas sampler, see TileLayerOptions). */
   filter?: FilterMode
@@ -81,8 +86,9 @@ export type TileLayerProps = {
  */
 export let TileLayer: VoidComponent<TileLayerProps> = props => {
   let layer = untrack(() =>
-    createTileLayer(props.cols, props.rows, props.tileW, props.tileH, props.atlas, {
+    createTileLayer(props.cols, props.rows, props.tileW, props.tileH, props.atlases, {
       chunkClearColor: props.chunkClearColor,
+      blend: props.blend,
       filter: props.filter,
       chunkTiles: props.chunkTiles,
       tint: props.tint,

package/src/dispatch.ts

@@ -42,7 +42,8 @@ const TAP_REPEAT_SLOP = 20
 export type DispatchDeps = {
   size: () => [number, number]
   camera: () => CameraUpdate
-  pick: (x: number, y: number) => Sprite[]
+  /** The layer's pick, `zoom` the camera zoom its floors are measured at. */
+  pick: (x: number, y: number, zoom: number) => Sprite[]
   /** The view: the walk's root and the listeners' currentTarget. */
   root: ViewHandle
   /** The root's listeners, in registration order. */
@@ -151,7 +152,7 @@ export function spriteDispatch(deps: DispatchDeps): (layout: (() => { width: num
       }
       return event
     }
-    let topmost = (x: number, y: number): Sprite | null => deps.pick(x, y)[0] ?? null
+    let topmost = (x: number, y: number): Sprite | null => deps.pick(x, y, deps.camera().zoom ?? 1)[0] ?? null
     // Enter/leave go to one sprite directly, outside the walk: the event
     // in its sprite view.
     let hoverEvent = (sprite: Sprite, x: number, y: number, e: ElementPointerEvent): SpritePointerEvent =>

package/src/extrude.ts

@@ -0,0 +1,156 @@
+// Atlas extrusion, pure: repack a sheet so every cell sits in a gutter of
+// its own replicated edge pixels - TexturePacker's "Extrude", Unity's
+// "Extrude Edges" import setting - the answer to mip-chain bleed. The
+// layer shaders clamp every sample into its frame, which keeps mip level 0
+// clean on an edge-to-edge sheet, but a mip chain averages 2^k texel
+// blocks BEFORE any sampling decision, and a block straddling a cell edge
+// mixes two cells. With a gutter of g replicated texels around every cell
+// and every cell edge on a multiple of g, each block at level k <= log2(g)
+// lies inside one cell's own colours, so levels 0 through log2(g) sample
+// clean (deeper levels mix neighbours again; widen the gutter for a sheet
+// drawn further below its texel size). CPU work at load time - a few
+// milliseconds for a 1024-square sheet - and the result goes through
+// createAtlas like any decoded image. No GPU or GUI imports (the
+// DecodedImage import is a type), so tests/extrude.test.ts runs headless.
+import type { DecodedImage } from "@solidrt/core"
+import type { GridOptions } from "./frames.ts"
+import { packRects, packWidth } from "./pack.ts"
+
+// Bytes per pixel of a DecodedImage (tightly packed RGBA8).
+const BYTES_PER_PIXEL = 4
+
+/** A named pixel-rect table, `[x, y, w, h]` per name: namedFrames' input. */
+export type Rects<K extends string> = Record<K, [number, number, number, number]>
+
+/** extrudeGrid's result: the repacked sheet and the GridOptions that slice it. */
+export type ExtrudedGrid = { image: DecodedImage; options: GridOptions }
+/** extrudeRects' result: the repacked sheet and each rect's place in it. */
+export type ExtrudedRects<K extends string> = { image: DecodedImage; rects: Rects<K> }
+
+/**
+ * Extrude a uniform sheet: every cell of the `cols` x `rows` grid (laid
+ * out by `source`, the same geometry `grid` reads - cell size, spacing,
+ * margins; default the sheet divided evenly) is copied into a new sheet
+ * inside a `gutter`-texel border of its own replicated edge pixels.
+ * Returns the sheet and the GridOptions that slice it:
+ * `grid(atlas, cols, rows, extruded.options)` over
+ * `createAtlas(extruded.image, { mipmap: true })`.
+ *
+ * `gutter` is a power of two and the cell size a multiple of it, so cell
+ * edges land on mip texel edges; mip levels 0 through log2(gutter) then
+ * sample clean. The new sheet is `cell + 2 * gutter` per cell on each
+ * axis - a 16 px cell with a 4-texel gutter is 24 px, 2.25x the texels.
+ * Throws on a gutter or cell size that breaks the alignment, or a grid
+ * the sheet does not hold.
+ */
+export function extrudeGrid(image: DecodedImage, cols: number, rows: number, gutter: number, source?: GridOptions): ExtrudedGrid {
+  checkImage("extrudeGrid", image)
+  if (!(cols > 0 && rows > 0 && Number.isInteger(cols) && Number.isInteger(rows))) {
+    throw new Error(`extrudeGrid: cols and rows must be positive integers, got ${cols} x ${rows}`)
+  }
+  checkGutter("extrudeGrid", gutter)
+  let { width, height } = image
+  let { spacing = 0, marginX = 0, marginY = 0 } = source ?? {}
+  let cellW = source?.cellW ?? (width - marginX * 2 - spacing * (cols - 1)) / cols
+  let cellH = source?.cellH ?? (height - marginY * 2 - spacing * (rows - 1)) / rows
+  checkCell("extrudeGrid", cellW, cellH, gutter)
+  if (marginX + cols * cellW + (cols - 1) * spacing > width || marginY + rows * cellH + (rows - 1) * spacing > height) {
+    throw new Error(`extrudeGrid: a ${cols} x ${rows} grid of ${cellW} x ${cellH} cells does not fit the ${width} x ${height} sheet`)
+  }
+  let pitchX = cellW + 2 * gutter
+  let pitchY = cellH + 2 * gutter
+  let out = blank(cols * pitchX, rows * pitchY)
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      copyCell(image, marginX + col * (cellW + spacing), marginY + row * (cellH + spacing), cellW, cellH, out, col * pitchX + gutter, row * pitchY + gutter, gutter)
+    }
+  }
+  return { image: out, options: { cellW, cellH, spacing: 2 * gutter, marginX: gutter, marginY: gutter } }
+}
+
+/**
+ * Extrude a hand-packed sheet: every named rect is re-placed on a new
+ * sheet (a shelf packing, pack.ts) inside a `gutter`-texel border of its
+ * own replicated edge pixels, and the table of new rects comes back for
+ * `namedFrames(atlas, extruded.rects)`. The same alignment rule as
+ * extrudeGrid: `gutter` a power of two, every rect's size a multiple of
+ * it (pad a rect in the source sheet to make it so). The new sheet is a
+ * power of two wide and as tall as its shelves.
+ */
+export function extrudeRects<K extends string>(image: DecodedImage, rects: Rects<K>, gutter: number): ExtrudedRects<K> {
+  checkImage("extrudeRects", image)
+  checkGutter("extrudeRects", gutter)
+  let names = Object.keys(rects) as K[]
+  if (names.length === 0) throw new Error("extrudeRects: no rects to extrude")
+  let sizes = names.map(name => {
+    let [x, y, w, h] = rects[name]
+    checkCell(`extrudeRects: rect '${name}'`, w, h, gutter)
+    if (!(Number.isInteger(x) && Number.isInteger(y) && x >= 0 && y >= 0 && x + w <= image.width && y + h <= image.height)) {
+      throw new Error(`extrudeRects: rect '${name}' [${x}, ${y}, ${w}, ${h}] is not inside the ${image.width} x ${image.height} sheet`)
+    }
+    return { width: w + 2 * gutter, height: h + 2 * gutter }
+  })
+  let packing = packRects(sizes, packWidth(sizes))
+  let out = blank(packing.width, packing.height)
+  let placed = {} as Rects<K>
+  names.forEach((name, i) => {
+    let [x, y, w, h] = rects[name]
+    let p = packing.rects[i]!
+    copyCell(image, x, y, w, h, out, p.x + gutter, p.y + gutter, gutter)
+    placed[name] = [p.x + gutter, p.y + gutter, w, h]
+  })
+  return { image: out, rects: placed }
+}
+
+/** A transparent sheet of the given size. */
+function blank(width: number, height: number): DecodedImage {
+  return { data: new Uint8Array(width * height * BYTES_PER_PIXEL), width, height }
+}
+
+/**
+ * Copy the `w` x `h` cell at (sx, sy) of `src` to (dx, dy) of `dst` inside
+ * a `g`-texel border replicating its edge pixels: each output row takes
+ * the nearest cell row in one bulk copy, then its first and last pixels
+ * fill the side gutters pixel by pixel.
+ */
+function copyCell(src: DecodedImage, sx: number, sy: number, w: number, h: number, dst: DecodedImage, dx: number, dy: number, g: number): void {
+  let srcRow = src.width * BYTES_PER_PIXEL
+  let dstRow = dst.width * BYTES_PER_PIXEL
+  let cellBytes = w * BYTES_PER_PIXEL
+  for (let oy = -g; oy < h + g; oy++) {
+    let row = sy + Math.min(Math.max(oy, 0), h - 1)
+    let from = row * srcRow + sx * BYTES_PER_PIXEL
+    let to = (dy + oy) * dstRow + dx * BYTES_PER_PIXEL
+    dst.data.set(src.data.subarray(from, from + cellBytes), to)
+    let last = to + cellBytes - BYTES_PER_PIXEL
+    for (let i = 1; i <= g; i++) {
+      dst.data.copyWithin(to - i * BYTES_PER_PIXEL, to, to + BYTES_PER_PIXEL)
+      dst.data.copyWithin(last + i * BYTES_PER_PIXEL, last, last + BYTES_PER_PIXEL)
+    }
+  }
+}
+
+function checkImage(what: string, image: DecodedImage): void {
+  let { width, height, data } = image
+  if (!(Number.isInteger(width) && Number.isInteger(height) && width > 0 && height > 0)) {
+    throw new Error(`${what}: image size must be positive integers, got ${width} x ${height}`)
+  }
+  if (data.length !== width * height * BYTES_PER_PIXEL) {
+    throw new Error(`${what}: image data holds ${data.length} bytes, not the ${width * height * BYTES_PER_PIXEL} of ${width} x ${height} RGBA8 pixels`)
+  }
+}
+
+function checkGutter(what: string, gutter: number): void {
+  if (!(Number.isInteger(gutter) && gutter >= 1 && (gutter & (gutter - 1)) === 0)) {
+    throw new Error(`${what}: gutter must be a power of two >= 1, got ${gutter}`)
+  }
+}
+
+function checkCell(what: string, w: number, h: number, gutter: number): void {
+  if (!(Number.isInteger(w) && Number.isInteger(h) && w > 0 && h > 0)) {
+    throw new Error(`${what}: cell size must be positive integers, got ${w} x ${h}`)
+  }
+  if (w % gutter !== 0 || h % gutter !== 0) {
+    throw new Error(`${what}: a ${w} x ${h} cell is not a multiple of the ${gutter}-texel gutter, so its edges would not land on mip texel edges; pad the cell or lower the gutter`)
+  }
+}

package/src/font.ts

@@ -0,0 +1,207 @@
+// A sprite font: the runtime's glyph engine (`flux:font`) seen as an atlas
+// a layer declares plus a frame per glyph. The engine shapes the text and
+// makes the glyph cells on its worker thread; this keeps the cells as
+// frames, asks for the ones a run needs, and re-frames the runs whose
+// glyphs arrive - including every run when the atlas grew, which moves
+// every cell (a growth is a size change of `font.atlas`). The font is a
+// handle from the first call: its atlas texture exists at once, so a layer
+// declares it at creation and draws from it as cells land, a label's
+// unbaked glyphs drawing as nothing at the right advance until then.
+//
+// XNA's SpriteFont, PixiJS's BitmapFont: a font asset drawn as quads. Two
+// cell kinds: "msdf" (the default, what a zooming label wants), one atlas
+// sharp at every zoom with the layer's fragment stage decoding the field
+// (`Atlas.sdf`), and "mask", coverage at the face's exact size for drawing
+// 1:1.
+import { getOwner, onCleanup } from "@solidrt/core"
+import type { PreparedText } from "@solidrt/core"
+import { createFont, destroyFont, fontAtlas, glyphCells, prepareText, requestGlyphs } from "flux:font"
+import type { FontAtlasOptions, FontFace, FontId, FontPrepareOptions, GlyphCell } from "flux:font"
+import type { Atlas } from "./atlas.ts"
+import type { Frame } from "./frames.ts"
+
+/** The printable ASCII range, warmed up by default: what labels, counters
+ * and HUD text are made of, so a run of them never waits for a cell. */
+const ASCII_FIRST = 0x20
+const ASCII_LAST = 0x7e
+
+export type SpriteFontOptions = FontAtlasOptions & {
+  /**
+   * The characters to make cells for at creation (default printable
+   * ASCII; `false` for none): a run drawn later from these never waits. A
+   * run needing other glyphs makes them on demand and draws them when they
+   * land (`ready` awaits that).
+   */
+  chars?: string | false
+  /** Skip the owner-scoped auto-free (the core createTexture contract). */
+  autoFree?: boolean
+}
+
+/** One glyph as the atlas holds it: its frame, its cell size in texels
+ * and where the cell sits on the glyph (`left` right of the origin,
+ * `top` above the baseline, texels). */
+export type Glyph = {
+  frame: Frame
+  width: number
+  height: number
+  left: number
+  top: number
+}
+
+/** What a text run registers with its font: the call that re-reads its
+ * glyphs after cells landed or moved. */
+export type FontListener = { _reframe(grew: boolean, arrived: ReadonlySet<number>): void }
+
+export type SpriteFont = {
+  /** The engine's handle. */
+  readonly id: FontId
+  /**
+   * The atlas a layer declares (`createSpriteLayer([art, font.atlas])`):
+   * one record for the font's life whose `width`/`height` change in place
+   * as the atlas grows, `sdf` set for msdf cells.
+   */
+  readonly atlas: Atlas
+  /** Texels per em the cells were made at: a glyph drawn at `fontSize`
+   * scales its cell by `fontSize / size`. */
+  readonly size: number
+  /** The face's size: what `prepare` shapes at when the call names none. */
+  readonly fontSize: number
+  /** Shape `text` on the engine (see flux:font prepareText): every unit
+   * carries its glyphs, for `layoutText`. */
+  prepare(text: string, options?: FontPrepareOptions): PreparedText
+  /** The glyph's frame and placement, or null while its cell is not in
+   * the atlas (request it with `request`). */
+  glyph(id: number): Glyph | null
+  /** Ask for the cells of `ids` the atlas lacks; they land at a later
+   * frame and every listening run is re-framed. */
+  request(ids: Iterable<number>): void
+  /** Resolves once no cells are in the making: the font is drawable as
+   * asked. */
+  ready(): Promise<void>
+  /** Free the engine font and its atlas texture; runs over it must be
+   * gone. */
+  dispose(): void
+  /** Internal: the runs to re-frame when cells land. */
+  _listeners: Set<FontListener>
+}
+
+/**
+ * Create a sprite font over a registered face (a role alias such as
+ * "sans" or a registered family, the weight and style, and the size a
+ * mask atlas is made at and text shapes at by default). Printable ASCII
+ * is made right away; `ready()` tells when. Freed with the owning
+ * reactive scope like a texture (opt out with `{ autoFree: false }`).
+ */
+export function createSpriteFont(face: FontFace, opts?: SpriteFontOptions): SpriteFont {
+  let { chars, autoFree, ...atlasOptions } = opts ?? {}
+  let id = createFont(face, { cells: "msdf", ...atlasOptions })
+  let info = fontAtlas(id)
+  let atlas: Atlas = { texture: info.texture, width: info.width, height: info.height }
+  if (info.cells === "msdf") atlas.sdf = { range: info.range }
+  let glyphs = new Map<number, Glyph>()
+  let known = new Set<number>()
+  // Requests in flight, and who waits for all of them to land.
+  let inFlight = 0
+  let waiting: (() => void)[] = []
+  let disposed = false
+
+  let toGlyph = (cell: GlyphCell): Glyph => ({
+    frame: {
+      texture: atlas.texture,
+      u0: cell.x / atlas.width,
+      v0: cell.y / atlas.height,
+      u1: (cell.x + cell.width) / atlas.width,
+      v1: (cell.y + cell.height) / atlas.height,
+    },
+    width: cell.width,
+    height: cell.height,
+    left: cell.left,
+    top: cell.top,
+  })
+
+  // Cells landed: take the atlas's size (a change means every cell moved
+  // and every frame is re-cut), record the arrivals, tell the runs.
+  let landed = (ids: number[], cells: (GlyphCell | null)[]) => {
+    if (disposed) return
+    let now = fontAtlas(id)
+    let grew = now.width !== atlas.width || now.height !== atlas.height
+    atlas.width = now.width
+    atlas.height = now.height
+    let arrived = new Set<number>()
+    if (grew) {
+      let all = [...known]
+      glyphs.clear()
+      glyphCells(id, all).forEach((cell, i) => {
+        if (cell !== null) glyphs.set(all[i]!, toGlyph(cell))
+      })
+    }
+    cells.forEach((cell, i) => {
+      // A failed glyph (null) stays absent: drawn as nothing at its advance.
+      if (cell !== null) glyphs.set(ids[i]!, toGlyph(cell))
+      arrived.add(ids[i]!)
+    })
+    for (let listener of font._listeners) listener._reframe(grew, arrived)
+  }
+
+  let font: SpriteFont = {
+    id,
+    atlas,
+    size: info.size,
+    fontSize: info.fontSize,
+    _listeners: new Set(),
+    prepare(text, options) {
+      if (disposed) throw new Error("prepare: the sprite font is disposed")
+      return prepareText(id, text, options)
+    },
+    glyph(glyph) {
+      return glyphs.get(glyph) ?? null
+    },
+    request(ids) {
+      if (disposed) return
+      let missing: number[] = []
+      for (let glyph of ids) {
+        if (!known.has(glyph)) {
+          known.add(glyph)
+          missing.push(glyph)
+        }
+      }
+      if (missing.length === 0) return
+      inFlight++
+      requestGlyphs(id, missing)
+        .then(cells => landed(missing, cells))
+        .catch(error => console.warn(`[2d] glyph request failed: ${error}`))
+        .finally(() => {
+          inFlight--
+          if (inFlight === 0) {
+            let resolve = waiting
+            waiting = []
+            for (let r of resolve) r()
+          }
+        })
+    },
+    ready() {
+      if (inFlight === 0) return Promise.resolve()
+      return new Promise(resolve => waiting.push(resolve))
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      font._listeners.clear()
+      destroyFont(id)
+    },
+  }
+  if (chars !== false) {
+    let warm = chars ?? ascii()
+    let ids = new Set<number>()
+    for (let unit of font.prepare(warm).units) for (let g of unit.glyphs ?? []) ids.add(g.id)
+    font.request(ids)
+  }
+  if (autoFree !== false && getOwner()) onCleanup(() => font.dispose())
+  return font
+}
+
+function ascii(): string {
+  let out = ""
+  for (let c = ASCII_FIRST; c <= ASCII_LAST; c++) out += String.fromCharCode(c)
+  return out
+}