@drawcall/lod 0.1.2 → 0.3.0

package/dist/loader/request.js

@@ -0,0 +1,59 @@
+import { ladderEntry } from "./cache.js";
+import { loaderPathURL, sourceRelativeURL } from "./url.js";
+// What a LodLoader is asked for, normalised, and the cache entries the levels it derives are saved under.
+/**
+ * Whether this runs in a production server-side build (`import.meta.env.PROD` and `SSR`), which precomputes assets
+ * into the deployed cache: every level is built and saved, and a level that cannot be saved fails the build.
+ */
+export const warmup = import.meta.env?.PROD === true && import.meta.env?.SSR === true;
+const DEFAULT_LEVELS = [{ type: "impostor" }];
+/** `request` with its URLs resolved against `path`, and every asset URL it builds from named as a dependency. */
+export function normalize(request, path) {
+    const input = typeof request === "string" ? { url: request } : request;
+    const url = loaderPathURL(input.url, path);
+    const levels = structuredClone(input.levels ?? DEFAULT_LEVELS);
+    const urls = { source: url };
+    levels.forEach((level, position) => {
+        if (level.type !== "baked")
+            return;
+        for (const name of ["low", "interior"]) {
+            const value = level[name];
+            if (value !== undefined)
+                urls[auxiliary(position + 1, name)] = sourceRelativeURL(value, url);
+        }
+    });
+    return { ...input, url, levels, urls };
+}
+/** The request of ladder level `index`, which must be a derived level. */
+export function derived(levels, index) {
+    const level = levels[index - 1];
+    if (!level || level.type === "empty")
+        throw new Error(`LodLoader: level ${index} is not derived`);
+    return level;
+}
+/** The dependency name of the low or interior asset of the baked level at ladder index `level`. */
+export const auxiliary = (level, name) => `auxiliary:${level}:${name}`;
+/** Derived level `index`'s cache entry, keyed by the inputs it is built from; undefined when the ladder is not cacheable. */
+export function levelEntry(ladder, index, dependencies, options) {
+    // Keyed by role rather than ladder position, so adding or removing another level leaves this one's entry.
+    const roles = { source: "source", low: auxiliary(index, "low"), interior: auxiliary(index, "interior") };
+    return entry(ladder, derived(ladder.levels, index), roles, dependencies, options);
+}
+/** The cache entry of the source's shape, which describes the ladder before any level is built. */
+export function shapeEntry(ladder, dependencies, options) {
+    return entry(ladder, "shape", { source: "source" }, dependencies, options);
+}
+function entry({ modules }, of, roles, dependencies, options) {
+    if (!modules)
+        return undefined;
+    const pick = (values) => Object.fromEntries(Object.entries(roles).flatMap(([role, name]) => {
+        const value = values[name];
+        return value === undefined ? [] : [[role, value]];
+    }));
+    return ladderEntry(pick(dependencies.inputs), of, pick(modules), options);
+}
+/** `entry` and the bytes it holds, read: undefined when it holds none. */
+export async function cached(entry) {
+    return { entry, bytes: await entry?.load() };
+}
+//# sourceMappingURL=request.js.map

package/dist/loader/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/loader/request.ts"],"names":[],"mappings":"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"}

package/dist/loader/url.d.ts

@@ -0,0 +1,16 @@
+/** Resolve a relative asset path without changing absolute URLs or root-relative paths. */
+export declare function loaderPathURL(url: string, base: string): string;
+export declare const urlPath: (url: string) => string;
+export declare const urlQuery: (url: string) => string;
+export declare function assetPath(url: string): {
+    path: string;
+    extension: string;
+};
+export declare function sourceRelativeURL(value: string, source: string): string;
+/**
+ * A same-origin path, as localURL leaves it, or a `file:` URL, as a `vite build` warmup sees public files: vitecache
+ * can resolve only these to project files.
+ */
+export declare const isLocal: (url: string) => boolean;
+/** Same-origin dependencies as paths, portable between development and deployment. */
+export declare function localURL(url: string): string;

package/dist/loader/url.js

