Crunch2

<h1 align="center"> Crunch 2 </h1> <h4 align="center">An advanced DXTn texture compression library</h4> <p align="center"> <a href="https://github.com/FrozenStormInteractive/Crunch2/releases"><img src="https://img.shields.io/github/v/release/FrozenStormInteractive/Crunch2?sort=semver" alt="Gitter"></a> <a href="https://github.com/FrozenStormInteractive/Crunch2/stargazers"><img src="https://img.shields.io/github/stars/FrozenStormInteractive/Crunch2.svg"></a> <a href="https://github.com/FrozenStormInteractive/Crunch2/issues"><img src="https://img.shields.io/github/issues/FrozenStormInteractive/Crunch2.svg"></a> <a href="https://github.com/FrozenStormInteractive/Crunch2/pulls"><img src="https://img.shields.io/github/issues-pr/FrozenStormInteractive/Crunch2"></a> <a href="https://github.com/FrozenStormInteractive/Crunch2/graphs/contributors"><img src="https://img.shields.io/github/contributors-anon/FrozenStormInteractive/Crunch2.svg"></a> <a href="https://github.com/FrozenStormInteractive/Crunch2/issues"><img src="https://img.shields.io/badge/contributions-welcome-orange.svg"></a> <a href="License.md"><img src="https://img.shields.io/badge/license-Zlib-blue.svg"></a> </p>

Table of Contents

• Built Status
• Overview
• Crunch2 VS Crunch
• Installation
• Usage
• Examples
• Known Issues / Bugs
• Contributing
• License

Built Status

| Branch | Windows | Linux | macOS | |:-------:|:-------:|:-----:|:-----:| | Master | [![Master branch build status on Windows][Build Status Master Windows]][Latest Master Build] | [![Master branch build status on Linux][Build Status Master Linux]][Latest Master Build] | [![Master branch build status on macOS][Build Status Master macOS]][Latest Master Build] | | Develop | [![Develop branch build status on Windows][Build Status Develop Windows]][Latest Develop Build] | [![Develop branch build status on Linux][Build Status Develop Linux]][Latest Develop Build] | [![Develop branch build status on macOS][Build Status Develop macOS]][Latest Develop Build] |

Overview

Crunch2 is a fork of crunch, a lossy texture compression tool and library for developers that ship content using the DXT1/5/N or 3DC compressed color/normal map/cubemapmipmapped texture formats. It was written by the same author as the open source LZHAM compression library.

It can compress mipmapped 2D textures, normal maps, and cubemaps to approx. 1-1.25 bits/texel, and normal maps to 1.75-2 bits/texel. The actual bitrate depends on the complexity of the texture itself, the specified quality factor/target bitrate, and ultimately on the desired quality needed for a particular texture.

crnlib's differs significantly from other approaches because its compressed texture data format was carefully designed to be quickly transcodable directly to DXTn with no intermediate recompression step. The typical (single threaded) transcode to DXTn rate is generally between 100-250 megatexels/sec. The current library supports PC (Win32/x64) and Xbox 360. Fast random access to individual mipmap levels is supported.

crnlib can also generates standard .DDS files at specified quality setting, which results in files that are much more compressible by LZMA/Deflate/etc. compared to files generated by standard DXTn texture tools (see below). This feature allows easy integration into any engine or graphics library that already supports .DDS files.

The .CRN file format supports the following core DXTn texture formats: DXT1 (but not DXT1A), DXT5, DXT5A, and DXN/3DC

