@msb235/blits 0.4.0 → 0.5.0

package/dist/fill.js

@@ -0,0 +1,381 @@
+import { foldNumber, lerpNumber } from './channels.js';
+import { passAt, phaseAt, silent, weighed } from './clock.js';
+import { flush } from './columns.js';
+import { crowdsUpTo, freshen } from './crowd.js';
+import { foldLocus, gatherLocus } from './gather.js';
+import { held } from './lane.js';
+import { reach } from './meet.js';
+import { absent } from './numbers.js';
+import { AT, NOTHING, readKeys, seg, segment, shifted } from './patch.js';
+import { reading } from './reading.js';
+import { move, runMotion } from './sample.js';
+/** The least prime at least `n`, and 1 below 2. */
+function primeFrom(n) {
+    if (n < 2)
+        return 1;
+    for (let c = n;; c++) {
+        let prime = true;
+        for (let d = 2; d * d <= c; d++)
+            if (c % d === 0) {
+                prime = false;
+                break;
+            }
+        if (prime)
+            return c;
+    }
+}
+export function fillAll(lanes, now, version) {
+    flush(lanes);
+    const host = lanes.host;
+    lanes.filling = true;
+    try {
+        lanes.fills++;
+        lanes.owed.begin(lanes.fills);
+        lanes.now = now;
+        lanes.filledAt = now;
+        lanes.filledVersion = version;
+        const size = lanes.numbers.size;
+        lanes.keeps = host.keeps;
+        const decide = lanes.fresh;
+        lanes.fresh = false;
+        const share = lanes.live > 0 ? lanes.lastDistinct / lanes.live : 1;
+        // Deciding which lanes and crowds go idle first, then running them, in voice order: a crowd's
+        // rows are folded between the lanes on either side of their voices, as the general path
+        // folds every voice in order.
+        let busy = false;
+        for (const lane of lanes.lanes) {
+            if (decide) {
+                // A lane with few subjects, such as one naming its own, goes by the share of all probed;
+                // one with a single subject shares nothing a fill could save, as a solo lane does not.
+                const line = lane.line;
+                const n = lane.list.length;
+                if (n >= 64)
+                    pace(lanes, lane);
+                else if (n === 1 && lane.motion === undefined) {
+                    if (!lane.idle)
+                        rest(lanes, lane);
+                }
+                else if (lane.idle ? share >= line.start : share < line.stop)
+                    flip(lanes, lane);
+            }
+            if (!lane.idle)
+                busy = true;
+        }
+        for (const c of lanes.crowds) {
+            if (decide) {
+                if (c.size >= 64)
+                    pace(lanes, c);
+                else if (c.idle ? share >= c.line.start : share < c.line.stop)
+                    flip(lanes, c);
+            }
+            c.cursor = 0;
+            if (c.stale)
+                freshen(c);
+            if (!c.idle && c.size > 0)
+                busy = true;
+        }
+        if (busy) {
+            for (const ch of lanes.laned)
+                ch.values.fill(ch.rest, 0, size * ch.axes);
+            for (const g of lanes.loci)
+                gatherLocus(lanes, g);
+            for (const lane of lanes.lanes) {
+                if (lane.idle)
+                    continue;
+                if (lanes.crowds.length > 0)
+                    crowdsUpTo(lanes, lane.voice.id);
+                lanes.run(lane);
+            }
+            if (lanes.crowds.length > 0)
+                crowdsUpTo(lanes, Number.POSITIVE_INFINITY);
+            for (const c of lanes.crowds)
+                if (!c.idle) {
+                    c.bareFill = lanes.fills;
+                    c.bareNow = now;
+                }
+        }
+        // With every lane idle there was nothing to fill, and no subject reads a lane this frame.
+        if (busy)
+            for (let s = 0; s < size; s++)
+                lanes.per[s * 6 /* Per.SLOT */ + 0 /* Per.FILLED */] = lanes.fills;
+        for (const slot of lanes.late)
+            lanes.per[slot * 6 /* Per.SLOT */ + 0 /* Per.FILLED */] = 0;
+        if (lanes.holding) {
+            lanes.subjects.fill(undefined, 0, size);
+            lanes.holding = false;
+        }
+        lanes.moved = reading.moved;
+    }
+    finally {
+        lanes.filling = false;
+        lanes.late.length = 0;
+    }
+}
+/**
+ * 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.
+ */
+function pace(lanes, lane) {
+    const list = lane.list;
+    const line = lane.line;
+    const from = lanes.lastFrom;
+    const to = lanes.lastTo;
+    const step = primeFrom(Math.floor(list.length / 256));
+    let looked = 0;
+    let probed = 0;
+    for (let p = lanes.fills % step; p < list.length; p += step) {
+        const slot = list[p];
+        if (slot < 0)
+            continue;
+        const a = lanes.per[slot * 6 /* Per.SLOT */ + 3 /* Per.LANE_PROBE */];
+        const b = lanes.per[slot * 6 /* Per.SLOT */ + 4 /* Per.GENERAL_PROBE */];
+        if ((a > from && a <= to) || (b > from && b <= to))
+            probed++;
+        looked++;
+    }
+    const share = looked > 0 ? probed / looked : 1;
+    if (lane.idle ? share >= line.start : share < line.stop)
+        flip(lanes, lane);
+}
+function flip(lanes, lane) {
+    if (lane.idle)
+        wake(lanes, lane);
+    else
+        rest(lanes, lane);
+}
+/** Leaves a lane's subjects to the general path until it wakes, keeping what `weightOf` reports. */
+export function rest(lanes, lane) {
+    lane.idle = true;
+    const list = lane.list;
+    const data = lane.data;
+    for (let p = 0; p < list.length; p++) {
+        const slot = list[p];
+        if (slot < 0)
+            continue;
+        reach(lanes, slot, 1);
+        // A probe read this subject from the last fill, which this lane's weight stays from.
+        if (lanes.per[slot * 6 /* Per.SLOT */ + 5 /* Per.LANE_FILL */] === lanes.fills - 1) {
+            const o = p * 8 /* Row.STRIDE */;
+            data[o + 3 /* Row.PROBED */] = data[o + 2 /* Row.WEIGHT */];
+        }
+    }
+}
+export function wake(lanes, lane) {
+    lane.idle = false;
+    for (const slot of lane.list)
+        if (slot >= 0)
+            reach(lanes, slot, -1);
+}
+/**
+ * A voice with a signal weight: its weight for the subject at `slot` under the voice's fade `fade`,
+ * through the general path's own arithmetic; NaN where that path has not made the voice's first
+ * call for the subject, which it then makes this frame, so a signal that keeps state is first
+ * called where the general path would call it.
+ */
+export function signalled(voice, slot, rec, elapsed, pass, fade) {
+    if (Number.isNaN(rec.probed)) {
+        this.late.push(slot);
+        return Number.NaN;
+    }
+    const subject = this.subjectAt(slot);
+    if (subject === absent)
+        return 0;
+    const base = this.host.signal(voice, subject, rec, elapsed, pass, slot);
+    return weighed(base, fade, voice.parts === null ? 1 : this.host.parting(voice, subject));
+}
+/** What a subject's own ramp out of a voice leaves of its weight: 1 with none. */
+export function parting(voice, slot) {
+    if (voice.parts === null)
+        return 1;
+    const subject = this.subjectAt(slot);
+    return subject === absent ? 1 : this.host.parting(voice, subject);
+}
+export function subjectAt(slot) {
+    let subject = this.subjects[slot];
+    if (subject === undefined) {
+        subject = this.numbers.subject(slot);
+        this.subjects[slot] = subject;
+        this.holding = true;
+    }
+    return subject;
+}
+/** What a lane remembers within one fill, cleared before the fill runs it. */
+export function reset(lane) {
+    const voice = lane.voice;
+    lane.placed = false;
+    lane.read = false;
+    lane.weighed = false;
+    // With no fade in or out the envelope is 1 for every subject, which is what it would return.
+    lane.flat = !((voice.fade.in ?? 0) > 0) && voice.out === null && voice.owner === null;
+    lane.fade = 1;
+}
+/** One voice's contribution to every subject it plays on. */
+export function run(lane) {
+    const voice = lane.voice;
+    if (voice.state === 'pending' || voice.state === 'done')
+        return;
+    if (lane.group !== null) {
+        foldLocus(this, lane, lane.group);
+        return;
+    }
+    this.reset(lane);
+    if (lane.motion !== undefined && !voice.keeping) {
+        runMotion(this, lane, lane.motion);
+        return;
+    }
+    const elapsed = voice.elapsedAt(this.now);
+    const duration = voice.duration;
+    const passes = voice.passes;
+    const list = lane.list;
+    for (let p = 0; p < list.length; p++) {
+        this.one(lane, p, list[p], elapsed, duration, passes);
+        // Its patch just made kept state: no further call this fill, the general path makes them.
+        if (voice.keeping)
+            return;
+    }
+}
+/**
+ * One subject's contribution from a lane's voice. True where the voice gave the subject a delta,
+ * as the general path's `influence` does where it returns one, which is what makes a voice in a
+ * locus one of its members for the subject.
+ */
+export function one(lane, p, slot, elapsedNow, duration, passes) {
+    const host = this.host;
+    const voice = lane.voice;
+    const data = lane.data;
+    const o = p * 8 /* Row.STRIDE */;
+    // A probe read this subject from the last fill: keep the weight it read for `weightOf`.
+    if (this.per[slot * 6 /* Per.SLOT */ + 5 /* Per.LANE_FILL */] === this.fills - 1)
+        data[o + 3 /* Row.PROBED */] = data[o + 2 /* Row.WEIGHT */];
+    const delay = data[o + 0 /* Row.DELAY */];
+    const elapsed = held(voice, elapsedNow - delay);
+    if (!(elapsed >= 0)) {
+        data[o + 2 /* Row.WEIGHT */] = 0;
+        return false;
+    }
+    if (!lane.placed || !Object.is(elapsed, lane.placedAt)) {
+        lane.placed = true;
+        lane.placedAt = elapsed;
+        lane.phase = phaseAt(elapsed, duration, passes);
+        lane.pass = passAt(elapsed, duration, passes);
+    }
+    const since = data[o + 1 /* Row.SINCE */];
+    if (!lane.flat && (!lane.weighed || !Object.is(since, lane.weighedSince))) {
+        lane.fade = host.envelope(voice, since);
+        lane.weighed = true;
+        lane.weighedSince = since;
+    }
+    let w;
+    if (typeof voice.spec.weight === 'function') {
+        w = this.signalled(voice, slot, lane.records[p], elapsed, lane.pass, lane.fade);
+        if (Number.isNaN(w)) {
+            data[o + 2 /* Row.WEIGHT */] = 0;
+            return false;
+        }
+    }
+    else
+        w = weighed(voice.weight, lane.fade, this.parting(voice, slot));
+    data[o + 2 /* Row.WEIGHT */] = w;
+    if (voice.built !== null) {
+        if (!lane.read || !Object.is(elapsed, lane.readAt)) {
+            this.readKeyed(voice, lane.phase, lane.delta, lane.scratch);
+            lane.read = true;
+            lane.readAt = elapsed;
+            this.gather(lane, lane.delta);
+        }
+        if (w > 0)
+            this.fold(lane, slot, w);
+        return true;
+    }
+    const rec = lane.records[p];
+    // The general path makes a voice's first call for a subject, where it first sees it play.
+    if (Number.isNaN(rec.probed)) {
+        this.late.push(slot);
+        return false;
+    }
+    // A motion patch needs the subject only to number it, so the lookup waits until then.
+    if (lane.motion !== undefined) {
+        move(this, lane, lane.motion, p, slot, rec, elapsed, delay, w);
+        return true;
+    }
+    return this.call(voice, lane.chans, rec, slot, elapsed, lane.phase, lane.pass, delay, w);
+}
+/**
+ * A keys voice's stops at `phase` folded straight into a subject's values, without a delta: what
+ * `readKeyed` then `foldDelta` give, through the same segment search and the stock channels' own
+ * lerp, which is all a laned keys voice can use.
+ */
+export function foldKeys(voice, chans, phase, slot, w) {
+    const built = voice.built;
+    const tracks = built.tracks;
+    for (let i = 0; i < tracks.length; i++) {
+        const track = tracks[i];
+        const ch = chans[i];
+        const found = segment(track, shifted(track, phase, built.duration), undefined);
+        if (found === NOTHING)
+            continue;
+        if (found === AT) {
+            this.foldInto(ch, slot, seg.a, w);
+            continue;
+        }
+        const a = seg.a;
+        const b = seg.b;
+        const u = seg.eased;
+        if (ch.scalar) {
+            this.foldInto(ch, slot, voice.lerps[i](a, b, u), w);
+            continue;
+        }
+        // `vec`'s lerp, reading each end past its length as the rest, then its fold.
+        const as = a;
+        const bs = b;
+        const values = ch.values;
+        const base = slot * ch.axes;
+        const rest = ch.rest;
+        for (let x = 0; x < ch.axes; x++) {
+            const v = lerpNumber(as[x] ?? rest, bs[x] ?? rest, u);
+            values[base + x] = foldNumber(ch.op, values[base + x], v, w);
+        }
+    }
+}
+/** Reads a keys voice's stops at `phase` into `delta`, interpolating into the reader's `scratch`. */
+export function readKeyed(voice, phase, delta, scratch) {
+    readKeys(voice.built, phase, delta, undefined, voice.lerps, undefined, voice.intos, scratch);
+}
+/**
+ * Calls a stateless fn voice's patch for a subject its general path has met, and folds the delta;
+ * false for a subject the host has let go of.
+ */
+export function call(voice, chans, rec, slot, elapsed, phase, pass, delay, w) {
+    const host = this.host;
+    const subject = this.subjectAt(slot);
+    if (subject === absent)
+        return false;
+    // Called already this frame, by the general path or a fill before a refill: reuse, as a probe does.
+    if (rec.probed === this.now && rec.delta !== null && rec.seeks === voice.seeks) {
+        if (w > 0)
+            this.foldDelta(chans, slot, rec.delta, w);
+        return true;
+    }
+    if (silent(voice, w))
+        return true;
+    const kept = reading.kept;
+    host.ready(voice, subject, rec, elapsed, pass, w);
+    if (this.keeps)
+        host.horizon(voice, delay);
+    else
+        reading.horizon = Number.POSITIVE_INFINITY;
+    const delta = voice.patch.at(phase, subject, voice.setting);
+    // What `influence` leaves on the record, so a probe on the general path this frame reuses it.
+    rec.delta = delta;
+    rec.probed = this.now;
+    rec.seeks = voice.seeks;
+    if (this.keeps)
+        host.after(voice, rec);
+    if (reading.kept !== kept && !voice.keeping)
+        host.kept(voice);
+    if (w > 0)
+        this.foldDelta(chans, slot, delta, w);
+    return true;
+}

