@msb235/blits 0.2.1 → 0.4.0

package/dist/motion.d.ts

@@ -1,7 +1,16 @@
-import type { Patch } from './types.js';
-/** A number, or one number per axis. */
+import { type Curve } from './easing.js';
+import type { Easing, Patch } from './types.js';
+/**
+ * A number, or one number per axis.
+ *
+ * @category patch
+ */
 export type Value = number | readonly number[];
-/** One value for every subject, or one per subject. */
+/**
+ * One value for every subject, or one per subject.
+ *
+ * @category patch
+ */
 export type PerSubject<I, V> = V | ((subject: I) => V);
 /**
  * Where a subject is and how fast it is moving, at one moment of voice time.
@@ -13,6 +22,19 @@ export interface Motion<V extends Value = number> {
     /** Units per second. */
     velocity: V;
 }
+interface Change {
+    /**
+     * Voice ms it takes effect at; absent, until the subject's next read stamps it with that read's
+     * time, for one made while no frame had met the subject.
+     */
+    at?: number;
+    to?: number[];
+    v?: number[];
+}
+/** A motion patch's `frame` while no mix plays it: no subject has a latest frame. */
+export declare const noFrame: () => number;
+export declare const noRevive: () => void;
+export declare const noTouch: () => void;
 /**
  * A patch whose motion is a closed form per subject, so it lands in the same place at any frame
  * rate, and whose changes mid-flight start from where the subject is and how fast it moves.
@@ -20,11 +42,160 @@ export interface Motion<V extends Value = number> {
  * @category patch
  */
 export type Moving<I, O, V extends Value> = Patch<I, O, void> & {
-    /** Where `subject` is and how fast it moves at voice time `at`, default its last read. */
+    /**
+     * Where `subject` is and how fast it moves at voice time `at`, default the mix's latest frame,
+     * counting every change due by then. With no time given, undefined until a frame of its voice
+     * has met the subject, while the subject is still inside its stagger, and once that voice is gone.
+     */
     read(subject: I, at?: number): Motion<V> | undefined;
-    /** Sets `subject` moving at `velocity`, units per second, from voice time `at`, default its next read. */
+    /**
+     * Sets `subject` moving at `velocity`, units per second, from voice time `at`, default the mix's
+     * latest frame; for a subject no frame of its voice has met yet, or still inside its stagger, its
+     * first read, after any change with a time due by then.
+     */
     push(subject: I, velocity: V, at?: number): void;
 };
