15.8. Portable BC texture compression, mip generation, caching, validation, and decoding

Portable BC1, BC3, BC4, and BC5 texture compression with complete mip chains, deterministic cache keys, serialized validation, and RGBA8 decoding.

15.8.1. Constants

BLOCK_TEXTURE_VERSION = 1

BLOCK_TEXTURE_VERSION:int const

15.8.2. Structures

BlockMip

One block-compressed mip level and its logical pixel dimensions.

Fields:

  • width : int - Logical width and height; edge blocks are padded by the compressor.

  • height : int - Logical width and height; edge blocks are padded by the compressor.

  • data : array<uint8> - Encoded BC block bytes in row-major block order.

BlockTexture

A complete BC-compressed texture with a deterministic content key and mip chain.

Fields:

  • version : int - Serialization layout version; must equal BLOCK_TEXTURE_VERSION.

  • width : int - Base dimensions and format code: BC1, BC3, BC4, or BC5 (0..3).

  • height : int - Base dimensions and format code: BC1, BC3, BC4, or BC5 (0..3).

  • format : int - Base dimensions and format code: BC1, BC3, BC4, or BC5 (0..3).

  • srgb : bool - Whether mip reduction treats RGB input as sRGB-encoded color.

  • key : uint64 - Content-derived cache key including dimensions, format, color space, and version.

  • mips : array< BlockMip> - Full mip chain from the base level through 1x1.

15.8.3. Compression and caching

block_texture_key(pixels: array<uint8>; width: int; height: int; format: int; srgb: bool ): uint64

Compute the deterministic cache key for tightly packed RGBA8 pixels and their compression settings. Callers must include exactly the same metadata later used for compression.

Arguments:

  • pixels : array<uint8>

  • width : int

  • height : int

  • format : int

  • srgb : bool

cached_block_texture(pixels: array<uint8>; width: int; height: int; format: int; srgb: bool; directory: string; hit: bool& ): BlockTexture

Load a valid content-keyed .das_tex entry from directory, or compress and atomically populate it on a miss. Sets hit only for a valid matching entry; an empty directory disables I/O.

Arguments:

  • pixels : array<uint8>

  • width : int

  • height : int

  • format : int

  • srgb : bool

  • directory : string

  • hit : bool&

compress_block_texture(pixels: array<uint8>; width: int; height: int; format: int; srgb: bool ): BlockTexture

Compress tightly packed RGBA8 pixels into BC1/BC3/BC4/BC5 (format 0..3), generating a box-filtered mip chain through 1x1. Panics when dimensions do not match the input byte count.

Arguments:

  • pixels : array<uint8>

  • width : int

  • height : int

  • format : int

  • srgb : bool

15.8.4. Validation and decoding

block_texture_valid(t: BlockTexture ): bool

Return true when version, dimensions, format, mip count, and every encoded byte size satisfy the serialized block-texture contract. This does not decode or assess image quality.

Arguments:
decode_block_mip(texture: BlockTexture; level: int ): array<uint8>

Decode one BC mip to tightly packed RGBA8 pixels. Panics if the texture contract is invalid or level is outside the stored mip chain.

Arguments: