1 // SPDX-License-Identifier: Apache-2.0 2 // ---------------------------------------------------------------------------- 3 // Copyright 2020-2022 Arm Limited 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 6 // use this file except in compliance with the License. You may obtain a copy 7 // of the License at: 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 13 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 14 // License for the specific language governing permissions and limitations 15 // under the License. 16 // ---------------------------------------------------------------------------- 17 18 /** 19 * @brief The core astcenc codec library interface. 20 * 21 * This interface is the entry point to the core astcenc codec. It aims to be easy to use for 22 * non-experts, but also to allow experts to have fine control over the compressor heuristics if 23 * needed. The core codec only handles compression and decompression, transferring all inputs and 24 * outputs via memory buffers. To catch obvious input/output buffer sizing issues, which can cause 25 * security and stability problems, all transfer buffers are explicitly sized. 26 * 27 * While the aim is that we keep this interface mostly stable, it should be viewed as a mutable 28 * interface tied to a specific source version. We are not trying to maintain backwards 29 * compatibility across codec versions. 30 * 31 * The API state management is based around an explicit context object, which is the context for all 32 * allocated memory resources needed to compress and decompress a single image. A context can be 33 * used to sequentially compress multiple images using the same configuration, allowing setup 34 * overheads to be amortized over multiple images, which is particularly important when images are 35 * small. 36 * 37 * Multi-threading can be used two ways. 38 * 39 * * An application wishing to process multiple images in parallel can allocate multiple 40 * contexts and assign each context to a thread. 41 * * An application wishing to process a single image in using multiple threads can configure 42 * contexts for multi-threaded use, and invoke astcenc_compress/decompress() once per thread 43 * for faster processing. The caller is responsible for creating the worker threads, and 44 * synchronizing between images. 45 * 46 * Threading 47 * ========= 48 * 49 * In pseudocode, the usage for manual user threading looks like this: 50 * 51 * // Configure the compressor run 52 * astcenc_config my_config; 53 * astcenc_config_init(..., &my_config); 54 * 55 * // Power users can tweak <my_config> settings here ... 56 * 57 * // Allocate working state given config and thread_count 58 * astcenc_context* my_context; 59 * astcenc_context_alloc(&my_config, thread_count, &my_context); 60 * 61 * // Compress each image using these config settings 62 * foreach image: 63 * // For each thread in the thread pool 64 * for i in range(0, thread_count): 65 * astcenc_compress_image(my_context, &my_input, my_output, i); 66 * 67 * astcenc_compress_reset(my_context); 68 * 69 * // Clean up 70 * astcenc_context_free(my_context); 71 * 72 * Images 73 * ====== 74 * 75 * The codec supports compressing single images, which can be either 2D images or volumetric 3D 76 * images. Calling code is responsible for any handling of aggregate types, such as mipmap chains, 77 * texture arrays, or sliced 3D textures 78 * 79 * Images are passed in as an astcenc_image structure. Inputs can be either 8-bit unorm, 16-bit 80 * half-float, or 32-bit float, as indicated by the data_type field. 81 * 82 * Images can be any dimension; there is no requirement to be a multiple of the ASTC block size. 83 * 84 * Data is always passed in as 4 color components, and accessed as an array of 2D image slices. Data 85 * within an image slice is always tightly packed without padding. Addresing looks like this: 86 * 87 * data[z_coord][y_coord * x_dim * 4 + x_coord * 4 ] // Red 88 * data[z_coord][y_coord * x_dim * 4 + x_coord * 4 + 1] // Green 89 * data[z_coord][y_coord * x_dim * 4 + x_coord * 4 + 2] // Blue 90 * data[z_coord][y_coord * x_dim * 4 + x_coord * 4 + 3] // Alpha 91 * 92 * Common compressor usage 93 * ======================= 94 * 95 * One of the most important things for coding image quality is to align the input data component 96 * count with the ASTC color endpoint mode. This avoids wasting bits encoding components you don't 97 * actually need in the endpoint colors. 98 * 99 * | Input data | Encoding swizzle | Sampling swizzle | 100 * | ------------ | ---------------- | ---------------- | 101 * | 1 component | RRR1 | .[rgb] | 102 * | 2 components | RRRG | .[rgb]a | 103 * | 3 components | RGB1 | .rgb | 104 * | 4 components | RGBA | .rgba | 105 * 106 * The 1 and 2 component modes recommend sampling from "g" to recover the luminance value as this 107 * provide best compatibility with other texture formats where the green component may be stored at 108 * higher precision than the others, such as RGB565. For ASTC any of the RGB components can be used; 109 * the luminance endpoint component will be returned for all three. 110 * 111 * When using the normal map compression mode ASTC will store normals as a two component X+Y map. 112 * Input images must contain unit-length normalized and should be passed in using a two component 113 * swizzle. The astcenc command line tool defaults to an RRRG swizzle, but some developers prefer 114 * to use GGGR for compatability with BC5n which will work just as well. The Z component can be 115 * recovered programatically in shader code, using knowledge that the vector is unit length and that 116 * Z must be positive for a tangent-space normal map. 117 * 118 * Decompress-only usage 119 * ===================== 120 * 121 * For some use cases it is useful to have a cut-down context and/or library which supports 122 * decompression but not compression. 123 * 124 * A context can be made decompress-only using the ASTCENC_FLG_DECOMPRESS_ONLY flag when the context 125 * is allocated. These contexts have lower dynamic memory footprint than a full context. 126 * 127 * The entire library can be made decompress-only by building the files with the define 128 * ASTCENC_DECOMPRESS_ONLY set. In this build the context will be smaller, and the library will 129 * exclude the functionality which is only needed for compression. This reduces the binary size by 130 * ~180KB. For these builds contexts must be created with the ASTCENC_FLG_DECOMPRESS_ONLY flag. 131 * 132 * Note that context structures returned by a library built as decompress-only are incompatible with 133 * a library built with compression included, and visa versa, as they have different sizes and 134 * memory layout. 135 * 136 * Self-decompress-only usage 137 * ========================== 138 * 139 * ASTC is a complex format with a large search space. The parts of this search space that are 140 * searched is determined by heuristics that are, in part, tied to the quality level used when 141 * creating the context. 142 * 143 * A normal context is capable of decompressing any ASTC texture, including those generated by other 144 * compressors with unknown heuristics. This is the most flexible implementation, but forces the 145 * data tables used by the codec to include entries that are not needed during compression. This 146 * can slow down context creation by a significant amount, especially for the faster compression 147 * modes where few data table entries are actually used. To optimize this use case the context can 148 * be created with the ASTCENC_FLG_SELF_DECOMPRESS_ONLY flag. This tells the compressor that it will 149 * only be asked to decompress images that it compressed itself, allowing the data tables to 150 * exclude entries that are not needed by the current compression configuration. This reduces the 151 * size of the context data tables in memory and improves context creation performance. Note that, 152 * as of the 3.6 release, this flag no longer affects compression performance. 153 * 154 * Using this flag while attempting to decompress an valid image which was created by another 155 * compressor, or even another astcenc compressor version or configuration, may result in blocks 156 * returning as solid magenta or NaN value error blocks. 157 */ 158 159 #ifndef ASTCENC_INCLUDED 160 #define ASTCENC_INCLUDED 161 162 #include <cstddef> 163 #include <cstdint> 164 #if defined(__aarch64__) 165 #define ASTCENC_NEON 1 166 #else 167 #define ASTCENC_NEON 0 168 #endif 169 170 enum QualityProfile { 171 HIGH_QUALITY_PROFILE = 0, // default profile 172 HIGH_SPEED_PROFILE 173 }; 174 175 static const int HIGH_SPEED_PROFILE_BLOCK_MODE = 67; // keep openSource type, example 176 static const int BYTE_MASK = 0xFF; 177 178 #define QUALITY_CONTROL (1) 179 #if QUALITY_CONTROL 180 enum ComponentRGBA { 181 R_COM = 0, 182 G_COM, 183 B_COM, 184 A_COM, 185 RGBA_COM 186 }; 187 #endif 188 189 #if defined(ASTCENC_DYNAMIC_LIBRARY) 190 #if defined(_MSC_VER) 191 #define ASTCENC_PUBLIC extern "C" __declspec(dllexport) 192 #else 193 #define ASTCENC_PUBLIC extern "C" __attribute__ ((visibility ("default"))) 194 #endif 195 #else 196 #define ASTCENC_PUBLIC 197 #endif 198 199 /* ============================================================================ 200 Data declarations 201 ============================================================================ */ 202 203 /** 204 * @brief An opaque structure; see astcenc_internal.h for definition. 205 */ 206 struct astcenc_context; 207 208 /** 209 * @brief A codec API error code. 210 */ 211 enum astcenc_error { 212 /** @brief The call was successful. */ 213 ASTCENC_SUCCESS = 0, 214 /** @brief The call failed due to low memory, or undersized I/O buffers. */ 215 ASTCENC_ERR_OUT_OF_MEM, 216 /** @brief The call failed due to the build using fast math. */ 217 ASTCENC_ERR_BAD_CPU_FLOAT, 218 /** @brief The call failed due to the build using an unsupported ISA. */ 219 ASTCENC_ERR_BAD_CPU_ISA, 220 /** @brief The call failed due to an out-of-spec parameter. */ 221 ASTCENC_ERR_BAD_PARAM, 222 /** @brief The call failed due to an out-of-spec block size. */ 223 ASTCENC_ERR_BAD_BLOCK_SIZE, 224 /** @brief The call failed due to an out-of-spec color profile. */ 225 ASTCENC_ERR_BAD_PROFILE, 226 /** @brief The call failed due to an out-of-spec quality value. */ 227 ASTCENC_ERR_BAD_QUALITY, 228 /** @brief The call failed due to an out-of-spec component swizzle. */ 229 ASTCENC_ERR_BAD_SWIZZLE, 230 /** @brief The call failed due to an out-of-spec flag set. */ 231 ASTCENC_ERR_BAD_FLAGS, 232 /** @brief The call failed due to the context not supporting the operation. */ 233 ASTCENC_ERR_BAD_CONTEXT, 234 /** @brief The call failed due to unimplemented functionality. */ 235 ASTCENC_ERR_NOT_IMPLEMENTED, 236 #if defined(ASTCENC_DIAGNOSTICS) 237 /** @brief The call failed due to an issue with diagnostic tracing. */ 238 ASTCENC_ERR_DTRACE_FAILURE, 239 #endif 240 #if QUALITY_CONTROL 241 ASTCENC_ERR_BAD_QUALITY_CHECK 242 #endif 243 }; 244 245 /** 246 * @brief A codec color profile. 247 */ 248 enum astcenc_profile { 249 /** @brief The LDR sRGB color profile. */ 250 ASTCENC_PRF_LDR_SRGB = 0, 251 /** @brief The LDR linear color profile. */ 252 ASTCENC_PRF_LDR, 253 /** @brief The HDR RGB with LDR alpha color profile. */ 254 ASTCENC_PRF_HDR_RGB_LDR_A, 255 /** @brief The HDR RGBA color profile. */ 256 ASTCENC_PRF_HDR 257 }; 258 259 /** @brief The fastest, lowest quality, search preset. */ 260 static const float ASTCENC_PRE_FASTEST = 0.0f; 261 262 /** @brief The fast search preset. */ 263 static const float ASTCENC_PRE_FAST = 10.0f; 264 265 /** @brief The medium quality search preset. */ 266 static const float ASTCENC_PRE_MEDIUM = 60.0f; 267 268 /** @brief The throrough quality search preset. */ 269 static const float ASTCENC_PRE_THOROUGH = 98.0f; 270 271 /** @brief The exhaustive, highest quality, search preset. */ 272 static const float ASTCENC_PRE_EXHAUSTIVE = 100.0f; 273 274 /** 275 * @brief A codec component swizzle selector. 276 */ 277 enum astcenc_swz 278 { 279 /** @brief Select the red component. */ 280 ASTCENC_SWZ_R = 0, 281 /** @brief Select the green component. */ 282 ASTCENC_SWZ_G = 1, 283 /** @brief Select the blue component. */ 284 ASTCENC_SWZ_B = 2, 285 /** @brief Select the alpha component. */ 286 ASTCENC_SWZ_A = 3, 287 /** @brief Use a constant zero component. */ 288 ASTCENC_SWZ_0 = 4, 289 /** @brief Use a constant one component. */ 290 ASTCENC_SWZ_1 = 5, 291 /** @brief Use a reconstructed normal vector Z component. */ 292 ASTCENC_SWZ_Z = 6 293 }; 294 295 /** 296 * @brief A texel component swizzle. 297 */ 298 struct astcenc_swizzle 299 { 300 /** @brief The red component selector. */ 301 astcenc_swz r; 302 /** @brief The green component selector. */ 303 astcenc_swz g; 304 /** @brief The blue component selector. */ 305 astcenc_swz b; 306 /** @brief The alpha component selector. */ 307 astcenc_swz a; 308 }; 309 310 /** 311 * @brief A texel component data format. 312 */ 313 enum astcenc_type 314 { 315 /** @brief Unorm 8-bit data per component. */ 316 ASTCENC_TYPE_U8 = 0, 317 /** @brief 16-bit float per component. */ 318 ASTCENC_TYPE_F16 = 1, 319 /** @brief 32-bit float per component. */ 320 ASTCENC_TYPE_F32 = 2 321 }; 322 323 /** 324 * @brief Enable normal map compression. 325 * 326 * Input data will be treated a two component normal map, storing X and Y, and the codec will 327 * optimize for angular error rather than simple linear PSNR. In this mode the input swizzle should 328 * be e.g. rrrg (the default ordering for ASTC normals on the command line) or gggr (the ordering 329 * used by BC5n). 330 */ 331 static const unsigned int ASTCENC_FLG_MAP_NORMAL = 1 << 0; 332 333 /** 334 * @brief Enable mask map compression. 335 * 336 * Input data will be treated a multi-layer mask map, where is is desirable for the color components 337 * to be treated independently for the purposes of error analysis. 338 */ 339 static const unsigned int ASTCENC_FLG_MAP_MASK = 1 << 1; 340 341 /** 342 * @brief Enable RGBM map compression. 343 * 344 * Input data will be treated as HDR data that has been stored in an LDR RGBM-encoded wrapper 345 * format. Data must be preprocessed by the user to be in LDR RGBM format before calling the 346 * compression function, this flag is only used to control the use of RGBM-specific heuristics and 347 * error metrics. 348 * 349 * IMPORTANT: The ASTC format is prone to bad failure modes with unconstrained RGBM data; very small 350 * M values can round to zero due to quantization and result in black or white pixels. It is highly 351 * recommended that the minimum value of M used in the encoding is kept above a lower threshold (try 352 * 16 or 32). Applying this threshold reduces the number of very dark colors that can be 353 * represented, but is still higher precision than 8-bit LDR. 354 * 355 * When this flag is set the value of @c rgbm_m_scale in the context must be set to the RGBM scale 356 * factor used during reconstruction. This defaults to 5 when in RGBM mode. 357 * 358 * It is recommended that the value of @c cw_a_weight is set to twice the value of the multiplier 359 * scale, ensuring that the M value is accurately encoded. This defaults to 10 when in RGBM mode, 360 * matching the default scale factor. 361 */ 362 static const unsigned int ASTCENC_FLG_MAP_RGBM = 1 << 6; 363 364 /** 365 * @brief Enable alpha weighting. 366 * 367 * The input alpha value is used for transparency, so errors in the RGB components are weighted by 368 * the transparency level. This allows the codec to more accurately encode the alpha value in areas 369 * where the color value is less significant. 370 */ 371 static const unsigned int ASTCENC_FLG_USE_ALPHA_WEIGHT = 1 << 2; 372 373 /** 374 * @brief Enable perceptual error metrics. 375 * 376 * This mode enables perceptual compression mode, which will optimize for perceptual error rather 377 * than best PSNR. Only some input modes support perceptual error metrics. 378 */ 379 static const unsigned int ASTCENC_FLG_USE_PERCEPTUAL = 1 << 3; 380 381 /** 382 * @brief Create a decompression-only context. 383 * 384 * This mode disables support for compression. This enables context allocation to skip some 385 * transient buffer allocation, resulting in lower memory usage. 386 */ 387 static const unsigned int ASTCENC_FLG_DECOMPRESS_ONLY = 1 << 4; 388 389 /** 390 * @brief Create a self-decompression context. 391 * 392 * This mode configures the compressor so that it is only guaranteed to be able to decompress images 393 * that were actually created using the current context. This is the common case for compression use 394 * cases, and setting this flag enables additional optimizations, but does mean that the context 395 * cannot reliably decompress arbitrary ASTC images. 396 */ 397 static const unsigned int ASTCENC_FLG_SELF_DECOMPRESS_ONLY = 1 << 5; 398 399 /** 400 * @brief The bit mask of all valid flags. 401 */ 402 static const unsigned int ASTCENC_ALL_FLAGS = 403 ASTCENC_FLG_MAP_MASK | 404 ASTCENC_FLG_MAP_NORMAL | 405 ASTCENC_FLG_MAP_RGBM | 406 ASTCENC_FLG_USE_ALPHA_WEIGHT | 407 ASTCENC_FLG_USE_PERCEPTUAL | 408 ASTCENC_FLG_DECOMPRESS_ONLY | 409 ASTCENC_FLG_SELF_DECOMPRESS_ONLY; 410 411 /** 412 * @brief The config structure. 413 * 414 * This structure will initially be populated by a call to astcenc_config_init, but power users may 415 * modify it before calling astcenc_context_alloc. See astcenccli_toplevel_help.cpp for full user 416 * documentation of the power-user settings. 417 * 418 * Note for any settings which are associated with a specific color component, the value in the 419 * config applies to the component that exists after any compression data swizzle is applied. 420 */ 421 struct astcenc_config 422 { 423 /** @brief The color profile. */ 424 astcenc_profile profile; 425 426 /** @brief The set of set flags. */ 427 unsigned int flags; 428 429 /** @brief The ASTC block size X dimension. */ 430 unsigned int block_x; 431 432 /** @brief The ASTC block size Y dimension. */ 433 unsigned int block_y; 434 435 /** @brief The ASTC block size Z dimension. */ 436 unsigned int block_z; 437 438 /** @brief The red component weight scale for error weighting (-cw). */ 439 float cw_r_weight; 440 441 /** @brief The green component weight scale for error weighting (-cw). */ 442 float cw_g_weight; 443 444 /** @brief The blue component weight scale for error weighting (-cw). */ 445 float cw_b_weight; 446 447 /** @brief The alpha component weight scale for error weighting (-cw). */ 448 float cw_a_weight; 449 450 /** 451 * @brief The radius for any alpha-weight scaling (-a). 452 * 453 * It is recommended that this is set to 1 when using FLG_USE_ALPHA_WEIGHT on a texture that 454 * will be sampled using linear texture filtering to minimize color bleed out of transparent 455 * texels that are adjcent to non-transparent texels. 456 */ 457 unsigned int a_scale_radius; 458 459 /** @brief The RGBM scale factor for the shared multiplier (-rgbm). */ 460 float rgbm_m_scale; 461 462 /** 463 * @brief The maximum number of partitions searched (-partitioncountlimit). 464 * 465 * Valid values are between 1 and 4. 466 */ 467 unsigned int tune_partition_count_limit; 468 469 /** 470 * @brief The maximum number of partitions searched (-partitionindexlimit). 471 * 472 * Valid values are between 1 and 1024. 473 */ 474 unsigned int tune_partition_index_limit; 475 476 /** 477 * @brief The maximum centile for block modes searched (-blockmodelimit). 478 * 479 * Valid values are between 1 and 100. 480 */ 481 unsigned int tune_block_mode_limit; 482 483 /** 484 * @brief The maximum iterative refinements applied (-refinementlimit). 485 * 486 * Valid values are between 1 and N; there is no technical upper limit 487 * but little benefit is expected after N=4. 488 */ 489 unsigned int tune_refinement_limit; 490 491 /** 492 * @brief The number of trial candidates per mode search (-candidatelimit). 493 * 494 * Valid values are between 1 and TUNE_MAX_TRIAL_CANDIDATES (default 4). 495 */ 496 unsigned int tune_candidate_limit; 497 498 /** 499 * @brief The dB threshold for stopping block search (-dblimit). 500 * 501 * This option is ineffective for HDR textures. 502 */ 503 float tune_db_limit; 504 505 /** 506 * @brief The amount of overshoot needed to early-out mode 0 fast path. 507 * 508 * We have a fast-path for mode 0 (1 partition, 1 plane) which uses only essential block modes 509 * as an initital search. This can short-cut compression for simple blocks, but to avoid 510 * shortcutting too much we* force this to overshoot the MSE threshold needed to hit the 511 * block-local db_limit e.g. 1.0 = no overshoot, 2.0 = need half the error to trigger. 512 */ 513 float tune_mode0_mse_overshoot; 514 515 /** 516 * @brief The amount of overshoot needed to early-out refinement. 517 * 518 * The codec will refine block candidates iteratively to improve the encoding, based on the 519 * @c tune_refinement_limit count. Earlier implementations will use all refinement iterations, 520 * even if the target threshold is reached. This tuning parameter allows an early out, but with 521 * an overshoot MSE threshold. Setting this to 1.0 will early-out as soon as the target is hit, 522 * but does reduce image quality vs the default behavior of over-refinement. 523 */ 524 float tune_refinement_mse_overshoot; 525 526 /** 527 * @brief The threshold for skipping 2.2/3.1/3.2/4.1 trials (-2partitionlimitfactor). 528 * 529 * This option is further scaled for normal maps, so it skips less often. 530 */ 531 float tune_2_partition_early_out_limit_factor; 532 533 /** 534 * @brief The threshold for skipping 3.2/4.1 trials (-3partitionlimitfactor). 535 * 536 * This option is further scaled for normal maps, so it skips less often. 537 */ 538 float tune_3_partition_early_out_limit_factor; 539 540 /** 541 * @brief The threshold for skipping two weight planes (-2planelimitcorrelation). 542 * 543 * This option is ineffective for normal maps. 544 */ 545 float tune_2_plane_early_out_limit_correlation; 546 547 /** 548 * @brief The threshold below which (inclusive) we stop testing low/high/low+high cutoffs. 549 */ 550 unsigned int tune_low_weight_count_limit; 551 552 #if defined(ASTCENC_DIAGNOSTICS) 553 /** 554 * @brief The path to save the diagnostic trace data to. 555 * 556 * This option is not part of the public API, and requires special builds 557 * of the library. 558 */ 559 const char* trace_file_path; 560 #endif 561 QualityProfile privateProfile; 562 }; 563 564 /** 565 * @brief An uncompressed 2D or 3D image. 566 * 567 * 3D image are passed in as an array of 2D slices. Each slice has identical 568 * size and color format. 569 */ 570 struct astcenc_image 571 { 572 /** @brief The stride dimension of the image, in texels. */ 573 unsigned int dim_stride; 574 575 /** @brief The X dimension of the image, in texels. */ 576 unsigned int dim_x; 577 578 /** @brief The Y dimension of the image, in texels. */ 579 unsigned int dim_y; 580 581 /** @brief The Z dimension of the image, in texels. */ 582 unsigned int dim_z; 583 584 /** @brief The data type per component. */ 585 astcenc_type data_type; 586 587 /** @brief The array of 2D slices, of length @c dim_z. */ 588 void** data; 589 }; 590 591 /** 592 * @brief A block encoding metadata query result. 593 * 594 * If the block is an error block or a constant color block or an error block all fields other than 595 * the profile, block dimensions, and error/constant indicator will be zero. 596 */ 597 struct astcenc_block_info 598 { 599 /** @brief The block encoding color profile. */ 600 astcenc_profile profile; 601 602 /** @brief The number of texels in the X dimension. */ 603 unsigned int block_x; 604 605 /** @brief The number of texels in the Y dimension. */ 606 unsigned int block_y; 607 608 /** @brief The number of texel in the Z dimension. */ 609 unsigned int block_z; 610 611 /** @brief The number of texels in the block. */ 612 unsigned int texel_count; 613 614 /** @brief True if this block is an error block. */ 615 bool is_error_block; 616 617 /** @brief True if this block is a constant color block. */ 618 bool is_constant_block; 619 620 /** @brief True if this block is an HDR block. */ 621 bool is_hdr_block; 622 623 /** @brief True if this block uses two weight planes. */ 624 bool is_dual_plane_block; 625 626 /** @brief The number of partitions if not constant color. */ 627 unsigned int partition_count; 628 629 /** @brief The partition index if 2 - 4 partitions used. */ 630 unsigned int partition_index; 631 632 /** @brief The component index of the second plane if dual plane. */ 633 unsigned int dual_plane_component; 634 635 /** @brief The color endpoint encoding mode for each partition. */ 636 unsigned int color_endpoint_modes[4]; 637 638 /** @brief The number of color endpoint quantization levels. */ 639 unsigned int color_level_count; 640 641 /** @brief The number of weight quantization levels. */ 642 unsigned int weight_level_count; 643 644 /** @brief The number of weights in the X dimension. */ 645 unsigned int weight_x; 646 647 /** @brief The number of weights in the Y dimension. */ 648 unsigned int weight_y; 649 650 /** @brief The number of weights in the Z dimension. */ 651 unsigned int weight_z; 652 653 /** @brief The unpacked color endpoints for each partition. */ 654 float color_endpoints[4][2][4]; 655 656 /** @brief The per-texel interpolation weights for the block. */ 657 float weight_values_plane1[216]; 658 659 /** @brief The per-texel interpolation weights for the block. */ 660 float weight_values_plane2[216]; 661 662 /** @brief The per-texel partition assignments for the block. */ 663 uint8_t partition_assignment[216]; 664 }; 665 666 /** 667 * Populate a codec config based on default settings. 668 * 669 * Power users can edit the returned config struct to fine tune before allocating the context. 670 * 671 * @param profile Color profile. 672 * @param block_x ASTC block size X dimension. 673 * @param block_y ASTC block size Y dimension. 674 * @param block_z ASTC block size Z dimension. 675 * @param quality Search quality preset / effort level. Either an 676 * @c ASTCENC_PRE_* value, or a effort level between 0 677 * and 100. Performance is not linear between 0 and 100. 678 679 * @param flags A valid set of @c ASTCENC_FLG_* flag bits. 680 * @param[out] config Output config struct to populate. 681 * 682 * @return @c ASTCENC_SUCCESS on success, or an error if the inputs are invalid 683 * either individually, or in combination. 684 */ 685 ASTCENC_PUBLIC astcenc_error astcenc_config_init( 686 astcenc_profile profile, 687 unsigned int block_x, 688 unsigned int block_y, 689 unsigned int block_z, 690 float quality, 691 unsigned int flags, 692 astcenc_config* config); 693 694 /** 695 * @brief Allocate a new codec context based on a config. 696 * 697 * This function allocates all of the memory resources and threads needed by the codec. This can be 698 * slow, so it is recommended that contexts are reused to serially compress or decompress multiple 699 * images to amortize setup cost. 700 * 701 * Contexts can be allocated to support only decompression using the @c ASTCENC_FLG_DECOMPRESS_ONLY 702 * flag when creating the configuration. The compression functions will fail if invoked. For a 703 * decompress-only library build the @c ASTCENC_FLG_DECOMPRESS_ONLY flag must be set when creating 704 * any context. 705 * 706 * @param[in] config Codec config. 707 * @param thread_count Thread count to configure for. 708 * @param[out] context Location to store an opaque context pointer. 709 * 710 * @return @c ASTCENC_SUCCESS on success, or an error if context creation failed. 711 */ 712 ASTCENC_PUBLIC astcenc_error astcenc_context_alloc( 713 const astcenc_config* config, 714 unsigned int thread_count, 715 astcenc_context** context); 716 717 /** 718 * @brief Compress an image. 719 * 720 * A single context can only compress or decompress a single image at a time. 721 * 722 * For a context configured for multi-threading, any set of the N threads can call this function. 723 * Work will be dynamically scheduled across the threads available. Each thread must have a unique 724 * @c thread_index. 725 * 726 * @param context Codec context. 727 * @param[in,out] image An input image, in 2D slices. 728 * @param swizzle Compression data swizzle, applied before compression. 729 * @param[out] data_out Pointer to output data array. 730 * @param data_len Length of the output data array. 731 * @param thread_index Thread index [0..N-1] of calling thread. 732 * 733 * @return @c ASTCENC_SUCCESS on success, or an error if compression failed. 734 */ 735 ASTCENC_PUBLIC astcenc_error astcenc_compress_image( 736 astcenc_context* context, 737 astcenc_image* image, 738 const astcenc_swizzle* swizzle, 739 uint8_t* data_out, 740 size_t data_len, 741 #if QUALITY_CONTROL 742 bool calQualityEnable, 743 int32_t *mse[RGBA_COM], 744 #endif 745 unsigned int thread_index); 746 747 /** 748 * @brief Reset the codec state for a new compression. 749 * 750 * The caller is responsible for synchronizing threads in the worker thread pool. This function must 751 * only be called when all threads have exited the @c astcenc_compress_image() function for image N, 752 * but before any thread enters it for image N + 1. 753 * 754 * Calling this is not required (but won't hurt), if the context is created for single threaded use. 755 * 756 * @param context Codec context. 757 * 758 * @return @c ASTCENC_SUCCESS on success, or an error if reset failed. 759 */ 760 ASTCENC_PUBLIC astcenc_error astcenc_compress_reset( 761 astcenc_context* context); 762 763 /** 764 * @brief Decompress an image. 765 * 766 * @param context Codec context. 767 * @param[in] data Pointer to compressed data. 768 * @param data_len Length of the compressed data, in bytes. 769 * @param[in,out] image_out Output image. 770 * @param swizzle Decompression data swizzle, applied after decompression. 771 * @param thread_index Thread index [0..N-1] of calling thread. 772 * 773 * @return @c ASTCENC_SUCCESS on success, or an error if decompression failed. 774 */ 775 ASTCENC_PUBLIC astcenc_error astcenc_decompress_image( 776 astcenc_context* context, 777 const uint8_t* data, 778 size_t data_len, 779 astcenc_image* image_out, 780 const astcenc_swizzle* swizzle, 781 unsigned int thread_index); 782 783 /** 784 * @brief Reset the codec state for a new decompression. 785 * 786 * The caller is responsible for synchronizing threads in the worker thread pool. This function must 787 * only be called when all threads have exited the @c astcenc_decompress_image() function for image 788 * N, but before any thread enters it for image N + 1. 789 * 790 * Calling this is not required (but won't hurt), if the context is created for single threaded use. 791 * 792 * @param context Codec context. 793 * 794 * @return @c ASTCENC_SUCCESS on success, or an error if reset failed. 795 */ 796 ASTCENC_PUBLIC astcenc_error astcenc_decompress_reset( 797 astcenc_context* context); 798 799 /** 800 * Free the compressor context. 801 * 802 * @param context The codec context. 803 */ 804 ASTCENC_PUBLIC void astcenc_context_free( 805 astcenc_context* context); 806 807 /** 808 * @brief Provide a high level summary of a block's encoding. 809 * 810 * This feature is primarily useful for codec developers but may be useful for developers building 811 * advanced content packaging pipelines. 812 * 813 * @param context Codec context. 814 * @param data One block of compressesd ASTC data. 815 * @param info The output info structure to populate. 816 * 817 * @return @c ASTCENC_SUCCESS if the block was decoded, or an error otherwise. Note that this 818 * function will return success even if the block itself was an error block encoding, as the 819 * decode was correctly handled. 820 */ 821 ASTCENC_PUBLIC astcenc_error astcenc_get_block_info( 822 astcenc_context* context, 823 const uint8_t data[16], 824 astcenc_block_info* info); 825 826 /** 827 * @brief Get a printable string for specific status code. 828 * 829 * @param status The status value. 830 * 831 * @return A human readable nul-terminated string. 832 */ 833 ASTCENC_PUBLIC const char* astcenc_get_error_string( 834 astcenc_error status); 835 836 #endif 837