@zephyr3d/scene 0.9.3 → 0.9.5

package/dist/asset/assetmanager.js

@@ -1,5 +1,4 @@
-import { DWeakRef, ASSERT, base64ToUint8Array, Vector3, DRef, Vector4, VFSError, isPowerOf2, nextPowerOf2 } from '@zephyr3d/base';
-import { GLTFLoader } from './loaders/gltf/gltf_loader.js';
+import { DWeakRef, DRef, ASSERT, base64ToUint8Array, Vector3, Vector4, guessMimeType, isPowerOf2, nextPowerOf2 } 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';
@@ -24,6 +23,7 @@ import '../material/pbrsg.js';
 import { PBRBluePrintMaterial } from '../material/pbrblueprint.js';
 import '../material/sprite.js';
 import '../material/sprite_std.js';
+import '../material/msdf_text.js';
 import { SpriteBlueprintMaterial } from '../material/spriteblueprint.js';
 import { BoundingBox } from '../utility/bounding_volume.js';
 import { MaterialBlueprintIR } from '../utility/blueprint/material/ir.js';
@@ -32,6 +32,7 @@ import '../render/rendergraph/forward_plus_builder.js';
 import '../render/sky.js';
 import '../render/clipmap.js';
 import '../shaders/atmosphere.js';
+import { FontAsset } from '../text/font/font_asset.js';
 
 /**
  * Centralized asset manager for loading and caching resources.
@@ -58,12 +59,11 @@ import '../shaders/atmosphere.js';
         new HDRLoader(),
         new TGALoader()
     ];
-    /** @internal */ static _modelLoaders = [
-        new GLTFLoader()
-    ];
+    /** @internal */ _modelLoaders = {};
     /** @internal */ _textures;
     /** @internal */ _models;
     /** @internal */ _binaryDatas;
+    /** @internal */ _fontAssets;
     /** @internal */ _textDatas;
     /** @internal */ _bluePrints;
     /** @internal */ _materials;
@@ -82,6 +82,7 @@ import '../shaders/atmosphere.js';
         this._skeletons = {};
         this._bluePrints = {};
         this._binaryDatas = {};
+        this._fontAssets = {};
         this._textDatas = {};
         this._jsonDatas = {};
     }
@@ -133,11 +134,26 @@ import '../shaders/atmosphere.js';
             }
         }
         this._skeletons = {};
