gloop-sim 0.0.0-stage → 1.0.0

package/dist/render/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../../src/render/frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,MAAM,GAAG,CAAC,CAAC;AAqCjB,MAAM,UAAU;IACe;IAA7B,YAA6B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAErD,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACrC,CAAC;IAED,CAAC,CAAC,QAAgB;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,CAAC,CAAC,QAAgB;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,CAAC,CAAC,QAAgB;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,EAAE,CAAC,QAAgB;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,GAAG,CAAC,QAAgB,EAAE,QAA2C;QAC/D,MAAM,IAAI,GAAG,QAAQ,GAAG,MAAM,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IAEO,IAAI,CAAC,QAAgB,EAAE,IAAY;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;QACpD,MAAM,CACJ,KAAK,KAAK,SAAS,EACnB,YAAY,QAAQ,4CAA4C,IAAI,CAAC,MAAM,CAAC,MAAM,SAAS,CAC5F,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAED,MAAM,KAAW,eAAe,CAc/B;AAdD,WAAiB,eAAe;IAC9B;;OAEG;IACH,SAAgB,EAAE,CAAC,MAAoB;QACrC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAFe,kBAAE,KAEjB,CAAA;IAED;;OAEG;IACH,SAAgB,QAAQ,CAAC,KAAa;QACpC,OAAO,IAAI,YAAY,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;IAC1C,CAAC;IAFe,wBAAQ,WAEvB,CAAA;AACH,CAAC,EAdgB,eAAe,KAAf,eAAe,QAc/B","sourcesContent":["import { assert } from \"@/assert.js\";\n\nconst STRIDE = 3;\n\n/**\n * A view over a position buffer.\n */\nexport interface PackedPositions {\n  /**\n   * The number of particles the buffer holds.\n   */\n  readonly count: number;\n\n  /**\n   * The x coordinate of a particle at the specified index.\n   */\n  x(particle: number): number;\n\n  /**\n   * The y coordinate of a particle at the specified index.\n   */\n  y(particle: number): number;\n\n  /**\n   * The z coordinate of a particle at the specified index.\n   */\n  z(particle: number): number;\n\n  /**\n   * A particle's coordinates as a tuple.\n   */\n  at(particle: number): readonly [number, number, number];\n\n  /**\n   * Updates a particle's coordinates from an `[x, y, z]` tuple.\n   */\n  set(particle: number, position: readonly [number, number, number]): void;\n}\n\nclass PackedView implements PackedPositions {\n  constructor(private readonly buffer: Float32Array) {}\n\n  get count(): number {\n    return this.buffer.length / STRIDE;\n  }\n\n  x(particle: number): number {\n    return this.read(particle, 0);\n  }\n\n  y(particle: number): number {\n    return this.read(particle, 1);\n  }\n\n  z(particle: number): number {\n    return this.read(particle, 2);\n  }\n\n  at(particle: number): readonly [number, number, number] {\n    return [this.x(particle), this.y(particle), this.z(particle)];\n  }\n\n  set(particle: number, position: readonly [number, number, number]): void {\n    const base = particle * STRIDE;\n    this.buffer[base] = position[0];\n    this.buffer[base + 1] = position[1];\n    this.buffer[base + 2] = position[2];\n  }\n\n  private read(particle: number, axis: number): number {\n    const value = this.buffer[particle * STRIDE + axis];\n    assert(\n      value !== undefined,\n      `particle ${particle} is out of range in a position buffer of ${this.buffer.length} floats`,\n    );\n    return value;\n  }\n}\n\nexport namespace PackedPositions {\n  /**\n   * Wraps a packed position buffer so it can be read and written by particle.\n   */\n  export function of(buffer: Float32Array): PackedPositions {\n    return new PackedView(buffer);\n  }\n\n  /**\n   * Allocates a packed position buffer sized to hold `count` particles.\n   */\n  export function allocate(count: number): Float32Array<ArrayBuffer> {\n    return new Float32Array(count * STRIDE);\n  }\n}\n\n/**\n * A snapshot of the simulation state at a given point in time.\n */\nexport interface Frame {\n  /**\n   * The simulated time of this frame, in seconds.\n   */\n  readonly time: number;\n\n  /**\n   * Particle positions as a packed `x, y, z` buffer.\n   */\n  readonly positions: Float32Array;\n\n  /**\n   * Per-particle speed (velocity magnitude).\n   */\n  readonly speeds: Float32Array;\n\n  /**\n   * The number of particles in the swarm.\n   */\n  readonly particleCount: number;\n}\n"]}

package/dist/render/index.d.ts

@@ -0,0 +1,12 @@
+export type { Camera, OrthographicCamera, PerspectiveCamera, Vec3 } from "../render/camera.js";
+export type { Channel } from "../render/channel.js";
+export type { Color, Rgba } from "../render/color.js";
+export type { BloomEffect, BloomOptions, Effect, VignetteEffect, VignetteOptions } from "../render/effect.js";
+export type { Frame } from "../render/frame.js";
+export type { FlatGlyph, Layer, LayerObject, ParticleGlyph, ParticlesLayer, SolidGlyph } from "../render/layer.js";
+export type { ColorInput, ColorRamp, ColorValue, Constant, Ramp, ScalarInput, ScalarRamp, ScalarValue, Stop, ValueSource, } from "../render/ramp.js";
+export type { Sample, Sampler, SamplerOptions } from "../render/sampler.js";
+export type { Signal, SignalOptions } from "../render/signal.js";
+export type { ParticleSource, Source } from "../render/sources.js";
+export type { RenderBackend, Scene, Stage, StageOptions } from "../render/stage.js";
+export { view } from "../render/view.js";

package/dist/render/index.js

@@ -0,0 +1,2 @@
+export { view } from "../render/view.js";
+//# sourceMappingURL=index.js.map

package/dist/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["export type { Camera, OrthographicCamera, PerspectiveCamera, Vec3 } from \"@/render/camera.js\";\nexport type { Channel } from \"@/render/channel.js\";\nexport type { Color, Rgba } from \"@/render/color.js\";\nexport type { BloomEffect, BloomOptions, Effect, VignetteEffect, VignetteOptions } from \"@/render/effect.js\";\nexport type { Frame } from \"@/render/frame.js\";\nexport type { FlatGlyph, Layer, LayerObject, ParticleGlyph, ParticlesLayer, SolidGlyph } from \"@/render/layer.js\";\nexport type {\n  ColorInput,\n  ColorRamp,\n  ColorValue,\n  Constant,\n  Ramp,\n  ScalarInput,\n  ScalarRamp,\n  ScalarValue,\n  Stop,\n  ValueSource,\n} from \"@/render/ramp.js\";\nexport type { Sample, Sampler, SamplerOptions } from \"@/render/sampler.js\";\nexport type { Signal, SignalOptions } from \"@/render/signal.js\";\nexport type { ParticleSource, Source } from \"@/render/sources.js\";\nexport type { RenderBackend, Scene, Stage, StageOptions } from \"@/render/stage.js\";\nexport { view } from \"@/render/view.js\";\n"]}

package/dist/render/layer.d.ts

@@ -0,0 +1,90 @@
+import type { Object3D } from "three/webgpu";
+import type { Frame } from "../render/frame.js";
+import { type ColorInput, type ColorValue, type ScalarInput, type ScalarValue } from "../render/ramp.js";
+import type { ParticleSource, Source } from "../render/sources.js";
+/**
+ * A built layer that is added to the scene and updated per frame.
+ */
+export interface LayerObject {
+    /**
+     * The underlying three.js object that is added to the scene.
+     */
+    readonly object: Object3D;
+    /**
+     * Updates the layer's object with the given frame data.
+     */
+    update(frame: Frame): void;
+    /**
+     * Disposes the layer's resources.
+     */
+    dispose(): void;
+}
+export interface Layer<S extends Source> {
+    /**
+     * The list this layer draws along.
+     */
+    readonly source: S;
+    /**
+     * Creates the three object and per-frame updater this layer needs.
+     */
+    build(): LayerObject;
+}
+/**
+ * A glyph drawn as a flat shape that turns to face the camera.
+ */
+export type FlatGlyph = "cross" | "circle" | "diamond" | "point" | "reticle" | "gyroscope";
+/**
+ * A glyph drawn as a solid shape, shaded by which way its surface faces the
+ * camera.
+ */
+export type SolidGlyph = "sphere" | "octahedron" | "axes" | "gimbal";
+/**
+ * The glyph a particle is drawn as, either flat or solid.
+ */
+export type ParticleGlyph = FlatGlyph | SolidGlyph;
+export interface ParticlesLayer extends Layer<ParticleSource> {
+    /**
+     * The shape of the glyphs used to represent particles.
+     */
+    readonly shape: ParticleGlyph;
+    /**
+     * The color of the particle glyphs.
+     */
+    readonly color: ColorValue;
+    /**
+     * The size of the particle glyphs.
+     */
+    readonly size: ScalarValue;
+    /**
+     * The opacity of the particle glyphs.
+     */
+    readonly opacity: ScalarValue;
+}
+/**
+ * Converts a scalar input to a constant value if possible, otherwise returns undefined.
+ */
+export declare function constant<S extends Source>(input: ScalarInput<S> | undefined): number | undefined;
+/**
+ * Verifies that the specified value is a unit scalar (i.e. `0..1`).
+ */
+export declare function verifyIsUnit(value: number | undefined, name: string): void;
+/**
+ * Verifies that the specified value is a positive scalar (i.e. `> 0`).
+ */
+export declare function verifyIsPositive(value: number | undefined, name: string): void;
+/**
+ * Verifies that the specified value is a non-negative scalar (i.e. `>= 0`).
+ */
+export declare function verifyIsNonNegative(value: number | undefined, name: string): void;
+export declare namespace layer {
+    /**
+     * A particles layer, drawing one glyph per particle.
+     */
+    function particles({ from, shape, color, size, opacity, }: {
+        from: ParticleSource;
+        shape?: ParticleGlyph;
+        color: ColorInput;
+        size?: ScalarInput;
+        opacity?: ScalarInput;
+    }): ParticlesLayer;
+}

package/dist/render/layer.js

