basis_universal

Basis Universal GPU Texture Codec

2,661

260

2,661

118

View on GitHub View on NPM

Top Related Projects

DirectXTex

1,790

DirectXTex texture processing library

compressonator

1,289

Tool suite for Texture and 3D Model Compression, Optimization and Analysis using CPUs, GPUs and APUs

stb

26,312

stb single-file public domain libraries for C/C++

Quick Overview

Basis Universal is a high-quality texture compression library that implements the Basis Universal GPU texture compression system. It allows developers to compress textures into a universal format that can be efficiently transcoded to various GPU texture formats at runtime, optimizing storage and bandwidth usage in applications like games and 3D visualization tools.

Pros

Supports a wide range of GPU texture formats, ensuring compatibility across different platforms and devices
Offers high compression ratios while maintaining good image quality
Provides fast transcoding to native GPU formats at runtime
Includes both encoder and transcoder implementations

Cons

Learning curve for integrating the library into existing projects
May require additional processing time during asset preparation compared to using native formats directly
Limited control over specific compression parameters compared to format-specific compressors
Potential performance overhead for runtime transcoding on lower-end devices

Code Examples

Encoding an image to Basis Universal format:

#include "basisu_enc.h"

basisu::basis_compressor_params params;
params.m_source_images.push_back(input_image);
params.m_output_path = "output.basis";
params.m_compression_level = 1;

basisu::basis_compressor compressor;
if (!compressor.init(params))
{
    // Handle initialization error
}

compressor.process();

Transcoding a Basis Universal file to a specific GPU format:

#include "basisu_transcoder.h"

basist::basisu_transcoder transcoder;
basist::basisu_file_info file_info;

if (!transcoder.get_file_info("input.basis", file_info))
{
    // Handle file info error
}

basist::basisu_image_info image_info;
if (!transcoder.get_image_info("input.basis", image_info, 0))
{
    // Handle image info error
}

std::vector<uint8_t> output_data(image_info.m_total_blocks * 16);
if (!transcoder.transcode_image_level("input.basis", 0, 0, &output_data[0], output_data.size(), basist::basis_tex_format::cTFBC7_RGBA, 0))
{
    // Handle transcoding error
}

Setting up the transcoder for multiple threads:

#include "basisu_transcoder.h"

basist::basisu_transcoder_init();

// In each thread:
basist::basisu_transcoder transcoder;
// Use the transcoder instance for transcoding operations

Getting Started

Clone the repository:

git clone https://github.com/BinomialLLC/basis_universal.git

Build the library:

cd basis_universal
cmake -B build
cmake --build build

Include the necessary headers in your project:

#include "basisu_enc.h"
#include "basisu_transcoder.h"

Link against the built library in your project's build system.
Use the encoder and transcoder classes as shown in the code examples above to compress and transcode textures in your application.

Competitor Comparisons

DirectXTex

1,790

DirectXTex texture processing library

Pros of DirectXTex

Comprehensive support for DirectX texture formats and operations
Extensive documentation and integration with Microsoft's DirectX ecosystem
Robust error handling and performance optimizations for DirectX applications

Cons of DirectXTex

Limited to DirectX-specific formats and not as versatile for cross-platform use
Larger codebase and potentially steeper learning curve for non-DirectX developers
Less focus on texture compression compared to basis_universal

Code Comparison

DirectXTex:

DirectX::ScratchImage image;
HRESULT hr = DirectX::LoadFromWICFile(L"texture.png", DirectX::WIC_FLAGS_NONE, nullptr, image);
if (SUCCEEDED(hr))
{
    DirectX::SaveToDDSFile(image.GetImages(), image.GetImageCount(), image.GetMetadata(), DirectX::DDS_FLAGS_NONE, L"output.dds");
}

basis_universal:

basisu::basis_compressor_params params;
params.m_source_filenames.push_back("texture.png");
params.m_output_filename = "output.basis";
params.m_compression_level = 1;
basisu::basis_compressor compressor;
bool status = compressor.init(params);

compressonator

1,289

Tool suite for Texture and 3D Model Compression, Optimization and Analysis using CPUs, GPUs and APUs

Pros of Compressonator

Supports a wider range of texture compression formats, including BC1-7, ETC, ASTC, and more
Offers a GUI application for easier use by non-programmers
Provides additional image processing tools beyond compression

Cons of Compressonator

Generally slower compression speeds compared to Basis Universal
Larger codebase and more complex setup process
Less focus on web-specific optimizations

Code Comparison

Basis Universal (encoding):

basisu::basis_compressor_params params;
params.m_source_images.push_back(input_image);
basisu::basis_compressor compressor;
compressor.init(params);
compressor.process();

Compressonator (encoding):

CMP_CompressOptions options = {};
options.dwSize = sizeof(options);
options.fquality = 0.5f;
CMP_ConvertTexture(&srcTexture, &destTexture, &options, nullptr);

Both libraries offer straightforward APIs for texture compression, but Basis Universal's API is more focused on its specific format, while Compressonator provides a more general-purpose interface for various compression formats.

stb

26,312

stb single-file public domain libraries for C/C++

Pros of stb

Broader scope: stb is a collection of single-file libraries for various purposes, not limited to texture compression
Simpler integration: Each stb library is contained in a single header file, making it easy to include in projects
More mature project: stb has been around longer and has a larger user base

Cons of stb

Less specialized: stb's texture compression is not as advanced or optimized as basis_universal
Limited format support: stb doesn't support newer texture formats like Basis Universal
Slower compression: stb's texture compression algorithms are generally slower than basis_universal

Code comparison

basis_universal:

basisu::basis_compressor_params params;
params.m_quality_level = 128;
basisu::basis_compressor compressor;
compressor.init(params);
compressor.process();

stb:

int x,y,n;
unsigned char *data = stbi_load("input.png", &x, &y, &n, 0);
int comp_len = stbi_write_png_to_mem(data, x*n, x, y, n, &output);
stbi_image_free(data);

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

basis_universal

Basis Universal Supercompressed LDR/HDR GPU Texture Transcoding System

Intro

Basis Universal is an open source supercompressed LDR/HDR GPU texture interchange system from Binomial LLC that supports two intermediate file formats: the .KTX2 open standard from the Khronos Group, and our own ".basis" file format. These file formats support rapid transcoding to virtually any GPU texture format released in the past ~25 years. Our overall goal is to simplify the encoding and efficient distribution of LDR and HDR GPU texture, image, and texture video content in a way that works well on any GPU.

The current system supports three modes: ETC1S, UASTC LDR, and UASTC HDR. The C/C++ encoder and transcoder libaries can be compiled to native code or WebAssembly. All encoder/transcoder features can be accessed from Javascript.

Supported LDR GPU Texture Formats

ETC1S and UASTC LDR files can be transcoded to:

ASTC LDR 4x4 L/LA/RGB/RGBA 8bpp
BC1-5 RGB/RGBA/X/XY
BC7 RGB/RGBA
ETC1 RGB, ETC2 RGBA, and ETC2 EAC R11/RG11
PVRTC1 4bpp RGB/RGBA and PVRTC2 RGB/RGBA
ATC RGB/RGBA and FXT1 RGB
Uncompressed LDR raster image formats: 8888/565/4444

Supported HDR GPU Texture Formats

UASTC HDR files can be transcoded to:

ASTC HDR 4x4 RGB 8bpp
BC6H RGB
Uncompressed HDR raster image formats: RGB_16F/RGBA_16F (half float/FP16 RGB, 48 or 64bpp), 32-bit shared exponent RGB_9E5

Supported Texture Compression Modes

ETC1S: A roughly .3-3bpp low to medium quality supercompressed mode based off a subset of ETC1 called "ETC1S". This mode supports variable quality vs. file size levels (like JPEG), alpha channels, built-in compression, and texture arrays optionally compressed as a video sequence using skip blocks (Conditional Replenishment). This mode can be rapidly transcoded to all of the supported LDR texture formats.
UASTC LDR: An 8 bits/pixel LDR high quality mode. UASTC LDR is a 19 mode subset of the standard ASTC LDR 4x4 (8bpp) texture format, but with a custom block format containing transcoding hints. Transcoding UASTC LDR to ASTC LDR and BC7 are particularly fast and simple, because UASTC LDR is a common subset of both BC7 and ASTC. The transcoders for the other texture formats are accelerated by several format-specific hint bits present in each UASTC LDR block.