+interface Shape<I> {
+    from: (subject: I) => number[];
+    velocity: (subject: I) => number[];
+    /** Where it heads when released from `x` at `v`, given where it was heading. */
+    aim: (x: number[], v: number[], was: number[] | null, subject: I) => number[];
+    /** `[form, settle, k1, k2, k3]`. */
+    law: readonly number[];
+    /** Whether a subject's value is a number rather than an array. */
+    scalar: (subject: I) => boolean;
+    /** A tween's easing, which its law cannot hold; undefined, but present, on every other shape. */
+    ease: Curve | undefined;
+    /** A tween's seconds for a stretch the subject starts now; undefined, but present, on the rest. */
+    ms: ((subject: I) => number) | undefined;
+}
+/**
+ * A motion patch's subjects: the stretch each is playing, in one flat array by a number the patch
+ * gives it, with earlier stretches a read back may reach and changes not yet applied beside them.
+ * The one copy, read by `at` and by a mix's lane alike.
+ *
+ * After the law, each subject's run of `stride` numbers is its release time, its flags, a tween's
+ * seconds for the stretch, then `x0`, `v0` and `to` per axis. A live sample reads this one buffer and nothing else the patch owns: at
+ * 10k springs of one subject each, a buffer per field, a map lookup per sample and the law in an
+ * object of its own took a call from 130 ns to 490.
+ */
+export declare class Motions<I> {
+    private readonly shape;
+    private readonly numbers;
+    private readonly slots;
+    /** Axes per subject; -1 until the first subject sets it. */
+    n: number;
+    private cap;
+    private stride;
+    private runs;
+    /**
+     * Where `sample` leaves a subject's position and velocity, per axis. Shared by every patch, so
+     * read it before the next sample.
+     */
+    xs: Float64Array<ArrayBuffer>;
+    vs: Float64Array<ArrayBuffer>;
+    private readonly pending;
+    private readonly older;
+    /**
+     * The subject's voice time at the mix's latest frame, which an untimed change and a `read` with
+     * no time take; NaN where no frame of the patch's voice has met the subject. Set by the mix that
+     * cues the patch, and put back when its voice retires.
+     */
+    frame: (subject: I) => number;
+    /**
+     * Brings a subject its voice faded out back to it, so a change is not made for nothing. Set by
+     * the mix that cues the patch, and put back when its voice retires.
+     */
+    revive: (subject: I) => void;
+    constructor(shape: Shape<I>);
+    /** The patch's number for `subject`, made with its first stretch on first ask. */
+    slot(subject: I): number;
+    /** Forgets a subject, so a later ask starts it afresh from `from`. */
+    release(subject: I): void;
+    /**
+     * Called with a subject's number whenever its stretch or what is pending for it changes, so a
+     * mix keeping a copy of it knows to read it again. Set by the mix, put back when its voice retires.
+     */
+    touched: (s: number) => void;
+    /** The easing a tween's stretches follow; undefined for every other shape. */
+    get ease(): Curve | undefined;
+    /** A copy of the patch's law, `[form, settle, k1, k2, k3]`. */
+    law(): Float64Array;
+    /**
+     * Copies subject `s`'s current stretch into `out` from `o` as its release time, its seconds, then
+     * `x0`, `v0` and `to` per axis; false, copying nothing, while it has a change pending or an
+     * earlier stretch kept, which only `sample` handles.
+     */
+    stretchInto(s: number, out: Float64Array, o: number): boolean;
+    /** Whether subject `s`'s value is a number rather than an array. */
+    scalar(s: number): boolean;
+    /** The value `at` hands the mix: the first axis for a number, a fresh array otherwise. */
+    value(s: number, xs: Float64Array): number | number[];
+    /**
+     * Position and velocity at voice time `t` into `xo` and `vo`, a tween's velocity left at 0. A live
+     * read stamps every untimed change with `t` and commits every change due by then, in time order;
+     * a projection's read applies the timed ones to a copy and commits nothing.
+     */
+    sample(s: number, t: number, xo: Float64Array, vo: Float64Array): void;
+    /**
+     * A live `sample` at `t` for a subject with nothing pending and no earlier stretch kept, true
+     * then; false, writing nothing, for any other, which `quiet` and `sample` take instead.
+     */
+    sampleBare(s: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
+    /**
+     * Whether every subject has landed on its target at its voice time at the latest frame, as a
+     * sample there would find; one with a change waiting has not. Commits nothing.
+     */
+    landed(): boolean;
+    /**
+     * Whether a live `sample` at `t` would leave the subject's state as it is: nothing to stamp or
+     * commit by then, and nothing older than `reading.horizon` to let go of.
+     */
+    quiet(s: number, t: number): boolean;
+    /** Position and velocity at `at`, default the latest frame; undefined until there is one. */
+    read(subject: I, at?: number): {
+        x: Float64Array;
+        v: Float64Array;
+        s: number;
+    } | undefined;
+    /**
+     * Queues a retarget or push, untimed at the latest frame, for `subject`'s next read past its time.
+     * The queue keeps the changes with a time in time order, ahead of any still waiting for one.
+     */
+    change(subject: I, c: Change): void;
+    /** Files a change with a time after every one due by then, ahead of those still waiting for one. */
+    private queue;
+    /** Every change due by `t` applied to a copy of the stretch playing then, committing nothing. */
+    private peek;
+    private check;
+    private flag;
+    private forget;
+    /** Where subject `s`'s run starts in `runs`. */
+    private base;
+    private grow;
+    private write;
+    /** The stretch subject `s` is playing now, as an object. */
+    private latest;
+    /** The stretch playing at voice time `t`: the latest released by then, else the first. */
+    private playing;
+    private applied;
+    private commit;
+    private insert;
+    /** Lets go of stretches older than the one in force at `reading.horizon`. */
+    private prune;
+    private evaluateSegment;
+    private evaluate;
+}
+/**
+ * A stretch `t` voice ms into it, released at `at` from `x0` moving at `v0` toward `to` (each read
+ * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
+ * `[form, settle, k1, k2, k3]`, the head of a patch's buffer or a copy of it) picks between. A tween reads `ease` and
+ * `ms`, the stretch's length, dividing in milliseconds so a boundary lands exactly; every other
+ * form ignores them.
+ */
+export declare function closed(law: Float64Array, ease: Curve | undefined, n: number, at: number, ms: number, x0: ArrayLike<number>, x: number, v0: ArrayLike<number>, v: number, to: ArrayLike<number>, g: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
+/** The state behind a `'motion'` patch, for an engine that reads it directly. */
+export declare function motionOf<I>(p: object): Motions<I> | undefined;
 interface Common<I, V extends Value> {
     /** Units per second each subject starts moving at. Default 0. */
     velocity?: PerSubject<I, V>;
@@ -37,9 +208,8 @@ interface Common<I, V extends Value> {
 /**
  * A damped spring toward a target, solved in closed form. `to(subject, target)` retargets one
  * subject mid-flight, and the new stretch starts from where it is and how fast it moves, so there is
- * no kink. Time is the voice's, so `rate` and `seek` apply; a read earlier than the latest change
- * evaluates the latest stretch, not history. Its state is its own, kept per subject: cue each spring
- * on one voice.
+ * no kink. Time is the voice's, so `rate` and `seek` apply. Its state is its own, kept per subject:
+ * cue each spring on one voice. Every subject moves on the same number of axes.
  *
  * @category patch
  */
@@ -53,7 +223,11 @@ export declare function spring<I, O, V extends Value = number>(writes: keyof O,
     damping?: number;
     mass?: number;
 }): Moving<I, O, V> & {
-    /** Heads `subject` for `target` from voice time `at`, default its next read, keeping its velocity. */
+    /**
+     * Heads `subject` for `target` from voice time `at`, keeping its velocity: by default the mix's
+     * latest frame, or for a subject no frame of its voice has met yet, or still inside its stagger,
+     * its first read, after any change with a time due by then.
+     */
     to(subject: I, target: V, at?: number): void;
 };
 /**
@@ -69,4 +243,30 @@ export declare function glide<I, O, V extends Value = number>(writes: keyof O, o
     /** The friction's time constant, ms. Default 325, a touch scroll's. */
     ms?: number;
 }): Moving<I, O, V>;
+/**
+ * From one value to another over `ms` along an easing, solved in closed form, so frame rate does not
+ * change where a subject is. `to(subject, target)` retargets one subject mid-flight: the new stretch
+ * starts from where it is and takes the full `ms` again, so its velocity jumps where a spring's
+ * would not. Time is the voice's, so `rate` and `seek` apply, and a voice's `loop` does not repeat
+ * it. Cue each tween on one voice. Every subject moves on the same number of axes.
+ *
+ * @category patch
+ */
+export declare function tween<I, O, V extends Value = number>(writes: keyof O, opts: {
+    /** Where each subject starts. */
+    from: PerSubject<I, V>;
+    /** Where each subject ends. */
+    to: PerSubject<I, V>;
+    /** How long a stretch takes, ms: asked per subject each time one of its stretches starts. */
+    ms: PerSubject<I, number>;
+    /** The curve from `from` to `to`. Default `'ease'`, as CSS's. */
+    ease?: Easing;
+}): Omit<Moving<I, O, V>, 'push'> & {
+    /**
+     * Heads `subject` for `target` from voice time `at`, over a full `ms` from where it is: by default
+     * the mix's latest frame, or for a subject no frame of its voice has met yet, or still inside its
+     * stagger, its first read, after any change with a time due by then.
+     */
+    to(subject: I, target: V, at?: number): void;
+};
 export {};