phoria2 1.1.0 → 1.2.0

package/src/scene/drawables.js

@@ -12,7 +12,7 @@ import { NODE_OPTIONS, Node } from './Node.js'
 /** @import { Material, MaterialOptions } from '../material/Material.js' */
 /** @import { GeometryOptions } from '../geometry/Geometry.js' */
 /** @import { NodeOptions } from './Node.js' */
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 
 /**
  * @typedef {NodeOptions & {
@@ -45,11 +45,14 @@ import { NODE_OPTIONS, Node } from './Node.js'
  * @property {'left' | 'right' | null} [edge] set the label at the view's left or right edge, level with its
  *   point - callouts in a column down the side of a diagram, with leader: true. offset then moves it in from
  *   the edge and up or down (default null: by its point)
+ * @property {number} [minScale] show the label only when zoomed in this far: at least this many CSS pixels to
+ *   one world unit, at the label's point - details that appear as you come closer (default 0: always)
  */
 /** @typedef {'center' | 'above' | 'below' | 'left' | 'right'} LabelPlace */
 
 /**
- * One label per instance or point, from its row of data.
+ * One label per instance or point, from its row of data - or a list of these, for several each (a symbol
+ * always, its details when zoomed in).
  * @typedef {Omit<LabelPlacement, 'priority'> & {
  *   text: (datum: any, index: number) => string | number | null | undefined,
  *   priority?: number | ((datum: any, index: number) => number),
@@ -61,7 +64,7 @@ import { NODE_OPTIONS, Node } from './Node.js'
  */
 
 export const LABEL_PLACES = /** @type {LabelPlace[]} */ (['center', 'above', 'below', 'left', 'right'])
-const PLACEMENT_OPTIONS = ['place', 'offset', 'className', 'priority', 'overlap', 'occlude', 'leader', 'edge']
+const PLACEMENT_OPTIONS = ['place', 'offset', 'className', 'priority', 'overlap', 'occlude', 'leader', 'edge', 'minScale']
 const LABEL_HINTS = {
   line: 'use leader: true - a line from the point to the label',
   callout: "use leader: true, with edge: 'left' | 'right' to line the labels up down the side",
@@ -70,6 +73,8 @@ const LABEL_HINTS = {
   pointer: 'use leader: true - a line from the point to the label',
   anchor: "use place: 'center' | 'above' | 'below' | 'left' | 'right' (where the label goes)",
   zIndex: "use 'priority': higher stays when labels overlap",
+  minZoom: "use 'minScale': CSS pixels to one world unit at the label's point",
+  lod: "use 'minScale': the label shows when zoomed in at least this far (CSS pixels to one world unit)",
   collision: "use overlap: 'hide' | 'dim' | 'show'",
 }
 // labels per instance or point take one more: they can't be moved anywhere but by offset
@@ -94,12 +99,26 @@ function placement(owner, o) {
     occlude: !!o.occlude,
     leader: !!o.leader,
     edge: o.edge == null ? null : /** @type {'left' | 'right'} */ (checkOneOf(owner, 'edge', o.edge, ['left', 'right'])),
+    minScale: o.minScale === undefined ? 0 : minScale(owner, o.minScale),
   }
 }
 