package/dist/fold.d.ts

@@ -0,0 +1,51 @@
+import type { Mixer } from './mixer.js';
+import type { Subject, Voice } from './voice.js';
+export type Key<O> = keyof O & string;
+export declare function near(a: unknown, b: unknown): boolean;
+export type Values = Record<string, unknown>;
+/**
+ * One live voice's delta for one subject this frame, through its record for the subject, or null
+ * when it does not reach. Its weight is left in `w`.
+ */
+export declare function influence<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, held: Subject<unknown>): Record<string, unknown> | null;
+/** Reads a keys voice's stops at `held.phase` into the subject's delta, through the voice's scratch. */
+export declare function keyed<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown>): Record<string, unknown>;
+/**
+ * Runs `step` once per whole interval between where this subject last stopped and now, on a grid
+ * counted from when its delay ran out, and leaves the remainder for the next sample. Counting
+ * rather than adding keeps the grid where it is however many samples it is reached through.
+ */
+export declare function tick<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown>, tick: number, to: number): void;
+/**
+ * Stop 0 for a retargeting voice: the subject's pose in the frame before this voice contributes.
+ * With no such frame on record — a voice cued before the subject was ever probed, or a host that
+ * samples into its own object — it is this frame's pose with every other voice folded in.
+ */
+export declare function baseFor<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): Record<string, unknown>;
+/**
+ * How fast each numeric channel this voice writes was moving, from the subject's last two probed
+ * poses, in units per ms. Undefined with fewer than two on record, which starts the voice at rest.
+ */
+export declare function slopeFor<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): Record<string, unknown> | undefined;
+export declare function isRest<I, O>(this: Mixer<I, O>, delta: Record<string, unknown>): boolean;
+/** Whether a rest-less channel's influence is switched on, across a band rather than an edge. */
+export declare function passes<I, O>(this: Mixer<I, O>, was: boolean | undefined, w: number): boolean;
+/** Folds one voice's delta into the pose, its band state kept on the subject's record. */
+export declare function apply<I, O>(this: Mixer<I, O>, pose: Record<string, unknown>, voice: Voice<I, O>, held: Subject<unknown>, delta: Record<string, unknown>, weight: number): void;
+/** Clamps every bounded channel of a folded pose into its range, in place. */
+export declare function clamp<I, O>(this: Mixer<I, O>, pose: Record<string, unknown>): Record<string, unknown>;
+export declare function fold<I, O>(this: Mixer<I, O>, subject: I, out?: O, dry?: boolean, except?: number): O;
+export declare function folded<I, O>(this: Mixer<I, O>, subject: I, out?: O, dry?: boolean, except?: number): O;
+/**
+ * A subject's chain, linked for this frame, and in `linkedLaned` whether its lanes answer for the
+ * voices on them; a subject numbered since the frame's fill folds every voice, laned ones included.
+ */
+export declare function linked<I, O>(this: Mixer<I, O>, subject: I): Subject<unknown> | null;
+/** The fold after a subject's chain is linked and its lanes asked whether it reads from them. */
+export declare function foldWith<I, O>(this: Mixer<I, O>, subject: I, out: O, head: Subject<unknown> | null, laned: boolean, dry: boolean, except?: number): O;
+/** Whether the subject numbered `owed` reads laned `voice` from the general path this fill. */
+export declare function owedBy<I, O>(this: Mixer<I, O>, owed: number, voice: Voice<I, O>): boolean;
+/** `foldWith`'s voices with a locus in play: each locus folds at its first member's place. */
+export declare function foldLoci<I, O>(this: Mixer<I, O>, subject: I, pose: Record<string, unknown>, head: Subject<unknown>, laned: boolean, dry: boolean, except: number | undefined, owed: number): O;
+/** `influence`, or for a dry fold a subject already probed this frame, without advancing it. */
+export declare function read<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, dry: boolean, held: Subject<unknown>): Record<string, unknown> | null;