@kalyptos/narcissus 0.1.3 → 0.2.1

package/dist/element/index.js

@@ -1,4 +1,4 @@
-import { b as e, h as t, p as n, s as r, t as i } from "../controls-IBLB-RWS.js";
+import { S as e, _ as t, h as n, s as r, t as i } from "../controls--A-CvrQ5.js";
 //#region src/element/index.ts
 var a = 4e3, o = 4e6, s = [2e6, 6e6], c = 2e6, l = [
 	.62,

package/dist/engine/engine.d.ts

@@ -1,8 +1,11 @@
 import { type World } from '../format/index.ts';
+import { type Layer } from './layer.ts';
+import type { Mask, MaskOptions } from './mask.ts';
+import type { Line, LineStyle, Marker, MarkerStyle } from './overlay.ts';
 import { type Mat4 } from './math/mat4.ts';
 import type { Fetch } from '../ports.ts';
 import type { Plugin } from './plugin.ts';
-import type { Camera, Settings, Stats } from './types.ts';
+import type { Camera, Progress, Settings, Stats } from './types.ts';
 export interface EngineOptions {
     settings: Settings;
     /** display rgb 0..1 behind the splats */
@@ -16,6 +19,14 @@ export interface EngineOptions {
     /** no animation loop: frames come only from step(), for benches */
     manual?: boolean;
 }
+export interface Hit {
+    /** where the pixel's ray meets the splat's depth, world coordinates */
+    point: [number, number, number];
+    /** unit; the splat's thinnest axis, toward the camera */
+    normal: [number, number, number];
+    /** null for the world */
+    layer: Layer | null;
+}
 export interface StepReport {
     /** main-thread ms of the frame */
     cpuMs: number;
@@ -25,12 +36,31 @@ export interface StepReport {
 }
 export interface Engine {
     open(worldUrl: string): Promise<World>;
+    /**
+     * a layer from a pack, its bytes or its url read through the engine's source; origin is the
+     * south-west corner its positions count from, as encodeLayer gives it. it stays through open()
+     */
+    addLayer(source: {
+        url: string;
+    } | {
+        bytes: Uint8Array;
+    }, origin: readonly [number, number]): Promise<Layer>;
+    addMask(mask: MaskOptions): Mask;
+    /** a polyline in world coordinates over the splats; one point draws a dot */
+    addLine(points: readonly Point[], style?: LineStyle): Line;
+    addMarker(point: Point, style?: MarkerStyle): Marker;
+    /** canvas css pixel of a world point under the camera set last, null behind it */
+    toScreen(point: Point): [number, number] | null;
     setCamera(camera: Camera): void;
     configure(settings: Partial<Settings>): void;
     /** canvas size in css pixels and the device pixel ratio to render at */
     resize(width: number, height: number, ratio: number): void;
-    /** world point under canvas css pixel (x, y), or null over nothing */
-    pick(x: number, y: number): Promise<[number, number, number] | null>;
+    /**
+     * the surface under canvas css pixel (x, y), or null over nothing: where the splats the last
+     * frame drew there, blended front to back, first cover half the pixel, met on that splat's
+     * plane; it renders no frame of its own
+     */
+    pick(x: number, y: number): Promise<Hit | null>;
     ground(e: number, n: number): number | undefined;
     /** ground(e, n) once every .idx over (e, n) is read */
     groundAt(e: number, n: number): Promise<number | undefined>;
@@ -45,6 +75,8 @@ export interface Engine {
     use(plugin: Plugin): () => void;
     /** device loss, with its reason; the engine is then dead */
     onLost(fn: (reason: string) => void): () => void;
+    /** fn(progress) each time the planned or missing splats, or whether pages load, change */
+    onProgress(fn: (progress: Progress) => void): () => void;
     /** fn(now) starts each frame the loop draws, so a camera it sets shows in that frame */
     onFrame(fn: (now: number) => void): () => void;
     /** the camera may soon move: after a rest, frames run a moment so the gpu is up to speed by then */

package/dist/engine/gpu/masks.d.ts

@@ -0,0 +1,26 @@
+import { type Prism } from '../math/prism.ts';
+export declare class Masks {
+    #private;
+    /** layout of group 1 in the passes that call masks.wgsl's masked() */
+    readonly layout: GPUBindGroupLayout;
+    constructor(device: GPUDevice);
+    get group(): GPUBindGroup;
+    get size(): number;
+    /** a new mask's id */
+    add(prism: Prism, targets: ReadonlySet<number>): number;
+    enable(id: number, enabled: boolean): void;
+    delete(id: number): void;
+    /** world min e, n, max e, n of a mask's polygon */
+    area(id: number): readonly [number, number, number, number] | undefined;
+    /**
+     * whether an enabled mask over layer hides every centre in the world box min to max; when none
+     * does, the ids of those that may hide some go into crossing
+     */
+    relate(layer: number, min: ArrayLike<number>, max: ArrayLike<number>, crossing: number[]): boolean;
+    setOrigin(origin: readonly [number, number, number]): void;
+    /** words before the lists: the records and their vertices */
+    get listBase(): number;
+    /** the records, vertices and lists, as mask ids from listBase on; the last lists when left out */
+    write(lists?: number[]): void;
+    destroy(): void;
+}

package/dist/engine/gpu/overlay.d.ts

@@ -0,0 +1,21 @@
+/** a capsule from a to b, world coordinates; a marker where a is b */
+export interface Capsule {
+    a: readonly [number, number, number];
+    b: readonly [number, number, number];
+    /** pixels */
+    radius: number;
+    /** rgba 0 to 1 */
+    colour: readonly [number, number, number, number];
+    /** hidden where splats lie in front */
+    occlude: boolean;
+}
+export declare class Overlay {
+    #private;
+    constructor(device: GPUDevice, format: GPUTextureFormat, uniforms: GPUBuffer);
+    get count(): number;
+    /** the capsules to draw, moved into the floating-origin frame at origin */
+    set(capsules: readonly Capsule[], origin: readonly [number, number, number]): void;
+    /** draws over target, which holds the finished frame; depth is the splats' log-depth span */
+    encode(encoder: GPUCommandEncoder, target: GPUTextureView, depth: GPUTextureView): void;
+    destroy(): void;
+}

package/dist/engine/gpu/pick.d.ts

@@ -0,0 +1,28 @@
+import type { Frame, Shade } from '../plugin.ts';
+import { type FrameBuffers } from './buffers.ts';
+import type { Pool } from './pool.ts';
+export interface Found {
+    /** view depth, metres */
+    depth: number;
+    /** 0 for the world */
+    layer: number;
+    /** the splat's thinnest axis, toward the camera */
+    normal: [number, number, number];
+}
+export declare class Pick {
+    #private;
+    constructor(device: GPUDevice, pool: Pool, buffers: FrameBuffers);
+    /** the next pick runs these hooks, as project does */
+    hooks(shades: {
+        shade: Shade;
+        slot: number;
+    }[]): void;
+    /**
+     * submits a pick of target pixel (x, y from the top-left) over the frame's visible clusters;
+     * frame must be the last one submitted, whose uniforms and cull the buffers still hold. null
+     * where the splats over the pixel never reach half, and where more lay there than the buffer
+     * kept, which grows it for the next
+     */
+    run(x: number, y: number, frame: Frame): Promise<Found | null>;
+    destroy(): void;
+}

package/dist/engine/gpu/pool.d.ts

@@ -1,4 +1,6 @@
 import { type DecodedPage } from '../../format/index.ts';
+import { Masks } from './masks.ts';
+import type { Prism } from '../math/prism.ts';
 import type { Drawn } from '../types.ts';
 export declare class Pool {
     #private;
@@ -14,6 +16,7 @@ export declare class Pool {
     listed: number;
     /** splats */
     capacity: number;
+    readonly masks: Masks;
     constructor(device: GPUDevice, capacity: number);
     /** clusters the pool can hold */
     get slots(): number;
@@ -26,10 +29,11 @@ export declare class Pool {
     ids(): Iterable<number>;
     /**
      * queues page id of the unit with south-west corner (e, n), evicting the least recently drawn
-     * pages keep rejects; false when it cannot fit even then
+     * pages keep rejects; false when it cannot fit even then. a page of a layer other than 0 is pinned
      */
-    add(id: number, page: DecodedPage, unit: readonly [number, number], keep: (id: number) => boolean): boolean;
+    add(id: number, page: DecodedPage, unit: readonly [number, number], keep: (id: number) => boolean, layer?: number): boolean;
     remove(id: number): void;
+    /** removes every page but the pinned */
     clear(): void;
     /** pages queued and not yet uploaded */
     get queued(): number;
@@ -39,6 +43,10 @@ export declare class Pool {
     draw(drawn: Drawn[]): void;
     /** world position of the floating origin; rewrites every page origin */
     setOrigin(origin: readonly [number, number, number]): void;
+    /** a new mask over targets, layer numbers with 0 for the world; it hides from the next draw */
+    addMask(prism: Prism, targets: ReadonlySet<number>): number;
+    enableMask(id: number, enabled: boolean): void;
+    deleteMask(id: number): void;
     /** room for capacity splats, the pages held staying in place; new buffers, so new bind groups */
     grow(capacity: number): void;
     destroy(): void;

package/dist/engine/gpu/project.d.ts

@@ -11,3 +11,8 @@ export declare class Project {
     }[]): void;
     encode(encoder: GPUCommandEncoder, visible: number, timestamps?: GPUComputePassTimestampWrites): void;
 }
+/** wgsl of parts, the hooks, and a shade(s) that runs them in order, each from its first slot */
+export declare function shaded(parts: string[], shades: {
+    shade: Shade;
+    slot: number;
+}[]): string;

package/dist/engine/gpu/raster.d.ts

@@ -12,8 +12,3 @@ export declare class Raster {
     encode(encoder: GPUCommandEncoder, colour: GPUTextureView, depth: GPUTextureView | null, sky: readonly [number, number, number], timestamps?: GPURenderPassTimestampWrites): void;
     destroy(): void;
 }
-/**
- * encodes a read of depth texel (x, y from the top-left, clamped); the call it returns, once the
- * encoder is submitted, gives view depth in metres, null where no splat drew
- */
-export declare function depthAt(device: GPUDevice, encoder: GPUCommandEncoder, depth: GPUTexture, x: number, y: number, near: number, far: number): () => Promise<number | null>;

package/dist/engine/gpu/renderer.d.ts

@@ -1,6 +1,8 @@
 import type { Frame, Post, Shade } from '../plugin.ts';
 import type { Gpu } from './device.ts';
 import type { Pool } from './pool.ts';
+import { type Capsule } from './overlay.ts';
+import { type Found } from './pick.ts';
 export interface GpuStats {
     gpuMs: number;
     passes: Record<string, number>;
@@ -8,12 +10,6 @@ export interface GpuStats {
     drawn: number;
     bytes: number;
 }
-/** view depth in metres of the nearest splat under target pixel (x, y from the top-left), null where none drew */
-export interface DepthPick {
-    x: number;
-    y: number;
-    resolve: (depth: number | null) => void;
-}
 /** Heights over cells x cells from corner (x, y), floating-origin frame */
 export interface HeightsRequest {
     x: number;
@@ -32,8 +28,12 @@ export declare class Renderer {
     post(pass: Post): () => void;
     /** render target size in pixels */
     resize(width: number, height: number): void;
-    /** encodes and submits a frame that answers picks and heights; resolves when the gpu has finished it */
-    render(frame: Frame, planes: Float32Array, sky: readonly [number, number, number], picks: DepthPick[], heights: HeightsRequest[]): Promise<void>;
+    /** the surface under target pixel (x, y from the top-left) as frame, the last rendered, drew it */
+    pick(x: number, y: number, frame: Frame): Promise<Found | null>;
+    /** host graphics the frames draw last, world coordinates moved to the floating origin */
+    overlay(capsules: readonly Capsule[], origin: readonly [number, number, number]): void;
+    /** encodes and submits a frame that answers heights; resolves when the gpu has finished it */
+    render(frame: Frame, planes: Float32Array, sky: readonly [number, number, number], heights: HeightsRequest[]): Promise<void>;
     stats(): GpuStats;
     destroy(): void;
 }

package/dist/engine/index.d.ts

@@ -1,9 +1,12 @@
 export { createEngine, NoWebGpu } from './engine.ts';
-export type { Engine, EngineOptions, StepReport } from './engine.ts';
+export type { Engine, EngineOptions, Hit, StepReport } from './engine.ts';
 export type { Cache, Fetch } from '../ports.ts';
 export type { Frame, Host, Plugin, Post, PostPass, Shade } from './plugin.ts';
+export type { Layer } from './layer.ts';
+export type { Mask, MaskOptions } from './mask.ts';
+export type { Colour, Line, LineStyle, Marker, MarkerStyle } from './overlay.ts';
 export type { World } from '../format/index.ts';
-export type { Camera, Settings, Stats } from './types.ts';
+export type { Box, Camera, Progress, Settings, Stats } from './types.ts';
 export { grade } from './plugins/grade.ts';
 export { dof } from './plugins/dof.ts';
 export { fog } from './plugins/fog.ts';

package/dist/engine/layer.d.ts

@@ -0,0 +1,26 @@
+import { type DecodedPage } from '../format/index.ts';
+import type { Box } from './types.ts';
+export interface Layer {
+    /** splats it draws */
+    readonly splats: number;
+    /** world extent of its splats' 3-sigma boxes */
+    readonly box: Box;
+    /** a hidden layer costs no frame time; its pages stay on the gpu, so it shows again at once */
+    visible: boolean;
+    /** 0 to 1, of every splat */
+    opacity: number;
+    /** frees its pages; the handle then does nothing */
+    remove(): void;
+}
+export interface LayerPage {
+    page: DecodedPage;
+    /** world min e, n, h then max e, n, h of its splats' extents */
+    box: Float64Array;
+}
+/**
+ * the pages of a pack whose positions count from origin, the south-west corner; only its finest
+ * level, as a layer draws at full detail at every distance
+ */
+export declare function layerPages(pack: Uint8Array, origin: readonly [number, number]): Promise<LayerPage[]>;
+/** the extent of page boxes as layerPages gives them */
+export declare function boxOf(boxes: Float64Array[]): Box;

package/dist/engine/mask.d.ts

@@ -0,0 +1,18 @@
+import type { Layer } from './layer.ts';
+/**
+ * a splat of a target is hidden while its centre lies inside the polygon by the even-odd rule and
+ * within z; at every level, through fades and while pages stream
+ */
+export interface MaskOptions {
+    /** world e, n of its corners, three or more */
+    polygon: readonly (readonly [number, number])[];
+    /** world heights from and to; the full height when left out */
+    z?: readonly [number, number];
+    /** what it hides: 'world' for the world's own splats, and layers */
+    targets: readonly (Layer | 'world')[];
+}
+export interface Mask {
+    enabled: boolean;
+    /** shows what it hid; the handle then does nothing */
+    remove(): void;
+}

package/dist/engine/math/frustum.d.ts

@@ -1,5 +1,8 @@
 import type { Mat4 } from './mat4.ts';
-/** the six planes of a webgpu view-projection (clip z 0..1), normalised; inside when n.p + d >= 0 */
-export declare function planes(out: Float32Array | Float64Array, m: Mat4): typeof out;
+/**
+ * the six planes of a webgpu view-projection (clip z 0..1), normalised; inside when n.p + d >= 0.
+ * sides moves left, right, bottom, top to those ndc bounds
+ */
+export declare function planes(out: Float32Array | Float64Array, m: Mat4, sides?: readonly number[]): typeof out;
 /** false only when the box lies wholly outside one plane */
 export declare function boxVisible(p: ArrayLike<number>, min: ArrayLike<number>, max: ArrayLike<number>): boolean;

package/dist/engine/math/prism.d.ts

@@ -0,0 +1,13 @@
+/** polygon as e0, n0, e1, n1, ..; z the height range, infinite for the full height */
+export interface Prism {
+    polygon: Float64Array;
+    z: readonly [number, number];
+}
+/** a box's relation to a prism, for every point in the box */
+export declare const OUT = 0;
+export declare const IN = 1;
+export declare const CROSS = 2;
+/** (x, y) inside polygon by the even-odd rule; masks.wgsl tests the same way */
+export declare function inside(polygon: ArrayLike<number>, x: number, y: number): boolean;
+/** OUT, IN or CROSS for the box min x, y, z to max x, y, z */
+export declare function relate(prism: Prism, min: ArrayLike<number>, max: ArrayLike<number>): number;

package/dist/engine/overlay.d.ts

@@ -0,0 +1,28 @@
+/** rgba, each 0 to 1 */
+export type Colour = readonly [number, number, number, number];
+type Point = readonly [number, number, number];
+export interface LineStyle {
+    colour?: Colour;
+    /** css pixels */
+    width?: number;
+    /** joins the last point to the first */
+    closed?: boolean;
+    /** hidden where splats lie in front; true when left out */
+    occlude?: boolean;
+}
+export interface MarkerStyle {
+    colour?: Colour;
+    /** css pixels across */
+    size?: number;
+    /** hidden where splats lie in front; true when left out */
+    occlude?: boolean;
+}
+export interface Line {
+    set(points: readonly Point[]): void;
+    remove(): void;
+}
+export interface Marker {
+    set(point: Point): void;
+    remove(): void;
+}
+export {};

package/dist/engine/stream/feed.d.ts

@@ -17,6 +17,8 @@ export declare class Feed {
      * arriving pages into the pool while protecting plan.keep and drawn
      */
     update(plan: Plan, drawn: ReadonlySet<number>, now: number): void;
+    /** a page the pool must not evict for another: plan.keep or drawn holds it */
+    protects: (id: number) => boolean;
     /** idx fetches and page batches in flight */
     get loading(): number;
     /** pages wanted and not yet started */

package/dist/engine/types.d.ts

@@ -3,6 +3,12 @@ export interface Drawn {
     id: number;
     factors: number;
 }
+/** world metres, min and max per axis, as World.extent */
+export interface Box {
+    e: readonly [number, number];
+    n: readonly [number, number];
+    h: readonly [number, number];
+}
 /** degrees; yaw clockwise from north, pitch negative looks down, fov vertical */
 export interface Camera {
     e: number;
@@ -53,3 +59,5 @@ export interface Stats {
     scale: number;
     loading: boolean;
 }
+/** how far the view has loaded, as stats() also gives it */
+export type Progress = Pick<Stats, 'planned' | 'missing' | 'loading'>;

package/dist/format/encode.d.ts

@@ -31,6 +31,14 @@ export declare function encodePack(pages: {
     row: PageRow;
     blob: Uint8Array;
 }[]): Uint8Array;
+/**
+ * world-ENU splats as the pack of one page, which a layer draws; origin is the south-west corner in
+ * whole metres that the pack's positions count from
+ */
+export declare function encodeLayer(splats: Splats): Promise<{
+    pack: Uint8Array;
+    origin: [number, number];
+}>;
 /** magic, version and the deflated body */
 export declare function wrap(body: Uint8Array, magic: string): Promise<Uint8Array>;
 export declare function encodeIdx(idx: Idx): Promise<Uint8Array>;

package/dist/format/idx.d.ts

@@ -1,6 +1,8 @@
 import type { Idx, PageRow, UnitKey } from './types.ts';
 /** a 52-byte page row at offset, as in .idx and the .pack table */
 export declare function rowAt(view: DataView, offset: number): PageRow;
+/** the rows of a pack's page table, through read(start, end) of a pack of size bytes; throws naming the fault */
+export declare function packRows(read: (start: number, end: number) => Promise<Uint8Array>, size: number): Promise<PageRow[]>;
 /** throws an Error naming the fault when the bytes are not a v1 .idx */
 export declare function parseIdx(bytes: Uint8Array): Promise<Idx>;
 /** u/<L>/<E>/<N>.<hash>.<ext>, relative to world.json */

package/dist/format/index.d.ts

@@ -1,9 +1,10 @@
 export * from './spec.ts';
 export type { Col, DecodedPage, Idx, PageRow, UnitKey, World, WorldRoot } from './types.ts';
 export { directory, parseWorld } from './world.ts';
-export { namedUnits, parseIdx, parseUnitPath, rowAt, unitPath } from './idx.ts';
+export { namedUnits, packRows, parseIdx, parseUnitPath, rowAt, unitPath } from './idx.ts';
 export { parseCol, sampleCol } from './col.ts';
 export { decodePage, pageHeader, readSplat } from './page.ts';
 export type { SplatValues } from './page.ts';
 export { inflate } from './inflate.ts';
 export { contentHash } from './hash.ts';
+export { encodeLayer, type Splats } from './encode.ts';

package/dist/format/index.js

@@ -1 +1 @@
-export { _ as BASE_PLANES, v as C0, y as C1, b as CHILD_BYTES, x as CLUSTER, S as COLOUR_WORDS, C as COL_CHANNELS, w as COL_HEADER, T as COL_MAGIC, E as DESCENDANT_BYTES, D as GEOMETRY_WORDS, O as IDX_HEADER, k as IDX_MAGIC, A as LEAF, j as PACK_MAGIC, M as PACK_TRAILER, N as PAGE_HEADER, P as PAGE_PARAMS, F as PAGE_SIDE, I as PARAMS, L as PLANES, R as PREFIX, z as ROW_BYTES, B as SH_COEFFS, V as VERSION, t as contentHash, n as decodePage, c as directory, g as inflate, u as namedUnits, i as pageHeader, o as parseCol, d as parseIdx, f as parseUnitPath, l as parseWorld, a as readSplat, p as rowAt, s as sampleCol, m as unitPath } from "../format-C3Vn0c2b.js";
+export { x as BASE_PLANES, S as C0, C as C1, w as CHILD_BYTES, T as CLUSTER, E as COLOUR_WORDS, D as COL_CHANNELS, O as COL_HEADER, k as COL_MAGIC, A as DESCENDANT_BYTES, j as GEOMETRY_WORDS, M as IDX_HEADER, N as IDX_MAGIC, P as LEAF, F as PACK_MAGIC, I as PACK_TRAILER, L as PAGE_HEADER, R as PAGE_PARAMS, z as PAGE_SIDE, B as PARAMS, V as PLANES, H as PREFIX, U as ROW_BYTES, W as SH_COEFFS, G as VERSION, o as contentHash, s as decodePage, f as directory, r as encodeLayer, b as inflate, m as namedUnits, h as packRows, c as pageHeader, u as parseCol, g as parseIdx, _ as parseUnitPath, p as parseWorld, l as readSplat, v as rowAt, d as sampleCol, y as unitPath } from "../format-CbtEy9NS.js";