use std::collections::HashMap;
use std::sync::Arc;
use crate::textures::{Texture, TextureFormat};
const IDENTIFIER: [u8; 12] = [
0xAB, 0x4B, 0x54, 0x58, 0x20, 0x32, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A,
];
#[derive(Debug, PartialEq)]
pub enum Ktx2Error {
NotKtx2,
Truncated,
Corrupt,
Unsupported(&'static str),
}
impl std::fmt::Display for Ktx2Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Ktx2Error::NotKtx2 => write!(f, "not a KTX2 file"),
Ktx2Error::Truncated => write!(f, "truncated KTX2 file"),
Ktx2Error::Corrupt => write!(f, "corrupt KTX2 file"),
Ktx2Error::Unsupported(what) => write!(f, "unsupported KTX2 texture: {what}"),
}
}
}
impl std::error::Error for Ktx2Error {}
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Supercompression {
None,
BasisLz,
Zstd,
Zlib,
}
#[derive(Debug, Clone)]
pub struct Level {
pub data: Vec<u8>,
pub uncompressed_length: usize,
}
#[derive(Debug, Clone)]
pub struct Ktx2 {
pub vk_format: u32,
pub type_size: u32,
pub width: u32,
pub height: u32,
pub depth: u32,
pub layers: u32,
pub faces: u32,
pub level_count: u32,
pub supercompression: Supercompression,
pub levels: Vec<Level>,
pub transfer_function: u8,
pub key_value: HashMap<String, Vec<u8>>,
}
struct Reader<'a> {
data: &'a [u8],
at: usize,
}
impl<'a> Reader<'a> {
fn u32(&mut self) -> Result<u32, Ktx2Error> {
let b = self.take(4)?;
Ok(u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
}
fn u64(&mut self) -> Result<u64, Ktx2Error> {
let b = self.take(8)?;
Ok(u64::from_le_bytes([
b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
]))
}
fn take(&mut self, n: usize) -> Result<&'a [u8], Ktx2Error> {
let end = self.at.checked_add(n).ok_or(Ktx2Error::Truncated)?;
let s = self.data.get(self.at..end).ok_or(Ktx2Error::Truncated)?;
self.at = end;
Ok(s)
}
}
pub fn parse(bytes: &[u8]) -> Result<Ktx2, Ktx2Error> {
if bytes.len() < IDENTIFIER.len() || bytes[..IDENTIFIER.len()] != IDENTIFIER {
return Err(Ktx2Error::NotKtx2);
}
let mut r = Reader {
data: bytes,
at: IDENTIFIER.len(),
};
let vk_format = r.u32()?;
let type_size = r.u32()?;
let width = r.u32()?;
let height = r.u32()?;
let depth = r.u32()?;
let layers = r.u32()?;
let faces = r.u32()?;
let level_count = r.u32()?;
let supercompression = match r.u32()? {
0 => Supercompression::None,
1 => Supercompression::BasisLz,
2 => Supercompression::Zstd,
3 => Supercompression::Zlib,
_ => return Err(Ktx2Error::Corrupt),
};
let dfd_offset = r.u32()? as usize;
let dfd_length = r.u32()? as usize;
let kvd_offset = r.u32()? as usize;
let kvd_length = r.u32()? as usize;
let _sgd_offset = r.u64()?;
let _sgd_length = r.u64()?;
if width == 0 || faces == 0 {
return Err(Ktx2Error::Corrupt);
}
let stored_levels = level_count.max(1) as usize;
if stored_levels.saturating_mul(24) > bytes.len() {
return Err(Ktx2Error::Corrupt);
}
let mut levels = Vec::with_capacity(stored_levels);
for _ in 0..stored_levels {
let offset = r.u64()? as usize;
let length = r.u64()? as usize;
let uncompressed_length = r.u64()? as usize;
let end = offset.checked_add(length).ok_or(Ktx2Error::Truncated)?;
let data = bytes.get(offset..end).ok_or(Ktx2Error::Truncated)?.to_vec();
levels.push(Level {
data,
uncompressed_length,
});
}
let transfer_function = if dfd_length >= 16 {
bytes.get(dfd_offset + 15).copied().unwrap_or(0)
} else {
0
};
let key_value = key_values(bytes, kvd_offset, kvd_length);
Ok(Ktx2 {
vk_format,
type_size,
width,
height,
depth,
layers,
faces,
level_count,
supercompression,
levels,
transfer_function,
key_value,
})
}
fn key_values(bytes: &[u8], offset: usize, length: usize) -> HashMap<String, Vec<u8>> {
let mut out = HashMap::new();
let Some(block) = bytes.get(offset..offset + length) else {
return out;
};
let mut at = 0usize;
while at + 4 <= block.len() {
let size =
u32::from_le_bytes([block[at], block[at + 1], block[at + 2], block[at + 3]]) as usize;
at += 4;
let Some(entry) = block.get(at..at + size) else {
break;
};
if let Some(split) = entry.iter().position(|b| *b == 0) {
let key = String::from_utf8_lossy(&entry[..split]).into_owned();
out.insert(key, entry[split + 1..].to_vec());
}
at += size.next_multiple_of(4);
}
out
}
impl Ktx2 {
pub fn texture_format(&self) -> Result<TextureFormat, Ktx2Error> {
use TextureFormat as F;
Ok(match self.vk_format {
9 => F::R8Unorm, 16 => F::Rg8Unorm, 37 => F::Rgba8Unorm, 43 => F::Rgba8UnormSrgb, 44 => F::Rgba8Unorm,
50 => F::Rgba8UnormSrgb,
64 => F::Rgb10a2Unorm, 70 => F::R16Unorm, 76 => F::R16Float, 83 => F::Rg16Float, 91 => F::Rgba16Unorm, 97 => F::Rgba16Float, 100 => F::R32Float, 103 => F::Rg32Float, 109 => F::Rgba32Float, 122 => F::Rg11b10Ufloat, 123 => F::Rgb9e5Ufloat, 131 | 133 => F::Bc1RgbaUnorm, 132 | 134 => F::Bc1RgbaUnormSrgb,
137 => F::Bc3RgbaUnorm, 138 => F::Bc3RgbaUnormSrgb,
139 => F::Bc4RUnorm, 141 => F::Bc5RgUnorm, 143 => F::Bc6hRgbUfloat, 144 => F::Bc6hRgbFloat, 145 => F::Bc7RgbaUnorm, 146 => F::Bc7RgbaUnormSrgb,
147 => F::Etc2Rgb8Unorm, 148 => F::Etc2Rgb8UnormSrgb,
151 => F::Etc2Rgba8Unorm, 152 => F::Etc2Rgba8UnormSrgb,
v @ 157..=184 => F::Astc {
block: crate::textures::AstcBlock::ALL[((v - 157) / 2) as usize],
srgb: (v - 157) % 2 == 1,
},
135 | 136 => return Err(Ktx2Error::Unsupported("BC2 (DXT3)")),
140 | 142 => return Err(Ktx2Error::Unsupported("signed BC4/BC5")),
149 | 150 => return Err(Ktx2Error::Unsupported("ETC2 RGB8A1 (punch-through alpha)")),
153..=156 => return Err(Ktx2Error::Unsupported("EAC R11/RG11")),
0 => {
return Err(Ktx2Error::Unsupported(
"Basis Universal, which needs transcoding",
))
}
_ => return Err(Ktx2Error::Unsupported("this Vulkan format")),
})
}
pub fn level_data(&self) -> Result<Vec<Vec<u8>>, Ktx2Error> {
let mut out = Vec::with_capacity(self.levels.len());
for level in &self.levels {
let bytes = match self.supercompression {
Supercompression::None => level.data.clone(),
Supercompression::Zlib => {
let inflated = crate::loaders::deflate::inflate_zlib(&level.data)
.map_err(|_| Ktx2Error::Corrupt)?;
if inflated.len() != level.uncompressed_length {
return Err(Ktx2Error::Corrupt);
}
inflated
}
Supercompression::Zstd => {
return Err(Ktx2Error::Unsupported("zstd supercompression"))
}
Supercompression::BasisLz => {
return Err(Ktx2Error::Unsupported("BasisLZ supercompression"))
}
};
out.push(bytes);
}
Ok(out)
}
pub fn to_texture(&self) -> Result<Texture, Ktx2Error> {
let format = self.texture_format()?;
if self.faces != 1 {
return Err(Ktx2Error::Unsupported("cube maps"));
}
if self.layers > 1 {
return Err(Ktx2Error::Unsupported("array textures"));
}
let mut data = self.level_data()?;
if data.is_empty() {
return Err(Ktx2Error::Corrupt);
}
if matches!(self.vk_format, 44 | 50) {
for level in &mut data {
for px in level.as_chunks_mut::<4>().0 {
px.swap(0, 2);
}
}
}
let base = data.remove(0);
let height = self.height.max(1);
if base.len() < format.data_len(self.width, height) {
return Err(Ktx2Error::Corrupt);
}
let mut texture = Texture::new(self.width, height, format, base);
texture.flip_y = false;
texture.mips = data.into_iter().map(Arc::new).collect();
Ok(texture)
}
}
#[cfg(test)]
mod tests {
use super::*;
const RGBA8: &[u8] = include_bytes!("testdata/ktx/rgba8.ktx2");
const BC7: &[u8] = include_bytes!("testdata/ktx/bc7.ktx2");
const MIPS: &[u8] = include_bytes!("testdata/ktx/mips.ktx2");
const ZLIB: &[u8] = include_bytes!("testdata/ktx/zlib.ktx2");
const KV: &[u8] = include_bytes!("testdata/ktx/kv.ktx2");
#[test]
fn an_uncompressed_texture_reads() {
let k = parse(RGBA8).expect("parses");
assert_eq!(k.vk_format, 43, "R8G8B8A8_SRGB");
assert_eq!((k.width, k.height), (4, 4));
assert_eq!(k.level_count, 1);
assert_eq!(k.faces, 1);
assert_eq!(k.supercompression, Supercompression::None);
assert_eq!(k.levels.len(), 1);
assert_eq!(k.levels[0].data.len(), 64, "4 * 4 * 4 bytes");
assert_eq!(k.levels[0].uncompressed_length, 64);
let texture = k.to_texture().expect("a texture");
assert_eq!(texture.format, TextureFormat::Rgba8UnormSrgb);
assert_eq!((texture.width, texture.height), (4, 4));
assert_eq!(&texture.data[..4], &[0, 255, 64, 255]);
assert_eq!(&texture.data[60..64], &[240, 15, 64, 255]);
}
#[test]
fn a_block_compressed_texture_reads() {
let k = parse(BC7).expect("parses");
assert_eq!(k.vk_format, 146, "BC7_SRGB_BLOCK");
assert_eq!((k.width, k.height), (8, 8));
let texture = k.to_texture().expect("a texture");
assert_eq!(texture.format, TextureFormat::Bc7RgbaUnormSrgb);
assert!(texture.format.is_block_compressed());
assert_eq!(texture.data.len(), 64, "2x2 blocks of 16 bytes");
assert_eq!(texture.data[0], 0x40, "the first block is untouched");
assert!(!texture.flip_y);
}
#[test]
fn a_mip_chain_reads_in_order() {
let k = parse(MIPS).expect("parses");
assert_eq!(k.level_count, 4);
assert_eq!(k.levels.len(), 4);
let sizes: Vec<usize> = k.levels.iter().map(|l| l.data.len()).collect();
assert_eq!(sizes, [256, 64, 16, 4], "8x8, 4x4, 2x2, 1x1 in RGBA8");
let texture = k.to_texture().expect("a texture");
assert_eq!(texture.data.len(), 256, "the base level");
assert_eq!(texture.mips.len(), 3, "and three smaller ones");
assert_eq!(texture.data[0], 8, "level 0 was filled with 8");
assert_eq!(texture.mips[0][0], 4, "level 1 with 4");
assert_eq!(texture.mips[2][0], 1, "level 3 with 1");
}
#[test]
fn zlib_supercompression_is_decompressed() {
let k = parse(ZLIB).expect("parses");
assert_eq!(k.supercompression, Supercompression::Zlib);
assert_eq!(k.levels[0].data.len(), 71, "as stored");
assert_eq!(k.levels[0].uncompressed_length, 64, "as it will be");
let texture = k.to_texture().expect("a texture");
assert_eq!(texture.data.len(), 64);
let plain = parse(RGBA8).unwrap().to_texture().unwrap();
assert_eq!(texture.data, plain.data, "compressed and plain disagree");
}
#[test]
fn key_value_metadata_reads() {
let k = parse(KV).expect("parses");
assert_eq!(
k.key_value.get("KTXorientation").map(|v| v.as_slice()),
Some(&b"rd\0"[..]),
"{:?}",
k.key_value.keys().collect::<Vec<_>>()
);
assert!(k.key_value.contains_key("KTXwriter"));
}
#[test]
fn unsupported_formats_name_themselves() {
let mut k = parse(RGBA8).unwrap();
k.vk_format = 0;
assert!(matches!(
k.texture_format(),
Err(Ktx2Error::Unsupported(what)) if what.contains("Basis")
));
k.vk_format = 135;
assert!(matches!(
k.texture_format(),
Err(Ktx2Error::Unsupported(what)) if what.contains("BC2")
));
k.vk_format = 149;
assert!(matches!(
k.texture_format(),
Err(Ktx2Error::Unsupported(what)) if what.contains("punch-through")
));
let mut z = parse(ZLIB).unwrap();
z.supercompression = Supercompression::Zstd;
assert!(matches!(
z.level_data(),
Err(Ktx2Error::Unsupported(what)) if what.contains("zstd")
));
}
#[test]
fn every_supported_vulkan_format_maps_to_its_own() {
use crate::textures::AstcBlock;
let mut k = parse(RGBA8).unwrap();
for (vk, want) in [
(145, TextureFormat::Bc7RgbaUnorm),
(146, TextureFormat::Bc7RgbaUnormSrgb),
(133, TextureFormat::Bc1RgbaUnorm),
(141, TextureFormat::Bc5RgUnorm),
(143, TextureFormat::Bc6hRgbUfloat),
(151, TextureFormat::Etc2Rgba8Unorm),
(
157,
TextureFormat::Astc {
block: AstcBlock::B4x4,
srgb: false,
},
),
(
172,
TextureFormat::Astc {
block: AstcBlock::B8x8,
srgb: true,
},
),
(
184,
TextureFormat::Astc {
block: AstcBlock::B12x12,
srgb: true,
},
),
(123, TextureFormat::Rgb9e5Ufloat),
(64, TextureFormat::Rgb10a2Unorm),
] {
k.vk_format = vk;
assert_eq!(k.texture_format(), Ok(want), "VkFormat {vk}");
}
}
#[test]
fn a_non_ktx2_file_is_refused_and_truncation_is_safe() {
assert_eq!(parse(b"not a texture").unwrap_err(), Ktx2Error::NotKtx2);
for cut in 0..RGBA8.len() {
let _ = parse(&RGBA8[..cut]);
}
for cut in 0..MIPS.len() {
let _ = parse(&MIPS[..cut]).map(|k| k.to_texture());
}
}
#[test]
fn bgra_is_swizzled_to_rgba() {
let mut k = parse(RGBA8).unwrap();
let original = k.to_texture().unwrap();
k.vk_format = 44;
let swizzled = k.to_texture().unwrap();
assert_eq!(swizzled.format, TextureFormat::Rgba8Unorm);
let (a, b) = (&original.data[..], &swizzled.data[..]);
assert_eq!(a.len(), b.len());
for (p, q) in a.as_chunks::<4>().0.iter().zip(b.as_chunks::<4>().0) {
assert_eq!([p[2], p[1], p[0], p[3]], [q[0], q[1], q[2], q[3]]);
}
}
}