@msb235/blits 0.6.0 → 0.7.0

package/dist/motions.d.ts

@@ -0,0 +1,266 @@
+import type { Curve } from './easing.js';
+import type { MotionSpec } from './types.js';
+/**
+ * One closed-form stretch: released at `at` (voice ms) from `x0` moving at `v0`, toward `to`, over
+ * `ms` for a tween (0 for any other shape).
+ */
+export interface Segment {
+    at: number;
+    ms: number;
+    x0: number[];
+    v0: number[];
+    to: number[];
+    /** The change that released it; undefined for a subject's first stretch. */
+    change?: Change;
+}
+export 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[];
+    /** The mix clock when it was made, NaN where no mix was playing the patch. */
+    made?: number;
+}
+/**
+ * The mix playing a patch, asked with its voice's id: an owner and an id, where a pair of closures
+ * cost two functions, their contexts and a weak reference per voice.
+ */
+export interface MotionOwner {
+    /** The subject's voice time at the mix's latest frame; NaN where no frame of the voice met it. */
+    frame(id: number, subject: unknown): number;
+    /** Brings a subject the voice faded out back to it, so a change is not made for nothing. */
+    revive(id: number, subject: unknown): void;
+    /** The mix clock at its latest frame; NaN before the first. */
+    now(): number;
+    /**
+     * The host made a change, already given its time, which a seek makes again on the patch its
+     * voice plays then: a voice a history store paged out comes back with a patch of its own.
+     */
+    changed<I>(id: number, motion: Motions<I>, subject: I, change: Change): void;
+    /** History leaving memory for a subject, which a mix with a history store pages out. */
+    page(id: number, stream: 'released' | 'stretch', subject: unknown, out: Paging[]): void;
+}
+/** A record of a motion patch's history leaving memory, at a mix time. */
+export interface Paging {
+    at: number;
+    data: unknown;
+}
+/** A subject's run as plain data: its flags, its stretches oldest first, and changes still to apply. */
+export interface Run {
+    flags: number;
+    stretches: Segment[];
+    pending: Change[] | undefined;
+}
+/**
+ * What a mix keeping copies of a patch's stretches is told, with its id and the subject's number,
+ * before one changes.
+ */
+export interface Watcher {
+    stretchChanged(id: number, s: number): void;
+}
+export interface Shape<I> {
+    from: (subject: I) => number[];
+    /** How fast each axis starts moving, given where it starts: still unless the options say. */
+    velocity: (subject: I, x: number[]) => 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;
+    /** Whether every subject's value is a number; undefined where that depends on the subject. */
+    scalarEvery(): boolean | undefined;
+    /** 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;
+    /** The patch's kind and constants, as `Patch.motion` reports them. */
+    spec(): MotionSpec;
+}
+/**
+ * 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;
+    /** Numbers by subject once a second is numbered: till then the one subject is found by `numbers`. */
+    private readonly slots;
+    /** Axes per subject; -1 until the first subject sets it. */
+    n: number;
+    private cap;
+    private stride;
+    /**
+     * The law, then each subject's run; empty until the first subject, the law read from `shape`.
+     * Read outside, at `bareAt`, and written only here.
+     */
+    runs: Float64Array<ArrayBuffer>;
+    /**
+     * 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>;
+    /**
+     * By subject number, changes not yet applied and earlier stretches a read back may reach: null
+     * until a subject first has one, since many patches are never changed. Each starts with room for
+     * one: an empty array written at 0 reserves 17, and most patches have one subject.
+     */
+    private pending;
+    private older;
+    /** By subject number, the change that released the stretch it is playing; null until one has. */
+    private causes;
+    /**
+     * The mix playing the patch and its voice's id, which an untimed change and a `read` with no time
+     * ask for the latest frame. Set by the mix that cues the patch, and cleared when its voice retires.
+     */
+    owner: MotionOwner | null;
+    ownerId: number;
+    /** Whether the channel it was cued on holds a number; undefined until it is cued. */
+    private holdsNumber;
+    private channel;
+    /**
+     * Records what the channel the patch is cued on holds, refusing a value of the other kind: at once
+     * where every subject's value is one kind, else on the first sample of a subject whose value is not.
+     */
+    cuedOn(channel: string, holdsNumber: boolean): void;
+    private frame;
+    constructor(shape: Shape<I>);
+    /** The patch's number for `subject`, made with its first stretch on first ask. */
+    slot(subject: I): number;
+    /** Sets the axes every subject moves on, at the first. */
+    private size;
+    /** Numbers `subject`, with room for its run. */
+    private take;
+    /** The patch's number for `subject`, undefined where it has none. */
+    private known;
+    /**
+     * Subjects released at a mix time a rewind may still reach, with their run as it stood, so a
+     * rewind before the release plays them on from there. Empty without history.
+     */
+    private released;
+    /**
+     * Forgets a subject, so a later ask starts it afresh from `from`. Given the mix time `at`, under
+     * history, its run is kept for a rewind before then, until `reach` passes it.
+     */
+    release(subject: I, at?: number, reach?: number): void;
+    /** Puts back each subject released after mix time `t`, as it stood when released. */
+    private unrelease;
+    /** Subject `s`'s run as it stands. */
+    private runAt;
+    /** A subject's run as plain data, for a voice leaving memory; undefined where it has none. */
+    pack(subject: I): Run | undefined;
+    /** Puts a subject's run back as `pack` or a release left it, replacing any it has now. */
+    unpack(subject: I, run: Run): void;
+    /** A released run a history store gave back, for a rewind to before its release. */
+    reclaim(subject: I, at: number, run: Run): void;
+    /**
+     * Stretches a history store gave back, each by the mix time it was in force by: each life of the
+     * subject, ended by a release, takes those from its own, ahead of the earliest it still keeps.
+     */
+    restretch(subject: I, back: readonly Paging[]): void;
+    /**
+     * Told, with `watchId`, whenever a subject's 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, cleared when its voice retires. An
+     * owner and an id, where a callback cost a closure and its context per patch.
+     */
+    watcher: Watcher | null;
+    watchId: number;
+    /** The easing a tween's stretches follow; undefined for every other shape. */
+    get ease(): Curve | undefined;
+    /** The patch's kind and constants. */
+    spec(): MotionSpec;
+    /** A copy of the patch's law, `[form, settle, k1, k2, k3]`. */
+    law(): Float64Array;
+    /** Whether `law` holds this patch's law, number for number, as `Object.is` compares them. */
+    hasLaw(law: Float64Array): boolean;
+    /**
+     * 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;
+    /**
+     * Where subject `s`'s run starts in `runs` (its release time, then flags, seconds, `x0`, `v0`
+     * and `to`) while it has nothing pending and no earlier stretch kept; -1 for any other.
+     */
+    bareAt(s: number): number;
+    /**
+     * 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;
+    forget(s: number): void;
+    /**
+     * Takes back every change made after mix time `t`: each subject plays from its earliest stretch
+     * kept, with the changes made by then queued to be applied again.
+     */
+    rewind(t: number): void;
+    private cut;
+    /** Where subject `s`'s run starts in `runs`. */
+    base(s: number): number;
+    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;
+    /**
+     * The mix time a stretch was in force by, which a store keys it under: when the change that
+     * ended it was made, which falls in the same life of the subject.
+     */
+    private made;
+    /** Lets go of stretches older than the one in force at `reading.horizon`. */
+    private prune;
+    private evaluateSegment;
+    private evaluate;
+}