@msb235/blits 0.3.0 → 0.5.0

package/dist/lanes.d.ts

@@ -1,20 +1,13 @@
-import type { Subject, Voice } from './mixer.js';
+import type { Column } from './columns.js';
+import { type Crowd, row } from './crowd.js';
+import { call, foldKeys, one, parting, readKeyed, reset, run, signalled, subjectAt } from './fill.js';
+import { fold, foldDelta, foldInto, foldRun, gather } from './gather.js';
+import { type Lane, type Laned, type Locus } from './lane.js';
+import type { Watcher } from './motion.js';
+import { type absent, Numbers } from './numbers.js';
+import { Owed } from './owed.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>;
-};
+import type { Subject, Voice } from './voice.js';
 /** What a lane fill asks of the mix it belongs to. */
 export interface LaneHost<I, O> {
     readonly voices: readonly Voice<I, O>[];
@@ -22,14 +15,26 @@ export interface LaneHost<I, O> {
     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 voice's record for a subject this probe has already linked it to, from `head` if there. */
+    meet(voice: Voice<I, O>, subject: I, head: Subject<unknown> | null, slot: number): Subject<unknown>;
+    /** The number `slot` was let go of, to be handed to another subject. */
+    forgot(slot: number): void;
     /** 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;
+    /**
+     * A voice with a signal weight: the signal's value for a subject the general path has met, before
+     * the fade and ramp `weighed` applies, with the setting filled in for the call; makes the voice
+     * stateful if the signal keeps state. `slot` is the subject's number.
+     */
+    signal(voice: Voice<I, O>, subject: I, held: Subject<unknown>, elapsed: number, pass: number, slot: number): number;
     /** 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. */
@@ -39,39 +44,49 @@ export interface LaneHost<I, O> {
     /** 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;
+export declare class Lanes<I, O> implements Watcher {
+    readonly host: LaneHost<I, O>;
+    readonly numbers: Numbers<I>;
+    lanes: Lane<I, O>[];
     /** The lanes over every subject that have started playing, by epoch. */
-    private dense;
-    private readonly byId;
-    private laned;
+    dense: Lane<I, O>[];
+    readonly byId: Map<number, Lane<I, O>>;
+    /** The crowds of single-subject motion voices, one per channel, and which holds each voice. */
+    crowds: Crowd<I, O>[];
+    readonly crowdOf: Map<number, Crowd<I, O>>;
+    /** Whether two crowds share a channel, so their rows must interleave in voice order. */
+    overlap: boolean;
+    /** The loci whose voices are on lanes, every member of each on one. */
+    loci: Locus<I, O>[];
+    /** While a fill gathers a locus: that locus and the member gathering, where folds go instead. */
+    into: Locus<I, O> | null;
+    intoId: number;
+    readonly lawsByKey: Map<string, Float64Array<ArrayBufferLike>>;
+    lastLaw: Float64Array | null;
+    /** The lanes the last `meet` gave a position, and whether it placed a crowd row. */
+    readonly met: number[];
+    metCrowd: boolean;
+    /** By subject number, the laned voices its probes fold on the general path this fill. */
+    readonly owed: Owed;
+    laned: Laned[];
     /** By kit slot, the laned channel there. */
-    private bySlot;
+    bySlot: (Laned | undefined)[];
     /** 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;
+    cap: number;
+    epochs: number;
+    /** The latest epoch of a lane over every subject, which every subject meets on its next probe. */
+    wide: number;
+    /** Voices that joined, started or left since the last qualify, settled at the next probe. */
+    touched: Voice<I, O>[];
+    /** The highest voice id the last qualify or settling of `touched` considered. */
+    known: number;
     /**
      * 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;
@@ -79,129 +94,135 @@ export declare class Lanes<I, O> {
      * 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;
+    per: Float64Array<ArrayBuffer>;
+    fills: number;
+    probes: number;
     /**
      * 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;
+    subjects: (I | typeof absent | undefined)[];
     /** Whether a probe has held a subject since the last fill let them go. */
-    private holding;
+    holding: boolean;
     /** While a fill runs, so a probe a patch makes from inside it takes the general path. */
-    private filling;
+    filling: boolean;
     /**
      * 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;
+    readonly late: number[];
+    /**
+     * What `writeLater` and `pullRun` have queued, for one set of columns, as runs: each run's first
+     * lane slot, the row it goes to, and how many subjects follow both one apart.
+     */
+    queueSlots: Int32Array<ArrayBuffer>;
+    queueRows: Int32Array<ArrayBuffer>;
+    queueCounts: Int32Array<ArrayBuffer>;
+    queued: number;
+    queuedFor: readonly Column[] | null;
+    keeps: boolean;
+    now: number;
+    filledAt: number;
     /** `reading.moved` at the last fill, so a retarget or push between two probes refills. */
-    private moved;
+    moved: number;
     /** The `now` of the latest probe, and the probe count before its first, to tell a probe this frame. */
-    private frameAt;
-    private frameProbes;
+    frameAt: number;
+    frameProbes: number;
     /** The probe counts the last frame with a probe began and ended at, which lanes go idle by. */
-    private lastFrom;
-    private lastTo;
+    lastFrom: number;
+    lastTo: number;
     /** Set when a frame's first probe arrives, so its first fill decides which lanes go idle. */
-    private fresh;
+    fresh: boolean;
     /** Subjects probed this frame and in the last frame with a probe, counted once each. */
-    private distinct;
-    private lastDistinct;
+    distinct: number;
+    lastDistinct: number;
     /** Numbered subjects alive. */
-    private live;
-    private filledVersion;
-    private qualifiedVersion;
+    live: number;
+    filledVersion: number;
+    qualifiedVersion: number;
     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;
+    /** 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;
+    reported(lane: Lane<I, O>, slot: number): number | undefined;
     /**
      * 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;
+    prepare(slot: number, subject: I, now: number, version: number, head: Subject<unknown> | null): boolean;
+    /** Whether this frame's lanes are filled and nothing since asks `begin` to look again. */
+    filled(now: number, version: number): boolean;
+    /**
+     * 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 or the lanes are filled.
+     */
+    begin(now: number, version: number): number;
+    general(slot: number): false;
     /** Whether a probe has read the subject since the frame began, on either path. */
-    private probedThisFrame;
+    probedThisFrame(slot: number): boolean;
+    /** Whether the subject at `slot` reads some laned voice from the general path this fill. */
+    owes(slot: number): boolean;
+    /** Whether the subject at `slot` reads laned voice `id` from the general path this fill. */
+    owesVoice(slot: number, id: number): boolean;
+    /** The weight the general path gave a voice the subject at `slot` owes, as `weightOf` reports. */
+    paid(id: number, slot: number, w: number): void;
     /**
-     * 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.
+     * Whether a subject's laned values are at their channels' rest, as `atRest` reads the pose `copy`
+     * would write: each number within 1e-9 of its rest.
      */
-    write(slot: number, columns: readonly Column[], n: number): void;
+    rests(slot: number): boolean;
     /** Writes a subject's laned values into a pose, each array channel into a new array. */
     copy(slot: number, pose: Record<string, unknown>): void;
+    forget(slot: number): void;
+    grow(size: number): 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.
+     * A laned voice's patch is about to change subject `s`'s stretch: a crowd copies it again at the
+     * next fill, and a lane keeps the sample the old one gave.
      */
-    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;
+    stretchChanged(id: number, s: number): void;
+    /** Something on a voice changed: a crowd copies it again at the next fill. */
+    voiceChanged(id: number): void;
+}
+declare const methods: {
+    row: typeof row;
+    signalled: typeof signalled;
+    parting: typeof parting;
+    subjectAt: typeof subjectAt;
+    reset: typeof reset;
+    run: typeof run;
+    one: typeof one;
+    foldKeys: typeof foldKeys;
+    readKeyed: typeof readKeyed;
+    call: typeof call;
+    gather: typeof gather;
+    fold: typeof fold;
+    foldDelta: typeof foldDelta;
+    foldRun: typeof foldRun;
+    foldInto: typeof foldInto;
+};
+type Methods = typeof methods;
+export interface Lanes<I, O> extends Methods {
 }
+export {};