Basis Universal, from Binomial, is a texture format that a program turns into whatever block format the graphics card has. A KTX 2 file can hold it in two forms: ETC1S data with BasisLZ supercompression, and UASTC blocks. The KTX specification says where the data is and what it is called; the bit-level layouts below come from the open source Basis Universal transcoder (Apache-2.0). The viewer decodes both to pictures by going to ETC1 blocks (ETC1S) or straight to pixels (UASTC); it never makes another GPU format on the way.
ETC1S with BasisLZ
The data format descriptor has the colour model ETC1S (163), vkFormat is 0, and
the supercompression global data
holds two codebooks and the Huffman tables for the slices. Every 4 × 4 block of an image
is one entry of the endpoint palette (a base colour and an intensity table) and
one entry of the selector palette (16 two-bit selectors), which together are an
ETC1 block in which both halves share one colour and one table.
Bits and Huffman tables
Every part is read from a bit string whose first bit is the least significant bit of its first byte. A Huffman table is coded as:
- 14 bits: the number of symbols (0 is an empty table, and nothing else follows).
- 5 bits: the number of code length codes, 1 to 21; then that many 3-bit sizes, for the code length symbols in the order 17, 18, 19, 20, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15, 16 (the other symbols have size 0).
- The size of each symbol, coded with that code: the symbols 0 to 16 are the size itself; 17 is a run of 3 to 10 zero sizes (3 more bits); 18 a run of 11 to 138 zeros (7 more bits); 19 repeats the size before it 3 to 6 times (2 more bits); 20 repeats it 7 to 134 times (7 more bits).
Codes are canonical: shorter codes first, equal lengths in symbol order, and a code is read from its most significant bit.
Endpoint codebook
The endpoint data starts with four Huffman tables: the change of a colour component when the one before was at most 9, when it was 10 to 21, and when it was above 21, and the change of the intensity table. One bit then says whether every endpoint is grey (only the red component is coded). The endpoints follow, each as: the intensity table (0 to 7) as a change from the one before, modulo 8, and then each colour component (5 bits) as a change from the same component of the endpoint before, modulo 32. The first endpoint is relative to the colour (16, 16, 16) and the intensity table 0.
Selector codebook
Three bits: a global-codebook flag and a hybrid flag (both must be 0 in KTX 2) and a raw flag. Raw: for each selector, 4 bytes, one for each row of the block, the selector of the pixel at column x in bits 2x and 2x + 1. Otherwise: one Huffman table of byte deltas; the first selector is 4 raw bytes, and every later byte is the table’s symbol XOR the same byte of the selector before. A selector value 0 to 3 picks the entry of the ETC1 modifier table in rising order (the ETC1 bit codes 3, 2, 0, 1).
Slice tables
Five items: a Huffman table of 257 symbols for the endpoint prediction (the 256 values of a group of four predictions, and a symbol that repeats the last), a table for the endpoint index delta, a table for the selector (one symbol per selector, then one per slot of the selector history buffer, then a symbol for a run), a table for the length of a run, and 13 bits: the size of the selector history buffer (not 0).
A slice
A slice is a Huffman-coded walk over the blocks from the top left, row by row. For each block it gives an endpoint index and a selector index.
- Endpoint. A prediction symbol is read for each 2 × 2 group of blocks on every even row (or repeated: 4 bits give a run length plus 3); it holds a 2-bit prediction for each of the four blocks, taken as the group’s bits low to high; the two blocks of the row below use the upper two. A prediction is 0, the block to the left; 1, the block above; 2, the block above and to the left; 3, a coded change from the previous endpoint index, wrapping round the number of endpoints.
- Selector. A symbol is read; a symbol below the selector count is that selector, and is added to the history buffer. A symbol that is the run symbol starts a run of the selector at history position 0, of a length from the run table (plus 3; the last symbol of the table means 7 more bits plus 3). Any other symbol is a position in the history buffer: the selector there is used, and the entry is swapped with the entry at half its index. The history buffer holds the size from the slice tables and is a ring that starts half way.
An image with alpha has a second slice, coded the same way, whose pixels’ green component is the alpha. A texture with one or two channels uses the slices for them: ETC1S “RRR” is one slice holding grey; “RG” puts the red of one slice in the first channel and the red of the other in the second.
UASTC LDR 4x4
The data format descriptor has the colour model UASTC (166), vkFormat is 0, a
block is 4 × 4 texels in 16 bytes, and the channel type says what the block holds: RGB,
RGBA, RRR (one channel shown as grey), RRRG (grey and alpha) or RG. The data is usually
supercompressed with Zstandard. A block starts with a prefix code that gives one of 19
modes (or the reserved 20th, which is an error):
| Mode | Prefix (bits read first to last) | Subsets | Weight planes | Components | Weight bits | Endpoint levels | Hint bits |
|---|---|---|---|---|---|---|---|
| 0 | 1000 (4 bits) | 1 | 1 | RGB | 4 | 192 | 15 |
| 1 | 101011 (6) | 1 | 1 | RGB | 2 | 256 | 15 |
| 2 | 10111 (5) | 2 | 1 | RGB | 3 | 16 | 15 |
| 3 | 11000 (5) | 3 | 1 | RGB | 2 | 12 | 15 |
| 4 | 11001 (5) | 2 | 1 | RGB | 2 | 40 | 15 |
| 5 | 11010 (5) | 1 | 1 | RGB | 3 | 256 | 15 |
| 6 | 11011 (5) | 1 | 2 | RGB | 2 | 160 | 15 |
| 7 | 11100 (5) | 2 | 1 | RGB | 2 | 40 | 15 |
| 8 | 11101 (5) | solid colour: 8 bits each of red, green, blue and alpha, then hints | |||||
| 9 | 11110 (5) | 2 | 1 | RGBA | 2 | 16 | 23 |
| 10 | 010 (3) | 1 | 1 | RGBA | 4 | 48 | 17 |
| 11 | 00 (2) | 1 | 2 | RGBA | 2 | 48 | 17 |
| 12 | 011 (3) | 1 | 1 | RGBA | 3 | 192 | 17 |
| 13 | 11111 (5) | 1 | 2 | RGBA | 1 | 256 | 23 |
| 14 | 10110 (5) | 1 | 1 | RGBA | 2 | 256 | 23 |
| 15 | 1010000 (7) | 1 | 1 | luminance, alpha | 4 | 256 | 23 |
| 16 | 101010 (6) | 2 | 1 | luminance, alpha | 2 | 256 | 23 |
| 17 | 101001 (6) | 1 | 2 | luminance, alpha | 2 | 256 | 23 |
| 18 | 1001 (4) | 1 | 1 | RGB | 5 | 32 | 15 |
After the prefix come the hint bits (the count in the last column), which only help a transcoder to ETC1, ETC2 and BC1 and are ignored when making pixels. Then:
- For modes 2, 4, 7, 9 and 16 a 5-bit index of a common 2-subset partition (mode 3: a
4-bit index of a 3-subset one). The partition is the ASTC partition of a seed. Modes 2, 4, 9, 16:
28 20 16 29 91 9 107 72 149 204 50 114 496 17 78 39 252 828 43 156 116 210 476 273 684 359 246 195 694 524(30 seeds). Mode 7:36 48 61 137 161 183 226 281 302 307 479 495 593 594 605 799 812 988 993. Mode 3:260 74 32 156 183 15 745 0 335 902 254. An index past the end of its list is an error. - For modes 6, 11 and 13 a 2-bit number: the component whose weights are in the second plane. Mode 17 always uses component 3 (alpha).
- The endpoints, two values per component per subset, as ASTC bounded integer sequence values of the “levels” in the table: the trits or quints of a group first (8 bits for five trits, 7 bits for three quints), then the low bits of each value, in order. The values are unquantised with the ASTC colour unquantisation tables.
- The weights, one per texel (two for a texel in the dual plane modes), of “weight bits” each. The weight of the first texel of every subset (the first texel in raster order that falls in it) has one bit fewer, and its top bit is 0. Mode 18 reads sixteen weights in turn; the others fit in 64 bits.
A texel is the interpolation, with the ASTC weight (0 to 64 from the weight value) of the subset’s two endpoints; the 8-bit endpoints are expanded to 16 bits by repeating the byte, and the 16-bit result is shifted right by 8. The viewer interpolates the stored values as they are, whatever the transfer function: it is how Binomial’s own transcoder makes RGBA from UASTC. Luminance-alpha modes copy the luminance to red, green and blue.
UASTC HDR
The colour models UASTC HDR 4x4 (167) and UASTC HDR 6x6 (168) hold ASTC HDR blocks of 4 × 4 and 6 × 6 texels: a block is an ordinary ASTC block, decoded with the ASTC rules (see texture formats). Supercompression scheme 4, the intermediate UASTC HDR 6x6 form, is a further coding that is not described here.
Sources
- Basis Universal – Binomial:
basisu_transcoder.cpp,basisu_lowlevel_etc1s_transcoderandunpack_uastc; Apache-2.0 - KTX File Format Specification, version 2.0 – Khronos Group: Appendix C, BasisLZ global data
- Khronos Data Format Specification – the ETC1S and UASTC colour models