Home

Awesome

<!-- Copyright 2013-2020 Mark Callow --> <!-- SPDX-License-Identifier: Apache-2.0 --> <img src="https://www.khronos.org/assets/images/api_logos/khronos.svg" width="300"/>

The Official Khronos KTX Software Repository

GNU/Linux, iOS, macOS & wasmWindowsAndroidMingw
Build StatusBuild statusKTX-Software CIKTX-Software CI

This is the official home of the source code for the Khronos KTX library and tools.

KTX (Khronos Texture) is a lightweight container for textures for OpenGL<sup>®</sup>, Vulkan<sup>®</sup> and other GPU APIs. KTX files contain all the parameters needed for texture loading. A single file can contain anything from a simple base-level 2D texture through to a cubemap array texture with mipmaps. Contained textures can be in a Basis Universal format, in any of the block-compressed formats supported by OpenGL family and Vulkan APIs and extensions or in an uncompressed single-plane format. Basis Universal currently encompasses two formats that can be quickly transcoded to any GPU-supported format: LZ/ETC1S, which combines block-compression and supercompression, and UASTC, a block-compressed format. Formats other than LZ/ETC1S can be supercompressed with Zstd and ZLIB.

Download KTX Software Releases to get binary packages of the tools, library and development headers described below. The Releases page also has packages with the Javascript wrappers and .wasm binaries.

See the Doxygen generated live documentation for API and tool usage information.

The software consists of: (links are to source folders in the KhronosGroup repo)

See CONTRIBUTING for information about contributing.

See LICENSE for information about licensing.

See BUILDING for information about building the code.

<!-- More information about KTX and links to tools that support it can be found on the [KTX page](http://www.khronos.org/opengles/sdk/tools/KTX/) of the [OpenGL ES SDK](http://www.khronos.org/opengles/sdk) on [khronos.org](http://www.khronos.org). -->

If you need help with using the KTX library or KTX tools, please use GitHub Discussions. To report problems use GitHub issues.

IMPORTANT: you must install the Git LFS command line extension in order to fully checkout this repository after cloning. You need at least version 1.1. If you did not have Git LFS installed at first checkout then, after installing it, you must run

git lfs checkout

KTX-Software-CTS - Conformance Test Suite

The tests and test files for the generic command line ktx tool can be found in a separate CTS Repository. To save space and bandwidth this repository is included with git submodule and by default it is not required for building the libraries or the tools. For more information about building, running and extending the CTS tests see BUILDING and CTS README.

<a id="kwexpansion"></a>$Date$ keyword expansion

A few files have $Date$ keywords. If you care about having the proper dates shown or will be generating the documentation or preparing distribution archives, you must follow the instructions below.

$Date$ keywords are expanded via smudge & clean filters. To install the filters, issue the following commands in the root of your clone.

On Unix (Linux, Mac OS X, etc.) platforms and Windows using Git for Windows' Git Bash or Cygwin's bash terminal:

./install-gitconfig.sh
./scripts/smudge_date.sh

On Windows PowerShell (requires git.exe in a directory on your %PATH%):

install-gitconfig.ps1
./scripts/smudge_date.ps1

The first command adds an [include] of the repo's .gitconfig to the local git config file .git/config, i.e. the one in your clone of the repo. .gitconfig contains the config of the "keyworder" filter. The script in the second command forces a new checkout of the affected files to smudge them with their last modified date. This is unnecessary if you plan to edit these files.

Useful Tools

scripts/gk

For finding strings within the KTX-Software source. Type scripts/gk -h for help. gk avoids looking in any build directories, .git, external or tests/cts.

scripts/ktx-compare-git

Wrapper that allows use of ktx compare when using git diff on KTX2 files. Together with this, .gitconfig now includes a ktx-compare diff command. Those wishing to use this must run, or have run, install-gitconfig.{ps1,sh} as described above for keyword expansion so that .gitconfig is included by your local .git/config.

You need to have the ktx command installed in a directory on your $PATH.

You need to add the line

*.ktx2 binary diff=ktx-compare

to your repo clone's .git/info/attributes. This is not included in the repo's .gitattributes because not everyone will have the ktx command installed nor have .gitconfig included by .git/config.

NOTE: This line in a user-global or system-global Git attributes file will not work because those are lower priority than .gitattributes so are read first and .gitattributes already has an entry for *.ktx2, indicating binary, which overrides anything from the global files.

To set up your tests/cts submodule to use this, copy the ktx-compare diff command to .git/modules/tests/cts/config. Depending on when you set up the submodule and when you ran install-gitconfig.sh, it may already be there. Add the attribute line to .git/modules/tests/cts/info/attributes.

We will be happy to accept a PR to add a .ps1 equivalent script.