@aethervtt/shard-sprite 0.0.1

package/dist/render.d.ts

@@ -0,0 +1,202 @@
+import { type AssetRef, type Entity, type World } from '@aethervtt/shard-core';
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { type CameraData, type NodeContext, type NodeDescriptor } from '@aethervtt/shard-render';
+import { type Texture } from '@aethervtt/shard-texture';
+/** Floats per sprite record: affine rows (12), uv rect (4), size (2), anchor (2), color, flags, pad. */
+export declare const SPRITE_FLOATS = 24;
+/** Sprites sharing a texture, blend, and space: one draw per contiguous run in sorted order. */
+export interface SpriteBatch {
+    index: number;
+    texture: Texture;
+    /** The normal map lit views sample (2D lighting), or null. */
+    normal: Texture | null;
+    blend: number;
+    space: number;
+    count: number;
+}
+/** A draw: `count` sprites of one batch from `first` in the sorted order. */
+interface Run {
+    batch: SpriteBatch;
+    first: number;
+    count: number;
+    layer: number;
+}
+/**
+ * Persistent sprite records: each Sprite entity owns a slot, rewritten when its components or
+ * transform change and uploaded in coalesced runs. Draw order is a sorted slot list, rebuilt only
+ * when a sort key or batch changes: layer, then depth (z, or −y), then batch, so sprites sharing
+ * a layer and depth group into as few draws as their textures allow.
+ */
+export declare class SpriteStore {
+    capacity: number;
+    high: number;
+    f32: Float32Array<ArrayBuffer>;
+    u32: Uint32Array<ArrayBuffer>;
+    /** Batch per slot, or -1 (hidden, freed, or waiting on an asset). */
+    batchOf: Int32Array<ArrayBuffer>;
+    keyHi: Uint32Array<ArrayBuffer>;
+    keyLo: Uint32Array<ArrayBuffer>;
+    entities: Float64Array<ArrayBuffer>;
+    private readonly free;
+    private dirty;
+    private dirtyLo;
+    private dirtyHi;
+    /** Slots waiting for a texture or atlas to load. */
+    readonly pending: Set<number>;
+    readonly batches: SpriteBatch[];
+    private readonly byTexture;
+    order: Uint32Array<ArrayBuffer>;
+    orderCount: number;
+    orderDirty: boolean;
+    readonly runs: Run[];
+    runCount: number;
+    /** Sprites per layer in the last sort. */
+    readonly perLayer: Map<number, number>;
+    /** Bytes of sprite records uploaded this frame. */
+    uploadedBytes: number;
+    sorts: number;
+    readonly records: GpuBuffer;
+    readonly orderBuffer: GpuBuffer;
+    private orderUploaded;
+    /** Hidden sprites per ECS table id, from the last visit. */
+    readonly tableSeen: number[];
+    private readonly gpu;
+    private generation;
+    constructor(gpu: GpuContext);
+    get live(): number;
+    private grow;
+    alloc(entity: Entity): number;
+    release(slot: number): void;
+    markDirty(slot: number): void;
+    /** The batch for a texture, normal map, blend, and space, made on first use. */
+    batchFor(texture: Texture, blend: number, space: number, normal?: Texture | null): SpriteBatch;
+    assign(slot: number, batch: number): void;
+    setKey(slot: number, hi: number, lo: number): void;
+    private sortA;
+    private sortB;
+    private readonly counts;
+    /** Sorts drawable slots by (keyHi, keyLo): four 16-bit LSD radix passes. Then builds runs. */
+    sort(): void;
+    /** Uploads dirty records in coalesced runs, and the order when it changed. */
+    upload(): void;
+}
+export declare const Sprites: import("@aethervtt/shard-core").ResourceDef<SpriteStore>;
+/**
+ * Assigns sprite slots, rewrites the records of sprites whose components or transform changed,
+ * retries sprites waiting on assets, re-sorts when a key changed, and uploads.
+ */
+export declare const prepareSprites: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+    atlasVersions: Map<unknown, number>;
+    textureVersions: Map<Texture, number>;
+}>;
+/** Frees a sprite's slot when the Sprite goes away (including on despawn). */
+export declare function observeSpriteRemovals(world: World): void;
+interface LayerGpu {
+    buffer: GpuBuffer;
+    chunksX: number;
+    chunksY: number;
+    cursor: number;
+    base: number;
+    params: GpuBuffer;
+}
+interface TilemapGpu {
+    entity: Entity;
+    data: unknown;
+    version: number;
+    chunkSize: number;
+    layers: LayerGpu[];
+    regions: GpuBuffer;
+    regionKey: string;
+    remap: GpuBuffer;
+    remapData: Uint32Array;
+    layer: number;
+    tileSize: [number, number];
+    affine: Float32Array;
+    /** World bounds per chunk per layer (minX, minY, minZ, maxX, maxY, maxZ). */
+    bounds: Float32Array[];
+    atlas: AssetRef<'TextureAtlas'> | null;
+    texture: Texture | undefined;
+    /** The atlas's normal map (2D lighting), or null. */
+    normal: Texture | null;
+    lit: boolean;
+}
+/** Tilemaps on the GPU, and chunk uploads in the last frame (for describe and tests). */
+export declare class TilemapStore {
+    readonly maps: Map<number, TilemapGpu>;
+    chunkUploads: number;
+    /** Per view: chunks drawn, chunks in total. */
+    readonly drawn: Map<string, {
+        visible: number;
+        total: number;
+        draws: number;
+    }>;
+}
+export declare const Tilemaps: import("@aethervtt/shard-core").ResourceDef<TilemapStore>;
+interface DrawCaches {
+    generation: number;
+    layouts?: {
+        view: GPUBindGroupLayout;
+        sprites: GPUBindGroupLayout;
+        tilemap: GPUBindGroupLayout;
+        texture: GPUBindGroupLayout;
+        /** Lit views: the texture group plus a normal map. */
+        litTexture: GPUBindGroupLayout;
+    };
+    /** A 1×1 flat normal for lit batches without a normal map. */
+    flatNormal?: GPUTextureView;
+    pipelines: Map<string, GPURenderPipeline>;
+    groups: Map<string, {
+        key: string;
+        group: GPUBindGroup;
+    }>;
+    views: Map<string, {
+        uniform: GpuBuffer;
+        chunks: GpuBuffer;
+    }>;
+    batchParams: Map<SpriteBatch, GpuBuffer>;
+    samplers?: {
+        linear: GPUSampler;
+        nearest: GPUSampler;
+    };
+}
+/** Pipelines, bind groups, and buffers of the sprite passes, per world. */
+export declare const SpriteDrawCaches: import("@aethervtt/shard-core").ResourceDef<DrawCaches>;
+/** World sprites into the picking pass (a PickDrawer): texels under half opacity don't pick. */
+export declare function drawSpritePicks(ctx: NodeContext, cam: CameraData): void;
+/** World sprites and tilemaps: after opaque 3D and the sky, before transparent 3D. */
+export declare function spriteNode(world: World): NodeDescriptor;
+/** Screen sprites: over the finished image, after tonemapping and anti-aliasing. */
+export declare function overlayNode(world: World): NodeDescriptor;
+/** The sprites section of `render.describe`. */
+export declare function describeSprites(world: World): {
+    sprites: number;
+    drawn: number;
+    pending: number;
+    batches: number;
+    drawCalls: number;
+    perLayer: {
+        [k: string]: number;
+    };
+    uploadedBytes: number;
+    sorts: number;
+    lighting: {
+        occluders: number;
+        tileLayers: number;
+        segments: number;
+        chunkRebuilds: number;
+        views: Record<string, import("./lights2d.js").LightViewStats>;
+    } | undefined;
+    tilemaps: {
+        maps: number;
+        chunkUploads: number;
+        views: {
+            [k: string]: {
+                visible: number;
+                total: number;
+                draws: number;
+            };
+        };
+    } | undefined;
+} | undefined;
+export {};