phoria2 1.1.0 → 1.3.0

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)
@@ -147,7 +147,11 @@ export class ChangeWatch {
     this.#push(g.version)
     this.#push(g.drawCount ?? -1)
     this.#push(node.renderOrder)
-    this.#push((node.castShadow ? 1 : 0) | (node.receiveShadow ? 2 : 0))
+    this.#push((node.castShadow ? 1 : 0) | (node.receiveShadow ? 2 : 0) | (node.sort ? 4 : 0))
+    if ('arrowBits' in node) {
+      this.#push(node.arrowBits)
+      this.#push(node.arrowSize)
+    }
     // per-instance labels come from these, so swapping either redraws
     this.#push(node.labels ? idOf(node.labels) : 0)
     this.#push(node.data && typeof node.data === 'object' ? idOf(node.data) : 0)
@@ -164,6 +168,9 @@ export class ChangeWatch {
     this.#push(m.metalness)
     this.#push(m.size)
     this.#push(m.width)
+    this.#push(m.dash)
+    this.#push(m.gap)
+    this.#push(m.dashOffset)
     this.#push(m.alphaTest)
     this.#push(m.normalScale)
     this.#push(m.aoMapIntensity)
@@ -208,6 +215,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 +226,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)

package/src/webgl/WebGLRenderer.js

@@ -117,6 +117,8 @@ export class WebGLRenderer {
   /** This frame's prefiltered environment, when it is an HDR image. @type {Environment | null} */ #environment = null
   /** This frame's shadows - directional, spot, point - for the meshes that receive them. @type {import('./passes.js').ShadowMap[]} */ #shadows = []
   /** @type {Float32Array} */ #normalMatrix = new Float32Array(9)
+  /** Model-view for sorting points back to front. */
+  #modelView = new Float32Array(16)
   /** @type {Record<string, any>} */ #lights = {}
   /** This frame waits for shaders to compile rather than leaving things out. */
   #wait = false
@@ -407,6 +409,7 @@ export class WebGLRenderer {
 
     const clip = kind === 'mesh' ? item.clip : null
     const defines = this.#defines(kind, material, geometry.colors !== null, !!instances, geometry.uvs2 !== null)
+    if (kind === 'points' && /** @type {any} */ (node).drawsSprites) defines.push('SPRITES')
     for (const shadow of shadows) defines.push(shadow.define)
     const fog = material.fog ? frame.fog : null
     if (fog) {
@@ -531,9 +534,18 @@ export class WebGLRenderer {
     if (kind === 'lines') {
       gl.disable(gl.CULL_FACE)
       program.set('uWidth', material.width * this.pixelRatio)
+      const arrows = /** @type {any} */ (node).arrowBits ?? 0
+      program.set('uArrows', arrows)
+      program.set('uArrowSize', /** @type {any} */ (node).arrowPixels?.(material.width) * this.pixelRatio || 0)
+      if (material.dash > 0) {
+        program.set('uDash', material.dash)
+        program.set('uGap', material.gap || material.dash)
+        program.set('uDashOffset', material.dashOffset)
+      }
       const buffers = this.#gpu.resources.lines(geometry)
       gl.bindVertexArray(buffers.vao)
-      gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, Math.min(buffers.count, Math.floor(geometry.drawnCount / 2)))
+      // a quad a segment, and two arrowheads where there are any
+      gl.drawArraysInstanced(gl.TRIANGLES, 0, arrows ? 12 : 6, Math.min(buffers.count, Math.floor(geometry.drawnCount / 2)))
       this.info.drawCalls++
       return
     }
@@ -541,9 +553,27 @@ export class WebGLRenderer {
     if (kind === 'points') {
       gl.disable(gl.CULL_FACE)
       program.set('uSize', material.sizeAttenuation ? material.size : material.size * this.pixelRatio)
-      const buffers = this.#gpu.resources.mesh(geometry, null, false)
-      gl.bindVertexArray(buffers.vao)
-      gl.drawArrays(gl.POINTS, 0, geometry.drawnVertices)
+      // round points are solid, but their edges are soft: blended over what is behind even in the
+      // opaque pass, or the edge fades to black - a dark ring round every dot
+      const round = !transparent && !material.map
+      if (round) {
+        gl.enable(gl.BLEND)
+        gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+      }
+      if (/** @type {any} */ (node).drawsSprites) {
+        // each point a square, any size and turned - drawn back to front when the points ask, for
+        // smoke and other soft things that hide what is behind them
+        program.set('uResolution', [this.canvas.width, this.canvas.height])
+        const modelView = /** @type {any} */ (node).sort ? mat4.multiply(this.#modelView, frame.camera.view, worldMatrix) : null
+        const buffers = this.#gpu.resources.sprites(geometry, modelView)
+        gl.bindVertexArray(buffers.vao)
+        gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, buffers.count)
+      } else {
+        const buffers = this.#gpu.resources.mesh(geometry, null, false)
+        gl.bindVertexArray(buffers.vao)
+        gl.drawArrays(gl.POINTS, 0, geometry.drawnVertices)
+      }
+      if (round) gl.disable(gl.BLEND)
       this.info.drawCalls++
       return
     }
@@ -676,7 +706,8 @@ export class WebGLRenderer {
     } else if (kind === 'points') {
       if (material.map) d.push('MAP')
       if (material.sizeAttenuation) d.push('SIZE_ATTENUATION')
-    }
+    } else if (material.dash > 0) d.push('DASHED')
+    // (points drawn as squares add SPRITES - see #draw, which knows the node)
     return d
   }
 }

package/src/webgl/picking.js

@@ -18,6 +18,9 @@ const PICK_FRAGMENT = /* glsl */ `
 precision highp float;
 precision highp int;
 flat in uint vPickElement;
+#ifdef SPRITES
+in vec2 vUv;
+#endif
 #ifdef CLIP
 in vec3 vWorldPosition;
 #endif
@@ -30,7 +33,11 @@ void main() {
   clipAway(vWorldPosition);
 #endif
 #ifdef ROUND
+#ifdef SPRITES
+  vec2 p = vUv * 2.0 - 1.0;
+#else
   vec2 p = gl_PointCoord * 2.0 - 1.0;
+#endif
   if (dot(p, p) > 1.0) discard;
 #endif
   pickOut = uvec4(uPickId, vPickElement, floatBitsToUint(gl_FragCoord.z), 1u);
@@ -219,9 +226,11 @@ export class Picker {
     const kind = mode === 'points' ? 'points' : mode === 'lines' ? 'lines' : 'mesh'
     const defines = ['PICK']
     if (instances) defines.push('INSTANCED')
+    const sprites = kind === 'points' && /** @type {any} */ (node).drawsSprites
     if (kind === 'points') {
       if (material.sizeAttenuation) defines.push('SIZE_ATTENUATION')
       if (!material.map) defines.push('ROUND')
+      if (sprites) defines.push('SPRITES')
     }
     if (kind === 'mesh' && item.clip) defines.push('CLIP')
     const program = this.programs.ready(`pick-${kind}`, defines, SOURCES[kind])
@@ -240,9 +249,13 @@ export class Picker {
       program.set('uResolution', [REGION, REGION])
       program.set('uWidth', material.width * pixelRatio)
       program.set('uNear', frame.camera.near)
+      // arrowheads pick as their segment; dashes' gaps do too, so a dashed link is as easy to hit
+      const arrows = /** @type {any} */ (node).arrowBits ?? 0
+      program.set('uArrows', arrows)
+      program.set('uArrowSize', /** @type {any} */ (node).arrowPixels?.(material.width) * pixelRatio || 0)
       const buffers = this.resources.lines(geometry)
       gl.bindVertexArray(buffers.vao)
-      gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, Math.min(buffers.count, Math.floor(geometry.drawnCount / 2)))
+      gl.drawArraysInstanced(gl.TRIANGLES, 0, arrows ? 12 : 6, Math.min(buffers.count, Math.floor(geometry.drawnCount / 2)))
       return
     }
     if (kind === 'points') {
@@ -250,6 +263,14 @@ export class Picker {
       // sizes as drawn: world sizes scale by the real projection, not the zoomed one
       program.set('uSize', material.sizeAttenuation ? material.size : material.size * pixelRatio)
       program.set('uScale', frame.camera.projection[5] * height / 2)
+      if (sprites) {
+        // squares, in whatever order they were last drawn - each says which point it is
+        program.set('uResolution', [REGION, REGION])
+        const buffers = this.resources.sprites(geometry)
+        gl.bindVertexArray(buffers.vao)
+        gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, buffers.count)
+        return
+      }
       const buffers = this.resources.mesh(geometry, null, false)
       gl.bindVertexArray(buffers.vao)
       gl.drawArrays(gl.POINTS, 0, geometry.drawnVertices)