phoria2 1.0.0 → 1.2.0

package/src/material/Material.js

@@ -30,8 +30,36 @@ import { Texture } from './Texture.js'
  * @property {MapInput | null} [aoMap] ambient occlusion in its red channel; darkens environment and ambient light
  * @property {number} [aoMapIntensity] 0-1 (default 1)
  * @property {MapInput | null} [emissiveMap] multiplies the emissive colour
+ * @property {MapInput | null} [lightMap] light baked into a texture, added as light from all round - usually on
+ *   the second UV set (uvSet: 1)
+ * @property {number} [lightMapIntensity] (default 1)
+ * @property {number} [environmentIntensity] this material's share of the environment's light and reflections:
+ *   lower for a matte floor in a shiny showroom, higher to make one thing catch the light (default 1)
  * @property {ColorInput} [emissive] glow colour (default black)
  * @property {number} [emissiveIntensity] (default 1)
+ * @property {number} [transmission] 0-1: how much light passes through, as through glass (default 0). Unlike
+ *   opacity, which fades the whole surface, glass keeps its reflections, and shows less of what is behind it
+ *   towards its edges. Its colour shows in proportion to 1 - transmission
+ * @property {number} [clearcoat] 0-1: a clear glossy layer over the surface - car paint, lacquer, varnish (default 0)
+ * @property {number} [clearcoatRoughness] 0-1: how glossy the coat is, 0 a mirror (default 0)
+ * @property {number} [sheen] 0-1: the soft bright rim of cloth at grazing angles - velvet, felt, upholstery (default 0)
+ * @property {ColorInput} [sheenColor] the sheen's colour (default white)
+ * @property {number} [sheenRoughness] 0-1: a thin bright rim at 0, a broad soft glow at 1 (default 0.5)
+ * @property {number} [ior] index of refraction, 1 or more: how strongly a non-metal reflects - water 1.33, glass and
+ *   plastic 1.5 (the default), diamond 2.4
+ * @property {number} [specularIntensity] 0-1: scales a non-metal's reflections, 0 for none - chalk, clay (default 1)
+ * @property {ColorInput} [specularColor] tints a non-metal's reflections face on (default white)
+ * @property {number} [anisotropy] 0-1: brushed metal - highlights drawn out along the brushing, which runs along
+ *   the UVs' u (around the mesh where it has no UVs) (default 0)
+ * @property {number} [anisotropyRotation] turns the brushing from the UVs' u, in radians (default 0)
+ * @property {number} [translucency] 0-1: light through thin surfaces, lighting them from behind - leaves, paper,
+ *   lampshades, curtains (default 0)
+ * @property {ColorInput} [translucencyColor] tints the light that comes through (default white)
+ * @property {MapInput | null} [matcap] a picture of a lit sphere that gives the whole look - clay, wax, chrome,
+ *   a painted ball - picked by which way the surface faces the camera. Lights, shadows and the environment are
+ *   ignored; the colour and colour map multiply it
+ * @property {number} [toon] cartoon shading in this many flat tones (2 or more) with a hard-edged highlight;
+ *   0 (the default) is smooth
  * @property {boolean} [unlit] flat colour that ignores lights (default false)
  * @property {boolean} [flatShading] faceted look from face normals (default false)
  * @property {boolean} [doubleSided] draw back faces too (default false)
@@ -46,18 +74,26 @@ import { Texture } from './Texture.js'
  * @property {number} [width] Lines: width in pixels (default 1)
  */
 