@@ -0,0 +1,54 @@
+import { assert } from "../assert.js";
+import { buildParticles } from "../render/backend/particles.js";
+import { colorValue, scalarValue, } from "../render/ramp.js";
+/**
+ * Converts a scalar input to a constant value if possible, otherwise returns undefined.
+ */
+export function constant(input) {
+    return typeof input === "number" ? input : undefined;
+}
+/**
+ * Verifies that the specified value is a unit scalar (i.e. `0..1`).
+ */
+export function verifyIsUnit(value, name) {
+    if (value !== undefined) {
+        assert(value >= 0 && value <= 1, `${name} must be within 0..1, but is ${value}`);
+    }
+}
+/**
+ * Verifies that the specified value is a positive scalar (i.e. `> 0`).
+ */
+export function verifyIsPositive(value, name) {
+    if (value !== undefined) {
+        assert(Number.isFinite(value) && value > 0, `${name} must be positive and finite, but is ${value}`);
+    }
+}
+/**
+ * Verifies that the specified value is a non-negative scalar (i.e. `>= 0`).
+ */
+export function verifyIsNonNegative(value, name) {
+    if (value !== undefined) {
+        assert(Number.isFinite(value) && value >= 0, `${name} must be non-negative and finite, but is ${value}`);
+    }
+}
+export var layer;
+(function (layer) {
+    /**
+     * A particles layer, drawing one glyph per particle.
+     */
+    function particles({ from, shape = "cross", color, size = 2, opacity = 1, }) {
+        verifyIsPositive(constant(size), "particles size");
+        verifyIsUnit(constant(opacity), "particles opacity");
+        const spec = {
+            source: from,
+            shape,
+            color: colorValue(color),
+            size: scalarValue(size),
+            opacity: scalarValue(opacity),
+            build: () => buildParticles(spec),
+        };
+        return spec;
+    }
+    layer.particles = particles;
+})(layer || (layer = {}));
+//# sourceMappingURL=layer.js.map

package/dist/render/layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer.js","sourceRoot":"","sources":["../../src/render/layer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EAGL,UAAU,EAGV,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAyE1B;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAmB,KAAiC;IAC1E,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB,EAAE,IAAY;IAClE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,GAAG,IAAI,gCAAgC,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAyB,EAAE,IAAY;IACtE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,GAAG,IAAI,wCAAwC,KAAK,EAAE,CAAC,CAAC;IACtG,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAyB,EAAE,IAAY;IACzE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,GAAG,IAAI,4CAA4C,KAAK,EAAE,CAAC,CAAC;IAC3G,CAAC;AACH,CAAC;AAED,MAAM,KAAW,KAAK,CA6BrB;AA7BD,WAAiB,KAAK;IACpB;;OAEG;IACH,SAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,KAAK,GAAG,OAAO,EACf,KAAK,EACL,IAAI,GAAG,CAAC,EACR,OAAO,GAAG,CAAC,GAOZ;QACC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACnD,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC,CAAC;QACrD,MAAM,IAAI,GAAmB;YAC3B,MAAM,EAAE,IAAI;YACZ,KAAK;YACL,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC;YACxB,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC;YACvB,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC;YAC7B,KAAK,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC;SAClC,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAxBe,eAAS,YAwBxB,CAAA;AACH,CAAC,EA7BgB,KAAK,KAAL,KAAK,QA6BrB","sourcesContent":["import type { Object3D } from \"three/webgpu\";\nimport { assert } from \"@/assert.js\";\nimport { buildParticles } from \"@/render/backend/particles.js\";\nimport type { Frame } from \"@/render/frame.js\";\nimport {\n  type ColorInput,\n  type ColorValue,\n  colorValue,\n  type ScalarInput,\n  type ScalarValue,\n  scalarValue,\n} from \"@/render/ramp.js\";\nimport type { ParticleSource, Source } from \"@/render/sources.js\";\n\n/**\n * A built layer that is added to the scene and updated per frame.\n */\nexport interface LayerObject {\n  /**\n   * The underlying three.js object that is added to the scene.\n   */\n  readonly object: Object3D;\n\n  /**\n   * Updates the layer's object with the given frame data.\n   */\n  update(frame: Frame): void;\n\n  /**\n   * Disposes the layer's resources.\n   */\n  dispose(): void;\n}\n\nexport interface Layer<S extends Source> {\n  /**\n   * The list this layer draws along.\n   */\n  readonly source: S;\n\n  /**\n   * Creates the three object and per-frame updater this layer needs.\n   */\n  build(): LayerObject;\n}\n\n/**\n * A glyph drawn as a flat shape that turns to face the camera.\n */\nexport type FlatGlyph = \"cross\" | \"circle\" | \"diamond\" | \"point\" | \"reticle\" | \"gyroscope\";\n\n/**\n * A glyph drawn as a solid shape, shaded by which way its surface faces the\n * camera.\n */\nexport type SolidGlyph = \"sphere\" | \"octahedron\" | \"axes\" | \"gimbal\";\n\n/**\n * The glyph a particle is drawn as, either flat or solid.\n */\nexport type ParticleGlyph = FlatGlyph | SolidGlyph;\n\nexport interface ParticlesLayer extends Layer<ParticleSource> {\n  /**\n   * The shape of the glyphs used to represent particles.\n   */\n  readonly shape: ParticleGlyph;\n\n  /**\n   * The color of the particle glyphs.\n   */\n  readonly color: ColorValue;\n\n  /**\n   * The size of the particle glyphs.\n   */\n  readonly size: ScalarValue;\n\n  /**\n   * The opacity of the particle glyphs.\n   */\n  readonly opacity: ScalarValue;\n}\n\n/**\n * Converts a scalar input to a constant value if possible, otherwise returns undefined.\n */\nexport function constant<S extends Source>(input: ScalarInput<S> | undefined): number | undefined {\n  return typeof input === \"number\" ? input : undefined;\n}\n\n/**\n * Verifies that the specified value is a unit scalar (i.e. `0..1`).\n */\nexport function verifyIsUnit(value: number | undefined, name: string): void {\n  if (value !== undefined) {\n    assert(value >= 0 && value <= 1, `${name} must be within 0..1, but is ${value}`);\n  }\n}\n\n/**\n * Verifies that the specified value is a positive scalar (i.e. `> 0`).\n */\nexport function verifyIsPositive(value: number | undefined, name: string): void {\n  if (value !== undefined) {\n    assert(Number.isFinite(value) && value > 0, `${name} must be positive and finite, but is ${value}`);\n  }\n}\n\n/**\n * Verifies that the specified value is a non-negative scalar (i.e. `>= 0`).\n */\nexport function verifyIsNonNegative(value: number | undefined, name: string): void {\n  if (value !== undefined) {\n    assert(Number.isFinite(value) && value >= 0, `${name} must be non-negative and finite, but is ${value}`);\n  }\n}\n\nexport namespace layer {\n  /**\n   * A particles layer, drawing one glyph per particle.\n   */\n  export function particles({\n    from,\n    shape = \"cross\",\n    color,\n    size = 2,\n    opacity = 1,\n  }: {\n    from: ParticleSource;\n    shape?: ParticleGlyph;\n    color: ColorInput;\n    size?: ScalarInput;\n    opacity?: ScalarInput;\n  }): ParticlesLayer {\n    verifyIsPositive(constant(size), \"particles size\");\n    verifyIsUnit(constant(opacity), \"particles opacity\");\n    const spec: ParticlesLayer = {\n      source: from,\n      shape,\n      color: colorValue(color),\n      size: scalarValue(size),\n      opacity: scalarValue(opacity),\n      build: () => buildParticles(spec),\n    };\n    return spec;\n  }\n}\n"]}

