@msb235/blits 0.2.0 → 0.3.0

package/dist/lanes.d.ts

@@ -0,0 +1,207 @@
+import type { Subject, Voice } from './mixer.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 voice's own fade for a subject whose delay ran out at `since`. */
+    envelope(voice: Voice<I, O>, since: number): 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 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;
+/**
+ * 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;
+    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;
+    /**
+     * 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;
+    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;
+    /** Numbers a subject the mix sees for the first time. */
+    number(subject: I): number;
+    release(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;
+    private general;
+    /** Whether a probe has read the subject since the frame began, on either path. */
+    private probedThisFrame;
+    /**
+     * Writes a subject's values into each column at subject `n`'s places, for a probe that reads from
+     * the lanes while every voice is on one: a channel no lane holds is at rest.
+     */
+    write(slot: number, columns: readonly Column[], n: number): 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;
+    /** Counts an idle lane more or fewer reaching a subject. */
+    private reach;
+    private forget;
+    private grow;
+    private requalify;
+    /** 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;
+    /**
+     * 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;
+}