@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/asset/assetmanager.js

@@ -1,24 +1,25 @@
-import { DWeakRef, DRef, ASSERT, base64ToUint8Array, Vector3, Vector4, guessMimeType, isPowerOf2, nextPowerOf2 } from '@zephyr3d/base';
+import { isZmshBinary, readZmshBinary, decodeZmshBinary } from './zmsh_binary.js';
+import { getMeshoptDecoder } from './meshopt_decoder.js';
+import { DWeakRef, DRef, ASSERT, base64ToUint8Array, Vector3, Vector4, guessMimeType } from '@zephyr3d/base';
 import { WebImageLoader } from './loaders/image/webimage_loader.js';
 import { DDSLoader } from './loaders/dds/dds_loader.js';
 import { HDRLoader } from './loaders/hdr/hdr.js';
-import { Primitive } from '../render/primitive.js';
-import '@zephyr3d/device';
-import { getEngine, getDevice } from '../app/api.js';
-import { CopyBlitter } from '../blitter/copy.js';
 import { getSheenLutLoader } from './builtin.js';
 import { BUILTIN_ASSET_TEXTURE_SHEEN_LUT } from '../values.js';
 import { TGALoader } from './loaders/image/tga_Loader.js';
+import { KTX2Loader } from './loaders/ktx2/ktx2_loader.js';
+import { getEngine, getDevice } from '../app/api.js';
 import '../material/shader/helper.js';
 import '../material/lambert.js';
 import '../material/blinn.js';
 import '../material/unlit.js';
+import '../material/meshmaterial.js';
 import '../material/particle.js';
 import '../material/subsurfaceprofile.js';
-import '../material/skin.js';
+import '../material/sssprofile.js';
+import '../material/sss.js';
 import '../material/eye.js';
 import { Material } from '../material/material.js';
-import '../material/meshmaterial.js';
 import '../material/hair.js';
 import '../material/hairstrand.js';
 import '../material/grassmaterial.js';
@@ -35,15 +36,23 @@ import { BoundingBox } from '../utility/bounding_volume.js';
 import { MaterialBlueprintIR } from '../utility/blueprint/material/ir.js';
 import { getDefaultTexture2D } from '../utility/blueprint/material/texture.js';
 import '../render/render_queue.js';
+import { Primitive } from '../render/primitive.js';
+import '@zephyr3d/device';
 import '../render/rendergraph/forward_plus_builder.js';
 import '../render/lightpass.js';
 import '../render/sky.js';
 import '../render/clipmap.js';
 import '../render/envlight.js';
+import '../render/lod.js';
 import '../render/dualdepthpeeling_oit.js';
 import '../shaders/atmosphere.js';
+import '../render/water_interaction.js';
 import '../render/rendergraph/scene_render_context.js';
+import '../render/sdf/scene_sdf.js';
+import '../render/sdf/global_sdf.js';
+import '../render/gi/voxelize_pass.js';
 import { FontAsset } from '../text/font/font_asset.js';