@@ -0,0 +1,35 @@
+import { LoaderUtils } from "three/webgpu";
+const absolute = /^[a-z][a-z\d+.-]*:/i;
+/** An origin no URL has, to parse paths with when there is no document to resolve them against. */
+const placeholderOrigin = "https://lod.invalid";
+/** Resolve a relative asset path without changing absolute URLs or root-relative paths. */
+export function loaderPathURL(url, base) {
+    return absolute.test(url) || url.startsWith("/") ? url : LoaderUtils.resolveURL(url, base);
+}
+export const urlPath = (url) => url.replace(/[?#].*$/s, "");
+export const urlQuery = (url) => new URL(url, placeholderOrigin).search;
+export function assetPath(url) {
+    const path = urlPath(url);
+    const extension = /\.(glb|gltf|glts)$/i.exec(path)?.[1]?.toLowerCase();
+    if (!extension)
+        throw new Error(`LodLoader: cannot load "${url}": expected a .glb, .gltf or .glts file`);
+    return { path, extension };
+}
+export function sourceRelativeURL(value, source) {
+    const base = new URL(source, typeof document === "undefined" ? placeholderOrigin : document.baseURI);
+    const url = new URL(value, base);
+    return url.origin === base.origin && !absolute.test(source) ? url.pathname + url.search + url.hash : url.href;
+}
+/**
+ * A same-origin path, as localURL leaves it, or a `file:` URL, as a `vite build` warmup sees public files: vitecache
+ * can resolve only these to project files.
+ */
+export const isLocal = (url) => (url.startsWith("/") && !url.startsWith("//")) || url.startsWith("file:");
+/** Same-origin dependencies as paths, portable between development and deployment. */
+export function localURL(url) {
+    if (typeof location === "undefined" || !/^https?:/i.test(url))
+        return url;
+    const parsed = new URL(url);
+    return parsed.origin === location.origin ? parsed.pathname + parsed.search + parsed.hash : url;
+}
+//# sourceMappingURL=url.js.map

package/dist/loader/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/loader/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AACvC,mGAAmG;AACnG,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEhD,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAY;IACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,MAAM,CAAC;AAExF,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IACvE,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,yCAAyC,CAAC,CAAC;IACzG,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,MAAc;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrG,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AAChH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAE3H,sFAAsF;AACtF,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1E,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;AACjG,CAAC"}

package/dist/lod.d.ts

@@ -1,78 +1,108 @@
-import { Object3D, type Camera, type Intersection, type Raycaster } from "three/webgpu";
-import { type LevelsEventMap } from "./lazy.js";
-import { type LodLevel } from "./levels.js";
-import { WIND_BOUNDS } from "./wind/hooks.js";
+import { Object3D, type Camera, type Intersection, type LoadingManager, type Raycaster } from "three/webgpu";
+import type { LodGpu } from "./gpu.js";
+import { type LodLevel, type ThresholdedLevel } from "./levels/index.js";
+import { type LodEventMap } from "./levels/manager.js";
+import { WIND } from "./wind/hooks.js";
+export interface LodOptions {
+    /**
+     * Gets an item while levels a camera needs load, compile or fade in, ended once they are complete. Without one, a
+     * Lod nested in another's level reports to that one's, any other to three's `DefaultLoadingManager`. Wait for a
+     * quiet frame, one in which no item started or ended, rendering (or compiling) the Scene that holds the Lod a frame
+     * apart meanwhile, to capture what a camera sees complete. A Lod its renderer rendered around for a frame without
+     * updating it ends its item, and its next update starts it again. Renders of other scenes in a separate task can end
+     * the item early, and the next update reopens it; a renderer that only compiles leaves a hidden Lod's item held.
+     */
+    manager?: LoadingManager;
+}
 /**
- * Levels of detail of one object, switched by its height on screen. Level 0 is the
- * source; each further level is used while the object is at most its `maxPixels` tall
- * (see `LodLevel.maxPixels` for the defaults). Near a switch both neighbours draw and
- * split the pixels with a dither, so nothing pops; elsewhere exactly one level is visible
- * and the others are hidden. Shadows follow the camera's choice and fade with it; nothing
- * of the object is drawn into a directional light's shadow map whose texels are wider
- * than the whole object: it could cover a texel only by chance.
+ * One object's levels, switched by on-screen height with dithered fades. three's renderer calls `update` with each
+ * camera before it draws, shadow maps' included; each camera measures at the height it draws at, measured in each
+ * render (outside one, the canvas's). Orthographic cameras switch without fading. Shadows follow what the camera draws
+ * and omit casters smaller than a shadow texel; levels cast into three's shadow maps, not into a light whose shadow
+ * map a custom shadow node replaces. Nothing draws until the coarsest level that draws something has loaded, which
+ * loads first; a deferred level loads when a camera first needs it, once that one has loaded, and meanwhile the
+ * nearest loaded coarser level draws in its place.
  *
- * three's renderer calls `update(camera)` while it lists the scene (as for its own LOD),
- * before shadow maps render; the calls its shadow passes make are ignored. The height
- * uses the viewport the camera last drew one of the levels' meshes in, in CSS pixels
- * (1080 before that), so several views each get their own. An orthographic camera has
- * no distance to dither by: levels switch by on-screen size there too, but at once.
+ * Arriving levels' texture uploads are paced to about one uncompressed 2048² RGBA texture's bytes per frame. Levels
+ * are cloned into the Lod. A nested Lod switches and fades its own levels. Lines, points and sprites draw without
+ * fading. Raycasts hit the source only. A Lod draws with its LodGpu's renderer only.
  *
- * Levels are children of the Lod in its space, any Object3D: meshes, an ImpostorMesh, a
- * group, another Lod. Each mesh draws with a faded copy of its material, which every Lod
- * drawing that material shares. Lines, points and sprites are drawn but neither fade nor
- * tell the Lod the viewport height. A nested Lod hands over to its neighbours at once.
- * Raycasts hit the source only.
- *
- * Levels are read when the Lod is built: meshes added to a level later, or moved within
- * it, are neither faded nor measured right. Build a new Lod instead.
+ * Build a new Lod after adding or moving meshes within a level: geometry is measured and hooked at construction or
+ * arrival. Skinned meshes and ShaderMaterials are refused; use static meshes with node materials or supported built-in
+ * materials.
  */
-export declare class Lod extends Object3D<LevelsEventMap> {
+export declare class Lod extends Object3D<LodEventMap> {
+    private readonly gpu;
     /** Multiplies every measured height: below 1, cheaper levels take over sooner. */
     static quality: number;
     /** Tint every level by its index, to see which level draws where. */
     static debug: boolean;
-    /**
-     * Share of a level's range its fade spans: from `maxPixels × (1 - fade)` up to its
-     * `maxPixels`, the finer level draws too.
-     */
+    /** Share of a level's range its fade spans: from `maxPixels × (1 - fade)` up to its `maxPixels`, the finer level draws too. */
     static readonly fade = 0.1;
     readonly isLOD = true;
     /** Let the renderer call `update` with its camera every frame. */
     autoUpdate: boolean;
-    /** Draw only this level, without fades. */
+    /** Draw only this level, without fades, once the coarsest level that draws something has loaded. */
     forceLevel: number | null;
-    readonly levels: readonly LodLevel[];
-    private readonly entries;
-    /** Per level, how its meshes draw. */
-    private readonly draws;
-    /** Bounding sphere of the source (see the constructor) in the Lod's own space. */
+    /** The levels, each `object` this Lod's own copy once there is one. Set `maxPixels` to move a switch. */
+    readonly levels: ThresholdedLevel[];
+    /** The levels as they were given, which a copy is made from. */
+    private inputs;
+    /** Per level, where its meshes' fade comes from. */
+    private readonly fades;
+    /** Per level, whether its object is a Lod, which fades its own levels. */
+    private readonly nested;
+    /**
+     * Per loaded level, what in it may cast (see `shadowCasters`): found when it is built or joins, read every shadow
+     * map.
+     */
+    private readonly casters;
+    /** The levels as levelsToDraw reads them. */
+    private encoded;
+    /** Bounding sphere of the source (see `measureLevels`) in the Lod's own space. */
     private sphere;
     private casterRadius;
+    private loads;
     private disposed;
-    private readonly installed;
-    private fallback;
     /**
-     * `levels[0]` is the source. Empty only as the target of `copy`. A source that draws
-     * nothing (an empty Object3D, for detail another system draws) is measured by the
-     * first level that draws something.
+     * `levels[0]` is the source. Empty only as the target of `copy`. A source that draws nothing (an empty Object3D, for
+     * detail another system draws) is measured by the first level that draws something. `gpu` is what it shares with
+     * every Lod drawing with its renderer.
      */
-    constructor(levels?: Object3D[]);
+    constructor(levels: readonly LodLevel[], gpu: LodGpu, options?: LodOptions);
     private build;
-    /** Fade the meshes under `node` by `draw` and learn the viewport height from them; an inner Lod fades its own. */
+    /** Fade the meshes under `node` by `fade`; an inner Lod fades its own. */
     private hook;
-    [WIND_BOUNDS](padding: number): void;
-    /** Pick and fade levels for `camera`; three's renderer calls this itself while `autoUpdate`. */
+    /** A copy of `loaded`, level `index`'s object, parented hidden for world matrices and wind until it joins. */
+    private prepare;
+    get pending(): boolean;
+    get error(): Error | undefined;
+    /** Where the item of levels a camera misses goes (see `LodOptions.manager`). */
+    get manager(): LoadingManager;
+    set manager(manager: LoadingManager | undefined);
+    /** Switch and fade the levels for `camera`, and load those it needs. What fails is reported (see `error`): three is rendering. */
     update(camera: Camera): void;
+    /** Show the levels for `camera`, a shadow map's when `shadow`. */
+    private show;
+    /** The source's height on `camera`'s screen, and the levels as levelsToDraw reads them there. */
+    private measure;
+    /**
+     * The index of the level that draws most of the Lod's pixels for `camera` from where it is, with the levels loaded
+     * now and no arrival under way (see `drawnLevel`); null while no level it could draw is loaded.
+     */
+    getLevel(camera: Camera): number | null;
+    [WIND](padding: number): void;
     raycast(raycaster: Raycaster, intersects: Intersection[]): boolean;
     /**
-     * Copies `source`'s levels into this empty Lod (it throws otherwise). The copies share
-     * geometry, materials and textures with `source`, as three's clone does; the Lod
-     * settings and each level's `maxPixels` come along.
+     * Copies `source`'s levels into this empty Lod (it throws otherwise). The copies share geometry, materials and
+     * textures with `source`, as three's clone does; the settings, LoadingManager, wind and each level's `maxPixels`
+     * come along.
      */
     copy(source: Lod): this;
+    clone(): this;
     /**
-     * Frees every level, the source included: geometries, materials and their textures.
-     * Clones share them, so dispose a Lod only once no clone draws any more.
+     * Release what the Lod made of its levels, once nothing it prepares or compiles still uses them. Objects you give or
+     * load are yours to dispose; LodLoader's are freed when the last Lod holding them is disposed (see `LodLevel.hold`).
      */
     dispose(): void;
 }