-const MAPS = ['map', 'roughnessMap', 'metalnessMap', 'normalMap', 'bumpMap', 'aoMap', 'emissiveMap']
+// the matcap last: the first map's repeat and offset are every map's, and a matcap has none
+const MAPS = ['map', 'roughnessMap', 'metalnessMap', 'normalMap', 'bumpMap', 'aoMap', 'emissiveMap', 'lightMap', 'matcap']
 // data maps hold numbers, not colours
 const LINEAR_MAPS = new Set(['roughnessMap', 'metalnessMap', 'normalMap', 'bumpMap', 'aoMap'])
 const FLAGS = ['unlit', 'flatShading', 'doubleSided', 'vertexColors', 'depthWrite', 'depthTest', 'sizeAttenuation', 'transparent', 'fog']
 const NUMBERS = { opacity: [0, 1], roughness: [0, 1], metalness: [0, 1], emissiveIntensity: [0, Infinity], size: [0, Infinity], width: [0, Infinity],
-  alphaTest: [0, 1], normalScale: [-Infinity, Infinity], aoMapIntensity: [0, 1], triplanar: [0, Infinity], bumpScale: [-Infinity, Infinity] }
+  alphaTest: [0, 1], normalScale: [-Infinity, Infinity], aoMapIntensity: [0, 1], triplanar: [0, Infinity], bumpScale: [-Infinity, Infinity],
+  transmission: [0, 1], clearcoat: [0, 1], clearcoatRoughness: [0, 1], sheen: [0, 1], sheenRoughness: [0, 1], ior: [1, Infinity],
+  specularIntensity: [0, 1], anisotropy: [0, 1], anisotropyRotation: [-Infinity, Infinity], translucency: [0, 1], toon: [0, 16],
+  lightMapIntensity: [0, Infinity], environmentIntensity: [0, Infinity] }
+// colours, and their defaults
+const COLORS = { color: 0xffffff, emissive: 0x000000, sheenColor: 0xffffff, specularColor: 0xffffff, translucencyColor: 0xffffff }
 const DEFAULTS = {
-  name: '', opacity: 1, alphaTest: 0, roughness: 0.5, metalness: 0, normalScale: 1, bumpScale: 1, aoMapIntensity: 1, triplanar: 0, emissiveIntensity: 1, unlit: false, flatShading: false,
+  name: '', opacity: 1, alphaTest: 0, roughness: 0.5, metalness: 0, normalScale: 1, bumpScale: 1, aoMapIntensity: 1, triplanar: 0, emissiveIntensity: 1,
+  transmission: 0, clearcoat: 0, clearcoatRoughness: 0, sheen: 0, sheenRoughness: 0.5, ior: 1.5, specularIntensity: 1, anisotropy: 0,
+  anisotropyRotation: 0, translucency: 0, toon: 0, lightMapIntensity: 1, environmentIntensity: 1, unlit: false, flatShading: false,
   doubleSided: false, vertexColors: false, blending: 'normal', depthWrite: true, depthTest: true, fog: true,
   size: 1, sizeAttenuation: true, width: 1,
 }
