@msb235/blits 0.2.1 → 0.4.0

package/dist/lanes.d.ts

@@ -0,0 +1,353 @@
+import { type Numeric } from './channels.js';
+import type { Subject, Voice } from './mixer.js';
+import { type Motions } from './motion.js';
+import type { Channel } from './types.js';
+/** What qualifying needs of one voice: whether its patch and spec can run on a lane, and its channels. */
+export interface Candidate {
+    readonly id: number;
+    readonly fits: boolean;
+    readonly slots: readonly number[];
+}
+/**
+ * Which channels run as lanes and which voices run on them: the fixed point where every voice
+ * writing a laned channel fits and writes only laned channels. Only channels some laned voice
+ * writes are laned.
+ */
+export declare function qualify(numeric: readonly boolean[], voices: readonly Candidate[]): {
+    channels: boolean[];
+    voices: Set<number>;
+};
+/** What a lane fill asks of the mix it belongs to. */
+export interface LaneHost<I, O> {
+    readonly voices: readonly Voice<I, O>[];
+    readonly channels: readonly Channel<unknown>[];
+    readonly names: readonly string[];
+    /** Whether a voice's patch and spec can run on a lane, its channels aside. */
+    fits(voice: Voice<I, O>): boolean;
+    /** The voice's record for a subject this probe has already linked it to. */
+    meet(voice: Voice<I, O>, subject: I): Subject<unknown>;
+    /** The voices whose `subjects` name the subject, in voice order. */
+    naming(subject: I): readonly Voice<I, O>[] | undefined;
+    /** The subject's number, -1 where it has none yet. */
+    slotOf(subject: I): number;
+    /** The voice's own fade for a subject whose delay ran out at `since`. */
+    envelope(voice: Voice<I, O>, since: number): number;
+    /** What a subject's own ramp out of the voice leaves of its weight, 0..1. */
+    parting(voice: Voice<I, O>, subject: I): number;
+    /** Fills the voice's setting and the send target for a call to its patch. */
+    ready(voice: Voice<I, O>, subject: I, held: Subject<unknown>, elapsed: number, pass: number, weight: number): void;
+    /** Sets `reading.horizon` for the voice and a subject delayed `delay` voice ms. */
+    horizon(voice: Voice<I, O>, delay: number): void;
+    /** Whether the mix keeps history, so a record a patch call changed may need a copy kept. */
+    readonly keeps: boolean;
+    /** After a patch call, keeps history of a record that grew kept state. */
+    after(voice: Voice<I, O>, held: Subject<unknown>): void;
+    /** A patch call left kept state on a record: the voice is stateful from now on. */
+    kept(voice: Voice<I, O>): void;
+}
+/** One laned channel: its arithmetic, and every numbered subject's folded value, `axes` per subject. */
+interface Laned {
+    name: string;
+    /** Its value is a number, its rest a number; otherwise an array, which `vec(1)` is too. */
+    scalar: boolean;
+    op: Numeric['op'];
+    rest: number;
+    axes: number;
+    values: Float64Array;
+    /** An array channel's rest, which a copy starts from as the general path's does. */
+    start: readonly number[];
+}
+/** One channel `pull` writes: where in the kit, how many numbers a subject, and its rest. */
+export interface Column {
+    key: string;
+    slot: number;
+    axes: number;
+    out: Float64Array;
+    /** The rest, clamped, or NaN for a channel with none. */
+    rest: Float64Array;
+    bounds: readonly [number, number] | undefined;
+}
+export declare function clampRun(out: Float64Array, at: number, n: number, [lo, hi]: readonly [number, number]): void;
+/**
+ * Where a motion voice's per-subject numbers live, by position: a lane of one voice, or the crowd
+ * of single-subject motion voices, whose positions each belong to a voice of their own.
+ */
+export interface Positions<I, O> {
+    /** `STRIDE` numbers per position. */
+    data: Float64Array;
+    /** Each position's last delta, built from its kept sample only when asked. */
+    deltas: (Record<string, unknown> | null)[];
+    /** Keeps a position's sample, `n` numbers from `xs`. */
+    keep(p: number, xs: Float64Array, n: number): void;
+    /** Reads a position's kept sample back into `xs`. */
+    kept(p: number, xs: Float64Array): void;
+    chans: Laned[];
+    voiceAt(p: number): Voice<I, O>;
+    motionAt(p: number): Motions<I> | undefined;
+}
+/**
+ * The lanes of one mix: subject numbers, which channels and voices run on lanes, and the values a
+ * frame's fill leaves for probes to copy.
+ */
+export declare class Lanes<I, O> {
+    private readonly host;
+    private readonly numbers;
+    private lanes;
+    /** The lanes a fill visits: every lane but the solo ones. */
+    private runs;
+    /** The lanes over every subject that have started playing, by epoch. */
+    private dense;
+    private readonly byId;
+    /** The crowds of single-subject motion voices, one per channel, and which holds each voice. */
+    private crowds;
+    private readonly crowdOf;
+    private readonly lawsByKey;
+    private laned;
+    /** By kit slot, the laned channel there. */
+    private bySlot;
+    /** By kit slot, whether a fill leaves the channel's values for probes to copy. */
+    readonly copies: boolean[];
+    /** Whether every voice in the mix is on a lane, so a filled subject has nothing left to fold. */
+    whole: boolean;
+    private cap;
+    private epochs;
+    /** The latest epoch of a lane over every subject, which every subject meets on its next probe. */
+    private wide;
+    /** Voices that joined, started or left since the last qualify, settled at the next probe. */
+    private touched;
+    /** The highest voice id the last qualify or settling of `touched` considered. */
+    private known;
+    /**
+     * Per subject number, `SLOT` numbers side by side, so a probe reads one place in memory: which
+     * fill last wrote it (0 for none); the latest lane epoch a probe of it has checked it against;
+     * how many idle lanes reach it, since a probe reads lanes only where none do; and the probe count
+     * at its last probe read from the lanes and at its last probe folded by the general path, with
+     * the fill the former read, which say whether a lane or a record holds what `weightOf` reports.
+     */
+    private per;
+    private fills;
+    private probes;
+    /**
+     * Each subject by number as last probed, held from that probe until the next fill uses it, so a
+     * fill rarely looks one up through its weak reference, which costs on every look. A host that
+     * stops syncing keeps at most one frame's probed subjects alive until its next fill, and none
+     * once no lane remains.
+     */
+    private subjects;
+    /** Whether a probe has held a subject since the last fill let them go. */
+    private holding;
+    /** While a fill runs, so a probe a patch makes from inside it takes the general path. */
+    private filling;
+    /**
+     * Numbers a fill left to the general path: handed out while it ran, or with a voice whose call
+     * the general path has to make.
+     */
+    private readonly late;
+    /** What `writeLater` has queued: lane slots and the rows they go to, for one set of columns. */
+    private queueSlots;
+    private queueRows;
+    private queued;
+    private inOrder;
+    private queuedFor;
+    private keeps;
+    private now;
+    private filledAt;
+    /** `reading.moved` at the last fill, so a retarget or push between two probes refills. */
+    private moved;
+    /** The `now` of the latest probe, and the probe count before its first, to tell a probe this frame. */
+    private frameAt;
+    private frameProbes;
+    /** The probe counts the last frame with a probe began and ended at, which lanes go idle by. */
+    private lastFrom;
+    private lastTo;
+    /** Set when a frame's first probe arrives, so its first fill decides which lanes go idle. */
+    private fresh;
+    /** Subjects probed this frame and in the last frame with a probe, counted once each. */
+    private distinct;
+    private lastDistinct;
+    /** Numbered subjects alive. */
+    private live;
+    private filledVersion;
+    private qualifiedVersion;
+    constructor(host: LaneHost<I, O>);
+    /** A change that may move a voice on or off its lane: qualify again, then fill again. */
+    invalidate(): void;
+    /** A change to a laned voice's weight or clock between probes: fill again. */
+    refill(): void;
+    /**
+     * A voice joined, started playing or left: the next probe takes it on or off its crowd where it
+     * can, and qualifies again where it cannot.
+     */
+    touch(voice: Voice<I, O>): void;
+    /** Numbers a subject the mix sees for the first time. */
+    number(subject: I): number;
+    release(slot: number): void;
+    /** A voice faded a subject out of itself alone: its lane lets the subject's position go. */
+    part(id: number, slot: number): void;
+    /** Takes a crowd row off its subject, to be placed again if a probe meets it again. */
+    private unplace;
+    /** A voice brought a subject back: its next probe meets every lane again, as it met them first. */
+    rejoin(slot: number): void;
+    /**
+     * A laned voice's weight for a subject at the last frame a probe read it from the lane; undefined
+     * where the subject's record holds it instead, because its last probe took the general path or
+     * the voice is not on a lane.
+     */
+    weightOf(id: number, slot: number): number | undefined;
+    private reported;
+    /**
+     * Fills the lanes once a frame, and says whether this probe of a subject reads its values from
+     * them. One that a lane has not met yet, newly numbered or newly reached, takes the general path
+     * this frame, which is where it is first seen; so does one probed from inside a fill.
+     */
+    prepare(slot: number, subject: I, now: number, version: number): boolean;
+    /**
+     * For a `pull` of a list it read last time in the same order, with every voice on a lane, where
+     * `heads` holds each position's remembered chain head unless all are known current: what
+     * `prepare` and `writeLater` do for each subject from position `from`, while the subject reads
+     * from the lanes; returns the first position that does not, or the list's length.
+     */
+    pullRun(slots: Int32Array, list: readonly I[], was: readonly I[], heads: readonly ({
+        version: number;
+    } | undefined)[] | null, from: number, columns: readonly Column[], now: number, version: number): number;
+    /** Whether this frame's lanes are filled and nothing since asks `begin` to look again. */
+    private filled;
+    /**
+     * What a probe does before its subject, once a frame's lanes are settled: qualifies and fills as
+     * needed. Says whether the subject takes the general path, whether only solo lanes exist, so
+     * there is nothing to fill, or whether the lanes are filled.
+     */
+    private begin;
+    private general;
+    /** Whether a probe has read the subject since the frame began, on either path. */
+    private probedThisFrame;
+    /**
+     * Queues a subject's values for each column at subject `n`'s places, for a `pull` that reads
+     * from the lanes while every voice is on one; `flush` writes what is queued, column by column. A
+     * channel no lane holds is at rest. Anything queued is written before the lanes fill again.
+     */
+    writeLater(slot: number, columns: readonly Column[], n: number): void;
+    flush(): void;
+    /** Writes a subject's laned values into a pose, each array channel into a new array. */
+    copy(slot: number, pose: Record<string, unknown>): void;
+    /**
+     * Gives a probed subject a position on every lane that started playing since the subject was last
+     * checked and that reaches it. True when any did, so the probe takes the general path.
+     */
+    private meet;
+    /** Places a crowd voice's row on the subject a probe met, as `Lane.add` adds a position. */
+    private place;
+    /** Counts an idle lane more or fewer reaching a subject. */
+    private reach;
+    private forget;
+    private grow;
+    private requalify;
+    /**
+     * Rebuilds the crowds from the voices that belong in one, in voice order: a voice already in a
+     * crowd keeps its row's numbers, a new one gets a row a probe will place, and a voice no longer in
+     * one is handed back to the general path, as a lane's voice is when it leaves.
+     */
+    private regroup;
+    /**
+     * Gives a voice the next row of its channel's crowd, made if there is none: a copy of the row it
+     * had in `from` at `at`, or a new one. `old` holds the crowds being replaced, whose idle state a
+     * new crowd on the same channel keeps. Rows stay in voice order only because voices join in it.
+     */
+    private join;
+    /**
+     * A voice starts playing on a lane or crowd: its epoch. Every subject meets a voice over all of
+     * them on its next probe; a voice naming its subjects marks only those.
+     */
+    private open;
+    /**
+     * Takes the voices `touch` named on or off their crowds, each as it now stands; false at the
+     * first that cannot be, which needs a qualify: one that leaves a lane or the general path, which
+     * may open a channel, or one that joins anything but a crowd on a laned channel. Neither a voice
+     * that fits joining laned channels nor a laned one leaving moves the fixed point `qualify` finds.
+     * False too once a crowd is more than half empty rows, which a qualify rebuilds without.
+     */
+    private retouch;
+    /** A crowd voice left: its row stays, empty, until the crowds are next rebuilt. */
+    private bury;
+    private copyRow;
+    private newRow;
+    /** A patch's law, as the one array every crowd row with the same law shares. */
+    private lawOf;
+    /** A crowd voice's patch changed a stretch: its copy is read again at the next fill. */
+    private touchedCrowd;
+    /** Something on a voice changed: a crowd copies it again at the next fill. */
+    voiceChanged(id: number): void;
+    /** Hands a crowd voice back to the general path, as `leave` does a lane's. */
+    private leaveCrowd;
+    /** A crowd row's weight as `reported` reads a lane position's. */
+    private reportedRow;
+    /** Hands a voice back to the general path, with the weights `weightOf` reports kept on its records. */
+    private leave;
+    private fillAll;
+    /**
+     * Sets a lane idle or busy by the share of its subjects probed in the last frame that had a probe,
+     * read from about 256 of them a prime stride apart, from an offset that moves each frame, so a host
+     * probing every second or third subject is not read as probing all or none. Both paths give the
+     * same values, so this only picks the cheaper.
+     */
+    private pace;
+    private flip;
+    /** Leaves a lane's subjects to the general path until it wakes, keeping what `weightOf` reports. */
+    private rest;
+    private wake;
+    private subjectAt;
+    /** One voice's contribution to every subject it plays on. */
+    private run;
+    private one;
+    /** Reads a keys voice's stops at `phase` into `delta`, interpolating into the reader's `scratch`. */
+    private readKeyed;
+    /** Calls a stateless fn voice's patch for a subject its general path has met, and folds the delta. */
+    private call;
+    /** Runs every crowd's rows whose voices come before voice `id`, from where each crowd reached. */
+    private crowdsUpTo;
+    /**
+     * A crowd's rows from its cursor up to voice `id`: what `runMotion` does for a lane's subjects,
+     * reading each row's voice and stretch from `hot`, and through `move` for whatever `hot` cannot
+     * answer, as `runMotion` does.
+     */
+    private runCrowd;
+    /** A keys or fn row's contribution, as `one` makes a lane position's. */
+    private row;
+    /** Copies what a fill reads of a crowd row's voice into `hot`; returns the row's flags. */
+    private copyVoice;
+    /** Copies a crowd row's current stretch from its patch into `hot`; returns the row's flags. */
+    private copyStretch;
+    /**
+     * A motion voice's fill: what `one` and `move` do for each subject, in one loop for the common
+     * case, a subject not yet probed this frame with nothing pending, and through `move` for the rest.
+     */
+    private runMotion;
+    /**
+     * A motion voice's value for a subject, sampled from the patch's state as its `at` would, but only
+     * where that sample changes nothing: one with a change to stamp, commit or let go of goes to the
+     * general path, which samples it if and when a probe asks, as it would with no lanes. A probe
+     * this frame already read keeps the value it read, as the general path's record would.
+     */
+    private move;
+    /** The delta a motion voice's last sample for position `p` made, built from `samples`. */
+    private sampled;
+    /**
+     * A probe this frame read a motion voice's value for the subject from an earlier fill: write onto
+     * its record what the general path's sample would have, so a later read this frame reuses it.
+     */
+    private settle;
+    /** For a keys voice: the delta's value for each channel it writes, read once per phase. */
+    private gather;
+    /** Folds what `gather` read into a subject's laned values. */
+    private fold;
+    /**
+     * Folds a delta a patch returned into a subject's laned values. The first few channels are read
+     * at a site of their own, which in most mixes sees one channel name and stays fast, where one
+     * site reading every name in turn slows every read.
+     */
+    private foldDelta;
+    /** Folds a motion sample's axes, kept apart from `foldInto` so neither reads two array kinds. */
+    private foldRun;
+    private foldInto;
+}
+export {};