.. _stdlib_texture_blocks:

==================================================================================
Portable BC texture compression, mip generation, caching, validation, and decoding
==================================================================================

.. das:module:: texture_blocks

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



+++++++++
Constants
+++++++++

.. _global-texture_blocks-BLOCK_TEXTURE_VERSION:

.. das:attribute:: BLOCK_TEXTURE_VERSION = 1

BLOCK_TEXTURE_VERSION:int const


++++++++++
Structures
++++++++++

.. _struct-texture_blocks-BlockMip:

.. das:attribute:: 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.



.. _struct-texture_blocks-BlockTexture:

.. das:attribute:: 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< :ref:`BlockMip <struct-texture_blocks-BlockMip>`> - Full mip chain from the base level through 1x1.




+++++++++++++++++++++++
Compression and caching
+++++++++++++++++++++++

  *  :ref:`block_texture_key (pixels: array\<uint8\>; width: int; height: int; format: int; srgb: bool) : uint64 <function-texture_blocks_block_texture_key_array_ls_uint8_gr__int_int_int_bool>`
  *  :ref:`cached_block_texture (pixels: array\<uint8\>; width: int; height: int; format: int; srgb: bool; directory: string; var hit: bool&) : BlockTexture <function-texture_blocks_cached_block_texture_array_ls_uint8_gr__int_int_int_bool_string_bool_ref_>`
  *  :ref:`compress_block_texture (pixels: array\<uint8\>; width: int; height: int; format: int; srgb: bool) : BlockTexture <function-texture_blocks_compress_block_texture_array_ls_uint8_gr__int_int_int_bool>`

.. _function-texture_blocks_block_texture_key_array_ls_uint8_gr__int_int_int_bool:

.. das:function:: 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

.. _function-texture_blocks_cached_block_texture_array_ls_uint8_gr__int_int_int_bool_string_bool_ref_:

.. das:function:: 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\ &

.. _function-texture_blocks_compress_block_texture_array_ls_uint8_gr__int_int_int_bool:

.. das:function:: 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


+++++++++++++++++++++++
Validation and decoding
+++++++++++++++++++++++

  *  :ref:`block_texture_valid (t: BlockTexture) : bool <function-texture_blocks_block_texture_valid_BlockTexture>`
  *  :ref:`decode_block_mip (texture: BlockTexture; level: int) : array\<uint8\> <function-texture_blocks_decode_block_mip_BlockTexture_int>`

.. _function-texture_blocks_block_texture_valid_BlockTexture:

.. das:function:: 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: * **t** :  :ref:`BlockTexture <struct-texture_blocks-BlockTexture>`

.. _function-texture_blocks_decode_block_mip_BlockTexture_int:

.. das:function:: 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: * **texture** :  :ref:`BlockTexture <struct-texture_blocks-BlockTexture>`

            * **level** : int