btex spec.txt

// * Each level of each layer is called an image.
// * All the values are in little endian.
// * level(0) is called the base level.
// * level(0).size is (header.width, header.height)
// * level(i+1).size is max(1, floor(level(i).size / 2))
// * The min width, height and depth for the smallest level is (1, 1, 1)
// * Each layer may only have as many levels until (including) the smallest level size is reached
// * Zero sized layers must have zero levels.
// * Images have a top-left(-front) origin coordinate system, growing down and right (and forwards).
// * If the texture is zero-sized, all image formats should be seen as compatible
// * If, and only if, the sparse attribute is set may this texture contain omitted images.

#[repr(C)]
struct BTexFile {
	header: FileHeader,
	offset_table: OffsetTable,
	pixel_data_array: [[u8; m(i)]; n], // |n| is layers * levels. |m| is the size in bytes of the given image i, as specified in the offset table
}

#[repr(C)]
struct FileHeader {
	/// The magic number of the file.
	/// Always `['b', 't', 'e', 'x']`
	magic_number: [u8; 4],
	
	/// The version of the file.
	/// Right now always 1.
	version: u32,
	
	/// The total size in bytes of this header.
	/// Always 64 for now.
	header_length: u32,
	
	/// The total size in bytes of the offset table.
	/// Note that offset table starts immediately after the header.
	offset_table_length: u32,
	
	/// Flags about the texture.
	/// Bit 0 - Sparse flag: The offset table may contain omitted images
	attributes: u32,
	
	/// The width (x-resolution) of the base level of each layer.
	/// If width is zero all layers are zero-sized.
	/// If width is non-zero and both height and depth are zero, this texture is 1d.
	/// If both width and height are non-zero and depth is zero, this texture is 2d.
	/// If width, height and depth are all non-zero, this texture is 3d.
	width: u32,
	
	/// The height (y-resolution) of base level of each layer.
	/// If width is zero, height must also be zero.
	height: u32,
	
	/// The depth (z-resolution) of base level of each layer.
	/// If height is zero, depth must also be zero.
	depth: u32,
	
	/// The number of levels each layer.
	/// The number of levels must be greater than zero
	/// except if the layers are zero-sized, then it must be zero.
	/// 
	/// Note that there may only be as many levels until the smallest
	/// level size is reached, or zero if the layers are zero-sized.
	levels: u32,
	
	/// The number of layers in this texture.
	/// The number of layers must be greater than zero
	/// except if the layers are zero-sized, then it must be zero.
	/// If the file is storing one "logical" multi-level texture this will be 1.
	layers: u32,
	
	/// A string-based, case-sensitive, strictly compared enum representing
	/// the image format of the pixel data of all images in this texture.
	/// 
	/// Note that image formats store linear data if not otherwise specified.
	/// Note that most compressed formats are only compatible with 2d images.
	/// 
	/// Examples:
	/// * rgba8
	/// * srgb8_a8
	/// * bc1_rgb
	/// * bc1_rgb_a1
	/// * bc2_rgb_a4
	/// * bc3_rgba
	/// * bc4_r
	/// * bc5_r_g
	/// * bc6_rgb_float
	/// * bc7_rgb
	/// * bc7_rgba
	/// * astc_8x6
	/// * astc_4x4x4_srgb
	image_format: [u8; 16],
	
	_padding: [u8; 8],
}

#[repr(C)]
struct OffsetTable {
	/// Offsets in bytes from the start of the file to the start
	/// of the block of pixel data for an image, and the size of the
	/// data block in bytes.
	/// The offset array is grouped first by level then by layer.
	/// Example: [layer0.level0, layer0.level1, layer1.level0, layer1.level1]
	/// 
	/// The offsets (and therefore the pixel data in the file)
	/// should always be ordered from smallest to largest, if possible.
	/// 
	/// Multiple images may use the the same offset and pixel data if,
	/// and only if, the two images have the same size.
	/// (e.g. the same level from two seperate layers)
	/// 
	/// If the sparse flag is set in the attributes an offset may be zero,
	/// in which case the image is said to be 'omitted' and has no pixel data
	/// associated with it. How an omitted image is interpreted is up
	/// to the situation and context.
	data_offsets: [(u64, u64); n], // |n| is layers * levels
}