@yali-engine/gltf 0.0.0-stage → 0.4.0

package/dist/parse.d.ts

@@ -0,0 +1,230 @@
+/** One drawable piece of a mesh: triangles with one material. Arrays are tightly packed. */
+export interface GltfPrimitive {
+    /** xyz per vertex. */
+    readonly positions: Float32Array;
+    /** xyz per vertex (computed, smooth, when the file has none). */
+    readonly normals: Float32Array;
+    /** uv per vertex, or null. */
+    readonly uvs: Float32Array | null;
+    /** Triangle list (generated 0..n-1 when the file has no indices). */
+    readonly indices: Uint32Array;
+    /** Index into `materials`, or -1 for the default material. */
+    readonly material: number;
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+    /**
+     * Coarser levels of detail from `MSFT_lod`, finest first: index lists over this
+     * primitive's own vertices, with their error in mesh units (`extras.yaliLodError`).
+     * Empty when the file has none.
+     */
+    readonly lods: readonly GltfLod[];
+    /**
+     * Skinning (`JOINTS_0` / `WEIGHTS_0`): 4 joint slots and 4 weights per vertex, weights
+     * normalized to sum to 1; a file's `JOINTS_1` / `WEIGHTS_1` are folded into the 4 largest
+     * (ADR-0083). Null for a rigid primitive.
+     */
+    readonly skin: {
+        readonly joints: Uint16Array;
+        readonly weights: Float32Array;
+    } | null;
+    /** Morph targets: per target, position deltas (xyz per vertex) and normal deltas (or null). Empty without any. */
+    readonly targets: readonly GltfMorphTarget[];
+    /**
+     * The primitive's clusters, packed ahead of time (`YALI_clusters`, written by `yali convert
+     * --clusters`; ADR-0121): `packClusters`' layout over this primitive's own vertices. Null without.
+     */
+    readonly clusters: GltfClusters | null;
+    /**
+     * The primitive's cluster hierarchy in streaming pages (`YALI_cluster_pages`, written by `yali convert
+     * --clusters --stream`; ADR-0134): the primitive's own vertices and indices are then its root pages'
+     * mesh. Null without.
+     */
+    readonly pages: GltfClusterPages | null;
+}
+/**
+ * A primitive's cluster hierarchy in pages (`YALI_cluster_pages`, ADR-0134), in `@yali-engine/render`'s
+ * `ClusterPages` layout: every cluster record, the page table, the root pages' bytes (in the file),
+ * and where the other pages are.
+ */
+export interface GltfClusterPages {
+    readonly words: Uint32Array;
+    readonly pages: Uint32Array;
+    readonly roots: number;
+    readonly localIds: number;
+    readonly triangleBytes: number;
+    readonly corners: number;
+    readonly slotVertices: number;
+    /** The root pages' bytes: the page data's first `rootData.length` bytes. */
+    readonly rootData: Uint8Array;
+    /** The other pages' file, relative to the GLB: a page at table offset `o` is at `base + o - rootData.length` in it (one file holds every primitive's). */
+    readonly uri: string;
+    readonly base: number;
+}
+/**
+ * A primitive's clusters as `yali convert --clusters` stores them (`YALI_clusters`, ADR-0121): the
+ * records, the clusters' local vertex ids and their triangle bytes, in `@yali-engine/render`'s
+ * `PackedClusters` layout, and whether they form a cluster LOD hierarchy.
+ */
+export interface GltfClusters {
+    readonly lod: boolean;
+    readonly words: Uint32Array;
+    readonly vertices: Uint32Array;
+    readonly triangles: Uint8Array;
+    readonly corners: number;
+}
+/** One morph target of a primitive: offsets added in proportion to its weight. */
+export interface GltfMorphTarget {
+    readonly positions: Float32Array;
+    readonly normals: Float32Array | null;
+}
+/** One level of detail of a primitive. */
+export interface GltfLod {
+    readonly indices: Uint32Array;
+    /** How far, in mesh units, this level's surface may be from the full primitive's. */
+    readonly error: number;
+}
+export interface GltfMesh {
+    readonly name: string;
+    readonly primitives: readonly GltfPrimitive[];
+    /** Morph target weights when nothing animates them (`mesh.weights`, else zeros). */
+    readonly weights: readonly number[];
+}
+/** A node: a local transform (TRS), an optional mesh, children. */
+export interface GltfNode {
+    readonly name: string;
+    /** Index into `meshes`, or -1. */
+    readonly mesh: number;
+    /** Index into `skins` (its mesh is skinned), or -1. */
+    readonly skin: number;
+    readonly children: readonly number[];
+    readonly t: readonly [number, number, number];
+    readonly r: readonly [number, number, number, number];
+    readonly s: readonly [number, number, number];
+}
+/** A material's texture: the image it samples (index into `GltfScene.images`) and its UV set. */
+export interface GltfTextureRef {
+    readonly image: number;
+    readonly texCoord: number;
+}
+/** A glTF metallic-roughness material (M2 increment 5, ADR-0066). */
+export interface GltfMaterial {
+    readonly name: string;
+    readonly baseColor: readonly [number, number, number, number];
+    readonly metallic: number;
+    readonly roughness: number;
+    /** Linear emissive colour times `KHR_materials_emissive_strength`. */
+    readonly emissive: readonly [number, number, number];
+    readonly normalScale: number;
+    readonly occlusionStrength: number;
+    readonly alphaMode: 'OPAQUE' | 'MASK' | 'BLEND';
+    readonly alphaCutoff: number;
+    readonly doubleSided: boolean;
+    readonly baseColorTexture: GltfTextureRef | null;
+    readonly metallicRoughnessTexture: GltfTextureRef | null;
+    readonly normalTexture: GltfTextureRef | null;
+    readonly occlusionTexture: GltfTextureRef | null;
+    readonly emissiveTexture: GltfTextureRef | null;
+    /** KHR_materials_clearcoat (ADR-0093): the coat's strength and roughness, 0 without it. */
+    readonly clearcoat: number;
+    readonly clearcoatRoughness: number;
+    readonly clearcoatTexture: GltfTextureRef | null;
+    readonly clearcoatRoughnessTexture: GltfTextureRef | null;
+    /** KHR_materials_transmission: 0 without it. */
+    readonly transmission: number;
+    readonly transmissionTexture: GltfTextureRef | null;
+    /** KHR_materials_sheen: linear colour (black without it) and roughness. */
+    readonly sheenColor: readonly [number, number, number];
+    readonly sheenRoughness: number;
+    readonly sheenColorTexture: GltfTextureRef | null;
+    /** KHR_materials_ior (default 1.5). */
+    readonly ior: number;
+    /** KHR_materials_volume (ADR-0099): thickness (0: thin-walled), attenuation colour and distance (Infinity: none). */
+    readonly thickness: number;
+    /** The volume's thickness map (its G channel times `thickness`, ADR-0125), or null. */
+    readonly thicknessTexture: GltfTextureRef | null;
+    /** KHR_materials_dispersion (ADR-0125): how far the colours part when refracted (20 / the Abbe number; 0: none). */
+    readonly dispersion: number;
+    readonly attenuationColor: readonly [number, number, number];
+    readonly attenuationDistance: number;
+}
+/** An image a texture uses: its bytes when the file embeds it (a buffer view or data URI), else its URL. */
+export interface GltfImage {
+    readonly mimeType: string;
+    readonly bytes: Uint8Array | null;
+    readonly url: string | null;
+    /**
+     * The sizes `yali convert` wrote of an external KTX2 (`extras.yaliSizes`, ascending, the last
+     * the full one): `<name>.<variant>.<size>.ktx2` beside `<name>.<variant>.ktx2`.
+     */
+    readonly sizes?: readonly number[];
+}
+/** A skin: the nodes its joint slots follow, and each slot's inverse bind matrix. */
+export interface GltfSkin {
+    readonly name: string;
+    /** Node of each joint slot (a vertex's `JOINTS_0` values are slots). */
+    readonly joints: readonly number[];
+    /** 16 floats (column-major) per slot; identities when the file has none. */
+    readonly inverseBindMatrices: Float32Array;
+}
+/** One animated property of one node. */
+export interface GltfChannel {
+    readonly node: number;
+    readonly path: 'translation' | 'rotation' | 'scale' | 'weights';
+    /** LINEAR or STEP (a CUBICSPLINE sampler is resampled to LINEAR at 60 Hz when parsed). */
+    readonly interpolation: 'LINEAR' | 'STEP';
+    /** Key times (seconds), increasing. */
+    readonly times: Float32Array;
+    /** Values per key: 3 (translation, scale), 4 (rotation, xyzw) or one per morph target. */
+    readonly values: Float32Array;
+}
+/** An animation: channels over nodes. */
+export interface GltfAnimation {
+    readonly name: string;
+    readonly channels: readonly GltfChannel[];
+}
+/** A parsed glTF: plain data and typed arrays, so it crosses from a decode worker by transfer. */
+export interface GltfScene {
+    readonly nodes: readonly GltfNode[];
+    readonly skins: readonly GltfSkin[];
+    readonly animations: readonly GltfAnimation[];
+    /** The default scene's root nodes. */
+    readonly roots: readonly number[];
+    readonly meshes: readonly GltfMesh[];
+    readonly materials: readonly GltfMaterial[];
+    readonly images: readonly GltfImage[];
+    readonly stats: {
+        readonly vertices: number;
+        readonly triangles: number;
+        readonly bytes: number;
+    };
+    /** Things skipped (non-triangle primitives, unsupported optional extensions). */
+    readonly warnings: readonly string[];
+}
+/** What `parseGltf` needs for a `.gltf` with external buffers. */
+export interface ParseOptions {
+    /** Base URL that relative buffer URIs resolve against (the `.gltf` file's URL). */
+    readonly baseUrl?: string;
+    /** Fetches an external buffer (default: `fetch`). */
+    readonly fetchBuffer?: (url: string) => Promise<Uint8Array>;
+}
+/**
+ * Parses a glTF 2.0 asset (`.glb`, or `.gltf` with embedded or external buffers) into
+ * plain arrays (DESIGN.md §9; ADR-0047). Pure and allocation-heavy by nature: it runs in a
+ * decode worker.
+ *
+ * @example
+ * const scene = await parseGltf(new Uint8Array(await (await fetch('/temple.glb')).arrayBuffer()));
+ * scene.meshes[0].primitives[0].positions; // Float32Array
+ */
+export declare function parseGltf(bytes: Uint8Array, options?: ParseOptions): Promise<GltfScene>;
+/** Rate (keys per second) a CUBICSPLINE sampler is resampled to LINEAR at (ADR-0083). */
+export declare const CUBIC_RESAMPLE_HZ = 60;
+/**
+ * A glTF CUBICSPLINE sampler (per key: in-tangent, value, out-tangent) as LINEAR keys at
+ * `CUBIC_RESAMPLE_HZ` plus every original key, evaluated with the spec's Hermite form;
+ * rotations are normalized.
+ */
+export declare function resampleCubic(times: Float32Array, data: Float32Array, width: number, rotation: boolean): {
+    times: Float32Array;
+    values: Float32Array;
+};