@loaders.gl/textures 4.4.0-alpha.18 → 4.4.0-alpha.19

package/README.md

@@ -2,7 +2,7 @@
 
 [loaders.gl](https://loaders.gl/docs) is a collection of framework-independent 3D and geospatial parsers and encoders.
 
-This module contains loaders for compressed textures and [basis universal textures](https://github.com/BinomialLLC/basis_universal).
+This module contains loaders for compressed textures, Radiance HDR textures, and [basis universal textures](https://github.com/BinomialLLC/basis_universal).
 
 ## Texture Levels
 
@@ -12,11 +12,14 @@ This module contains loaders for compressed textures and [basis universal textur
 
 `CrunchLoader` returns `TextureLevel[]` for Crunch mip chains.
 
+`RadianceHDRLoader` returns a `Texture` with `shape: 'texture'`, `type: '2d'`, and one decoded `rgba32float` level for Radiance `.hdr` images.
+
 Each returned `TextureLevel` now exposes:
 
 - `shape`: always `'texture-level'`. <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
 - `format`: the corresponding WebGL internal format number. <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
 - `textureFormat`: the corresponding luma.gl / WebGPU-style texture format string. <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
+- `data`: a typed array containing the mip level payload. Compressed textures expose byte data, while `RadianceHDRLoader` exposes `Float32Array`.
 
 ```ts
 import {load} from '@loaders.gl/core';
@@ -48,4 +51,153 @@ console.log(images[0][0].format);
 console.log(images[0][0].textureFormat);
 ```
 
+## Composite Image Texture Loaders
+
+The `textures` module also exports JSON manifest loaders for image-based composite textures:
+
+- `TextureLoader` for a single image or mip chain
+- `TextureArrayLoader` for texture arrays
+- `TextureCubeLoader` for cubemaps
+- `TextureCubeArrayLoader` for cube arrays
+
+Each manifest includes a `shape` discriminator and resolves relative member URLs against the manifest URL.
+Member assets are parsed with `ImageLoader` by default, and additional loaders passed to top-level `load()` are also available for manifest members.
+These loaders return schema `Texture` objects rather than raw image trees.
+
+```ts
+import {load} from '@loaders.gl/core';
+import {BasisLoader, CompressedTextureLoader, TextureCubeLoader} from '@loaders.gl/textures';
+
+const imageCube = await load('environment.image-texture-cube.json', [
+  TextureCubeLoader,
+  CompressedTextureLoader,
+  BasisLoader
+]);
+```
+
+### Manifest Shapes
+
+Single image:
+
+```json
+{
+  "shape": "image-texture",
+  "image": "texture.png"
+}
+```
+
+Single image with mipmaps:
+
+```json
+{
+  "shape": "image-texture",
+  "mipmaps": ["texture-0.png", "texture-1.png", "texture-2.png"]
+}
+```
+
+Texture array:
+
+```json
+{
+  "shape": "image-texture-array",
+  "layers": ["layer-0.png", "layer-1.png"]
+}
+```
+
+Texture array with mipmaps:
+
+```json
+{
+  "shape": "image-texture-array",
+  "layers": [
+    ["layer-0-0.png", "layer-0-1.png"],
+    ["layer-1-0.png", "layer-1-1.png"]
+  ]
+}
+```
+
+Cubemap:
+
+```json
+{
+  "shape": "image-texture-cube",
+  "faces": {
+    "+X": "right.png",
+    "-X": "left.png",
+    "+Y": "top.png",
+    "-Y": "bottom.png",
+    "+Z": "front.png",
+    "-Z": "back.png"
+  }
+}
+```
+
+Cubemap with mipmaps:
+
+```json
+{
+  "shape": "image-texture-cube",
+  "faces": {
+    "+X": ["right-0.png", "right-1.png"],
+    "-X": ["left-0.png", "left-1.png"],
+    "+Y": ["top-0.png", "top-1.png"],
+    "-Y": ["bottom-0.png", "bottom-1.png"],
+    "+Z": ["front-0.png", "front-1.png"],
+    "-Z": ["back-0.png", "back-1.png"]
+  }
+}
+```
+
+Cube array:
+
+```json
+{
+  "shape": "image-texture-cube-array",
+  "layers": [
+    {
+      "faces": {
+        "+X": "sky-right.png",
+        "-X": "sky-left.png",
+        "+Y": "sky-top.png",
+        "-Y": "sky-bottom.png",
+        "+Z": "sky-front.png",
+        "-Z": "sky-back.png"
+      }
+    },
+    {
+      "faces": {
+        "+X": "irr-right.png",
+        "-X": "irr-left.png",
+        "+Y": "irr-top.png",
+        "-Y": "irr-bottom.png",
+        "+Z": "irr-front.png",
+        "-Z": "irr-back.png"
+      }
+    }
+  ]
+}
+```
+
+Template-driven mipmaps:
+
+```json
+{
+  "shape": "image-texture",
+  "mipLevels": "auto",
+  "template": "texture-{lod}.png"
+}
+```
+
+Template placeholders are validated strictly. Supported placeholders are:
+
+- `{lod}` for mip level
+- `{index}` for array or cube-array layer index
+- `{face}`, `{direction}`, `{axis}`, `{sign}` for cubemap faces
+
+Use `\\{` and `\\}` to include literal braces in filenames.
+
+Cube manifests use luma.gl-style face names: `'+X'`, `'-X'`, `'+Y'`, `'-Y'`, `'+Z'`, `'-Z'`. Directional aliases such as `right`, `left`, `top`, `bottom`, `front`, and `back` are still accepted for compatibility, but new manifests should use the luma.gl names.
+
+If you parse an in-memory manifest instead of loading from a URL, provide `options.core.baseUrl` so relative member URLs can still be resolved.
+
 For documentation please visit the [website](https://loaders.gl).

package/dist/basis-worker-node.js

@@ -50494,7 +50494,7 @@ function getVersion() {
       globalThis._loadersgl_.version = NPM_TAG;
       warningIssued = true;
     } else {
-      globalThis._loadersgl_.version = "4.4.0-alpha.18";
+      globalThis._loadersgl_.version = "4.4.0-alpha.19";
     }
   }
   return globalThis._loadersgl_.version;
@@ -54239,7 +54239,7 @@ if (nodeVersion2 < 18) {
 }
 
 // src/lib/utils/version.ts
-var VERSION2 = true ? "4.4.0-alpha.18" : "latest";
+var VERSION2 = true ? "4.4.0-alpha.19" : "latest";
 
 // src/lib/parsers/basis-module-loader.ts
 var BASIS_EXTERNAL_LIBRARIES = {
@@ -54358,7 +54358,7 @@ var WEBGL_TEXTURE_FORMATS = {
     "bc7-rgba-unorm",
     "bc7-rgba-unorm-srgb"
   ],
-  WEBGL_compressed_texture_etc1: ["etc1-rbg-unorm-webgl"],
+  WEBGL_compressed_texture_etc1: ["etc1-rgb-unorm-webgl"],
   WEBGL_compressed_texture_etc: [
     "etc2-rgb8unorm",
     "etc2-rgb8unorm-srgb",
@@ -54374,7 +54374,7 @@ var WEBGL_TEXTURE_FORMATS = {
   WEBGL_compressed_texture_pvrtc: [
     "pvrtc-rgb4unorm-webgl",
     "pvrtc-rgba4unorm-webgl",
-    "pvrtc-rbg2unorm-webgl",
+    "pvrtc-rgb2unorm-webgl",
     "pvrtc-rgba2unorm-webgl"
   ],
   WEBGL_compressed_texture_atc: [
@@ -54474,12 +54474,13 @@ function isKTX(data) {
 }
 
 // src/lib/parsers/parse-basis.ts
+var basisTranscodingLock = Promise.resolve();
 var BASIS_FORMAT_TO_OUTPUT_OPTIONS = {
   etc1: {
     basisFormat: 0,
     compressed: true,
     format: GL_COMPRESSED_RGB_ETC1_WEBGL,
-    textureFormat: "etc1-rbg-unorm-webgl"
+    textureFormat: "etc1-rgb-unorm-webgl"
   },
   etc2: {
     basisFormat: 1,
@@ -54581,32 +54582,47 @@ var BASIS_FORMAT_TO_OUTPUT_OPTIONS = {
 var BASIS_FORMATS = Object.freeze(
   Object.keys(BASIS_FORMAT_TO_OUTPUT_OPTIONS)
 );
+async function withBasisTranscodingLock(transcode) {
+  const previousLock = basisTranscodingLock;
+  let releaseLock;
+  basisTranscodingLock = new Promise((resolve) => {
+    releaseLock = resolve;
+  });
+  await previousLock;
+  try {
+    return await transcode();
+  } finally {
+    releaseLock();
+  }
+}
 async function parseBasis(data, options = {}) {
-  var _a;
   const loadLibraryOptions = extractLoadLibraryOptions(options);
-  if (!((_a = options.basis) == null ? void 0 : _a.containerFormat) || options.basis.containerFormat === "auto") {
-    if (isKTX(data)) {
-      const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
-      return parseKTX2File(fileConstructors.KTX2File, data, options);
-    }
-    const { BasisFile } = await loadBasisTranscoderModule(loadLibraryOptions);
-    return parseBasisFile(BasisFile, data, options);
-  }
-  switch (options.basis.module) {
-    case "encoder":
-      const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
-      switch (options.basis.containerFormat) {
-        case "ktx2":
-          return parseKTX2File(fileConstructors.KTX2File, data, options);
-        case "basis":
-        default:
-          return parseBasisFile(fileConstructors.BasisFile, data, options);
+  return await withBasisTranscodingLock(async () => {
+    var _a;
+    if (!((_a = options.basis) == null ? void 0 : _a.containerFormat) || options.basis.containerFormat === "auto") {
+      if (isKTX(data)) {
+        const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
+        return parseKTX2File(fileConstructors.KTX2File, data, options);
       }
-    case "transcoder":
-    default:
       const { BasisFile } = await loadBasisTranscoderModule(loadLibraryOptions);
       return parseBasisFile(BasisFile, data, options);
-  }
+    }
+    switch (options.basis.module) {
+      case "encoder":
+        const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
+        switch (options.basis.containerFormat) {
+          case "ktx2":
+            return parseKTX2File(fileConstructors.KTX2File, data, options);
+          case "basis":
+          default:
+            return parseBasisFile(fileConstructors.BasisFile, data, options);
+        }
+      case "transcoder":
+      default:
+        const { BasisFile } = await loadBasisTranscoderModule(loadLibraryOptions);
+        return parseBasisFile(BasisFile, data, options);
+    }
+  });
 }
 function parseBasisFile(BasisFile, data, options) {
   const basisFile = new BasisFile(new Uint8Array(data));
@@ -54752,7 +54768,7 @@ function selectSupportedBasisFormat(supportedTextureFormats = detectSupportedTex
   } else if (hasSupportedTextureFormat(textureFormats2, [
     "pvrtc-rgb4unorm-webgl",
     "pvrtc-rgba4unorm-webgl",
-    "pvrtc-rbg2unorm-webgl",
+    "pvrtc-rgb2unorm-webgl",
     "pvrtc-rgba2unorm-webgl"
   ])) {
     return {
@@ -54772,7 +54788,7 @@ function selectSupportedBasisFormat(supportedTextureFormats = detectSupportedTex
     "eac-rg11snorm"
   ])) {
     return "etc2";
-  } else if (textureFormats2.has("etc1-rbg-unorm-webgl")) {
+  } else if (textureFormats2.has("etc1-rgb-unorm-webgl")) {
     return "etc1";
   } else if (hasSupportedTextureFormat(textureFormats2, [
     "atc-rgb-unorm-webgl",

package/dist/basis-worker.js

@@ -22,7 +22,7 @@
         globalThis._loadersgl_.version = NPM_TAG;
         warningIssued = true;
       } else {
-        globalThis._loadersgl_.version = "4.4.0-alpha.18";
+        globalThis._loadersgl_.version = "4.4.0-alpha.19";
       }
     }
     return globalThis._loadersgl_.version;
@@ -382,7 +382,7 @@
   }
 
   // src/lib/utils/version.ts
-  var VERSION2 = true ? "4.4.0-alpha.18" : "latest";
+  var VERSION2 = true ? "4.4.0-alpha.19" : "latest";
 
   // src/lib/parsers/basis-module-loader.ts
   var BASIS_EXTERNAL_LIBRARIES = {
@@ -501,7 +501,7 @@
       "bc7-rgba-unorm",
       "bc7-rgba-unorm-srgb"
     ],
-    WEBGL_compressed_texture_etc1: ["etc1-rbg-unorm-webgl"],
+    WEBGL_compressed_texture_etc1: ["etc1-rgb-unorm-webgl"],
     WEBGL_compressed_texture_etc: [
       "etc2-rgb8unorm",
       "etc2-rgb8unorm-srgb",
@@ -517,7 +517,7 @@
     WEBGL_compressed_texture_pvrtc: [
       "pvrtc-rgb4unorm-webgl",
       "pvrtc-rgba4unorm-webgl",
-      "pvrtc-rbg2unorm-webgl",
+      "pvrtc-rgb2unorm-webgl",
       "pvrtc-rgba2unorm-webgl"
     ],
     WEBGL_compressed_texture_atc: [
@@ -617,12 +617,13 @@
   }
 
   // src/lib/parsers/parse-basis.ts
+  var basisTranscodingLock = Promise.resolve();
   var BASIS_FORMAT_TO_OUTPUT_OPTIONS = {
     etc1: {
       basisFormat: 0,
       compressed: true,
       format: GL_COMPRESSED_RGB_ETC1_WEBGL,
-      textureFormat: "etc1-rbg-unorm-webgl"
+      textureFormat: "etc1-rgb-unorm-webgl"
     },
     etc2: {
       basisFormat: 1,
@@ -724,31 +725,46 @@
   var BASIS_FORMATS = Object.freeze(
     Object.keys(BASIS_FORMAT_TO_OUTPUT_OPTIONS)
   );
+  async function withBasisTranscodingLock(transcode) {
+    const previousLock = basisTranscodingLock;
+    let releaseLock;
+    basisTranscodingLock = new Promise((resolve) => {
+      releaseLock = resolve;
+    });
+    await previousLock;
+    try {
+      return await transcode();
+    } finally {
+      releaseLock();
+    }
+  }
   async function parseBasis(data, options = {}) {
     const loadLibraryOptions = extractLoadLibraryOptions(options);
-    if (!options.basis?.containerFormat || options.basis.containerFormat === "auto") {
-      if (isKTX(data)) {
-        const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
-        return parseKTX2File(fileConstructors.KTX2File, data, options);
-      }
-      const { BasisFile } = await loadBasisTranscoderModule(loadLibraryOptions);
-      return parseBasisFile(BasisFile, data, options);
-    }
-    switch (options.basis.module) {
-      case "encoder":
-        const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
-        switch (options.basis.containerFormat) {
-          case "ktx2":
-            return parseKTX2File(fileConstructors.KTX2File, data, options);
-          case "basis":
-          default:
-            return parseBasisFile(fileConstructors.BasisFile, data, options);
+    return await withBasisTranscodingLock(async () => {
+      if (!options.basis?.containerFormat || options.basis.containerFormat === "auto") {
+        if (isKTX(data)) {
+          const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
+          return parseKTX2File(fileConstructors.KTX2File, data, options);
         }
-      case "transcoder":
-      default:
         const { BasisFile } = await loadBasisTranscoderModule(loadLibraryOptions);
         return parseBasisFile(BasisFile, data, options);
-    }
+      }
+      switch (options.basis.module) {
+        case "encoder":
+          const fileConstructors = await loadBasisEncoderModule(loadLibraryOptions);
+          switch (options.basis.containerFormat) {
+            case "ktx2":
+              return parseKTX2File(fileConstructors.KTX2File, data, options);
+            case "basis":
+            default:
+              return parseBasisFile(fileConstructors.BasisFile, data, options);
+          }
+        case "transcoder":
+        default:
+          const { BasisFile } = await loadBasisTranscoderModule(loadLibraryOptions);
+          return parseBasisFile(BasisFile, data, options);
+      }
+    });
   }
   function parseBasisFile(BasisFile, data, options) {
     const basisFile = new BasisFile(new Uint8Array(data));
@@ -893,7 +909,7 @@
     } else if (hasSupportedTextureFormat(textureFormats2, [
       "pvrtc-rgb4unorm-webgl",
       "pvrtc-rgba4unorm-webgl",
-      "pvrtc-rbg2unorm-webgl",
+      "pvrtc-rgb2unorm-webgl",
       "pvrtc-rgba2unorm-webgl"
     ])) {
       return {
@@ -913,7 +929,7 @@
       "eac-rg11snorm"
     ])) {
       return "etc2";
-    } else if (textureFormats2.has("etc1-rbg-unorm-webgl")) {
+    } else if (textureFormats2.has("etc1-rgb-unorm-webgl")) {
       return "etc1";
     } else if (hasSupportedTextureFormat(textureFormats2, [
       "atc-rgb-unorm-webgl",