-const OPTIONS = ['name', 'color', 'emissive', ...MAPS, ...FLAGS, ...Object.keys(NUMBERS), 'blending']
+const OPTIONS = ['name', ...Object.keys(COLORS), ...MAPS, ...FLAGS, ...Object.keys(NUMBERS), 'blending']
 
 // what agents (and three.js habits) will reach for
 const HINTS = {
@@ -65,7 +101,17 @@ const HINTS = {
   side: "use 'doubleSided: true'",
   wireframe: 'use new Lines({ geometry: edges(geometry) }) for a wireframe',
   shininess: "use 'roughness' (0 = mirror, 1 = matte)",
-  specular: "use 'roughness' and 'metalness'",
+  envMapIntensity: "use 'environmentIntensity'",
+  reflectivityScale: "use 'environmentIntensity'",
+  matcapMap: "use 'matcap'",
+  gradientMap: "use 'toon' - the number of flat tones",
+  cel: "use 'toon' - the number of flat tones",
+  celShading: "use 'toon' - the number of flat tones",
+  specular: "use 'specularIntensity' and 'specularColor' for a non-metal's reflections, or 'roughness' and 'metalness'",
+  reflectivity: "use 'ior' (1.5 by default) or 'specularIntensity'",
+  anisotropyStrength: "use 'anisotropy'",
+  diffuseTransmission: "use 'translucency'",
+  subsurface: "use 'translucency' for light through thin surfaces",
   colour: "use 'color'",
   emissiveColor: "use 'emissive'",
   alpha: "use 'opacity'",
@@ -91,6 +137,19 @@ export class Material {
   /** @type {number} */ roughness
   /** @type {number} */ metalness
   /** @type {number} */ emissiveIntensity
+  /** How much light passes through, as through glass: 0-1. @type {number} */ transmission
+  /** A clear glossy layer over the surface: 0-1. @type {number} */ clearcoat
+  /** How glossy the coat is, 0 a mirror. @type {number} */ clearcoatRoughness
+  /** The soft bright rim of cloth: 0-1. @type {number} */ sheen
+  /** A thin bright rim at 0, a broad soft glow at 1. @type {number} */ sheenRoughness
+  /** Index of refraction: how strongly a non-metal reflects (1.5). @type {number} */ ior
+  /** Scales a non-metal's reflections, 0-1. @type {number} */ specularIntensity
+  /** Brushed metal: 0-1. @type {number} */ anisotropy
+  /** Turns the brushing from the UVs' u, in radians. @type {number} */ anisotropyRotation
+  /** Light through thin surfaces: 0-1. @type {number} */ translucency
+  /** Cartoon shading in this many flat tones; 0 is smooth. @type {number} */ toon
+  /** @type {number} */ lightMapIntensity
+  /** This material's share of the environment's light and reflections. @type {number} */ environmentIntensity
   /** @type {boolean} */ unlit
   /** @type {boolean} */ flatShading
   /** @type {boolean} */ doubleSided
@@ -103,8 +162,8 @@ export class Material {
   /** @type {boolean} */ sizeAttenuation
   /** @type {number} */ width
 
-  #color = new Color(0xffffff)
-  #emissive = new Color(0x000000)
+  /** @type {Record<string, Color>} */
+  #colors = Object.fromEntries(Object.entries(COLORS).map(([key, hex]) => [key, new Color(hex)]))
   #transparent = false
   /** @type {Record<string, Texture | null>} */
   #maps = Object.fromEntries(MAPS.map((m) => [m, null]))
@@ -117,8 +176,7 @@ export class Material {
     Object.assign(this, DEFAULTS)
     for (const [key, value] of /** @type {[string, any][]} */ (Object.entries(options))) {
       if (value === undefined) continue
-      if (key === 'color') this.color = value
-      else if (key === 'emissive') this.emissive = value
+      if (key in COLORS) this.#colors[key].set(value, 'Material')
       else if (MAPS.includes(key)) this.setMap(key, value)
       else if (FLAGS.includes(key)) this[key] = bool(key, value)
       else if (key in NUMBERS) this[key] = range(key, value, NUMBERS[key])
@@ -141,14 +199,29 @@ export class Material {
   }
 
   /** Base colour; assign any colour input. @returns {Color} */
-  get color() { return this.#color }
+  get color() { return this.#colors.color }
   /** @param {ColorInput} v */
-  set color(v) { this.#color.set(v, 'Material') }
+  set color(v) { this.#colors.color.set(v, 'Material') }
 
   /** Glow colour; assign any colour input. @returns {Color} */
-  get emissive() { return this.#emissive }
+  get emissive() { return this.#colors.emissive }
   /** @param {ColorInput} v */
-  set emissive(v) { this.#emissive.set(v, 'Material') }
+  set emissive(v) { this.#colors.emissive.set(v, 'Material') }
+
+  /** The sheen's colour; assign any colour input. @returns {Color} */
+  get sheenColor() { return this.#colors.sheenColor }
+  /** @param {ColorInput} v */
+  set sheenColor(v) { this.#colors.sheenColor.set(v, 'Material') }
+
+  /** Tints a non-metal's reflections face on; assign any colour input. @returns {Color} */
+  get specularColor() { return this.#colors.specularColor }
+  /** @param {ColorInput} v */
+  set specularColor(v) { this.#colors.specularColor.set(v, 'Material') }
+
+  /** Tints the light that comes through a translucent surface; assign any colour input. @returns {Color} */
+  get translucencyColor() { return this.#colors.translucencyColor }
+  /** @param {ColorInput} v */
+  set translucencyColor(v) { this.#colors.translucencyColor.set(v, 'Material') }
 
   /** @returns {Texture | null} */
   get map() { return this.#maps.map }
@@ -178,9 +251,17 @@ export class Material {
   get emissiveMap() { return this.#maps.emissiveMap }
   /** @param {MapInput | null} v */
   set emissiveMap(v) { this.setMap('emissiveMap', v) }
+  /** Light baked into a texture. @returns {Texture | null} */
+  get lightMap() { return this.#maps.lightMap }
+  /** @param {MapInput | null} v */
+  set lightMap(v) { this.setMap('lightMap', v) }
+  /** A picture of a lit sphere that gives the whole look. @returns {Texture | null} */
+  get matcap() { return this.#maps.matcap }
+  /** @param {MapInput | null} v */
+  set matcap(v) { this.setMap('matcap', v) }
 
   /** @internal
-   * @param {string} slot one of map, roughnessMap, metalnessMap, normalMap, aoMap, emissiveMap
+   * @param {string} slot one of map, roughnessMap, metalnessMap, normalMap, bumpMap, aoMap, emissiveMap, lightMap, matcap
    * @param {MapInput | null} value
    */
   setMap(slot, value) {
@@ -213,7 +294,7 @@ export class Material {
 
   /** Rendered in the transparent pass: an opacity below 1, additive or multiply blending, or set for maps with soft alpha. @returns {boolean} */
   get transparent() {
-    return this.#transparent || this.opacity < 1 || this.blending !== 'normal'
+    return this.#transparent || this.opacity < 1 || this.transmission > 0 || this.blending !== 'normal'
   }
   /** @param {boolean} v */
   set transparent(v) { this.#transparent = !!v }
@@ -226,6 +307,12 @@ export class Material {
     const parts = [this.unlit ? 'unlit' : 'lit']
     for (const [slot] of this.textures) parts.push(slot)
     if (this.alphaTest > 0) parts.push('cutout')
+    if (this.transmission > 0) parts.push('glass')
+    if (this.clearcoat > 0) parts.push('clearcoat')
+    if (this.sheen > 0) parts.push('sheen')
+    if (this.anisotropy > 0) parts.push('brushed')
+    if (this.translucency > 0) parts.push('translucent')
+    if (this.toon > 0) parts.push('toon')
     if (this.flatShading) parts.push('flat')
     if (this.vertexColors) parts.push('vcolor')
     return parts.join('+')
@@ -240,8 +327,7 @@ export class Material {
   clone() {
     const copy = new Material(this.toJSON(true))
     // the colours exactly: a description rounds them to 8-bit sRGB and can't hold values past 1
-    copy.color.set(this.#color)
-    copy.emissive.set(this.#emissive)
+    for (const [key, c] of Object.entries(this.#colors)) copy.#colors[key].set(c)
     return copy
   }
 
@@ -268,8 +354,7 @@ export class Material {
       if (this[key] !== value) json[key] = this[key]
     }
     if (this.#transparent) json.transparent = true
-    if (this.#color.getHex() !== 0xffffff) json.color = this.#color.getStyle()
-    if (this.#emissive.getHex() !== 0) json.emissive = this.#emissive.getStyle()
+    for (const [key, c] of Object.entries(this.#colors)) if (c.getHex() !== COLORS[key]) json[key] = c.getStyle()
     for (const [slot, t] of this.textures) {
       const desc = keepTextures ? t : t.toJSON()
       if (desc) json[slot] = desc

package/src/material/Texture.js

@@ -10,36 +10,49 @@ import { checkNumber, checkOneOf, checkOptions, describe, fail } from '../valida
  * @typedef {object} TextureOptions
  * @property {TextureImage} [image] the pixels; omit and give a url to load them
  * @property {string} [url] image to load (starts loading immediately in a browser); a .hdr file loads as
- *   linear HDR radiance, for scene.environment
+ *   linear HDR radiance, for scene.environment; a video (.mp4, .webm, .ogv, .mov, .m4v) plays muted and on a
+ *   loop, and texture.image is its <video> to pause, seek or unmute
  * @property {'srgb' | 'linear'} [colorSpace] 'srgb' for colour maps (default), 'linear' for data
  *   maps such as normal and roughness maps
  * @property {'repeat' | 'clamp' | 'mirror'} [wrap] (default 'repeat')
  * @property {number[]} [repeat] [u, v] (default [1, 1])
  * @property {number[]} [offset] [u, v] (default [0, 0])
+ * @property {number} [rotation] turns the image on the surface, in radians, about `center` (default 0)
+ * @property {number[]} [center] [u, v] the point rotation turns about, in repeated UVs (default [0, 0], the
+ *   corner, as glTF has it; [0.5, 0.5] for the middle of an unrepeated image)
+ * @property {0 | 1} [uvSet] which UV set to read: 0 the first, 1 the second (Geometry uvs2) - baked occlusion
+ *   and light maps usually come on the second (default 0)
  * @property {'linear' | 'nearest'} [filter] (default 'linear')
- * @property {boolean} [mipmaps] (default true)
+ * @property {boolean} [mipmaps] (default true; false for a video, which would make them every frame)
  * @property {number} [anisotropy] samples along a surface seen at a glancing angle - floors and roads
  *   stay sharp into the distance. Up to what the GPU allows; 1 is off (default 8)
  * @property {boolean} [flipY] flip on upload; false for glTF-style UVs (default false)
  */
 
-const OPTIONS = ['image', 'url', 'colorSpace', 'wrap', 'repeat', 'offset', 'filter', 'mipmaps', 'anisotropy', 'flipY']
-const DEFAULTS = { colorSpace: 'srgb', wrap: 'repeat', repeat: [1, 1], offset: [0, 0], filter: 'linear', mipmaps: true, anisotropy: 8, flipY: false }
+const OPTIONS = ['image', 'url', 'colorSpace', 'wrap', 'repeat', 'offset', 'rotation', 'center', 'uvSet', 'filter', 'mipmaps', 'anisotropy', 'flipY']
+const DEFAULTS = { colorSpace: 'srgb', wrap: 'repeat', repeat: [1, 1], offset: [0, 0], rotation: 0, center: [0, 0], uvSet: 0, filter: 'linear',
+  mipmaps: true, anisotropy: 8, flipY: false }
 
 const HINTS = {
   src: "use 'url' for the image address",
   encoding: "use colorSpace: 'srgb' | 'linear'",
   wrapS: "use wrap: 'repeat' | 'clamp' | 'mirror' (applies to both directions)",
   maxAnisotropy: "use 'anisotropy' - samples along glancing angles, 1 for off",
+  channel: "use 'uvSet' - 0 for the first UV set, 1 for the second",
+  texCoord: "use 'uvSet' - 0 for the first UV set, 1 for the second",
+  scale: "use 'repeat' - [u, v] times across",
 }
 
-/** An image for a material map. Canvas and video textures: set `needsUpdate()` after drawing. */
+/**
+ * An image for a material map. A video's frames upload by themselves as it plays; after drawing on
+ * a canvas, call `needsUpdate()`.
+ */
 export class Texture {
   /** The options it takes, and hints for names people reach for instead. */
   static OPTIONS = OPTIONS
   static HINTS = HINTS
-  /** @type {TextureImage | null} null until loaded */
-  image = null
+  /** @type {TextureImage | null} */
+  #image = null
   /** @type {string | null} */
   url = null
   /** @type {'srgb' | 'linear'} */
@@ -50,6 +63,12 @@ export class Texture {
   wrap = 'repeat'
   repeat = [1, 1]
   offset = [0, 0]
+  /** Turns the image on the surface, in radians, about `center`. */
+  rotation = 0
+  /** [u, v] the point rotation turns about, in repeated UVs. */
+  center = [0, 0]
+  /** Which UV set it reads: 0 the first, 1 the second (Geometry uvs2). @type {0 | 1} */
+  uvSet = 0
   /** @type {'linear' | 'nearest'} */
   filter = 'linear'
   mipmaps = true
@@ -75,7 +94,12 @@ export class Texture {
     this.filter = checkOneOf('Texture', 'filter', o.filter, ['linear', 'nearest'])
     this.repeat = pair('repeat', o.repeat)
     this.offset = pair('offset', o.offset)
-    this.mipmaps = !!o.mipmaps
+    this.rotation = checkNumber('Texture', 'rotation', o.rotation)
+    this.center = pair('center', o.center)
+    if (o.uvSet !== 0 && o.uvSet !== 1) fail('Texture', `'uvSet' is 0 (the first UV set) or 1 (the second), got ${describe(o.uvSet)}`)
+    this.uvSet = o.uvSet
+    // a video would make mipmaps every frame: off unless asked for
+    this.mipmaps = options.mipmaps !== undefined ? !!options.mipmaps : !(isVideo(o.image) || (!o.image && VIDEO.test(o.url ?? '')))
     this.anisotropy = checkNumber('Texture', 'anisotropy', o.anisotropy)
     if (!(this.anisotropy >= 1)) fail('Texture', `'anisotropy' is how many samples along a glancing angle - 1 (off) or more, got ${this.anisotropy}`)
     this.flipY = !!o.flipY
@@ -83,7 +107,8 @@ export class Texture {
 
     if (o.image) {
       this.image = o.image
-      this.ready = Promise.resolve(this)
+      this.ready = isVideo(o.image) ? loaded(/** @type {HTMLVideoElement} */ (o.image)).then(() => this) : Promise.resolve(this)
+      this.ready.catch(() => {})
     } else if (this.url) {
       this.ready = this.#load(this.url)
       // a failed load is reported by whoever awaits `ready`; don't also raise an unhandled rejection
@@ -94,6 +119,57 @@ export class Texture {
   }
 
   /** Call after redrawing a canvas or advancing a video. @returns {this} */
+  /**
+   * The pixels: null until loaded. A <video>'s frames upload by themselves while it plays.
+   * @returns {TextureImage | null}
+   */
+  get image() { return this.#image }
+  /** @param {TextureImage | null} v */
+  set image(v) {
+    this.#image = v
+    this.needsUpdate()
+    if (isVideo(v)) this.#follow(/** @type {HTMLVideoElement} */ (v))
+  }
+
+  // Each new frame of a playing video marks the texture changed, so views redraw with it: the
+  // browser's own per-frame callback where there is one, otherwise a check every animation frame
+  // while it plays. Following stops when the image is replaced.
+  /** @param {HTMLVideoElement} video */
+  #follow(video) {
+    if (typeof video.requestVideoFrameCallback === 'function') {
+      const frame = () => {
+        if (this.#image !== video) return
+        this.needsUpdate()
+        video.requestVideoFrameCallback(frame)
+      }
+      video.requestVideoFrameCallback(frame)
+      return
+    }
+    let last = -1, running = false
+    const tick = () => {
+      if (this.#image !== video || video.paused || video.ended) {
+        running = false
+        return
+      }
+      if (video.currentTime !== last) {
+        last = video.currentTime
+        this.needsUpdate()
+      }
+      requestAnimationFrame(tick)
+    }
+    const start = () => {
+      if (running || this.#image !== video) return
+      running = true
+      requestAnimationFrame(tick)
+    }
+    video.addEventListener('play', start)
+    // a seek while paused shows a new frame too
+    video.addEventListener('seeked', () => {
+      if (this.#image === video) this.needsUpdate()
+    })
+    if (!video.paused) start()
+  }
+
   /** 'srgb' for colour (decoded to linear by the GPU), 'linear' for data such as normals and roughness. Call needsUpdate() after changing it. @returns {'srgb' | 'linear'} */
   get colorSpace() { return this.#colorSpace }
   set colorSpace(v) {
@@ -139,12 +215,26 @@ export class Texture {
 
   /** @param {string} url @returns {Promise<Texture>} */
   async #load(url) {
+    if (VIDEO.test(url)) {
+      if (typeof document === 'undefined') throw new Error(`Texture: can't load '${url}' - no video support in this environment`)
+      const video = document.createElement('video')
+      // muted, so browsers let it play by itself; inline, so phones don't take it full screen
+      Object.assign(video, { crossOrigin: 'anonymous', muted: true, loop: true, playsInline: true, autoplay: true, src: url })
+      try {
+        await loaded(video)
+      } catch {
+        throw new Error(`Texture: failed to load '${url}'`)
+      }
+      // a browser that won't autoplay leaves it paused on its first frame: video.play() on a click starts it
+      video.play()?.catch(() => {})
+      this.image = video
+      return this
+    }
     if (/\.hdr($|[?#])/i.test(url)) {
       const [{ parseHDR }, response] = await Promise.all([import('../hdr.js'), fetch(url)])
       if (!response.ok) throw new Error(`Texture: failed to load '${url}' (${response.status})`)
       this.image = parseHDR(await response.arrayBuffer())
       this.colorSpace = 'linear'
-      this.needsUpdate()
       return this
     }
     if (typeof Image === 'undefined') {
@@ -159,11 +249,26 @@ export class Texture {
       throw new Error(`Texture: failed to load '${url}'`)
     }
     this.image = img
-    this.needsUpdate()
     return this
   }
 }
 
+const VIDEO = /\.(mp4|webm|ogv|mov|m4v)($|[?#])/i
+
+/** @internal A <video>, whose frames change as it plays. @param {unknown} image @returns {boolean} */
+export function isVideo(image) {
+  return typeof HTMLVideoElement !== 'undefined' && image instanceof HTMLVideoElement
+}
+
+/** Resolves once a video has a frame to show. @param {HTMLVideoElement} video @returns {Promise<void>} */
+function loaded(video) {
+  if (video.readyState >= 2) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    video.addEventListener('loadeddata', () => resolve(), { once: true })
+    video.addEventListener('error', () => reject(new Error('Texture: the video failed to load')), { once: true })
+  })
+}
+
 /**
  * Load an image as a texture; resolves once it has decoded.
  * @param {string} url

package/src/scene/Node.js

@@ -10,7 +10,7 @@ import { Vec3 } from '../value/Vec3.js'
 import { checkOptions, describe, fail } from '../validate.js'
 import { Clip } from '../clip.js'
 
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 /** @import { Hit } from '../Raycaster.js' */
 /** @import { Camera } from './cameras.js' */
 /** @import { ClipOptions } from '../clip.js' */
@@ -44,7 +44,7 @@ import { Clip } from '../clip.js'
  * @property {string} [name]
  * @property {Vec3Input} [position]
  * @property {Vec3Input | Euler} [rotation] Euler angles in radians, XYZ order
- * @property {ArrayLike<number>} [quaternion] [x, y, z, w] - instead of rotation
+ * @property {QuatInput} [quaternion] [x, y, z, w] or { x, y, z, w } - instead of rotation
  * @property {Vec3Input | number} [scale] a number scales uniformly
  * @property {boolean} [visible]
  * @property {boolean} [pickable] include in view.pick() (default true)
@@ -54,7 +54,8 @@ import { Clip } from '../clip.js'
  * @property {UpdateHandler | UpdateHandler[]} [onUpdate]
  * @property {((hit: Hit) => any) | null} [tooltip] tooltip for anything picked in this subtree; nearer nodes win, and
  *   all win over the View's
- * @property {ColorInput | null} [highlight] hover tint for this subtree, over the View's
+ * @property {ColorInput | null | false} [highlight] hover tint for this subtree, over the View's; false for none - a
+ *   floor or wall left plain under a View that tints everything else (null: the View's)
  * @property {boolean} [highlightWhole] hovering any part of this subtree tints all of it, as one thing - a
  *   piece of furniture, a machine - rather than just the part under the pointer (default false)
  * @property {((hit: Hit | null) => void) | null} [onHover] called as the thing under the pointer in this subtree changes
@@ -136,7 +137,7 @@ export class Node {
   onDrag = null
   /** @type {Outline | null} */
   #outline = null
-  /** @type {Color | null} */
+  /** @type {Color | null | false} */
   #highlight = null
   /** Hovering any part of this subtree tints all of it, not just the part under the pointer. */
   highlightWhole = false
@@ -164,7 +165,7 @@ export class Node {
   set rotation(v) { this.#rotation.copy(/** @type {any} */ (v), this.constructor.name) }
   /** Kept in sync with rotation. Assigning copies, normalised. @returns {Quat} */
   get quaternion() { return this.#quaternion }
-  /** @param {ArrayLike<number>} v */
+  /** @param {QuatInput} v */
   set quaternion(v) { this.#quaternion.copy(v, this.constructor.name).normalize() }
 
   /** @param {NodeOptions} [options] */
@@ -191,7 +192,7 @@ export class Node {
       if (typeof fn !== 'function') fail(owner, `'${key}' must be a function, got ${describe(fn)}`)
       this[key] = fn
     }
-    if (options.highlight != null) this.#highlight = Color.fromInput(options.highlight, owner)
+    if (options.highlight != null) this.#setHighlight(options.highlight, owner)
     if (options.highlightWhole !== undefined) {
       if (typeof options.highlightWhole !== 'boolean') fail(owner, `'highlightWhole' must be true or false, got ${describe(options.highlightWhole)}`)
       this.highlightWhole = options.highlightWhole
@@ -201,14 +202,23 @@ export class Node {
     if (options.children) for (const child of options.children) this.add(child)
   }
 
-  /** Hover tint for this subtree, over the View's; set any colour, or null. @returns {Color | null} */
+  /**
+   * Hover tint for this subtree, over the View's: a colour, false for none, or null to use the View's.
+   * @returns {Color | null | false}
+   */
   get highlight() {
     return this.#highlight
   }
 
-  /** @param {ColorInput | null} value */
+  /** @param {ColorInput | null | false} value */
   set highlight(value) {
-    this.#highlight = value == null ? null : Color.fromInput(value, this.constructor.name)
+    this.#setHighlight(value, this.constructor.name)
+  }
+
+  /** @param {ColorInput | null | false | true} value @param {string} owner */
+  #setHighlight(value, owner) {
+    if (value === true) fail(owner, "'highlight' is a colour, false for no tint, or null to use the View's - got true")
+    this.#highlight = value == null ? null : value === false ? false : Color.fromInput(value, owner)
   }
 
   /**
@@ -612,6 +622,7 @@ export class Node {
     if (!this.pickable) json.pickable = false
     if (!this.matrixAutoUpdate) json.matrixAutoUpdate = false
     if (this.highlight) json.highlight = this.highlight.getStyle()
+    else if (this.highlight === false) json.highlight = false
     if (this.highlightWhole) json.highlightWhole = true
     if (this.#clip) json.clip = this.#clip.toJSON()
     if (this.#outline) json.outline = { color: this.#outline.color.getStyle(), width: this.#outline.width }

package/src/scene/Scene.js

@@ -44,6 +44,8 @@ export class Scene extends Node {
   environmentIntensity = 1
   /** 0-1: how blurred a panorama background is drawn - a soft backdrop that doesn't compete. */
   backgroundBlur = 0
+  /** @internal Set by the View drawing it, from its reducedMotion: charts' transitions and flows stand still. */
+  motionReduced = false
   /** @type {Fog | null} */
   #fog = null
 

package/src/scene/cameras.js

@@ -20,7 +20,10 @@ const tmp3 = new Float32Array(9)
 export function aimAt(node, target) {
   if (node.position.equals(target, 1e-9)) return
   const dir = target.clone().sub(node.position).normalize()
-  const up = Math.abs(dir[1]) > 0.9999 ? [0, 0, -1] : UP
+  // world up keeps the picture upright, and turns it smoothly with the view right up to straight up
+  // or down - the orbit stops a thousandth of a radian short. Only within a hair of exactly vertical
+  // (the 'top' preset's view), where up would no longer say which way the screen faces, is north up
+  const up = Math.hypot(dir[0], dir[2]) < 5e-4 ? [0, 0, -1] : UP
   mat4.targetTo(tmp, node.position, target, up)
   const q = quat.normalize(new Float32Array(4), quat.fromMat3(new Float32Array(4), mat3.fromMat4(tmp3, tmp)))
   node.quaternion.copy(q)