@msb235/blits 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.4.0
+
+### Breaking
+
+- A tween's `MotionSpec` reads `ms: undefined` where its `ms` is a function of the subject.
+- `Handle.state` can read `'held'`. Only a voice cued with `hold` reaches it, so nothing changes at
+  run time for one cued without, but a `switch` over every state no longer covers them all.
+
+### Added
+
+- `mix.inert` is true when another frame would change no pose, so a host's loop may sleep while
+  `live` is still true: every voice is done, held after its passes at a plain weight, or a motion
+  whose every subject has landed on its target. A retarget, a fade or a cue makes it false again.
+- `handle.fade({ subject, over })` fades one subject out of a voice, which plays on for the rest.
+  Once the ramp ends the voice forgets the subject (its record, its lane position and a motion
+  patch's state for it) and no longer reaches it; a motion patch's `to` brings it back, met afresh.
+  `mix.drop(subject)` clears it too. It keeps the voice on its lane.
+- `tween`'s `ms` may be a function of the subject, asked each time one of its stretches starts.
+- `hold: 'before' | 'after' | 'both'` on a voice. Before, a subject shows the voice's first frame
+  while the voice is pending and while the subject waits out its `stagger`; after, a finite loop
+  shows its last frame once its passes are done and stays, `held`, until faded. `fade.in` counts
+  from the first frame shown. What WAAPI calls `fill`.
+- `handle.played` resolves true when a finite loop's last pass ends, false if the voice leaves
+  first. It never rejects.
+
+### Fixed
+
+- A `keys` or stateless `fn` voice naming one subject and writing one channel fills from its
+  channel's crowd, as a motion voice does, where it took the general path. On teitou 10k `fn`
+  voices of one subject each read by `pull` take 0.7 of the time they did.
+- A voice naming its subjects that is cued, starts or retires relinks only those subjects, and
+  joins or leaves its crowd in place, where it made every subject relink and the lanes qualify
+  every voice again: a frame stopping one of 10k such voices and cueing another fell from about
+  9 ms to 0.6 by `pull` on teitou. `mix.drop` looks only at the voices over every subject and
+  those naming the one dropped, where it walked every voice.
+- `mix.drop` frees a subject from a voice faded off it with `handle.fade({ subject })`, and a mix
+  whose last ramp of that kind is dropped can read `inert` again; it also frees the subject from a
+  motion patch that another voice plays on after the voice naming the subject left.
+- `pull` reads a list it read before in the same order from the lanes in one run, checking the
+  frame once rather than per subject: a tween voice over 10k subjects read by `pull` takes about
+  0.83 of the time it did on teitou.
+- A lane gives a `vec(1)` channel an array of one, as the general path does, where it gave a
+  bare number; and a motion voice on one folds without making an array per subject per frame.
+- A `tween` divides elapsed by its length in milliseconds, so a point a whole fraction of the way
+  in lands exactly: 150 ms into a 200 ms linear tween from 0 to 100 reads 75, not 74.99999999999999.
+- `pull` over a list read again in the same order skips looking each subject up, and copies lane
+  values a column at a time; a motion voice's lane fills in one loop. One tween voice over 10k
+  subjects read by `pull` takes 0.59–0.66 of the time it did on teitou; a spring 0.68–0.74.
+- Motion voices of one subject each fill from one crowd of flat rows per channel, and `sync` visits
+  only voices with something due: 10k tween voices of one subject each take 0.54–0.59 of the time
+  they did on teitou, 100k take 0.31–0.33.
+
 ## 0.3.0
 
 ### Breaking

package/README.md

@@ -76,9 +76,9 @@ so the engine keeps no dependencies; its README says how it works.
 
 ## Status
 
-v0.3.0, with two consumers. magicsmoke runs every fault on it, and
+v0.4.0, with two consumers. magicsmoke runs every fault on it, and
 [klieg](https://github.com/orochi235/klieg) composes all three of its systems — letter motion,
-part effects, and the environment a sign is lit by — on a mix each, on a branch not yet merged.
+part effects, and the environment a sign is lit by — on a mix each.
 That port was an extraction rather than a rewrite, so it is also the evidence that the arithmetic
 here is the arithmetic a working renderer already had: klieg's suite of 1974 cases and its
 screenshot baselines came through it unchanged.

package/dist/lanes.d.ts

@@ -1,4 +1,6 @@
+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 {
@@ -26,8 +28,12 @@ export interface LaneHost<I, O> {
     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. */
@@ -39,6 +45,18 @@ 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 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;
@@ -50,6 +68,23 @@ export interface Column {
     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.
@@ -63,6 +98,10 @@ export declare class Lanes<I, O> {
     /** 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;
@@ -72,6 +111,12 @@ export declare class Lanes<I, O> {
     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;
@@ -98,6 +143,12 @@ export declare class Lanes<I, O> {
      * 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;
@@ -123,9 +174,20 @@ export declare class Lanes<I, O> {
     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
@@ -139,14 +201,33 @@ export declare class Lanes<I, O> {
      * 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;
     /**
-     * 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.
+     * 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.
      */
-    write(slot: number, columns: readonly Column[], n: number): void;
+    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;
     /**
@@ -154,11 +235,52 @@ export declare class Lanes<I, O> {
      * 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;
@@ -177,6 +299,29 @@ export declare class Lanes<I, O> {
     /** 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
@@ -205,3 +350,4 @@ export declare class Lanes<I, O> {
     private foldRun;
     private foldInto;
 }
+export {};