@fjader/svelte 0.2.2 → 0.2.3

package/dist/gpu/identity-slot-packing.d.ts

@@ -18,12 +18,45 @@
  * on it. It is a pure function over plain arrays and maps, which is
  * what it should have been.
  *
- * Layout: index 0 is a permanent zero-length block, then one block per scale of
- * `[count, slot0, slot1, ...]`. The count header makes each block
- * self-describing, so the shader rejects an id past this scale's end instead of
- * reading into the next scale's slots — ids and the slot table can disagree
- * transiently while a dim appends. Budget is therefore
- * `capacity - 1 - (1 per scale)` slots.
+ * LAYOUT. Index 0 is a permanent empty block `[0, 0, 0]`. Then one SLOT
+ * block per scale, then one ACTIVITY block per live categorical field:
+ *
+ *   scale block: [count, actRef, n, slot0 … slot(count-1)]
+ *   field block: [group 0: act0 … act(n-1), group 1: act0 … act(n-1), …]
+ *
+ * Slots come first so that when the buffer runs out it is activity that is
+ * lost (a mark draws undimmed), never an axis. A field has a block while a
+ * scale draws it, selected on or not, and a field no chart draws any more
+ * frees its space. Tying the block to the selection instead saved that space
+ * on pages with nothing selected, but every select and clear then moved the
+ * block and rewrote every scale block pointing at it, slots included:
+ * measured at about 105000 floats uploaded per click for 20 scales on a
+ * 5000-category field, against 5000 when the block stays.
+ *
+ * KNOWN LIMIT: a field block that does not fit leaves a selection on that
+ * field doing nothing for the marks that dim by it. Routing (the mark's reads,
+ * see activity-reads.ts) still sends them to dim rather than filter, and their
+ * shader finds no activity. Routing does not ask the packer whether a field
+ * got a block, which would tie the query layer to the GPU layout; the packer
+ * warns instead, on load. It takes fields of tens of thousands of ids across
+ * several groups to reach. A buffer that grows on demand is the real fix.
+ *
+ * A scale block's header says how many ids its slots cover (`count`), where its
+ * field's activity block starts (`actRef`) and how many ids that block covers
+ * (`n`). The count is what makes a block self-describing, so the shader rejects
+ * an id past this scale's end instead of reading into the next scale's slots —
+ * ids and the slot table can disagree transiently while a dim appends.
+ *
+ * ACTIVITY says how selected each id is in each filter group (1 active, 0
+ * inactive; see FieldActivity). It belongs to the field, not to the scale:
+ * every scale on one field reads the same block, a mark choosing its group's
+ * half by its group index. So a click rewrites and resolves one half of one
+ * field block, however many scales draw that field. The header comes first so
+ * the shader finds `actRef` and `n` without reading `count`: the activity read
+ * is two dependent loads, as it was when the activity sat after the slots. No
+ * mark holds `actRef`; the packer writes it in the same pass that moves the
+ * field block, so it cannot go stale. A scale with no field to dim points at
+ * the empty block, where `n` is 0 and every id is active.
  *
  * TWO buffers share one set of offsets: `from` is where each id's current
  * transition started and `to` where it is going, and the resolve kernel writes
@@ -31,28 +64,43 @@
  * bindings rather than two runs in one buffer, so the halves line up at the
  * same base and one dispatch per block covers both.
  *
