Home

Awesome

Introduction

Cuttlefish

Cuttlefish is a texture conversion library and tool. A command line tool is provided for most texture conversion needs, such as running manually or part of an asset conversion pipeline. The library may be used to integrate more advanced texture generation within other software.

Features include:

Dependencies

The following software is required to build Cuttlefish:

The submodules can be downloaded by running the command

Cuttlefish$ git submodule update --init

When using the BC6H and BC7 encoders, it's highly recommended to install the ISPC compiler. This will use higher quality encoders that are also faster compared to the fallback used when ISP isn't available.

Note: Use the CUTTLEFISH_ISPC_PATH CMake variable when ISPC isn't visible on the system PATH.

Note: As of this writing, the last release of PVRTexTool that supports macOS is the 2023r2 release, with both releases in 2024 not having downloads available for macOS. For now, the 2023r2 release will continue to be used to support PVRTC formats across all major platforms until either it breaks or releases resume on macOS.

Platforms

Cuttlefish has been built for and tested on the following platforms:

Building and Installing

CMake is used as the build system. The way to invoke CMake differs for different platforms.

Linux/macOS

To create a release build, execute the following commands:

Cuttlefish$ mkdir build
Cuttlefish$ cd build
Cuttlefish/build$ cmake .. -DCMAKE_BUILD_TYPE=Release
Cuttlefish/build$ make

The tests can be run by running the command:

Cuttlefish/build$ ctest

The library and tool may then be installed by running the command:

Cuttlefish/build$ sudo make install

macOS Universal Binary

To create a universal binary on macOS, set the CMAKE_OSX_ARCHITECTURES variable. For example, for an x86_64/arm64 universal binary, add the argument -DCMAKE_OSX_ARCHITECTURES=arm64;x86_64. Building a universal binary requires creating an Xcode project with the -GXcode argument to CMake.

Note: when installing ISPC through homebrew not all targets are supported. For example, when installing on an ARM CPU (e.g. M1), only ARM targets are supported. Download from the ISPC website to get a version that supports both x86 and ARM targets.

Note: when creating an install package using shared libraries with Xcode, add the -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON option when running CMake. This avoids CMake breaking the code signature, which will make the executable unrunnable. The executables won't run in the build directory, however.

Windows

Building is generally performed through Visual Studio. This can either be done through the CMake GUI tool or on the command line. To generate Visual Studio 2017 projects from the command line, you can run the commands:

Cuttlefish$ mkdir build
Cuttlefish$ cd build
Cuttlefish\build$ cmake .. -G "Visual Studio 15 2017 Win64"

Once generated, the project may be opened through Visual Studio and built as normal. The RUN_TESTS project may be built in order to run the tests.

In order to install the libraries and tool, run Visual Studio as administrator, perform a release build, and run the INSTALL project. The default installation location is C:\Program Files\Cuttlefish. After installation, it's recommended to place the C:\Program Files\Cuttlefish\bin folder on your PATH environment variable to run the cuttlefish tool from the command line.

Options

The following options may be used when running cmake:

Compile Options:

Enabled Builds

Miscellaneous Options:

Once you have built and installed Cuttlefish, you can find the library by calling find_package(Cuttlefish) within your CMake files. You can either link to the Cuttlefish::lib target or use the Cuttlefish_LIBRARIES and Cuttlefish_INCLUDE_DIRS CMake variables. The Cuttlefish::tool target may also be used for the tool executable.

Note: In order for find_package() to succeed, you will need to add the base installation path to CMAKE_PREFIX_PATH.

Limitations

Texture file format limitations

Some texture file formats have limitations for what texture formats are used. The following formats are not supported:

Custom PVR metadata

Metadata is used to enhance the PVR file format to provide information beyond what is supported by the base format. The metadata values are:

A dummy data field of 4 bytes is used because the PVRTexTool GUI tool will crash with a data size of 0.

Further Documentation