package/dist/render/ramp.d.ts

@@ -0,0 +1,93 @@
+import { type Color, type Rgba } from "../render/color.js";
+import { type Signal } from "../render/signal.js";
+import type { Source } from "../render/sources.js";
+/**
+ * A single control point for the mapping of a ramp.
+ */
+export interface Stop<T> {
+    /**
+     * Where on the signal's `0..1` axis this control point sits.
+     */
+    readonly at: number;
+    /**
+     * What the signal's value should be mapped to at this position.
+     */
+    readonly value: T;
+}
+/**
+ * A mapping of a signal's `0..1` parameter to some kind of output value `T`.
+ */
+export interface Ramp<T, S extends Source> {
+    /**
+     * The signal supplying normalized values.
+     */
+    readonly by: Signal<S>;
+    /**
+     * The control points, in ascending position order, with at least two stops.
+     */
+    readonly stops: readonly Stop<T>[];
+}
+export interface ValueSource<Out, S extends Source> {
+    /**
+     * Prepares the rendering data source for sampling, returning a function
+     * providing the value of some property for an element at a given index.
+     */
+    prepare(source: S): (index: number) => Out;
+}
+/**
+ * A fixed value that is the same for every element.
+ */
+export type Constant<T, Out = T> = ValueSource<Out, Source> & {
+    readonly value: T;
+};
+/**
+ * A ramp providing scalar values for each element.
+ */
+export type ScalarRamp<S extends Source> = Ramp<number, S> & ValueSource<number, S>;
+/**
+ * A ramp providing a color value for each element.
+ */
+export type ColorRamp<S extends Source> = Ramp<Color, S> & ValueSource<Rgba, S>;
+/**
+ * A value source providing a scalar value for each element.
+ */
+export type ScalarValue<S extends Source = Source> = Constant<number> | ScalarRamp<S>;
+/**
+ * A value source providing a color value for each element.
+ */
+export type ColorValue<S extends Source = Source> = Constant<Color, Rgba> | ColorRamp<S>;
+/**
+ * What a caller may write for a scalar layer property.
+ */
+export type ScalarInput<S extends Source = Source> = number | ScalarRamp<S>;
+/**
+ * What a caller may write for a color layer property.
+ */
+export type ColorInput<S extends Source = Source> = Color | ColorRamp<S>;
+/**
+ * A namespace for predefined ramps.
+ */
+export declare namespace ramp {
+    /**
+     * A ramp that interpolates a color across `stops` as the signal `by` moves through `0..1`.
+     * Signal values outside of the specified stop range are clamped to the nearest endpoint.
+     */
+    function color<S extends Source>({ by, stops }: Ramp<Color, S>): ColorRamp<S>;
+    /**
+     * A ramp that interpolates a number across `stops` as the signal `by` moves through `0..1`.
+     * Signal values outside of the specified stop range are clamped to the nearest endpoint.
+     */
+    function scalar<S extends Source>({ by, stops }: Ramp<number, S>): ScalarRamp<S>;
+    /**
+     * Whether a layer property is a ramp.
+     */
+    function is<S extends Source>(value: ScalarValue<S> | ColorValue<S>): value is ScalarRamp<S> | ColorRamp<S>;
+}
+/**
+ * Wraps a scalar property, such that it has the same interface as a ramp.
+ */
+export declare function scalarValue<S extends Source>(input: ScalarInput<S>): ScalarValue<S>;
+/**
+ * Wraps a color property, such that it has the same interface as a ramp.
+ */
+export declare function colorValue<S extends Source>(input: ColorInput<S>): ColorValue<S>;

package/dist/render/ramp.js