- * `t` is not in the buffers. It is PER SCALE — each band scale has its own
- * driver — and reaches the kernel as an immediate on that scale's dispatch, so
- * a frame where only `t` moved uploads nothing at all.
+ * `t` is not in the buffers. It is per scale (its data clock) and per field
+ * half (that group's selection clock), and reaches the kernel as an immediate
+ * on that range's dispatch, so a frame where only `t` moved uploads nothing.
  */
 /**
  * Floats GLOBALLY across every band and point scale on the page, headers
- * included.
+ * included, and every live field's activity.
  *
  * No longer a binding limit: the tables are storage buffers, bound only to the
- * resolve pass, and the render stages read one resolved storage buffer. The
- * number is left over from when they were 64 KB uniforms, and making the
- * allocation grow on demand (recreate the buffers, rebuild the bind groups) is
- * what would retire it.
+ * resolve pass, and the render stages read one resolved storage buffer. Making
+ * the allocation grow on demand (recreate the buffers, rebuild the bind groups)
+ * is what would retire it.
+ *
+ * Each scale takes `3 + count`; each live field `n × groups`. 65536 fits a
+ * 5000-category field selected on across 3 groups (15000) with its scales
+ * (about 5000 each) several times over. It costs 256 KB per buffer, 768 KB for
+ * the three; the resolve pass dispatches per block, sized by the block, so a
+ * larger buffer costs no GPU time.
  */
-export declare const IDENTITY_SLOT_CAPACITY = 16384;
+export declare const IDENTITY_SLOT_CAPACITY = 65536;
 /**
- * Base of the permanent zero-length block. A scale that cannot be placed points
- * here, so every lookup finds count 0 and discards — which is what the capacity
- * warning claims happens. Pointing it at a stale base instead left the scale
- * rendering, from another scale's slots.
+ * Base of the permanent empty block `[0, 0, 0]`. A scale that cannot be placed
+ * points here, so every lookup finds count 0 and discards, and every activity
+ * read finds n 0 and is fully active. Pointing it at a stale base instead left
+ * the scale rendering, from another scale's slots.
  */
 export declare const IDENTITY_SLOT_EMPTY = 0;
+/**
+ * The group index of a mark that reads no selection activity: identityActivity
+ * returns fully active for it before computing any offset, so it never indexes
+ * past a field block. A mark whose selectionResponse is 'filter' gets it: in
+ * the chart holding a selection's control it keeps its data (the chart skips
+ * its own selection), and this keeps it from dimming there too.
+ */
+export declare const NO_GROUP = 4294967295;
+/** Floats before a scale block's slots: count, actRef, n. */
+export declare const IDENTITY_SLOT_HEADER = 3;
 /**
  * One scale's slot table as the packer reads it: identity id -> display slot,
  * as the two ends of a transition and where between them it is.
@@ -73,17 +121,51 @@ export interface SlotSource {
     /** Bumped whenever `from` or `to` move; the packer re-uploads on it alone. */
     readonly version: number;
 }
