An unofficial Rust port of Khronos KTX-Software:
the libktx library and the ktx command line tool, including the Basis Universal encoders and
transcoders. It is not affiliated with or endorsed by The Khronos Group.
The port follows the C/C++ API and behaviour closely: output is byte identical to the upstream tools, and every case of the upstream CLI conformance test suite (CTS) passes. The upstream revision it tracks is recorded in LATEST_REFERENCE.md.
- KTX1 / KTX2 reading, writing, validation; zstd and zlib supercompression.
- Basis Universal: ETC1S (Basis-LZ), UASTC, UASTC HDR 4x4 and 6x6i encoders; transcoding to every target libktx supports.
- ASTC encoding and decoding (astcenc port), ETC unpack, PNG / JPEG / EXR input.
- GPU upload: Vulkan loader (feature
vulkan, default) and OpenGL / OpenGL ES loader (featureopengl, opt in). - WebAssembly: the library builds for
wasm32-unknown-unknown/wasm32-wasip1(single threaded, GPU loaders compiled out); see docs/spec/wasm.md. - The
ktxCLI:create,convert,encode,deflate,transcode,extract,info,validate,compare,help.
JS binding: ktx-rs-wasm (see below).
Not ported: the legacy tools (toktx, ktx2check, ...), the Java and Python bindings (not ported
yet), OpenCL encoding, and ASTC HDR encoding (broken upstream; deferred). See ROADMAP.md for the full status.
make build # ./bin/ktx and its man pages in ./share/man/man1
make install # ~/bin/ktx and ~/share/man/man1 (PREFIX=/usr/local to change)Or with Cargo: cargo build --release (the binary is target/release/ktx).
ktx create --format R8G8B8A8_SRGB --generate-mipmap albedo.png albedo.ktx2
ktx encode --codec basis-lz albedo.ktx2 albedo_blz.ktx2
ktx info albedo_blz.ktx2
ktx help createThe package is ktx-rs; the library is imported as ktx:
[dependencies]
ktx-rs = "4.4.3"use ktx::texture::KtxTexture;
use ktx::{KtxResult, Texture2, TranscodeFmt};
fn transcode_to_bc7(src: &str, dst: &str) -> KtxResult<()> {
let mut texture =
Texture2::create_from_named_file(src, ktx::KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT)?;
if texture.needs_transcoding() {
texture.transcode_basis(TranscodeFmt::BC7_RGBA, 0)?;
}
texture.write_to_named_file(dst)
}Functions keep their libktx names in snake case (ktxTexture2_TranscodeBasis is
Texture2::transcode_basis) and return KtxResult<T>, whose error is the libktx ErrorCode.
The library never panics on bad input (unwrap, expect and panic! are denied).
bindings/js (crate ktx-rs-wasm) ports KTX-Software's Emscripten JS binding to wasm-bindgen
with the same JS API (factory promise, embind-style enums and delete()), so existing code
keeps working. make js builds bindings/js/dist/ (needs wasm-bindgen-cli matching the
wasm-bindgen crate version); make test-js runs the node tests.
const MSC_TRANSCODER = require('./msc_basis_transcoder.js');
MSC_TRANSCODER().then((module) => {
module.initTranscoders();
const uit = new module.UastcImageTranscoder();
// ... uit.transcodeImage(module.TranscodeTarget.BC7_RGBA, data, imageInfo, 0, hasAlpha)
});Done: msc_basis_transcoder.js, libktx.js and libktx_read.js, including texture.glUpload
to WebGL (make test-js-browser checks it in headless Chrome through chromedriver; set
CHROMEDRIVER / CHROME). See docs/spec/js_binding.md.
- Pure Rust except the allowed C bindings: Vulkan (
ash) and, behindopengl, OpenGL. unsafeis denied outside the GPU loaders and the astcenc SIMD code.- Encoders use multiple threads (
--threads, default: all cores). The ASTC encoder has SSE2, SSE4.1 and AVX2 builds and picks one at runtime, so notarget-cpuflags are needed. - Implementation notes per component live in docs/spec.
cargo test --release # unit, golden and CTS tests
cargo test --release --features opengl # plus the OpenGL loader (needs Mesa / EGL)
scripts/bench/bench.sh <path-to-C++-ktx> # speed and output comparison with upstreamTest data under tests/resources is copied from KTX-Software and its CTS.
Each translated source file keeps the copyright and license of the code it was ported from:
mostly Apache-2.0 (KTX-Software, Basis Universal, astc-encoder), plus Zlib (LodePNG),
BSD-3-Clause (tinyexr) and MIT (cxxopts). The crate license is therefore
Apache-2.0 AND BSD-3-Clause AND MIT AND Zlib. See NOTICE.md, LICENSE,
LICENSES/ and REUSE.toml.
Test data under tests/resources comes from KTX-Software and keeps its original licenses
(recorded in REUSE.toml); it is not part of the published crate. The HI Corporation trademark
images (hi_mark*.ktx) that upstream ships under a non-open license are left out.