@solidrt/2d 0.0.66 → 0.0.68

package/src/frames.ts

@@ -1,19 +1,44 @@
-// Atlas frame math, pure: names and grid coordinates to normalized UV rects.
-// No GPU or GUI imports, so its test (tests/frames.test.ts) exercises
-// this module headless on the flux binary.
+// Atlas frame math, pure: names and grid coordinates to normalized UV rects,
+// each stamped with the texture it is cut from. No GPU or GUI imports (the
+// Atlas and TextureId imports are types), so its test
+// (tests/frames.test.ts) exercises this module headless on the flux binary.
+import type { TextureId } from "@solidrt/core/gpu"
+import type { Atlas } from "./atlas.ts"
 
 /**
- * One atlas frame as normalized UVs: the rect [u0, v0] to [u1, v1] with
- * top-left origin (the texture pixel contract), u right, v down.
+ * One atlas frame: the texture it is cut from plus the rect [u0, v0] to
+ * [u1, v1] in normalized UVs, top-left origin (the texture pixel
+ * contract), u right, v down. A frame is self-describing - PixiJS's
+ * Texture, Phaser's Frame, Unity's Sprite and Godot's AtlasTexture all
+ * pair the texture with the rect - so the same frame draws in every layer
+ * that declares its atlas, and a layer that does not rejects it at the
+ * write (the wrong-sheet bug, caught instead of drawn).
  */
