BASISU -- Basis Universal

Added in version 3.6.

Driver short name

BASISU

Build dependencies

Basis Universal

From https://github.com/BinomialLLC/basis_universal,

Basis Universal is a "supercompressed" GPU texture data interchange system that supports two highly compressed intermediate file formats (.basis or the .KTX2 open standard from the Khronos Group) that can be quickly transcoded to a very wide variety of GPU compressed and uncompressed pixel formats.

This driver handles textures with the .basis extension. For KTX2, refer to the KTX2 driver.

Note that while the file format supports direct transcoding to other GPU pixel formats, this GDAL driver supports only conversion between uncompressed RGB(A) data and Basis Universal textures.

When a file is made of several images, they are exposed as subdataset, with the BASISU:filename:image_idx syntax.

Mipmaps levels are exposed as GDAL overviews.

Driver capabilities

Supports CreateCopy()

This driver supports the GDALDriver::CreateCopy() operation

Supports VirtualIO

This driver supports virtual I/O operations (/vsimem/, etc.)

Creation options

The format supports 2 modes: a high quality mode which is internally based off the UASTC compressed texture format, and the original lower quality mode which is based off a subset of ETC1 called "ETC1S". The default is ETC1S. Only input of type Byte and with 1 (grey), 2 (grey+alpha), 3 (RGB) or 4 (RGB + alpha) bands is supported. Refer to https://github.com/BinomialLLC/basis_universal for more details on those modes and their options.

Creation options can be specified in command-line tools using the syntax -co <NAME>=<VALUE> or by providing the appropriate arguments to GDALCreate() (C) or Driver.Create (Python). The following creation options are available:

  • COMPRESSION=[ETC1S​/​UASTC]: Defaults to ETC1S.

  • UASTC_LEVEL=[0​/​1​/​2​/​3​/​4]: Defaults to 2. The higher value, the higher the quality but the slower computing time. 4 is impractically slow. Only valid when COMPRESSION=UASTC.

  • UASTC_RDO_LEVEL=<float>: Defaults to 1.0. Rate distortion optimization level. The lower value, the higher the quality, but the larger the file size. Usual range is [0.2,3]. Only valid when COMPRESSION=UASTC.

  • ETC1S_LEVEL=[0​/​1​/​2​/​3​/​4​/​5​/​6]: Defaults to 1. The higher value, the higher the quality but the slower computing time. Only valid when COMPRESSION=ETC1S.

  • ETC1S_QUALITY_LEVEL=[<integer in [1​/​255] range>]: Defaults to 128. The higher value, the higher the quality, but the larger the file size. Only valid when COMPRESSION=ETC1S.

  • ETC1S_MAX_ENDPOINTS_CLUSTERS=[<integer in [1​/​16128] range>]: Maximum number of endpoint clusters. When set, ETC1S_MAX_SELECTOR_CLUSTERS must also be set. Mutually exclusive with ETC1S_QUALITY_LEVEL. Only valid when COMPRESSION=ETC1S.

  • ETC1S_MAX_SELECTOR_CLUSTERS=[<integer in [1​/​16128] range>]: Maximum number of selector clusters. When set, ETC1S_MAX_ENDPOINTS_CLUSTERS must also be set. Mutually exclusive with ETC1S_QUALITY_LEVEL. Only valid when COMPRESSION=ETC1S.

  • NUM_THREADS=<integer>:

    Defaults to the maximum number of virtual CPUs available. Can also be controlled with the GDAL_NUM_THREADS configuration option.

  • MIPMAP=[YES​/​NO]: Defaults to NO.

    Whether to enable MIPMAP generation.

  • COLORSPACE=[PERCEPTUAL_SRGB​/​LINEAR]: Defaults to PERCEPTUAL_SRGB. For non-photometric input, use LINEAR to avoid unnecessary artifacts.

Build instructions

Building basisu as a library requires currently building the cmake branch of the https://github.com/rouault/basis_universal/tree/cmake fork.

git clone -b cmake https://github.com/rouault/basis_universal
cd basis_universal
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install-basisu -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
cmake --build . --config Release --target install

Once basisu is built, GDAL CMake options must be configured by pointing the basisu install prefix in the CMAKE_PREFIX_PATH variable or basisu_ROOT variable.