-/** @param {string} owner @param {unknown} v @returns {(InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & { priority: number | ((datum: any, index: number) => number) }) | null} */
+/** @param {string} owner @param {unknown} v @returns {number} */
+function minScale(owner, v) {
+  const n = checkNumber(owner, 'minScale', v)
+  if (!(n >= 0)) fail(owner, `'minScale' is CSS pixels to one world unit, 0 or more, got ${n}`)
+  return n
+}
+
+/** @typedef {InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & { priority: number | ((datum: any, index: number) => number) }} CheckedLabels */
+
+/** @param {string} owner @param {unknown} v @returns {CheckedLabels | CheckedLabels[] | null} */
 function instanceLabels(owner, v) {
   if (v == null) return null
+  if (Array.isArray(v)) {
+    if (!v.length) fail(owner, "'labels' as a list needs at least one { text: (datum, index) => string, ... }")
+    return v.map((one) => /** @type {CheckedLabels} */ (instanceLabels(owner, one)))
+  }
   if (typeof v !== 'object' || typeof (/** @type {any} */ (v)).text !== 'function') {
     fail(owner, `'labels' must be { text: (datum, index) => string, ... }, got ${describe(v)}`)
   }
@@ -253,7 +272,7 @@ export class Mesh extends Drawable {
  * @typedef {object} InstanceOptions
  * @property {Vec3Input} [position]
  * @property {Vec3Input | Euler} [rotation] Euler angles in radians, XYZ order
- * @property {ArrayLike<number>} [quaternion]
+ * @property {QuatInput} [quaternion] [x, y, z, w] or { x, y, z, w } - as physics engines give them
  * @property {Vec3Input | number} [scale]
  * @property {ColorInput} [color] multiplies the material colour
  */
@@ -261,11 +280,23 @@ export class Mesh extends Drawable {
 const INSTANCE_OPTIONS = new Set(['position', 'rotation', 'quaternion', 'scale', 'color'])
 // reused by setInstance, so updating every instance of a large mesh each frame allocates nothing
 const scratch = { position: new Vec3(), scale: new Vec3(), quaternion: new Quat(), rotation: new Euler() }
+const SCRATCH_COLOR = new Color()
 const scratchMatrix = new Float32Array(16)
 
+/**
+ * True when an instance is scaled to nothing - hidden: it draws nothing, takes no room in its mesh's
+ * bounds and shows no label.
+ * @internal @param {ArrayLike<number>} m instance matrices @param {number} i
+ */
+export function hiddenInstance(m, i) {
+  const o = i * 16
+  return !m[o] && !m[o + 1] && !m[o + 2] && !m[o + 4] && !m[o + 5] && !m[o + 6] && !m[o + 8] && !m[o + 9] && !m[o + 10]
+}
+
 /**
  * Many copies of one geometry and material, drawn together. Set each copy with setInstance().
- * Picking reports which instance was hit.
+ * Picking reports which instance was hit. An instance scaled to 0 is hidden - it draws nothing, and
+ * framing, culling, shadows and labels leave it out - so a pool of instances can keep spares.
  */
 export class InstancedMesh extends Mesh {
   static type = 'instanced-mesh'
@@ -279,12 +310,12 @@ export class InstancedMesh extends Mesh {
   instanceColors = null
   /** @internal Bumped when instance data changes, so renderers re-upload. */
   version = 0
-  /** A label per instance, from its row of data. @type {ReturnType<typeof instanceLabels>} */
+  /** A label per instance from its row of data - or a list of them, several per instance. @type {ReturnType<typeof instanceLabels>} */
   labels = null
 
   /**
    * @param {DrawableOptions & { count?: number, instances?: InstanceOptions[], instanceMatrices?: ArrayLike<number>,
-   *   instanceColors?: ArrayLike<number>, labels?: InstanceLabels | null }} options count defaults to the number
+   *   instanceColors?: ArrayLike<number>, labels?: InstanceLabels | InstanceLabels[] | null }} options count defaults to the number
    *   of instances or rows of data; instanceMatrices/instanceColors are raw data, as toJSON() writes
    */
   constructor(options) {
@@ -375,7 +406,7 @@ export class InstancedMesh extends Mesh {
   /** @param {number} i @param {ColorInput} color */
   #setColor(i, color) {
     if (!this.instanceColors) this.instanceColors = new Float32Array(this.instanceMatrices.length / 16 * 3).fill(1)
-    this.instanceColors.set(Color.fromInput(color, 'InstancedMesh'), i * 3)
+    this.instanceColors.set(SCRATCH_COLOR.set(color, 'InstancedMesh'), i * 3)
   }
 
   /** @internal @param {Box3} box */
@@ -401,6 +432,7 @@ export class InstancedMesh extends Mesh {
     const ex = (local.max[0] - local.min[0]) / 2, ey = (local.max[1] - local.min[1]) / 2, ez = (local.max[2] - local.min[2]) / 2
     const w = this.worldMatrix, im = this.instanceMatrices, m = scratchMatrix
     for (let i = 0; i < this.count; i++) {
+      if (hiddenInstance(im, i)) continue
       mat4.multiply(m, w, im.subarray(i * 16, i * 16 + 16))
       const x = m[0] * cx + m[4] * cy + m[8] * cz + m[12]
       const y = m[1] * cx + m[5] * cy + m[9] * cz + m[13]
@@ -436,10 +468,10 @@ export class Points extends Drawable {
   static type = 'points'
   static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'labels'] }
 
-  /** A label per point, from its row of data. @type {ReturnType<typeof instanceLabels>} */
+  /** A label per point from its row of data - or a list of them, several per point. @type {ReturnType<typeof instanceLabels>} */
   labels = null
 
-  /** @param {DrawableOptions & { labels?: InstanceLabels | null }} options */
+  /** @param {DrawableOptions & { labels?: InstanceLabels | InstanceLabels[] | null }} options */
   constructor(options) {
     super(options)
     this.labels = instanceLabels(this.constructor.name, options?.labels)
@@ -505,6 +537,8 @@ export class Label extends Node {
   leader = false
   /** Set at the view's left or right edge, level with its point, or null for by its point. @type {'left' | 'right' | null} */
   edge = null
+  /** Shown only when zoomed in this far: CSS pixels to one world unit at its point; 0 for always. */
+  minScale = 0
 
   /** @param {LabelOptions} options */
   constructor(options) {
@@ -529,7 +563,8 @@ export class Label extends Node {
   /** @internal @returns {Record<string, unknown>} */
   cloneOptions() {
     return { ...super.cloneOptions(), text: this.text, className: this.className, place: this.place,
-      offset: [...this.offset], priority: this.priority, overlap: this.overlap, occlude: this.occlude, leader: this.leader, edge: this.edge }
+      offset: [...this.offset], priority: this.priority, overlap: this.overlap, occlude: this.occlude, leader: this.leader, edge: this.edge,
+      minScale: this.minScale }
   }
 
   /** @internal @returns {Record<string, unknown>} */
@@ -544,6 +579,7 @@ export class Label extends Node {
     if (this.occlude) json.occlude = true
     if (this.leader) json.leader = true
     if (this.edge) json.edge = this.edge
+    if (this.minScale) json.minScale = this.minScale
     return json
   }
 }

package/src/scene/lights.js

@@ -1,10 +1,11 @@
 import { Color } from '../value/Color.js'
 import { Vec3 } from '../value/Vec3.js'
-import { checkNumber, fail } from '../validate.js'
+import { Box3 } from '../value/Box3.js'
+import { checkNumber, describe, fail } from '../validate.js'
 import { NODE_OPTIONS, Node, inParentSpace, setPoint } from './Node.js'
 
 /** @import { NodeOptions } from './Node.js' */
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { Box3Input, ColorInput, Vec3Input } from '../types.js' */
 
 /** @typedef {NodeOptions & { color?: ColorInput, intensity?: number }} LightOptions */
 /** @typedef {'ambient' | 'hemisphere' | 'directional' | 'point' | 'spot'} LightKind */
@@ -189,24 +190,57 @@ export class DirectionalLight extends AimedLight {
   static type = 'directional-light'
   /** @internal @type {LightKind} */
   static kind = 'directional'
-  static get OPTIONS() { return [...LIGHT_OPTIONS, 'direction', 'target', 'castShadow'] }
+  static get OPTIONS() { return [...LIGHT_OPTIONS, 'direction', 'target', 'castShadow', 'shadowBounds'] }
 
   castShadow = false
+  /** @type {Box3 | null} */
+  #shadowBounds = null
 
-  /** @param {AimedLightOptions & { castShadow?: boolean }} [options] */
+  /** @param {AimedLightOptions & { castShadow?: boolean, shadowBounds?: Box3Input | null }} [options] */
   constructor(options = {}) {
     super(options)
     if (options.castShadow !== undefined) this.castShadow = !!options.castShadow
+    if (options.shadowBounds !== undefined) this.#setShadowBounds(options.shadowBounds)
+  }
+
+  /**
+   * The part of the world, in world units, that has shadows - or null (the default) to follow
+   * whatever casts them. The shadow map is fitted to what casts every frame, so one caster flung far
+   * off spreads its texels over everything and every shadow blurs; set the area where things happen
+   * and its shadows stay sharp. Casters outside it still shadow it, from wherever they stand.
+   * Assigning copies.
+   * @returns {Box3 | null}
+   */
+  get shadowBounds() { return this.#shadowBounds }
+
+  /** @param {Box3Input | null} v */
+  set shadowBounds(v) { this.#setShadowBounds(v) }
+
+  /** @param {Box3Input | null} v */
+  #setShadowBounds(v) {
+    if (v === null) {
+      this.#shadowBounds = null
+      return
+    }
+    const b = /** @type {any} */ (v)
+    if (!b || typeof b !== 'object' || !b.min || !b.max) {
+      fail(this.constructor.name, `'shadowBounds' is a box - { min: [x, y, z], max: [x, y, z] } or a Box3 - or null, got ${describe(v)}`)
+    }
+    const box = new Box3(Vec3.fromInput(b.min, this.constructor.name), Vec3.fromInput(b.max, this.constructor.name))
+    if (box.isEmpty()) fail(this.constructor.name, `'shadowBounds' min must not be above max on any axis, got ${describe(v)}`)
+    this.#shadowBounds = box
   }
 
   /** @internal @returns {Record<string, unknown>} */
   cloneOptions() {
-    return { ...super.cloneOptions(), castShadow: this.castShadow }
+    return { ...super.cloneOptions(), castShadow: this.castShadow, shadowBounds: this.#shadowBounds }
   }
 
   /** @internal @returns {Record<string, unknown>} */
   jsonOptions() {
-    return { ...super.jsonOptions(), ...(this.castShadow ? { castShadow: true } : {}) }
+    const b = this.#shadowBounds
+    return { ...super.jsonOptions(), ...(this.castShadow ? { castShadow: true } : {}),
+      ...(b ? { shadowBounds: { min: Array.from(b.min), max: Array.from(b.max) } } : {}) }
   }
 }
 

package/src/shadow.js

@@ -23,9 +23,10 @@ export const SHADOW_MAP_SIZE = 2048
  * @param {Box3[]} casters world bounds
  * @param {Box3[]} receivers world bounds
  * @param {number} [size] map size in texels
+ * @param {Box3 | null} [area] the light's shadowBounds: the map covers this across, whatever casts
  * @returns {ShadowFit | null}
  */
-export function fitShadow(direction, casters, receivers, size = SHADOW_MAP_SIZE) {
+export function fitShadow(direction, casters, receivers, size = SHADOW_MAP_SIZE, area = null) {
   const boxes = casters.filter((b) => !b.isEmpty())
   if (!boxes.length) return null
   const d = normalized(direction)
@@ -50,7 +51,10 @@ export function fitShadow(direction, casters, receivers, size = SHADOW_MAP_SIZE)
       if (z > z1) z1 = z
     }
   }
-  for (const b of boxes) corners(b, true)
+  // across the light's view: the area it was given, or else the casters; in depth, everything that
+  // casts - so a caster outside the area, between it and the light, still shadows it
+  if (area) corners(area, true)
+  for (const b of boxes) corners(b, !area)
   // receivers only stretch the depth (view z is negative in front, so the far end is the minimum)
   for (const b of receivers) if (!b.isEmpty()) corners(b, false)
 
@@ -58,10 +62,29 @@ export function fitShadow(direction, casters, receivers, size = SHADOW_MAP_SIZE)
   const margin = Math.max(x1 - x0, y1 - y0, 1e-3) * 0.02
   x0 -= margin; x1 += margin; y0 -= margin; y1 += margin
   const depthMargin = Math.max(z1 - z0, 1e-3) * 0.01
-  const projection = mat4.ortho(mat4.create(), x0, x1, y0, y1, -z1 - depthMargin, -z0 + depthMargin)
+  z0 -= depthMargin; z1 += depthMargin
+
+  // steady while things move: the map grows and shrinks in small steps rather than with every change
+  // in the casters' extent, and its edges sit on the texel grid, so a shadow that isn't moving falls
+  // on the same texels every frame, instead of shimmering as the fit slides about under it
+  const w = steps(x1 - x0), h = steps(y1 - y0)
+  const tx = w / size, ty = h / size
+  x0 = Math.floor((x0 + x1 - w) / 2 / tx) * tx
+  y0 = Math.floor((y0 + y1 - h) / 2 / ty) * ty
+  // the depth range too, which sets what each stored depth means
+  const dz = steps(z1 - z0) / 64
+  z0 = Math.floor(z0 / dz) * dz
+  z1 = Math.ceil(z1 / dz) * dz
+
+  const projection = mat4.ortho(mat4.create(), x0, x0 + w, y0, y0 + h, -z1, -z0)
   const viewProjection = new Mat4()
   mat4.multiply(viewProjection, projection, view)
-  return { viewProjection, texelSize: Math.max(x1 - x0, y1 - y0) / size }
+  return { viewProjection, texelSize: Math.max(w, h) / size }
+}
+
+/** A length rounded up to the next of a ladder of sizes, sixteen to each doubling. @param {number} v */
+function steps(v) {
+  return 2 ** (Math.ceil(Math.log2(Math.max(v, 1e-3)) * 16) / 16)
 }
 
 /** Spot shadows' map: four tiles of half its size, one a light. */

package/src/types.js

@@ -9,6 +9,12 @@
 
 /** A vector as accepted on input: [x, y, z], { x, y, z } or a Vec3. @typedef {Vec3Like | XYZ} Vec3Input */
 
+/** A quaternion as an object literal - as physics engines such as Rapier return them. @typedef {{ x: number, y: number, z: number, w: number }} XYZW */
+
+/** A rotation quaternion as accepted on input: [x, y, z, w], { x, y, z, w } or a Quat. @typedef {ArrayLike<number> | XYZW} QuatInput */
+
+/** A box as accepted on input: a Box3, or its lowest and highest corners. @typedef {import('./value/Box3.js').Box3 | { min: Vec3Input, max: Vec3Input }} Box3Input */
+
 /**
  * A colour as accepted on input, in sRGB: '#ff8800', '#f80', 0xff8800, 'rgb(255 136 0)',
  * 'hsl(32 100% 50%)', a CSS colour name, or [r, g, b] with components 0-1.

package/src/value/Color.js

@@ -16,6 +16,11 @@ const HELP = "use '#rrggbb', a CSS name, 'rgb(...)', 'hsl(...)', 0xrrggbb or [r,
  * An RGB colour. Input is sRGB, as everywhere in phoria2; the components are stored **linear**,
  * ready for lighting maths. `toJSON()` gives sRGB '#rrggbb' back.
  */
+// colour strings already worked out, as linear rgb - emptied when full, as a palette never fills it
+/** @type {Map<string, number[]>} */
+const PARSED = new Map()
+const PARSED_MAX = 1024
+
 export class Color extends Float32Array {
   static get [Symbol.species]() { return Float32Array }
 
@@ -154,6 +159,22 @@ export class Color extends Float32Array {
 
   /** @param {string} s @param {string} owner */
   #setString(s, owner) {
+    // the same few strings come again and again - an instance's colour set every frame - so each is
+    // worked out once
+    const known = PARSED.get(s)
+    if (known) {
+      this[0] = known[0]
+      this[1] = known[1]
+      this[2] = known[2]
+      return
+    }
+    this.#parse(s, owner)
+    if (PARSED.size >= PARSED_MAX) PARSED.clear()
+    PARSED.set(s, [this[0], this[1], this[2]])
+  }
+
+  /** @param {string} s @param {string} owner */
+  #parse(s, owner) {
     const lower = s.toLowerCase()
     if (lower.startsWith('#')) {
       let hex = lower.slice(1)

package/src/value/Quat.js

@@ -1,6 +1,8 @@
 import * as quat from '../math/quat.js'
 import { describe, fail } from '../validate.js'
 
+/** @import { QuatInput } from '../types.js' */
+
 /**
  * A rotation quaternion [x, y, z, w]: a Float32Array(4) with accessors and chainable methods.
  * A node's quaternion and its Euler `rotation` keep each other in sync through these setters;
@@ -61,13 +63,20 @@ export class Quat extends Float32Array {
     return this.changed()
   }
 
-  /** @param {ArrayLike<number>} q [x, y, z, w] @param {string} [owner] @returns {this} */
+  /** @param {QuatInput} q [x, y, z, w], or { x, y, z, w } as physics engines give them @param {string} [owner] @returns {this} */
   copy(q, owner = 'Quat') {
-    if (!q || typeof q !== 'object' || !(q.length >= 4)) fail(owner, `expected a quaternion [x, y, z, w], got ${describe(q)}`)
-    this[0] = q[0]
-    this[1] = q[1]
-    this[2] = q[2]
-    this[3] = q[3]
+    const o = /** @type {any} */ (q)
+    if (o && typeof o === 'object' && o.length >= 4) {
+      this[0] = o[0]
+      this[1] = o[1]
+      this[2] = o[2]
+      this[3] = o[3]
+    } else if (o && typeof o === 'object' && 'x' in o && 'y' in o && 'z' in o && 'w' in o) {
+      this[0] = o.x
+      this[1] = o.y
+      this[2] = o.z
+      this[3] = o.w
+    } else fail(owner, `expected a quaternion [x, y, z, w] or { x, y, z, w }, got ${describe(q)}`)
     return this.changed()
   }
 

package/src/watch.js

@@ -123,7 +123,7 @@ export class ChangeWatch {
     this.#push((node.handlersFor('click').length ? 1 : 0) | (node.handlersFor('hover').length ? 2 : 0) | (node.tooltip ? 4 : 0) | (node.onDrag ? 8 : 0) | (node.highlightWhole ? 16 : 0))
     // what hovering tints it with - a different colour shows straight away on what is hovered
     if (node.highlight) this.#pushAll(node.highlight)
-    else this.#push(-4)
+    else this.#push(node.highlight === false ? -5 : -4)
     const outline = node.outline
     if (outline) {
       this.#pushAll(outline.color)
@@ -208,6 +208,7 @@ export class ChangeWatch {
     this.#push(label.priority)
     this.#push(label.occlude ? 1 : 0)
     this.#push(label.leader ? 1 : 0)
+    this.#push(label.minScale)
   }
 
   /** @param {any} light */
@@ -218,6 +219,10 @@ export class ChangeWatch {
     if (light.direction) this.#pushAll(light.direction)
     if (light.target) this.#pushAll(light.target)
     if (light.castShadow) this.#push(1)
+    if (light.shadowBounds) {
+      this.#pushAll(light.shadowBounds.min)
+      this.#pushAll(light.shadowBounds.max)
+    }
     if ('range' in light) this.#push(light.range)
     if ('angle' in light) {
       this.#push(light.angle)