@@ -0,0 +1,120 @@
+import { assert } from "../assert.js";
+import { color as srgb } from "../render/color.js";
+import { normalizeSignal } from "../render/signal.js";
+function validateStops(stops) {
+    assert(stops.length >= 2, `a ramp needs at least two stops, but has ${stops.length}`);
+    let previous = Number.NEGATIVE_INFINITY;
+    for (const [index, { at }] of stops.entries()) {
+        assert(Number.isFinite(at), `ramp stop ${index} position must be finite, but is ${at}`);
+        assert(at > previous, `ramp stop ${index} position ${at} must be greater than the previous stop`);
+        previous = at;
+    }
+}
+function bracket(stops, t) {
+    const first = stops[0];
+    const last = stops[stops.length - 1];
+    assert(first !== undefined && last !== undefined, "a ramp must have stops to be sampled");
+    if (t <= first.at) {
+        return { from: first, to: first, local: 0 };
+    }
+    if (t >= last.at) {
+        return { from: last, to: last, local: 0 };
+    }
+    for (let index = 1; index < stops.length; index++) {
+        const to = stops[index];
+        const from = stops[index - 1];
+        assert(from !== undefined && to !== undefined, `ramp stop ${index} is missing`);
+        if (t <= to.at) {
+            return { from, to, local: (t - from.at) / (to.at - from.at) };
+        }
+    }
+    assert(false, `no ramp segment contains parameter ${t}`);
+}
+function prepareParameter(by, source) {
+    const values = by.channel.values(source);
+    return (index) => {
+        const raw = values[index];
+        assert(raw !== undefined, `${by.channel.name} channel has no sample at index ${index}`);
+        return normalizeSignal(by, raw);
+    };
+}
+/**
+ * A namespace for predefined ramps.
+ */
+export var ramp;
+(function (ramp) {
+    /**
+     * A ramp that interpolates a color across `stops` as the signal `by` moves through `0..1`.
+     * Signal values outside of the specified stop range are clamped to the nearest endpoint.
+     */
+    function color({ by, stops }) {
+        validateStops(stops);
+        const parsed = stops.map(({ at, value }) => ({ at, value: srgb.parse(value) }));
+        function sample(t) {
+            const { from, to, local } = bracket(parsed, t);
+            return srgb.mix({ from: from.value, to: to.value, t: local });
+        }
+        return {
+            by,
+            stops,
+            prepare(source) {
+                const parameter = prepareParameter(by, source);
+                return (index) => sample(parameter(index));
+            },
+        };
+    }
+    ramp.color = color;
+    /**
+     * A ramp that interpolates a number across `stops` as the signal `by` moves through `0..1`.
+     * Signal values outside of the specified stop range are clamped to the nearest endpoint.
+     */
+    function scalar({ by, stops }) {
+        validateStops(stops);
+        function sample(t) {
+            const { from, to, local } = bracket(stops, t);
+            return from.value + (to.value - from.value) * local;
+        }
+        return {
+            by,
+            stops,
+            prepare(source) {
+                const parameter = prepareParameter(by, source);
+                return (index) => sample(parameter(index));
+            },
+        };
+    }
+    ramp.scalar = scalar;
+    /**
+     * Whether a layer property is a ramp.
+     */
+    function is(value) {
+        return "stops" in value;
+    }
+    ramp.is = is;
+})(ramp || (ramp = {}));
+/**
+ * Wraps a scalar property, such that it has the same interface as a ramp.
+ */
+export function scalarValue(input) {
+    if (typeof input !== "number") {
+        return input;
+    }
+    return {
+        value: input,
+        prepare: () => () => input,
+    };
+}
+/**
+ * Wraps a color property, such that it has the same interface as a ramp.
+ */
+export function colorValue(input) {
+    if (typeof input !== "string") {
+        return input;
+    }
+    const parsed = srgb.parse(input);
+    return {
+        value: input,
+        prepare: () => () => parsed,
+    };
+}
+//# sourceMappingURL=ramp.js.map

