@aethervtt/shard-structure 0.0.0-stage → 0.1.0

package/dist/interior.d.ts

@@ -0,0 +1,159 @@
+import { LINK_X, LINK_Z } from '@aethervtt/shard-render';
+import type { FloorShape } from './geometry.js';
+export { LINK_X, LINK_Z };
+/** The field's grid: origin (x, z) of texel (0, 0)'s corner, texel size, size in texels. */
+export interface FieldGrid {
+    ox: number;
+    oz: number;
+    texel: number;
+    width: number;
+    height: number;
+}
+/** A rectangle of texels, [x0, x1) × [z0, z1). */
+export interface TexelRect {
+    x0: number;
+    z0: number;
+    x1: number;
+    z1: number;
+}
+/** A world rectangle, [minX, maxX] × [minZ, maxZ]. */
+export interface Bounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/** A barrier for the field and the rows: a segment, its top (y), and its wall's thickness. */
+export interface Barrier {
+    ax: number;
+    az: number;
+    bx: number;
+    bz: number;
+    /** World y of its top, for wall-blocked lights (a window's sill, a low wall's top). */
+    top: number;
+    thickness: number;
+    /** Blocks the field's spill (a gap for the field may still block low for the rows). */
+    field: boolean;
+}
+/** A cover: a slab outline (holes included) whose surface stands over the layer. */
+export interface Cover {
+    shape: FloorShape;
+    /** Rings of closed hatches: they cover though their hole is in the shape. */
+    closed: readonly number[];
+}
+/** One level's field: cover, links and visibility per texel. */
+export declare class FieldLayer {
+    /** Cover top y over the layer's base, per texel; Infinity where uncovered. */
+    cover: Float32Array;
+    /** LINK_X | LINK_Z: flux to the +x and +z neighbour is blocked. */
+    links: Uint8Array;
+    /** The solve's visibility, before the blur: a region re-solve starts from it. */
+    value: Float32Array;
+    /** What uploads: blurred visibility, links and cover, packed (see `packTexel`). */
+    packed: Uint32Array;
+    /** The y cover heights count from: the level's elevation (the ground level's is 0). */
+    base: number;
+    constructor(width: number, height: number);
+}
+/** Scratch shared by solves: reused, grown when a solve needs more. */
+export declare class SolveScratch {
+    blurred: Float32Array<ArrayBuffer>;
+    /** Per texel: neighbours reached, and 1 / (their count + κ). */
+    mask: Uint8Array<ArrayBuffer>;
+    inv: Float32Array<ArrayBuffer>;
+    /** Per tile: how far its texels moved in the last sweep, and in this one. */
+    moved: Float32Array<ArrayBuffer>;
+    movedNext: Float32Array<ArrayBuffer>;
+    crossings: Float64Array<ArrayBuffer>;
+    /** Aggregation (the coarse pass): aggregate per texel, and per aggregate its sums. */
+    agg: Int32Array<ArrayBuffer>;
+    aggValue: Float64Array<ArrayBuffer>;
+    aggDiag: Float64Array<ArrayBuffer>;
+    aggRhs: Float64Array<ArrayBuffer>;
+    /** Coarse couplings as CSR. */
+    rowStart: Int32Array<ArrayBuffer>;
+    colIndex: Int32Array<ArrayBuffer>;
+    weight: Float64Array<ArrayBuffer>;
+    stack: Int32Array<ArrayBuffer>;
+    ensure(n: number): void;
+}
+/** Texels of `rect` clipped to the grid. */
+export declare function clipRect(grid: FieldGrid, r: TexelRect): TexelRect;
+/** The texels whose centres lie within `b` grown by `grow` metres, clipped to the grid. */
+export declare function texelsOf(grid: FieldGrid, b: Bounds, grow: number): TexelRect;
+/**
+ * Covers the texels of `rect` whose centres are inside `cover` (even-odd over its rings, so
+ * holes stay open; closed hatches cover again): each keeps the lowest cover top over `base`.
+ */
+export declare function rasterCover(grid: FieldGrid, layer: FieldLayer, cover: Cover, rect: TexelRect, base: number, scratch: SolveScratch): void;
+/**
+ * Marks the links of `rect`'s texels (each texel owns its links to +x and +z) that a barrier
+ * crosses: the segment meets the line between the two centres, ends included, so walls meeting
+ * at a corner leave no crack.
+ */
+export declare function rasterBarrier(grid: FieldGrid, layer: FieldLayer, s: Barrier, rect: TexelRect): void;
+/** Clears `rect`'s cover and links, before they're rasterized again. */
+export declare function clearRect(grid: FieldGrid, layer: FieldLayer, rect: TexelRect): void;
+/** κ = h² / L²: the screening term of a texel h wide for spill reach L. */
+export declare function screening(texel: number, reach: number): number;
+/** SOR's relaxation for the screened Laplacian: optimal for its slowest mode. */
+export declare function relaxation(kappa: number): number;
+/** Options of a solve. */
+export interface SolveOptions {
+    /** Spill reach (m). */
+    reach: number;
+    /** Stop once no texel moves more than this in a sweep. */
+    tolerance?: number;
+    /** At most this many sweeps at the texel size. */
+    maxSweeps?: number;
+    /** Start from an aggregated coarse solve (whole-field solves); a region starts from its old values. */
+    coarse?: boolean;
+    /** Coarse cells, in texels: about 1 m. */
+    coarseCells?: number;
+}
+/** What a solve did. */
+export interface SolveReport {
+    texels: number;
+    sweeps: number;
+    coarseSweeps: number;
+}
+/**
+ * Solves `rect` of a layer: uncovered texels are 1, covered ones the screened diffusion, with
+ * texels outside the rect held at their values. Then blurs and packs `rect` grown by a texel
+ * (`packRect` reads it back). Whole-field solves start from a coarse pass over ~1 m aggregates;
+ * a region starts from the values it had, which an edit changes only near it.
+ */
+export declare function solveRect(grid: FieldGrid, layer: FieldLayer, rect: TexelRect, options: SolveOptions, scratch: SolveScratch): SolveReport;
+/**
+ * Blurs `rect` of the solved values once (each covered texel with the neighbours it isn't walled
+ * off from, itself weighted 4) and packs it for upload. Uncovered texels stay 1.
+ */
+export declare function packRect(grid: FieldGrid, layer: FieldLayer, rect: TexelRect, scratch: SolveScratch): void;
+/** A field texel as uploaded: visibility (14 bits) over the link bits, the cover code above. */
+export declare function packTexel(visibility: number, links: number, cover: number): number;
+/** The uploaded visibility of a packed texel. */
+export declare function unpackVisibility(texel: number): number;
+/**
+ * A direction's place around the circle, 0 to 1 from −x counter-clockwise (+x at ½): the pseudo-
+ * angle `interior_bin` in the lighting stage reads bins by (one division, not an atan2).
+ */
+export declare function binOf(x: number, z: number): number;
+/** Scratch for `buildRow`. */
+export declare class RowScratch {
+    distance: Float64Array<ArrayBuffer>;
+    top: Float64Array<ArrayBuffer>;
+    ensure(bins: number): void;
+}
+/** How far behind a barrier's centreline a receiver counts as behind it: a quarter of its thickness, at most 5 cm. */
+export declare function rowBias(thickness: number): number;
+/**
+ * A light's polar row: per bin, the distance to the nearest barrier along the bin's direction
+ * within `range` (plus its bias), and that barrier's top, packed for upload (`ROW_*`). Only the
+ * first `count` barriers are tested: the caller gathers the ones near the light.
+ */
+export declare function buildRow(out: Uint32Array, x: number, y: number, z: number, range: number, barriers: readonly Barrier[], count: number, scratch: RowScratch): void;
+/** A row bin's barrier distance (Infinity for none) and top (relative to the light's y). */
+export declare function unpackBin(bin: number): {
+    distance: number;
+    top: number;
+};