three-ilda 0.1.0

package/src/core/LaserShowBase.js

@@ -0,0 +1,224 @@
+import { BufferAttribute, BufferGeometry, DynamicDrawUsage, Group, LineSegments, Mesh, Object3D, Vector2 } from 'three'
+import { LaserScanner, SCANNER_DEFAULTS, TRAIL_POINTS } from './LaserScanner.js'
+
+function number(value, min, max, name) {
+  if (!Number.isFinite(value) || value < min || value > max) throw new RangeError(`${name} must be between ${min} and ${max}.`)
+  return value
+}
+function dynamic(size, width = 3) { return new BufferAttribute(new Float32Array(size), width).setUsage(DynamicDrawUsage) }
+function upload(attribute, size) {
+  attribute.clearUpdateRanges()
+  if (size) { attribute.addUpdateRange(0, size); attribute.needsUpdate = true }
+}
+
+/** @typedef {import('../loaders/ILDALoader.js').ILDAAsset} ILDAAsset */
+/** @typedef {'Disabled' | 'Front' | 'Back'} BeamMode */
+/**
+ * @typedef {Object} LaserShowOptions
+ * @property {number} [track] Projector track to play; defaults to the first track of the asset.
+ * @property {number} [capacity] Trail length in samples, 2 to 65536 (default 2048).
+ * @property {number} [width] Projection width in local units at zoom 1 (default 4.8).
+ * @property {number} [height] Projection height in local units at zoom 1 (default 3.2).
+ */
+
+/**
+ * Renderer-independent part of a laser show: scene graph, scanner playback, segment compaction and buffer uploads.
+ * The image lies in local XY at Z=0; Front is +Z, Back is -Z, regardless of the camera.
+ * One instance plays one ILDA projector track. Assets may be shared; playback/GPU buffers are independent.
+ * A subclass supplies the two materials through _createMaterials(); the uniform handles it returns only need a `.value`.
+ */
+export class LaserShowBase extends Group {
+  /**
+   * @param {ILDAAsset | null} [asset] Parsed ILDA file; call setData() later when omitted.
+   * @param {LaserShowOptions} [options]
+   */
+  constructor(asset = null, { track, capacity = TRAIL_POINTS, width = 4.8, height = 3.2 } = {}) {
+    super()
+    if (!Number.isInteger(capacity) || capacity < 2 || capacity > 65536) throw new RangeError('capacity must be an integer from 2 to 65536.')
+    this.type = 'LaserShow'; this.name = 'ILDA laser show'; this.isLaserShow = true
+    this.capacity = capacity; this.playing = true; this.disposed = false
+    /** @type {import('./LaserScanner.js').ScannerParams} */
+    this._params = { ...SCANNER_DEFAULTS }
+    /** @type {BeamMode} */
+    this._beamMode = 'Disabled'
+    this._zoom = 1; this._dirty = true
+    /** @type {ILDAAsset | null} */ this.asset = null
+    /** @type {number | undefined} */ this.track = undefined
+    /** @type {LaserScanner | null} */ this.scanner = null
+    this._projectionSize = new Vector2(width, height)
+    const { line, beam, scale, origin, clock, intensity, beamIntensity } = this._createMaterials()
+    this._scale = scale; this._origin = origin; this._clock = clock; this._intensity = intensity; this._beamIntensity = beamIntensity
+    this.projector = new Object3D(); this.projector.name = 'Projector aperture'; this.projector.position.set(-2.2, -1.4, 3)
+    this.add(this.projector)
+
+    const segments = capacity - 1
+    this._linePosition = dynamic(segments * 6); this._lineColor = dynamic(segments * 6)
+    const lineGeometry = new BufferGeometry()
+    lineGeometry.setAttribute('position', this._linePosition); lineGeometry.setAttribute('color', this._lineColor); lineGeometry.setDrawRange(0, 0)
+    this.projection = new LineSegments(lineGeometry, line)
+    this.projection.name = 'Laser projection'; this.projection.frustumCulled = false
+    this.add(this.projection)
+
+    this._beamPosition = dynamic(segments * 9); this._beamColor = dynamic(segments * 9)
+    const along = new Float32Array(segments * 3)
+    for (let i = 0; i < along.length; i += 3) { along[i + 1] = 1; along[i + 2] = 1 }
+    const beamGeometry = new BufferGeometry()
+    beamGeometry.setAttribute('position', this._beamPosition); beamGeometry.setAttribute('color', this._beamColor)
+    beamGeometry.setAttribute('beamAlong', new BufferAttribute(along, 1)); beamGeometry.setDrawRange(0, 0)
+    this.beams = new Mesh(beamGeometry, beam); this.beams.name = 'Soft projector beams'
+    this.beams.frustumCulled = false; this.beams.visible = false; this.add(this.beams)
+    this.setProjectionSize(width, height)
+    if (asset) this.setData(asset, track)
+  }
+
+  /**
+   * Creates the line and beam materials for one renderer family.
+   * @returns {{ line: import('three').Material, beam: import('three').Material, scale: { value: import('three').Vector3 }, origin: { value: import('three').Vector3 }, clock: { value: number }, intensity: { value: number }, beamIntensity: { value: number } }}
+   */
+  _createMaterials() { throw new Error('LaserShowBase is abstract: use the LaserShow of the three-ilda or three-ilda/webgl entry.') }
+
+  get pointRate() { return this._params.rate }
+  set pointRate(v) { this._params.rate = number(v, 1, 100000, 'pointRate') }
+  get gain() { return this._params.gain }
+  set gain(v) { this._params.gain = number(v, 0.001, 2, 'gain'); this._retune() }
+  get dampening() { return this._params.dampening }
+  set dampening(v) { this._params.dampening = number(v, 0, 1, 'dampening'); this._retune() }
+  get blankingOffset() { return this._params.blankingOffset }
+  set blankingOffset(v) { this._params.blankingOffset = Math.round(number(v, -100, 100, 'blankingOffset')); this._retune() }
+  get lightDecay() { return this._params.lightDecay }
+  set lightDecay(v) { this._params.lightDecay = number(v, 0, 1, 'lightDecay'); this._dirty = true }
+  get zoom() { return this._zoom }
+  set zoom(v) { this._zoom = number(v, 0, 4, 'zoom'); this._updateScale() }
+  get intensity() { return this._intensity.value }
+  set intensity(v) { this._intensity.value = number(v, 0, 100, 'intensity') }
+  get beamIntensity() { return this._beamIntensity.value }
+  set beamIntensity(v) { this._beamIntensity.value = number(v, 0, 2, 'beamIntensity') }
+  get beamMode() { return this._beamMode }
+  /** @param {BeamMode} mode */
+  set beamMode(mode) {
+    if (!['Disabled', 'Front', 'Back'].includes(mode)) throw new RangeError('beamMode must be Disabled, Front or Back.')
+    this._beamMode = mode; this.beams.visible = mode !== 'Disabled'
+    if (mode !== 'Disabled') this.projector.position.z = Math.max(0.1, Math.abs(this.projector.position.z)) * (mode === 'Front' ? 1 : -1)
+    this._dirty = true
+  }
+  get frame() { return this.scanner?.lastFrame ?? 0 }
+  get frameCount() { return this.scanner?.frames.length ?? 0 }
+  get time() { return this.scanner?.time ?? 0 }
+  get trackIds() { return this.asset ? [...this.asset.tracks.keys()] : [] }
+  get projectionSize() { return this._projectionSize.clone() }
+
+  /** @param {number} width @param {number} height @returns {this} */
+  setProjectionSize(width, height) {
+    this._projectionSize.set(number(width, 0.001, 10000, 'width'), number(height, 0.001, 10000, 'height'))
+    this._updateScale(); return this
+  }
+  _updateScale() { this._scale.value.set(this._projectionSize.x * this.zoom / 2, this._projectionSize.y * this.zoom / 2, 0) }
+  _retune() {
+    if (this.scanner && !this.playing) this.scanner.seekFrame(this.frame, this._params)
+    this._dirty = true
+  }
+  /**
+   * Replaces the played file, building a fresh scanner for one projector track.
+   * @param {ILDAAsset} asset
+   * @param {number} [track] Defaults to the first track of the asset.
+   * @returns {this}
+   */
+  setData(asset, track = asset.tracks.keys().next().value) {
+    if (this.disposed) throw new Error('LaserShow has been disposed.')
+    const frames = asset?.tracks?.get(track)
+    if (!frames?.length) throw new Error(`ILDA track ${track} does not exist.`)
+    const scanner = new LaserScanner(frames, this.capacity)
+    this.asset = asset; this.track = track; this.scanner = scanner
+    this.scanner.seekFrame(0, this._params); this._dirty = true; this.update(0)
+    return this
+  }
+  /** @param {number} track @returns {this} */
+  setTrack(track) { return this.setData(this.asset, track) }
+  /** @param {number} frame @returns {this} */
+  seekFrame(frame) {
+    if (!this.scanner) return this
+    number(frame, 0, this.frameCount - 1, 'frame')
+    this.scanner.seekFrame(Math.floor(frame), this._params); this._dirty = true; this.update(0)
+    return this
+  }
+  reset() { if (this.scanner) { this.scanner.reset(); this._dirty = true; this.update(0) } return this }
+
+  /**
+   * Advances playback and uploads the trail. Call once per application frame, including while paused to apply parameter changes.
+   * @param {number} [delta] Seconds since the previous call.
+   * @returns {this}
+   */
+  update(delta = 0) {
+    if (this.disposed || !this.scanner) return this
+    if (!Number.isFinite(delta) || delta < 0) throw new RangeError('delta must be a finite non-negative number.')
+    if (this.playing && delta > 0) { this.scanner.advance(delta, this._params); this._dirty = true }
+    this._origin.value.copy(this.projector.position); this._clock.value = this.time
+    if (!this._dirty) return this
+    const out = this.scanner.snapshot(this.lightDecay)
+    const lp = this._linePosition.array, lc = this._lineColor.array, bp = this._beamPosition.array, bc = this._beamColor.array
+    let lineSize = 0, beamSize = 0
+    for (let i = 1; i < out.count; i++) {
+      if (out.blank[i - 1] || out.blank[i]) continue
+      const a = (i - 1) * 3, b = i * 3
+      if (Math.max(out.color[a], out.color[a + 1], out.color[a + 2], out.color[b], out.color[b + 1], out.color[b + 2]) < 0.001) continue
+      for (let j = 0; j < 3; j++) {
+        lp[lineSize + j] = out.position[a + j]; lp[lineSize + 3 + j] = out.position[b + j]
+        lc[lineSize + j] = out.color[a + j]; lc[lineSize + 3 + j] = out.color[b + j]
+      }
+      lineSize += 6
+      if (!this.beams.visible) continue
+      for (let j = 0; j < 3; j++) {
+        bp[beamSize + j] = 0; bp[beamSize + 3 + j] = out.position[a + j]; bp[beamSize + 6 + j] = out.position[b + j]
+        const color = (out.color[a + j] + out.color[b + j]) * 0.5
+        bc[beamSize + j] = color; bc[beamSize + 3 + j] = color; bc[beamSize + 6 + j] = color
+      }
+      beamSize += 9
+    }
+    this.projection.geometry.setDrawRange(0, lineSize / 3)
+    upload(this._linePosition, lineSize); upload(this._lineColor, lineSize)
+    if (this.beams.visible) {
+      this.beams.geometry.setDrawRange(0, beamSize / 3)
+      upload(this._beamPosition, beamSize); upload(this._beamColor, beamSize)
+    }
+    this._dirty = false; return this
+  }
+
+  /**
+   * Clone shares the immutable asset, but copies scanner history and allocates independent GPU resources.
+   * @param {boolean} [recursive]
+   * @returns {this}
+   */
+  clone(recursive = true) {
+    return new this.constructor(null, { capacity: this.capacity, width: this._projectionSize.x, height: this._projectionSize.y }).copy(this, recursive)
+  }
+  /** @param {LaserShowBase} source @param {boolean} [recursive] @returns {this} */
+  copy(source, recursive = true) {
+    if (this.disposed || source.disposed) throw new Error('Cannot copy a disposed LaserShow.')
+    if (this.capacity !== source.capacity) throw new Error('copy() requires matching trail capacities; use clone() to preserve capacity.')
+    super.copy(source, false)
+    this._params = { ...source._params }; this.playing = source.playing
+    this.setProjectionSize(source._projectionSize.x, source._projectionSize.y)
+    this.zoom = source.zoom; this.intensity = source.intensity; this.beamIntensity = source.beamIntensity; this.beamMode = source.beamMode
+    this.projector.position.copy(source.projector.position)
+    this.projection.visible = source.projection.visible; this.beams.visible = source.beams.visible
+    if (source.asset) {
+      this.setData(source.asset, source.track)
+      for (const key of ['frame', 'index', 'lastFrame', 'time', 'fraction', 'write', 'count', 'samples', 'x', 'y', 'vx', 'vy']) this.scanner[key] = source.scanner[key]
+      for (const key of ['position', 'color', 'blank', 'born']) this.scanner[key].set(source.scanner[key])
+    } else {
+      this.asset = null; this.scanner = null; this.track = undefined
+      this.projection.geometry.setDrawRange(0, 0); this.beams.geometry.setDrawRange(0, 0)
+    }
+    for (const child of [...this.children]) if (![this.projector, this.projection, this.beams].includes(child)) this.remove(child)
+    if (recursive) for (const child of source.children) if (![source.projector, source.projection, source.beams].includes(child)) this.add(child.clone())
+    this._dirty = true; this.update(0); return this
+  }
+
+  /** Releases only this instance's GPU resources; shared ILDA data stays usable. */
+  dispose() {
+    if (this.disposed) return
+    this.projection.geometry.dispose(); this.projection.material.dispose()
+    this.beams.geometry.dispose(); this.beams.material.dispose()
+    this.disposed = true; this.dispatchEvent({ type: 'dispose' })
+  }
+}

