phoria2 1.2.0 → 1.3.0

package/src/index.js

@@ -50,6 +50,7 @@ export { PhoriaError } from './validate.js'
 /** @typedef {import('./presets.js').CameraPreset} CameraPreset */
 /** @typedef {import('./tooltip.js').TooltipContent} TooltipContent */
 /** @typedef {import('./Raycaster.js').Hit} Hit */
+/** @typedef {import('./area.js').PickArea} PickArea */
 /** @typedef {import('./scene/drawables.js').LabelPlacement} LabelPlacement */
 /** @typedef {import('./scene/drawables.js').LabelPlace} LabelPlace */
 /** @typedef {import('./scene/drawables.js').InstanceLabels} InstanceLabels */

package/src/material/Material.js

@@ -72,6 +72,9 @@ import { Texture } from './Texture.js'
  * @property {number} [size] Points: diameter in world units, or pixels when sizeAttenuation is off (default 1)
  * @property {boolean} [sizeAttenuation] Points: sized in the world, so smaller with distance (default true)
  * @property {number} [width] Lines: width in pixels (default 1)
+ * @property {number} [dash] Lines: dashed, with dashes this long in the model's units; 0 is solid (default 0)
+ * @property {number} [gap] Lines: the gaps between dashes; 0 is as long as the dashes (default 0)
+ * @property {number} [dashOffset] Lines: moves the dashes along the lines - animate it for flow (default 0)
  */
 
 // the matcap last: the first map's repeat and offset are every map's, and a matcap has none
@@ -83,7 +86,8 @@ const NUMBERS = { opacity: [0, 1], roughness: [0, 1], metalness: [0, 1], emissiv
   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] }
