@voluma/vlam 0.1.0 → 0.2.0

package/dist/streamed-splat-mesh-utils.d.ts

@@ -0,0 +1,146 @@
+/** Scheduling and data helpers shared by the streamed mesh implementation. */
+import type { SplatRange } from './splat-mesh';
+import type { SplatData } from './splat-data';
+import type { LodRun } from './lod-scheduler';
+/** One resident entry: the run description plus its pool handle. */
+type ResidentEntry = [string, {
+    run: LodRun;
+    handle: SplatRange;
+}];
+/** A set of adds and removals covering one contiguous leaf region. */
+export interface SwapGroup {
+    adds: LodRun[];
+    removes: ResidentEntry[];
+    leafStart: number;
+    leafEnd: number;
+    addCount: number;
+}
+/**
+ * One swap group per run for the startup hold. The mesh is invisible, so L0
+ * cell-atomicity is unnecessary; committing slice-by-slice lets the hold finish
+ * as soon as the capped set is resident instead of waiting on sibling subchunks.
+ */
+export declare function buildHoldSwapGroups(toAdd: readonly LodRun[]): SwapGroup[];
+/**
+ * Groups adds and removals into visible-cell transactions.
+ *
+ * Classic LCC (`coverageGroup` set on every run): one transaction per sub-leaf
+ * interval at every resolved level (including L0), so a cached slice can
+ * replace its own prior coverage while siblings still fetch. Hierarchical
+ * sources without coverage groups keep interval-overlap grouping.
+ */
+export declare function buildSwapGroups(toAdd: LodRun[], toRemove: ResidentEntry[]): SwapGroup[];
+/**
+ * Groups that only add coverage first (coarse before fine), then the ones that
+ * retire it - pure removals last of all.
+ *
+ * The order is what makes the wave gate in `reschedule` decidable: by the time a
+ * retiring group is reached, every purely additive group has already had its
+ * turn, so "have the replacements landed?" is answered rather than guessed.
+ * Pure removals free pool rows, so they go last, where they relieve the
+ * over-draw the gate deliberately trades for.
+ *
+ * Exported for tests only - not part of the public API surface.
+ */
+export declare function groupPriority(group: SwapGroup): number;
+/** True when every transaction belongs to classic LCC physical coverage. */
+export declare function isClassicLccSwapSet(groups: readonly SwapGroup[]): boolean;
+/**
+ * Orders classic display transactions by what the camera can see. This is
+ * separate from {@link groupPriority}: its global coarse-before-retirement
+ * wave preserves hierarchical RAD coverage, whereas LCC has an independent
+ * coarse shell for every L1+ slice and can safely commit a ready centre slice.
+ * Exported for tests only - not part of the public API surface.
+ */
+export declare function compareClassicSwapGroups(a: SwapGroup, b: SwapGroup): number;
+/** One classic-path chunk want, ranked before {@link StreamedSplatMesh} issues it. */
+export type ClassicFetchPhase = 'finest-target' | 'coverage' | 'target' | 'background';
+export interface ClassicFetchWant {
+    /** Cross-mesh scheduler kind derived from {@link phase}. */
+    kind: 'priority' | 'base';
+    /** Internal classic ranking tier (not exported on ChunkFetchKind). */
+    phase: ClassicFetchPhase;
+    distance: number;
+    level: number;
+    /** Prefer in-frustum wants; false means behind-camera / out of view. */
+    inView: boolean;
+    /** Classic LCC physical cell; `-1` when the source has no coverage groups. */
+    coverageGroup: number;
+    /** Source interval: L1+ uses this as its progressive display transaction. */
+    leafStart: number;
+    /** One past {@link leafStart}. */
+    leafEnd: number;
+    /** Fetch-only angular distance from the screen centre; smaller wins. */
+    screenImportance: number;
+    /**
+     * Min distance among pending wants in this coverage group. Stamped in
+     * {@link stampClassicFetchGroups} so a split cell's slices stay together.
+     */
+    groupDistance: number;
+    /** Pending file count in this coverage group; denser near cells win ties. */
+    groupPending: number;
+    /** True when any pending run in this group is in-frustum. */
+    groupInView: boolean;
+    /** Best screen-centre score among runs in this fetch transaction. */
+    groupScreenImportance: number;
+    /** True when this transaction contains a finest-level (L0) target. */
+    groupFinest: boolean;
+    /** Stable aggregate key: L0 cell, L1+ slice, or singleton file. */
+    groupId: string;
+    /** Visible(0) / near-out-of-view(1) / background(2) ranking bucket. */
+    groupClass: 0 | 1 | 2;
+}
+/**
+ * Fills {@link ClassicFetchWant.groupDistance} / `groupPending` so ranking can
+ * finish one near cell before sprinkling bandwidth across neighbors.
+ */
+export declare function stampClassicFetchGroups(pending: Map<number, ClassicFetchWant>, lodBaseDistance?: number, forceNearPriority?: boolean): void;
+/**
+ * Distance inside which classic LCC treats a cut as short-range for fetch
+ * ranking. Matches {@link LodSourceOptions.lodBaseDistance} (default 10).
+ */
+export declare function nearDisplayDistance(lodBaseDistance: number, _lodMultiplier?: number): number;
+/**
+ * True when this deferred group is waiting on resolved finest (L0) - never
+ * flash coarsest discs as a stand-in.
+ */
+export declare function isWaitingOnFinest(group: SwapGroup): boolean;
+/**
+ * Classic fetch phase for a **resolved** desired run. Ambition-only levels are
+ * never requested - callers pass runs from `computeDesiredRuns` only.
+ */
+export declare function classicFetchPhaseForDesired(run: LodRun, lodBaseDistance: number, lodMultiplier?: number): ClassicFetchPhase;
+/** Classic fetch phase for a pinned coarsest substitute of an L1+ gap. */
+export declare function classicFetchPhaseForCoverage(run: LodRun, lodBaseDistance: number, lodMultiplier?: number): ClassicFetchPhase;
+/**
+ * Maps a desired run to the cross-mesh fetch kind. Prefer
+ * {@link classicFetchPhaseForDesired} for ranking; this remains for tests.
+ */
+export declare function classicFetchKindForDesired(run: LodRun, lodBaseDistance: number, lodMultiplier?: number): ClassicFetchWant['kind'];
+export declare function enqueueClassicFetch(pending: Map<number, ClassicFetchWant>, file: number, phase: ClassicFetchPhase, run: LodRun): void;
+/**
+ * Sort by coverage group first: visible groups, then near out-of-view, then
+ * background. Within a group: coverage → resolved target (L0/L1+) → background.
+ */
+export declare function compareClassicFetches(a: ClassicFetchWant, b: ClassicFetchWant, fileA: number, fileB: number): number;
+/** Zero-copy view of one contiguous splat range within a decoded chunk.
+ * Exported for tests only - not part of the public API surface. */
+export declare function sliceSplatData(chunk: SplatData, offset: number, count: number): SplatData;
+export declare function chunkBytes(data: SplatData): number;
+/** An abort signal's reason as an Error, whatever the caller aborted with. */
+export declare function abortReason(signal: AbortSignal): Error;
+export declare function validateAppendCap(value: number | undefined): number;
+/** Validates Spark's per-mesh `lodScale`; `undefined` means the neutral 1. */
+export declare function validateLodScale(value: number | undefined): number;
+/**
+ * The decoded-chunk cache cap.
+ *
+ * Delegates to {@link resolveCpuCacheBytes} rather than re-deriving it. The
+ * local copy this replaces read `navigator.deviceMemory ?? 4`, which looks
+ * equivalent but is not: **iOS never reports `deviceMemory` at all**, so every
+ * iPhone took the `4` fallback and a 128 MiB cache, where the profile-aware
+ * policy gives a memory-less device 32 MiB. That is 96 MiB of decoded chunks
+ * held on the one platform whose tab gets killed for holding too much.
+ */
+export declare function defaultCpuCacheBytes(): number;
+export {};