@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/mesh.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Mesh: a vertex buffer (+ optional index buffer) in one of the engine's vertex layouts.
+ *
+ * - `VERTEX_LAYOUT_2D` (the default): `pos: vec2f, uv: vec2f, color: vec4f`, 8 floats
+ *   (`VERTEX_FLOATS`), 32 bytes per vertex.
+ * - `VERTEX_LAYOUT_3D`: `pos: vec3f, normal: vec3f, uv: vec2f, color: vec4f`, 12 floats
+ *   (`VERTEX3D_FLOATS`), 48 bytes per vertex.
+ * - `VERTEX_LAYOUT_3D_TANGENT`: the 3D layout plus `tangent: vec4f` (xyz, handedness w),
+ *   16 floats, 64 bytes per vertex.
+ *
+ * Positions are in the mesh's local space; each draw's 3×4 instance matrix (built from
+ * `DrawParams` x, y, w, h, rotation, or taken from a `Transform`) maps local → world space.
+ * For `DrawParams` that is `xy + rotate(pos * wh)`: the built-in quad spans -0.5..0.5 so
+ * `w, h` are its size in logical pixels; for arbitrary meshes authored directly in logical
+ * pixels, draw with `x = 0, y = 0, w = 1, h = 1`.
+ *
+ * Materials build one pipeline per (vertex layout, depth mode), lazily, on first use.
+ */
+export declare const VERTEX_FLOATS = 8;
+export declare const VERTEX_STRIDE: number;
+export declare const VERTEX3D_FLOATS = 12;
+export declare const VERTEX3D_STRIDE: number;
+/** The 2D layout's buffer layout (locations 0..2). */
+export declare const VERTEX_BUFFER_LAYOUT: GPUVertexBufferLayout;
+/** The 3D layout's buffer layout: position 0, normal 10, uv 1, colour 2. */
+export declare const VERTEX3D_BUFFER_LAYOUT: GPUVertexBufferLayout;
+/**
+ * A vertex layout: the GPU buffer layout plus the WGSL that reads it. The material prelude is
+ * generated per layout (`materialPrelude(layout)`), so `engine_vertex`, `VSOut` and the
+ * fragment side are the same for every layout. Layouts compare by identity.
+ */
+export interface VertexLayout {
+    /** Short name, used in pipeline labels. */
+    readonly name: string;
+    readonly floats: number;
+    readonly stride: number;
+    readonly buffer: GPUVertexBufferLayout;
+    /** The vertex-attribute fields of WGSL `VertexIn` (the instance fields follow them). */
+    readonly wgslFields: string;
+    /** WGSL expression over `v: VertexIn` for the object-space position (`vec3f`). */
+    readonly wgslPosition: string;
+    /** WGSL expression over `v: VertexIn` for the object-space normal (`vec3f`). */
+    readonly wgslNormal: string;
+    /**
+     * Float offset of x, y, z inside a vertex (0 in every shipped layout), so a layout goes
+     * straight to `meshTester(..., { stride: layout.floats, offset: layout.positionOffset })`.
+     * Optional for a layout written by hand; read it as `layout.positionOffset ?? 0`.
+     */
+    readonly positionOffset?: number;
+    /**
+     * The layout carries joints and weights: `materialPrelude` emits `WGSL_SKIN` (the palette
+     * binding and `engine_skin`) so `wgslPosition` / `wgslNormal` may call it. See `skin.ts`.
+     */
+    readonly skinned?: boolean;
+    /**
+     * WGSL expression over `v: VertexIn` for the file tangent (`vec4f`: xyz along +u, w the
+     * handedness) when the layout carries one; the prelude's `engine_local_tangent(v)` returns it,
+     * or `vec4f(0)` (w = 0: "no tangent", the derivative fallback) for a layout without.
+     */
+    readonly wgslTangent?: string;
+    /**
+     * WGSL expression over `v: VertexIn` for the second texture coordinate set (`vec2f`), the
+     * `uv1` varying (`TEXCOORD_1`); `v.uv` is used when absent.
+     */
+    readonly wgslUv1?: string;
+    /**
+     * WGSL expression over `v: VertexIn` for the object-space position of the previous frame as
+     * a `vec4f` (w = 0 means "unknown": the velocity target reads zero). Default: the current
+     * position with w = 1. A skinned layout reads the palette's previous block.
+     */
+    readonly wgslPreviousPosition?: string;
+}
+/** 2D layout: `v.pos` is a `vec2f` (z = 0); the normal faces the viewer, `(0, 0, -1)`. */
+export declare const VERTEX_LAYOUT_2D: VertexLayout;
+/** 3D layout: `v.pos` and `v.normal` are `vec3f`. */
+export declare const VERTEX_LAYOUT_3D: VertexLayout;
+/**
+ * Tangent layout (ws/geom-2): the 3D layout's 12 floats followed by a tangent `vec4f` at
+ * `@location(13)` (3..9 are the instance buffer, 11 and 12 skinning): xyz the unit tangent
+ * along +u, w the handedness ±1, so the bitangent is `w · cross(normal, tangent)`. 16 floats,
+ * 64 bytes. `geom`'s `computeTangents` writes it; the prelude reads it like the 3D layout, so a
+ * material that ignores `v.tangent` draws unchanged.
+ */
+export declare const VERTEX_LAYOUT_3D_TANGENT: VertexLayout;
+/** Floats of `VERTEX_LAYOUT_3D_UV2` (the 3D layout plus a second uv). */
+export declare const VERTEX3D_UV2_FLOATS = 14;
+export declare const VERTEX3D_UV2_STRIDE: number;
+/**
+ * Two-uv layout (ws/render-4): the 3D layout's 12 floats followed by `uv1: vec2f` at
+ * `@location(14)` (glTF `TEXCOORD_1`, the usual home of a light or occlusion map): 14 floats,
+ * 56 bytes. The prelude carries it as `VSOut.uv1`; the standard material's maps pick it with
+ * `texCoord: 1`. Materials that ignore it draw as with the 3D layout.
+ */
+export declare const VERTEX_LAYOUT_3D_UV2: VertexLayout;
+/**
+ * Skinned layout: the 3D layout's 12 floats followed by four joint indices (`uint8x4`, read as
+ * `vec4u`) and four weights (`unorm8x4`, read as `vec4f`), 8 bytes that occupy the slots of
+ * floats 12 and 13: 14 "floats" (`VERTEX_SKINNED_FLOATS`), 56 bytes per vertex. Write the
+ * joints and weights through a byte view of the vertex buffer (`setVertexSkin` in `skin.ts`),
+ * not as floats (a packed value may be a NaN pattern). `materialPrelude` applies the four
+ * weighted joint matrices from the material's `SkinPalette` before the instance matrix.
+ */
+export declare const VERTEX_SKINNED_FLOATS = 14;
+export declare const VERTEX_SKINNED_STRIDE: number;
+/** Byte offset of the four joint indices inside a skinned vertex. */
+export declare const SKIN_JOINTS_BYTE_OFFSET = 48;
+/** Byte offset of the four weights (unorm8) inside a skinned vertex. */
+export declare const SKIN_WEIGHTS_BYTE_OFFSET = 52;
+/** The skinned layout's buffer layout: the 3D attributes, joints at 11 and weights at 12. */
+export declare const VERTEX_SKINNED_BUFFER_LAYOUT: GPUVertexBufferLayout;
+/**
+ * Skinned layout: `v.pos`, `v.normal`, `v.uv`, `v.color` as in 3D plus `v.joints: vec4u` and
+ * `v.weights: vec4f`. The prelude's `engine_local_position` / `engine_local_normal` return the
+ * skinned position and normal (`engine_skin`), so `engine_vertex` and every material work
+ * unchanged. The instance's palette slot travels in `params.w` (see `skin.ts`).
+ */
+export declare const VERTEX_LAYOUT_SKINNED: VertexLayout;
+/** An index sub-range of a mesh: `first` index and `count` indices (`InstanceParams.range`). */
+export interface MeshRange {
+    first: number;
+    count: number;
+}
+/** Room reserved in a mesh's buffers, in vertices and indices. */
+export interface MeshCapacity {
+    readonly vertices: number;
+    readonly indices: number;
+}
+export interface MeshDesc {
+    label?: string;
+    /**
+     * Interleaved vertices in `layout`: 8 floats each for 2D (x, y, u, v, r, g, b, a), 12 for
+     * 3D (x, y, z, nx, ny, nz, u, v, r, g, b, a). Optional when `capacity` is given: the mesh
+     * then starts empty (`vertexCount` 0) and is filled by `update()`.
+     */
+    vertices?: Float32Array;
+    /** Vertex layout. Default `VERTEX_LAYOUT_2D`. */
+    layout?: VertexLayout;
+    indices?: Uint16Array | Uint32Array;
+    /**
+     * Reserve room for this many vertices and indices so `update()` can rewrite the geometry
+     * without reallocating. Defaults to the initial data's size. `indices` > 0 gives the mesh an
+     * index buffer even when no initial indices are passed.
+     */
+    capacity?: {
+        vertices?: number;
+        indices?: number;
+    };
+    /**
+     * Index format of a mesh created with only an index capacity. Default: the format of the
+     * initial `indices`, else `uint16` when `capacity.vertices` fits, `uint32` otherwise.
+     */
+    indexFormat?: GPUIndexFormat;
+    /**
+     * Bounding sphere in mesh space, for frustum culling (`camera.cull`). Default: computed from
+     * `vertices` when `autoBounds` is on, else unbounded (never culled).
+     */
+    bounds?: MeshBounds;
+    /**
+     * Recompute `bounds` from the positions on every `update()` that uploads vertices without
+     * passing `bounds`. Default on under `AUTO_BOUNDS_MAX_VERTICES` (65 536) of capacity, off
+     * above it, so a chunk pipeline that knows its bounds passes them itself.
+     */
+    autoBounds?: boolean;
+    /**
+     * Named index ranges (storage only, ws/render-4): a sub-mesh per material of a file, say.
+     * Draw one with `frame.mesh(mesh, material, transform, { range: mesh.ranges.door })`.
+     */
+    ranges?: Record<string, MeshRange>;
+}
+/** A bounding sphere: `center` (x, y, z) and `radius`. `radius` Infinity means unbounded. */
+export interface MeshBounds {
+    center: [number, number, number];
+    radius: number;
+}
+/** Capacity (vertices) up to which `MeshDesc.autoBounds` defaults to on. */
+export declare const AUTO_BOUNDS_MAX_VERTICES = 65536;
+/**
+ * One geometry upload. Views are read from their own `ArrayBuffer` (`buffer`, `byteOffset`),
+ * so a buffer transferred from a Worker is uploaded in place, with no copy on the main thread.
+ * Any view type works; counts default to the view's whole length in the mesh's layout and
+ * index format. `vertexCount`/`indexCount` without a view only move the draw range.
+ */
+export interface MeshUpdate {
+    vertices?: ArrayBufferView;
+    indices?: ArrayBufferView;
+    /** Vertices to upload and draw. Default: all of `vertices`. */
+    vertexCount?: number;
+    /** Indices to upload and draw. Default: all of `indices`. */
+    indexCount?: number;
+    /**
+     * New bounding sphere (copied). Without it, bounds are recomputed from `vertices` only when
+     * the mesh's `autoBounds` is on.
+     */
+    bounds?: MeshBounds;
+}
+/**
+ * The shape a meshing Worker posts back (`harness/stream.ts`): one `ArrayBuffer` holding
+ * `vertexCount` vertices of the mesh's layout from byte 0 and, when `indexCount` is given, that
+ * many indices of the mesh's index format at `indexOffset` (default: right after the vertices,
+ * rounded up to 4 bytes); an indexed mesh given no `indexCount` draws nothing until the next
+ * reply. `Mesh.update` takes it as-is, so the page never builds views over the
+ * transferred buffer. Extra fields (a chunk id) are ignored.
+ */
+export interface MeshReply {
+    buffer: ArrayBuffer;
+    vertexCount: number;
+    indexCount?: number;
+    /** Byte offset of the indices in `buffer`. Default: the vertices' byte length, 4-aligned. */
+    indexOffset?: number;
+    bounds?: MeshBounds;
+}
+export declare class Mesh {
+    private readonly device;
+    readonly label: string;
+    /** Vertex layout of this mesh's buffer; pipelines are keyed by (material, layout). */
+    readonly layout: VertexLayout;
+    vertexBuffer: GPUBuffer;
+    indexBuffer: GPUBuffer | null;
+    indexFormat: GPUIndexFormat;
+    /** Vertices drawn (non-indexed) and uploaded by the last `update`. */
+    vertexCount: number;
+    /**
+     * Indices drawn (`drawIndexed`) when > 0. With an index buffer and `indexCount` 0 the renderer
+     * skips the draw entirely (no non-indexed fallback, no draw call, nothing in
+     * `RenderStats`), so `update({ indexCount: 0 })` empties the mesh.
+     */
+    indexCount: number;
+    /**
+     * Buffers reallocated so far, by `update()` exceeding `capacity` or changing the index format.
+     * A caller that caches `vertexBuffer`/`indexBuffer` (a drawable, a bind group) re-reads them
+     * when this changes.
+     */
+    growths: number;
+    /**
+     * Bounding sphere in mesh space (the renderer carries it through each draw's instance matrix
+     * and culls against `camera.frustum`). From `MeshDesc.bounds`, `MeshUpdate.bounds` or, with
+     * `autoBounds`, the positions; `radius` Infinity when unknown (never culled). The object is
+     * owned by the mesh; read it, set it through `update({ bounds })`.
+     */
+    readonly bounds: MeshBounds;
+    /** Whether `update()` recomputes `bounds` from uploaded vertices (`MeshDesc.autoBounds`). */
+    readonly autoBounds: boolean;
+    /** Named index ranges from `MeshDesc.ranges`; storage only, the renderer never reads it. */
+    readonly ranges: Record<string, MeshRange> | undefined;
+    /** The layout's position attribute (location 0) has a z component. */
+    private readonly pos3;
+    private readonly cap;
+    /** 4-byte scratch for the last index of an odd uint16 count at the end of its buffer. */
+    private readonly tail16;
+    constructor(device: GPUDevice, desc: MeshDesc);
+    /** Room in the buffers (vertices, indices); `indices` is 0 for a non-indexed mesh. */
+    get capacity(): MeshCapacity;
+    /**
+     * Replace geometry (`MeshUpdate`). Writes with `queue.writeBuffer` straight from each view's
+     * buffer and reuses the GPU buffers while the counts fit `capacity`; grows them (1.5×) only
+     * when a count exceeds it or the index format changes. Returns true when a buffer was
+     * reallocated (`growths` counts them). `bounds` are copied when given, else recomputed from
+     * the uploaded positions when `autoBounds` is on (a `Float32Array` view is read in place;
+     * any other view type gets one over the same buffer). Allocation-free otherwise.
+     *
+     * A `MeshReply` (`{ buffer, vertexCount, indexCount?, bounds? }`, a Worker's message) is the
+     * same upload read straight out of the one transferred buffer; it allocates the two views.
+     */
+    update(u: MeshUpdate | MeshReply): boolean;
+    private updateFromReply;
+    private updateViews;
+    /**
+     * Bounding sphere of the first `count` vertices of `view` in this layout: the centre of their
+     * axis-aligned box, the radius the farthest vertex from it. 2D positions have z = 0.
+     */
+    private computeBounds;
+    /** `writeBuffer` wants 4-byte sizes and offsets; a uint16 count may be odd. */
+    private writeIndices;
+    /** The `GPUVertexBufferLayout` of `layout` (buffer slot 0 of every pipeline drawing it). */
+    get vertexBufferLayout(): GPUVertexBufferLayout;
+    destroy(): void;
+    private makeVertexBuffer;
+    private makeIndexBuffer;
+}
+/** Unit quad centred on the origin (-0.5..0.5), uv (0,0) top-left, white. */
+export declare function quadGeometry(): {
+    vertices: Float32Array;
+    indices: Uint16Array;
+};