@driftengine/assets 3.61.0

package/dist/gltf.d.ts

@@ -0,0 +1,242 @@
+/**
+ * glTF 2.0 → `MeshData`, with no dependencies and no filesystem.
+ *
+ * glTF is the only third-party format this engine reads at tier 1, and it earns that by
+ * being an open Khronos standard with a published specification and a conformance suite.
+ * Everything the baker guarantees rests here; nothing guaranteed rests on a vendor's
+ * internal layout. See docs/FORMAT.md §2.
+ *
+ * **Buffers arrive as bytes, never as paths.** The parser takes the JSON and the binary
+ * blobs it refers to, so it runs identically in the CLI, in a test, and in a browser, and
+ * so a test can build a document by hand instead of shipping fixture files for cases that
+ * are three lines of JSON.
+ *
+ * **Transforms are baked.** `MeshData` has no node and no matrix — a mesh is geometry in
+ * world space, which is what makes drawing it one call with no per-object state. So the
+ * scene graph is flattened here: each primitive's vertices are transformed by its node's
+ * world matrix on the way through, and the graph does not survive into the engine.
+ */
+import type { DrftNode, MeshData } from '@driftengine/drft';
+import type { DrftMaterial } from '@driftengine/drft';
+import type { AssetReference } from './assetPath.ts';
+interface GltfAccessor {
+    bufferView?: number;
+    byteOffset?: number;
+    componentType: number;
+    count: number;
+    type: string;
+    normalized?: boolean;
+    sparse?: unknown;
+}
+interface GltfBufferView {
+    buffer: number;
+    byteOffset?: number;
+    byteLength: number;
+    byteStride?: number;
+}
+interface GltfPrimitive {
+    attributes: Record<string, number>;
+    indices?: number;
+    material?: number;
+    mode?: number;
+    /** Morph targets: one entry per target, each naming its own delta accessors. */
+    targets?: Record<string, number>[];
+}
+interface GltfPbrMetallicRoughness {
+    baseColorFactor?: number[];
+    metallicFactor?: number;
+    roughnessFactor?: number;
+    baseColorTexture?: {
+        index: number;
+        texCoord?: number;
+    };
+    metallicRoughnessTexture?: {
+        index: number;
+        texCoord?: number;
+    };
+}
+/**
+ * `KHR_materials_pbrSpecularGlossiness`: Khronos' first PBR material model, archived in 2020.
+ *
+ * A material stating it carries **no `pbrMetallicRoughness` object at all** — the colour map is
+ * `diffuseTexture` here, and reflection is a specular colour and a glossiness rather than a
+ * metalness and a roughness. It is still what an asset store serves for anything exported from a
+ * specular workflow, and a reader that knows only the core model reads such a file's images, binds
+ * none of them, and paints the result in one flat fallback colour.
+ */
+interface GltfSpecularGlossiness {
+    /** RGB the diffuse colour, A the opacity. Multiplies `diffuseTexture` where there is one. */
+    diffuseFactor?: number[];
+    diffuseTexture?: {
+        index: number;
+        texCoord?: number;
+    };
+    /** The specular *colour*, which is what carries a metal's tint in this model. */
+    specularFactor?: number[];
+    glossinessFactor?: number;
+    /** RGB the specular colour, A the glossiness. Both multiply the factors above. */
+    specularGlossinessTexture?: {
+        index: number;
+        texCoord?: number;
+    };
+}
+interface GltfMaterial {
+    pbrMetallicRoughness?: GltfPbrMetallicRoughness;
+    /**
+     * The material extensions this reader knows. One, and everything else is ignored.
+     *
+     * Read as an optional field rather than as `Record<string, unknown>` so that adding a second
+     * costs a name here and a branch in `pbrOf`, and so that a typo in either is a compile error.
+     */
+    extensions?: {
+        KHR_materials_pbrSpecularGlossiness?: GltfSpecularGlossiness;
+    };
+    normalTexture?: {
+        index: number;
+        texCoord?: number;
+        scale?: number;
+    };
+    /** `strength` is a mix from 1, not a multiply: 0 means unoccluded. */
+    occlusionTexture?: {
+        index: number;
+        texCoord?: number;
+        strength?: number;
+    };
+    emissiveTexture?: {
+        index: number;
+        texCoord?: number;
+    };
+    emissiveFactor?: number[];
+    /** `OPAQUE`, `MASK` or `BLEND`. Absent means opaque, which the specification states. */
+    alphaMode?: string;
+    alphaCutoff?: number;
+    name?: string;
+    /**
+     * Whatever the authoring tool put here, and this reader wants exactly one field of it.
+     *
+     * `extras.substance` is a substance id — `oak`, `gypsum-board` — which the baker writes into the
+     * `SUBS` chunk so a consumer can hand it to `installChemistry().match`. **An artist labels the oak
+     * in Blender and the log burns like oak**, with no code in between; `§16` of the chemistry design
+     * is the argument, and glTF's `extras` is the standard place for exactly this.
+     *
+     * Read as `unknown` and checked, because `extras` is whatever somebody's exporter wrote.
+     */
+    extras?: Record<string, unknown>;
+}
+/** An image, either inside the binary chunk or beside the document. */
+interface GltfImage {
+    uri?: string;
+    bufferView?: number;
+    mimeType?: string;
+    name?: string;
+}
+/** A sampler paired with an image. Only the image is used; sampler state is the engine's. */
+interface GltfTexture {
+    source?: number;
+    sampler?: number;
+}
+interface GltfNode {
+    mesh?: number;
+    /** The skin this node's mesh is deformed by. Its presence is what stops the bake. */
+    skin?: number;
+    children?: number[];
+    matrix?: number[];
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+    name?: string;
+}
+export interface GltfDocument {
+    asset?: {
+        version?: string;
+        generator?: string;
+    };
+    scene?: number;
+    scenes?: {
+        nodes?: number[];
+    }[];
+    nodes?: GltfNode[];
+    meshes?: {
+        primitives: GltfPrimitive[];
+        name?: string;
+    }[];
+    accessors?: GltfAccessor[];
+    bufferViews?: GltfBufferView[];
+    buffers?: {
+        byteLength: number;
+        uri?: string;
+    }[];
+    materials?: GltfMaterial[];
+    images?: GltfImage[];
+    textures?: GltfTexture[];
+    skins?: GltfSkinDef[];
+    animations?: GltfAnimationDef[];
+}
+/** A skin, as glTF declares one. `skeleton` is a hint this reader does not need and ignores. */
+export interface GltfSkinDef {
+    joints: number[];
+    inverseBindMatrices?: number;
+    skeleton?: number;
+    name?: string;
+}
+export interface GltfAnimationDef {
+    name?: string;
+    samplers: {
+        input: number;
+        output: number;
+        interpolation?: string;
+    }[];
+    channels: {
+        sampler: number;
+        target: {
+            node?: number;
+            path?: string;
+        };
+    }[];
+}
+/**
+ * Split a `.glb` into its JSON and its binary chunk.
+ *
+ * A `.glb` is the same document as a `.gltf` with the JSON and the buffer packed into one
+ * file, which is why an asset store hands you both — and why preferring it costs nothing.
+ */
+export declare function readGlb(buffer: ArrayBuffer): {
+    json: GltfDocument;
+    binary: Uint8Array | null;
+};
+/** Everything a document needs to be read: its buffers, in `buffers` order. */
+export type BufferResolver = (index: number, uri: string | undefined) => Uint8Array;
+/** What a caller can tell the reader about what it is going to do with the result. */
+export interface GltfReadOptions {
+    /**
+     * Derive a tangent frame where a material declares a normal map and the file supplies none.
+     *
+     * **On by default, and the baker turns it off.** The derivation accumulates per index, so run
+     * on a mesh stored as one vertex per triangle corner it gives every corner its own frame and
+     * leaves a following weld nothing to merge — measured at 9,600 corners welding to 9,482 rather
+     * than 1,681. A caller that welds should decline here and call `deriveTangentsFor` afterwards,
+     * which is both a smaller mesh and a better frame, since that is the sharing the derivation
+     * exists to average over.
+     *
+     * A caller that does *not* weld — anything reading a model straight into a renderer — wants the
+     * default, or a normal-mapped model draws with no frame to sample the map along.
+     *
+     * A frame the file supplies is kept either way. This gates inventing one, never believing one.
+     */
+    readonly deriveTangents?: boolean;
+}
+/**
+ * Turn a document into meshes in world space, one per primitive.
+ *
+ * One `MeshData` per primitive rather than per glTF mesh, because a primitive is the unit
+ * that carries a single material — and a `MeshData` has one material's worth of vertex
+ * attributes. Merging them would mean losing the distinction the file was drawing.
+ */
+export declare function gltfToMeshes(doc: GltfDocument, buffers: readonly Uint8Array[], options?: GltfReadOptions): {
+    meshes: MeshData[];
+    warnings: string[];
+    materials: DrftMaterial[];
+    textures: AssetReference[];
+    nodes: DrftNode[];
+};
+export {};