@aethervtt/shard-render 0.0.1

package/dist/instances.d.ts

@@ -0,0 +1,349 @@
+import { type World } from '@aethervtt/shard-core';
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import type { Mesh } from '@aethervtt/shard-mesh';
+import { MaterialAsset } from './assets.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<{}>;
+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">;
+}>;
+export declare const MeshMaterial: import("@aethervtt/shard-core").ComponentDef<{
+    readonly material: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Material"> | null, "object">;
+}>;
+export declare const MAX_LOD_LEVELS = 8;
+export declare const Lod: import("@aethervtt/shard-core").ComponentDef<{
+    readonly levels: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        mesh: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Mesh"> | null, "object">;
+        screenSize: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    }>[], "object">;
+    readonly hysteresis: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly bias: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const SkinnedMesh: import("@aethervtt/shard-core").ComponentDef<{
+    readonly skin: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Skin"> | null, "object">;
+    readonly joints: import("@aethervtt/shard-core").FieldType<(number | null)[], "object">;
+}>;
+export declare const MorphWeights: import("@aethervtt/shard-core").ComponentDef<{
+    readonly weights: import("@aethervtt/shard-core").FieldType<number[], "object">;
+}>;
+export declare const VisibilityRange: import("@aethervtt/shard-core").ComponentDef<{
+    readonly start: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly end: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const InstanceData: import("@aethervtt/shard-core").ComponentDef<{
+    readonly x: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly y: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+/** Floats per instance record: affine rows (12), batch, flags, visibility range, entity. */
+export declare const INSTANCE_FLOATS = 16;
+export declare const INSTANCE_BYTES: number;
+export declare const InstanceFlags: {
+    readonly Visible: 1;
+    readonly Caster: 2;
+    readonly Receiver: 4;
+    readonly Range: 8;
+    readonly Lod: 16;
+    /** Skinned: the vertex stage reads joint matrices; culling reads the slot's own sphere. */
+    readonly Skinned: 32;
+    /** Morphed: the vertex stage adds morph target deltas. */
+    readonly Morph: 64;
+};
+/** Record value for "no batch". LOD slots store `LOD_BIT | lodSet`. */
+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. */
+export declare const SLOT_MASK = 268435455;
+/** A LOD state entry with no level chosen yet. */
+export declare const LOD_UNSET = 255;
+/** All instances of one (mesh, material) pair: one draw per view. */
+export interface Batch {
+    index: number;
+    mesh: Mesh;
+    material: MaterialAsset;
+    meshGuid: string | undefined;
+    materialGuid: string | undefined;
+    /** Instances that can land in this batch (LOD slots count for every level of their set). */
+    count: number;
+    /** Whether the material's textures are ready this frame. */
+    ready: boolean;
+    /** Blended (alpha, additive, premultiplied): drawn after opaque, back to front, no shadows. */
+    transparent: boolean;
+    /** Can go through the G-buffer: standard lighting and not blended. */
+    deferrable: boolean;
+    /** Plain (non-LOD) slots in this batch, for culling one batch without scanning all slots. */
+    members: Uint32Array;
+    memberCount: number;
+    /** Where this batch's instances start in a view's visible region (GPU culling). */
+    region: number;
+    /** Per-cull scratch: slots that passed, before packing. */
+    scratch: Uint32Array;
+    scratchCount: number;
+    /** Per-cull scratch for forward-only slots in deferred views. */
+    forwardScratch: Uint32Array;
+    forwardCount: number;
+}
+/** A Lod component's levels resolved to batches, shared by every entity with the same values. */
+export interface LodSet {
+    index: number;
+    key: string;
+    batches: number[];
+    thresholds: Float32Array;
+    hysteresis: number;
+    bias: number;
+    count: number;
+}
+export interface DrawItem {
+    batch: Batch;
+    /** First entry in the visible buffer (the draw's firstInstance). */
+    first: number;
+    count: number;
+    /** Byte offset of the draw's indirect arguments (GPU culling), or -1 for a direct draw. */
+    indirect: number;
+}
+/** One view's culled draws: a camera, or a shadow map face. */
+export interface DrawList {
+    items: DrawItem[];
+    length: number;
+    visible: number;
+    culled: number;
+    hidden: number;
+    pending: number;
+    /** Index in the frame's GPU cull views, or -1 (CPU culled). */
+    cullView: number;
+}
+export declare function createDrawList(): DrawList;
+/** What a view culls with: frustum planes, the camera it measures distance and LOD from. */
+export interface CullParams {
+    planes: Float32Array | null;
+    require: number;
+    /** Where distances (visibility ranges, LOD) are measured from. */
+    eye: Float32Array | undefined;
+    /** Screen size of a sphere: r · lodScale / distance (perspective) or r · lodScale (ortho). */
+    lodScale: number;
+    orthographic: boolean;
+    /** LOD state per slot for this view's camera; updated when `updateLod`. */
+    lodState: Uint8Array | undefined;
+    updateLod: boolean;
+}
+/**
+ * World bounding sphere of a slot: the mesh's local sphere (from its bounds) through the slot's
+ * affine transform, radius scaled by the largest axis. Mirrors `slot_sphere` in the cull shader.
+ */
+export declare function slotSphere(out: Float32Array, f: Float32Array, o: number, bounds: Float32Array): Float32Array;
+/** Sphere against six planes (inside where n·p + d ≥ 0). */
+export declare function sphereInFrustum(planes: Float32Array, s: Float32Array): boolean;
+/**
+ * The LOD level for a size, from the previous level with hysteresis. Returns `count` (culled) when
+ * smaller than the last threshold. Mirrors `select_lod` in the cull shader.
+ */
+export declare function selectLod(size: number, thresholds: ArrayLike<number>, count: number, hysteresis: number, previous: number): number;
+type LodValue = {
+    levels: {
+        mesh: {
+            guid: string | undefined;
+        } | null;
+        screenSize: number;
+    }[];
+    hysteresis: number;
+    bias: number;
+};
+/**
+ * The persistent instance buffer. Each Mesh3d entity owns a slot holding its transform, batch (or
+ * LOD set), flags, and visibility range; only slots whose data changed are uploaded, in coalesced
+ * runs. Views cull slots on the CPU here, or on the GPU (`GpuCuller`), into per-view visible lists
+ * the vertex stage indexes through.
+ */
+export declare class InstanceStore {
+    capacity: number;
+    /** Slots in use or freed; slots >= high were never used. */
+    high: number;
+    f32: Float32Array<ArrayBuffer>;
+    u32: Uint32Array<ArrayBuffer>;
+    /**
+     * 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>;
+    /** 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. */
+    batchOf: Int32Array<ArrayBuffer>;
+    /** Index of the slot in its batch's member list, or -1. */
+    private memberIndex;
+    /** Visibility range per slot, as the GPU sees it (f16-rounded start, end). */
+    ranges: Float32Array<ArrayBuffer>;
+    meshRefs: ({
+        guid: string | undefined;
+    } | null)[];
+    materialRefs: ({
+        guid: string | undefined;
+    } | null)[];
+    /** Lod component value per slot, or null. */
+    lods: (LodValue | null)[];
+    private dirty;
+    private dirtyLo;
+    private dirtyHi;
+    /**
+     * Last frame's transform per slot (12 floats), for motion vectors. A slot that moved last frame
+     * but not this one catches up, so a stopped object has no velocity.
+     */
+    prev: Float32Array<ArrayBuffer>;
+    private prevDirty;
+    private prevLo;
+    private prevHi;
+    private movedFrame;
+    private moved;
+    private movedCount;
+    private lastMoved;
+    private lastMovedCount;
+    private frame;
+    readonly prevBuffer: GpuBuffer;
+    private readonly free;
+    /** Slots waiting for their mesh or material to load. */
+    readonly pending: Set<number>;
+    readonly batches: Batch[];
+    /** Batches in draw order (sorted by pipeline, then material, then mesh). */
+    readonly sorted: Batch[];
+    private readonly byMesh;
+    readonly lodSets: LodSet[];
+    private readonly lodByKey;
+    readonly defaultMaterial: MaterialAsset;
+    /** Bytes of instance data uploaded this frame. */
+    uploadedBytes: number;
+    /** Slots with a batch and not hidden, and hidden ones: stats for GPU-culled views. */
+    drawableCount: number;
+    hiddenCount: number;
+    /** Bumps when batches or LOD sets change shape (the GPU tables re-upload). */
+    structureVersion: number;
+    /** Visible slot lists of every CPU-culled view this frame, concatenated. */
+    visible: Uint32Array<ArrayBuffer>;
+    visibleCount: number;
+    readonly instanceBuffer: GpuBuffer;
+    readonly visibleBuffer: GpuBuffer;
+    private generation;
+    private readonly gpu;
+    bindGroup: GPUBindGroup | undefined;
+    private bound;
+    layout: GPUBindGroupLayout;
+    /** Set by the GPU culler: views it culls read their visible lists from this buffer. */
+    gpuVisible: GpuBuffer | undefined;
+    /** Bind group over `gpuVisible`, for draws of GPU-culled views. */
+    gpuBindGroup: GPUBindGroup | undefined;
+    private gpuBound;
+    /** Joint matrices, morph weights, and deform records of skinned and morphed slots. */
+    readonly deform: DeformStore;
+    constructor(gpu: GpuContext);
+    get live(): number;
+    private grow;
+    alloc(entity: number): number;
+    release(slot: number): void;
+    private boundsDirty;
+    private readonly cachedBounds;
+    /**
+     * The world bounds of every shadow caster (spheres), cached until an instance changes. GPU
+     * culling fits cascade depth ranges to it, having no CPU cull to take a union from.
+     */
+    casterBounds(out: Float32Array): Float32Array;
+    markDirty(slot: number): void;
+    /**
+     * Records a transform change: `from` is where the slot's record is now (copied to its previous
+     * transform), unless the slot is new, when both get `to`.
+     */
+    moveSlot(slot: number, g: ArrayLike<number>, offset: number, fresh: boolean): void;
+    /**
+     * The floating origin moved (spec 0040): adds `x, y, z` to every slot's current and previous
+     * translation, so this frame's moves compare against last frame's pose in the new frame and
+     * motion vectors stay continuous. Runs once per shift, not per frame.
+     */
+    shiftOrigin(x: number, y: number, z: number): void;
+    private markPrevDirty;
+    /** Slots that moved last frame but not this one: their previous transform catches up. */
+    settleMoved(): void;
+    /** Assigns a slot to a batch (>= 0), a LOD set (-2 - index), or nothing (-1). */
+    assign(slot: number, assignment: number): void;
+    /** 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;
+    /** 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). */
+    batchKey: (b: Batch) => number;
+    /** Draw order: grouped by pipeline, then material, then mesh, so switches stay rare. */
+    sortBatches(key?: (b: Batch) => number): void;
+    /** Materials and meshes in the order their first batch appeared (draw order within a pipeline). */
+    private readonly materialOrder;
+    private readonly meshOrder;
+    private compareBatches;
+    /** Writes a slot's visibility range (packed as two halves, as the GPU reads it). */
+    setRange(slot: number, start: number, end: number): void;
+    /** Uploads dirty slots in coalesced runs. Returns bytes written. */
+    upload(): number;
+    beginFrame(): void;
+    private transparentCount;
+    private forwardOnlyCount;
+    private tSlots;
+    private tBatches;
+    private tDepths;
+    private readonly tOrder;
+    /**
+     * 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;
+    /** Transparent-only CPU cull over blended batches' members (LOD slots aren't members). */
+    cullTransparentMembers(list: DrawList, params: CullParams, forward: Float32Array): void;
+    /**
+     * 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).
+     */
+    cull(list: DrawList, planes: Float32Array | null, require?: number, bounds?: Float32Array, transparent?: DrawList, eye?: Float32Array, forward?: Float32Array, forwardOnly?: DrawList): void;
+    private pushTransparent;
+    /** Sorts this cull's transparent instances back to front; runs of one batch share a draw. */
+    private packTransparent;
+    private reserve;
+    private item;
+    /**
+     * False only when every instance of a small batch is hidden (Visibility), so views skip its
+     * draw. The GPU culler otherwise issues one indirect draw per batch, empty or not: a planet's
+     * pooled chunks are mostly hidden, and empty draws still cost their binds and calls.
+     */
+    anyVisible(batch: Batch): boolean;
+    private nearKeys;
+    private nearItems;
+    /**
+     * Reorders a camera's opaque draws nearest first within each run that shares a pipeline and
+     * material, so the depth test rejects hidden fragments before they're shaded (overdraw on heavy
+     * shaders, like terrain, costs the most). Pipeline and material switches stay as few as before.
+     * A batch's distance is its first member's origin: exact for single-instance draws (terrain
+     * chunks), a fair guess for instanced ones. No allocation after warm-up: one typed-array sort of
+     * packed keys (run, log distance, index).
+     */
+    orderNearFirst(list: DrawList, eye: ArrayLike<number>): void;
+    /** Copies each batch's scratch into the shared visible array, in draw order. */
+    pack(list: DrawList): void;
+    private createBindGroup;
+    /** Uploads this frame's CPU visible lists and (re)builds the bind groups the vertex stage reads. */
+    finishFrame(): void;
+}
+/** 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;
+export declare const Instances: import("@aethervtt/shard-core").ResourceDef<InstanceStore>;
+/** Present when skinningPlugin is installed: SkinnedMesh and MorphWeights deform what they draw. */
+export declare const DeformPath: import("@aethervtt/shard-core").ResourceDef<{
+    installed: true;
+}>;
+export declare const prepareInstances: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;
+/** Frees a Mesh3d's slot when the component goes away (including on despawn). */
+export declare function observeInstanceRemovals(world: World): void;
+export {};