Overview

The @loaders.gl/textures module contains loaders for compressed textures. More specifically it contains loaders and writers for compressed texture container formats, including KTX, DDS and PVR. It also supports supercompressed Basis textures and decoded Radiance HDR images.

Note that a texture is more complex than an image. A texture typically has many subimages. A texture can represent a single logical image but can also be a texture cube, a texture array etc representing many logical images. In addition, each "image" typically has many mipmap levels.

In addition, in compressed textures each mipmap image is compressed opaquely into a format that can only be understood by certain GPUs.

Basis encoded textures are super compressed. A more recent addition, they can be efficiently transcoded on the client into actual compressed texture formats appropriate for each device and are therefore quite convenient to use.

Installation

npm install @loaders.gl/textures
npm install @loaders.gl/core

Formats

The @loaders.gl/textures module handles the following formats:

Format	Description
Compressed Textures	Overview of GPU texture container and compression formats
KTX / KTX2	Khronos texture container formats for mipmapped textures
DDS	Microsoft DirectDraw Surface texture container
PVR	PowerVR texture container format
Basis Universal	Supercompressed texture format for runtime transcoding
Crunch	Lossy compressed texture distribution format for GPU textures
Radiance HDR	High-dynamic-range RGBE textures stored in .hdr files

API

Loader	Description
BasisLoader	Basis Universal textures as TextureLevel[][]
CompressedTextureLoader	KTX, DDS and PVR mip chains as TextureLevel[]
RadianceHDRLoader	Radiance .hdr textures as Texture
CrunchWorkerLoader	Crunch mip chains as TextureLevel[]
TextureLoader	Manifest-driven single image or mip chain
TextureArrayLoader	Manifest-driven texture arrays
TextureCubeLoader	Manifest-driven cubemaps
TextureCubeArrayLoader	Manifest-driven cube arrays

Return Types

The compressed texture loaders in this module return TextureLevel objects from @loaders.gl/schema.

Texture Category

A TextureLevel describes one mip level of one texture image.

Field	Type	Description
compressed	boolean	Whether the mip level data is GPU-compressed.
shape	'texture-level'	Shape tag for normalized texture-level payloads.
format	number	WebGL internal format enum for the decoded level.
textureFormat	TextureFormat	WebGPU / luma.gl style format string for the data.
data	TypedArray	The payload for this mip level. Compressed texture loaders return Uint8Array; RadianceHDRLoader returns Float32Array.
width	number	Width of this mip level.
height	number	Height of this mip level.
levelSize	number	Size in bytes for this mip level, when available.
hasAlpha	boolean	Whether the transcoded texture contains alpha.

BasisLoader returns TextureLevel[][], preserving all images in a .basis or .ktx2 asset.

CompressedTextureLoader returns TextureLevel[].

RadianceHDRLoader returns a Texture with shape: 'texture', type: '2d', one decoded rgba32float level in data, and optional application-facing metadata.

CrunchWorkerLoader returns TextureLevel[].

See BasisLoader and CompressedTextureLoader for loader-specific options and return shapes.

Composite Image Loaders

The textures module also includes manifest-driven loaders for composite image textures:

• TextureLoader for a single image or mip chain
• TextureArrayLoader for texture arrays, including mipmapped layers
• TextureCubeLoader for cubemaps, including mipmapped faces
• TextureCubeArrayLoader for cube arrays

These loaders resolve relative member URLs against the manifest URL, or against options.core.baseUrl when parsing an in-memory manifest. Member assets are parsed with ImageLoader by default, and additional loaders passed to top-level load() are also available for manifest members. They return schema Texture objects rather than raw image trees.

Attributions

• The CompressedTextureLoader was forked from PicoGL, Copyright (c) 2017 Tarek Sherif, The MIT License (MIT)
• The CompressedTextureWriter is a wrapper around @TimvanScherpenzeel's texture-compressor utility (MIT licensed).