-/** A scale with a slot table, as the packer needs it. */
+/**
+ * One group's activity on one field as the packer reads it: 1 active, 0
+ * inactive, as the two ends of a fade. ActivityTable has this shape.
+ *
+ * Its length is not trusted: the packer takes `n` from the field and pads with
+ * 1 or truncates, so a moment where the two disagree cannot shift the half onto
+ * the wrong ids.
+ */
+export interface ActivitySource {
+    readonly from: Float32Array;
+    readonly to: Float32Array;
+    /** 0 -> from, 1 -> to. Its own clock, not the slots'. */
+    readonly t: number;
+    /** Bumped whenever `from` or `to` change. */
+    readonly version: number;
+}
+/**
+ * A scale with a slot table, as the packer needs it: its slots, and the identity
+ * key of its field, whose activity block its header points at. No field (or a
+ * field with no activity block) points it at the empty block.
+ */
 export interface IdentitySlotScale {
     id: string;
     slots: SlotSource;
+    field?: string | null;
 }
 /**
- * One block to resolve this frame: `length` floats from `base`, at `t`.
+ * A categorical field's selection activity, as the packer reads it: one fade
+ * per filter group, over `count` ids. FieldActivity has this shape.
+ */
+export interface ActivityField {
+    readonly key: string;
+    /** Ids covered: the block's `n`. */
+    readonly count: number;
+    /** Group `index`'s fade, or null when that group never selected here (all 1). */
+    fadeOf(index: number): ActivitySource | null;
+}
+/**
+ * One range to resolve this frame: `length` floats from `base`, at `t`. A
+ * scale's slots and each group's half of a field block are separate ranges,
+ * since each has its own `t`.
  *
- * The count header is inside the range rather than skipped: it holds the same
- * value in both halves, so mixing it returns it, and the render stages read
- * their bound from the resolved copy. Pooled in the state and overwritten by
+ * The header is inside the slot range rather than skipped: it holds the same
+ * values in both buffers, so the kernel returns them exactly, and the render
+ * stages read it from the resolved copy. Pooled in the state and overwritten by
  * the next pack.
  */
 export interface ResolveBlock {
@@ -116,30 +198,65 @@ export interface IdentitySlotState {
     offsets: Map<string, number>;
     /** Last packed slotVersion per scale, so a static chart re-uploads nothing. */
     versions: Map<string, number>;
+    /** Last packed count per scale. */
+    counts: Map<string, number>;
+    /** Last packed actRef and n per scale: a field block that moved rewrites the header. */
+    refs: Map<string, number>;
+    ns: Map<string, number>;
+    /**
+     * The `t` each scale's slots were last resolved at, so a still frame
+     * dispatches nothing. A typed array per scale, created once, rather than a
+     * `Map<string, number>`: a fractional `t` stored as a Map value is boxed,
+     * which allocated on every frame of every transition.
+     */
+    resolvedT: Map<string, Float64Array>;
+    /** Per field: its block's base, `n` and the group count it was packed for. */
+    fieldBases: Map<string, number>;
+    fieldNs: Map<string, number>;
+    fieldGroups: Map<string, number>;
+    /** Per field, per group: the fade version last written and the `t` last resolved. */
+    fieldVersions: Map<string, Float64Array>;
+    fieldT: Map<string, Float64Array>;
+    /** The pass a scale last drew each field in: a field no scale draws gets no block. */
+    fieldSeen: Map<string, number>;
+    /** Fields whose block did not fit, warned about once until they fit again. */
+    warnedFields: Set<string>;
     /**
-     * The `t` each scale's block was last resolved at, so a still frame
-     * dispatches nothing and an animating one dispatches only the scales that
-     * are moving.
+     * The pass each scale was last seen in, for the eviction sweep.
+     *
+     * A pass counter rather than a Set cleared every pack: clearing a Set
+     * allocates a new table in V8, which made every frame allocate ~370 bytes
+     * (measured, 20 scales) even when nothing moved. Re-setting an existing key
+     * to a small integer allocates nothing.
      */
-    resolvedT: Map<string, number>;
-    /** Scratch for the eviction sweep; cleared, not reallocated, per pack. */
-    seen: Set<string>;
+    seenPass: Map<string, number>;
+    /** The current pass, a small integer that wraps. */
+    pass: number;
     /** Returned by every pack and overwritten by the next — read it immediately. */
     result: PackResult;
 }
 /** A state with the permanent empty block in place. */
 export declare function createIdentitySlotState(capacity?: number): IdentitySlotState;
 /**
- * Assign every scale a base, write the blocks that moved, and list what to
- * upload and what to resolve.
+ * Assign every field and scale a base, write the ranges that moved, and list
+ * what to upload and what to resolve.
+ *
+ * | Range | Rewritten when | Resolved when |
+ * |---|---|---|
+ * | A field's group half | its base, `n` or the group count moved, or that group's fade version | rewritten, or that fade's `t` moved |
+ * | A scale's header + slots | its base, slot version, or its field block's base or `n` moved | rewritten, or slot `t` moved |
+ *
+ * A range that is rewritten must be resolved even when its `t` did not move:
+ * the render stages read the resolved buffer, not these. A parked scale is
+ * neither rewritten nor resolved: it has no block, and the empty block it
+ * points at is never written.
  *
- * A block is REWRITTEN when its base or its version moved, and RESOLVED when it
- * was rewritten or its `t` moved. A parked scale is neither: it has no block,
- * and the empty block it points at is never written.
+ * Offsets are recomputed on every call because a block appearing or
+ * disappearing shifts every block after it. That is a running sum over a
+ * handful of blocks, and the alternative — a free list — would have to survive
+ * a block changing size, which happens whenever a dim appends. A field block
+ * that moves rewrites the headers pointing at it in the same pass.
  *
- * Offsets are recomputed on every call because a scale appearing or
- * disappearing shifts every scale after it. That is a running sum over a
- * handful of scales, and the alternative — a free list — would have to survive
- * a scale changing size, which happens whenever a dim appends.
+ * `fields` and `groups` default to none, which packs the slots alone.
  */
-export declare function packIdentitySlots(scales: readonly IdentitySlotScale[], state: IdentitySlotState): PackResult;
+export declare function packIdentitySlots(scales: readonly IdentitySlotScale[], state: IdentitySlotState, fields?: readonly ActivityField[], groups?: number): PackResult;