-export type Frame = { u0: number; v0: number; u1: number; v1: number }
+export type Frame = { texture: TextureId; u0: number; v0: number; u1: number; v1: number }
+
+/** Whether a value is a frame: a non-negative integer texture id and four
+ * numeric UVs (what the layers check before touching a record). */
+export function isFrame(f: unknown): f is Frame {
+  let o = f as Frame | null
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    Number.isInteger(o.texture) &&
+    o.texture >= 0 &&
+    typeof o.u0 === "number" &&
+    typeof o.v0 === "number" &&
+    typeof o.u1 === "number" &&
+    typeof o.v1 === "number"
+  )
+}
 
 /**
  * Write a frame's four UVs at `at`, mirrored on the UV side when flipped:
  * `flipX` swaps u0/u1, `flipY` swaps v0/v1. A flip is an involution, so the
  * same call with the stored floats and only the CHANGED axes set toggles a
  * flip in place, and reading back through it recovers the frame. Positional
- * floats so the write allocates nothing.
+ * floats so the write allocates nothing; the texture's sampler index is the
+ * layer's own field beside these four.
  */
 export function writeFrame(
   data: Float32Array,
@@ -32,12 +57,9 @@ export function writeFrame(
 }
 
 /**
- * What the slicers need of an atlas: its pixel size, the space every rect
- * and gap below is measured in. An `Atlas` fits as it is; a texture from
- * anywhere else (a render target, a camera) passes `{ width, height }`.
+ * The geometry of a uniform sheet: what `grid` reads to place cells, and
+ * what `extrudeGrid` returns for the sheet it repacks.
  */
-export type AtlasSize = { width: number; height: number }
-
 export type GridOptions = {
   /** Cell size in pixels; defaults to width/cols x height/rows. */
   cellW?: number
@@ -47,29 +69,23 @@ export type GridOptions = {
   /** Pixel offset of the first cell from the top-left corner; default 0. */
   marginX?: number
   marginY?: number
-  /**
-   * Texels shaved off every side of each frame; default 0. Only a
-   * mipmapped atlas needs it: 2^k texels keep mip level k inside the cell
-   * (the layer shaders already clamp level-0 samples into the frame), at
-   * the cost of that border of every sprite. The stopgap until extrusion
-   * (okf/backlog/2d-atlas-extrude.md).
-   */
-  inset?: number
 }
 
-export type NamedFramesOptions = {
-  /** As GridOptions.inset: texels shaved off every side of each rect. */
-  inset?: number
+/** The slicers' atlas check: a positive pixel size and a texture id to
+ * stamp (throws - the dev validation policy). */
+function checkAtlas(what: string, atlas: Atlas): void {
+  if (!(atlas.width > 0 && atlas.height > 0)) {
+    throw new Error(`${what}: atlas size must be positive, got ${atlas.width} x ${atlas.height}`)
+  }
+  if (!(Number.isInteger(atlas.texture) && atlas.texture >= 0)) {
+    throw new Error(`${what}: atlas has no texture id, got ${JSON.stringify(atlas.texture)}`)
+  }
 }
 
-/** A pixel rect to UVs, shrunk by `inset` on every side; `what` names the throw. */
-function frameOf(atlas: AtlasSize, x: number, y: number, w: number, h: number, inset: number, what: string): Frame {
-  if (!(inset >= 0)) throw new Error(`${what}: inset must be non-negative, got ${inset}`)
-  let iw = w - inset * 2
-  let ih = h - inset * 2
-  if (!(iw > 0 && ih > 0)) throw new Error(`${what}: inset ${inset} leaves no frame of a ${w} x ${h} rect`)
-  let { width, height } = atlas
-  return { u0: (x + inset) / width, v0: (y + inset) / height, u1: (x + inset + iw) / width, v1: (y + inset + ih) / height }
+/** A pixel rect of `atlas` to a frame over its texture. */
+function frameOf(atlas: Atlas, x: number, y: number, w: number, h: number): Frame {
+  let { width, height, texture } = atlas
+  return { texture, u0: x / width, v0: y / height, u1: (x + w) / width, v1: (y + h) / height }
 }
 
 /**
@@ -80,18 +96,17 @@ function frameOf(atlas: AtlasSize, x: number, y: number, w: number, h: number, i
  *
  * Cells that touch do not bleed at mip level 0: the layer shaders clamp
  * every sample into its frame (shaders.ts). A mip chain is different - its
- * texels straddle cell edges before sampling - so a mipmapped sheet packs
- * a gutter (`spacing`) or shaves its frames (`inset`); see namedFrames.
+ * texels straddle cell edges before sampling - so a sheet going through
+ * `createAtlas` with `mipmap` is extruded first (`extrudeGrid`, whose
+ * returned options slice the repacked sheet).
  */
-export function grid(atlas: AtlasSize, cols: number, rows: number, opts?: GridOptions): Frame[] {
+export function grid(atlas: Atlas, cols: number, rows: number, opts?: GridOptions): Frame[] {
   if (!(cols > 0 && rows > 0 && Number.isInteger(cols) && Number.isInteger(rows))) {
     throw new Error(`grid: cols and rows must be positive integers, got ${cols} x ${rows}`)
   }
+  checkAtlas("grid", atlas)
   let { width, height } = atlas
-  if (!(width > 0 && height > 0)) {
-    throw new Error(`grid: atlas size must be positive, got ${width} x ${height}`)
-  }
-  let { spacing = 0, marginX = 0, marginY = 0, inset = 0 } = opts ?? {}
+  let { spacing = 0, marginX = 0, marginY = 0 } = opts ?? {}
   let cellW = opts?.cellW ?? (width - marginX * 2 - spacing * (cols - 1)) / cols
   let cellH = opts?.cellH ?? (height - marginY * 2 - spacing * (rows - 1)) / rows
   if (!(cellW > 0 && cellH > 0)) {
@@ -102,7 +117,7 @@ export function grid(atlas: AtlasSize, cols: number, rows: number, opts?: GridOp
     for (let col = 0; col < cols; col++) {
       let x = marginX + col * (cellW + spacing)
       let y = marginY + row * (cellH + spacing)
-      frames.push(frameOf(atlas, x, y, cellW, cellH, inset, "grid"))
+      frames.push(frameOf(atlas, x, y, cellW, cellH))
     }
   }
   return frames
@@ -123,28 +138,23 @@ export function grid(atlas: AtlasSize, cols: number, rows: number, opts?: GridOp
  * flashing a one-texel line of the cell next door - is handled in the
  * layer shaders, which clamp every sample into its frame. What they cannot
  * handle is a mip chain, whose texels average across cell edges before
- * sampling: a mipmapped sheet passes `inset` (2^k texels keeps level k
- * clean, losing that border) or packs a gutter, until extrusion lands
- * (okf/backlog/2d-atlas-extrude.md).
+ * sampling: a sheet uploaded with `mipmap` is extruded first
+ * (`extrudeRects`, whose returned table names the repacked rects).
  */
-export function namedFrames<K extends string>(
-  atlas: AtlasSize,
-  rects: Record<K, [number, number, number, number]>,
-  opts?: NamedFramesOptions,
-): Record<K, Frame> {
-  let { width, height } = atlas
-  if (!(width > 0 && height > 0)) {
-    throw new Error(`namedFrames: atlas size must be positive, got ${width} x ${height}`)
-  }
-  let inset = opts?.inset ?? 0
+export function namedFrames<K extends string>(atlas: Atlas, rects: Record<K, [number, number, number, number]>): Record<K, Frame> {
+  checkAtlas("namedFrames", atlas)
   let out = {} as Record<K, Frame>
   for (let name in rects) {
     let [x, y, w, h] = rects[name]
     if (!(w > 0 && h > 0)) throw new Error(`namedFrames: frame '${name}' has non-positive size ${w} x ${h}`)
-    out[name] = frameOf(atlas, x, y, w, h, inset, `namedFrames: frame '${name}'`)
+    out[name] = frameOf(atlas, x, y, w, h)
   }
   return out
 }
 
-/** The whole texture as one frame (a plain image used as a sprite). */
-export const FULL_FRAME: Frame = { u0: 0, v0: 0, u1: 1, v1: 1 }
+/** The whole texture as one frame (a plain image used as a sprite, a
+ * render target shown by a sprite). */
+export function fullFrame(atlas: Atlas): Frame {
+  checkAtlas("fullFrame", atlas)
+  return { texture: atlas.texture, u0: 0, v0: 0, u1: 1, v1: 1 }
+}

package/src/index.ts

@@ -1,29 +1,35 @@
 // @solidrt/2d - an instanced sprite layer above @solidrt/core/gpu.
-// One atlas, N quads in one draw per VIEW: a layer holds the sprites and
-// shows only through its views (layer.createView / <View2d>, each a target
-// with a camera of its own - a Unity scene renders only through Cameras,
-// a Godot World2D only through Viewports). The live layer
+// A layer's atlases bound together, N quads in one draw per VIEW: a layer
+// holds the sprites and shows only through its views (layer.createView /
+// <View2d>, each a target with a camera of its own - a Unity scene renders
+// only through Cameras, a Godot World2D only through Viewports); every
+// frame names its texture, so sprites from several sheets interleave in
+// the one draw (the PixiJS/Phaser multi-texture batch). The live layer
 // (createSpriteLayer/addSprite) backs every sprite with a SPATIAL ARENA
 // node whose Pose2D record sink writes the pose instance buffer at the
 // core flush, so core producers reach sprites and picking walks the core
 // BVH; style stays a JS-written second instance buffer. The records layer (createRecordLayer)
-// is the raw escape hatch for motion only JS can compute: 13 JS-owned
-// floats per sprite published through the zero-copy write lease. The baked
+// is the raw escape hatch for motion only JS can compute: 16 JS-owned
+// floats per sprite in a mirror, published by dirty range through the
+// 3d record mesh's verbs (records/updateRecords/setRecordCount). The baked
 // tile layer (createTileLayer/TileLayer) is the static sibling: a tile
 // world rendered once into textures and composited as a few quads,
 // re-baked on change. Two faces throughout: the imperative core (usable
 // without Solid components) and the components (SpriteLayer/Sprite/Group/
-// View2d/TileLayer) on top. See AGENTS.md for the model and the traps.
+// View2d/TileLayer) on top. Sheets reach the GPU through createAtlas,
+// sliced by grid/namedFrames/fullFrame, and a mipmapped sheet is extruded
+// first (extrudeGrid/extrudeRects). See AGENTS.md for the model and the
+// traps.
 
 export { addGroup, addSprite, createSpriteLayer, getSprite, destroyGroup, destroySprite, setGroup, setGroupTransition, setSprite, setSpriteParent, setSpriteTransition, worldPosition, POSE_FLOATS, STYLE_FLOATS } from "./layer.ts"
-export { createRecordLayer, FLOATS_PER_SPRITE } from "./records.ts"
-export type { RecordLayer as RecordLayerHandle, RecordLayerOptions } from "./records.ts"
-export { pointInSprite } from "./pick.ts"
+export { createRecordLayer, records, setRecordCount, updateRecords, INSTANCE_FLOATS } from "./records.ts"
+export type { RecordLayer as RecordLayerHandle, RecordLayerOptions, UpdateRecordsOptions } from "./records.ts"
+export { floorReach, pointInSprite } from "./pick.ts"
 export { projectCamera, unprojectCamera } from "./camera.ts"
 export type { CameraState, CameraUpdate } from "./camera.ts"
 export { createCamera2d } from "./camera2d.ts"
-export type { Camera2d as Camera2dHandle, Camera2dAxes, Camera2dOptions, Camera2dPose, Camera2dTarget, Rect2d } from "./camera2d.ts"
-export { createShots, mixCamera2d } from "./shots.ts"
+export type { Camera2d as Camera2dHandle, Camera2dAxes, Camera2dOptions, Camera2dPose, Camera2dPoseState, Camera2dTarget, Rect2d } from "./camera2d.ts"
+export { createShots, mixCamera } from "./shots.ts"
 export type { ShotTarget, ShotsHandle } from "./shots.ts"
 export { camera2dActions, camera2dBindings } from "./input.ts"
 export type { CameraDevices } from "./input.ts"
@@ -39,6 +45,7 @@ export type {
   QueryOptions,
   Hit,
   Rect,
+  LayerEventBase,
   LayerPointerEvent,
   LayerPointerListener,
   LayerTapEvent,
@@ -59,17 +66,29 @@ export type {
   Volume,
 } from "./layer.ts"
 export { feedPointer } from "./views.ts"
+export { moveAndSlide } from "./collision.ts"
+export type { MoveLayer } from "./collision.ts"
 export type { ViewHandle, ViewOptions } from "./views.ts"
 export { createTileLayer } from "./tiles.ts"
 export type { TileChunk, TileLayer as TileLayerHandle, TileLayerOptions } from "./tiles.ts"
 
-export type { NodeTransition, NodeTransitionSpec } from "flux:spatial"
-export { grid, namedFrames, FULL_FRAME } from "./frames.ts"
-export type { AtlasSize, Frame, GridOptions, NamedFramesOptions } from "./frames.ts"
+export type { NodeMotionSpec, NodeTransitionSpec } from "flux:spatial"
+export { fullFrame, grid, isFrame, namedFrames } from "./frames.ts"
+export type { Frame, GridOptions } from "./frames.ts"
+export { extrudeGrid, extrudeRects } from "./extrude.ts"
+export type { ExtrudedGrid, ExtrudedRects, Rects } from "./extrude.ts"
+export { packRects, packWidth } from "./pack.ts"
+export type { Packing, Placement, Size } from "./pack.ts"
 export { createAnimation } from "./animation.ts"
 export type { AnimationOptions, SpriteAnimation } from "./animation.ts"
 export { fitOversample } from "./oversample.ts"
-export { createAtlas } from "./atlas.ts"
+export { createAtlas, isAtlas } from "./atlas.ts"
 export type { Atlas, AtlasOptions } from "./atlas.ts"
-export { Camera2d, Group, Sprite, SpriteLayer, TileLayer, View2d, useSpriteLayer, Shot, Shots } from "./components/index.ts"
-export type { Camera2dProps, GroupProps, LayerPointerProps, SpriteLayerProps, SpritePointerProps, SpriteProps, TileCamera, TileLayerProps, View2dProps, ShotProps, ShotsProps } from "./components/index.ts"
+export { createSpriteFont } from "./font.ts"
+export type { FontListener, Glyph, SpriteFont, SpriteFontOptions } from "./font.ts"
+export { layoutText } from "./text-layout.ts"
+export type { GlyphPlacement, TextAlign, TextAnchor, TextAnchorY, TextLayout, TextLayoutOptions, TextLine } from "./text-layout.ts"
+export { addText, destroyText, setText } from "./text.ts"
+export type { AddTextOptions, TextPose, TextRun, TextStyle } from "./text.ts"
+export { Camera2d, Group, Sprite, SpriteLayer, Text2d, TileLayer, View2d, useSpriteLayer, Shot, Shots } from "./components/index.ts"
+export type { BubblingSpritePointerProps, Camera2dProps, GroupProps, LayerPointerProps, SpriteLayerProps, SpritePointerProps, SpriteProps, TileCamera, TileLayerProps, View2dProps, ShotProps, ShotsProps } from "./components/index.ts"