package/dist/render/ramp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ramp.js","sourceRoot":"","sources":["../../src/render/ramp.ts"],"names":[],"mappings":"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","sourcesContent":["import { assert } from \"@/assert.js\";\nimport { type Color, type Rgba, color as srgb } from \"@/render/color.js\";\nimport { normalizeSignal, type Signal } from \"@/render/signal.js\";\nimport type { Source } from \"@/render/sources.js\";\n\n/**\n * A single control point for the mapping of a ramp.\n */\nexport interface Stop<T> {\n  /**\n   * Where on the signal's `0..1` axis this control point sits.\n   */\n  readonly at: number;\n\n  /**\n   * What the signal's value should be mapped to at this position.\n   */\n  readonly value: T;\n}\n\n/**\n * A mapping of a signal's `0..1` parameter to some kind of output value `T`.\n */\nexport interface Ramp<T, S extends Source> {\n  /**\n   * The signal supplying normalized values.\n   */\n  readonly by: Signal<S>;\n\n  /**\n   * The control points, in ascending position order, with at least two stops.\n   */\n  readonly stops: readonly Stop<T>[];\n}\n\nexport interface ValueSource<Out, S extends Source> {\n  /**\n   * Prepares the rendering data source for sampling, returning a function\n   * providing the value of some property for an element at a given index.\n   */\n  prepare(source: S): (index: number) => Out;\n}\n\n/**\n * A fixed value that is the same for every element.\n */\nexport type Constant<T, Out = T> = ValueSource<Out, Source> & {\n  readonly value: T;\n};\n\n/**\n * A ramp providing scalar values for each element.\n */\nexport type ScalarRamp<S extends Source> = Ramp<number, S> & ValueSource<number, S>;\n\n/**\n * A ramp providing a color value for each element.\n */\nexport type ColorRamp<S extends Source> = Ramp<Color, S> & ValueSource<Rgba, S>;\n\n/**\n * A value source providing a scalar value for each element.\n */\nexport type ScalarValue<S extends Source = Source> = Constant<number> | ScalarRamp<S>;\n\n/**\n * A value source providing a color value for each element.\n */\nexport type ColorValue<S extends Source = Source> = Constant<Color, Rgba> | ColorRamp<S>;\n\n/**\n * What a caller may write for a scalar layer property.\n */\nexport type ScalarInput<S extends Source = Source> = number | ScalarRamp<S>;\n\n/**\n * What a caller may write for a color layer property.\n */\nexport type ColorInput<S extends Source = Source> = Color | ColorRamp<S>;\n\nfunction validateStops<T>(stops: readonly Stop<T>[]): void {\n  assert(stops.length >= 2, `a ramp needs at least two stops, but has ${stops.length}`);\n\n  let previous = Number.NEGATIVE_INFINITY;\n  for (const [index, { at }] of stops.entries()) {\n    assert(Number.isFinite(at), `ramp stop ${index} position must be finite, but is ${at}`);\n    assert(at > previous, `ramp stop ${index} position ${at} must be greater than the previous stop`);\n    previous = at;\n  }\n}\n\nfunction bracket<T>(stops: readonly Stop<T>[], t: number): { from: Stop<T>; to: Stop<T>; local: number } {\n  const first = stops[0];\n  const last = stops[stops.length - 1];\n  assert(first !== undefined && last !== undefined, \"a ramp must have stops to be sampled\");\n\n  if (t <= first.at) {\n    return { from: first, to: first, local: 0 };\n  }\n  if (t >= last.at) {\n    return { from: last, to: last, local: 0 };\n  }\n\n  for (let index = 1; index < stops.length; index++) {\n    const to = stops[index];\n    const from = stops[index - 1];\n    assert(from !== undefined && to !== undefined, `ramp stop ${index} is missing`);\n    if (t <= to.at) {\n      return { from, to, local: (t - from.at) / (to.at - from.at) };\n    }\n  }\n\n  assert(false, `no ramp segment contains parameter ${t}`);\n}\n\nfunction prepareParameter<S extends Source>(by: Signal<S>, source: S): (index: number) => number {\n  const values = by.channel.values(source);\n  return (index) => {\n    const raw = values[index];\n    assert(raw !== undefined, `${by.channel.name} channel has no sample at index ${index}`);\n    return normalizeSignal(by, raw);\n  };\n}\n\n/**\n * A namespace for predefined ramps.\n */\nexport namespace ramp {\n  /**\n   * A ramp that interpolates a color across `stops` as the signal `by` moves through `0..1`.\n   * Signal values outside of the specified stop range are clamped to the nearest endpoint.\n   */\n  export function color<S extends Source>({ by, stops }: Ramp<Color, S>): ColorRamp<S> {\n    validateStops(stops);\n    const parsed = stops.map(({ at, value }) => ({ at, value: srgb.parse(value) }));\n\n    function sample(t: number): Rgba {\n      const { from, to, local } = bracket(parsed, t);\n      return srgb.mix({ from: from.value, to: to.value, t: local });\n    }\n\n    return {\n      by,\n      stops,\n      prepare(source) {\n        const parameter = prepareParameter(by, source);\n        return (index) => sample(parameter(index));\n      },\n    };\n  }\n\n  /**\n   * A ramp that interpolates a number across `stops` as the signal `by` moves through `0..1`.\n   * Signal values outside of the specified stop range are clamped to the nearest endpoint.\n   */\n  export function scalar<S extends Source>({ by, stops }: Ramp<number, S>): ScalarRamp<S> {\n    validateStops(stops);\n\n    function sample(t: number): number {\n      const { from, to, local } = bracket(stops, t);\n      return from.value + (to.value - from.value) * local;\n    }\n\n    return {\n      by,\n      stops,\n      prepare(source) {\n        const parameter = prepareParameter(by, source);\n        return (index) => sample(parameter(index));\n      },\n    };\n  }\n\n  /**\n   * Whether a layer property is a ramp.\n   */\n  export function is<S extends Source>(value: ScalarValue<S> | ColorValue<S>): value is ScalarRamp<S> | ColorRamp<S> {\n    return \"stops\" in value;\n  }\n}\n\n/**\n * Wraps a scalar property, such that it has the same interface as a ramp.\n */\nexport function scalarValue<S extends Source>(input: ScalarInput<S>): ScalarValue<S> {\n  if (typeof input !== \"number\") {\n    return input;\n  }\n  return {\n    value: input,\n    prepare: () => () => input,\n  };\n}\n\n/**\n * Wraps a color property, such that it has the same interface as a ramp.\n */\nexport function colorValue<S extends Source>(input: ColorInput<S>): ColorValue<S> {\n  if (typeof input !== \"string\") {\n    return input;\n  }\n  const parsed = srgb.parse(input);\n  return {\n    value: input,\n    prepare: () => () => parsed,\n  };\n}\n"]}

package/dist/render/sampler.d.ts

