@driftengine/assets 3.61.0

package/dist/drftLoader.d.ts

@@ -0,0 +1,420 @@
+/** Loading a `.drft` into drawable parts progressively, without stalling the frame. */
+import type { MeshData } from '@driftengine/drft';
+import type { RendererApi } from '@driftengine/core';
+import type { SurfaceTextureHandle } from '@driftengine/core';
+import type { DrftMaterial } from '@driftengine/drft';
+import { TextureSet } from './drftTextures.ts';
+import type { AnimationClip, DrftMorph, DrftNode, DrftSkin } from '@driftengine/drft';
+import type { DrftLoadProgress, DrftPart } from './loadProgress.ts';
+/**
+ * How a loaded model is placed: fitted to a size, or left exactly where its file puts it.
+ *
+ * **`'none'` exists because the way to ask for nothing was to ask for the answer.** A game whose
+ * importer has already put a model in its own frame — metres, y = 0 at the road — wanted no fit
+ * at all, and the only way to say so was to hand `load` the footprint and height it would have
+ * computed, which means measuring the model to tell the loader not to measure it. The obvious
+ * shortcut is a trap and a consumer fell in it: `footprint: Number.MAX_SAFE_INTEGER` does not mean
+ * "do not scale", it means a scale of 2.3e15, and a car drawn nine quadrillion metres wide looks
+ * from inside exactly like a model that failed to load.
+ */
+export type DrftFit = {
+    /** The size the larger of the model's footprint and height is scaled to. */
+    readonly footprint: number;
+    readonly height: number;
+    /** Where its lowest point sits, for a scene whose floor is not at zero. Zero unless stated. */
+    readonly baseY?: number;
+} | {
+    /** Scale 1 and no offset: the model arrives in the coordinates the file states. */
+    readonly fit: 'none';
+};
+export interface DrftLoaderOptions {
+    /**
+     * The most parts one `update` may take, however cheap they turn out to be.
+     *
+     * **A ceiling, not the budget.** The budget is `uploadMsPerFrame`, because what a part costs
+     * cannot be known by counting parts — see `mayBeginMore`. This stays as the guard against the
+     * opposite shape of asset, a model of hundreds of tiny parts where the clock would happily take
+     * a hundred of them in one frame and spend the whole reveal in two.
+     */
+    readonly uploadsPerFrame?: number;
+    /**
+     * How long one `update` may spend starting new stream work, in milliseconds.
+     *
+     * `DEFAULT_UPLOAD_MS_PER_FRAME` unless stated. Raise it for a tool that would rather have the
+     * model in front of it sooner than hold a rate; lower it for a scene where the frame matters
+     * more than the wait. Zero is the slowest honest setting rather than a stall: one piece a frame
+     * still begins, because a load has to finish.
+     */
+    readonly uploadMsPerFrame?: number;
+    /** Seconds for a part to fade from nothing to itself. Zero makes it appear. */
+    readonly revealSec?: number;
+    /**
+     * Anisotropic filtering asked of every image, where the extension exists.
+     *
+     * A model's maps are the case for it: tread on a tyre, a panel gap, a plate, all bands of fine
+     * detail seen at a grazing angle, which is exactly where a trilinear sample gives up.
+     */
+    readonly anisotropy?: number;
+    /**
+     * How every image this asset carries behaves past its own edge. `repeat` unless stated.
+     *
+     * **Reported from outside, and it is a real trap on a bought model.** A surface texture repeats
+     * by default, which is right for a tiling map and wrong at the border of a UV island: a sample
+     * whose footprint crosses the edge wraps to the far side of the image, and a mip level high
+     * enough averages across islands that have nothing to do with each other. On a model whose
+     * untextured surfaces sit at an exporter's default `0.8` grey, the result is single bright pixels
+     * tracing every seam of every textured part, which is invisible against a light background and
+     * obvious against black paint.
+     *
+     * `clamp` is the repair where an asset's own UV padding is thin, and it is stated rather than
+     * assumed because a model that genuinely tiles a map needs `repeat` and would band without it.
+     */
+    readonly textureWrap?: 'repeat' | 'clamp';
+    /**
+     * A last chance to change a mesh's vertex data before it is uploaded.
+     *
+     * For a scene that dresses an import rather than taking it as it comes: a bought asset that
+     * stores every surface as the same default grey while naming them `body`, `glass` and `chrome`
+     * can have its paint decided here, per material, without the loader knowing what a car is.
+     */
+    readonly transform?: (mesh: MeshData, material: DrftMaterial | undefined) => MeshData;
+    /** Per-material opacity and reflectivity overrides, for the same reason as `transform`. */
+    readonly surface?: (material: DrftMaterial | undefined) => {
+        readonly opacity?: number;
+        readonly reflectivity?: number;
+    } | undefined;
+    /**
+     * Draw a coarse whole model while the parts arrive, where the file carries one.
+     *
+     * **On when the file carries one, and `false` refuses it.** This was off by default for two
+     * releases, on the argument that a `LODM` chunk is a *decimated* model and how good it looks
+     * is a property of the asset rather than of this code. That argument was about the old hull,
+     * which was built by clustering vertices and joined clusters lying on different surfaces of
+     * the model, so a car grew spikes through its own bodywork and somebody waiting for it saw
+     * white cliffs. A bad preview reads as a broken import where an empty stage reads as a load,
+     * so refusing to guess was right.
+     *
+     * The hull is the surface of an occupancy grid now (`buildCoarseLevel`), which cannot do that:
+     * it emits the boundary of a solid, so the worst case is a coarse version of the shape rather
+     * than a shape that was never there. And nothing carries a `LODM` by accident. A chunk exists
+     * only because somebody baked one, so ignoring it by default meant the file said one thing and
+     * the reader did another.
+     *
+     * `outline: false` still refuses, for a caller swapping a model already on screen for a better
+     * one, where a coarse version of the new one is a step backwards.
+     */
+    readonly outline?: boolean;
+    /**
+     * Keep the arrival state after the load, so `replay` can put any point of it back on screen.
+     *
+     * **Off by default, because it costs a second copy of the model on the GPU.** The load
+     * normally ends by disposing the outline and the per-part meshes, since the merged groups
+     * draw the same geometry in seven draws rather than 188. Holding them is what makes the
+     * reveal *inspectable* rather than a thing that happens once and cannot be looked at again:
+     * a stage that is only ever seen while the bytes are arriving can only be studied by
+     * reloading, at whatever speed the network happens to give.
+     *
+     * The cost is stated rather than hidden: on a 187-part car the per-part meshes are about the
+     * same vertex count as the merged ones, so this roughly doubles the geometry the asset holds.
+     * For a tool, a documentation page or a demo that is worth it. For a game shipping a level
+     * it is not, which is why it is not the default.
+     */
+    readonly keepReveal?: boolean;
+    /**
+     * Put a small version of each image on its surfaces before the full one, at this many pixels
+     * on the longest side. Absent means every image arrives once, at full size.
+     *
+     * **This is the blur-to-sharp arrival of docs/FORMAT.md §4.6, done from the bytes already in
+     * the file.** The section asks for mip levels stored smallest first as separate chunks, which
+     * is the better answer for a metered connection because it can stop early and keep the small
+     * one. It needs the *baker* to resize an image, and the baker runs in Node where there is no
+     * decoder for a JPEG, so that half is a dependency decision rather than an implementation.
+     *
+     * What is available without one: `createImageBitmap` resizes while it decodes. A 256 pixel
+     * version of a 2048 square costs a fraction of the full decode, so a surface stops being
+     * flat about a second earlier on a real model, and the full image then replaces it in the
+     * same GPU object. It costs a second decode per image, off the main thread, and not one byte
+     * of the file — which is why it is an option a caller weighs rather than a default.
+     */
+    readonly texturePreview?: number;
+}
+/**
+ * A `.drft` loaded progressively: the model builds up on screen instead of appearing.
+ *
+ * **What this exists to prevent is the two obvious ways of doing it, both of which are worse.**
+ * Reading the whole file and uploading it at the end switches from nothing to everything after
+ * several seconds, which demonstrates nothing about a format built to arrive in priority order.
+ * Uploading each part the moment its bytes land puts an unbounded number of GPU allocations in
+ * one animation frame and hitches the page. This does neither: bytes stream, arrivals queue, and
+ * a bounded number of parts are uploaded per frame with a fade.
+ *
+ * **It starts on an outline where the file carries one.** A `LODM` chunk is a coarse whole model
+ * laid out ahead of everything else, so it is uploaded first and drawn until the real geometry is
+ * complete — which turns "nothing, then parts appearing" into "an object, sharpening". The parts
+ * fade in over it and the swap to the finished model is atomic, because a frame showing both is
+ * showing the same car twice. A caller that would rather hold the last picture says
+ * `outline: false`. See `DrftLoaderOptions.outline`.
+ *
+ * **It ends in one mesh per material group.** The reveal wants one upload per part and the steady
+ * state wants as few draws as possible, so the load does the first and finishes by doing the
+ * second: after the last byte the parts are merged by the image and blend they wear, uploaded
+ * once, and the per-part meshes are disposed. On a 187-part car that is 187 draws while loading
+ * and seven afterwards.
+ *
+ * Nothing here touches WebGL. Every GPU object comes from the `Renderer` it is handed, which is
+ * what keeps the engine's rule about where raw GL may live intact.
+ */
+export declare class DrftLoader {
+    private readonly renderer;
+    private readonly options;
+    private readonly revealed;
+    /** Arrived, not yet uploaded. Drained by `update` at the budget. */
+    private readonly queue;
+    /**
+     * Coarse levels that have arrived and not yet been uploaded, in arrival order.
+     *
+     * Its own queue rather than the part queue, because it must not wait behind a budget meant
+     * for parts: the entire value of an outline is that it is on screen before them.
+     */
+    private readonly lodQueue;
+    /** The outline currently on screen, and its level. -1 means none has landed. */
+    private outlinePart;
+    private outlineMesh;
+    private outlineLevel;
+    /**
+     * The merged groups, accumulated *as parts arrive* rather than all at once at the end.
+     *
+     * This is the second of the two stalls this class exists to avoid, and it was the worse one.
+     * Building seven merged meshes out of 187 parts after the last byte is a million vertices of
+     * copying in a single frame, and it landed exactly where a viewer had just started looking at a
+     * finished car. Adding each part to its group as it is uploaded spreads that cost over the whole
+     * load, where there is already a budget governing it, and leaves only one `build` and one upload
+     * per group to do at the end — which `update` then spends one group per frame.
+     */
+    private readonly groups;
+    /** Group keys still to be built and uploaded, drained one per frame after the stream ends. */
+    private readonly mergeQueue;
+    private readonly mergedParts;
+    /**
+     * Every part in the order it arrived, and the finished model, held only for `keepReveal`.
+     *
+     * The load itself needs neither: it draws from `revealed` and throws the singles away at the
+     * merge. These exist so `replay` can put an arrival state back, which needs the *order* as
+     * much as the meshes — a reveal replayed in the order the groups merged would be a different
+     * sequence from the one the file delivered.
+     */
+    private readonly arrivals;
+    private readonly finished;
+    /** Decoded images waiting for the GPU, uploaded one per frame for the same reason. */
+    private readonly imageQueue;
+    /** Which images have arrived at full size, so a late preview cannot blur one of them again. */
+    private readonly sharp;
+    /**
+     * Which images are on the GPU, and how many, which is what `imagesDone` reports.
+     *
+     * Counted at the upload rather than at the arrival of the bytes, and the difference is a
+     * second and three quarters on a real asset. See `DrftLoadProgress`.
+     */
+    private readonly bound;
+    private boundCount;
+    private readonly singles;
+    private readonly images;
+    private readonly chunks;
+    private materials;
+    /**
+     * The rig, as its chunks land.
+     *
+     * **Collected here rather than dropped**, which is not a hypothetical worry about this class:
+     * the normal-map texture index was written, carried and readable for a whole release while this
+     * was the single layer that discarded it. A field the container carries and the loader does not
+     * hand on is invisible to every test of either side.
+     */
+    private loadedNodes;
+    private readonly loadedSkins;
+    private readonly loadedClips;
+    /**
+     * Deltas as their chunks land, paired to their meshes when a part is built.
+     *
+     * Collected rather than applied on arrival because a `MORP` chunk can precede the `MESH` it
+     * names, and the mesh ordinal in its payload is what makes the pairing independent of order.
+     */
+    private readonly loadedMorphs;
+    private textureSet;
+    private fit;
+    private bounds;
+    private meshShare;
+    private imageShare;
+    private state;
+    /** Set once the last byte has landed, so `update` knows when to merge. */
+    private streamed;
+    private merged;
+    private disposed;
+    private arrived;
+    constructor(renderer: RendererApi, options?: DrftLoaderOptions);
+    get progress(): DrftLoadProgress;
+    /**
+     * The parts to draw this frame. Grows while loading, then becomes the merged groups.
+     *
+     * While a coarse level is on screen it is the **first** entry, so a caller drawing them in
+     * order draws the outline behind the parts that are replacing it. It leaves the list in the
+     * same frame the merged model enters it.
+     */
+    get parts(): readonly DrftPart[];
+    /**
+     * Whether a coarse level is on screen, or held for a replay.
+     *
+     * False for most loads: the file has to carry one *and* the consumer has to have asked. It is
+     * here because a caller wording a readout needs it — with an outline, state 1 of a replay is
+     * the outline alone and state 2 is the first part, and without one the states shift down by
+     * one. A caller counting that out for itself would be guessing at what the file contained.
+     */
+    /**
+     * The asset's hierarchy, or empty for a file carrying no `NODE`.
+     *
+     * Handed on rather than consumed here, because what to do with a hierarchy is the caller's:
+     * this class draws parts, and placing them under a graph is a scene decision.
+     */
+    get nodes(): readonly DrftNode[];
+    /** Skins the file carried, in the order their chunks appeared. Empty for a file with none. */
+    get skins(): readonly DrftSkin[];
+    /** Clips the file carried, in the order their chunks appeared. Empty for a file with none. */
+    get clips(): readonly AnimationClip[];
+    /** Morph deltas the file carried, each naming the mesh ordinal it deforms. */
+    get morphs(): readonly DrftMorph[];
+    get hasOutline(): boolean;
+    /**
+     * How many states the finished reveal can be put back into, or 0 when none were kept.
+     *
+     * A **count of states rather than a fraction**, because the states are what a viewer is
+     * actually choosing between and they are not evenly spaced in anything: an outline is one
+     * thing, a part is one thing, and the merge is one thing. A caller drives it with an integer
+     * so every state is reachable — a fraction would make the outline a band 1/188th of a slider
+     * wide, which is a state nobody can stop on.
+     *
+     * State 0 is an empty stage. State 1 is the outline where the file carried one, and the first
+     * part where it did not. The last state is the finished model, drawn exactly as `ready` draws
+     * it. Everything between adds one more part, in the order the file delivered them.
+     */
+    get revealSteps(): number;
+    /**
+     * Put one state of the reveal back on screen. Needs `keepReveal`, and does nothing without it.
+     *
+     * **This is a presentation control, not a second loader.** Nothing is re-read, re-uploaded or
+     * re-merged: the meshes the load made are all still there and this decides which of them
+     * `parts` names. So it is free to call every frame, and a caller may scrub it as fast as it
+     * likes without touching the GPU.
+     */
+    replay(step: number): void;
+    /** The asset's images by the name its source gave them, or null before any have arrived. */
+    get textures(): TextureSet<SurfaceTextureHandle> | null;
+    /** The model's own bounds, from `HEAD`, which arrives before any geometry. */
+    get modelBounds(): readonly number[];
+    /**
+     * How the model was fitted: a uniform scale and an offset that centres it on the origin with
+     * its base at zero. Null until `HEAD` lands.
+     */
+    get placement(): {
+        readonly scale: number;
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    } | null;
+    /**
+     * Start loading, and resolve when the last byte has been read.
+     *
+     * Deliberately not the thing that produces the parts: the parts appear through `update`, so a
+     * caller draws its frames as usual and never awaits anything. A failed load leaves the phase at
+     * `failed` with a message rather than throwing, because a scene is usually still valid without
+     * its model and a blank screen would report the wrong problem.
+     *
+     * `fitTo` is the size the model's larger of footprint and height is scaled to fit, which is the
+     * one thing a loader cannot infer: a bought asset arrives in whatever units its author used.
+     * `baseY` is where its lowest point should sit, for a scene whose floor is not at zero — a
+     * plinth, a turntable, a deck. It defaults to zero, and getting it wrong is very visible: the
+     * first version of this had no such parameter and put a car's wheels through the turntable it
+     * was standing on.
+     *
+     * **`{ fit: 'none' }` declines all of it** — scale 1, no centring, no base — for a caller whose
+     * importer has already placed the model. See `DrftFit` for why that is a stated option rather
+     * than a very large footprint.
+     */
+    load(url: string, fitTo: DrftFit): Promise<void>;
+    /**
+     * The same load, from a container this class did not fetch.
+     *
+     * Split out because a `.drft` is not the only way a model arrives. A source format read at
+     * runtime is parsed and written to a container in a worker, and what comes back is bytes
+     * that have never been near a URL. Everything after the first byte is identical, so it would
+     * be a second copy of the stream, the upload budget, the fade and the merge, kept in step by
+     * hand. A `Response` is the seam because it is what `streamDrft` already takes, and one can
+     * be built over an `ArrayBuffer` with no copy and no server.
+     */
+    consume(response: Response, fitTo: DrftFit): Promise<void>;
+    /**
+     * Spend this frame's upload budget and advance the fades. Call once per frame.
+     *
+     * Returns whether anything changed, for a caller that wants to know it should redraw a
+     * progress readout rather than rebuild one every frame.
+     */
+    update(dtSec: number): boolean;
+    dispose(): void;
+    /**
+     * The coarse whole model, on screen until the real one is complete.
+     *
+     * **Drawn as a part rather than through a second path**, so a scene that already iterates
+     * `parts` needs no change and cannot forget it. It wears no image and no reflection, because
+     * a level of detail carries the four mandatory attributes only — see `buildCoarseLevel`, and
+     * §4.6 for why a silhouette does not pay for the roughness of a surface nobody looks at.
+     *
+     * **The replacement is atomic**, which §4.6 asks for by name: a better level takes the worse
+     * one's place in the draw list in the same call it is uploaded in, so no frame draws both and
+     * none draws neither. It keeps the fade it had, or a finer level arriving would restart it and
+     * the model would appear to flash.
+     */
+    private uploadOutline;
+    /** One part, transformed, dressed and uploaded. Returns whether it landed. */
+    private uploadOne;
+    /**
+     * Replace the per-part meshes with one per material group.
+     *
+     * Grouped by opacity and reflectivity as well as by image, because two surfaces can share a map
+     * and differ in blend: merging on the image alone means one cannot be made translucent without
+     * taking the other with it.
+     */
+    private buildGroup;
+    /**
+     * Put the merged groups on screen and throw the per-part meshes away.
+     *
+     * **In one step, once every group exists.** A frame drawn with both sets present would draw the
+     * model twice and blend its translucent surfaces against themselves, and a frame drawn with the
+     * singles already gone would show a model with holes in it. So the groups are built over as many
+     * frames as it takes and swapped in together.
+     */
+    private swapInMerged;
+    /**
+     * Rebuild the name-addressed texture set as images decode.
+     *
+     * Rebuilt rather than mutated because `TextureSet` is immutable once made, and this happens
+     * once per image rather than once per frame. Addressing by name is what stops a regroup
+     * silently reassigning an image to a different surface.
+     */
+    private rebuildTextures;
+    /** One place that writes the progress, so every field stays consistent with the phase. */
+    private set;
+}
+/**
+ * The MIME type a codec's bytes carry, or `null` for one the browser has no decoder for.
+ *
+ * **Exported because the fall-through was the bug.** This was written inline as two ternaries
+ * ending in `'image/jpeg'`, so every codec the chain did not name became a JPEG — and `CODEC_RAW`,
+ * which the baker writes for every image it could not find, was handed four bytes of pixel and a
+ * decoder that had no chance with them. Naming each codec and returning `null` for the one that is
+ * not an encoded image makes the omission a value rather than a default, and lets a test say so.
+ */
+export declare function imageTypeFor(codec: number): string;
+/**
+ * Whether a codec is decoded from its own bytes rather than through an image decoder.
+ *
+ * Raw is the only one, and it is not an encoded image at all: the bytes *are* the pixels.
+ */
+export declare function isRawCodec(codec: number): boolean;