@loaders.gl/textures

loaders.gl is a collection of framework-independent 3D and geospatial parsers and encoders.

This module contains loaders for compressed textures, Radiance HDR textures, and basis universal textures.

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'.
format: the corresponding WebGL internal format number.
textureFormat: the corresponding luma.gl / WebGPU-style texture format string.
data: a typed array containing the mip level payload. Compressed textures expose byte data, while RadianceHDRLoader exposes Float32Array.

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:

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.

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:

{
  "shape": "image-texture",
  "image": "texture.png"
}

Single image with mipmaps:

{
  "shape": "image-texture",
  "mipmaps": ["texture-0.png", "texture-1.png", "texture-2.png"]
}

Texture array:

{
  "shape": "image-texture-array",
  "layers": ["layer-0.png", "layer-1.png"]
}

Texture array with mipmaps:

{
  "shape": "image-texture-array",
  "layers": [
    ["layer-0-0.png", "layer-0-1.png"],
    ["layer-1-0.png", "layer-1-1.png"]
  ]
}

Cubemap:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

Current Tags

4.0.0-alpha.5 ... beta (4 years ago)
3.1.7 ... latest (4 years ago)

65 Versions

3.1.7 ... 4 years ago
3.1.6 ... 4 years ago
3.1.5 ... 4 years ago
3.1.4 ... 4 years ago
4.0.0-alpha.5 ... 4 years ago
3.1.3 ... 4 years ago
3.1.2 ... 4 years ago
3.1.1 ... 4 years ago
3.0.14 ... 4 years ago
3.1.0 ... 4 years ago
3.1.0-beta.7 ... 4 years ago
3.1.0-beta.5 ... 4 years ago
3.1.0-beta.3 ... 4 years ago
3.0.13 ... 4 years ago
3.1.0-beta.2 ... 4 years ago
3.1.0-beta.1 ... 4 years ago
3.1.0-alpha.5 ... 4 years ago
4.0.0-alpha.4 ... 4 years ago
4.0.0-alpha.3 ... 4 years ago
4.0.0-alpha.1 ... 4 years ago
3.1.0-alpha.4 ... 5 years ago
3.1.0-alpha.3 ... 5 years ago
3.0.12 ... 5 years ago
3.1.0-alpha.2 ... 5 years ago
3.1.0-alpha.1 ... 5 years ago
3.0.11 ... 5 years ago
3.0.10 ... 5 years ago
3.0.9 ... 5 years ago
3.0.8 ... 5 years ago
3.0.7 ... 5 years ago
3.0.6 ... 5 years ago
3.0.5 ... 5 years ago
3.0.4 ... 5 years ago
3.0.3 ... 5 years ago
3.0.2 ... 5 years ago
3.0.1 ... 5 years ago
3.0.0-beta.10 ... 5 years ago
3.0.0-beta.9 ... 5 years ago
3.0.0-beta.8 ... 5 years ago
3.0.0-beta.7 ... 5 years ago
3.0.0-beta.6 ... 5 years ago
3.0.0-beta.5 ... 5 years ago
3.0.0-beta.3 ... 5 years ago
3.0.0-beta.2 ... 5 years ago
3.0.0-beta.1 ... 5 years ago
3.0.0-alpha.21 ... 5 years ago
3.0.0-alpha.20 ... 5 years ago
3.0.0-alpha.19 ... 5 years ago
3.0.0-alpha.18 ... 5 years ago
3.0.0-alpha.17 ... 5 years ago
3.0.0-alpha.16 ... 5 years ago
3.0.0-alpha.15 ... 5 years ago
3.0.0-alpha.14 ... 5 years ago
3.0.0-alpha.13 ... 5 years ago
3.0.0-alpha.12 ... 5 years ago
3.0.0-alpha.11 ... 5 years ago
3.0.0-alpha.10 ... 5 years ago
3.0.0-alpha.9 ... 5 years ago
3.0.0-alpha.8 ... 5 years ago
3.0.0-alpha.7 ... 5 years ago
3.0.0-alpha.6 ... 5 years ago
3.0.0-alpha.5 ... 5 years ago
3.0.0-alpha.4 ... 5 years ago
3.0.0-alpha.3 ... 5 years ago
3.0.0-alpha.2 ... 5 years ago