@@ -0,0 +1,34 @@
+import { type Frame } from "../render/frame.js";
+import type { Swarm, SwarmState } from "../types.js";
+export interface SamplerOptions {
+    /**
+     * The swarm to sample state from.
+     */
+    readonly swarm: Swarm;
+}
+/**
+ * The result of reading the swarm's state for a single frame.
+ */
+export interface Sample extends Frame {
+    /**
+     * The snapshot the buffers were filled from.
+     */
+    readonly state: SwarmState;
+}
+/**
+ * Generates {@link Sample}s by reading a swarm's observable state.
+ */
+export declare class Sampler {
+    private readonly swarm;
+    private positionBuffer;
+    private speedBuffer;
+    private inFlight;
+    private latest;
+    constructor({ swarm }: SamplerOptions);
+    /**
+     * Reads the swarm's state for a single frame and returns a {@link Sample}. On
+     * subsequent calls, returns the most recent sample immediately.
+     */
+    sample(): Promise<Sample>;
+    private readState;
+}

package/dist/render/sampler.js

@@ -0,0 +1,53 @@
+import { assert } from "../assert.js";
+import { PackedPositions } from "../render/frame.js";
+/**
+ * Generates {@link Sample}s by reading a swarm's observable state.
+ */
+export class Sampler {
+    swarm;
+    positionBuffer = new Float32Array(0);
+    speedBuffer = new Float32Array(0);
+    inFlight = null;
+    latest = null;
+    constructor({ swarm }) {
+        this.swarm = swarm;
+    }
+    /**
+     * Reads the swarm's state for a single frame and returns a {@link Sample}. On
+     * subsequent calls, returns the most recent sample immediately.
+     */
+    sample() {
+        this.inFlight ??= this.readState().finally(() => {
+            this.inFlight = null;
+        });
+        const latest = this.latest;
+        return latest === null ? this.inFlight : Promise.resolve(latest);
+    }
+    async readState() {
+        const state = await this.swarm.snapshot();
+        const { positions, velocities } = state.particles;
+        const particleCount = positions.length;
+        assert(velocities.length === particleCount, `snapshot has ${particleCount} positions, but ${velocities.length} velocities`);
+        if (this.speedBuffer.length !== particleCount) {
+            this.positionBuffer = PackedPositions.allocate(particleCount);
+            this.speedBuffer = new Float32Array(particleCount);
+        }
+        const points = PackedPositions.of(this.positionBuffer);
+        for (let particle = 0; particle < particleCount; particle++) {
+            const position = positions[particle];
+            const velocity = velocities[particle];
+            assert(position !== undefined && velocity !== undefined, `particle ${particle} is missing from the snapshot`);
+            points.set(particle, position);
+            this.speedBuffer[particle] = Math.hypot(velocity[0], velocity[1], velocity[2]);
+        }
+        this.latest = {
+            time: state.time,
+            positions: this.positionBuffer,
+            speeds: this.speedBuffer,
+            particleCount,
+            state,
+        };
+        return this.latest;
+    }
+}
+//# sourceMappingURL=sampler.js.map

package/dist/render/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","sourceRoot":"","sources":["../../src/render/sampler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAc,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAoBhE;;GAEG;AACH,MAAM,OAAO,OAAO;IACD,KAAK,CAAQ;IAEtB,cAAc,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IACrC,WAAW,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IAElC,QAAQ,GAA2B,IAAI,CAAC;IACxC,MAAM,GAAkB,IAAI,CAAC;IAErC,YAAY,EAAE,KAAK,EAAkB;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,MAAM;QACJ,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC9C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1C,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;QAElD,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC;QACvC,MAAM,CACJ,UAAU,CAAC,MAAM,KAAK,aAAa,EACnC,gBAAgB,aAAa,mBAAmB,UAAU,CAAC,MAAM,aAAa,CAC/E,CAAC;QAEF,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;YAC9C,IAAI,CAAC,cAAc,GAAG,eAAe,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;YAC9D,IAAI,CAAC,WAAW,GAAG,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;QACrD,CAAC;QAED,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAEvD,KAAK,IAAI,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,aAAa,EAAE,QAAQ,EAAE,EAAE,CAAC;YAC5D,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;YACrC,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;YACtC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,YAAY,QAAQ,+BAA+B,CAAC,CAAC;YAC9G,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC/B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,CAAC;QAED,IAAI,CAAC,MAAM,GAAG;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,IAAI,CAAC,cAAc;YAC9B,MAAM,EAAE,IAAI,CAAC,WAAW;YACxB,aAAa;YACb,KAAK;SACN,CAAC;QACF,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF","sourcesContent":["import { assert } from \"@/assert.js\";\nimport { type Frame, PackedPositions } from \"@/render/frame.js\";\nimport type { Swarm, SwarmState } from \"@/types.js\";\n\nexport interface SamplerOptions {\n  /**\n   * The swarm to sample state from.\n   */\n  readonly swarm: Swarm;\n}\n\n/**\n * The result of reading the swarm's state for a single frame.\n */\nexport interface Sample extends Frame {\n  /**\n   * The snapshot the buffers were filled from.\n   */\n  readonly state: SwarmState;\n}\n\n/**\n * Generates {@link Sample}s by reading a swarm's observable state.\n */\nexport class Sampler {\n  private readonly swarm: Swarm;\n\n  private positionBuffer = new Float32Array(0);\n  private speedBuffer = new Float32Array(0);\n\n  private inFlight: Promise<Sample> | null = null;\n  private latest: Sample | null = null;\n\n  constructor({ swarm }: SamplerOptions) {\n    this.swarm = swarm;\n  }\n\n  /**\n   * Reads the swarm's state for a single frame and returns a {@link Sample}. On\n   * subsequent calls, returns the most recent sample immediately.\n   */\n  sample(): Promise<Sample> {\n    this.inFlight ??= this.readState().finally(() => {\n      this.inFlight = null;\n    });\n    const latest = this.latest;\n    return latest === null ? this.inFlight : Promise.resolve(latest);\n  }\n\n  private async readState(): Promise<Sample> {\n    const state = await this.swarm.snapshot();\n    const { positions, velocities } = state.particles;\n\n    const particleCount = positions.length;\n    assert(\n      velocities.length === particleCount,\n      `snapshot has ${particleCount} positions, but ${velocities.length} velocities`,\n    );\n\n    if (this.speedBuffer.length !== particleCount) {\n      this.positionBuffer = PackedPositions.allocate(particleCount);\n      this.speedBuffer = new Float32Array(particleCount);\n    }\n\n    const points = PackedPositions.of(this.positionBuffer);\n\n    for (let particle = 0; particle < particleCount; particle++) {\n      const position = positions[particle];\n      const velocity = velocities[particle];\n      assert(position !== undefined && velocity !== undefined, `particle ${particle} is missing from the snapshot`);\n      points.set(particle, position);\n      this.speedBuffer[particle] = Math.hypot(velocity[0], velocity[1], velocity[2]);\n    }\n\n    this.latest = {\n      time: state.time,\n      positions: this.positionBuffer,\n      speeds: this.speedBuffer,\n      particleCount,\n      state,\n    };\n    return this.latest;\n  }\n}\n"]}