This mode supports an optional Rate-Distortion Optimizated (RDO) post-process stage that conditions the encoded UASTC LDR texture data in the .KTX2/.basis file so it can be more effectively LZ compressed. More details here.

Here is the UASTC LDR specification document.

UASTC HDR: An 8 bits/pixel HDR high quality mode. This is a 24 mode subset of the standard ASTC HDR 4x4 (8bpp) texture format. It's designed to be high quality, supporting the 27 partition patterns in common between BC6H and ASTC, and fast to transcode with very little loss (typically a fraction of a dB PSNR) to the BC6H HDR texture format. Notably, UASTC HDR data is 100% standard ASTC texture data, so no transcoding at all is required on devices or API's supporting ASTC HDR. This mode can also be transcoded to various 32-64bpp uncompressed HDR texture/image formats.

Here is the UASTC HDR specification document, and some compressed example images.

Other Features

Both .basis and .KTX2 files support mipmap levels, texture arrays, cubemaps, cubemap arrays, and texture video, in all three modes. Additionally, .basis files support non-uniform texture arrays, where each image in the file can have a different resolution or number of mipmap levels.

In ETC1S mode, the compressor is able to exploit color and pattern correlations across all the images in the entire file using global endpoint/selector codebooks, so multiple images with mipmaps can be stored efficiently in a single file. The ETC1S mode also supports short video sequences, with skip blocks (Conditional Replenishment) used to not send blocks which haven't changed relative to the previous frame.

The LDR image formats supported for reading are .PNG, .DDS with mipmaps, .TGA, .QOI, and .JPG. The HDR image formats supported for reading are .EXR, .HDR, and .DDS with mipmaps. It can write .basis, .KTX2, .DDS, .KTX (v1), .ASTC, .OUT, .EXR, and .PNG files.

The system now supports loading basic 2D .DDS files with optional mipmaps, but the .DDS file must be in one of the supported uncompressed formats: 24bpp RGB, 32bpp RGBA/BGRA, half-float RGBA, or float RGBA. Using .DDS files allows the user to control exactly how the mipmaps are generated before compression.

Building

The encoding library and command line tool have no required 3rd party dependencies that are not already in the repo itself. The transcoder is a single .cpp source file (in transcoder/basisu_transcoder.cpp) which has no 3rd party dependencies.

We build and test under:

Windows x86/x64 using Visual Studio 2019/2022, MSVC, or clang
Mac OSX (M1) with clang v15.0
Ubuntu Linux with gcc v11.4 or clang v14
Arch Linux ARM, on a Pinebook Pro, with gcc v12.1.

Under Windows with Visual Studio you can use the included basisu.sln file. Alternatively, you can use cmake to create new VS solution/project files.

To build, first install cmake, then:

cd build
cmake ..
make

To build with SSE 4.1 support on x86/x64 systems (encoding is roughly 15-30% faster), add -DSSE=TRUE to the cmake command line. Add -DOPENCL=TRUE to build with (optional) OpenCL support. Use -DCMAKE_BUILD_TYPE=Debug to build in debug. To build 32-bit executables, add -DBUILD_X64=FALSE.

After building, the native command line tool used to create, validate, and transcode/unpack .basis/.KTX2 files is bin/basisu.

Testing the Codec

The command line tool includes some automated LDR/HDR encoding/transcoding tests:

cd ../bin
basisu -test
basisu -test_hdr

To test the codec in OpenCL mode (must have OpenCL libs/headers/drivers installed and have compiled OpenCL support in by running cmake with -DOPENCL=TRUE):

basisu -test -opencl

Compressing and Unpacking .KTX2/.basis Files

To compress an LDR sRGB PNG/QOI/TGA/JPEG/DDS image to an ETC1S .KTX2 file, at quality level 255 (the highest):

basisu -q 255 x.png

For a linear LDR image, in ETC1S mode, at default quality (128):

basisu -linear x.png

