Skip to content

Commit e907cc6

Browse files
ibgreenibgreen
authored
feat(textures): Add WebGPU textureFormat field (#3317)
1 parent bb99df2 commit e907cc6

33 files changed

+1899
-519
lines changed

‎docs/modules/textures/README.md‎

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,39 @@ npm install @loaders.gl/core
2121

2222
## API
2323

24-
| Loader | Description |
25-
| ------------------------------------------------------------------ | ----------- |
26-
| [`BasisLoader`](/docs/modules/textures/api-reference/basis-loader) | |
24+
| Loader | Description |
25+
| ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
26+
| [`BasisLoader`](/docs/modules/textures/api-reference/basis-loader) | Basis Universal textures as `TextureLevel[][]` |
27+
| [`CompressedTextureLoader`](/docs/modules/textures/api-reference/compressed-texture-loader) | KTX, DDS and PVR mip chains as `TextureLevel[]` |
28+
| [`CrunchWorkerLoader`](/docs/modules/textures/api-reference/crunch-loader) | Crunch mip chains as `TextureLevel[]` |
2729

2830
## Return Types
2931

30-
The `BasisLoader` returns Array of Array of ArrayBuffer
32+
The compressed texture loaders in this module return `TextureLevel` objects from `@loaders.gl/schema`.
3133

32-
See [`BasisLoader`](/docs/modules/images/api-reference/image-loader) for more details on options etc.
34+
## Texture Category
35+
36+
A `TextureLevel` describes one mip level of one texture image.
37+
38+
| Field | Type | Description |
39+
| --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
40+
| `compressed` | `boolean` | Whether the mip level data is GPU-compressed. |
41+
| `shape` | `'texture-level'` | Shape tag for normalized texture-level payloads. <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" /> |
42+
| `format` | `number` | WebGL internal format enum for the decoded level. <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" /> |
43+
| `textureFormat` | `TextureFormat` | WebGPU / luma.gl style format string for the data. <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" /> |
44+
| `data` | `Uint8Array` | The bytes for this mip level. |
45+
| `width` | `number` | Width of this mip level. |
46+
| `height` | `number` | Height of this mip level. |
47+
| `levelSize` | `number` | Size in bytes for this mip level, when available. |
48+
| `hasAlpha` | `boolean` | Whether the transcoded texture contains alpha. |
49+
50+
`BasisLoader` returns `TextureLevel[][]`, preserving all images in a `.basis` or `.ktx2` asset.
51+
52+
`CompressedTextureLoader` returns `TextureLevel[]`.
53+
54+
`CrunchWorkerLoader` returns `TextureLevel[]`.
55+
56+
See [`BasisLoader`](/docs/modules/textures/api-reference/basis-loader) and [`CompressedTextureLoader`](/docs/modules/textures/api-reference/compressed-texture-loader) for loader-specific options and return shapes.
3357

3458
## Texture APIs
3559

‎docs/modules/textures/api-reference/basis-loader.md‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ A loader for Basis Universal "supercompressed" GPU textures. Extracts supercompr
1111
| File Format | [Basis Universal](https://github.com/BinomialLLC/basis_universal) |
1212
| File Extension | `.basis`, `.ktx2` |
1313
| File Type | Binary |
14-
| Data Format | Array of compressed image data objects |
14+
| Data Format | `TextureLevel[][]` |
1515
| Supported APIs | `load`, `parse` |
1616

1717
## Usage
@@ -21,18 +21,31 @@ import {BasisLoader} from '@loaders.gl/textures';
2121
import {load} from '@loaders.gl/core';
2222

2323
const miplevels = await load(url, BasisLoader, options);
24-
for (const compressedImage of miplevels) {
25-
...
24+
for (const imageLevels of miplevels) {
25+
for (const level of imageLevels) {
26+
console.log(level.format, level.textureFormat);
27+
}
2628
}
2729
```
2830

2931
## Options
3032

31-
| Option | Type | Default | Description |
32-
| ----------------------- | ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33-
| `basis.format` | String | `'auto'` | Set to one of the supported compressed texture formats. |
34-
| `basis.containerFormat` | String | `'auto'` | BasisLoader can decode KTX2 container. `ktx2` - decode data as KTX2 container with basis texture in it, `basis` - decode data as unwrapped basis texture, `auto` - detect KTX2 format by magic string |
35-
| `basis.module` | String | `'transcoder'` | Possible values: `transcoder` or `encoder`. Selects wasm module to decode the texture. `transcoder` is smaller but supports only `BasisFile`. `encoder` supports `BasisFile` and `KTX2File`. |
33+
| Option | Type | Default | Description |
34+
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
35+
| `basis.format` | `'auto' \| 'etc1' \| 'etc2' \| 'bc1' \| 'bc3' \| 'bc4' \| 'bc5' \| 'bc7-m6-opaque-only' \| 'bc7-m5' \| 'pvrtc1-4-rgb' \| 'pvrtc1-4-rgba' \| 'astc-4x4' \| 'atc-rgb' \| 'atc-rgba-interpolated-alpha' \| 'rgba32' \| 'rgb565' \| 'bgr565' \| 'rgba4444' \| {alpha, noAlpha}` | `'auto'` | Select the transcode target format, or provide separate alpha and non-alpha targets using the same set of format names. |
36+
| `basis.supportedTextureFormats` | `TextureFormat[]` | auto-detect | A list of compressed texture formats that the basis transcoder can select from when transcoding. |
37+
| `basis.containerFormat` | `'auto' \| 'ktx2' \| 'basis'` | `'auto'` | Select whether the input should be interpreted as a KTX2 container, a raw Basis file, or auto-detected from the data. |
38+
| `basis.module` | `'transcoder' \| 'encoder'` | `'transcoder'` | Select the wasm module used for decoding. `transcoder` supports `.basis`, while `encoder` supports both `.basis` and `.ktx2`. |
39+
40+
## Output
41+
42+
Each decoded mip level is returned as a `TextureLevel` with:
43+
44+
- `shape`: `'texture-level'` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
45+
- `format`: the WebGL internal format enum <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
46+
- `textureFormat`: the WebGPU texture format string corresponding to the format of the data in this texture level <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
47+
48+
When `basis.format` is `'auto'`, pass `basis.supportedTextureFormats` to select from a known set of target formats. If omitted, `BasisLoader` falls back to internal runtime capability detection.
3649

3750
## Wasm modules
3851

‎docs/modules/textures/api-reference/compressed-texture-loader.md‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@
44
<img src="https://img.shields.io/badge/From-v3.0-blue.svg?style=flat-square" alt="From-v3.0" />
55
</p>
66

7-
Loader for compressed textures in the PVR file format
7+
Loader for compressed texture containers in the KTX, DDS and PVR formats.
88

99
| Loader | Characteristic |
1010
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1111
| File Format | [PVR](http://powervr-graphics.github.io/WebGL_SDK/WebGL_SDK/Documentation/Specifications/PVR%20File%20Format.Specification.pdf), [DDS](https://docs.microsoft.com/en-us/windows/win32/direct3ddds/dx-graphics-dds-pguide), [KTX](https://github.com/KhronosGroup/KTX-Software/) |
1212
| File Extension | `.dds`, `.pvr`, `.ktx`, `.ktx2` |
1313
| File Type | Binary |
14-
| Data Format | Array of compressed image data objects |
14+
| Data Format | `TextureLevel[]` |
1515
| Supported APIs | `load`, `parse` |
1616

1717
## Usage
@@ -21,16 +21,25 @@ import {CompressedTextureLoader} from '@loaders.gl/textures';
2121
import {load} from '@loaders.gl/core';
2222

2323
const mipLevels = await load(url, CompressedTextureLoader);
24-
for (const image of mipLevels) {
25-
...
24+
for (const level of mipLevels) {
25+
console.log(level.shape, level.format, level.textureFormat);
2626
}
2727
```
2828

2929
## Data Format
3030

31-
Returns an array of image data objects representing mip levels.
31+
Returns `TextureLevel[]`, one entry per mip level.
3232

33-
`{compressed: true, format, width, height, data: ..., levelSize}`
33+
Each level includes:
34+
35+
- `shape: 'texture-level'` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
36+
- `compressed`
37+
- `format` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
38+
- `textureFormat` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
39+
- `width`
40+
- `height`
41+
- `data`
42+
- `levelSize` when available
3443

3544
## Options
3645

@@ -40,4 +49,4 @@ Returns an array of image data objects representing mip levels.
4049

4150
## Basis loader
4251

43-
From v3.1 [BasisLoader](/docs/modules/textures/api-reference/basis-loader) supports decoding KTX2 format. Applying BasisLoader for KTX2 files can possibly give results when internal ktx parser can't parse an image for some reason.
52+
Use [BasisLoader](/docs/modules/textures/api-reference/basis-loader) for KTX2 assets that need Basis transcoding.

‎docs/modules/textures/api-reference/crunch-loader.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Loader for compressed textures in the Crunch file format
1111
| File Format | [CRN](https://github.com/BinomialLLC/crunch) |
1212
| File Extension | `.crn` |
1313
| File Type | Binary |
14-
| Data Format | Array of compressed image data objects |
14+
| Data Format | `TextureLevel[]` |
1515
| Supported APIs | `load`, `parse` |
1616

1717
## Usage
@@ -21,16 +21,25 @@ import {CrunchWorkerLoader} from '@loaders.gl/textures';
2121
import {load} from '@loaders.gl/core';
2222

2323
const mipLevels = await load(url, CrunchWorkerLoader);
24-
for (const image of mipLevels) {
25-
...
24+
for (const level of mipLevels) {
25+
console.log(level.shape, level.format, level.textureFormat);
2626
}
2727
```
2828

2929
## Data Format
3030

31-
Returns an array of image data objects representing mip levels.
31+
Returns `TextureLevel[]`, one entry per mip level.
3232

33-
`{compressed: true, format, width, height, data: ..., levelSize}`
33+
Each level includes:
34+
35+
- `shape: 'texture-level'` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
36+
- `compressed`
37+
- `format` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
38+
- `textureFormat` <img src="https://img.shields.io/badge/From-v4.4-blue.svg?style=flat-square" alt="From-v4.4" />
39+
- `width`
40+
- `height`
41+
- `data`
42+
- `levelSize` when available
3443

3544
## Options
3645

‎docs/upgrade-guide.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@
22

33
## Upgrading to v4.4
44

5+
**@loaders.gl/textures**
6+
7+
- `TextureLevel` now exposes `shape`, `format`, and `textureFormat`. Use `format` for WebGL APIs and `textureFormat` for WebGPU-style or luma.gl APIs.
8+
- `BasisLoader` uses `basis.supportedTextureFormats` to control `'auto'` basis format selection, and can accept explicit `basis.format` targets.
9+
- `@loaders.gl/textures` no longer exports `selectSupportedBasisFormat` or `getSupportedGPUTextureFormats`. Pass `basis.supportedTextureFormats` to `BasisLoader` instead of using exported auto-detection helpers.
10+
511
**@loaders.gl/compression**
612

713
- `LZOCompression` was removed due to maintenance and licensing concerns with the underlying `lzo-wasm` library.

0 commit comments

Comments
 (0)