@msb235/blits 0.2.1 → 0.3.0

package/dist/mixer.d.ts

@@ -1,6 +1,188 @@
-import type { Engine, Kit, Mix, MixOptions } from './types.js';
+import { type Curve } from './easing.js';
+import { type Built, intosOf, type Scratch } from './patch.js';
+import { Store } from './store.js';
+import type { Channel, Engine, FadeSpec, Kit, Mix, MixOptions, Patch, Setting, VoiceSpec } from './types.js';
+/** Everything one voice holds for one subject, chained through the next voice that reaches it. */
+export interface Subject<S> {
+    /** The voice's `target` answer, fixed on first sight. */
+    reaches: boolean;
+    /** The voice's `stagger` answer in voice ms, fixed on first sight. */
+    delay: number;
+    /** The mix timestamp this subject's delay ran out at, which its fade in counts from. */
+    since: number;
+    /** The weight this voice gave this subject the last frame it was probed, 0 where it gave none. */
+    weight: number;
+    /** Left at rest during a handover, so it stops contributing. */
+    rested: boolean;
+    /** Per written channel, whether a rest-less influence is on: 0 unknown, 1 on, 2 off. */
+    bands: Uint8Array;
+    state: S;
+    /** The `now` this subject last caught up to, for this voice. */
+    stepped: number;
+    /** Under `stepMs`, how many intervals have run since `since`; `stepped` is where that lands. */
+    ticks: number;
+    /** The `now` this subject was last probed at, so twelve probes in a frame step once. */
+    probed: number;
+    /** The last delta computed this frame, handed back to a repeat probe unchanged. */
+    delta: Record<string, unknown> | null;
+    /** The phase `delta` was read at, to read it again once its voice's scratch has moved on. */
+    phase: number;
+    /** The voice's `seeks` when `delta` was read, so a seek later in the frame reads it again. */
+    seeks: number;
+    /** Stop 0 for a `from: 'current'` voice, taken the first frame this subject is seen. */
+    base?: Record<string, unknown>;
+    /** The pose's velocity per channel at that moment, units per ms, so the first segment leaves at it. */
+    slope?: Record<string, unknown>;
+    /** What each stateful signal on this voice keeps for this subject, by the signal. */
+    kept: Map<object, unknown>;
+    keep: Setting['keep'];
+    /** Under `history`, copies of this record by the mix time they were taken, oldest first. */
+    snaps?: {
+        at: number;
+        held: Subject<S>;
+    }[];
+    /** In a projection: where this record started from, and whether nothing known could be. */
+    from?: number;
+    unknown?: boolean;
+    /** Under `history` with `inputs`, what an input weight signal read for this subject, when it changed. */
+    inputs?: {
+        at: number;
+        value: number;
+    }[];
+    /** In a projection reading back: that record, to read in place of the signal. */
+    replay?: {
+        at: number;
+        value: number;
+    }[];
+    /** The voice this is the record of; null on a subject's stub. */
+    voice: object | null;
+    /** The next voice's record for this subject, in voice order, among those that reach it. */
+    next: Subject<unknown> | null;
+    /**
+     * On the first record, which the mix keeps per subject so a probe makes one lookup: the `version`
+     * the chain was linked at, and per locus and channel whether a rest-less influence is on.
+     */
+    version: number;
+    loci: Map<string, boolean> | null;
+    /** On the first record: the number lanes index this subject by, -1 without one. */
+    slot: number;
+}
+/** What sets a voice's clock: its rate, and where it was last anchored. */
+interface Clock {
+    anchorNow: number;
+    anchorElapsed: number;
+    rate: number;
+    ramp: {
+        from: number;
+        to: number;
+        over: number;
+    } | null;
+}
+/** A voice's clock, weight and fade from one mix time on, kept under `history`. */
+interface Controls extends Clock {
+    at: number;
+    weight: number;
+    out: Ramp | null;
+    /** Where its anchors had placed it then: start, and the start of an anchored fade out. */
+    start: number;
+    outAt: number;
+    /** Made by a sync, so it shows in that frame; a host's change between frames shows from the next. */
+    sync: boolean;
+}
+interface Ramp {
+    from: number;
+    at: number;
+    over: number;
+    rest: boolean;
+    deadline?: number;
+}
+export declare class Voice<I, O> {
+    readonly id: number;
+    readonly spec: VoiceSpec<I, O>;
+    readonly patch: Patch<I, O, unknown>;
+    readonly fade: FadeSpec;
+    start: number;
+    state: 'pending' | 'live' | 'fading' | 'done';
+    rate: number;
+    weight: number;
+    /**
+     * elapsed = anchorElapsed + the rate integrated from anchorNow, rebased on a rate change or a seek.
+     * Without a ramp the rate is constant; with one it moves linearly from `from` to `to` over `over`
+     * mix ms starting at the anchor, and holds `to` after.
+     */
+    anchorNow: number;
+    anchorElapsed: number;
+    ramp: {
+        from: number;
+        to: number;
+        over: number;
+    } | null;
+    out: Ramp | null;
+    readonly subjects: Store<I, Subject<unknown>>;
+    /** The subjects its spec names, or null where it names none. */
+    readonly named: ReadonlySet<I> | null;
+    /** Kit slot of each channel the patch writes, in `writes` order. */
+    readonly slots: number[];
+    /** The stops built ahead of time, for a `keys` patch. */
+    readonly built: Built | null;
+    /** The kit's `lerp` for each channel the patch writes, which keyed stops interpolate through. */
+    readonly lerps: Channel<unknown>['lerp'][];
+    /** Per keyed channel, the in-place form of the lerp its stops take, where it has one. */
+    readonly intos: ReturnType<typeof intosOf> | undefined;
+    /**
+     * The arrays keyed reads interpolate into: one set for the voice, not one per subject, since 10k
+     * subjects' worth of long-lived arrays costs more in cache misses than allocating them did.
+     */
+    scratch: Scratch;
+    /** The record whose delta holds `scratch`'s arrays; any other's must be read again to be handed out. */
+    holder: Subject<unknown> | null;
+    /** Whether its channels run as lanes this frame, so the general fold passes it by. */
+    laned: boolean;
+    /** How many times it has been sought, so a delta read before a seek is not handed out after it. */
+    seeks: number;
+    /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
+    keeping: boolean;
+    /** For a motion patch, the hook it was given to ask the mix for its subjects' voice time. */
+    frame: ((subject: I) => number) | null;
+    readonly ease: Curve | undefined;
+    /** How many passes its `loop` plays, worked out once. */
+    readonly passes: number;
+    /** Reused for every call this voice makes, so it is valid only during the call. */
+    readonly setting: Setting<unknown>;
+    /** Every subject this voice has been asked about, so a handover knows when it is finished. */
+    seen: number;
+    /** The longest stagger of any subject seen, so a finite loop waits for the last of them. */
+    latest: number;
+    restedCount: number;
+    /** The mix time it was cued at; -Infinity before the first sync. */
+    cuedAt: number;
+    /** The mix time it left at. */
+    doneAt: number;
+    /** Under `history`, its controls after each change, oldest first. */
+    log: Controls[] | null;
+    /** Where an anchored `out` or `end` puts its fade's start, mix time; Infinity until known. */
+    outAt: number;
+    /** Whether its start is still to be fixed by an anchor, so it waits pending. */
+    placing: boolean;
+    resolve: () => void;
+    readonly done: Promise<void>;
+    constructor(id: number, spec: VoiceSpec<I, O>, patch: Patch<I, O, unknown>, fade: FadeSpec, now: number, start: number, slotOf: Map<string, number>, channels: readonly Channel<unknown>[], host: unknown, send: (event: unknown) => void);
+    elapsedAt(now: number): number;
+    /** The mix time its clock reads `elapsed`, inverting `elapsedAt`; Infinity where it never will. */
+    timeAt(elapsed: number): number;
+    /** Records this voice's controls as they stand, from mix time `at`. */
+    note(at: number, sync?: boolean): void;
+    /**
+     * A copy for a projection: its own setting, which sends nothing, and its own per-subject records,
+     * filled from `fill`. With `controls` it takes those, as the voice stood at an earlier time.
+     */
+    copy(fill: (subject: I) => Subject<unknown> | undefined, controls?: Controls): Voice<I, O>;
+    rateAt(now: number): number;
+    /** Moves the anchor to `now`, carrying what is left of a ramp. */
+    rebase(now: number): void;
+}
 /**
- * The one that ships: both forms on the CPU, probed per subject on demand.
+ * The one that ships: every form on the CPU, probed per subject on demand.
  *
  * @category engine
  */
@@ -11,3 +193,4 @@ export declare const mixer: Engine;
  * @category mix
  */
 export declare function mix<I, O>(kit: Kit<O>, opts?: MixOptions): Mix<I, O>;
+export {};