+import { getRecordableOptions } from './asset_preload.js';
 
 /**
  * Centralized asset manager for loading and caching resources.
@@ -60,6 +69,24 @@ import { FontAsset } from '../text/font/font_asset.js';
  *
  * @public
  */ class AssetManager {
+    /**
+   * Optional redirect consulted before a texture or primitive is read, see
+   * {@link AssetSourceResolver}. Scene objects keep what they already loaded; call
+   * invalidateAsset() on the path when the resolver's answer changes so later
+   * loads pick it up.
+   */ assetSourceResolver = null;
+    /** @internal */ async resolveAssetSource(url, kind, vfs) {
+        // An explicit VFS means the caller wants that file system's bytes, not a substitute
+        if (!this.assetSourceResolver || vfs) {
+            return null;
+        }
+        try {
+            return await this.assetSourceResolver(url, kind);
+        } catch (err) {
+            console.warn(`Asset source resolver failed for ${url}, loading the file itself: ${err}`);
+            return null;
+        }
+    }
     /** @internal */ static _builtinTextures = {};
     /** @internal */ static _builtinTextureLoaders = {
         [BUILTIN_ASSET_TEXTURE_SHEEN_LUT]: getSheenLutLoader(64)
@@ -68,7 +95,8 @@ import { FontAsset } from '../text/font/font_asset.js';
         new WebImageLoader(),
         new DDSLoader(),
         new HDRLoader(),
-        new TGALoader()
+        new TGALoader(),
+        new KTX2Loader()
     ];
     /** @internal */ _modelLoaders = {};
     /** @internal */ _textures;
@@ -84,6 +112,7 @@ import { FontAsset } from '../text/font/font_asset.js';
     /** @internal */ _cacheKeysByPath;
     /** @internal */ _cachePathByKey;
     /** @internal */ _resourceManager;
+    /** @internal */ _requestListeners;
     /**
    * Creates an instance of AssetManager
    */ constructor(resourceManager){
@@ -100,6 +129,42 @@ import { FontAsset } from '../text/font/font_asset.js';
         this._jsonDatas = {};
         this._cacheKeysByPath = new Map();
         this._cachePathByKey = new Map();
+        this._requestListeners = new Set();
+    }
+    /**
+   * Watches the fetches made from now on, to record them for {@link AssetPreloader}.
+   *
+   * @remarks
+   * Only fetches that can be made again from a recording are reported: not those
+   * reading from another VFS, loading into an existing texture, or post-processing
+   * through a callback. Fetching is unchanged.
+   *
+   * @param listener - Called with each fetch as it is made, cached or not
+   */ addRequestListener(listener) {
+        this._requestListeners.add(listener);
+    }
+    /** Stops a listener added by {@link AssetManager.addRequestListener} */ removeRequestListener(listener) {
+        this._requestListeners.delete(listener);
+    }
+    /** @internal */ notifyRequest(type, url, options, replayable = true) {
+        if (this._requestListeners.size === 0 || !replayable) {
+            return;
+        }
+        const recordable = getRecordableOptions(options);
+        if (!recordable) {
+            return;
+        }
+        const request = Object.keys(recordable).length > 0 ? {
+            type,
+            url,
+            options: recordable
+        } : {
+            type,
+            url
+        };
+        for (const listener of this._requestListeners){
+            listener(request);
+        }
     }
     /**
    * VFS used to read resources (files, URLs, virtual mounts).
@@ -306,6 +371,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
    * @returns A promise that resolves to the loaded (and optionally processed) text.
    */ async fetchTextData(url, postProcess, httpRequest, options) {
+        this.notifyRequest('text', url, options, !postProcess && !httpRequest);
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._textDatas[hash];
         if (!P) {
@@ -326,6 +392,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
    * @returns A promise that resolves to the loaded (and optionally processed) JSON value.
    */ async fetchJsonData(url, postProcess, httpRequest, options) {
+        this.notifyRequest('json', url, options, !postProcess && !httpRequest);
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._jsonDatas[hash];
         if (!P) {
@@ -346,6 +413,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param options - Optional fetch options
    * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
    */ async fetchBinaryData(url, postProcess, httpRequest, options) {
+        this.notifyRequest('binary', url, options, !postProcess && !httpRequest);
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._binaryDatas[hash];
         if (!P) {
@@ -366,6 +434,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param options - Optional MSDF atlas settings bound to the loaded FontAsset.
    * @returns A promise that resolves to the loaded (and optionally processed) font asset.
    */ async fetchFontAsset(url, options) {
+        this.notifyRequest('font', url, options);
         const hash = url;
         let P = this._fontAssets[hash];
         if (!P) {
@@ -390,6 +459,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         return this._fontAssets[hash] instanceof Promise ? null : this._fontAssets[hash] ?? null;
     }
     async fetchBluePrint(url, options) {
+        this.notifyRequest('blueprint', url, options);
         const hash = url;
         let P = this._bluePrints[hash];
         if (!P) {
@@ -406,6 +476,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param url - Resource URL or VFS path.
    * @returns A promise that resolves to the loaded material.
    */ async fetchMaterial(url, options) {
+        this.notifyRequest('material', url, options);
         const hash = url;
         let P = this._materials[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
@@ -428,6 +499,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param url - Resource URL or VFS path.
    * @returns A promise that resolves to the loaded primitive.
    */ async fetchPrimitive(url, options) {
+        this.notifyRequest('primitive', url, options);
         const hash = url;
         let P = this._primitives[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
@@ -457,6 +529,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @param httpRequest - Optional HttpRequest (not used for binary read but may supply URL resolver for hashing).
    * @returns A promise that resolves to the loaded texture.
    */ async fetchTexture(url, options) {
+        this.notifyRequest('texture', url, options);
         if (options?.texture) {
             return this.loadTexture(url, options.mimeType ?? null, !options.linearColorSpace, options.samplerOptions, options.texture, options.overrideVFS);
         } else {
@@ -487,7 +560,9 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @returns A promise that resolves to the SharedModel.
    * @internal
    */ async fetchModelData(url, options) {
-        const hash = url;
+        this.notifyRequest('model', url, options);
+        // The same model with and without levels of detail are different models
+        const hash = options?.generateLods ? `${url}#lod:${JSON.stringify(options.generateLods)}` : url;
         let P = this._models[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
@@ -598,10 +673,13 @@ import { FontAsset } from '../text/font/font_asset.js';
     }
     async loadPrimitive(url, vfs) {
         try {
-            const data = await this.readFileFromVFS(url, {
-                encoding: 'utf8'
+            const raw = (await this.resolveAssetSource(url, 'primitive', vfs))?.data ?? await this.readFileFromVFS(url, {
+                encoding: 'binary'
             }, vfs);
-            const content = JSON.parse(data);
+            if (isZmshBinary(raw)) {
+                return await this.createPrimitiveFromZmshBinary(raw);
+            }
+            const content = JSON.parse(new TextDecoder().decode(raw));
             ASSERT(content.type === 'Primitive' || content.type === 'Default', `Unsupported primitive type: ${content.type}`);
             if (content.type === 'Primitive') {
                 const data = content.data;
@@ -639,6 +717,25 @@ import { FontAsset } from '../text/font/font_asset.js';
             return null;
         }
     }
+    /** @internal */ async createPrimitiveFromZmshBinary(raw) {
+        const meshopt = readZmshBinary(raw).header.encoding === 'meshopt';
+        const { header, vertexData, indexData } = decodeZmshBinary(raw, meshopt ? await getMeshoptDecoder() : null);
+        const primitive = new Primitive();
+        header.attributes.forEach((a, i)=>primitive.createAndSetVertexBuffer(a.format, vertexData[i]));
+        if (indexData) {
+            primitive.createAndSetIndexBuffer(indexData);
+        }
+        primitive.primitiveType = header.primitiveType;
+        if (header.lods && header.lods.length > 0) {
+            primitive.indexStart = header.lods[0].indexStart;
+            primitive.indexCount = header.lods[0].indexCount;
+            primitive.lods = header.lods.slice(1);
+        } else {
+            primitive.indexCount = header.indexCount;
+        }
+        primitive.setBoundingVolume(new BoundingBox(new Vector3(header.boxMin[0], header.boxMin[1], header.boxMin[2]), new Vector3(header.boxMax[0], header.boxMax[1], header.boxMax[2])));
+        return primitive;
+    }
     async reloadBluePrintMaterials(filter) {
         const promises = [];
         const paths = [];
@@ -1038,10 +1135,11 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @returns A promise that resolves to the created or populated texture.
    * @internal
    */ async loadTexture(url, mimeType, srgb, samplerOptions, texture, vfs) {
-        const data = await this.readFileFromVFS(url, {
+        const redirected = await this.resolveAssetSource(url, 'texture', vfs);
+        const data = redirected?.data ?? await this.readFileFromVFS(url, {
             encoding: 'binary'
         }, vfs);
-        mimeType = mimeType ?? this.vfs.guessMIMEType(url);
+        mimeType = redirected?.mimeType ?? mimeType ?? this.vfs.guessMIMEType(url);
         for (const loader of AssetManager._textureLoaders){
             if (!loader.supportMIMEType(mimeType)) {
                 continue;
@@ -1055,8 +1153,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         throw new Error(`Can not find loader for asset ${url}`);
     }
     /**
-   * Internal routine that executes the texture load using a specific loader and applies
-   * backend-specific compatibility steps (e.g., WebGL NPOT/sRGB rules).
+   * Internal routine that executes the texture load using a specific loader.
    *
    * @param loader - Concrete loader to use for decoding/creation.
    * @param mimeType - Texture MIME type.
@@ -1067,54 +1164,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @returns A promise that resolves to the created or populated texture.
    * @internal
    */ async doLoadTexture(loader, mimeType, data, srgb, samplerOptions, texture) {
-        const device = getDevice();
-        if (device.type !== 'webgl') {
-            return await loader.load(mimeType, data, srgb, samplerOptions, texture);
-        } else {
-            let tex = await loader.load(mimeType, data, srgb, samplerOptions);
-            if (tex) {
-                if (texture) {
-                    const magFilter = tex.width !== texture.width || tex.height !== texture.height ? 'linear' : 'nearest';
-                    const minFilter = magFilter;
-                    const mipFilter = 'none';
-                    const sampler = device.createSampler({
-                        addressU: 'clamp',
-                        addressV: 'clamp',
-                        magFilter,
-                        minFilter,
-                        mipFilter
-                    });
-                    const blitter = new CopyBlitter();
-                    blitter.blit(tex, texture, sampler);
-                    tex = texture;
-                } else {
-                    const po2_w = isPowerOf2(tex.width);
-                    const po2_h = isPowerOf2(tex.height);
-                    const srgb = tex.isSRGBFormat();
-                    if (srgb || !po2_w || !po2_h) {
-                        const newWidth = po2_w ? tex.width : nextPowerOf2(tex.width);
-                        const newHeight = po2_h ? tex.height : nextPowerOf2(tex.height);
-                        const magFilter = newWidth !== tex.width || newHeight !== tex.height ? 'linear' : 'nearest';
-                        const minFilter = magFilter;
-                        const mipFilter = 'none';
-                        const sampler = device.createSampler({
-                            addressU: 'clamp',
-                            addressV: 'clamp',
-                            magFilter,
-                            minFilter,
-                            mipFilter
-                        });
-                        const destFormat = srgb ? 'rgba8unorm' : tex.format;
-                        const blitter = new CopyBlitter();
-                        const newTexture = tex.isTexture2D() ? device.createTexture2D(destFormat, newWidth, newHeight) : device.createCubeTexture(destFormat, newWidth);
-                        blitter.blit(tex, newTexture, sampler);
-                        tex.dispose();
-                        tex = newTexture;
-                    }
-                }
-            }
-            return tex;
-        }
+        return await loader.load(mimeType, data, srgb, samplerOptions, texture);
     }
     /**
    * Load a model via registered model loaders.
@@ -1131,7 +1181,9 @@ import { FontAsset } from '../text/font/font_asset.js';
         const mimeType = options?.mimeType || guessMimeType(url);
         const importer = this._modelLoaders[mimeType];
         if (importer) {
-            let model = await importer.loadModel(url, vfs);
+            let model = await importer.loadModel(url, vfs, options?.generateLods ? {
+                generateLods: options.generateLods
+            } : undefined);
             if (!model) {
                 throw new Error(`Load asset failed: ${url}`);
             }