To compress to UASTC LDR, which is much higher quality than ETC1S:

basisu -uastc x.png

To compress an .EXR, Radiance .HDR, or .DDS HDR image to a UASTC HDR .KTX2 file:

basisu x.exr

Note the .EXR reader we're using is TinyEXR's, which doesn't support all possible .EXR compression modes. Tools like ImageMagick can be used to create .EXR files that TinyEXR can read.

Alternatively, LDR images (such as .PNG) can be compressed to UASTC HDR by specifying -hdr. By default, LDR images, when compressed to UASTC HDR, are first converted from sRGB to linear light before compression. This conversion step can be disabled by specifying -hdr_ldr_no_srgb_to_linear.

Importantly, for best quality, you should supply basisu with original uncompressed source images. Any other type of lossy compression applied before basisu (including ETC1/BC1-5, BC7, JPEG, etc.) will cause multi-generational artifacts to appear in the final output textures.

Some Useful Command Line Options

-fastest (which is equivalent to -uastc_level 0) puts the UASTC LDR/HDR encoders in their fastest (but lower quality) modes.
-slower puts the UASTC LDR/HDR encoders in higher quality but slower modes (equivalent to -uastc_level 3). The default level is 1, and the highest is 4 (which is quite slow).
-q X, where X ranges from [1,255], controls the ETC1S mode's quality vs. file size tradeoff level. 255 is the highest quality, and the default is 128.
-debug causes the encoder to print internal and developer-oriented verbose debug information.
-stats to see various quality (PSNR) statistics.
-linear: ETC1S defaults to sRGB colorspace metrics, UASTC LDR currently always uses linear metrics, and UASTC HDR defaults to weighted RGB metrics (with 2,3,1 weights). If the input is a normal map, or some other type of non-sRGB (non-photographic) texture content, be sure to use -linear to avoid extra unnecessary artifacts. (Angular normal map metrics for UASTC LDR/HDR are definitely doable and on our TODO list.)
Specifying -opencl enables OpenCL mode, which currently only accelerates ETC1S encoding.
The compressor is multithreaded by default, which can be disabled using the -no_multithreading command line option. The transcoder is currently single threaded, although it is thread safe (i.e. it supports decompressing multiple texture slices in parallel).

More Example Command Lines

To compress an sRGB PNG/QOI/TGA/JPEG/DDS image to an RDO (Rate-Distortion Optimization) UASTC LDR .KTX2 file with mipmaps:

basisu -uastc -uastc_rdo_l 1.0 -mipmap x.png

-uastc_rdo_l X controls the RDO (Rate-Distortion Optimization) quality setting. The lower this value, the higher the quality, but the larger the compressed file size. Good values to try are between .2-3.0. The default is 1.0.

To add automatically generated mipmaps to a ETC1S .KTX2 file, at a higher than default quality level (which ranges from [1,255]):

basisu -mipmap -q 200 x.png

There are several mipmap options to change the filter kernel, the filter colorspace for the RGB channels (linear vs. sRGB), the smallest mipmap dimension, etc. The tool also supports generating cubemap files, 2D/cubemap texture arrays, etc. To bypass the automatic mipmap generator, you can create LDR or HDR uncompressed .DDS texture files and feed them to the compressor.

To create a slightly higher quality ETC1S .KTX2 file (one with higher quality endpoint/selector codebooks) at the default quality level (128) - note this is much slower to encode:

basisu -comp_level 2 x.png

On some rare images (ones with blue sky gradients come to bind), you may need to increase the ETC1S -comp_level setting, which ranges from 1,6. This controls the amount of overall effort the encoder uses to optimize the ETC1S codebooks and the compressed data stream. Higher comp_level's are significantly slower.

To manually set the ETC1S codebook sizes (instead of using -q), with a higher codebook generation level (this is useful with texture video):

basisu x.png -comp_level 2 -max_endpoints 16128 -max_selectors 16128

To tonemap an HDR .EXR or .HDR image file to multiple LDR .PNG files at different exposures, using the Reinhard tonemap operator:

basisu -tonemap x.exr

To compare two LDR images and print PSNR statistics:

basisu -compare a.png b.png

