@aethervtt/shard-terrain 0.0.1

package/dist/render.d.ts

@@ -0,0 +1,179 @@
+import { type AssetRef, type Entity, type Query, type World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import { Mesh } from '@aethervtt/shard-mesh';
+import { MaterialAsset } from '@aethervtt/shard-render';
+import type { App } from '@aethervtt/shard-runtime';
+import { Texture } from '@aethervtt/shard-texture';
+import { type ColliderChunk } from './colliders.js';
+import { type KernelGraph } from './kernel.js';
+import type { PlanetRuntime } from './planet.js';
+import { type NodeTree } from './quadtree.js';
+/**
+ * One render chunk: an entity drawing its range of an arena's vertex buffers, which a GPU job
+ * writes (or a collider chunk's vertices are copied into).
+ */
+interface Slot {
+    id: number;
+    kind: number;
+    mesh: Mesh;
+    meshRef: AssetRef;
+    entity: Entity;
+    /** Tree node it holds, or −1. */
+    node: number;
+    /** Edge lock bits (two per edge), fade, and InstanceData.x (fade + 2 × mask) now. */
+    bits: number;
+    fade: number;
+    packed: number;
+    /** The collider chunk whose vertices it holds (source 1). */
+    cpu: ColliderChunk | undefined;
+    /** Frame it was last rendered. */
+    used: number;
+    shown: boolean;
+    /** Where its vertices came from: 0 a GPU job, 1 a collider chunk (the collider's own numbers). */
+    source: number;
+    /** The index set drawn: quadrant mask + 16 × stitched edges (`chunkIndices`). */
+    indexKey: number;
+    /** A job for it is queued. */
+    pending: boolean;
+    /** Its GPU mesh holds this node at this planet version (−1: nothing valid). */
+    gpuNode: number;
+    gpuVersion: number;
+    /** Increments per job, so a late readback for an older job is ignored. */
+    jobId: number;
+    center: Float64Array;
+}
+/** A grid a job samples: its points, their origins per graph, and the kernel's uniform. */
+interface JobGrid {
+    count: number;
+    points: Float32Array;
+    originsH: Int32Array;
+    originsT: Int32Array;
+    originsM: Int32Array;
+    params: ArrayBuffer;
+}
+interface Job extends JobGrid {
+    slot: Slot;
+    id: number;
+    tree: NodeTree;
+    node: number;
+    kind: number;
+    version: number;
+    /** Only the normal tile (the slot shows a collider chunk's own vertices). */
+    normalsOnly: boolean;
+    /** The normal tile's grid (twice the vertex density), with tiles on. */
+    fine: JobGrid | undefined;
+}
+interface GridResources {
+    params: GPUBuffer;
+    points: GPUBuffer;
+    pointsSize: number;
+    values: GPUBuffer;
+    valuesSize: number;
+    origins: (GPUBuffer | undefined)[];
+    originSizes: number[];
+}
+interface GpuJobResources extends GridResources {
+    stats: GPUBuffer;
+    fine: GridResources;
+}
+/** GPU state of one planet's generation: kernels and per-job buffers (one set per job per frame). */
+interface PlanetGpu {
+    gpu: GpuContext;
+    generation: number;
+    resources: GpuJobResources[];
+    readbacks: GPUBuffer[];
+}
+/** Render-side state of one planet. */
+export declare class PlanetRender {
+    readonly slots: Slot[];
+    /** Vertex buffers shared by ARENA_SLOTS slots each, so chunks draw without rebinding. */
+    readonly arenas: Mesh[];
+    material: MaterialAsset;
+    materialRef: AssetRef<'Material'>;
+    ocean: MaterialAsset;
+    oceanRef: AssetRef<'Material'>;
+    biomeTexture: Texture | undefined;
+    biomeRef: AssetRef | undefined;
+    biomeVersion: number;
+    /** Every slot's normal tile (TILE_LAYER² layers of `tileGeometry` tiles), grown with the pool. */
+    tiles: Texture | undefined;
+    tilesRef: AssetRef | undefined;
+    jobs: Job[];
+    /** Each tree's walk stamp last frame (what was on screen then). */
+    lastStamp: number[];
+    readonly view: import("./quadtree.js").SelectionView;
+    /** The selecting camera in the origin frame (xyz) and pixels per radian / errorPixels (w). */
+    readonly camera: Float32Array<ArrayBuffer>;
+    hasCamera: boolean;
+    gpu: PlanetGpu | undefined;
+    /**
+     * The planet version on screen. After an edit (hot reload) every chunk keeps its old contents
+     * until the new kernels compile; then every visible chunk regenerates in one frame, so old and
+     * new never meet at a seam.
+     */
+    shownVersion: number;
+    /** The version whose generation pipelines are compiled. */
+    kernelsReady: number;
+    /** Jobs per generation pass (moving average), to turn the pass's GPU time into ms per job. */
+    jobsPerPass: number;
+    /** GPU milliseconds per job, from timestamp queries (0: not measured). */
+    msPerJob: number;
+    /** Kernel graphs, refreshed with the planet's version. */
+    kernels: {
+        version: number;
+        terrain: KernelGraph[];
+        ocean: KernelGraph[];
+    } | undefined;
+    stats: {
+        generated: number;
+        fromColliders: number;
+        readbacks: number;
+        evicted: number;
+        locks: number;
+        gpuFrames: number;
+        lastFrameJobs: number;
+    };
+    private jobCounter;
+    constructor(world: World);
+    nextJobId(): number;
+}
+export declare function renderOf(world: World, rt: PlanetRuntime): PlanetRender;
+/**
+ * Chooses each planet's chunks for the selecting camera (spec 0043): walks both quadtrees, gives
+ * new nodes pool slots and queues their GPU jobs within the frame's budget (nodes at collider depth
+ * near anchors show the collider chunk's own vertices instead, with no job), shows exactly the
+ * selected chunks, writes edge locks, and refreshes the planet's materials.
+ */
+export declare const selectChunks: import("@aethervtt/shard-core").SystemDef<{
+    cameras: Query;
+}>;
+/**
+ * A chunk's normal tile: its grid at twice the vertex density (2(n − 1) + 1 texels a side), and how
+ * many fit a layer. Off above 33 vertices per edge: those chunks are dense already, and uv1.x
+ * (grid point + n² × tile) must stay exact in f32.
+ */
+export declare function tileGeometry(n: number): {
+    size: number;
+    perRow: number;
+    perLayer: number;
+};
+/**
+ * Vertices a slot takes in its arena: its vertex count rounded up to 64, so every attribute's
+ * range starts at a multiple of 256 bytes (storage binding offsets must).
+ */
+export declare const slotStride: (vertexCount: number) => number;
+/**
+ * Debug shading (0 off, 1 biomes, 2 seams, 3 levels, 4 normals), for tests and tools. The
+ * terrain-biomes and terrain-lod overlays turn modes 1 and 3 on too.
+ */
+export declare const TerrainDebug: {
+    mode: number;
+    /** False shades from vertex normals even where normal tiles exist (comparisons, tests). */
+    normalTiles: boolean;
+};
+/** The render graph node: once per frame, every planet's GPU work before anything draws. */
+/** Adds the `terrain/generate` render graph node and the terrain shaders (once the GPU is up). */
+export declare function registerNode(app: App): void;
+/** Despawns a planet's chunk entities and frees its meshes and materials. */
+export declare function cleanupRender(world: World, rt: PlanetRuntime): void;
+export {};