+        this._fontAssets = {};
         this._binaryDatas = {};
         this._textDatas = {};
         this._jsonDatas = {};
     }
     /**
+   * Removes a cached font asset entry by URL.
+   *
+   * This only evicts the cache entry. It does not dispose any external references to the FontAsset.
+   *
+   * @param url - Resource URL or VFS path.
+   * @returns `true` if a cache entry existed and was removed.
+   */ releaseFontAsset(url) {
+        if (url in this._fontAssets) {
+            delete this._fontAssets[url];
+            return true;
+        }
+        return false;
+    }
+    /**
    * Register a texture loader (highest priority first).
    *
    * Note: This is a static registry shared by all AssetManager instances.
@@ -150,13 +166,9 @@ import '../shaders/atmosphere.js';
     }
     /**
    * Register a model loader (highest priority first).
-   *
-   * Note: This is a static registry shared by all AssetManager instances.
-   *
-   * @param loader - A concrete model loader implementation.
-   */ static addModelLoader(loader) {
+   */ setModelLoader(mimeType, loader) {
         if (loader) {
-            this._modelLoaders.unshift(loader);
+            this._modelLoaders[mimeType] = loader;
         }
     }
     /**
@@ -170,11 +182,11 @@ import '../shaders/atmosphere.js';
    * @param postProcess - Optional transformation applied to the loaded text.
    * @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, VFSs) {
+   */ async fetchTextData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._textDatas[hash];
         if (!P) {
-            P = this.loadTextData(url, postProcess, VFSs);
+            P = this.loadTextData(url, postProcess, options?.overrideVFS);
             this._textDatas[hash] = P;
         }
         return P;
@@ -189,11 +201,11 @@ import '../shaders/atmosphere.js';
    * @param postProcess - Optional transformation applied to the parsed JSON object.
    * @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, VFSs) {
+   */ async fetchJsonData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._jsonDatas[hash];
         if (!P) {
-            P = this.loadJsonData(url, postProcess, VFSs);
+            P = this.loadJsonData(url, postProcess, options?.overrideVFS);
             this._jsonDatas[hash] = P;
         }
         return P;
@@ -207,20 +219,53 @@ import '../shaders/atmosphere.js';
    * @param postProcess - Optional transformation applied to the loaded ArrayBuffer.
    * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
    * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
-   */ async fetchBinaryData(url, postProcess, httpRequest, VFSs) {
+   */ async fetchBinaryData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._binaryDatas[hash];
         if (!P) {
-            P = this.loadBinaryData(url, postProcess, VFSs);
+            P = this.loadBinaryData(url, postProcess, options?.overrideVFS);
             this._binaryDatas[hash] = P;
         }
         return P;
     }
-    async fetchBluePrint(url, VFSs) {
+    /**
+   * Fetch a font asset via VFS.
+   *
+   * - Cached per URL only.
+   * - `options` are applied only when the font is first loaded for that URL.
+   * - If the URL is already cached, later calls ignore `options` and reuse the cached FontAsset.
+   *
+   * @param url - Resource URL or VFS path.
+   * @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) {
+        const hash = url;
+        let P = this._fontAssets[hash];
+        if (!P) {
+            P = new Promise((resolve, reject)=>{
+                this.loadBinaryData(url, null, options?.overrideVFS).then((data)=>{
+                    resolve(data ? FontAsset.fromBuffer(data, options) : null);
+                }).catch((err)=>{
+                    reject(new Error(`Failed to load font asset from ${url}: ${err instanceof Error ? err.message : err}`));
+                });
+            });
+            this._fontAssets[hash] = P;
+        }
+        return P;
+    }
+    /**
+   * Fetch a font asset via VFS if already cached.
+   * @param url - Resource URL or VFS path.
+   * @returns The cached FontAsset if it exists and is loaded, or null if not cached or still loading.
+   */ getFontAsset(url) {
+        const hash = url;
+        return this._fontAssets[hash] instanceof Promise ? null : this._fontAssets[hash] ?? null;
+    }
+    async fetchBluePrint(url, options) {
         const hash = url;
         let P = this._bluePrints[hash];
         if (!P) {
-            P = this.loadBluePrint(url, VFSs);
+            P = this.loadBluePrint(url, options?.overrideVFS);
             this._bluePrints[hash] = P;
         }
         return P;
@@ -231,13 +276,13 @@ import '../shaders/atmosphere.js';
    * @typeParam T - Expected concrete material type.
    * @param url - Resource URL or VFS path.
    * @returns A promise that resolves to the loaded material.
-   */ async fetchMaterial(url, VFSs) {
+   */ async fetchMaterial(url, options) {
         const hash = url;
         let P = this._materials[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
         } else if (!P || P instanceof DWeakRef) {
-            P = this.loadMaterial(url, false, VFSs);
+            P = this.loadMaterial(url, false, options?.overrideVFS);
             this._materials[hash] = P;
         }
         const material = await P;
@@ -252,13 +297,13 @@ import '../shaders/atmosphere.js';
    * @typeParam T - Expected concrete primitive type.
    * @param url - Resource URL or VFS path.
    * @returns A promise that resolves to the loaded primitive.
-   */ async fetchPrimitive(url, VFSs) {
+   */ async fetchPrimitive(url, options) {
         const hash = url;
         let P = this._primitives[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
         } else if (!P || P instanceof DWeakRef) {
-            P = this.loadPrimitive(url, VFSs);
+            P = this.loadPrimitive(url, options?.overrideVFS);
             this._primitives[hash] = P;
         }
         const primitive = await P;
@@ -280,16 +325,16 @@ import '../shaders/atmosphere.js';
    * @param options - Texture fetching options (color space, sampler, target texture).
    * @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, VFSs) {
+   */ async fetchTexture(url, options) {
         if (options?.texture) {
-            return this.loadTexture(url, options.mimeType ?? null, !options.linearColorSpace, options.samplerOptions, options.texture, VFSs);
+            return this.loadTexture(url, options.mimeType ?? null, !options.linearColorSpace, options.samplerOptions, options.texture, options.overrideVFS);
         } else {
             const hash = this.getHash('2d', url, options);
             let P = this._textures[hash];
             if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
                 return P.get();
             } else if (!P || P instanceof DWeakRef) {
-                P = this.loadTexture(url, options?.mimeType ?? null, !options?.linearColorSpace, options?.samplerOptions, null, VFSs);
+                P = this.loadTexture(url, options?.mimeType ?? null, !options?.linearColorSpace, options?.samplerOptions, null, options?.overrideVFS);
                 this._textures[hash] = P;
             }
             const tex = await P;
@@ -309,13 +354,13 @@ import '../shaders/atmosphere.js';
    * @param options - Model loader options (MIME override, Draco, instancing hint, post-process).
    * @returns A promise that resolves to the SharedModel.
    * @internal
-   */ async fetchModelData(url, options, VFSs) {
+   */ async fetchModelData(url, options) {
         const hash = url;
         let P = this._models[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
         } else if (!P || P instanceof DWeakRef) {
-            P = this.loadModel(url, options, VFSs);
+            P = this.loadModel(url, options, options?.overrideVFS);
             this._models[hash] = P;
         }
         const sharedModel = await P;
@@ -335,13 +380,21 @@ import '../shaders/atmosphere.js';
    * @param options - Model loader options and instancing hint.
    * @param httpRequest - Optional HttpRequest (unused for binary read; present for API symmetry).
    * @returns A promise with the created node group and animation set info.
-   */ async fetchModel(scene, url, options, VFSs) {
-        const sharedModel = await this.fetchModelData(url, options, VFSs);
-        const node = sharedModel.createSceneNode(scene, !!options?.enableInstancing);
-        return {
-            group: node,
-            animationSet: node.animationSet
-        };
+   *
+   * @internal
+   */ async fetchModel(scene, url, options) {
+        const sharedModel = new DRef();
+        try {
+            sharedModel.set(await this.fetchModelData(url, options));
+            const node = await sharedModel.get().createSceneNode(getEngine().resourceManager, scene, options?.enableInstancing ?? false, options?.loadMeshes ?? true, options?.loadSkeletons ?? true, options?.loadAnimations ?? true, options?.loadJointDynamics ?? true, options?.overrideVFS ?? getEngine().resourceManager.VFS);
+            node.sharedModel = sharedModel.get();
+            node.animationSet.resetSkeletonModifiers();
+            return node;
+        } catch (err) {
+            console.error(`Load model failed: ${url}: ${err}`);
+        } finally{
+            sharedModel.dispose();
+        }
     }
     /**
    * Load a text resource via VFS and optionally post-process it.
@@ -352,10 +405,10 @@ import '../shaders/atmosphere.js';
    * @param postProcess - Optional transformation applied to the text.
    * @returns A promise that resolves to the loaded (and optionally processed) text.
    * @internal
-   */ async loadTextData(url, postProcess, VFSs) {
-        let text = await this.readFileFromVFSs(url, {
+   */ async loadTextData(url, postProcess, vfs) {
+        let text = await this.readFileFromVFS(url, {
             encoding: 'utf8'
-        }, VFSs);
+        }, vfs);
         if (postProcess) {
             try {
                 text = postProcess(text);
@@ -374,10 +427,10 @@ import '../shaders/atmosphere.js';
    * @param postProcess - Optional transformation applied to the parsed JSON.
    * @returns A promise that resolves to the loaded (and optionally processed) JSON.
    * @internal
-   */ async loadJsonData(url, postProcess, VFSs) {
-        let json = JSON.parse(await this.readFileFromVFSs(url, {
+   */ async loadJsonData(url, postProcess, vfs) {
+        let json = JSON.parse(await this.readFileFromVFS(url, {
             encoding: 'utf8'
-        }, VFSs));
+        }, vfs));
         if (postProcess) {
             try {
                 json = postProcess(json);
@@ -396,11 +449,11 @@ import '../shaders/atmosphere.js';
    * @param postProcess - Optional transformation applied to the ArrayBuffer.
    * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
    * @internal
-   */ async loadBinaryData(url, postProcess, VFSs) {
+   */ async loadBinaryData(url, postProcess, vfs) {
         try {
-            let data = await this.readFileFromVFSs(url, {
+            let data = await this.readFileFromVFS(url, {
                 encoding: 'binary'
-            }, VFSs);
+            }, vfs);
             if (postProcess) {
                 data = postProcess(data);
             }
@@ -410,11 +463,11 @@ import '../shaders/atmosphere.js';
             return null;
         }
     }
-    async loadPrimitive(url, VFSs) {
+    async loadPrimitive(url, vfs) {
         try {
-            const data = await this.readFileFromVFSs(url, {
+            const data = await this.readFileFromVFS(url, {
                 encoding: 'utf8'
-            }, VFSs);
+            }, vfs);
             const content = JSON.parse(data);
             ASSERT(content.type === 'Primitive' || content.type === 'Default', `Unsupported primitive type: ${content.type}`);
             if (content.type === 'Primitive') {
@@ -480,20 +533,22 @@ import '../shaders/atmosphere.js';
             }
         }
     }
-    async loadBluePrintMaterialData(url, reload, VFSs) {
+    async loadBluePrintMaterialData(url, reload, vfs) {
         try {
             let irData;
             if (typeof url === 'string') {
-                const data = await this.readFileFromVFSs(url, {
+                const data = await this.readFileFromVFS(url, {
                     encoding: 'utf8'
-                }, VFSs);
+                }, vfs);
                 const content = JSON.parse(data);
                 ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'SpriteBluePrintMaterial', `Unsupported material type: ${content.type}`);
                 irData = content.data;
             } else {
                 irData = url;
             }
-            const ir = reload ? await this.loadBluePrint(irData.IR, VFSs) : await this.fetchBluePrint(irData.IR, VFSs);
+            const ir = reload ? await this.loadBluePrint(irData.IR, vfs) : await this.fetchBluePrint(irData.IR, vfs ? {
+                overrideVFS: vfs
+            } : undefined);
             const uniformValues = irData.uniformValues.map((v)=>({
                     ...v,
                     finalValue: v.value.length === 1 ? v.value[0] : new Float32Array(v.value)
@@ -502,8 +557,9 @@ import '../shaders/atmosphere.js';
             const textures = irData.uniformTextures;
             for (const v of textures){
                 const tex = await this.fetchTexture(v.texture, {
-                    linearColorSpace: !v.sRGB
-                }, VFSs);
+                    linearColorSpace: !v.sRGB,
+                    overrideVFS: vfs
+                });
                 uniformTextures.push({
                     ...v,
                     finalTexture: new DRef(tex),
@@ -536,19 +592,19 @@ import '../shaders/atmosphere.js';
    * @param url - Resource URL or VFS path.
    * @returns A promise that resolves to the loaded material.
    * @internal
-   */ async loadMaterial(url, reload, VFSs) {
+   */ async loadMaterial(url, reload, vfs) {
         try {
-            const data = await this.readFileFromVFSs(url, {
+            const data = await this.readFileFromVFS(url, {
                 encoding: 'utf8'
-            }, VFSs);
+            }, vfs);
             const content = JSON.parse(data);
             ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'SpriteBluePrintMaterial' || content.type === 'Default', `Unsupported material type: ${content.type}`);
             let mat;
             if (content.type === 'PBRBluePrintMaterial') {
-                const data = await this.loadBluePrintMaterialData(content.data, reload, VFSs);
+                const data = await this.loadBluePrintMaterialData(content.data, reload, vfs);
                 mat = new PBRBluePrintMaterial(data.irFragment, data.irVertex, data.uniformValues, data.uniformTextures);
             } else if (content.type === 'SpriteBluePrintMaterial') {
-                const data = await this.loadBluePrintMaterialData(content.data, reload, VFSs);
+                const data = await this.loadBluePrintMaterialData(content.data, reload, vfs);
                 mat = new SpriteBlueprintMaterial(data.irFragment, data.uniformValues, data.uniformTextures);
             } else {
                 const obj = await this._resourceManager.deserializeObject(null, content.data);
@@ -691,11 +747,11 @@ import '../shaders/atmosphere.js';
     invalidateBluePrint(path) {
         delete this._bluePrints[path];
     }
-    async loadBluePrint(path, VFSs) {
+    async loadBluePrint(path, vfs) {
         try {
-            const content = await this.readFileFromVFSs(path, {
+            const content = await this.readFileFromVFS(path, {
                 encoding: 'utf8'
-            }, VFSs);
+            }, vfs);
             const bp = JSON.parse(content);
             ASSERT(bp.type === 'PBRMaterial' || bp.type === 'SpriteMaterial' || bp.type === 'MaterialFunction', `Unsupported blueprint type: ${bp.type}`);
             const states = bp.state;
@@ -758,10 +814,10 @@ import '../shaders/atmosphere.js';
    * @param texture - Optional destination texture to populate.
    * @returns A promise that resolves to the created or populated texture.
    * @internal
-   */ async loadTexture(url, mimeType, srgb, samplerOptions, texture, VFSs) {
-        const data = await this.readFileFromVFSs(url, {
+   */ async loadTexture(url, mimeType, srgb, samplerOptions, texture, vfs) {
+        const data = await this.readFileFromVFS(url, {
             encoding: 'binary'
-        }, VFSs);
+        }, vfs);
         mimeType = mimeType ?? this.vfs.guessMIMEType(url);
         for (const loader of AssetManager._textureLoaders){
             if (!loader.supportMIMEType(mimeType)) {
@@ -848,22 +904,11 @@ import '../shaders/atmosphere.js';
    * @param options - Model load options (MIME override, Draco module, post-process hook).
    * @returns A promise that resolves to the loaded SharedModel.
    * @internal
-   */ async loadModel(url, options, VFSs) {
-        const arrayBuffer = await this.readFileFromVFSs(url, {
-            encoding: 'binary'
-        }, VFSs);
-        const mimeType = options?.mimeType || this.vfs.guessMIMEType(url);
-        const data = new Blob([
-            arrayBuffer
-        ], {
-            type: mimeType
-        });
-        const filename = this.vfs.basename(url);
-        for (const loader of AssetManager._modelLoaders){
-            if (!loader.supportMIMEType(mimeType)) {
-                continue;
-            }
-            let model = await loader.load(this, url, options?.mimeType || data.type, data, options?.dracoDecoderModule, VFSs);
+   */ async loadModel(url, options, vfs) {
+        const mimeType = options?.mimeType || guessMimeType(url);
+        const importer = this._modelLoaders[mimeType];
+        if (importer) {
+            let model = await importer.loadModel(url, vfs);
             if (!model) {
                 throw new Error(`Load asset failed: ${url}`);
             }
@@ -874,7 +919,6 @@ import '../shaders/atmosphere.js';
                     throw new Error(`Model loader post process failed: ${err}`);
                 }
             }
-            model.name = filename;
             return model;
         }
         throw new Error(`Can not find loader for asset ${url}`);
@@ -939,39 +983,26 @@ import '../shaders/atmosphere.js';
         return `${type}:${url}:${!options?.linearColorSpace}`;
     }
     /**
-   * Try reading from file from a list of VFSs
+   * Try reading from file from a VFS
    *
    * @param path - File path
    * @param options - Read options
-   * @param vfsList - VFS list
+   * @param vfs - VFS to read from
    * @returns File content
    *
    * @internal
-   */ async readFileFromVFSs(path, options, vfsList) {
-        vfsList = vfsList ?? [
-            this.vfs
-        ];
-        for (const vfs of vfsList){
-            try {
-                return await vfs.readFile(path, options);
-            } catch  {}
-        }
-        throw new VFSError(`File does not exist: ${path}`, 'ENOENT', path);
+   */ async readFileFromVFS(path, options, vfs) {
+        return await (vfs ?? this.vfs).readFile(path, options);
     }
     /**
-   * Write file to a list of VFSs
+   * Write file to a VFS
    *
    * @param path - File path
    * @param data - Data to write
    * @param options - Write options
-   * @param vfsList - Which VFSs will be written to
-   */ async writeFileToVFSs(path, data, options, vfsList) {
-        vfsList = vfsList ?? [
-            this.vfs
-        ];
-        for (const vfs of vfsList){
-            await vfs.writeFile(path, data, options);
-        }
+   * @param vfs - VFS to write to
+   */ async writeFileToVFSs(path, data, options, vfs) {
+        await (vfs ?? this.vfs).writeFile(path, data, options);
     }
 }