@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/meshes.d.ts

@@ -0,0 +1,411 @@
+import { type Component, type World } from '@yali-engine/core';
+import { TextureRef } from './textures.ts';
+/** Floats per interleaved vertex in the geometry pool (position, normal, uv), for decode workers. */
+export declare const MESH_VERTEX_FLOATS = 8;
+/** Most LODs a mesh may have (LOD 0 included; `shaders/scene/instance.wesl` `MAX_LODS`). */
+export declare const MAX_LODS = 8;
+/** The mesh id of the unit cube every `MeshStore` starts with. */
+export declare const CUBE_MESH = 0;
+/** A coarser level of detail: indices into the same vertices, and its mesh-space error. */
+export interface MeshLod {
+    readonly indices: Uint32Array;
+    /** How far, in mesh units, this LOD's surface may be from the full mesh's. */
+    readonly error: number;
+}
+/**
+ * One mesh's geometry, as a loader hands it over: separate attributes (the glTF primitive
+ * shape), or already interleaved by a decode worker (8 floats per vertex: position,
+ * normal, uv), which keeps the main-thread step to storing a reference. `lods` are the
+ * coarser levels, finest first (LOD 0 is `indices`).
+ */
+export type MeshData = ({
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly uvs?: Float32Array | null;
+    readonly indices: Uint32Array;
+} | {
+    readonly vertices: Float32Array;
+    readonly indices: Uint32Array;
+}) & {
+    readonly lods?: readonly MeshLod[];
+    readonly state?: MeshState;
+    /**
+     * A skinned mesh's skin stream (ADR-0088): per vertex 4 joint slots (u16) then 4 weights
+     * (unorm16, summing to 65535 or all 0 for a vertex drawn unskinned), `packSkin`'s layout. A
+     * skinned mesh lives in the skinned pool and draws with the skinned draw classes.
+     */
+    readonly skin?: Uint16Array;
+    /** The culling radius about its bounds' centre, when the vertices move past them (GPU cloth, ADR-0101). */
+    readonly radius?: number;
+    /**
+     * Its clusters, packed ahead of time (`yali convert --clusters`, ADR-0121): `packClusters`' output
+     * over these vertices and whether it is a LOD hierarchy. `meshlets()` uses them instead of
+     * building (when `lod` matches its own).
+     */
+    readonly clusters?: PrebuiltClusters;
+    /**
+     * Its cluster hierarchy in streaming pages (`yali convert --clusters --stream`, ADR-0134): these
+     * vertices and indices are its root pages' mesh; `meshlets({ lod: true })` streams the rest.
+     */
+    readonly pages?: StreamedClusters;
+    /**
+     * Vertices to reserve in its block, at least its own (ADR-0134: room for streamed pages after its
+     * root vertices; `writeVertices` fills it). Its bounds are its own vertices'.
+     */
+    readonly vertexCapacity?: number;
+};
+/**
+ * A mesh's cluster hierarchy in streaming pages (ADR-0134), as `YALI_cluster_pages` carries it, and
+ * the absolute URL of the file with its pages past the roots.
+ */
+export interface StreamedClusters {
+    readonly words: Uint32Array;
+    readonly pages: Uint32Array;
+    readonly roots: number;
+    readonly localIds: number;
+    readonly triangleBytes: number;
+    readonly corners: number;
+    readonly slotVertices: number;
+    readonly rootData: Uint8Array;
+    /** The pages file; a page at table offset `o` is at `base + o - rootData.length` in it. */
+    readonly url: string;
+    readonly base: number;
+}
+/** A mesh's clusters packed ahead of time (ADR-0121): `PackedClusters` and whether they are a LOD hierarchy. */
+export interface PrebuiltClusters {
+    readonly lod: boolean;
+    readonly words: Uint32Array;
+    readonly vertices: Uint32Array;
+    readonly triangles: Uint8Array;
+    readonly corners: number;
+}
+/** Bytes per vertex of the skin stream: 4 × u16 joints, 4 × unorm16 weights. */
+export declare const SKIN_STREAM_BYTES = 16;
+/**
+ * Packs 4 joints and 4 weights per vertex (glTF `JOINTS_0` / `WEIGHTS_0`, weights summing to 1)
+ * into the skin stream's layout: u16 joints, then the weights as unorm16 rounded so they sum to
+ * exactly 65535 (the largest absorbs the rounding).
+ */
+export declare function packSkin(joints: ArrayLike<number>, weights: ArrayLike<number>, count: number): Uint16Array;
+/**
+ * How a mesh draws (ADR-0081): its material's alpha mode (glTF `alphaMode`; the cutoff is the
+ * material's `alphaCutoff`) and whether its back faces draw (glTF `doubleSided`). Per mesh, not
+ * per instance: draws are grouped per mesh, and a glTF primitive has one material.
+ */
+export interface MeshState {
+    readonly alpha?: 'opaque' | 'mask' | 'blend';
+    readonly doubleSided?: boolean;
+}
+/** The rigid draw classes: opaque, mask, blend (last), each single then double-sided. */
+export declare const RIGID_CLASSES = 6;
+/**
+ * Draw classes: the six rigid ones, then the same six skinned (ADR-0088: `+ SKINNED_CLASS`),
+ * which read the skinned pool and the palette.
+ */
+export declare const DRAW_CLASSES = 12;
+/** What a skinned mesh's class adds to its rigid class. */
+export declare const SKINNED_CLASS = 6;
+/** A mesh state's draw class: alpha mode × 2 + double-sided, + `SKINNED_CLASS` when skinned. Class 0 is opaque single-sided rigid. */
+export declare function drawClassOf(state?: MeshState, skinned?: boolean): number;
+/** Whether a draw class blends (no depth writes, no shadow casting, drawn last). */
+export declare const isBlendClass: (c: number) => boolean;
+/** Whether a draw class is skinned (reads the skinned pool and the palette). */
+export declare const isSkinnedClass: (c: number) => boolean;
+/** One LOD's placement in the index pool. */
+export interface LodRange {
+    readonly firstIndex: number;
+    readonly count: number;
+    readonly error: number;
+}
+/** A stored mesh. */
+export interface MeshEntry {
+    /** First vertex of this mesh in its vertex pool (the skinned pool for a skinned mesh). */
+    readonly baseVertex: number;
+    /** Whether it is skinned (its vertices are in the skinned pool, with a skin stream). */
+    readonly skinned: boolean;
+    /** LOD 0 first. */
+    lods: LodRange[];
+    /** Bounding sphere in mesh space. */
+    readonly center: readonly [number, number, number];
+    readonly radius: number;
+    /** `drawClassOf(state)` (ADR-0081). */
+    readonly drawClass: number;
+}
+/** A block of data waiting for (or already in) a GPU pool. */
+interface Block<T> {
+    readonly data: T;
+    /** Offset in the pool, in elements (vertices or indices). */
+    readonly at: number;
+}
+/**
+ * Every mesh the app has loaded, kept on the CPU too (ADR-0047): the GPU geometry pool is
+ * rebuilt from it after device loss (DESIGN.md §3). A mesh id is its index here, and what
+ * the `render.Mesh` component stores. Mesh 0 is a unit cube (`CUBE_MESH`).
+ *
+ * Geometry is append-only: vertex and index blocks are placed one after another, so a
+ * renderer uploads only what was added since it last looked (`vertexBlocks`,
+ * `indexBlocks`). LODs added later (`addLods`) are new index blocks over the same vertices.
+ */
+export declare class MeshStore {
+    #private;
+    readonly entries: MeshEntry[];
+    readonly vertexBlocks: Block<Float32Array>[];
+    readonly indexBlocks: Block<Uint32Array>[];
+    /** The skinned pool (ADR-0088): vertices in the same layout, and the skin stream beside them. */
+    readonly skinnedVertexBlocks: Block<Float32Array>[];
+    readonly skinBlocks: Block<Uint16Array>[];
+    /** Bumped on every change, so a renderer knows it has something to upload. */
+    version: number;
+    /**
+     * Meshes whose vertices were rewritten (`updateVertices`), by id: the serial of the latest
+     * write, the pool and where in it. A renderer uploads those newer than the last it saw.
+     */
+    readonly vertexWrites: Map<number, {
+        serial: number;
+        skinned: boolean;
+        at: number;
+        data: Float32Array;
+    }>;
+    /**
+     * Vertex ranges written into reserved room (`writeVertices`, streamed pages, ADR-0134): not motion,
+     * so they do not make the pool dynamic. The renderer uploads those newer than the last it saw and
+     * sets `rangesSeen`; older ones are dropped on the next write.
+     */
+    readonly rangeWrites: {
+        serial: number;
+        at: number;
+        data: Float32Array;
+    }[];
+    rangesSeen: number;
+    /**
+     * Meshes whose finest LOD's indices were rewritten (`updateIndices`, ADR-0117), by id: the serial
+     * of the latest write (shared with the vertex writes), where in the index pool, and the indices.
+     */
+    readonly indexWrites: Map<number, {
+        serial: number;
+        at: number;
+        data: Uint32Array;
+    }>;
+    constructor();
+    /** Interleaves (if needed) and stores a mesh; returns its id. Main thread, inside the upload budget. */
+    add(m: MeshData): number;
+    /**
+     * Rewrites mesh `id`'s vertices (the same count, `MESH_VERTEX_FLOATS` each): a morphed pose
+     * (ADR-0088). The stored copy changes too, so a pool rebuilt after device loss has it. Its
+     * bounds stay those it was added with.
+     */
+    updateVertices(id: number, vertices: Float32Array): void;
+    /**
+     * Writes `vertices` (`MESH_VERTEX_FLOATS` each) into mesh `id`'s block from its vertex `first`: room
+     * it reserved (`vertexCapacity`), for streamed cluster pages (ADR-0134). Not motion: the pool stays
+     * static. The stored copy changes too.
+     */
+    writeVertices(id: number, first: number, vertices: Float32Array): void;
+    /**
+     * Rewrites mesh `id`'s finest LOD's indices (the same count): a CPU cloth's triangles after a tear
+     * split them (ADR-0117). The stored copy changes too (a pool rebuilt after device loss has it, and
+     * picking sees it). Its coarser LODs stay as they were.
+     */
+    updateIndices(id: number, indices: Uint32Array): void;
+    /**
+     * Mesh `id`'s CPU geometry: interleaved vertices (`MESH_VERTEX_FLOATS` each, position first),
+     * its finest LOD's indices, its skin stream (null when rigid) and its prebuilt clusters (or null). Null for an unknown id.
+     */
+    geometry(id: number): {
+        readonly vertices: Float32Array;
+        readonly indices: Uint32Array;
+        readonly skin: Uint16Array | null;
+        readonly clusters: PrebuiltClusters | null;
+        readonly pages: StreamedClusters | null;
+    } | null;
+    /** The serial of the latest `updateVertices` or `updateIndices` (0: none yet). */
+    get writeSerial(): number;
+    /**
+     * Adds coarser LODs to mesh `id` (finest first, after the ones it has): for a model
+     * whose file carried none, simplified on a decode worker after LOD 0 was already drawn.
+     */
+    addLods(id: number, lods: readonly MeshLod[]): void;
+    get vertexCount(): number;
+    /** Vertices in the skinned pool. */
+    get skinnedVertexCount(): number;
+    get indexCount(): number;
+    /** CPU bytes held (vertices + indices). */
+    get bytes(): number;
+}
+/**
+ * Where a material's texture comes from: a texture already in the store, or anything with
+ * `get()` returning one (an asset `Handle` from a `.ktx2` loader, read again whenever the
+ * textures change, so a loading texture appears when it is ready). A handle whose state is
+ * `Failed` draws the magenta checker of DESIGN.md §9.
+ */
+export type TextureSource = TextureRef | {
+    get(): TextureRef | null;
+    readonly state?: string;
+};
+/**
+ * A compiled node material's shader (`@yali-engine/tsl`'s `CompiledMaterial`, from the `materials`
+ * build step; ADR-0064): a WGSL surface function and where its parameters sit.
+ */
+export interface MaterialShader {
+    readonly name: string;
+    readonly entry: string;
+    readonly wgsl: string;
+    readonly hash: string;
+    readonly params: readonly {
+        readonly name: string;
+        readonly lanes: number;
+        readonly offset: number;
+        readonly default: readonly number[];
+    }[];
+}
+/** One material: the standard one (shader 0), or a node material's shader with its parameters. */
+export interface MaterialData {
+    /** Linear RGBA (the standard material multiplies it in; a node material may ignore it). */
+    readonly baseColor: readonly [number, number, number, number];
+    /** An sRGB colour texture, multiplied with `baseColor` (sampled at the mesh's first UV set). */
+    readonly baseColorMap?: TextureSource;
+    /** A linear tangent-space normal map (used by PBR lighting, M2.5). */
+    readonly normalMap?: TextureSource;
+    /** A linear ORM map: occlusion (R), roughness (G), metalness (B), as glTF packs them. */
+    readonly ormMap?: TextureSource;
+    /** An sRGB emissive texture, multiplied with `emissive`. */
+    readonly emissiveMap?: TextureSource;
+    /** Standard material: 0–1 (default 0). */
+    readonly metalness?: number;
+    /** Standard material: 0–1 (default 1). */
+    readonly roughness?: number;
+    /** Standard material: linear emitted colour (default black). */
+    readonly emissive?: readonly [number, number, number];
+    /** Standard material: scale of the normal map's X and Y (glTF `normalTexture.scale`, default 1). */
+    readonly normalScale?: number;
+    /** Standard material: how much the ORM map's occlusion applies (glTF `occlusionTexture.strength`, default 1). */
+    readonly occlusionStrength?: number;
+    /**
+     * Standard material: the alpha below which a MASK mesh discards a fragment (glTF
+     * `alphaCutoff`, default 0.5). Whether a mesh masks or blends is its `MeshState` (ADR-0081).
+     */
+    readonly alphaCutoff?: number;
+    /** Standard material, KHR_materials_clearcoat: the coat's strength, 0–1 (default 0: none). */
+    readonly clearcoat?: number;
+    /** The coat's roughness, 0–1 (default 0). */
+    readonly clearcoatRoughness?: number;
+    /** Linear maps: the coat's strength in R, its roughness in G (glTF's channels). */
+    readonly clearcoatMap?: TextureSource;
+    readonly clearcoatRoughnessMap?: TextureSource;
+    /**
+     * Standard material, KHR_materials_transmission: the share of light passing through, 0–1
+     * (default 0). Drawn as a blended mesh (its `MeshState`), achromatic and unrefracted (ADR-0093).
+     */
+    readonly transmission?: number;
+    /** A linear map of it in R. */
+    readonly transmissionMap?: TextureSource;
+    /** Standard material, KHR_materials_sheen: the sheen's linear colour (default black: none) and roughness. */
+    readonly sheenColor?: readonly [number, number, number];
+    readonly sheenRoughness?: number;
+    /** An sRGB map of the sheen colour. */
+    readonly sheenColorMap?: TextureSource;
+    /** Index of refraction (KHR_materials_ior, default 1.5): how a transmissive surface bends what is behind it. */
+    readonly ior?: number;
+    /** KHR_materials_volume (ADR-0099): the thickness the light travels through (mesh units; 0: thin-walled, no bend). */
+    readonly thickness?: number;
+    /** The volume's thickness map: its G channel times `thickness` (glTF `thicknessTexture`, ADR-0125). */
+    readonly thicknessMap?: TextureSource;
+    /** KHR_materials_dispersion (ADR-0125): how far the colours part when refracted (20 / the Abbe number; 0: none). */
+    readonly dispersion?: number;
+    /**
+     * Which transparent layer the surface draws in (ADR-0125, default 0). Layer 1 is drawn after a second
+     * copy of the scene, so its transmission sees layer 0's glass: give it to glass that is in front of other
+     * glass. Only on devices with the opaque copy (the GPU cull's storage path); elsewhere one pass draws both.
+     */
+    readonly transmissionLayer?: 0 | 1;
+    /**
+     * A blended surface's motion (ADR-0133, default false): TAA and motion blur see it move where it is at
+     * least as opaque as its `alphaCutoff` (0.5 unless set), instead of seeing what is behind it. For
+     * mostly opaque blended surfaces (a fading character, a solid-looking leaf card drawn blended); smoke and
+     * glass should keep what is behind them, as by default.
+     */
+    readonly blendMotion?: boolean;
+    /** The colour white light becomes after `attenuationDistance` inside (default white, Infinity: none). */
+    readonly attenuationColor?: readonly [number, number, number];
+    readonly attenuationDistance?: number;
+    /** A node material's shader (`materials.registerShader`); 0 or absent is the standard material. */
+    readonly shader?: number;
+    /** A node material's uniforms by name; unset ones take the shader's defaults. */
+    readonly params?: Readonly<Record<string, number | readonly number[]>>;
+}
+/** Most materials in the uniform table (`shaders/scene/draw.wesl` `MAX_MATERIALS`). */
+export declare const MAX_MATERIALS = 256;
+/** Words per material: base colour (4 f32), texture slots (4 u32), parameters (8 f32). 64 bytes, so 256 fit compatibility mode's 16 KiB uniform binding. */
+export declare const MATERIAL_WORDS = 16;
+/** Most node-material shaders (the shader id has 6 bits; 0 is the standard material). */
+export declare const MAX_SHADERS = 63;
+/**
+ * Words per material in the extension table: four parameters, four texture slots, the volume (ior,
+ * thickness, attenuation distance and colour), then dispersion, the thickness map's slot and the
+ * transmission layer (ADR-0125).
+ */
+export declare const MATERIAL_EXT_WORDS = 16;
+/**
+ * The app's materials (M2 increments 2–4): a material id is its index, stored in
+ * `render.Mesh.material`. Material 0 is white, so a `render.Mesh` that sets only `color`
+ * draws that colour. Texture slots are packed from the texture store (`sync`), so a texture
+ * that streams in mip by mip is sampled from its first resident level. Node materials
+ * (`registerShader`) become functions of the draw shader, chosen per material by a switch
+ * (ADR-0064): one pipeline and one bind group for every material.
+ */
+export declare class MaterialStore {
+    #private;
+    /** `MATERIAL_WORDS` per material (the uniform table's layout). */
+    readonly data: Float32Array<ArrayBuffer>;
+    /**
+     * The standard material's glTF extensions (`material_ext`, ADR-0093), `MATERIAL_EXT_WORDS`
+     * per material: clearcoat, clearcoat roughness, transmission, the sheen packed RGBA8
+     * (colour, roughness); then four texture slots. All zero: no extension.
+     */
+    readonly ext: Float32Array<ArrayBuffer>;
+    /** Bumped on every change. */
+    version: number;
+    /** Bumped when a shader is registered (the draw pipeline is rebuilt). */
+    shadersVersion: number;
+    constructor();
+    /**
+     * Registers a node material's shader; returns its id for `MaterialData.shader`. The same
+     * shader (by hash) registered twice returns the first id.
+     */
+    registerShader(s: MaterialShader): number;
+    /**
+     * The draw shader's material block (between its `@yali:materials` markers): every
+     * registered shader's function and the switch that picks one per material.
+     */
+    shaderBlock(): string;
+    /** Stores a material; returns its id. */
+    add(m: MaterialData): number;
+    /**
+     * Re-packs the texture slots (and each material's shader bits) when `texturesVersion`
+     * (the texture store's `version`) moved or a material was added. Returns true when the
+     * table changed.
+     */
+    sync(texturesVersion: number): boolean;
+    get count(): number;
+    /** Materials in the second transparent layer (ADR-0125): the scene adds its second copy and pass only while there are any. */
+    layered: number;
+    /** Materials whose blended surfaces draw motion (ADR-0133): the motion pass draws the blended classes only while there are any. */
+    blendMotion: number;
+}
+/**
+ * The `render.Mesh` component: which mesh an entity draws, with which material, and a colour
+ * that tints it, packed RGBA8 (`rgba8`; zero is black). Packed because converting a float
+ * colour every frame cost 1.1 ms of the extract at 20k instances on a Galaxy F04 (ADR-0052).
+ */
+export declare function registerMeshComponent(world: World): Component;
+/**
+ * Packs a linear RGBA colour (components 0–1) for `render.Mesh.color`, red in the lowest byte
+ * (what the shader's `unpack4x8unorm` reads).
+ *
+ * @example
+ * world.insert(e, render.Mesh!, { mesh: CUBE_MESH, material: 0, color: rgba8(1, 0.5, 0.2) });
+ */
+export declare function rgba8(r: number, g: number, b: number, a?: number): number;
+/** The inverse of `rgba8`: [r, g, b, a], each 0–1. */
+export declare function unpackRgba8(packed: number): [number, number, number, number];
+export {};