ktx2-rw

A high-level Rust wrapper for the KTX2 texture format with full Basis Universal support.

KTX2 is the next-generation texture format developed by Khronos, designed for efficient GPU texture storage and transmission. This library provides safe, idiomatic Rust bindings with comprehensive support for texture compression, transcoding, and metadata management.

Features

• ✅ Full KTX2 Support: Read, write, and manipulate KTX2 texture files
• ✅ Basis Universal Integration: Compress textures with ETC1S and UASTC
• ✅ Universal Transcoding: Convert to GPU-specific formats (BC7, ETC2, ASTC, PVRTC, etc.)
• ✅ Cross-Platform: Support for Windows, macOS, and Linux (x64, ARM64)
• ✅ Memory Safety: Safe Rust API with proper error handling
• ✅ Metadata Support: Read/write custom key-value metadata
• ✅ Zero-Copy Operations: Efficient memory usage where possible

Quick Start

Add this to your Cargo.toml:

[dependencies]
ktx2-rw = { git = "https://github.com/AllenDang/ktx2-rw" }

Build Requirements

The library builds KTX-Software from source, so you need:

• CMake (3.15 or later)
• C/C++ compiler (GCC, Clang, or MSVC)
• Internet connection (for first build to download source)

Platform-specific requirements:

• Windows: Visual Studio 2022 or MinGW-w64
• macOS: Xcode command line tools
• Linux: build-essential package
• Android: Android NDK (set ANDROID_NDK_ROOT)
• iOS: Xcode

Basic Usage

use ktx2_rw::{Ktx2Texture, BasisCompressionParams, TranscodeFormat, VkFormat};

// Create a new texture
let mut texture = Ktx2Texture::create(512, 512, 1, 1, 1, 1, VkFormat::R8G8B8A8Unorm)?; // RGBA8

// Add image data (512x512 RGBA)
let rgba_data: Vec<u8> = generate_image_data();
texture.set_image_data(0, 0, 0, &rgba_data)?;

// Compress with Basis Universal using the builder pattern
let compression_params = BasisCompressionParams::builder()
    .quality_level(128)
    .thread_count(4)
    .build();
texture.compress_basis(&compression_params)?;

// For simple compression, you can also use:
texture.compress_basis_simple(128)?; // Quality level only

// Save to file
texture.write_to_file("texture.ktx2")?;

// Load from file
let loaded = Ktx2Texture::from_file("texture.ktx2")?;

// Transcode to GPU format
let mut transcoded = loaded;
transcoded.transcode_basis(TranscodeFormat::Bc7Rgba)?;

Advanced Compression

use ktx2_rw::BasisCompressionParams;

// Using the builder pattern for configuration
let params = BasisCompressionParams::builder()
    .uastc(true)                        // Use UASTC (higher quality)
    .quality_level(255)                 // Maximum quality
    .thread_count(8)                    // Multi-threaded compression
    .normal_map(true)                   // Optimize for normal maps
    .uastc_rdo_quality_scalar(1.0)      // RDO quality
    .build();

texture.compress_basis(&params)?;

Supported Platforms

The library now builds KTX-Software from source at compile time, providing excellent cross-compilation support.

Build System Benefits

• ✅ No pre-built binaries: Reduced repository size by 85MB
• ✅ Universal cross-compilation: Works on any target Rust supports
• ✅ Build optimization: Compiled with your project's flags
• ✅ Security: Build from verified source code
• ✅ Maintenance: Automatic updates with KTX-Software releases

The first build downloads and compiles KTX-Software (~5-10 minutes), but subsequent builds use cached results.

Transcoding Formats

The library supports transcoding to all major GPU texture formats:

• Desktop: BC1, BC3, BC4, BC5, BC7
• Mobile: ETC1, ETC2, ASTC 4x4, PVRTC1
• Universal: RGBA32, RGB565, RGBA4444

API Reference

Core Types

• Ktx2Texture - Main texture handle with safe lifetime management
• BasisCompressionParams - Comprehensive compression settings
  • BasisCompressionParams::builder() - Fluent builder for creating params
• TranscodeFormat - Supported GPU texture formats
• Error - Detailed error types with proper error messages

Key Methods

Creation and Loading

Ktx2Texture::create(width, height, depth, layers, faces, levels, vk_format)
Ktx2Texture::from_file(path)
Ktx2Texture::from_memory(bytes)

Texture Operations

texture.compress_basis(params)           // Compress with Basis Universal
texture.compress_basis_simple(quality)   // Simple compression with quality level
texture.transcode_basis(format)          // Transcode to GPU format
texture.get_image_data(level, layer, face) // Get raw image data
texture.set_image_data(level, layer, face, data) // Set image data

I/O Operations

texture.write_to_file(path)              // Save to file
texture.write_to_memory()                // Export to bytes

Metadata

texture.set_metadata(key, value)         // Set custom metadata
texture.get_metadata(key)                // Read metadata

Properties

texture.width(), texture.height(), texture.depth()
texture.layers(), texture.faces(), texture.levels()
texture.is_compressed(), texture.needs_transcoding()
texture.vk_format()

Error Handling

All operations return Result<T, Error> with detailed error information:

match texture.compress_basis(&params) {
    Ok(()) => println!("Compression successful"),
    Err(ktx2_rw::Error::OutOfMemory) => println!("Not enough memory"),
    Err(ktx2_rw::Error::UnsupportedFeature) => println!("Feature not supported"),
    Err(e) => println!("Other error: {}", e),
}

Performance Notes

• Basis Universal compression is CPU-intensive but produces excellent results
• UASTC mode provides higher quality but larger file sizes than ETC1S
• Multi-threaded compression significantly improves performance
• Transcoding is typically very fast (GPU-optimized)

Thread Safety

Ktx2Texture implements Send + Sync and can be safely used across threads.

License

This library is provided under the same license terms as the underlying KTX2 library.

Contributing

Contributions are welcome! Please ensure all tests pass and follow Rust coding conventions.