@aethervtt/shard-render 0.1.0 → 0.2.0

package/dist/foliage.d.ts

@@ -0,0 +1,194 @@
+import { type AssetRef } from '@aethervtt/shard-core';
+import { type PerfBudgetsData } from '@aethervtt/shard-runtime';
+import { CoveredGpuTime, FoliageController } from './foliage-budget.js';
+/** A chunk of foliage to place: its ground (a patch grid) and its lattice. */
+export interface FoliageChunk {
+    /** Patch vertices per side (the ground's grid, e.g. a terrain chunk's 33). */
+    grid: number;
+    /** grid² positions (xyz), in the chunk's frame (see `FoliageLayer.setTransform`). */
+    positions: Float32Array;
+    /** grid² unit normals (xyz). */
+    normals: Float32Array;
+    /** grid² density factors in [0, 1]: masks and biomes, interpolated between vertices. */
+    density: Float32Array;
+    /** Global lattice coordinates of the chunk's first cell, and its lattice domain (a cube face). */
+    cell0: readonly [number, number];
+    domain: number;
+    /** Chance a cell holds an item (density × cell area, ≤ 1) and jitter as a fraction of a cell. */
+    accept: number;
+    jitter: number;
+    /**
+     * The chunk's origin in its surface's frame: up is radial from the surface's center (a planet).
+     * Undefined: up is the chunk frame's +Y (a mesh).
+     */
+    radial?: readonly [number, number, number];
+    /** Footprints kept clear (x, y, z, radius), in the chunk's frame: props' bounds. */
+    avoid?: Float32Array;
+}
+export interface FoliageLayerOptions {
+    label: string;
+    /** The meshes it draws (a rule's variants), all with `material`. */
+    meshes: AssetRef<'Mesh'>[];
+    /** Cumulative chance of each mesh, ending at 1. */
+    weights: ArrayLike<number>;
+    material: AssetRef<'Material'>;
+    /** The rule's seed: placement hashes it with each cell. */
+    seed: number;
+    /** Lattice cells per chunk side (instances a chunk holds: cells²). */
+    cells: number;
+    /** Distance from the camera at which it exists (m). */
+    range: number;
+    /** Casts shadows within this distance of the camera (0: never). */
+    shadowRange: number;
+    /** Scale range [min, max]. */
+    scale: readonly [number, number];
+    /** Up from radial (0) to the ground's normal (1). */
+    align: number;
+    /** Where thinning starts, as a fraction of `range` (default 0.5). */
+    thinFrom?: number;
+    /**
+     * Each mesh's lower levels of detail (fewer triangles), drawn farther out: `lods[m]` for
+     * `meshes[m]`. Grass clumps come with blades of 2 and 1 segments.
+     */
+    lods?: readonly (readonly AssetRef<'Mesh'>[])[];
+    /** Where each lower level begins, as fractions of `range` (default 0.3, 0.6). */
+    lodDistances?: readonly number[];
+}
+/** A placement waiting for this frame's dispatch. */
+interface Pending {
+    slot: number;
+    chunk: FoliageChunk;
+}
+interface ViewBuffers {
+    visible: GPUBuffer;
+    args: GPUBuffer;
+    classes: GPUBuffer;
+    counts: GPUBuffer;
+    params: GPUBuffer;
+    draw: GPUBuffer;
+    cullGroup: GPUBindGroup | undefined;
+    drawGroup: GPUBindGroup | undefined;
+    /** Capacity, drawable count and buffers' generation it was made for. */
+    capacity: number;
+    drawables: number;
+    generation: number;
+    /** Frame it was last culled, so draws skip views that weren't. */
+    culled: number;
+    /** Instance counts read back per (list, drawable), and whether a read is in flight. */
+    read_: Uint32Array;
+    reading: boolean;
+    readback: GPUBuffer | undefined;
+    /** Frame of the last read-back. */
+    read: number;
+}
+/**
+ * GPU-only instances of a rule's meshes (spec 0045): one storage buffer of 16-byte instances,
+ * `cells²` per chunk slot, placed by compute from each chunk's ground patch, culled per camera
+ * (frustum, distance, thinning) into indirect draws, drawn with the material's own hooks. No
+ * entities, and no per-instance CPU work.
+ */
+export declare class FoliageLayer {
+    readonly options: FoliageLayerOptions;
+    readonly perChunk: number;
+    /** What draws: each mesh's levels in order (`meshes[m]` then `lods[m]`), and where each mesh's start. */
+    readonly drawables: AssetRef<'Mesh'>[];
+    readonly levels: Uint32Array;
+    /** Chunks in the layer: their inputs (kept to place again after growth or device loss). */
+    readonly chunks: Map<number, FoliageChunk>;
+    /** Per slot: chunk → origin-relative world rows (12), bounds (min xyz, size xyz), active. */
+    private records;
+    private slots;
+    private readonly free;
+    readonly pending: Pending[];
+    /** Buffers, made in the place node. */
+    instances: GPUBuffer | undefined;
+    chunkBuffer: GPUBuffer | undefined;
+    meshInfo: GPUBuffer | undefined;
+    levelBuffer: GPUBuffer | undefined;
+    /** Slots the instance buffer holds, and its device generation. */
+    capacitySlots: number;
+    generation: number;
+    readonly views: Map<string, ViewBuffers>;
+    /** Largest mesh bounding radius (m, unscaled): culling's sphere. */
+    meshRadius: number;
+    disposed: boolean;
+    constructor(options: FoliageLayerOptions);
+    /** A free chunk slot. */
+    allocate(): number;
+    /** Places a chunk in a slot (on the GPU, in the next frame's place pass). */
+    setChunk(slot: number, chunk: FoliageChunk): void;
+    private queue;
+    /** Frees a slot: its instances stop drawing at once. */
+    removeChunk(slot: number): void;
+    /**
+     * The chunk's frame in the world, origin-relative, as an affine's three rows (12 floats,
+     * row-major: rotation and translation). Set it every frame the frame moves (an origin shift).
+     */
+    setTransform(slot: number, rows: ArrayLike<number>): void;
+    /** Chunk slots in use. */
+    get chunkCount(): number;
+    /** Instances this layer can hold. */
+    get capacity(): number;
+    /** The last read-back instance counts for a camera: in view, and casting shadows. */
+    visible(view: string): {
+        drawn: number;
+        shadows: number;
+    };
+    /**
+     * The last read-back counts per drawable for a camera (`drawables[d]`: a mesh or one of its
+     * LODs), in view and casting shadows.
+     */
+    visibleByDrawable(view: string): {
+        drawn: number[];
+        shadows: number[];
+    };
+    /** Slot records for the GPU this frame. */
+    get chunkRecords(): Float32Array;
+    get slotCount(): number;
+    /** Releases its GPU buffers (the layer stops drawing). */
+    dispose(): void;
+}
+/** Every foliage layer, drawn by `foliagePlugin`. */
+export declare class FoliageLayerSet {
+    readonly layers: Set<FoliageLayer>;
+    /** Density and range under the budget (0075, `FoliageBudget`): full detail without a target. */
+    readonly steer: FoliageController;
+    /** Foliage's GPU time a frame: every `gpu:foliage/*` pass (0074's covers rule). */
+    readonly gpuTime: CoveredGpuTime;
+    /** The scenario slice the target came from, kept until the scenario or budgets change. */
+    sliceFor: string | null;
+    sliceData: PerfBudgetsData | undefined;
+    sliceMs: number;
+    /** The shared GPU objects (pipelines, staging buffers), made on first use. */
+    gpu: FoliageGpu | undefined;
+    add(layer: FoliageLayer): FoliageLayer;
+    remove(layer: FoliageLayer): void;
+    /** Releases every layer and the shared buffers (the app is going away). */
+    dispose(): void;
+}
+export declare const FoliageLayers: import("@aethervtt/shard-core").ResourceDef<FoliageLayerSet>;
+interface FoliageGpu {
+    generation: number;
+    placeLayout: GPUBindGroupLayout;
+    cullLayout: GPUBindGroupLayout;
+    drawLayout: GPUBindGroupLayout;
+    place: GPUComputePipeline | undefined;
+    reset: GPUComputePipeline | undefined;
+    cull: GPUComputePipeline | undefined;
+    scan: GPUComputePipeline | undefined;
+    scatter: GPUComputePipeline | undefined;
+    params: GPUBuffer;
+    paramsSize: number;
+    patch: GPUBuffer;
+    patchSize: number;
+    avoid: GPUBuffer;
+    avoidSize: number;
+}
+/**
+ * GPU foliage (0045): layers of instances placed by compute from ground patches, culled per camera,
+ * drawn indirectly with their material's hooks in its own forward pass (`foliage/draw`, so its GPU
+ * time is its own: 0075), the G-buffer and the shadow passes. The scatter package feeds it; no
+ * entities are involved. `FoliageBudget` keeps its GPU time inside a target.
+ */
+export declare const foliagePlugin: import("@aethervtt/shard-runtime").Plugin;
+export {};