@galacean/effects-plugin-ktx2 2.9.0-alpha.2 → 2.9.0

package/dist/index.js

@@ -3,7 +3,7 @@
  * Description: Galacean Effects player Khronos Texture 2.0 plugin
  * Author: Ant Group CO., Ltd.
  * Contributors: 澄弈
- * Version: v2.9.0-alpha.2
+ * Version: v2.9.0
  */
 
 'use strict';
@@ -59,6 +59,96 @@ function _async_to_generator(fn) {
     };
 }
 
+function _set_prototype_of(o, p) {
+    _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
+        o.__proto__ = p;
+        return o;
+    };
+    return _set_prototype_of(o, p);
+}
+
+function _inherits(subClass, superClass) {
+    if (typeof superClass !== "function" && superClass !== null) {
+        throw new TypeError("Super expression must either be null or a function");
+    }
+    subClass.prototype = Object.create(superClass && superClass.prototype, {
+        constructor: {
+            value: subClass,
+            writable: true,
+            configurable: true
+        }
+    });
+    if (superClass) _set_prototype_of(subClass, superClass);
+}
+
+function _is_native_reflect_construct() {
+    // Since Reflect.construct can't be properly polyfilled, some
+    // implementations (e.g. core-js@2) don't set the correct internal slots.
+    // Those polyfills don't allow us to subclass built-ins, so we need to
+    // use our fallback implementation.
+    try {
+        // If the internal slots aren't set, this throws an error similar to
+        //   TypeError: this is not a Boolean object.
+        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
+    } catch (_) {}
+    return (_is_native_reflect_construct = function _is_native_reflect_construct() {
+        return !!result;
+    })();
+}
+
+function _construct(Parent, args, Class) {
+    if (_is_native_reflect_construct()) _construct = Reflect.construct;
+    else {
+        _construct = function construct(Parent, args, Class) {
+            var a = [
+                null
+            ];
+            a.push.apply(a, args);
+            var Constructor = Function.bind.apply(Parent, a);
+            var instance = new Constructor();
+            if (Class) _set_prototype_of(instance, Class.prototype);
+            return instance;
+        };
+    }
+    return _construct.apply(null, arguments);
+}
+
+function _get_prototype_of(o) {
+    _get_prototype_of = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of(o);
+}
+
+function _is_native_function(fn) {
+    return Function.toString.call(fn).indexOf("[native code]") !== -1;
+}
+
+function _wrap_native_super(Class) {
+    var _cache = typeof Map === "function" ? new Map() : undefined;
+    _wrap_native_super = function _wrap_native_super(Class) {
+        if (Class === null || !_is_native_function(Class)) return Class;
+        if (typeof Class !== "function") throw new TypeError("Super expression must either be null or a function");
+        if (typeof _cache !== "undefined") {
+            if (_cache.has(Class)) return _cache.get(Class);
+            _cache.set(Class, Wrapper);
+        }
+        function Wrapper() {
+            return _construct(Class, arguments, _get_prototype_of(this).constructor);
+        }
+        Wrapper.prototype = Object.create(Class.prototype, {
+            constructor: {
+                value: Wrapper,
+                enumerable: false,
+                writable: true,
+                configurable: true
+            }
+        });
+        return _set_prototype_of(Wrapper, Class);
+    };
+    return _wrap_native_super(Class);
+}
+
 function __generator(thisArg, body) {
     var _ = {
         label: 0,
@@ -157,7 +247,6 @@ typeof SuppressedError === "function" ? SuppressedError : function _SuppressedEr
 
 /**
  * KTX2 transcode target format.
- * if you modify this file, please also modify KTX2TargetFormat in binomial-workercode.ts
  */ var KTX2TargetFormat;
 (function(KTX2TargetFormat) {
     /** RGB(A) compressed format, 128 bits per 4x4 pixel block. */ KTX2TargetFormat[KTX2TargetFormat["ASTC"] = 0] = "ASTC";
@@ -184,6 +273,41 @@ function _create_class(Constructor, protoProps, staticProps) {
     return Constructor;
 }
 
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+
+function _create_for_of_iterator_helper_loose(o, allowArrayLike) {
+    var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"];
+    if (it) return (it = it.call(o)).next.bind(it);
+    // Fallback for engines without symbol support
+    if (Array.isArray(o) || (it = _unsupported_iterable_to_array(o)) || allowArrayLike && o && typeof o.length === "number") {
+        if (it) o = it;
+        var i = 0;
+        return function() {
+            if (i >= o.length) return {
+                done: true
+            };
+            return {
+                done: false,
+                value: o[i++]
+            };
+        };
+    }
+    throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+
 /**
  * @internal
  * WorkerPool, T 为发送消息的类型，U 为返回值的类型。
@@ -204,7 +328,7 @@ function _create_class(Constructor, protoProps, staticProps) {
     var _proto = WorkerPool.prototype;
     _proto.prepareWorker = function prepareWorker() {
         var count = this.limitedCount;
-        var promises = new Array(count);
+        var promises = [];
         for(var i = 0; i < count; i++){
             promises.push(this.ensureWorker(i));
         }
@@ -552,6 +676,16 @@ var KTX2Container = /*#__PURE__*/ function() {
         this.parse(buffer);
     }
     var _proto = KTX2Container.prototype;
+    /**
+   * 释放内部持有的原始二进制数据引用
+   */ _proto.clear = function clear() {
+        for(var _iterator = _create_for_of_iterator_helper_loose(this.levels), _step; !(_step = _iterator()).done;){
+            var level = _step.value;
+            level.levelData = null;
+        }
+        this.levels.length = 0;
+        this.globalData = null;
+    };
     _proto.parse = function parse(data) {
         var KTX2_IDENTIFIER = new Uint8Array([
             0xAB,
@@ -739,28 +873,6 @@ var KTX2Container = /*#__PURE__*/ function() {
     return KTX2Container;
 }();
 
-function _set_prototype_of(o, p) {
-    _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
-        o.__proto__ = p;
-        return o;
-    };
-    return _set_prototype_of(o, p);
-}
-
-function _inherits(subClass, superClass) {
-    if (typeof superClass !== "function" && superClass !== null) {
-        throw new TypeError("Super expression must either be null or a function");
-    }
-    subClass.prototype = Object.create(superClass && superClass.prototype, {
-        constructor: {
-            value: subClass,
-            writable: true,
-            configurable: true
-        }
-    });
-    if (superClass) _set_prototype_of(subClass, superClass);
-}
-
 /* eslint-disable compat/compat */ /* eslint-disable promise/no-nesting */ /**
  * 转码核心代码
  * 主线程调用时会返回 API 对象
@@ -770,27 +882,38 @@ function _inherits(subClass, superClass) {
     /**
    * ZSTD (Zstandard) decoder.
    */ var ZSTDDecoder = /*#__PURE__*/ function() {
-        function ZSTDDecoder() {}
+        function ZSTDDecoder() {
+            var _this = this;
+            this.heap = new Uint8Array(0);
+            this.instance = null;
+            this.importObject = {
+                env: {
+                    emscripten_notify_memory_growth: function() {
+                        _this.heap = new Uint8Array(_this.instance.exports.memory.buffer);
+                    }
+                }
+            };
+        }
         var _proto = ZSTDDecoder.prototype;
         _proto.init = function init(zstddecWasmModule) {
+            var _this = this;
             if (!this.initPromise) {
-                this.initPromise = WebAssembly.instantiate(zstddecWasmModule, ZSTDDecoder.IMPORT_OBJECT).then(this.initInstance);
+                this.initPromise = WebAssembly.instantiate(zstddecWasmModule, this.importObject).then(function(result) {
+                    _this.instance = result;
+                    _this.importObject.env.emscripten_notify_memory_growth();
+                });
             }
             return this.initPromise;
         };
-        _proto.initInstance = function initInstance(result) {
-            ZSTDDecoder.instance = result;
-            ZSTDDecoder.IMPORT_OBJECT.env.emscripten_notify_memory_growth();
-        };
         _proto.decode = function decode(array, uncompressedSize) {
             if (uncompressedSize === void 0) uncompressedSize = 0;
-            if (!ZSTDDecoder.instance) {
+            if (!this.instance) {
                 throw new Error("ZSTDDecoder: Await .init() before decoding.");
             }
-            var exports = ZSTDDecoder.instance.exports;
+            var exports = this.instance.exports;
             var compressedSize = array.byteLength;
             var compressedPtr = exports.malloc(compressedSize);
-            ZSTDDecoder.heap.set(array, compressedPtr);
+            this.heap.set(array, compressedPtr);
             uncompressedSize = uncompressedSize || Number(exports.ZSTD_findDecompressedSize(compressedPtr, compressedSize));
             var uncompressedPtr = exports.malloc(uncompressedSize);
             var actualSize = exports.ZSTD_decompress(uncompressedPtr, uncompressedSize, compressedPtr, compressedSize);
@@ -800,20 +923,13 @@ function _inherits(subClass, superClass) {
                 throw new Error("ZSTDDecoder: decompression failed.");
             }
             // Read decompressed data and free WASM memory
-            var dec = ZSTDDecoder.heap.slice(uncompressedPtr, uncompressedPtr + actualSize);
+            var dec = this.heap.slice(uncompressedPtr, uncompressedPtr + actualSize);
             exports.free(compressedPtr);
             exports.free(uncompressedPtr);
             return dec;
         };
         return ZSTDDecoder;
     }();
-    ZSTDDecoder.IMPORT_OBJECT = {
-        env: {
-            emscripten_notify_memory_growth: function emscripten_notify_memory_growth() {
-                ZSTDDecoder.heap = new Uint8Array(ZSTDDecoder.instance.exports.memory.buffer);
-            }
-        }
-    };
     function transcodeASTC(wasmTranscoder, compressedData, width, height) {
         var nBlocks = (width + 3 >> 2) * (height + 3 >> 2);
         var texMemoryPages = nBlocks * 16 + 65535 >> 16;
@@ -882,35 +998,45 @@ function _inherits(subClass, superClass) {
             return result;
         });
     }
-    self.onmessage = function onmessage(event) {
-        var message = event.data;
-        switch(message.type){
-            case "init":
-                initTranscoder(message.transcoderWasm).then(function() {
-                    self.postMessage("init-completed");
-                }).catch(function(error) {
-                    self.postMessage({
-                        error: error
-                    });
-                });
-                break;
-            case "transcode":
-                wasmPromise.then(function(transcoderWasmModule) {
-                    transcode(message.data, message.needZstd, transcoderWasmModule, message.zstddecWasmModule).then(function(decodedData) {
-                        self.postMessage(decodedData);
+    // 仅在 Worker 环境中注册消息处理，避免在主线程调用时污染 window.onmessage
+    // Worker 环境中没有 window 对象
+    if (typeof window === "undefined") {
+        self.onmessage = function onmessage(event) {
+            var message = event.data;
+            switch(message.type){
+                case "init":
+                    initTranscoder(message.transcoderWasm).then(function() {
+                        self.postMessage("init-completed");
                     }).catch(function(error) {
-                        return self.postMessage({
+                        self.postMessage({
                             error: error
                         });
                     });
-                }).catch(function(error) {
-                    self.postMessage({
-                        error: error
+                    break;
+                case "transcode":
+                    if (!wasmPromise) {
+                        self.postMessage({
+                            error: new Error("Transcoder not initialized.")
+                        });
+                        break;
+                    }
+                    wasmPromise.then(function(transcoderWasmModule) {
+                        transcode(message.data, message.needZstd, transcoderWasmModule, message.zstddecWasmModule).then(function(decodedData) {
+                            self.postMessage(decodedData);
+                        }).catch(function(error) {
+                            return self.postMessage({
+                                error: error
+                            });
+                        });
+                    }).catch(function(error) {
+                        self.postMessage({
+                            error: error
+                        });
                     });
-                });
-                break;
-        }
-    };
+                    break;
+            }
+        };
+    }
     // 主线程使用
     return {
         ZSTDDecoder: ZSTDDecoder,
@@ -1055,7 +1181,7 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
     _proto.initTranscodeWorkerPool = function initTranscodeWorkerPool() {
         var _this = this;
         return _async_to_generator(function() {
-            var transcoderWasm, funcCode, funcBody, returnIndex, workerCode, workerURL;
+            var transcoderWasm, workerEntryCode, workerURL;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -1081,13 +1207,10 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                         ];
                     case 3:
                         transcoderWasm = _state.sent();
-                        funcCode = TranscodeWorkerCode.toString();
-                        funcBody = funcCode.substring(funcCode.indexOf("{") + 1, funcCode.lastIndexOf("}"));
-                        // 移除主线程的 return 语句，添加 Worker 消息处理
-                        returnIndex = funcBody.lastIndexOf("return {");
-                        workerCode = funcBody.substring(0, returnIndex);
+                        // 将 TranscodeWorkerCode 整体序列化
+                        workerEntryCode = "\n      (" + TranscodeWorkerCode.toString() + ")();\n      ";
                         workerURL = URL.createObjectURL(new Blob([
-                            workerCode
+                            workerEntryCode
                         ], {
                             type: "application/javascript"
                         }));
@@ -1100,17 +1223,21 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
             });
         })();
     };
-    _proto.transcode = function transcode(ktx2Container) {
+    _proto.transcode = function transcode(ktx2Container, neededLevelCount) {
         var _this = this;
         return _async_to_generator(function() {
-            var needZstd, levelCount, faceCount, encodedData, faceIndex, mipmapData, mipmapIndex, level, levelWidth, levelHeight, originBuffer, originOffset, originByteLength, zstddecWasmModule, _tmp, faces, postMessageData;
+            var needZstd, availableLevelCount, levelCount, faceCount, encodedData, faceIndex, mipmapData, mipmapIndex, level, levelWidth, levelHeight, originBuffer, originOffset, originByteLength, zstddecWasmModule, _tmp, faces, postMessageData;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         needZstd = ktx2Container.supercompressionScheme === SupercompressionScheme.Zstd;
-                        levelCount = ktx2Container.levels.length;
+                        availableLevelCount = ktx2Container.levels.length;
+                        levelCount = neededLevelCount != null ? neededLevelCount : availableLevelCount;
+                        if (levelCount < 1 || levelCount > availableLevelCount) {
+                            throw new Error("neededLevelCount " + levelCount + " is out of range [1, " + availableLevelCount + "].");
+                        }
                         faceCount = ktx2Container.faceCount;
-                        // 准备编码数据
+                        // 准备编码数据，只处理需要的 level，避免转码后丢弃多余结果
                         encodedData = new Array(faceCount);
                         for(faceIndex = 0; faceIndex < faceCount; faceIndex++){
                             mipmapData = new Array(levelCount);
@@ -1165,6 +1292,9 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                         ];
                     case 5:
                         // WebWorker 模式
+                        if (!_this.transcodeWorkerPool) {
+                            throw new Error("KhronosTranscoder: transcodeWorkerPool is not initialized.");
+                        }
                         postMessageData = {
                             type: "transcode",
                             format: 0,
@@ -1210,14 +1340,32 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
 }(TextureTranscoder);
 
 /**
- * KTX2 加载器 - 专用于 UASTC 转 ASTC
- */ var KTX2Loader = /*#__PURE__*/ function() {
+ * KTX2 加载器插件
+ */ var KTX2Loader = /*#__PURE__*/ function(Plugin) {
+    _inherits(KTX2Loader, Plugin);
     function KTX2Loader(workerCount) {
         if (workerCount === void 0) workerCount = 0;
-        this.workerCount = workerCount;
-        this.khronosTranscoder = null;
+        var _this;
+        _this = Plugin.call(this) || this;
+        _this.workerCount = workerCount;
+        _this.khronosTranscoder = null;
+        return _this;
     }
     var _proto = KTX2Loader.prototype;
+    _proto.onAssetsLoadStart = function onAssetsLoadStart(_scene, _options) {
+        var _this = this;
+        return _async_to_generator(function() {
+            return __generator(this, function(_state) {
+                // 仅在未手动注册时才自动注册，避免覆盖用户通过 registerKTX2Loader(workerCount) 的自定义配置
+                if (!EFFECTS.textureLoaderRegistry.has("ktx2")) {
+                    registerKTX2Loader(_this.workerCount);
+                }
+                return [
+                    2
+                ];
+            });
+        })();
+    };
     /**
    * 初始化 Khronos Transcoder
    */ _proto.initKhronosTranscoder = function initKhronosTranscoder() {
@@ -1305,7 +1453,7 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
    */ _proto.loadFromBuffer = function loadFromBuffer(arrBuffer) {
         var _this = this;
         return _async_to_generator(function() {
-            var buffer, _ref, ktx2Container, result;
+            var buffer, _ref, ktx2Container, result, hasFullMipmapChain, textureOptions;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -1315,10 +1463,13 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                             _this.parseBuffer(buffer)
                         ];
                     case 1:
-                        _ref = _state.sent(), ktx2Container = _ref.ktx2Container, result = _ref.result;
+                        _ref = _state.sent(), ktx2Container = _ref.ktx2Container, result = _ref.result, hasFullMipmapChain = _ref.hasFullMipmapChain;
+                        textureOptions = _this.createTextureByBuffer(ktx2Container, result, hasFullMipmapChain);
+                        // 转码完成后释放原始 KTX2 数据
+                        ktx2Container.clear();
                         return [
                             2,
-                            _this.createTextureByBuffer(ktx2Container, result)
+                            textureOptions
                         ];
                 }
             });
@@ -1329,7 +1480,7 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
    */ _proto.loadFromURL = function loadFromURL(url) {
         var _this = this;
         return _async_to_generator(function() {
-            var buffer, _, _ref, ktx2Container, result;
+            var buffer, _, _ref, ktx2Container, result, hasFullMipmapChain, textureOptions;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -1348,10 +1499,13 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                             _this.parseBuffer(buffer)
                         ];
                     case 2:
-                        _ref = _state.sent(), ktx2Container = _ref.ktx2Container, result = _ref.result;
+                        _ref = _state.sent(), ktx2Container = _ref.ktx2Container, result = _ref.result, hasFullMipmapChain = _ref.hasFullMipmapChain;
+                        textureOptions = _this.createTextureByBuffer(ktx2Container, result, hasFullMipmapChain);
+                        // 转码完成后释放原始 KTX2 数据
+                        ktx2Container.clear();
                         return [
                             2,
-                            _this.createTextureByBuffer(ktx2Container, result)
+                            textureOptions
                         ];
                 }
             });
@@ -1359,11 +1513,11 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
     };
     /**
    * @internal
-   * 解析并转码 KTX2 文件
+   * 解析并转码 KTX2 文件 - 专用于 UASTC 转 ASTC
    */ _proto.parseBuffer = function parseBuffer(buffer) {
         var _this = this;
         return _async_to_generator(function() {
-            var ktx2Container, transcoder, result;
+            var ktx2Container, pixelWidth, pixelHeight, maxDimension, availableLevelCount, fullChainCount, hasFullMipmapChain, neededLevelCount, transcoder, result;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -1372,6 +1526,13 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                         if (!ktx2Container.isUASTC) {
                             throw new Error("Unsupported KTX2: only UASTC format is supported");
                         }
+                        // 提前判断需要转码的 level 数量，避免转码后丢弃多余结果
+                        pixelWidth = ktx2Container.pixelWidth, pixelHeight = ktx2Container.pixelHeight;
+                        maxDimension = Math.max(pixelWidth, pixelHeight);
+                        availableLevelCount = ktx2Container.levels.length;
+                        fullChainCount = maxDimension > 0 ? Math.floor(Math.log2(maxDimension)) + 1 : 1;
+                        hasFullMipmapChain = availableLevelCount > 1 && availableLevelCount >= fullChainCount;
+                        neededLevelCount = hasFullMipmapChain ? availableLevelCount : 1;
                         return [
                             4,
                             _this.ensureKhronosTranscoder()
@@ -1380,7 +1541,7 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                         transcoder = _state.sent();
                         return [
                             4,
-                            transcoder.transcode(ktx2Container)
+                            transcoder.transcode(ktx2Container, neededLevelCount)
                         ];
                     case 2:
                         result = _state.sent();
@@ -1388,7 +1549,8 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
                             2,
                             {
                                 ktx2Container: ktx2Container,
-                                result: result
+                                result: result,
+                                hasFullMipmapChain: hasFullMipmapChain
                             }
                         ];
                 }
@@ -1398,21 +1560,19 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
     /**
    * @internal
    * 根据转码结果创建引擎所需的压缩纹理源选项
-   */ _proto.createTextureByBuffer = function createTextureByBuffer(ktx2Container, transcodeResult) {
+   * @param hasFullMipmapChain - 是否包含完整 mipmap 链（由 parseBuffer 提前判断）
+   */ _proto.createTextureByBuffer = function createTextureByBuffer(ktx2Container, transcodeResult, hasFullMipmapChain) {
         var _faces_;
         var pixelWidth = ktx2Container.pixelWidth, pixelHeight = ktx2Container.pixelHeight, faceCount = ktx2Container.faceCount;
         var _this_getASTC4x4TextureDetail = this.getASTC4x4TextureDetail(), internalFormat = _this_getASTC4x4TextureDetail.internalFormat, format = _this_getASTC4x4TextureDetail.format, type = _this_getASTC4x4TextureDetail.type;
+        if (Math.max(pixelWidth, pixelHeight) === 0) {
+            throw new Error("Invalid KTX2 texture: both width and height are zero");
+        }
         var target = faceCount === 6 ? EFFECTS.glContext.TEXTURE_CUBE_MAP : EFFECTS.glContext.TEXTURE_2D;
         var faces = transcodeResult.faces;
         var _faces__length;
-        var transLevels = (_faces__length = (_faces_ = faces[0]) == null ? void 0 : _faces_.length) != null ? _faces__length : 0;
-        var maxDimension = Math.max(pixelWidth, pixelHeight);
-        if (maxDimension === 0) {
-            throw new Error("Invalid KTX2 texture: both width and height are zero");
-        }
-        var fullChainCount = Math.floor(Math.log2(maxDimension)) + 1;
-        var useMipmaps = transLevels > 1 && transLevels >= fullChainCount;
-        var levelCount = useMipmaps ? transLevels : 1;
+        // 转码时已按 neededLevelCount 截断，直接使用全部转码结果
+        var levelCount = hasFullMipmapChain ? (_faces__length = (_faces_ = faces[0]) == null ? void 0 : _faces_.length) != null ? _faces__length : 0 : 1;
         var mipmaps = [];
         for(var level = 0; level < levelCount; level++){
             for(var face = 0; face < faceCount; face++){
@@ -1453,7 +1613,7 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
         this.khronosInitPromise = undefined;
     };
     return KTX2Loader;
-}();
+}(_wrap_native_super(EFFECTS.Plugin));
 /**
  * 注册 KTX2 加载器到全局注册表
  * @param workerCount - 大于 0 时使用 WebWorker，默认使用主线程
@@ -1471,8 +1631,8 @@ function zstddecWasm(imports){return _loadWasmModule(0, null, 'AGFzbQEAAAABpQEVY
 
 /**
  * 插件版本号
- */ var version = "2.9.0-alpha.2";
-registerKTX2Loader();
+ */ var version = "2.9.0";
+EFFECTS.registerPlugin("ktx2", KTX2Loader);
 EFFECTS.logger.info("Plugin ktx2 version: " + version + ".");
 if (version !== EFFECTS__namespace.version) {
     console.error("注意：请统一 KTX2 插件与 Player 版本，不统一的版本混用会有不可预知的后果！", "\nAttention: Please ensure the KTX2 plugin is synchronized with the Player version. Mixing and matching incompatible versions may result in unpredictable consequences!");