@loaders.gl/textures 4.4.0-alpha.2 → 4.4.0

package/README.md

@@ -2,6 +2,202 @@
 
 [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
+
+`BasisLoader` returns `TextureLevel[][]` and preserves every image stored in a `.basis` or `.ktx2` file.
+
+`CompressedTextureLoader` returns `TextureLevel[]` for KTX, DDS and PVR container formats.
+
+`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';
+import {BasisLoader} from '@loaders.gl/textures';
+
+const images = await load('texture.ktx2', BasisLoader);
+
+console.log(images[0][0].shape);
+console.log(images[0][0].format);
+console.log(images[0][0].textureFormat);
+```
+
+Use `format` when you need the WebGL enum for legacy APIs. Use `textureFormat` when creating textures through WebGPU-style or luma.gl APIs.
+
+When `basis.format` is set to `'auto'`, you can override the default capability detection by passing a list of supported texture formats:
+
+```ts
+import {load} from '@loaders.gl/core';
+import {BasisLoader} from '@loaders.gl/textures';
+
+const images = await load('texture.basis', BasisLoader, {
+  basis: {
+    format: 'auto',
+    supportedTextureFormats: ['bc3-rgba-unorm']
+  }
+});
+
+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-loader.d.ts

@@ -1,20 +1,26 @@
 import type { LoaderOptions } from '@loaders.gl/loader-utils';
-import type { TextureLevel } from '@loaders.gl/schema';
+import type { TextureFormat, TextureLevel } from '@loaders.gl/schema';
 import { parseBasis } from "./lib/parsers/parse-basis.js";
+import type { BasisFormat } from "./lib/parsers/parse-basis.js";
+type BasisFormatOption = BasisFormat | Uppercase<BasisFormat>;
+type BasisTargetFormat = 'auto' | BasisFormatOption | {
+    alpha: BasisFormatOption;
+    noAlpha: BasisFormatOption;
+};
 /** Options for the BasisLoader */
 export type BasisLoaderOptions = LoaderOptions & {
     /** Options for the BasisLoader */
     basis?: {
-        /** Format for texture data. auto selects based on platform caps (but gl context doesn't exist on a worker thread) */
-        format: 'auto' | 'rgb565' | 'etc1s' | 'etc2' | 'astc' | 'dxt1' | 'dxt3' | 'dxt5';
-        /** @deprecated specify path of basis library */
-        libraryPath?: string;
+        /** Supported texture formats - app would typically query a WebGPU device or WebGL context to obtain the list of supported formats.*/
+        supportedTextureFormats?: TextureFormat[];
+        /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+        workerUrl?: string;
         /** What container format is used? */
-        containerFormat: 'auto' | 'ktx2' | 'basis';
+        containerFormat?: 'auto' | 'ktx2' | 'basis';
+        /** Format for texture data. auto selects based on platform caps (but gl context doesn't exist on a worker thread) */
+        format?: BasisTargetFormat;
         /** What module to use for transcoding? */
         module?: 'transcoder' | 'encoder';
-        /** Override the URL to the worker bundle (by default loads from unpkg.com) */
-        workerUrl?: string;
     };
 };
 /**
@@ -35,7 +41,6 @@ export declare const BasisWorkerLoader: {
     readonly options: {
         readonly basis: {
             readonly format: "auto";
-            readonly libraryPath: "libs/";
             readonly containerFormat: "auto";
             readonly module: "transcoder";
         };
@@ -60,10 +65,10 @@ export declare const BasisLoader: {
     readonly options: {
         readonly basis: {
             readonly format: "auto";
-            readonly libraryPath: "libs/";
             readonly containerFormat: "auto";
             readonly module: "transcoder";
         };
     };
 };
+export {};
 //# sourceMappingURL=basis-loader.d.ts.map

package/dist/basis-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basis-loader.d.ts","sourceRoot":"","sources":["../src/basis-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAS,aAAa,EAAmB,MAAM,0BAA0B,CAAC;AACtF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAC,UAAU,EAAC,qCAAkC;AAErD,kCAAkC;AAClC,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG;IAC/C,kCAAkC;IAClC,KAAK,CAAC,EAAE;QACN,qHAAqH;QACrH,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;QACjF,gDAAgD;QAChD,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,qCAAqC;QACrC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;QAC3C,0CAA0C;QAC1C,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;QAClC,8EAA8E;QAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;uBACC,YAAY,EAAE,EAAE;wBAC1B,KAAK;;;;;;;;;;;;;;;;;;CAmB8C,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,WAAW;;uBAzBO,YAAY,EAAE,EAAE;wBAC1B,KAAK;;;;;;;;;;;;;;;;;;CA2BmD,CAAC"}
+{"version":3,"file":"basis-loader.d.ts","sourceRoot":"","sources":["../src/basis-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAS,aAAa,EAAmB,MAAM,0BAA0B,CAAC;AACtF,OAAO,KAAK,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAC,UAAU,EAAC,qCAAkC;AACrD,OAAO,KAAK,EAAC,WAAW,EAAC,qCAAkC;AAE3D,KAAK,iBAAiB,GAAG,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AAC9D,KAAK,iBAAiB,GAClB,MAAM,GACN,iBAAiB,GACjB;IACE,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAEN,kCAAkC;AAClC,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG;IAC/C,kCAAkC;IAClC,KAAK,CAAC,EAAE;QACN,qIAAqI;QACrI,uBAAuB,CAAC,EAAE,aAAa,EAAE,CAAC;QAC1C,8EAA8E;QAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB,qCAAqC;QACrC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;QAC5C,qHAAqH;QACrH,MAAM,CAAC,EAAE,iBAAiB,CAAC;QAC3B,0CAA0C;QAC1C,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;KACnC,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;uBACC,YAAY,EAAE,EAAE;wBAC1B,KAAK;;;;;;;;;;;;;;;;;CAkB8C,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,WAAW;;uBAxBO,YAAY,EAAE,EAAE;wBAC1B,KAAK;;;;;;;;;;;;;;;;;CA0BmD,CAAC"}

package/dist/basis-loader.js

@@ -21,7 +21,6 @@ export const BasisWorkerLoader = {
     options: {
         basis: {
             format: 'auto',
-            libraryPath: 'libs/',
             containerFormat: 'auto',
             module: 'transcoder'
         }
@@ -34,3 +33,4 @@ export const BasisLoader = {
     ...BasisWorkerLoader,
     parse: parseBasis
 };
+//# sourceMappingURL=basis-loader.js.map

package/dist/basis-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-loader.js","sourceRoot":"","sources":["../src/basis-loader.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAIpC,OAAO,EAAC,OAAO,EAAC,+BAA4B;AAC5C,OAAO,EAAC,UAAU,EAAC,qCAAkC;AA8BrD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ,EAAE,IAAmC;IAC7C,SAAS,EAAE,IAAa;IAExB,IAAI,EAAE,OAAO;IACb,EAAE,EAAE,OAAO;IACX,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,CAAC,0BAA0B,EAAE,YAAY,CAAC;IACrD,KAAK,EAAE,CAAC,IAAI,CAAC;IACb,MAAM,EAAE,IAAI;IACZ,OAAO,EAAE;QACP,KAAK,EAAE;YACL,MAAM,EAAE,MAAM;YACd,eAAe,EAAE,MAAM;YACvB,MAAM,EAAE,YAAY;SACrB;KACF;CACqE,CAAC;AAEzE;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,GAAG,iBAAiB;IACpB,KAAK,EAAE,UAAU;CAC0D,CAAC"}