Support for KTX2 Cubemaps (#9065)

* Support for KTX2 Cubemaps

* Discard package-lock.json

Author: MotivaCG

src/framework/handlers/basis-worker.js

@@ -202,6 +202,9 @@ function BasisWorker() {
         const hasAlpha = !!basisFile.getHasAlpha();
         const isUASTC = basisFile.isUASTC && basisFile.isUASTC();
 
+        // a six-face file is a cubemap; faces are transcoded into per-mip arrays
+        const cubemap = !!options.isCubemap;
+
         if (!width || !height || !levels) {
             basisFile.close();
             basisFile.delete();
@@ -211,8 +214,8 @@ function BasisWorker() {
         // choose the target format
         const format = chooseTargetFormat(options.deviceDetails, hasAlpha, isUASTC);
 
-        // unswizzle gggr textures under pvr compression
-        const unswizzle = !!options.isGGGR && format === 'pvr';
+        // unswizzle gggr textures under pvr compression (never applies to cubemaps)
+        const unswizzle = !cubemap && !!options.isGGGR && format === 'pvr';
 
         // convert to basis format taking into consideration platform restrictions
         let basisFormat;
@@ -235,22 +238,34 @@ function BasisWorker() {
             throw new Error(`Failed to start transcoding url=${url}`);
         }
 
-        let i;
+        const is16BitFormat = (basisFormat === BASIS_FORMAT.cTFRGB565 || basisFormat === BASIS_FORMAT.cTFRGBA4444);
 
-        const levelData = [];
-        for (let mip = 0; mip < levels; ++mip) {
-            const dstSize = basisFile.getImageTranscodedSizeInBytes(mip, 0, 0, basisFormat);
+        // transcode a single face of a single mip level into a typed array
+        const transcodeImage = (mip, face) => {
+            const dstSize = basisFile.getImageTranscodedSizeInBytes(mip, 0, face, basisFormat);
             const dst = new Uint8Array(dstSize);
 
-            if (!basisFile.transcodeImage(dst, mip, 0, 0, basisFormat, 0, -1, -1)) {
+            if (!basisFile.transcodeImage(dst, mip, 0, face, basisFormat, 0, -1, -1)) {
                 basisFile.close();
                 basisFile.delete();
                 throw new Error(`Failed to transcode image url=${url}`);
             }
 
-            const is16BitFormat = (basisFormat === BASIS_FORMAT.cTFRGB565 || basisFormat === BASIS_FORMAT.cTFRGBA4444);
+            return is16BitFormat ? new Uint16Array(dst.buffer) : dst;
+        };
 
-            levelData.push(is16BitFormat ? new Uint16Array(dst.buffer) : dst);
+        const levelData = [];
+        for (let mip = 0; mip < levels; ++mip) {
+            if (cubemap) {
+                // one entry per mip, each holding the six cubemap faces
+                const faceData = [];
+                for (let face = 0; face < 6; ++face) {
+                    faceData.push(transcodeImage(mip, face));
+                }
+                levelData.push(faceData);
+            } else {
+                levelData.push(transcodeImage(mip, 0));
+            }
         }
 
         basisFile.close();
@@ -259,7 +274,7 @@ function BasisWorker() {
         // handle unswizzle option
         if (unswizzle) {
             basisFormat = BASIS_FORMAT.cTFRGB565;
-            for (i = 0; i < levelData.length; ++i) {
+            for (let i = 0; i < levelData.length; ++i) {
                 levelData[i] = pack565(unswizzleGGGR(levelData[i]));
             }
         }
@@ -269,7 +284,7 @@ function BasisWorker() {
             width: width,
             height: height,
             levels: levelData,
-            cubemap: false,
+            cubemap: cubemap,
             transcodeTime: performanceNow() - funcStart,
             url: url,
             unswizzledGGGR: unswizzle
@@ -380,8 +395,22 @@ function BasisWorker() {
     const workerTranscode = (url, data, options) => {
         try {
             const result = transcode(url, data, options);
-            result.levels = result.levels.map(v => v.buffer);
-            self.postMessage({ url: url, data: result }, result.levels);
+
+            // replace typed arrays with their backing buffers for transfer. cubemap levels
+            // are arrays of six faces, all other levels are a single image.
+            const transfer = [];
+            result.levels = result.levels.map((level) => {
+                if (Array.isArray(level)) {
+                    return level.map((face) => {
+                        transfer.push(face.buffer);
+                        return face.buffer;
+                    });
+                }
+                transfer.push(level.buffer);
+                return level.buffer;
+            });
+
+            self.postMessage({ url: url, data: result }, transfer);
         } catch (err) {
             self.postMessage({ url: url, err: err }, null);
         }

src/framework/handlers/basis.js

@@ -169,18 +169,15 @@ class BasisQueue {
                 (callback[i])(err);
             }
         } else {
-            // (re)create typed array from the returned array buffers
-            if (data.format === PIXELFORMAT_RGB565 || data.format === PIXELFORMAT_RGBA4) {
-                // handle 16 bit formats
-                data.levels = data.levels.map((v) => {
-                    return new Uint16Array(v);
-                });
-            } else {
-                // all other
-                data.levels = data.levels.map((v) => {
-                    return new Uint8Array(v);
-                });
-            }
+            // (re)create typed array from the returned array buffers. cubemap levels are
+            // arrays of six face buffers, all other levels are a single image buffer.
+            const TypedArray = (data.format === PIXELFORMAT_RGB565 || data.format === PIXELFORMAT_RGBA4) ?
+                Uint16Array : Uint8Array;
+            data.levels = data.levels.map((level) => {
+                return Array.isArray(level) ?
+                    level.map(face => new TypedArray(face)) :
+                    new TypedArray(level);
+            });
 
             for (let i = 0; i < callback.length; ++i) {
                 (callback[i])(null, data);
@@ -330,6 +327,8 @@ let deviceDetails = null;
  * circumstances the texture will be unswizzled during transcoding.
  * @param {boolean} [options.isKTX2] - Indicates the image is KTX2 format. Otherwise
  * basis format is assumed.
+ * @param {boolean} [options.isCubemap] - Indicates the image contains six cubemap faces. Only
+ * supported for KTX2 files.
  * @returns {boolean} True if the basis worker was initialized and false otherwise.
  * @ignore
  */
@@ -345,7 +344,8 @@ function basisTranscode(device, url, data, callback, options) {
     queue.enqueueJob(url, data, callback, {
         deviceDetails: deviceDetails,
         isGGGR: !!options?.isGGGR,
-        isKTX2: !!options?.isKTX2
+        isKTX2: !!options?.isKTX2,
+        isCubemap: !!options?.isCubemap
     });
 
     return initializing;

src/framework/parsers/texture/ktx2.js

@@ -130,7 +130,9 @@ class Ktx2Parser extends TextureParser {
                 callback,
                 {
                     isGGGR: (asset?.file?.variants?.basis?.opt & 8) !== 0,
-                    isKTX2: true
+                    isKTX2: true,
+                    // a six-face ktx2 file is a cubemap
+                    isCubemap: header.faceCount === 6
                 }
             );