1# Terminology for the ASTC Encoder 2 3Like most software, the `astcenc` code base has a set of naming conventions 4for variables which are used to ensure both accuracy and reasonable brevity. 5 6:construction: These conventions are being used for new patches, so new code 7will conform to this, but older code is still being cleaned up to follow 8these conventions. 9 10## Counts 11 12For counts of things prefer `<x>_count` rather than `<x>s`. For example: 13 14* `plane_count` 15* `weight_count` 16* `texel_count` 17 18Where possible aim for descriptive loop variables, as these are more literate 19than simple `i` or `j` variables. For example: 20 21* `plane_index` 22* `weight_index` 23* `texel_index` 24 25## Ideal, Unpacked Quantized, vs Packed Quantized 26 27Variables that are quantized, such as endpoint colors and weights, have 28multiple states depending on how they are being used. 29 30**Ideal values** represent arbitrary numeric values that can take any value. 31These are often used during compression to work out the best value before 32any quantization is applied. For example, integer weights in the 0-64 range can 33take any of the 65 values available. 34 35**Quant uvalues** represent the unpacked numeric value after any quantization 36rounding has been applied. These are often used during compression to work out 37the error for the quantized value compared to the ideal value. For example, 38`QUANT_3` weights in the 0-64 range can only take one of `[0, 32, 64]`. 39 40**Quant pvalues** represent the packed numeric value in the quantized alphabet. 41This is what ends up encoded in the ASTC data, although note that the encoded 42ordering is scrambled to simplify hardware. For example, `QUANT_3` weights 43originally in the 0-64 range can only take one of `[0, 1, 2]`. 44 45For example: 46 47* `weights_ideal_value` 48* `weights_quant_uvalue` 49* `weights_quant_pvalue` 50 51## Full vs Decimated interpolation weights 52 53Weight grids have multiple states depending on how they are being used. 54 55**full_weights** represent per texel weight grids, storing one weight per texel. 56 57**decimated_weights** represent reduced weight grids, which can store fewer 58weights and which are bilinear interpolated to generate the full weight grid. 59 60Full weights have no variable prefix,but decimated weights are stored with 61a `dec_` prefix. 62 63* `dec_weights_ideal_value` 64* `dec_weights_quant_uvalue` 65* `dec_weights_quant_pvalue` 66 67## Weight vs Significance 68 69The original encoder used "weight" for multiple purposes - texel significance 70(weight the error), color channel significance (weight the error), and endpoint 71interpolation weights. This gets very confusing in functions using all three! 72 73We are slowly refactoring the code to only use "weight" to mean the endpoint 74interpolation weights. The error weighting factors used for other purposes are 75being updated to use the using the term "significance". 76 77- - - 78 79_Copyright © 2020-2022, Arm Limited and contributors. All rights reserved._ 80