package/dist/render/signal.d.ts

@@ -0,0 +1,66 @@
+import { type Channel } from "../render/channel.js";
+import type { Source } from "../render/sources.js";
+export interface ParticleSpeedSource extends Source {
+    /**
+     * Each particle's velocity magnitude for the current frame, in scene units
+     * per second.
+     */
+    speeds(): Float32Array;
+}
+export interface ParticleDepthSource extends Source {
+    /**
+     * Each particle's distance into the scene along the view axis for the current
+     * frame, in scene units.
+     */
+    depths(): Float32Array;
+}
+/**
+ * A component that normalizes the values provided by a channel.
+ */
+export interface Signal<S extends Source> {
+    /**
+     * The channel this signal reads from.
+     */
+    readonly channel: Channel<S>;
+    /**
+     * The `[low, high]` range mapped onto `0..1`. The endpoints must be
+     * finite and distinct. A reversed range is also valid and inverts the
+     * mapping.
+     */
+    readonly domain: readonly [number, number];
+    /**
+     * Whether raw values outside `domain` are clamped to `0..1` or allowed to
+     * extrapolate beyond it.
+     */
+    readonly clamp: boolean;
+}
+export interface SignalOptions {
+    /**
+     * The `[low, high]` range mapped onto `0..1`. The endpoints must be
+     * finite and distinct. A reversed range is also valid and inverts the
+     * mapping.
+     */
+    readonly domain: readonly [number, number];
+    /**
+     * Whether raw values outside `domain` are clamped or extrapolated beyond it.
+     */
+    readonly clamp?: boolean;
+}
+export declare function normalizeSignal({ domain: [low, high], clamp }: Signal<Source>, raw: number): number;
+/**
+ * The signal factories exposed on `view.signal`.
+ */
+export declare namespace signal {
+    /**
+     * A signal over the specified channel.
+     */
+    function of<S extends Source>(channel: Channel<S>, { domain, clamp }: SignalOptions): Signal<S>;
+    /**
+     * A particle's velocity magnitude, in scene units per second.
+     */
+    function speed(options: SignalOptions): Signal<ParticleSpeedSource>;
+    /**
+     * A particle's distance into the scene along the view axis, in scene units.
+     */
+    function depth(options: SignalOptions): Signal<ParticleDepthSource>;
+}

package/dist/render/signal.js

@@ -0,0 +1,51 @@
+import { assert } from "../assert.js";
+import { channel as defineChannel } from "../render/channel.js";
+/**
+ * Each particle's velocity magnitude, in scene units per second.
+ */
+const speedChannel = defineChannel({
+    name: "speed",
+    values: (source) => source.speeds(),
+});
+/**
+ * Each particle's distance into the scene along the view axis, in scene units.
+ */
+const depthChannel = defineChannel({
+    name: "depth",
+    values: (source) => source.depths(),
+});
+export function normalizeSignal({ domain: [low, high], clamp }, raw) {
+    const t = (raw - low) / (high - low);
+    return clamp ? Math.max(0, Math.min(1, t)) : t;
+}
+/**
+ * The signal factories exposed on `view.signal`.
+ */
+export var signal;
+(function (signal) {
+    /**
+     * A signal over the specified channel.
+     */
+    function of(channel, { domain, clamp = true }) {
+        const [low, high] = domain;
+        assert(Number.isFinite(low) && Number.isFinite(high), `${channel.name} signal domain must be finite, but is [${low}, ${high}]`);
+        assert(low !== high, `${channel.name} signal domain endpoints must differ, but are both ${low}`);
+        return { channel, domain, clamp };
+    }
+    signal.of = of;
+    /**
+     * A particle's velocity magnitude, in scene units per second.
+     */
+    function speed(options) {
+        return of(speedChannel, options);
+    }
+    signal.speed = speed;
+    /**
+     * A particle's distance into the scene along the view axis, in scene units.
+     */
+    function depth(options) {
+        return of(depthChannel, options);
+    }
+    signal.depth = depth;
+})(signal || (signal = {}));
+//# sourceMappingURL=signal.js.map