To compare two HDR .EXR/.HDR images and print FP16 PSNR statistics:

basisu -compare_hdr a.exr b.exr

See the help text for a complete listing of the tool's command line options. The command line tool is just a thin wrapper on top of the encoder library.

Unpacking .KTX2/.basis files to .PNG/.EXR/.KTX/.DDS files

You can either use the command line tool or call the transcoder directly from JavaScript or C/C++ code to decompress .KTX2/.basis files to GPU texture data or uncompressed image data. To unpack a .KTX2 or.basis file to multiple .png/.exr/.ktx/.dds files:

basisu x.ktx2

Use the -no_ktx and -etc1_only/-format_only options to unpack to less files.

-info and -validate will just display file information and not output any files.

The written mipmapped, cubemap, or texture array .KTX/.DDS files will be in a wide variety of compressed GPU texture formats (PVRTC1 4bpp, ETC1-2, BC1-5, BC7, etc.), and to our knowledge there is unfortunately (as of 2024) still no single .KTX or .DDS viewer tool that correctly and reliably supports every GPU texture format that we support. BC1-5 and BC7 files are viewable using AMD's Compressonator, ETC1/2 using Mali's Texture Compression Tool, and PVRTC1 using Imagination Tech's PVRTexTool. RenderDoc has a useful texture file viewer for many formats. The Mac OSX Finder supports previewing .EXR and .KTX files in various GPU formats. The Windows 11 Explorer can preview .DDS files. The online OpenHDR Viewer is useful for viewing .EXR/.HDR image files.

WebGL Examples

The 'WebGL' directory contains four simple WebGL demos that use the transcoder and compressor compiled to WASM with emscripten. These demos are online here. See more details in the readme file here.

Screenshot of 'texture' example running in a browser. Screenshot of 'gltf' example running in a browser. Screenshot of 'encode_test' example running in a browser.

Building the WASM Modules with Emscripten

Both the transcoder and encoder may be compiled using emscripten to WebAssembly and used on the web. A set of JavaScript wrappers to the codec, written in C++ with emscripten extensions, is located in webgl/transcoding/basis_wrappers.cpp. The JavaScript wrapper supports nearly all features and modes, including texture video. See the README.md and CMakeLists.txt files in webgl/transcoder and webgl/encoder.

To build the WASM transcoder, after installing emscripten:

cd webgl/transcoder/build
emcmake cmake ..
make

To build the WASM encoder:

cd webgl/encoder/build
emcmake cmake ..
make

There are two simple encoding/transcoding web demos, located in webgl/ktx2_encode_test and webgl/texture_test, that show how to use the encoder's and transcoder's Javascript wrapper API's.

Low-level C++ Encoder/Transcoder API Examples

Some simple examples showing how to directly call the C++ encoder and transcoder library API's are in example/examples.cpp.

ETC1S Texture Video Tips

See the wiki here.

Installation using the vcpkg dependency manager

You can download and install Basis Universal using the vcpkg dependency manager:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install basisu

The Basis Universal port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository. (9/10/2024: UASTC HDR support is not available here yet.)

License

The transcoder and core encoder libraries are Apache 2.0. The transcoder utilizes no 3rd party libraries or dependencies. See LICENSE.

The encoder library is Apache 2.0, but it utilizes some open source 3rd party modules (in 'encoder/3rdparty' and in the 'Zstd' directory) to load .QOI, .DDS, .EXR images, to handle Zstd compression, and to unpack ASTC texture blocks. See the LICENSES and .reuse folders.

Repository Licensing with REUSE

The repository has been updated to be compliant with the REUSE license checking tool (https://reuse.software/). See the .reuse subdirectory.

External Tool Links

Online .EXR HDR Image File Viewer

Windows HDR + WCG Image Viewer - A true HDR image viewer for Windows. Also see the github repo.

RenderDoc

AMD Compressonator

Microsoft's DirectXTex

PVRTexTool

Mali Texture Compression Tool - Now deprecated

For more useful links, papers, and tools/libraries, see the end of the UASTC HDR texture specification.

E-mail: info @ binomial dot info, or contact us on Twitter

Here's the Sponsors wiki page.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot