@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/instances.d.ts

@@ -1,12 +1,18 @@
 import { type World } from '@aethervtt/shard-core';
-import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import type { GpuBuffer, GpuContext } from '@aethervtt/shard-gpu';
 import type { Mesh } from '@aethervtt/shard-mesh';
 import { MaterialAsset } from './assets.js';
+import { DataStore } from './data-store.js';
 import { DeformStore } from './deform.js';
 export declare const InstanceSlot: import("@aethervtt/shard-core").ComponentDef<{
     readonly slot: import("@aethervtt/shard-core").FieldType<number, "u32">;
 }>;
 export declare const NotShadowCaster: import("@aethervtt/shard-core").ComponentDef<{}>;
+/**
+ * Tag: while hidden (Visibility), this mesh still casts shadows. A hidden roof keeps its interior
+ * dark (0067): camera views skip it, shadow views draw it.
+ */
+export declare const ShadowWhenHidden: import("@aethervtt/shard-core").ComponentDef<{}>;
 export declare const NotShadowReceiver: import("@aethervtt/shard-core").ComponentDef<{}>;
 export declare const Mesh3d: import("@aethervtt/shard-core").ComponentDef<{
     readonly mesh: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Mesh"> | null, "object">;
@@ -51,8 +57,22 @@ export declare const InstanceFlags: {
     readonly Skinned: 32;
     /** Morphed: the vertex stage adds morph target deltas. */
     readonly Morph: 64;
+    /** Hidden, but drawn in shadow views (ShadowWhenHidden); Visible is off. */
+    readonly ShadowOnly: 128;
+    /**
+     * May be cut away around a camera's reveal points (Cutaway, 0070). In the record's flags word
+     * it rides in bit 28 (`CUTAWAY_BIT`), above the layers and the LOD.
+     */
+    readonly Cutaway: 256;
 };
+/** Where `InstanceFlags.Cutaway` sits in the record's flags word (0070). */
+export declare const CUTAWAY_BIT: number;
+/** A slot's flags word: its flags (bits 0–7, Cutaway in 28) and render layers (8–23). */
+export declare function recordFlags(flags: number, layers: number): number;
 /** Record value for "no batch". LOD slots store `LOD_BIT | lodSet`. */
+/** The render layer mask's place in the flags word (bits 8–23; LOD rides in 24–27 when read). */
+export declare const LAYER_SHIFT = 8;
+export declare const LAYER_BITS: number;
 export declare const NO_BATCH = 4294967295;
 export declare const LOD_BIT = 2147483648;
 /** Visible-list entries: slot in the low 28 bits, LOD level in the top 4. */
@@ -85,6 +105,19 @@ export interface Batch {
     /** Per-cull scratch for forward-only slots in deferred views. */
     forwardScratch: Uint32Array;
     forwardCount: number;
+    /** The mesh version shadows last saw (cached shadows redraw when it changes, 0055). */
+    meshVersion: number;
+    /**
+     * Instances that can land in this batch and are Cutaway (0070). While any are, a view whose
+     * reveal points can cut one this frame draws it with the cutaway variant of its pipeline.
+     */
+    cutaway: number;
+    /**
+     * Drawn in the ground phase (0057): its slots have a GroundLayer, draw in (band, order) order
+     * after opaque geometry, and cast no shadows. Kept apart from the same mesh and material off
+     * the ground.
+     */
+    ground: boolean;
 }
 /** A Lod component's levels resolved to batches, shared by every entity with the same values. */
 export interface LodSet {
@@ -128,6 +161,12 @@ export interface CullParams {
     /** LOD state per slot for this view's camera; updated when `updateLod`. */
     lodState: Uint8Array | undefined;
     updateLod: boolean;
+    /** Render layers the view draws (0057): slots sharing no bit are culled first. Default: all. */
+    layers?: number;
+    /** Slots this view doesn't draw (ViewVisibility, 0070): a bit per slot. */
+    hidden?: Uint32Array | undefined;
+    /** Where those bits start in the GPU's hidden-set buffer, or NO_HIDDEN. */
+    hiddenBase?: number;
 }
 /**
  * World bounding sphere of a slot: the mesh's local sphere (from its bounds) through the slot's
@@ -167,7 +206,7 @@ export declare class InstanceStore {
      * Each slot's InstanceFlags, mirrored from its record: prepare compares against these every
      * frame, and reading them from the 64-byte records would touch a cache line per instance.
      */
-    flags: Uint8Array<ArrayBuffer>;
+    flags: Uint16Array<ArrayBuffer>;
     /** Hidden instances per ECS table id, from the last time prepare visited the table. */
     readonly tableHidden: number[];
     /** Batch index (>= 0), LOD set (-2 - index), or -1 (none), per slot. */
@@ -201,7 +240,7 @@ export declare class InstanceStore {
     private lastMoved;
     private lastMovedCount;
     private frame;
-    readonly prevBuffer: GpuBuffer;
+    readonly prevBuffer: DataStore;
     private readonly free;
     /** Slots waiting for their mesh or material to load. */
     readonly pending: Set<number>;
@@ -209,9 +248,24 @@ export declare class InstanceStore {
     /** Batches in draw order (sorted by pipeline, then material, then mesh). */
     readonly sorted: Batch[];
     private readonly byMesh;
+    private readonly byMeshGround;
+    /**
+     * Render layer mask per slot (0057); 1 for slots without RenderLayers. It also rides in bits
+     * 8–23 of the record's flags word, where the GPU culler reads it.
+     */
+    layers: Uint16Array<ArrayBuffer>;
+    /** Ground key per slot, (level, band, order) packed; NaN off the ground (0057, 0067). */
+    groundKeys: Float64Array<ArrayBuffer>;
     readonly lodSets: LodSet[];
     private readonly lodByKey;
     readonly defaultMaterial: MaterialAsset;
+    /**
+     * What stand-ins for failed meshes are drawn with (0061): matte gray, or magenta in a dev build
+     * (`DevMode`, read by prepareInstances).
+     */
+    readonly missingMaterial: MaterialAsset;
+    /** A development build: the missing material turns magenta. */
+    dev: boolean;
     /** Bytes of instance data uploaded this frame. */
     uploadedBytes: number;
     /** Slots with a batch and not hidden, and hidden ones: stats for GPU-culled views. */
@@ -219,11 +273,18 @@ export declare class InstanceStore {
     hiddenCount: number;
     /** Bumps when batches or LOD sets change shape (the GPU tables re-upload). */
     structureVersion: number;
+    /** Bumps when a slot is allocated or freed (hidden sets resolve again, 0070). */
+    slotEpoch: number;
+    /**
+     * Bumps when what casts shadows changes other than by moving: a slot's batch, its caster or
+     * visible flag, or a batch's mesh data. Cached shadow maps (0055) redraw when it moves.
+     */
+    shadowEpoch: number;
     /** Visible slot lists of every CPU-culled view this frame, concatenated. */
     visible: Uint32Array<ArrayBuffer>;
     visibleCount: number;
-    readonly instanceBuffer: GpuBuffer;
-    readonly visibleBuffer: GpuBuffer;
+    readonly instanceBuffer: DataStore;
+    readonly visibleBuffer: DataStore;
     private generation;
     private readonly gpu;
     bindGroup: GPUBindGroup | undefined;
@@ -240,6 +301,13 @@ export declare class InstanceStore {
     get live(): number;
     private grow;
     alloc(entity: number): number;
+    /** A slot's render layer mask (0057). What casts shadows in a view may change: cached maps redraw. */
+    setLayers(slot: number, mask: number): void;
+    /**
+     * A slot's ground key (0057): `groundKey(band, order, level)`, or NaN off the ground. Returns whether
+     * it moved on or off the ground (its batch must be resolved again).
+     */
+    setGround(slot: number, key: number): boolean;
     release(slot: number): void;
     private boundsDirty;
     private readonly cachedBounds;
@@ -265,11 +333,26 @@ export declare class InstanceStore {
     settleMoved(): void;
     /** Assigns a slot to a batch (>= 0), a LOD set (-2 - index), or nothing (-1). */
     assign(slot: number, assignment: number): void;
+    /** Adds `delta` to the cutaway count of every batch the slot can land in (0070). */
+    countCutaway(slot: number, delta: number): void;
+    /**
+     * Bumps `shadowEpoch` if any batch's mesh data changed since the last call (a structure chunk
+     * rebuilt in place). One compare per batch.
+     */
+    checkMeshVersions(): void;
+    /**
+     * Whether a visible caster that moved this frame touches the half-spaces `planes`, where it
+     * was or where it is now. Call after prepare. Skinned and morphed poses aren't moves; see
+     * `deforming`.
+     */
+    movedCasterIn(planes: Float32Array): boolean;
+    /** Whether skinned or morphed poses are being written this frame (their shadows move). */
+    get deforming(): boolean;
     /** A plain batch assignment. */
     setBatch(slot: number, index: number): void;
     private addMember;
     private removeMember;
-    batchFor(mesh: Mesh, material: MaterialAsset, meshGuid: string | undefined, materialGuid: string | undefined): Batch;
+    batchFor(mesh: Mesh, material: MaterialAsset, meshGuid: string | undefined, materialGuid: string | undefined, ground?: boolean): Batch;
     /** The LOD set for a Lod value and material (created on first use). Undefined if a mesh is missing. */
     lodSetFor(lod: LodValue, material: MaterialAsset, materialGuid: string | undefined, meshes: import('@aethervtt/shard-assets').AssetStore<Mesh, 'Mesh'>): LodSet | undefined;
     /** Orders batches by pipeline (set by the renderer: material type and variant). */
@@ -291,15 +374,37 @@ export declare class InstanceStore {
     private tBatches;
     private tDepths;
     private readonly tOrder;
+    private groundCount;
+    private gSlots;
+    private gBatches;
+    private gKeys;
+    private readonly gOrder;
     /**
      * CPU culling of every slot into `list` (and, for camera views, `transparent` back to front and
      * deferred `forwardOnly`). Same tests as the GPU culler: bounding sphere against the frustum,
      * visibility range, LOD level. `bounds` gets the union of what passed (cascade fitting). With
      * `transparentOnly`, only blended batches are culled (the GPU culls the rest).
      */
-    cullCpu(list: DrawList, params: CullParams, bounds?: Float32Array, transparent?: DrawList, forward?: Float32Array, forwardOnly?: DrawList, transparentOnly?: boolean): void;
+    cullCpu(list: DrawList, params: CullParams, bounds?: Float32Array, transparent?: DrawList, forward?: Float32Array, forwardOnly?: DrawList, transparentOnly?: boolean, ground?: DrawList, overlay?: DrawList): void;
     /** Transparent-only CPU cull over blended batches' members (LOD slots aren't members). */
     cullTransparentMembers(list: DrawList, params: CullParams, forward: Float32Array): void;
+    /**
+     * Ground-only CPU cull over ground batches' members (0057), for views the GPU culls: the ground
+     * list is always built on the CPU, in (band, order) order.
+     */
+    cullGroundMembers(list: DrawList, params: CullParams, overlay?: DrawList): void;
+    private pushGround;
+    /**
+     * Packs visible-list entries (a slot in the low 28 bits, 4 spare bits a pass may use, like an
+     * outline style) into `list`, one draw per batch: for passes that draw chosen slots (0057's
+     * outline mask). `batches` holds each entry's batch index. Skips entries whose batch isn't ready.
+     */
+    packEntries(list: DrawList, entries: Uint32Array, batches: Int32Array, count: number): void;
+    /**
+     * Sorts this cull's ground instances by (level, band, order), then batch; runs of a batch share a
+     * draw. With `overlay`, bands from OVERLAY_BAND up go there instead (0058).
+     */
+    private packGround;
     /**
      * CPU culling with positional arguments: planes, flag mask, bounds, transparent list, eye, view
      * direction, and the deferred forward-only list. LOD selects fresh (no hysteresis state).
@@ -335,8 +440,14 @@ export declare class InstanceStore {
 }
 /** Projected diameter of a sphere as a fraction of viewport height. Mirrors the cull shader. */
 export declare function lodSize(radius: number, distance: number, params: CullParams): number;
-export declare function createInstanceLayout(gpu: GpuContext): GPUBindGroupLayout;
+/** The instances bind group's layout: storage on the full tier, data textures on baseline. */
+export declare function createInstanceLayout(gpu: GpuContext, store: InstanceStore): GPUBindGroupLayout;
 export declare const Instances: import("@aethervtt/shard-core").ResourceDef<InstanceStore>;
+/**
+ * Ground draw order: level (−16..15, 0067), then band, then order. Exact in a double: 5 + 16 + 32
+ * bits.
+ */
+export declare function groundKey(band: number, order: number, level?: number): number;
 /** Present when skinningPlugin is installed: SkinnedMesh and MorphWeights deform what they draw. */
 export declare const DeformPath: import("@aethervtt/shard-core").ResourceDef<{
     installed: true;