@needle-tools/gltf-progressive 4.0.0-alpha.1 → 4.0.0-alpha.2

package/lib/extension.d.ts

@@ -24,6 +24,10 @@ type TextureLODsMinMaxInfo = {
         max_height: number;
     }>;
 };
+export type AssignTextureLODOptions = {
+    /** Force the exact requested level. Intended for explicit/debug LOD overrides. */
+    force?: boolean;
+};
 /**
  * The NEEDLE_progressive extension for the GLTFLoader is responsible for loading progressive LODs for meshes and textures.
  * This extension can be used to load different resolutions of a mesh or texture at runtime (e.g. for LODs or progressive textures).
@@ -42,8 +46,31 @@ type TextureLODsMinMaxInfo = {
 export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     /** The name of the extension */
     get name(): string;
+    /**
+     * Get the progressive mesh LOD extension data associated with a geometry.
+     * Returns the extension metadata (available LOD levels, vertex/index counts, densities) if the geometry was registered with progressive LODs, or `null` otherwise.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The mesh LOD extension data, or `null` if no progressive LODs are registered for this geometry.
+     */
     static getMeshLODExtension(geo: BufferGeometry): NEEDLE_ext_progressive_mesh | null;
+    /**
+     * Get the glTF primitive index for a geometry within its parent mesh.
+     * A single glTF mesh node can contain multiple primitives (sub-geometries). This returns which primitive the geometry corresponds to.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The zero-based primitive index, or `-1` if no LOD information is assigned to this geometry.
+     */
     static getPrimitiveIndex(geo: BufferGeometry): number;
+    /**
+     * Compute the minimum and maximum number of texture LOD levels across all textures of a material (or array of materials).
+     * Iterates over all texture slots on the material and collects LOD count ranges and per-level resolution bounds.
+     * Results are cached on the material so subsequent calls are free.
+     *
+     * @param material - A single material or an array of materials to inspect.
+     * @param minmax - Optional accumulator to merge results into (used internally for recursive calls with material arrays).
+     * @returns An object with `min_count` / `max_count` (the range of LOD levels across all textures) and a per-level `lods` array with `min_height` / `max_height`.
+     */
     static getMaterialMinMaxLODsCount(material: Material | Material[], minmax?: TextureLODsMinMaxInfo): TextureLODsMinMaxInfo;
     /** Check if a LOD level is available for a mesh or a texture
      * @param obj the mesh or texture to check
@@ -65,7 +92,10 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
      * });
      * ```
      */
-    static assignMeshLOD(mesh: Mesh, level: number): Promise<BufferGeometry | null>;
+    static assignMeshLOD(mesh: Mesh, level: number, options?: {
+        /** If false, load and return the requested geometry without assigning it to the mesh. Pass a function to apply it manually. */
+        apply?: boolean | ((geometry: BufferGeometry, level: number, mesh: Mesh) => boolean | void);
+    }): Promise<BufferGeometry | null>;
     /** Load a different resolution of a texture (if available)
      * @param context the context
      * @param source the sourceid of the file from which the texture is loaded (this is usually the component's sourceId)
@@ -73,9 +103,9 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
      * @param level the level of detail to load (0 is the highest resolution) - currently only 0 is supported
      * @returns a promise that resolves to the material or texture with the requested LOD level
      */
-    static assignTextureLOD(materialOrTexture: Material, level: number): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
-    static assignTextureLOD(materialOrTexture: Mesh, level: number): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
-    static assignTextureLOD(materialOrTexture: Texture, level: number): Promise<Texture | null>;
+    static assignTextureLOD(materialOrTexture: Material, level: number, options?: AssignTextureLODOptions): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
+    static assignTextureLOD(materialOrTexture: Mesh, level: number, options?: AssignTextureLODOptions): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
+    static assignTextureLOD(materialOrTexture: Texture, level: number, options?: AssignTextureLODOptions): Promise<Texture | null>;
     /**
      * Set the maximum number of concurrent loading tasks for LOD resources. This limits how many LOD resources (meshes or textures) can be loaded at the same time to prevent overloading the network or GPU. If the limit is reached, additional loading requests will be queued and processed as previous ones finish.
      * @default 50 on desktop, 20 on mobile devices
@@ -83,6 +113,22 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     static set maxConcurrentLoadingTasks(value: number);
     static get maxConcurrentLoadingTasks(): number;
     private static assignTextureLODForSlot;
+    private static trackedTextureSlots;
+    private static pendingTextureSlotRequests;
+    private static latestTextureSlotRequests;
+    private static textureSlotRequestId;
+    private static trackCurrentMaterialTextureSlots;
+    private static getPendingTextureSlotRequest;
+    private static nextTextureSlotRequestId;
+    private static getLatestTextureSlotRequest;
+    private static shouldApplyStaleTextureSlotLOD;
+    private static shouldApplyStaleMeshLOD;
+    private static setPendingTextureSlotRequest;
+    private static getMaterialTextureSlot;
+    private static setMaterialTextureSlot;
+    private static assignTrackedTextureSlot;
+    private static ensureTrackedTextureSlot;
+    private static releaseTrackedTextureSlot;
     private readonly parser;
     private readonly url;
     constructor(parser: GLTFParser);
@@ -90,11 +136,29 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     loadMesh: (meshIndex: number) => Promise<any> | null;
     afterRoot(gltf: GLTF): null;
     /**
-     * Register a texture with LOD information
+     * Register a texture with progressive LOD information. This associates the texture with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower resolution versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     *
+     * @param url - The source URL of the glTF file this texture was loaded from.
+     * @param tex - The three.js Texture instance to register.
+     * @param level - The LOD level this texture represents (0 = highest resolution).
+     * @param index - The texture index within the glTF file.
+     * @param ext - The parsed progressive texture extension data containing all available LOD levels and their dimensions.
      */
     static registerTexture: (url: string, tex: Texture, level: number, index: number, ext: NEEDLE_ext_progressive_texture) => void;
     /**
-     * Register a mesh with LOD information
+     * Register a mesh with progressive LOD information. This associates the mesh geometry with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower density versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     * If the mesh is registered at a level > 0 (i.e. not full resolution), a raycast mesh is automatically preserved for accurate picking.
+     *
+     * @param url - The source URL of the glTF file this mesh was loaded from.
+     * @param key - A unique key identifying this mesh's LOD group (typically derived from the extension GUID).
+     * @param mesh - The three.js Mesh instance to register.
+     * @param level - The LOD level this mesh represents (0 = highest resolution / full density).
+     * @param index - The primitive index within the glTF mesh node.
+     * @param ext - The parsed progressive mesh extension data containing all available LOD levels with vertex/index counts and densities.
      */
     static registerMesh: (url: string, key: string, mesh: Mesh, level: number, index: number, ext: NEEDLE_ext_progressive_mesh) => void;
     /**
@@ -134,7 +198,9 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     private static readonly workers;
     private static _workersIndex;
     private static getOrLoadLOD;
-    private static queue;
+    private static tryResolveLODCacheEntry;
+    private static _queue;
+    private static get queue();
     private static assignLODInformation;
     private static getAssignedLODInformation;
     private static copySettings;