It also supports several popular swizzled variants (several are also supported by AMD's Compressonator): DXT5_XGBR, DXT5_xGxR, DXT5_AGBR, and DXT5_CCxY (experimental luma-chroma YCoCg).

Compression Algorithm Details

The compression process employed in creating both .CRN and clustered .DDS files utilizes a very high quality, scalable DXTn endpoint optimizer capable of processing any number of pixels (instead of the typical hard coded 16), optional adaptive switching between several macroblock sizes/configurations (currently any combination of 4x4, 8x4, 4x8, and 8x8 pixel blocks), endpoint clusterization using top-down cluster analysis, vector quantization (VQ) of the selector indices, and several custom algorithms for compressing the resulting endpoint/selector codebooks and macroblock indices. Multiple feedback passes are performed between the clusterization and VQ steps to optimize quality, and several steps use a brute force refinement approach to improve quality. The majority of compression steps are multithreaded.

The .CRN format currently utilizes canonical Huffman coding for speed (similar to Deflate but with much larger tables), but the next major version will also utilize adaptive binary arithmetic coding and higher order context modeling using already developed tech from the my LZHAM compression library.

Supported File Formats

crnlib supports two compressed texture file formats. The first format (clustered .DDS) is simple to integrate into an existing project (typically, no code changes are required), but it doesn't offer the highest quality/compression ratio that crnlib is capable of. Integrating the second, higher quality custom format (.CRN) requires a few typically straightforward engine modifications to integrate the .CRN->DXTn transcoder header file library into your tools/engine.

.DDS

crnlib can compress textures to standard DX9-style .DDS files using clustered DXTn compression, which is a subset of the approach used to create .CRN files.(For completeness, crnlib also supports vanilla, block by block DXTn compression too, but that's not very interesting.) Clustered DXTn compressed .DDS files are much more compressible than files created by other libraries/tools. Apart from increased compressibility, the .DDS files generated by this process are completely standard so they should be fairly easy to add to a project with little to no code changes.

To actually benefit from clustered DXTn .DDS files, your engine needs to further losslessly compress the .DDS data generated by crnlib using a lossless codec such as zlib, lzo, LZMA, LZHAM, etc. Most likely, your engine does this already. (If not, you definitely should because DXTn compressed textures generally contain a large amount of highly redundant data.)

Clustered .DDS files are intended to be the simplest/fastest way to integrate crnlib's tech into a project.

.CRN

The second, better, option is to compress your textures to .CRN files using crnlib. To read the resulting .CRN data, you must add the .CRN transcoder library (located in the included single file, stand-alone header file library inc/crn_decomp.h) into your application. .CRN files provide noticeably higher quality at the same effective bitrate compared to clustered DXTn compressed .DDS files. Also, .CRN files don't require further lossless compression because they're already highly compressed.

.CRN files are a bit more difficult/risky to integrate into a project, but the resulting compression ratio and quality is superior vs. clustered .DDS files.

.KTX

crnlib and crunch can read/write the .KTX file format in various pixel formats. Rate distortion optimization (clustered DXTc compression) is not yet supported when writing .KTX files.

The .KTX file format is just like .DDS, except it's a fairly well specified standard created by the Khronos Group. Unfortunately, almost all of the tools I've found that support .KTX are fairly (to very) buggy, or are limited to only a handful of pixel formats, so there's no guarantee that the .KTX files written by crnlib can be reliably read by other tools.

Crunch2 VS Crunch

Crunch2 is a fork of crunch, the lossy texture compression tool written by Richard Geldreich, Jr.

Crunch2 provides some features to its predecessor:

• Updates and bug fixes
• Shared library
• Support for Linux and macOS
• CI pipeline
• Easy build with CMake
• Dependency management with Conan

Crunch2 isn't a rewrite of crunch, just an improvement. Our main goal is to keep the compatibility with the old crnlib API.

Installation

From binary

Download Crunch2 binary from GitHub releases page. Each release provides binaries for Windows, Linux and macOS.

Building from source

1. Install the prerequisites.

   • CMake

2. Download Crunch2 sources from GitHub and unpack the distribution archive somewhere on disk.

3. Generate build files with CMake.

   cmake -S . -B build -DCRN_BUILD_SHARED_LIBS=ON
   

4. Build crunch2 with the generated build files or use CMake.

   cmake --build build
   

5. (Optional) Export distribution files with install target or use CMake (You must provide CMAKE_INSTALL_PREFIX).

   cmake --install build
   

Compile to Javascript with Emscripten

1. Download and install Emscripten

2. Download Crunch2 sources from GitHub and unpack the distribution archive somewhere on disk.

3. From the root directory, run:

   emcc -O3 emscripten/crunch_lib.cpp -I./inc -s EXPORTED_FUNCTIONS="['_malloc', '_free', '_crn_get_width', '_crn_get_height', '_crn_get_levels', '_crn_get_dxt_format', '_crn_get_bytes_per_block', '_crn_get_uncompressed_size', '_crn_decompress']" -s NO_EXIT_RUNTIME=1 -s NO_FILESYSTEM=1 -s ELIMINATE_DUPLICATE_FUNCTIONS=1 -s ALLOW_MEMORY_GROWTH=1 --memory-init-file 0 -o crunch.js
   

Usage

Creating compressed textures with the Command