package/src/index.js

@@ -0,0 +1,10 @@
+/** @typedef {import('./loaders/ILDALoader.js').ILDAAsset} ILDAAsset */
+/** @typedef {import('./loaders/ILDALoader.js').ILDAFrame} ILDAFrame */
+/** @typedef {import('./core/LaserScanner.js').ScannerParams} ScannerParams */
+/** @typedef {import('./core/LaserShowBase.js').LaserShowOptions} LaserShowOptions */
+/** @typedef {import('./core/LaserShowBase.js').BeamMode} BeamMode */
+/** @typedef {import('./postprocessing/LaserShowPipeline.js').LaserShowPipelineOptions} LaserShowPipelineOptions */
+export { ILDALoader, ILDA_DEFAULT_PALETTE } from './loaders/ILDALoader.js'
+export { LaserScanner, SCANNER_DEFAULTS, TRAIL_POINTS } from './core/LaserScanner.js'
+export { LaserShow } from './objects/LaserShow.js'
+export { LaserShowPipeline } from './postprocessing/LaserShowPipeline.js'

package/src/loaders/ILDALoader.js

@@ -0,0 +1,160 @@
+import { FileLoader, Loader } from 'three'
+
+const MAX_FILE_BYTES = 32 * 1024 * 1024, MAX_POINTS = 2_000_000
+const FORMAT_SIZE = { 0: 8, 1: 6, 2: 3, 4: 10, 5: 8 }
+const HEADER = 32
+
+/**
+ * @typedef {Object} ILDAFrame
+ * @property {number} number Frame number from the file.
+ * @property {string} name Frame name from the file.
+ * @property {number} projector Projector ID from the file (zero-based).
+ * @property {number} count Number of points.
+ * @property {Float32Array} position Interleaved XYZ, normalized by 32768. Z is zero for 2D formats.
+ * @property {Float32Array} color Interleaved RGB in [0, 1], including colors of blanked points.
+ * @property {Uint8Array} blank One flag per point: 1 means laser off.
+ */
+
+/**
+ * @typedef {Object} ILDAAsset
+ * @property {ILDAFrame[]} frames Point frames in file order; palette records are not frames.
+ * @property {Map<number, ILDAFrame[]>} tracks Frames grouped by projector ID, sharing objects with frames.
+ * @property {number} totalPoints Total number of points in all tracks.
+ * @property {number} blanked Number of blanked points.
+ * @property {number} paletteFallbacks Number of unknown palette indices rendered in white.
+ * @property {boolean} eof Whether an explicit end-of-file record was found.
+ * @property {number} bytes Input size in bytes.
+ * @property {number} parseTimeMs CPU parsing time; excludes downloading and local file reading.
+ */
+
+/**
+ * ILDA IDTF loader for formats 0, 1, 2, 4 and 5. No renderer, DOM or player dependency.
+ * Uses the standard Three.js LoadingManager, FileLoader and inherited loadAsync().
+ *
+ * @example
+ * const loader = new ILDALoader(manager);
+ * const show = await loader.loadAsync('/shows/example.ild');
+ * const localShow = loader.parse(await file.arrayBuffer());
+ *
+ * @extends Loader
+ */
+export class ILDALoader extends Loader {
+  /** @param {import('three').LoadingManager} [manager] */
+  constructor(manager) {
+    super(manager)
+    this.fallbackPalette = ILDA_DEFAULT_PALETTE
+  }
+
+  /**
+   * Sets colors for indexed files without a format-2 palette. Embedded palettes always win.
+   * Copies the array; pass null to restore the standard ILDA palette.
+   * @param {ReadonlyArray<ReadonlyArray<number>> | null} palette Between 1 and 256 RGB triplets of integer bytes.
+   * @returns {ILDALoader}
+   */
+  setFallbackPalette(palette) {
+    if (palette === null) { this.fallbackPalette = ILDA_DEFAULT_PALETTE; return this }
+    if (!Array.isArray(palette) || !palette.length || palette.length > 256 || Array.from(palette).some(rgb =>
+      !Array.isArray(rgb) || rgb.length !== 3 || Array.from(rgb).some(v => !Number.isInteger(v) || v < 0 || v > 255))) {
+      throw new TypeError('Expected 1–256 RGB triplets with integer values from 0 to 255.')
+    }
+    this.fallbackPalette = Object.freeze(palette.map(rgb => Object.freeze([...rgb])))
+    return this
+  }
+
+  /**
+   * @param {string} url URL or path, resolved by the loading manager.
+   * @param {(asset: ILDAAsset) => void} onLoad
+   * @param {(event: ProgressEvent) => void} [onProgress]
+   * @param {(error: Error) => void} [onError] Receives download and parsing errors.
+   */
+  load(url, onLoad, onProgress, onError) {
+    const loader = new FileLoader(this.manager)
+    loader.setPath(this.path)
+    loader.setResponseType('arraybuffer')
+    loader.setRequestHeader(this.requestHeader)
+    loader.setWithCredentials(this.withCredentials)
+    loader.load(url, buffer => {
+      try {
+        const asset = this.parse(buffer)
+        if (onLoad) onLoad(asset)
+      } catch (error) {
+        if (onError) onError(error)
+        else console.error(error)
+        this.manager.itemError(url)
+      }
+    }, onProgress, onError)
+  }
+
+  /**
+   * Parses already-loaded bytes synchronously. Does not create geometry or apply scanner settings.
+   * @param {ArrayBuffer} buffer
+   * @returns {ILDAAsset}
+   * @throws {Error} On invalid data, unsupported formats or the 32 MiB / 2M point limits.
+   */
+  parse(buffer) {
+    const start = performance.now()
+    const asset = parseILDA(buffer, this.fallbackPalette)
+    asset.parseTimeMs = performance.now() - start
+    return asset
+  }
+}
+
+// ILDA IDTF revision 011, appendix A. A file's format-2 palette overrides this per projector.
+function defaultPalette() {
+  const p = []
+  for (let i = 0; i < 16; i++) p.push([255, i * 16, 0])
+  p.push([255, 255, 0]); for (let i = 7; i > 0; i--) p.push([i * 32, 255, 0])
+  p.push([0, 255, 0]); for (const v of [36, 73, 109, 146, 182, 219, 255]) p.push([0, 255, v])
+  for (const v of [227, 198, 170, 142, 113, 85, 56, 28, 0]) p.push([0, v, 255])
+  for (const v of [32, 64, 96, 128, 160, 192, 224, 255]) p.push([v, 0, 255])
+  for (const v of [32, 64, 96, 128, 160, 192, 224, 255]) p.push([255, v, 255])
+  for (const v of [224, 192, 160, 128, 96, 64, 32]) p.push([255, v, v])
+  return p
+}
+export const ILDA_DEFAULT_PALETTE = Object.freeze(defaultPalette().map(rgb => Object.freeze(rgb)))
+
+/** One DataView and a cursor: no repeated copies of the remaining file. Returns all projector tracks. */
+function parseILDA(buffer, fallbackPalette) {
+  if (!(buffer instanceof ArrayBuffer)) throw new Error('Expected a binary ILDA file.')
+  if (buffer.byteLength > MAX_FILE_BYTES) throw new Error('ILDALoader supports files up to 32 MiB.')
+  const v = new DataView(buffer), text = new TextDecoder('ascii'), palettes = new Map(), tracks = new Map(), frames = []
+  let offset = 0, totalPoints = 0, blanked = 0, paletteFallbacks = 0, eof = false
+  while (offset < v.byteLength) {
+    if (offset + HEADER > v.byteLength) throw new Error(`Incomplete ILDA header at byte ${offset}.`)
+    if (v.getUint32(offset) !== 0x494c4441) throw new Error(`Invalid ILDA signature at byte ${offset}.`)
+    const format = v.getUint8(offset + 7), count = v.getUint16(offset + 24), projector = v.getUint8(offset + 30)
+    const size = FORMAT_SIZE[format]
+    if (!size) throw new Error(`Unsupported ILDA format ${format}. Supported formats: 0, 1, 2, 4 and 5.`)
+    const number = v.getUint16(offset + 26), name = text.decode(new Uint8Array(buffer, offset + 8, 8)).replace(/\0/g, '').trim()
+    offset += HEADER
+    if (format !== 2 && count === 0) { eof = true; break }
+    if (offset + count * size > v.byteLength) throw new Error('The ILDA file ends in the middle of a frame.')
+    if (format === 2) {
+      if (count > 256 || count === 0) throw new Error('Invalid ILDA palette size.')
+      const palette = []
+      for (let i = 0; i < count; i++, offset += 3) palette.push([v.getUint8(offset), v.getUint8(offset + 1), v.getUint8(offset + 2)])
+      palettes.set(projector, palette); continue
+    }
+    totalPoints += count
+    if (totalPoints > MAX_POINTS) throw new Error('ILDALoader supports up to 2,000,000 points.')
+    const position = new Float32Array(count * 3), color = new Float32Array(count * 3), blank = new Uint8Array(count)
+    const palette = palettes.get(projector) || fallbackPalette, is3D = format === 0 || format === 4, indexed = format === 0 || format === 1
+    for (let i = 0; i < count; i++, offset += size) {
+      const j = i * 3, statusAt = offset + (is3D ? 6 : 4)
+      position[j] = v.getInt16(offset) / 32768; position[j + 1] = v.getInt16(offset + 2) / 32768
+      position[j + 2] = is3D ? v.getInt16(offset + 4) / 32768 : 0
+      blank[i] = (v.getUint8(statusAt) & 0x40) !== 0 ? 1 : 0; blanked += blank[i]
+      if (indexed) {
+        const rgb = palette[v.getUint8(statusAt + 1)]
+        if (!rgb) paletteFallbacks++
+        color[j] = (rgb?.[0] ?? 255) / 255; color[j + 1] = (rgb?.[1] ?? 255) / 255; color[j + 2] = (rgb?.[2] ?? 255) / 255
+      } else { // true-color point records store B, G, R; palette records store R, G, B
+        color[j] = v.getUint8(statusAt + 3) / 255; color[j + 1] = v.getUint8(statusAt + 2) / 255; color[j + 2] = v.getUint8(statusAt + 1) / 255
+      }
+    }
+    const frame = { number, name, projector, count, position, color, blank }
+    frames.push(frame); if (!tracks.has(projector)) tracks.set(projector, []); tracks.get(projector).push(frame)
+  }
+  if (!frames.length) throw new Error('The file contains no point frames.')
+  return { frames, tracks, totalPoints, blanked, paletteFallbacks, eof, bytes: buffer.byteLength }
+}

package/src/objects/LaserShow.js

@@ -0,0 +1,25 @@
+import { AdditiveBlending, DoubleSide, LineBasicNodeMaterial, MeshBasicNodeMaterial, Vector3 } from 'three/webgpu'
+import { attribute, float, mix, mx_noise_float, positionWorld, smoothstep, uniform, varying, vec3 } from 'three/tsl'
+import { LaserShowBase } from '../core/LaserShowBase.js'
+
+/**
+ * Laser show for THREE.WebGPURenderer (the WebGPU / TSL version): node materials with the projection and beam math in TSL.
+ * Playback, buffers and the public API live in LaserShowBase; ../webgl/LaserShow.js is the WebGL 2 version for WebGLRenderer.
+ */
+export class LaserShow extends LaserShowBase {
+  _createMaterials() {
+    const scale = uniform(new Vector3()), origin = uniform(new Vector3()), clock = uniform(0), intensity = uniform(1), beamIntensity = uniform(0.5)
+    const line = new LineBasicNodeMaterial({ transparent: true, depthWrite: false, blending: AdditiveBlending })
+    line.positionNode = attribute('position', 'vec3').mul(scale)
+    line.colorNode = attribute('color', 'vec3').mul(intensity)
+    const beam = new MeshBasicNodeMaterial({ transparent: true, depthWrite: false, blending: AdditiveBlending, side: DoubleSide })
+    beam.forceSinglePass = true
+    beam.positionNode = mix(origin, attribute('position', 'vec3').mul(scale), attribute('beamAlong', 'float'))
+    const along = varying(attribute('beamAlong', 'float'))
+    const drift = positionWorld.mul(1.4).add(vec3(clock.mul(0.08), clock.mul(-0.12), 0))
+    const haze = mx_noise_float(drift).mul(0.3).add(0.7)
+    const envelope = smoothstep(0, 0.025, along).mul(float(1).sub(smoothstep(0.78, 1, along)))
+    beam.colorNode = attribute('color', 'vec3').mul(haze).mul(envelope).mul(beamIntensity)
+    return { line, beam, scale, origin, clock, intensity, beamIntensity }
+  }
+}

package/src/postprocessing/LaserShowPipeline.js

@@ -0,0 +1,119 @@
+import { Color, Layers, PassNode, RenderPipeline } from 'three/webgpu'
+import { float, max, orthographicDepthToViewZ, pass, perspectiveDepthToViewZ, positionView, screenUV, smoothstep, uniform, vec2, vec3, vec4 } from 'three/tsl'
+import { bloom } from 'three/addons/tsl/display/BloomNode.js'
+import { gaussianBlur } from 'three/addons/tsl/display/GaussianBlurNode.js'
+
+// Same scene and camera, with a black background only while rendering the light layer.
+class BeamPass extends PassNode {
+  constructor(scene, camera) { super(PassNode.COLOR, scene, camera, { samples: 0, depthBuffer: false }); this.name = 'Projector beams'; this._clear = new Color() }
+  updateBefore(frame) {
+    const scene = this.scene, renderer = frame.renderer
+    const background = scene.background, backgroundNode = scene.backgroundNode, alpha = renderer.getClearAlpha()
+    renderer.getClearColor(this._clear)
+    try {
+      scene.background = null; scene.backgroundNode = null; renderer.setClearColor(0x000000, 0)
+      super.updateBefore(frame)
+    } finally {
+      scene.background = background; scene.backgroundNode = backgroundNode; renderer.setClearColor(this._clear, alpha)
+    }
+  }
+}
+
+/** @typedef {import('../core/LaserShowBase.js').LaserShowBase} LaserShowBase */
+/**
+ * @typedef {Object} LaserShowPipelineOptions
+ * @property {number} [beamLayer] Layer reserved for beam meshes, 1 to 31 (default 31).
+ * @property {number} [strength] Bloom strength (default 15).
+ * @property {number} [radius] Bloom radius (default 1).
+ * @property {number} [threshold] Bloom luminance threshold (default 0).
+ * @property {number} [samples] MSAA samples of the scene pass (default 4).
+ * @property {boolean} [inspect] Label the passes for the r185 Inspector (default false).
+ */
+
+/**
+ * Optional post-processing owned by the host application. Uses its scene, camera and renderer.
+ * Reserves beamLayer (default 31); all other objects keep their normal camera layers.
+ * One pipeline can serve multiple registered LaserShow objects in the same scene.
+ */
+export class LaserShowPipeline {
+  /**
+   * @param {import('three/webgpu').WebGPURenderer} renderer
+   * @param {import('three').Scene} scene
+   * @param {import('three').Camera} camera
+   * @param {LaserShowPipelineOptions} [options]
+   */
+  constructor(renderer, scene, camera, { beamLayer = 31, strength = 15, radius = 1, threshold = 0, samples = 4, inspect = false } = {}) {
+    if (!Number.isInteger(beamLayer) || beamLayer < 1 || beamLayer > 31) throw new RangeError('beamLayer must be an integer from 1 to 31.')
+    this.renderer = renderer; this.camera = camera; this.beamLayer = beamLayer
+    /** @type {Map<LaserShowBase, { mask: number, opacity: unknown, onDispose: () => void }>} */
+    this.shows = new Map()
+    this.disposed = false; this._withBeams = false
+    const baseLayers = new Layers(); baseLayers.mask = camera.layers.mask; baseLayers.disable(beamLayer)
+    this._baseLayers = baseLayers
+    const beamLayers = new Layers(); beamLayers.set(beamLayer)
+    this.scenePass = pass(scene, camera, { samples }).setLayers(baseLayers)
+    this._near = uniform(camera.near); this._far = uniform(camera.far)
+    const depth = this.scenePass.getTextureNode('depth').sample(screenUV)
+    this._sceneViewZ = (camera.isPerspectiveCamera ? perspectiveDepthToViewZ : orthographicDepthToViewZ)(depth, this._near, this._far)
+    this.beamPass = new BeamPass(scene, camera).setLayers(beamLayers).setResolutionScale(0.5)
+    const label = (node, name) => inspect ? node.toInspector(name) : node
+    const sceneColor = label(this.scenePass.getTextureNode('output'), 'Scene / projection')
+    this.glow = bloom(sceneColor, strength, radius, threshold)
+    this.blur = gaussianBlur(this.beamPass.getTextureNode('output'), vec2(1, 1), 3)
+    const glowColor = label(this.glow, 'Laser bloom'), beamColor = label(this.blur, 'Soft projector beams')
+    this.projectionOutput = sceneColor.add(glowColor)
+    const protect = float(1).sub(smoothstep(0.025, 0.3, max(this.projectionOutput.r, max(this.projectionOutput.g, this.projectionOutput.b))))
+    const haze = vec3(1).sub(beamColor.rgb.negate().exp()).mul(0.14).mul(protect)
+    this.beamOutput = vec4(this.projectionOutput.rgb.add(haze), this.projectionOutput.a)
+    this.pipeline = new RenderPipeline(renderer, this.projectionOutput)
+  }
+
+  /** @param {LaserShowBase} show @returns {this} */
+  add(show) {
+    if (this.shows.has(show)) return this
+    if (!show.isLaserShow || show.disposed) throw new TypeError('Expected a live LaserShow.')
+    if (!show.beams.material.isNodeMaterial) throw new TypeError('Expected a LaserShow from the three-ilda entry; three-ilda/webgl shows need the webgl pipeline.')
+    if (show.beams.userData.laserPipeline) throw new Error('This LaserShow already belongs to another LaserShowPipeline.')
+    const saved = { mask: show.beams.layers.mask, opacity: show.beams.material.opacityNode, onDispose: () => this.remove(show) }
+    this.shows.set(show, saved); show.beams.userData.laserPipeline = this
+    show.beams.layers.set(this.beamLayer)
+    // Beam geometry is drawn separately, but the main scene depth still occludes it.
+    const difference = this._sceneViewZ.sub(positionView.z)
+    show.beams.material.opacityNode = float(1).sub(smoothstep(0.002, 0.015, difference))
+    show.beams.material.needsUpdate = true; show.addEventListener('dispose', saved.onDispose)
+    return this
+  }
+
+  /** @param {LaserShowBase} show @returns {this} */
+  remove(show) {
+    const saved = this.shows.get(show)
+    if (!saved) return this
+    show.beams.layers.mask = saved.mask; show.beams.material.opacityNode = saved.opacity
+    show.beams.material.needsUpdate = true; delete show.beams.userData.laserPipeline
+    show.removeEventListener('dispose', saved.onDispose); this.shows.delete(show)
+    return this
+  }
+
+  render() {
+    if (this.disposed) return
+    this._near.value = this.camera.near; this._far.value = this.camera.far
+    this._baseLayers.mask = this.camera.layers.mask; this._baseLayers.disable(this.beamLayer)
+    let beams = false
+    for (const show of this.shows.keys()) {
+      let visible = show.beams.visible && show.beamIntensity > 0
+      for (let parent = show; parent; parent = parent.parent) visible &&= parent.visible
+      if (visible) { beams = true; break }
+    }
+    if (beams !== this._withBeams) {
+      this._withBeams = beams; this.pipeline.outputNode = beams ? this.beamOutput : this.projectionOutput; this.pipeline.needsUpdate = true
+    }
+    this.pipeline.render()
+  }
+
+  dispose() {
+    if (this.disposed) return
+    for (const show of [...this.shows.keys()]) this.remove(show)
+    this.pipeline.dispose(); this.scenePass.dispose(); this.beamPass.dispose(); this.glow.dispose(); this.blur.dispose()
+    this.disposed = true
+  }
+}

package/src/webgl/LaserShow.js

@@ -0,0 +1,85 @@
+import { AdditiveBlending, DoubleSide, ShaderMaterial, Vector2, Vector3 } from 'three'
+import { LaserShowBase } from '../core/LaserShowBase.js'
+
+const LINE_VERTEX = /* glsl */`
+uniform vec3 scale;
+varying vec3 vColor;
+void main() {
+  vColor = color;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position * scale, 1.0);
+}`
+
+const LINE_FRAGMENT = /* glsl */`
+uniform float intensity;
+varying vec3 vColor;
+void main() { gl_FragColor = vec4(vColor * intensity, 1.0); }`
+
+const BEAM_VERTEX = /* glsl */`
+uniform vec3 scale, origin;
+attribute float beamAlong;
+varying vec3 vColor, vWorld;
+varying float vAlong, vViewZ;
+void main() {
+  vColor = color; vAlong = beamAlong;
+  vec4 world = modelMatrix * vec4(mix(origin, position * scale, beamAlong), 1.0);
+  vec4 view = viewMatrix * world;
+  vWorld = world.xyz; vViewZ = view.z;
+  gl_Position = projectionMatrix * view;
+}`
+
+// DEPTH_FADE is defined by LaserShowPipeline, which also provides the scene depth uniforms.
+const BEAM_FRAGMENT = /* glsl */`
+uniform float clock, beamIntensity;
+varying vec3 vColor, vWorld;
+varying float vAlong, vViewZ;
+#ifdef DEPTH_FADE
+#include <packing>
+uniform sampler2D tDepth;
+uniform vec2 resolution;
+uniform float cameraNear, cameraFar;
+uniform bool orthographic;
+#endif
+// 3D gradient noise, the role mx_noise_float plays in the TSL material; values stay roughly within [-1, 1].
+vec3 hash(vec3 p) {
+  p = vec3(dot(p, vec3(127.1, 311.7, 74.7)), dot(p, vec3(269.5, 183.3, 246.1)), dot(p, vec3(113.5, 271.9, 124.6)));
+  return -1.0 + 2.0 * fract(sin(p) * 43758.5453123);
+}
+float noise(vec3 p) {
+  vec3 i = floor(p), f = fract(p), u = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(mix(dot(hash(i), f), dot(hash(i + vec3(1.0, 0.0, 0.0)), f - vec3(1.0, 0.0, 0.0)), u.x),
+        mix(dot(hash(i + vec3(0.0, 1.0, 0.0)), f - vec3(0.0, 1.0, 0.0)), dot(hash(i + vec3(1.0, 1.0, 0.0)), f - vec3(1.0, 1.0, 0.0)), u.x), u.y),
+    mix(mix(dot(hash(i + vec3(0.0, 0.0, 1.0)), f - vec3(0.0, 0.0, 1.0)), dot(hash(i + vec3(1.0, 0.0, 1.0)), f - vec3(1.0, 0.0, 1.0)), u.x),
+        mix(dot(hash(i + vec3(0.0, 1.0, 1.0)), f - vec3(0.0, 1.0, 1.0)), dot(hash(i + vec3(1.0, 1.0, 1.0)), f - vec3(1.0, 1.0, 1.0)), u.x), u.y), u.z);
+}
+void main() {
+  float envelope = smoothstep(0.0, 0.025, vAlong) * (1.0 - smoothstep(0.78, 1.0, vAlong));
+  float haze = 0.7 + 0.3 * noise(vWorld * 1.4 + vec3(clock * 0.08, clock * -0.12, 0.0));
+  float alpha = 1.0;
+#ifdef DEPTH_FADE
+  float depth = texture2D(tDepth, gl_FragCoord.xy / resolution).x;
+  float sceneViewZ = orthographic ? orthographicDepthToViewZ(depth, cameraNear, cameraFar) : perspectiveDepthToViewZ(depth, cameraNear, cameraFar);
+  alpha = 1.0 - smoothstep(0.002, 0.015, sceneViewZ - vViewZ);
+#endif
+  gl_FragColor = vec4(vColor * haze * envelope * beamIntensity, alpha);
+}`
+
+/**
+ * Laser show for THREE.WebGLRenderer (the WebGL 2 version): ShaderMaterials with the same math as the TSL variant.
+ * Playback, buffers and the public API live in LaserShowBase.
+ */
+export class LaserShow extends LaserShowBase {
+  _createMaterials() {
+    const scale = { value: new Vector3() }, origin = { value: new Vector3() }, clock = { value: 0 }, intensity = { value: 1 }, beamIntensity = { value: 0.5 }
+    const line = new ShaderMaterial({
+      uniforms: { scale, intensity }, vertexShader: LINE_VERTEX, fragmentShader: LINE_FRAGMENT,
+      vertexColors: true, transparent: true, depthWrite: false, blending: AdditiveBlending,
+    })
+    const beam = new ShaderMaterial({
+      uniforms: { scale, origin, clock, beamIntensity, tDepth: { value: null }, resolution: { value: new Vector2(1, 1) }, cameraNear: { value: 0.1 }, cameraFar: { value: 1000 }, orthographic: { value: false } },
+      vertexShader: BEAM_VERTEX, fragmentShader: BEAM_FRAGMENT,
+      vertexColors: true, transparent: true, depthWrite: false, blending: AdditiveBlending, side: DoubleSide, forceSinglePass: true,
+    })
+    return { line, beam, scale, origin, clock, intensity, beamIntensity }
+  }
+}