+  lightMapIntensity: [0, Infinity], environmentIntensity: [0, Infinity], dash: [0, Infinity], gap: [0, Infinity],
+  dashOffset: [-Infinity, Infinity] }
 // colours, and their defaults
 const COLORS = { color: 0xffffff, emissive: 0x000000, sheenColor: 0xffffff, specularColor: 0xffffff, translucencyColor: 0xffffff }
 const DEFAULTS = {
@@ -91,7 +95,7 @@ const DEFAULTS = {
   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,
+  size: 1, sizeAttenuation: true, width: 1, dash: 0, gap: 0, dashOffset: 0,
 }
 const OPTIONS = ['name', ...Object.keys(COLORS), ...MAPS, ...FLAGS, ...Object.keys(NUMBERS), 'blending']
 
@@ -161,6 +165,9 @@ export class Material {
   /** @type {number} */ size
   /** @type {boolean} */ sizeAttenuation
   /** @type {number} */ width
+  /** Lines: dash length in the model's units; 0 is solid. @type {number} */ dash
+  /** Lines: gap length; 0 is the dash's. @type {number} */ gap
+  /** Lines: how far the dashes have moved along. @type {number} */ dashOffset
 
   /** @type {Record<string, Color>} */
   #colors = Object.fromEntries(Object.entries(COLORS).map(([key, hex]) => [key, new Color(hex)]))

package/src/material/Texture.js

@@ -43,9 +43,18 @@ const HINTS = {
   scale: "use 'repeat' - [u, v] times across",
 }
 
+/**
+ * Part of an image, in its pixels from the top left, as needsUpdate() takes it.
+ * @typedef {{ x: number, y: number, width: number, height: number }} TextureRegion
+ */
+
+// how many updates a texture remembers the region of, for a renderer catching up on several - a
+// frame of paint can make a hundred or so
+const CHANGES_KEPT = 256
+
 /**
  * An image for a material map. A video's frames upload by themselves as it plays; after drawing on
- * a canvas, call `needsUpdate()`.
+ * a canvas, call `needsUpdate()` - with the rectangle drawn in, to send only that.
  */
 export class Texture {
   /** The options it takes, and hints for names people reach for instead. */
@@ -77,6 +86,8 @@ export class Texture {
   flipY = false
   /** @internal Bumped by needsUpdate() so renderers re-upload. */
   version = 0
+  /** What each recent update changed - its region, or null for all of it. @type {{ version: number, region: TextureRegion | null }[]} */
+  #changes = []
   /** Resolves when the image is available (immediately when one was given). @type {Promise<Texture>} */
   ready
 
@@ -180,11 +191,53 @@ export class Texture {
   /** @internal Whether the app chose the colour space, rather than leaving the default. @returns {boolean} */
   get colorSpaceSet() { return this.#colorSpaceSet }
 
-  needsUpdate() {
+  /**
+   * Upload the image again, after drawing on it (a canvas) or changing its pixels. Give the
+   * rectangle that changed - in the image's pixels, from its top left - and only that is sent: for a
+   * big canvas drawn on a little at a time, far less to send each frame.
+   *
+   *     ctx.fillRect(x, y, 20, 20)
+   *     texture.needsUpdate({ x, y, width: 20, height: 20 })
+   * @param {TextureRegion} [region]
+   * @returns {this}
+   */
+  needsUpdate(region) {
+    /** @type {TextureRegion | null} */
+    let changed = null
+    if (region !== undefined) {
+      const { x, y, width, height } = region ?? /** @type {any} */ ({})
+      if (![x, y, width, height].every((v) => typeof v === 'number' && Number.isFinite(v)) || width < 0 || height < 0) {
+        fail('Texture', `needsUpdate() takes the region changed, { x, y, width, height } in the image's pixels, got ${describe(region)}`)
+      }
+      // whole pixels, covering every one the region touches
+      const x0 = Math.floor(x), y0 = Math.floor(y)
+      changed = { x: x0, y: y0, width: Math.ceil(x + width) - x0, height: Math.ceil(y + height) - y0 }
+    }
     this.version++
+    this.#changes.push({ version: this.version, region: changed })
+    if (this.#changes.length > CHANGES_KEPT) this.#changes.shift()
     return this
   }
 
+  /**
+   * @internal What changed since a version a renderer uploaded: each update's region since, or null
+   * when that's all of it - an update without a region, or one too long ago to know.
+   * @param {number} version
+   * @returns {TextureRegion[] | null}
+   */
+  changedSince(version) {
+    const first = this.#changes[0]
+    if (!first || first.version > version + 1) return null
+    /** @type {TextureRegion[]} */
+    const regions = []
+    for (const { version: v, region } of this.#changes) {
+      if (v <= version) continue
+      if (!region) return null
+      regions.push(region)
+    }
+    return regions.length ? regions : null
+  }
+
   /** Release the GPU copy. @returns {void} */
   dispose() {
     for (const fn of this.#onDispose) fn()

package/src/particles/Emitter.js

@@ -1,7 +1,8 @@
 // A particle system as one Points node: particles are born at the emitter's origin, move under
 // velocity, gravity and drag, fade through a list of colours and die. The simulation runs in the
 // emitter's own update handler, so it follows the scene clock (frame-rate independent) and its
-// arrays go to the GPU as one buffer refill per frame.
+// arrays go to the GPU as one buffer refill per frame. Particles that grow, fade or turn give the
+// geometry per-point sizes, opacities or angles, and are drawn as squares.
 import * as mat4 from '../math/mat4.js'
 import { Geometry } from '../geometry/Geometry.js'
 import { Material } from '../material/Material.js'
@@ -48,17 +49,32 @@ import { checkNumber, describe, fail } from '../validate.js'
  *   frustumCulled?: boolean,
  *   renderOrder?: number,
  *   onParticle?: ((p: Particle) => boolean | void) | null,
- * }} EmitterOptions
+ *   sort?: boolean,
+ * } & LookOptions} EmitterOptions
  * max: most live particles at once (default 1000). rate: particles born per second (default 100).
  * gravity: acceleration, e.g. [0, -9.8, 0] (default none). drag: share of velocity lost per second
  * (default 0). follow: a node whose position becomes the origin each frame - a trail that stays
  * behind it. onParticle: called for every live particle each frame after it moves; return false to
- * remove it (a particle hitting something).
+ * remove it (a particle hitting something). sort: draw furthest first, for soft particles with
+ * blending 'normal' (smoke) that would otherwise layer wrongly.
+ */
+
+/**
+ * How particles look over their lives, beyond colour.
+ * @typedef {object} LookOptions
+ * @property {number | number[]} [size] a multiple of the material's size, or several each particle goes
+ *   through over its life - [0.5, 3] for smoke that billows out (default 1)
+ * @property {number} [sizeSpread] each particle's size varies by up to this share either way, 0-1 (default 0)
+ * @property {number | number[]} [opacity] 0-1, or several each particle goes through - [0, 1, 0] fades in
+ *   and out (default 1)
+ * @property {number | [number, number]} [spin] radians per second: a number turns each particle up to that
+ *   fast either way, [min, max] a range. Spinning particles start at a random angle (default 0)
  */
 
 const SPAWN_OPTIONS = ['origin', 'originSpread', 'velocity', 'velocitySpread', 'lifetime', 'color']
-const OPTIONS = [...Points.OPTIONS, ...SPAWN_OPTIONS,
-  'max', 'rate', 'gravity', 'drag', 'follow', 'onParticle']
+const LOOK_OPTIONS = ['size', 'sizeSpread', 'opacity', 'spin']
+const BEHAVIOUR_OPTIONS = ['rate', 'gravity', 'drag', 'follow', 'onParticle', ...LOOK_OPTIONS]
+const OPTIONS = [...Points.OPTIONS, ...SPAWN_OPTIONS, 'max', ...BEHAVIOUR_OPTIONS]
 const HINTS = {
   count: "use 'max' for the most particles alive at once, 'rate' for how many are born per second",
   lifetimeRnd: "give 'lifetime' a [min, max] range",
@@ -111,6 +127,13 @@ export class Emitter extends Points {
   /** @type {Map<string, number>} */ #paletteIds = new Map()
   /** @type {Uint8Array} */ #palette
   #spawnPalette = 0
+  // the looks: stops over each particle's life, and each one's own size factor and turn rate
+  /** @type {number[]} */ #size = [1]
+  #sizeSpread = 0
+  /** @type {number[]} */ #opacity = [1]
+  /** @type {[number, number]} */ #spin = [0, 0]
+  /** @type {Float32Array | null} */ #sizeFactors = null
+  /** @type {Float32Array | null} */ #spins = null
   /** Last frame's origin, so a moving source leaves an even trail rather than clumps. */
   #lastOrigin = /** @type {Vec3 | null} */ (null)
   #particle = /** @type {Particle} */ ({ position: new Vec3(), velocity: new Vec3(), age: 0, lifetime: 0 })
@@ -144,12 +167,12 @@ export class Emitter extends Points {
   /**
    * Change several settings at once - a preset, say. Vectors are copied into the emitter's own,
    * so anything bound to `emitter.gravity` and friends stays bound. Live particles carry on.
-   * @param {SpawnOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null,
+   * @param {SpawnOptions & LookOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null,
    *   onParticle?: ((p: Particle) => boolean | void) | null }} options
    * @returns {this}
    */
   set(options) {
-    const known = [...SPAWN_OPTIONS, 'rate', 'gravity', 'drag', 'follow', 'onParticle']
+    const known = [...SPAWN_OPTIONS, ...BEHAVIOUR_OPTIONS]
     for (const key of Object.keys(options ?? {})) {
       if (!known.includes(key)) fail('Emitter', `set() doesn't take '${key}' - it takes ${known.join(', ')}`)
     }
@@ -169,6 +192,22 @@ export class Emitter extends Points {
   /** @returns {[number, number, number][]} */
   get color() { return /** @type {[number, number, number][]} */ (this.#palettes[0].map((s) => [...s])) }
 
+  /** Each particle's size over its life, as multiples of the material's. @param {number | number[]} v */
+  set size(v) { this.#setLooks({ size: v }) }
+  /** @returns {number[]} */
+  get size() { return [...this.#size] }
+  /** How much each particle's size varies, 0-1 either way. @param {number} v */
+  set sizeSpread(v) { this.#setLooks({ sizeSpread: v }) }
+  get sizeSpread() { return this.#sizeSpread }
+  /** Each particle's opacity over its life. @param {number | number[]} v */
+  set opacity(v) { this.#setLooks({ opacity: v }) }
+  /** @returns {number[]} */
+  get opacity() { return [...this.#opacity] }
+  /** How fast particles turn, radians per second, as a [min, max] range. @param {number | [number, number]} v */
+  set spin(v) { this.#setLooks({ spin: v }) }
+  /** @returns {[number, number]} */
+  get spin() { return [...this.#spin] }
+
   /**
    * Birth `count` particles at once - explosions, splashes. Options override the emitter's own
    * spawn settings for this burst only.
@@ -211,6 +250,7 @@ export class Emitter extends Points {
     const v = this.#velocities, ages = this.#ages, lives = this.#lifetimes
     const g = this.gravity, keep = Math.exp(-this.drag * dt)
     const hook = this.onParticle, particle = this.#particle
+    const angles = this.geometry.angles, spins = this.#spins
 
     for (let i = 0; i < this.#alive;) {
       const age = ages[i] += dt
@@ -223,6 +263,7 @@ export class Emitter extends Points {
         v[i3 + k] = (v[i3 + k] + g[k] * dt) * keep
         p[i3 + k] += v[i3 + k] * dt
       }
+      if (angles && spins) angles[i] += spins[i] * dt
       this.#paint(i, age / lives[i])
       if (hook) {
         particle.position.set(p[i3], p[i3 + 1], p[i3 + 2])
@@ -256,7 +297,7 @@ export class Emitter extends Points {
     const rest = super.cloneOptions()
     delete rest.geometry
     return { ...rest, ...this.#saveSpawn(), max: this.#max, rate: this.rate, gravity: this.gravity.clone(),
-      drag: this.drag, follow: this.follow, onParticle: this.onParticle, color: this.color }
+      drag: this.drag, follow: this.follow, onParticle: this.onParticle, color: this.color, ...this.#looks() }
   }
 
   /** @internal @returns {Record<string, unknown>} */
@@ -266,7 +307,8 @@ export class Emitter extends Points {
     return { ...rest, max: this.#max, rate: this.rate, gravity: this.gravity.toArray(), drag: this.drag,
       origin: this.origin.toArray(), originSpread: this.originSpread, velocity: this.velocity.toArray(),
       velocitySpread: typeof this.velocitySpread === 'number' ? this.velocitySpread : this.velocitySpread.toArray(),
-      lifetime: [...this.lifetime], color: this.#palettes[0].map((s) => new Color().setSRGB(s[0], s[1], s[2]).toJSON()) }
+      lifetime: [...this.lifetime], color: this.#palettes[0].map((s) => new Color().setSRGB(s[0], s[1], s[2]).toJSON()),
+      ...this.#looks() }
   }
 
   // birth one particle somewhere between a and b, already `head` seconds into its life
@@ -287,6 +329,12 @@ export class Emitter extends Points {
     this.#lifetimes[i] = min + Math.random() * (max - min)
     this.#ages[i] = head
     this.#palette[i] = this.#spawnPalette
+    if (this.#sizeFactors) this.#sizeFactors[i] = 1 + (Math.random() * 2 - 1) * this.#sizeSpread
+    const angles = this.geometry.angles, spins = this.#spins
+    if (angles && spins) {
+      spins[i] = this.#spin[0] + Math.random() * (this.#spin[1] - this.#spin[0])
+      angles[i] = Math.random() * Math.PI * 2 + spins[i] * head
+    }
     this.#paint(i, head / this.#lifetimes[i])
   }
 
@@ -302,10 +350,16 @@ export class Emitter extends Points {
     this.#ages[i] = this.#ages[last]
     this.#lifetimes[i] = this.#lifetimes[last]
     this.#palette[i] = this.#palette[last]
+    for (const a of [this.geometry.sizes, this.geometry.opacities, this.geometry.angles, this.#sizeFactors, this.#spins]) {
+      if (a) a[i] = a[last]
+    }
   }
 
   /** @param {number} i @param {number} t 0-1 through its life */
   #paint(i, t) {
+    const { sizes, opacities } = this.geometry
+    if (sizes) sizes[i] = along(this.#size, t) * (this.#sizeFactors ? this.#sizeFactors[i] : 1)
+    if (opacities) opacities[i] = along(this.#opacity, t)
     const c = /** @type {Float32Array} */ (this.geometry.colors), stops = this.#palettes[this.#palette[i]]
     if (stops.length === 1) {
       c.set(stops[0], i * 3)
@@ -349,8 +403,9 @@ export class Emitter extends Points {
     if (o.color !== undefined) this.#palettes[0] = colorStops(o.color)
   }
 
-  /** @param {{ rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null, onParticle?: ((p: Particle) => boolean | void) | null }} o */
+  /** @param {LookOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null, onParticle?: ((p: Particle) => boolean | void) | null }} o */
   #setBehaviour(o) {
+    this.#setLooks(o)
     const owner = 'Emitter'
     if (o.rate !== undefined) this.rate = Math.max(0, checkNumber(owner, 'rate', o.rate))
     if (o.gravity !== undefined) this.gravity.copy(o.gravity, owner)
@@ -359,6 +414,31 @@ export class Emitter extends Points {
     if (o.onParticle !== undefined) this.onParticle = o.onParticle
   }
 
+  // Sizes, opacities and angles go on the geometry when first wanted (the points are then drawn as
+  // squares) and stay; live particles get the plain values until they are next painted.
+  /** @param {LookOptions} o */
+  #setLooks(o) {
+    const owner = 'Emitter', g = this.geometry, max = this.#max
+    if (o.size !== undefined) this.#size = lookStops('size', o.size, Infinity)
+    if (o.sizeSpread !== undefined) this.#sizeSpread = Math.min(Math.max(checkNumber(owner, 'sizeSpread', o.sizeSpread), 0), 1)
+    if (o.opacity !== undefined) this.#opacity = lookStops('opacity', o.opacity, 1)
+    if (o.spin !== undefined) this.#spin = spinRange(o.spin)
+    const plain = (/** @type {number[]} */ stops) => stops.length === 1 && stops[0] === 1
+    if (!g.sizes && (!plain(this.#size) || this.#sizeSpread)) g.sizes = new Float32Array(max).fill(1)
+    if (!this.#sizeFactors && this.#sizeSpread) this.#sizeFactors = new Float32Array(max).fill(1)
+    if (!g.opacities && !plain(this.#opacity)) g.opacities = new Float32Array(max).fill(1)
+    if (!g.angles && (this.#spin[0] || this.#spin[1])) {
+      g.angles = new Float32Array(max)
+      this.#spins = new Float32Array(max)
+    }
+  }
+
+  /** The looks, as options. @returns {LookOptions} */
+  #looks() {
+    return { size: unstop(this.#size), sizeSpread: this.#sizeSpread, opacity: unstop(this.#opacity),
+      spin: /** @type {[number, number]} */ ([...this.#spin]) }
+  }
+
   /** The spawn settings other than colour, as options. @returns {SpawnOptions} */
   #saveSpawn() {
     return { origin: this.origin.clone(), originSpread: this.originSpread, velocity: this.velocity.clone(),
@@ -397,6 +477,37 @@ function lifetimeRange(v) {
   return [Math.min(range[0], range[1]), Math.max(range[0], range[1])]
 }
 
+/** @param {string} name @param {number | number[]} v @param {number} most @returns {number[]} */
+function lookStops(name, v, most) {
+  const list = Array.isArray(v) ? v : [v]
+  if (!list.length || !list.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) {
+    fail('Emitter', `'${name}' must be a number of 0 or more, or a list of them a particle goes through, got ${describe(v)}`)
+  }
+  return list.map((n) => Math.min(n, most))
+}
+
+/** One stop as a number, several as a list. @param {number[]} stops @returns {number | number[]} */
+function unstop(stops) {
+  return stops.length === 1 ? stops[0] : [...stops]
+}
+
+/** The value t (0-1) of the way through evenly spaced stops. @param {number[]} stops @param {number} t */
+function along(stops, t) {
+  if (stops.length === 1) return stops[0]
+  const x = Math.min(Math.max(t, 0), 1) * (stops.length - 1)
+  const s = Math.min(Math.floor(x), stops.length - 2)
+  return stops[s] + (stops[s + 1] - stops[s]) * (x - s)
+}
+
+/** @param {number | [number, number]} v @returns {[number, number]} */
+function spinRange(v) {
+  const range = typeof v === 'number' ? [-Math.abs(v), Math.abs(v)] : v
+  if (!Array.isArray(range) || range.length !== 2 || !range.every((n) => typeof n === 'number' && Number.isFinite(n))) {
+    fail('Emitter', `'spin' must be radians per second, or a [min, max] range, got ${describe(v)}`)
+  }
+  return [Math.min(range[0], range[1]), Math.max(range[0], range[1])]
+}
+
 /** @param {ColorInput | ColorInput[]} v @returns {number[][]} */
 function colorStops(v) {
   // a single [r, g, b] array is one colour, not three

package/src/scene/drawables.js

@@ -466,20 +466,44 @@ export class InstancedMesh extends Mesh {
 /** Each vertex drawn as a square point sprite: star fields, particles, scatter plots. */
 export class Points extends Drawable {
   static type = 'points'
-  static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'labels'] }
+  static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'labels', 'sort'] }
 
   /** A label per point from its row of data - or a list of them, several per point. @type {ReturnType<typeof instanceLabels>} */
   labels = null
+  /**
+   * Draw the points back to front, furthest first, each frame - for soft points that cover what is
+   * behind them (smoke, with blending 'normal'), which then layer the right way round. Drawn as squares.
+   */
+  sort = false
 
-  /** @param {DrawableOptions & { labels?: InstanceLabels | InstanceLabels[] | null }} options */
+  /** @param {DrawableOptions & { labels?: InstanceLabels | InstanceLabels[] | null, sort?: boolean }} options */
   constructor(options) {
     super(options)
     this.labels = instanceLabels(this.constructor.name, options?.labels)
+    if (options?.sort !== undefined) {
+      if (typeof options.sort !== 'boolean') fail(this.constructor.name, `'sort' is true or false, got ${describe(options.sort)}`)
+      this.sort = options.sort
+    }
+  }
+
+  /**
+   * @internal Drawn as squares, one a point, rather than as GL points: when the geometry gives each
+   * point its own size, opacity or angle, or the points are sorted. Squares can be any size and stay
+   * whole at the edge of the view.
+   */
+  get drawsSprites() {
+    const g = this.geometry
+    return this.sort || !!(g.sizes || g.opacities || g.angles)
   }
 
   /** @internal @returns {Record<string, unknown>} */
   cloneOptions() {
-    return { ...super.cloneOptions(), labels: this.labels }
+    return { ...super.cloneOptions(), labels: this.labels, sort: this.sort }
+  }
+
+  /** @internal @returns {Record<string, unknown>} */
+  jsonOptions() {
+    return { ...super.jsonOptions(), ...(this.sort ? { sort: true } : {}) }
   }
 
   /** @returns {'points'} */
@@ -488,12 +512,52 @@ export class Points extends Drawable {
   }
 }
 
+const ARROWS = ['none', 'start', 'end', 'both']
+
+/**
+ * @typedef {DrawableOptions & { arrows?: 'none' | 'start' | 'end' | 'both', arrowSize?: number }} LinesOptions
+ */
+
 /**
  * Line segments: indices (or consecutive vertices) in pairs. Width is in pixels and works on
- * every platform. edges(geometry) makes a wireframe of any geometry.
+ * every platform. edges(geometry) makes a wireframe of any geometry. Segments each starting where
+ * the one before ended make a chain - a polyline - which dashes run on along and arrowheads finish.
  */
 export class Lines extends Drawable {
   static type = 'lines'
+  static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'arrows', 'arrowSize'] }
+
+  /** Arrowheads at the ends of each chain: at its 'start', its 'end', 'both' or 'none'. @type {'none' | 'start' | 'end' | 'both'} */
+  arrows = 'none'
+  /** Arrowhead length in pixels; 0 sizes them from the material's width. */
+  arrowSize = 0
+
+  /** @param {LinesOptions} options */
+  constructor(options) {
+    super(options)
+    if (options?.arrows !== undefined) this.arrows = /** @type {any} */ (checkOneOf('Lines', 'arrows', options.arrows, ARROWS))
+    if (options?.arrowSize !== undefined) this.arrowSize = Math.max(0, checkNumber('Lines', 'arrowSize', options.arrowSize))
+  }
+
+  /** @internal Which ends get arrowheads, for the shader: 1 the start, 2 the end. */
+  get arrowBits() {
+    return ARROWS.indexOf(this.arrows)
+  }
+
+  /** @internal An arrowhead's length in pixels, before the pixel ratio. @param {number} width */
+  arrowPixels(width) {
+    return this.arrowSize || 6 + width * 3
+  }
+
+  /** @internal @returns {Record<string, unknown>} */
+  cloneOptions() {
+    return { ...super.cloneOptions(), arrows: this.arrows, arrowSize: this.arrowSize }
+  }
+
+  /** @internal @returns {Record<string, unknown>} */
+  jsonOptions() {
+    return { ...super.jsonOptions(), ...(this.arrows !== 'none' ? { arrows: this.arrows } : {}), ...(this.arrowSize ? { arrowSize: this.arrowSize } : {}) }
+  }
 
   /** @returns {'lines'} */
   get drawMode() {

package/src/watch.js

@@ -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)

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)