illutions 0.29.1 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.30.0
+
+### Changed
+
+- Replaced `Mesh3D.setTexture()` and `TextureSlot` with `requestImageTexture()` and `getImageTexture()` to separate requesting unused GLTF images from accessing their initialized Three.js textures and assigning them directly to material slots.
+- Textures created from unused GLTF images now remain stable across progressive model levels while their image and mipmap data is updated.
+
+### Fixed
+
+- Fixed the `Obj3D.onStart()` lifecycle so it is called before GLTF model loading begins, as documented.
+
 ## 0.29.1
 
 ### Fixed
@@ -10,7 +21,7 @@
 
 ### Added
 
-- Added protected `Mesh3D.setTexture()` to assign unused GLTF images by name to the `ColorMap`, `LightMap`, or `AlphaMap` material slot, with optional UV channel and light map intensity settings; registered textures are updated across progressive model levels.
+- Added protected `Mesh3D.setTexture()` to assign unused GLTF images by name to the `ColorMap`, `LightMap`, or `AlphaMap` material slot, with optional UV channel and light map intensity settings; registered textures are updated across progressive model levels.
 - Added the exported `TextureSlot` union for the supported material slots.
 
 ## 0.28.0

package/dist/main.d.ts

@@ -1475,14 +1475,6 @@ export declare interface HemisphereCfg {
     intensity: number;
 }
 
-declare interface ImageTexture {
-    name: string;
-    material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
-    slot: TextureSlot;
-    lightMapIntensity: number;
-    channel: number;
-}
-
 /**
  * Defines the built-in engine infobox settings used to display FPS, CPU/frame timing and renderer.info values.
  * @category Cfg
@@ -1702,31 +1694,12 @@ export declare class Mesh3D extends Obj3D {
         [key: string]: any;
     }): void;
     /**
-     * Updates one or more material properties of this mesh.
-     * @param properties - Material properties to update. Texture paths are supported for `map` and `emissiveMap`.
-     * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
-     */
-    setMaterialProperties({ needsUpdate, ...properties }: {
-        needsUpdate?: boolean;
-        [key: string]: any;
-    }): void;
-    /**
-     * Loads an unused texture embedded in the current GLTF and assigns it to a material.
-     * @param options - Unused texture assignment settings.
-     * @param options.name - Name of the GLTF image used by the texture.
-     * @param options.material - Material that receives the unused texture.
-     * @param options.slot - Target material texture slot. See {@link TextureSlot}.
-     * @param options.lightMapIntensity - Light map intensity used for `LightMap`. Default: **1**
-     * @param options.channel - Texture UV channel. Default: **1**
+     * Returns an image texture requested from an unused GLTF image.
+     * @param name - GLTF image name passed to {@link requestImageTexture} during `onStart()`.
+     * @returns The initialized texture shared across progressive model levels.
      * @public
      */
-    protected setTexture({ name, material, slot, lightMapIntensity, channel }: {
-        name: string;
-        material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
-        slot: TextureSlot;
-        lightMapIntensity?: number;
-        channel?: number;
-    }): void;
+    protected getImageTexture(name: string): THREE_TYPE.Texture;
     /**
      * Called for each traversed mesh during GLTF parsing. Stores the current `THREE.Mesh` in `this.obj`.
      * @param objGltf - The currently traversed mesh.
@@ -1736,6 +1709,21 @@ export declare class Mesh3D extends Obj3D {
      * {@includeCode ../../examples/mesh3D-cube.ts}
      */
     protected onTraverse(objGltf: THREE_TYPE.Mesh): void;
+    /**
+     * Requests a Three.js texture from an unused GLTF image for initialization before the model is traversed. Call this method from `onStart()` for every unused image that will be accessed later.
+     * @param name - Name of the GLTF image.
+     * @public
+     */
+    protected requestImageTexture(name: string): void;
+    /**
+     * Updates one or more material properties of this mesh.
+     * @param properties - Material properties to update. Texture paths are supported for `map` and `emissiveMap`.
+     * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
+     */
+    setMaterialProperties({ needsUpdate, ...properties }: {
+        needsUpdate?: boolean;
+        [key: string]: any;
+    }): void;
     /* Excluded from this release type: setModel */
     /* Excluded from this release type: setReflectivesSSR */
     /* Excluded from this release type: traverse */
@@ -1776,26 +1764,25 @@ declare class Model {
     /* Excluded from this release type: sceneReady */
     private resolveSceneReady;
     private rejectSceneReady;
-    private gltf;
     private meshes;
     private scene;
-    private readonly imageTextures;
-    private readonly imageTextureInits;
+    private readonly imageNamesUnused;
+    private readonly imageTexturesUnused;
     private readonly textures;
     constructor({ canvas, cfg, events, modules, renderer, rendererReady, initFirstScene, reportModelReady, waitForRender }: ModelParams);
+    /* Excluded from this release type: addImageUnusedName */
     private addMaterialsFromMesh;
     private addTexturesFromMaterial;
     private addTexture;
-    private applyImageTexturesToMaterials;
     private disposeGeometries;
-    private disposeSourceMaterials;
-    private initImageTexture;
-    private initImageTextures;
-    private initTextures;
+    private disposeMaterialsAndTextures;
+    /* Excluded from this release type: getTextureFromImageUnused */
+    private initTextureFromImageUnused;
+    private initTexturesFromImagesUnused;
+    private initTexturesGltf;
     /* Excluded from this release type: load */
     private loadGltf;
-    private prepareImageTextures;
-    /* Excluded from this release type: prepareImageTextureForMaterial */
+    private prepareTextureImages;
     private reportError;
     private updateGeometries;
     private updateTextureImages;
@@ -2856,15 +2843,6 @@ export declare interface StateMachineCfg {
  */
 export declare type StopMode = 'all' | 'last' | 'none';
 
-/**
- * Defines the material texture slots available for unused GLTF images.
- *
- * - `ColorMap` assigns the texture to `map`. Use it with a `MeshBasicMaterial` for a fully baked color texture.
- * - `LightMap` assigns the texture to the `lightMap` slot and requires a `MeshStandardMaterial`.
- * - `AlphaMap` assigns a separate alpha texture to the `alphaMap` slot, which GLTF does not support natively.
- */
-export declare type TextureSlot = 'ColorMap' | 'LightMap' | 'AlphaMap';
-
 /** Function returned by an event subscription. Calling it removes the associated listener. */
 export declare type Unsubscribe = () => void;