diff --git a/.github/workflows/release_body_template.md b/.github/workflows/release_body_template.md index 0f81edce3..7bcd9802a 100644 --- a/.github/workflows/release_body_template.md +++ b/.github/workflows/release_body_template.md @@ -1,4 +1,4 @@ -**Status:** ${STATUS_DATE} +**Status:** Released ${STATUS_DATE} The ${RELEASE_VERSION} release is a minor/major maintenance release. diff --git a/CMakeLists.txt b/CMakeLists.txt index 96a684e8b..046d98cf0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -25,7 +25,7 @@ if(MSVC) add_compile_options("/wd4324") endif() -project(astcencoder VERSION 5.5.0) +project(astcencoder VERSION 5.6.0) set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON) diff --git a/Docs/Building.md b/Docs/Building.md index 04ee7c497..e1622f280 100644 --- a/Docs/Building.md +++ b/Docs/Building.md @@ -179,7 +179,7 @@ are an extra build output that are not currently used by the command line tool. All normal builds will support all ASTC block sizes, including the worst case 6x6x6 3D block size (216 texels per block). Compressor memory footprint and performance can be improved by limiting the block sizes supported in the build -by adding `-DASTCENC_BLOCK_MAX_TEXELS=` to to CMake command line +by adding `-DASTCENC_BLOCK_MAX_TEXELS=` to the CMake command line when configuring. Legal block sizes that are unavailable in a restricted build will return the error `ASTCENC_ERR_NOT_IMPLEMENTED` during context creation. @@ -221,7 +221,7 @@ microarchitecture pairing that you are targeting. ### Test builds We support building unit tests. These use the `googletest` framework, which is -pulled in though a git submodule. On first use, you must fetch the submodule +pulled in through a git submodule. On first use, you must fetch the submodule dependency: ```shell @@ -294,10 +294,11 @@ The current RISC-V Vector backend only supports VLEN=256 hardware, due to toolchain limitations that make a vector-length-agnostic port challenging. Hopefully there will be one in the future. -Since the backend only works when the VLEN is exactly 256, and you can only -enable this as a global compiler flag, there is no separate build target for -the backend yet. To enable it, simple build the none or native build target, -with the `-mrvv-vector-bits=zvl` CXXFLAG and a `zvl256b` in the ISA string. +Since the backend only works when the vector length is exactly 256 bits, and +you can only enable this as a global compiler flag, there is no separate build +target for the backend yet. To enable it, simply build the NONE or NATIVE build +target, with the `-mrvv-vector-bits=zvl` CXXFLAG and a `zvl256b` in the +`-march` ISA configuration string. You can cross-compile to RISC-V with the backend enabled using the following commands: @@ -319,7 +320,7 @@ the current CMake configuration using the `package` build target Configure CMake with: -* `-DASTCENC_PACAKGE=` to set the package architecture/variant name used +* `-DASTCENC_PACKAGE=` to set the package architecture/variant name used to name the package archive (not set by default). ```shell @@ -335,9 +336,10 @@ Windows packages will use the `.zip` format, other packages will use the The core codec of `astcenc` is built as a library, and so can be easily integrated into other projects. We recommend integrating the project in a way -that lets you control which version of `astcenc` you are using, as this allows you to manage API version changes. +that lets you control which version of `astcenc` you are using, as this allows +you to manage API version changes. -An basic example of CMake integration and codec API usage can be found in the `./Utils/Example` directory. See the [Example Readme](../Utils/Example/README.md) for more details. +A basic example of CMake integration and codec API usage can be found in the `./Utils/Example` directory. See the [Example Readme](../Utils/Example/README.md) for more details. > [!CAUTION] > This example is designed to always use the latest main branch so that it @@ -354,7 +356,7 @@ increment. When updating to a newer major version, callers of the API should expect that they will need to update to synchronize with any changes. When a major API -version makes changes to the API, they will be done in way that deliberately +version makes changes to the API, they will be done in a way that deliberately causes a compilation failure. This avoids applications hitting failures that only occur at runtime. diff --git a/Docs/ChangeLog-3x.md b/Docs/ChangeLog-3x.md deleted file mode 100644 index e81f7d41f..000000000 --- a/Docs/ChangeLog-3x.md +++ /dev/null @@ -1,308 +0,0 @@ -# 3.x series change log - -This page summarizes the major functional and performance changes in each -release of the 3.x series. - -All performance data on this page is measured on an Intel Core i5-9600K -clocked at 4.2 GHz, running `astcenc` using AVX2 and 6 threads. - - -## 3.7 - -**Status:** April 2022 - -The 3.7 release contains another round of performance optimizations, including -significant improvements to the command line front-end (faster PNG loader) and -the arm64 build of the codec (faster NEON implementation). - -* **General:** - * **Feature:** The command line tool PNG loader has been switched to use - the Wuffs library, which is robust and significantly faster than the - current stb_image implementation. - * **Feature:** Support for non-invariant builds returns. Opt-in to slightly - faster, but not bit-exact, builds by setting `-DNO_INVARIANCE=ON` for the - CMake configuration. This improves performance by around 2%. - * **Optimization:** Changed SIMD `select()` so that it matches the default - NEON behavior (bitwise select), rather than the default x86-64 behavior - (lane select on MSB). Specialization `select_msb()` added for the one case - we want to select on a sign-bit, where NEON needs a different - implementation. This provides a significant (>25%) performance uplift on - NEON implementations. - -### Performance: - -Key for charts: - -* Color = block size (see legend). -* Letter = image format (N = normal map, G = grayscale, L = LDR, H = HDR). - -**Relative performance vs 3.5 release:** - -![Relative scores 3.7 vs 3.6](./ChangeLogImg/relative-3.6-to-3.7.png) - - -## 3.6 - -**Status:** April 2022 - -The 3.6 release contains another round of performance optimizations. - -There are no interface changes in this release, but in general the API is not -designed to be binary compatible across versions. We always recommend -rebuilding your client-side code using the updated `astcenc.h` header. - -* **General:** - * **Feature:** Data tables are now optimized for contexts without the - `SELF_DECOMPRESS_ONLY` flag set. The flag therefore no longer improves - compression performance, but still reduces context creation time and - context data table memory footprint. - * **Feature:** Image quality for 4x4 `-fastest` configuration has been - improved. - * **Optimization:** Decimation modes are reliably excluded from processing - when they are only partially selected in the compressor configuration (e.g. - if used for single plane, but not dual plane modes). This is a significant - performance optimization for all quality levels. - * **Optimization:** Fast-path block load function variant added for 2D LDR - images with no swizzle. This is a moderate performance optimization for the - fast and fastest quality levels. - -### Performance: - -Key for charts: - -* Color = block size (see legend). -* Letter = image format (N = normal map, G = grayscale, L = LDR, H = HDR). - -**Relative performance vs 3.5 release:** - -![Relative scores 3.6 vs 3.5](./ChangeLogImg/relative-3.5-to-3.6.png) - - -## 3.5 - -**Status:** March 2022 - -The 3.5 release contains another round of performance optimizations. - -There are no interface changes in this release, but in general the API is not -designed to be binary compatible across versions. We always recommend -rebuilding your client-side code using the updated `astcenc.h` header. - -* **General:** - * **Feature:** Compressor configurations using `SELF_DECOMPRESS_ONLY` mode - store compacted partition tables, which significantly improves both - context create time and runtime performance. - * **Feature:** Bilinear infill for decimated weight grids supports a new - variant for half-decimated grids which are only decimated in one axis. - -### Performance: - -Key for charts: - -* Color = block size (see legend). -* Letter = image format (N = normal map, G = grayscale, L = LDR, H = HDR). - -**Relative performance vs 3.4 release:** - -![Relative scores 3.5 vs 3.4](./ChangeLogImg/relative-3.4-to-3.5.png) - - - -## 3.4 - -**Status:** February 2022 - -The 3.4 release introduces another round of optimizations, removing a number -of power-user configuration options to simplify the core compressor data path. - -Reminder for users of the library interface - the API is not designed to be -binary compatible across versions, and this release is not compatible with -earlier releases. Please update and rebuild your client-side code using the -updated `astcenc.h` header. - -* **General:** - * **Feature:** Many memory allocations have been moved off the stack into - dynamically allocated working memory. This significantly reduces the peak - stack usage, allowing the compressor to run in systems with 128KB stack - limits. - * **Feature:** Builds now support `-DBLOCK_MAX_TEXELS=` to allow a - compressor to support a subset of block sizes. This can reduce binary size - and runtime memory footprint, and improve performance. - * **Feature:** The `-v` and `-va` options to set a per-texel error weight - function are no longer supported. - * **Feature:** The `-b` option to set a per-texel error weight boost for - block border texels is no longer supported. - * **Feature:** The `-a` option to set a per-texel error weight based on texel - alpha value is no longer supported as an error weighting tool, but is still - supported for providing sprite-sheet RDO. - * **Feature:** The `-mask` option to set an error metric for mask map - textures is still supported, but is currently a no-op in the compressor. - * **Feature:** The `-perceptual` option to set a perceptual error metric is - still supported, but is currently a no-op in the compressor for mask map - and normal map textures. - * **Bug-fix:** Corrected decompression of error blocks in some cases, so now - returning the expected error color (magenta for LDR, NaN for HDR). Note - that astcenc determines the error color to use based on the output image - data type not the decoder profile. -* **Binary releases:** - * **Improvement:** Windows binaries changed to use ClangCL 12.0, which gives - up to 10% performance improvement. - -### Performance: - -Key for charts: - -* Color = block size (see legend). -* Letter = image format (N = normal map, G = grayscale, L = LDR, H = HDR). - -**Relative performance vs 3.3 release:** - -![Relative scores 3.4 vs 3.3](./ChangeLogImg/relative-3.3-to-3.4.png) - - - -## 3.3 - -**Status:** November 2021 - -The 3.3 release improves image quality for normal maps, and two component -textures. Normal maps are expected to compress 25% slower than the 3.2 -release, although it should be noted that they are still faster to compress -in 3.3 than when using the 2.5 series. This release also fixes one reported -stability issue. - -* **General:** - * **Feature:** Normal map image quality has been improved. - * **Feature:** Two component image quality has been improved, provided - that unused components are correctly zero-weighted using e.g. `-cw` on the - command line. - * **Bug-fix:** Improved stability when trying to compress complex blocks that - could not beat even the starting quality threshold. These will now always - compress in to a constant color blocks. - - -## 3.2 - -**Status:** August 2021 - -The 3.2 release is a bugfix release; no significant image quality or -performance differences are expected. - -* **General:** - * **Bug-fix:** Improved stability when new contexts were created while other - contexts were compressing or decompressing an image. - * **Bug-fix:** Improved stability when decompressing blocks with invalid - block encodings. - - -## 3.1 - -**Status:** July 2021 - -The 3.1 release gives another performance boost, typically between 5 and 20% -faster than the 3.0 release, as well as further incremental improvements to -image quality. A number of build system improvements make astcenc easier and -faster to integrate into other projects as a library, including support for -building universal binaries on macOS. Full change list is shown below. - -Reminder for users of the library interface - the API is not designed to be -binary compatible across versions, and this release is not compatible with -earlier releases. Please update and rebuild your client-side code using the -updated `astcenc.h` header. - -* **General:** - * **Feature:** RGB color data now supports `-perceptual` operation. The - current implementation is simple, weighting color channel errors by their - contribution to perceived luminance. This mimics the behavior of the human - visual system, which is most sensitive to green, then red, then blue. - * **Feature:** Codec supports a new low weight search mode, which is a - simpler weight assignment for encodings with a low number of weights in the - weight grid. The weight threshold can be overridden using the new - `-lowweightmodelimit` command line option. - * **Feature:** All platform builds now support building a native binary. - Native binaries automatically select the SIMD level based on the default - configuration of the compiler in use. Native binaries built on one machine - may use different SIMD options than native binaries build on another. - * **Feature:** macOS platform builds now support building universal binaries - containing both `x86_64` and `arm64` target support. - * **Feature:** Building the command line can be disabled when using as a - library in another project. Set `-DCLI=OFF` during the CMake configure - step. - * **Feature:** A standalone minimal example of the core codec API usage has - been added in the `./Utils/Example/` directory. -* **Core API:** - * **Feature:** Config flag `ASTCENC_FLG_USE_PERCEPTUAL` works for color data. - * **Feature:** Config option `tune_low_weight_count_limit` added. - * **Feature:** New heuristic added which prunes dual weight plane searches if - they are unlikely to help. This heuristic is not user controllable. - * **Feature:** Image quality has been improved. In general we see significant - improvements (up to 0.2dB) for high bitrate encodings (4x4, 5x4), and a - smaller improvement (up to 0.1dB) for lower bitrate encodings. - * **Bug fix:** Arm "none" SIMD builds could be invariant with other builds. - This fix has also been back-ported to the 2.x LTS branch. - -### Performance: - -Key for charts: - -* Color = block size (see legend). -* Letter = image format (N = normal map, G = grayscale, L = LDR, H = HDR). - -**Relative performance vs 3.0 release:** - -![Relative scores 3.1 vs 3.0](./ChangeLogImg/relative-3.0-to-3.1.png) - - -## 3.0 - -**Status:** June 2021 - -The 3.0 release is the first in a series of updates to the compressor that are -making more radical changes than we felt we could make with the 2.x series. -The primary goals of the 3.x series are to keep the image quality ~static or -better compared to the 2.5 release, but continue to improve performance. - -Reminder for users of the library interface - the API is not designed to be -binary compatible across versions, and this release is not compatible with -earlier releases. Please update and rebuild your client-side code using the -updated `astcenc.h` header. - -* **General:** - * **Feature:** The code has been significantly cleaned up, with improved - comments, API documentation, function naming, and variable naming. -* **Core API:** - * **API Change:** The core APIs for `astcenc_compress_image()` and for - `astcenc_decompress_image()` now accept swizzle structures by `const` - pointer, instead of pass-by-value. - * **API Change:** Calling the `astcenc_compress_reset()` and the - `astcenc_decompress_reset()` functions between images is no longer required - if the context was created for use by a single thread. - * **Feature:** New heuristics have been added for controlling when to search - beyond 2 partitions and 1 plane, and when to search beyond 3 partitions and - 1 plane. The previous `tune_partition_early_out_limit` config option has - been removed, and replaced with two new options - `tune_2_partition_early_out_limit_factor` and - `tune_3_partition_early_out_limit_factor`. See command line help for more - detailed documentation. - * **Feature:** New heuristics have been added for controlling when to use - dual weight planes. The previous `tune_two_plane_early_out_limit` has been - renamed to`tune_2_plane_early_out_limit_correlation`. See command line help - for more detailed documentation. - * **Feature:** Support for using dual weight planes has been restricted to - single partition blocks; it rarely helps blocks with 2 or more partitions - and takes considerable compression search time. - -### Performance: - -Key for charts: - -* Color = block size (see legend). -* Letter = image format (N = normal map, G = grayscale, L = LDR, H = HDR). - -**Relative performance vs 2.5 release:** - -![Relative scores 3.0 vs 2.5](./ChangeLogImg/relative-2.5-to-3.0.png) - -- - - - -_Copyright © 2021-2022, Arm Limited and contributors._ diff --git a/Docs/ChangeLog-4x.md b/Docs/ChangeLog-4x.md index 04a27112d..22f53099a 100644 --- a/Docs/ChangeLog-4x.md +++ b/Docs/ChangeLog-4x.md @@ -9,7 +9,7 @@ clocked at 4.2 GHz, running `astcenc` using AVX2 and 6 threads. ## 4.8.0 -**Status:** May 2024 +**Status:** Released May 2024 The 4.8.0 release is a minor maintenance release. @@ -27,7 +27,7 @@ The 4.8.0 release is a minor maintenance release. ## 4.7.0 -**Status:** January 2024 +**Status:** Released January 2024 The 4.7.0 release is a major maintenance release, fixing rounding behavior in the decompressor to match the Khronos specification. This fix includes the @@ -62,14 +62,14 @@ updated `astcenc.h` header. cannot be reliably determined. * **Feature:** Library configuration supports a new optional progress reporting callback to be specified. This is called during compression to - to allow interactive tooling use cases to display incremental progress. The + allow interactive tooling use cases to display incremental progress. The command line tool uses this feature to show compression progress unless `-silent` is used. ## 4.6.1 -**Status:** November 2023 +**Status:** Released November 2023 The 4.6.1 release is a minor maintenance release to fix a scaling bug on large core count Windows systems. @@ -85,7 +85,7 @@ large core count Windows systems. ## 4.6.0 -**Status:** November 2023 +**Status:** Released November 2023 The 4.6.0 release retunes the compressor heuristics to give improvements to performance for trivial losses to image quality. It also includes some minor @@ -113,7 +113,7 @@ versions. We always recommend rebuilding your client-side code using the updated ## 4.5.0 -**Status:** June 2023 +**Status:** Released June 2023 The 4.5.0 release is a maintenance release with small image quality improvements, and a number of build system quality of life improvements. @@ -128,7 +128,7 @@ improvements, and a number of build system quality of life improvements. binary for all platforms. * **Change:** Windows binary releases are now compiled with VS2022. * **Change:** Invariant MSVC builds for VS2022 now use `/fp:precise` instead - of `/fp:strict`, which is is now possible because precise no longer implies + of `/fp:strict`, which is now possible because precise no longer implies contraction. This should improve performance for MSVC builds. * **Change:** Non-invariant Clang builds now use `-ffp-model=precise` with `-ffp-contract=on`. This should improve performance on older Clang @@ -144,7 +144,7 @@ improvements, and a number of build system quality of life improvements. * **Change:** CMake config `ASTCENC_NO_INVARIANCE` has been inverted to remove the negated option, and is now `ASTCENC_INVARIANCE` with a default of `ON`. Disabling this option can substantially improve performance, but - images can different across platforms and compilers. + images can differ across platforms and compilers. * **Optimization:** Color quantization and packing for LDR RGB and RGBA has been vectorized to improve performance. * **Change:** Color quantization for LDR RGB and RGBA endpoints will now try @@ -156,7 +156,7 @@ improvements, and a number of build system quality of life improvements. ## 4.4.0 -**Status:** March 2023 +**Status:** Released March 2023 The 4.4.0 release is a minor release with image quality improvements, a small performance boost, and a few new quality-of-life features. @@ -195,7 +195,7 @@ Key for charts: ## 4.3.1 -**Status:** January 2023 +**Status:** Released January 2023 The 4.3.1 release is a minor maintenance release. No performance or image quality changes are expected. @@ -209,7 +209,7 @@ quality changes are expected. ## 4.3.0 -**Status:** January 2023 +**Status:** Released January 2023 The 4.3.0 release is an optimization release. There are minor performance and image quality improvements in this release. @@ -247,7 +247,7 @@ Key for charts: ## 4.2.0 -**Status:** November 2022 +**Status:** Released November 2022 The 4.2.0 release is an optimization release. There are significant performance improvements, minor image quality improvements, and library interface changes in @@ -259,7 +259,7 @@ versions. We always recommend rebuilding your client-side code using the updated * **General:** * **Bug-fix:** Compression for RGB and RGBA base+offset encodings no - longer generate endpoints with the incorrect blue-contract behavior. + longer generates endpoints with the incorrect blue-contract behavior. * **Bug-fix:** Lowest channel correlation calculation now correctly ignores constant color channels for the purposes of filtering 2 plane encodings. On average this improves both performance and image quality. @@ -313,7 +313,7 @@ Key for charts: ## 4.1.0 -**Status:** August 2022 +**Status:** Released August 2022 The 4.1.0 release is a maintenance release. There is no performance or image quality change in this release. @@ -338,20 +338,20 @@ quality change in this release. ## 4.0.0 -**Status:** July 2022 +**Status:** Released July 2022 -The 4.0.0 release introduces some major performance enhancement, and a number +The 4.0.0 release introduces some major performance enhancements, and a number of larger changes to the heuristics used in the codec to find a more effective cost:quality trade off. * **General:** * **Change:** The `-array` option for specifying the number of image planes - for ASTC 3D volumetric block compression been renamed to `-zdim`. + for ASTC 3D volumetric block compression has been renamed to `-zdim`. * **Change:** The build root package directory is now `bin` instead of `astcenc`, allowing the CMake install step to write binaries into `/usr/local/bin` if the user wishes to do so. * **Feature:** A new `-ssw` option for specifying the shader sampling swizzle - has been added as convenience alternative to the `-cw` option. This is + has been added as a convenience alternative to the `-cw` option. This is needed to correct error weighting during compression if not all components are read in the shader. For example, to extract and compress two components from an RGBA input image, weighting the two components equally when @@ -385,7 +385,7 @@ cost:quality trade off. be a significant optimization for paths that are load unit limited. * **Optimization:** Decompressed image block writes in the decompressor now use a vectorized approach to writing each row of texels in the block, - including to ability to exploit masked stores if the target supports them. + including the ability to exploit masked stores if the target supports them. * **Optimization:** Weight scrambling has been moved into the physical layer; the rest of the codec now uses linear order weights. * **Optimization:** Weight packing has been moved into the physical layer; diff --git a/Docs/ChangeLog-5x.md b/Docs/ChangeLog-5x.md index 401d0a9b1..ae3f3b266 100644 --- a/Docs/ChangeLog-5x.md +++ b/Docs/ChangeLog-5x.md @@ -9,27 +9,30 @@ clocked at 4.2 GHz, running `astcenc` using AVX2 and 6 threads. ## 5.6.0 -**Status:** In development +**Status:** July 2026 The 5.6.0 release is a minor maintenance release. +* **Codec library updates:** + * **Bug fix:** Avoid undefined behavior caused by passing floating point + values outside of the [0.0, 1.0] range as input data for a UNORM color + channel. + * **Bug fix:** Avoid undefined behavior caused by unaligned access in SSE, + AVX2, and NEON SIMD library implementations. * **Command line tool updates:** - * **Bug fix:** Zero the trailing reserved field of the DDS header before - writing it, so uncompressed `.dds` output no longer contains uninitialized - stack bytes. * **Bug fix:** Fixed incorrect plane stride when writing an uncompressed 3D LDR image to a DDS container. * **Bug fix:** Fixed potential integer overflow when storing very large uncompressed images to a `dds` or `.ktx` output image format. - * **Bug fix:** Avoid undefined behavior caused by passing floating point - values outside of the [0.0, 1.0] range as data for a UNORM color channel. - * **Bug fix:** Avoid undefined behavior caused by unaligned access in SSE - and AVX2 SIMD library implementations. + * **Bug fix:** Fixed missing initialization of the `reserved2` field in the + DDS file header when writing uncompressed `.dds` output images. + * **Bug fix:** Fixed typos and grammar issues in the command line `-help` + text. ## 5.5.0 -**Status:** June 2026 +**Status:** Released June 2026 The 5.5.0 release is a minor maintenance release, fixing minor functional issues and improving robustness when processing invalid images. @@ -70,7 +73,7 @@ issues and improving robustness when processing invalid images. ## 5.4.0 -**Status:** May 2026 +**Status:** Released May 2026 The 5.4.0 release is a minor feature release. @@ -104,7 +107,7 @@ header from the same release to avoid compatibility issues. ## 5.3.0 -**Status:** March 2025 +**Status:** Released March 2025 The 5.3.0 release is a minor maintenance release. @@ -124,7 +127,7 @@ The 5.3.0 release is a minor maintenance release. ## 5.2.0 -**Status:** February 2025 +**Status:** Released February 2025 The 5.2.0 release is a minor maintenance release. @@ -138,7 +141,7 @@ header from the same release to avoid compatibility issues. unintended specification change. Compared to previous releases, this change can cause LSB bit differences in the alpha channel of compressed images. * **Feature:** Arm64 builds for Linux added to the GitHub Actions builds, and - Arm64 binaries for NEON, 128-bit SVE 128 and 256-bit SVE added to release + Arm64 binaries for NEON, 128-bit SVE and 256-bit SVE added to release builds. * **Feature:** Added a new codec API, `astcenc_compress_cancel()`, which can be used to cancel an in-flight compression. This is designed to help make @@ -151,7 +154,7 @@ header from the same release to avoid compatibility issues. ## 5.1.0 -**Status:** November 2024 +**Status:** Released November 2024 The 5.1.0 release is an optimization release, giving moderate performance improvements on all platforms. There are no image quality differences. @@ -174,7 +177,7 @@ improvements on all platforms. There are no image quality differences. ## 5.0.0 -**Status:** November 2024 +**Status:** Released November 2024 The 5.0.0 release is the first stable release in the 5.x series. The main new feature is support for the Arm Scalable Vector Extensions (SVE) SIMD instruction @@ -190,7 +193,7 @@ set. can only run on hardware implementing 256-bit SVE. * **Feature:** Added backend for Arm SVE 128-bit builds. These are portable builds and can run on hardware implementing any SVE vector length, but the - explicit SVE use is augmented NEON and will only use the bottom 128-bits of + explicit SVE use is augmented NEON and will only use the bottom 128 bits of each SVE vector. * **Feature:** Optimized NEON mask `any()` and `all()` functions. * **Feature:** Migrated build and test to GitHub Actions pipelines. diff --git a/Docs/ChangeLogImg/relative-2.5-to-3.0.png b/Docs/ChangeLogImg/relative-2.5-to-3.0.png deleted file mode 100644 index 98e04bce0..000000000 Binary files a/Docs/ChangeLogImg/relative-2.5-to-3.0.png and /dev/null differ diff --git a/Docs/ChangeLogImg/relative-3.0-to-3.1.png b/Docs/ChangeLogImg/relative-3.0-to-3.1.png deleted file mode 100644 index 6ec271e4a..000000000 Binary files a/Docs/ChangeLogImg/relative-3.0-to-3.1.png and /dev/null differ diff --git a/Docs/ChangeLogImg/relative-3.3-to-3.4.png b/Docs/ChangeLogImg/relative-3.3-to-3.4.png deleted file mode 100644 index d714f3ead..000000000 Binary files a/Docs/ChangeLogImg/relative-3.3-to-3.4.png and /dev/null differ diff --git a/Docs/ChangeLogImg/relative-3.4-to-3.5.png b/Docs/ChangeLogImg/relative-3.4-to-3.5.png deleted file mode 100644 index 3878e90bc..000000000 Binary files a/Docs/ChangeLogImg/relative-3.4-to-3.5.png and /dev/null differ diff --git a/Docs/ChangeLogImg/relative-3.5-to-3.6.png b/Docs/ChangeLogImg/relative-3.5-to-3.6.png deleted file mode 100644 index 0c0c9bf48..000000000 Binary files a/Docs/ChangeLogImg/relative-3.5-to-3.6.png and /dev/null differ diff --git a/Docs/ChangeLogImg/relative-3.6-to-3.7.png b/Docs/ChangeLogImg/relative-3.6-to-3.7.png deleted file mode 100644 index 71f23851e..000000000 Binary files a/Docs/ChangeLogImg/relative-3.6-to-3.7.png and /dev/null differ diff --git a/Docs/Encoding.md b/Docs/Encoding.md index 21ea8113d..cf36cea80 100644 --- a/Docs/Encoding.md +++ b/Docs/Encoding.md @@ -1,6 +1,6 @@ # Effective ASTC Encoding -Most texture compression schemes encode a single color format at single +Most texture compression schemes encode a single color format at a single bitrate, so there are relatively few configuration options available to content creators beyond selecting which compressed format to use. @@ -94,11 +94,11 @@ component luminance will be returned for all three of the `.rgb` components. ## Equivalence with other formats -Based on these component encoding requirements we can now derive the the ASTC +Based on these component encoding requirements we can now derive the ASTC coding equivalents for most of the other texture compression formats in common use today. -| Formant | ASTC Coding Swizzle | ASTC Sampling Swizzle | Notes | +| Format | ASTC Coding Swizzle | ASTC Sampling Swizzle | Notes | | -------- | ------------------- | --------------------- | ---------------- | | BC1 | `rgba` 1 | `.rgba` | | | BC3 | `rgba` | `.rgba` | | @@ -120,7 +120,7 @@ component. **2:** ASTC relies on using the L+A color endpoint type for coding efficiency for two component data. It therefore has no direct equivalent of a two-plane -format sampled though the `.rg` components such as BC5 or EAC_RG11. This can +format sampled through the `.rg` components such as BC5 or EAC_RG11. This can be emulated by setting texture component swizzles in the runtime API - e.g. via `glTexParameteri()` for OpenGL ES - although it has been noted that API controlled swizzles are not available in WebGL. @@ -232,4 +232,4 @@ which will treat all components as HDR data. - - - -_Copyright © 2019-2024, Arm Limited and contributors._ +_Copyright © 2019-2026, Arm Limited and contributors._ diff --git a/Docs/FileFormat.md b/Docs/FileFormat.md index 7b01e6537..975dd0b71 100644 --- a/Docs/FileFormat.md +++ b/Docs/FileFormat.md @@ -8,7 +8,7 @@ payload for a single image surface. Header ====== -The header is a fixed 16 byte structure, defined as storing only bytes to avoid +The header is a fixed 16-byte structure, defined as storing only bytes to avoid any endianness issues or incur any padding overhead. ``` @@ -27,7 +27,7 @@ struct astc_header Magic number ------------ -The 4 byte magic number at the start of the file acts as a format identifier. +The 4-byte magic number at the start of the file acts as a format identifier. ``` magic[0] = 0x13; @@ -52,7 +52,7 @@ Note that the image is not required to be an exact multiple of the compressed block size; the compressed data may include padding that is discarded during decompression. -Each dimension is a 24 bit unsigned value that is reconstructed from the stored +Each dimension is a 24-bit unsigned value that is reconstructed from the stored byte values as: ``` @@ -68,4 +68,4 @@ determined from the header information. - - - -_Copyright © 2020-2022, Arm Limited and contributors._ +_Copyright © 2020-2026, Arm Limited and contributors._ diff --git a/Docs/FormatOverview.md b/Docs/FormatOverview.md index be9fdbde5..30c2b4e89 100644 --- a/Docs/FormatOverview.md +++ b/Docs/FormatOverview.md @@ -12,13 +12,13 @@ ASTC offers a number of advantages over earlier texture compression formats: (correlated RGB, non-correlated alpha). * **Bit rate flexibility:** ASTC supports compressing images with a fine grained choice of bit rates between 0.89 and 8 bits per texel (bpt). The bit - rate choice is independent to the color format choice. + rate choice is independent of the color format choice. * **Advanced format support:** ASTC supports compressing images in either low dynamic range (LDR), LDR sRGB, or high dynamic range (HDR) color spaces, as well as support for compressing 3D volumetric textures. * **Improved image quality:** Despite the high degree of format flexibility, ASTC manages to beat nearly all legacy texture compression formats -- such as - ETC2, PVRCT, and the BC formats -- on image quality at equivalent bit + ETC2, PVRTC, and the BC formats -- on image quality at equivalent bit rates. This article explores the ASTC format, and how it manages to generate the @@ -136,7 +136,7 @@ example, if we have a floating-point weight for each texel in the range 0.0 to 1.0 - which we can then represent in storage using the integer values 0 to 4. In the general case we need to be able to efficiently store characters of an -alphabet containing N symbols if we choose quantize to N levels. An N symbol +alphabet containing N symbols if we choose to quantize to N levels. An N symbol alphabet contains `log2(N)` bits of information per character. If we have an alphabet of 5 possible symbols then each character contains ~2.32 bits of information, but simple binary storage would require us to round up to 3 bits. @@ -185,8 +185,8 @@ most space-efficient choice of bits, trits, and quints. * Alphabets with up to (2n - 1) symbols can be encoded using n bits per character. -* Alphabets with up (3 * 2n - 1) symbols can be encoded using n bits - (m) and a trit (t) per character, and reconstructed using the equation +* Alphabets with up to (3 * 2n - 1) symbols can be encoded using n + bits (m) and a trit (t) per character, and reconstructed using the equation (t * 2n + m). * Alphabets with up to (5 * 2n - 1) symbols can be encoded using n bits (m) and a quint (q) per character, and reconstructed using the equation @@ -203,16 +203,16 @@ to store any padding after the end of the bit sequence, as we can safely assume that they are zero bits. With this constraint in place - and by some smart packing the bits, trits, and -quints - BISE encodes an string of S characters in an N symbol alphabet using a +quints - BISE encodes a string of S characters in an N symbol alphabet using a fixed number of bits: * S values up to (2n - 1) uses (NS) bits. * S values up to (3 * 2n - 1) uses (NS + ceil(8S / 5)) bits. * S values up to (5 * 2n - 1) uses (NS + ceil(7S / 3)) bits. -... and the compressor will choose the one of these which produces the smallest -storage for the alphabet size being stored; some will use binary, some will use -bits and a trit, and some will use bits and a quint. If we compare the storage +... and the compressor will choose the one which produces the smallest storage +for the alphabet size being stored; some will use binary, some will use bits +and a trit, and some will use bits and a quint. If we compare the storage efficiency of BISE against simple binary for the range of possible alphabet sizes we might want to encode we can see that it is much more efficient. @@ -266,7 +266,7 @@ lying on green grass. ASTC allows up to four color gradients - known as "partitions" - to be assigned to a single block. Each texel is then assigned to a single partition for the purposes of decompression. -Rather then directly storing the partition assignment for each texel, which +Rather than directly storing the partition assignment for each texel, which would need a lot of decompressor hardware to store it for all block sizes, we generate it procedurally. Each block only needs to store the partition index - which is the seed for the procedural generator - and the per texel assignment @@ -336,7 +336,7 @@ Adaptive -------- The first word in the name of ASTC is "adaptive", and it should now hopefully -be clear why. Each block always compresses into 128-bits of storage, but the +be clear why. Each block always compresses into 128 bits of storage, but the developer can choose from a wide range of texel block sizes and the compressor gets a huge amount of latitude to determine how those 128 bits are used. @@ -367,10 +367,10 @@ The only significant omission is the absence of a dedicated two channel encoding for HDR textures. We simply ran out of entries in the space we had for encoding color endpoint modes, and this one didn't make the cut. -The flexibility allowed by ASTC ticks the requirement that almost any asset can -be compressed to some degree, at an appropriate bitrate for its quality needs. -This is a powerful enabler for a compression format, because it puts control in -the hands of content creators and not arbitrary format restrictions. +The flexibility allowed by ASTC meets the requirement that almost any asset +can be compressed to some degree, at an appropriate bitrate for its quality +needs. This is a powerful enabler for a compression format, because it puts +control in the hands of content creators and not arbitrary format restrictions. Image quality @@ -485,4 +485,4 @@ which allow applications to reduce the intermediate precision to either UNORM8 - - - -_Copyright © 2019-2022, Arm Limited and contributors._ +_Copyright © 2019-2026, Arm Limited and contributors._ diff --git a/Docs/Terminology.md b/Docs/Terminology.md index 0f1bfb92a..d71af55b8 100644 --- a/Docs/Terminology.md +++ b/Docs/Terminology.md @@ -57,7 +57,7 @@ Weight grids have multiple states depending on how they are being used. **decimated_weights** represent reduced weight grids, which can store fewer weights and which are bilinear interpolated to generate the full weight grid. -Full weights have no variable prefix,but decimated weights are stored with +Full weights have no variable prefix, but decimated weights are stored with a `dec_` prefix. * `dec_weights_ideal_value` @@ -72,8 +72,8 @@ interpolation weights. This gets very confusing in functions using all three! We are slowly refactoring the code to only use "weight" to mean the endpoint interpolation weights. The error weighting factors used for other purposes are -being updated to use the using the term "significance". +being updated to use the term "significance". - - - -_Copyright © 2020-2022, Arm Limited and contributors._ +_Copyright © 2020-2026, Arm Limited and contributors._ diff --git a/Docs/Testing.md b/Docs/Testing.md index a6d8f0446..0e9dcfc8d 100644 --- a/Docs/Testing.md +++ b/Docs/Testing.md @@ -21,7 +21,7 @@ Running the tests requires Python 3.12 to be installed on the host machine. Compile the build of `astcenc` you wish to test, and install it into the project `./bin` directory. This can be achieved by configuring the CMake build using the install prefix `-DCMAKE_INSTALL_PREFIX=../` and then running a build with the `install` build target. -Run the functional tests against to appropriate encoder variant using: +Run the functional tests against the appropriate encoder variant using: ```sh python3 ./Test/astc_test_functional.py -v --encoder @@ -38,7 +38,7 @@ of the repository: python3 ./Test/astc_test_image.py ``` -This will run though a series of image compression tests, comparing the image +This will run through a series of image compression tests, comparing the image PSNR against a set of reference results from the last stable baseline. The test will fail if any reduction in PSNR above a set threshold is detected. @@ -50,7 +50,7 @@ how many threads the compressor is allowed to use. By default output images are discarded during testing. To store images for debug purposes, the decompressed output images can be kept by passing `--keep-output`. The resulting images are stored in the `TestOutput` -subdirectory, using the same test set directoy structure as the `Test/Images` +subdirectory, using the same test set directory structure as the `Test/Images` folder. ## Benchmarking @@ -91,7 +91,7 @@ high quality levels, or uses many repeats to improve result stability. **WARNING:** This may take some hours to complete, and it is best done when the test suite gets exclusive use of the machine to avoid other processing slowing down the compression and disturbing the performance data. It is recommended to -shutdown or disable any background applications that are running. +shut down or disable any background applications that are running. # Running C++ unit tests diff --git a/Docs/TestingOSSFuzz.md b/Docs/TestingOSSFuzz.md index f0114aefe..9d2df3ae4 100644 --- a/Docs/TestingOSSFuzz.md +++ b/Docs/TestingOSSFuzz.md @@ -22,7 +22,7 @@ You will need to log out and log in again for the group changes to take effect. # Running Python-based CLI functional tests -Checkout the OSS-Fuzz project: +Check out the OSS-Fuzz project: ```sh git clone --depth=1 https://github.com/google/oss-fuzz.git @@ -51,14 +51,14 @@ python3 infra/helper.py build_fuzzers astc-encoder python3 infra/helper.py build_fuzzers astc-encoder /mnt/c/work/projects/astcenc/Source --sanitizer ``` -Run a reproducer testcase downloaded from OSS Fuzz: +Run a reproducer test case downloaded from OSS Fuzz: ```sh python3 infra/helper.py reproduce astc-encoder ``` Sometimes reproducers are intermittent and do not always reproduce. Running the -the test scenario in a loop can be a useful way to try and make it reproduce. +test scenario in a loop can be a useful way to try and make it reproduce. ```sh while python3 infra/helper.py reproduce astc-encoder ; do :; done diff --git a/README.md b/README.md index 24f027d12..acf4f98d4 100644 --- a/README.md +++ b/README.md @@ -64,8 +64,8 @@ Binaries are provided for 64-bit builds on Windows, macOS, and Linux. ## Windows and Linux -For Windows and Linux the builds of the astcenc are provided as multiple -binaries, each tuned for a specific SIMD instruction set. +For Windows and Linux, the builds of astcenc are provided as multiple binaries, +each tuned for a specific SIMD instruction set. For x86-64 we provide, in order of increasing performance: @@ -89,9 +89,9 @@ style and requires the binary to match the vector length on the host CPU. ## macOS -For macOS devices we provide a single universal binary `astcenc`, which allows -the OS to automatically use the correct binary variant for the current host -machine. Support is provided for three architecture slices: +For macOS, we provide a single universal binary `astcenc`, which allows the OS +to automatically use the correct binary variant for the current host machine. +Support is provided for three architecture slices: * `x86_64` - uses the `astcenc-sse4.1` build defined above. * `x86_64h` - uses the `astcenc-avx2` build defined above. @@ -108,11 +108,9 @@ The `4.x` branch is a stable branch for the older 4.x release series. It is no longer under active development, but is a supported branch that continues to get back-ported bug fixes. -The `1.x`, `2.x`, and `3.x` branches are legacy branches for older releases. -They are no longer under active development or getting security or bug fixes, -and are scheduled for deletion at the end of August 2026. We recommend that -developers using an old branch migrate to using the latest 5.x series stable -release tag. +Older releases are no longer available as a release branch, but any official +releases are still available via their git tag. We recommend that developers +using an older version migrate to the latest 5.x series stable release tag. Any other branches you might find are development branches for new features or optimizations, so might be interesting to play with but should be considered @@ -131,7 +129,7 @@ the astcenc encoder program, like this on Linux or macOS: Invoking `astcenc -help` gives an extensive help message, including usage instructions and details of all available command line options. A summary of -the main encoder options are shown below. +the main encoder options is shown below. ## Compressing an image @@ -177,11 +175,11 @@ For example: astcenc -tl example.png example.tga 5x5 -thorough -This is equivalent to using using the LDR color profile and a 5x5 block size -to compress the image, using the `-thorough` quality preset, and then -immediately decompressing the image and saving the result. This can be used -to enable a visual inspection of the compressed image quality. In addition -this mode also prints out some image quality metrics to the console. +This is equivalent to using the LDR color profile and a 5x5 block size to +compress the image, using the `-thorough` quality preset, and then immediately +decompressing the image and saving the result. This can be used to enable a +visual inspection of the compressed image quality. In addition this mode also +prints out some image quality metrics to the console. The modes available mirror the options used for compression, but use a `t` prefix. @@ -195,7 +193,7 @@ there will come a point where the compressed image quality is unacceptable because there are simply not enough bits to represent the output with the precision needed. We recommend experimenting with the block footprint to find the optimum balance between size and quality, as the finely adjustable -compression ratio is one of major strengths of the ASTC format. +compression ratio is one of the major strengths of the ASTC format. The compression speed can be controlled from `-fastest`, through `-fast`, `-medium` and `-thorough`, up to `-exhaustive`. In general, the more time the diff --git a/Source/UnitTest/test_encode.cpp b/Source/UnitTest/test_encode.cpp index 7392af13e..069f64415 100644 --- a/Source/UnitTest/test_encode.cpp +++ b/Source/UnitTest/test_encode.cpp @@ -169,7 +169,7 @@ static void run_positive_test( /** @brief Input data contains negative infinities. */ TEST(compress, data_neg_inf_ldr) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -188,7 +188,7 @@ TEST(compress, data_neg_inf_ldr) /** @brief Input data contains negative infinities. */ TEST(compress, data_neg_inf_hdr) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -202,7 +202,7 @@ TEST(compress, data_neg_inf_hdr) /** @brief Input data contains negative infinities. */ TEST(compress, data_neg_inf_hdr_ldra) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -216,7 +216,7 @@ TEST(compress, data_neg_inf_hdr_ldra) /** @brief Input data contains positive infinities. */ TEST(compress, data_pos_inf_ldr) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -230,7 +230,7 @@ TEST(compress, data_pos_inf_ldr) /** @brief Input data contains positive infinities. */ TEST(compress, data_pos_inf_hdr) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -244,7 +244,7 @@ TEST(compress, data_pos_inf_hdr) /** @brief Input data contains positive infinities. */ TEST(compress, data_pos_inf_hdr_ldra) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -259,7 +259,7 @@ TEST(compress, data_pos_inf_hdr_ldra) /** @brief Input data contains NaN. */ TEST(compress, data_nan_ldr) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -273,7 +273,7 @@ TEST(compress, data_nan_ldr) /** @brief Input data contains NaN. */ TEST(compress, data_nan_hdr) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data @@ -287,7 +287,7 @@ TEST(compress, data_nan_hdr) /** @brief Input data contains NaN. */ TEST(compress, data_nan_hdr_ldra) { - // Cycle though a single bad value in each color channel + // Cycle through a single bad value in each color channel for(int offset = 0; offset < 4; offset++) { // 4x4 block input data diff --git a/Source/astcenc.h b/Source/astcenc.h index 7d01a135f..7f929a8c5 100644 --- a/Source/astcenc.h +++ b/Source/astcenc.h @@ -114,12 +114,12 @@ * | 4 components | RGBA | .rgba | * * The 1 and 2 component modes recommend sampling from "g" to recover the luminance value as this - * provide best compatibility with other texture formats where the green component may be stored at - * higher precision than the others, such as RGB565. For ASTC any of the RGB components can be used; - * the luminance endpoint component will be returned for all three. + * provides the best compatibility with other texture formats where the green component may be + * stored at higher precision than the others, such as RGB565. For ASTC any of the RGB components + * can be used; the luminance endpoint component will be returned for all three. * * When using the normal map compression mode ASTC will store normals as a two component X+Y map. - * Input images must contain unit-length normalized and should be passed in using a two component + * Input images must contain unit-length normals and they should be passed in using a two component * swizzle. The astcenc command line tool defaults to an RRRG swizzle, but some developers prefer * to use GGGR for compatibility with BC5n which will work just as well. The Z component can be * recovered programmatically in shader code, using knowledge that the vector is unit length and @@ -713,7 +713,7 @@ struct astcenc_block_info * @param block_y ASTC block size Y dimension. * @param block_z ASTC block size Z dimension. * @param quality Search quality preset / effort level. Either an - * @c ASTCENC_PRE_* value, or a effort level between 0 + * @c ASTCENC_PRE_* value, or an effort level between 0 * and 100. Performance is not linear between 0 and 100. * @param flags A valid set of @c ASTCENC_FLG_* flag bits. @@ -884,7 +884,7 @@ ASTCENC_PUBLIC enum astcenc_error astcenc_get_block_info( struct astcenc_block_info* info); /** - * @brief Get a printable string for specific status code. + * @brief Get a printable string for a specific status code. * * @param status The status value. * diff --git a/Source/astcenc_color_quantize.cpp b/Source/astcenc_color_quantize.cpp index dbe3bb7b6..4c015a68a 100644 --- a/Source/astcenc_color_quantize.cpp +++ b/Source/astcenc_color_quantize.cpp @@ -30,8 +30,8 @@ * * Endpoint 2 type: Direct color encoding, or scaled from endpoint 1. * * However, this leaves a number of decisions about exactly how to pack the endpoints open. In - * particular we need to determine if blue contraction can be used, or/and if delta encoding can be - * used. If they can be applied these will allow us to maintain higher precision in the endpoints + * particular we need to determine if blue contraction, delta encoding, or both can be used. If + * they can be applied these will allow us to maintain higher precision in the endpoints * without needing additional storage. */ diff --git a/Source/astcenc_compress_symbolic.cpp b/Source/astcenc_compress_symbolic.cpp index 6d0c965ed..a53d749e4 100644 --- a/Source/astcenc_compress_symbolic.cpp +++ b/Source/astcenc_compress_symbolic.cpp @@ -619,7 +619,7 @@ static float compress_symbolic_block_for_partition_1plane( best_errorval_in_mode = astc::min(errorval, best_errorval_in_mode); // Average refinement improvement is 3.5% per iteration (allow 4.5%), but the first - // iteration can help more so we give it a extra 8% leeway. Use this knowledge to + // iteration can help more so we give it an extra 8% leeway. Use this knowledge to // drive a heuristic to skip blocks that are unlikely to catch up with the best // block we have already. unsigned int iters_remaining = config.tune_refinement_limit - l; @@ -953,7 +953,7 @@ static float compress_symbolic_block_for_partition_2planes( best_errorval_in_mode = astc::min(errorval, best_errorval_in_mode); // Average refinement improvement is 3.5% per iteration (allow 4.5%), but the first - // iteration can help more so we give it a extra 8% leeway. Use this knowledge to + // iteration can help more so we give it an extra 8% leeway. Use this knowledge to // drive a heuristic to skip blocks that are unlikely to catch up with the best // block we have already. unsigned int iters_remaining = config.tune_refinement_limit - l; diff --git a/Source/astcenc_diagnostic_trace.h b/Source/astcenc_diagnostic_trace.h index 0e642124b..a9f6236e5 100644 --- a/Source/astcenc_diagnostic_trace.h +++ b/Source/astcenc_diagnostic_trace.h @@ -79,7 +79,7 @@ class TraceNode /** * @brief Construct a new node. * - * Constructing a node will push to the the top of the stack, automatically making it a child of + * Constructing a node will push to the top of the stack, automatically making it a child of * the current node, and then setting it to become the current node. * * @param format The format template for the node name. diff --git a/Source/astcenc_entry.cpp b/Source/astcenc_entry.cpp index 5afb4ac8b..d553884f4 100644 --- a/Source/astcenc_entry.cpp +++ b/Source/astcenc_entry.cpp @@ -518,7 +518,7 @@ astcenc_error astcenc_config_init( return status; } - // Zero init all config fields; although most of will be over written + // Zero init all config fields; although most of will be overwritten astcenc_config& config = *configp; std::memset(&config, 0, sizeof(config)); @@ -679,8 +679,8 @@ astcenc_error astcenc_config_init( if (flags & ASTCENC_FLG_MAP_NORMAL) { // Normal map encoding uses L+A blocks, so allow one more partitioning - // than normal. We need need fewer bits for endpoints, so more likely - // to be able to use more partitions than an RGB/RGBA block + // than usual. We need fewer bits for endpoints, so are more likely + // to be able to use more partitions config.tune_partition_count_limit = astc::min(config.tune_partition_count_limit + 1u, 4u); config.cw_g_weight = 0.0f; @@ -689,8 +689,8 @@ astcenc_error astcenc_config_init( config.tune_3partition_early_out_limit_factor *= 1.5f; config.tune_2plane_early_out_limit_correlation = 0.99f; - // Normals are prone to blocking artifacts on smooth curves - // so force compressor to try harder here ... + // Normals are prone to blocking artifacts on smooth curves so force + // compressor to try harder config.tune_db_limit *= 1.03f; } else if (flags & ASTCENC_FLG_MAP_RGBM) diff --git a/Source/astcenc_image.cpp b/Source/astcenc_image.cpp index db825fa3c..2471bdb6a 100644 --- a/Source/astcenc_image.cpp +++ b/Source/astcenc_image.cpp @@ -40,7 +40,7 @@ using pixel_swizzler = vfloat4(*)(vfloat4, const astcenc_swizzle&); using pixel_converter = vfloat4(*)(vfloat4, vmask4); /** - * @brief Load a 8-bit UNORM texel from a data array. + * @brief Load an 8-bit UNORM texel from a data array. * * @param data The data pointer. * @param base_offset The index offset to the start of the pixel. @@ -124,7 +124,7 @@ static vfloat4 swz_texel( * Out-of-range inputs will be clamped to the valid UNORM range. * * @param data The RGBA data to encode. - * @param lns_mask The mask for the HDR channels than need LNS encoding. + * @param lns_mask The mask for the HDR channels that need LNS encoding. */ static vfloat4 encode_texel_unorm( vfloat4 data, @@ -145,7 +145,7 @@ static vfloat4 encode_texel_unorm( * depending on @c lns_mask. * * @param data The RGBA data to encode. - * @param lns_mask The mask for the HDR channels than need LNS encoding. + * @param lns_mask The mask for the HDR channels that need LNS encoding. */ static vfloat4 encode_texel_lns( vfloat4 data, diff --git a/Source/astcenc_internal.h b/Source/astcenc_internal.h index 713ebf049..46942171b 100644 --- a/Source/astcenc_internal.h +++ b/Source/astcenc_internal.h @@ -277,20 +277,20 @@ struct partition_metrics }; /** - * @brief Computed lines for a a three component analysis. + * @brief Computed lines for a three component analysis. */ struct partition_lines3 { /** @brief Line for uncorrelated chroma. */ line3 uncor_line; - /** @brief Line for correlated chroma, passing though the origin. */ + /** @brief Line for correlated chroma, passing through the origin. */ line3 samec_line; /** @brief Post-processed line for uncorrelated chroma. */ processed_line3 uncor_pline; - /** @brief Post-processed line for correlated chroma, passing though the origin. */ + /** @brief Post-processed line for correlated chroma, passing through the origin. */ processed_line3 samec_pline; /** @@ -337,7 +337,7 @@ struct partition_info * @brief The weight grid information for a single decimation pattern. * * ASTC can store one weight per texel, but is also capable of storing lower resolution weight grids - * that are interpolated during decompression to assign a with to a texel. Storing fewer weights + * that are interpolated during decompression to assign a weight to a texel. Storing fewer weights * can free up a substantial amount of bits that we can then spend on more useful things, such as * more accurate endpoints and weights, or additional partitions. * diff --git a/Source/astcenc_mathlib.h b/Source/astcenc_mathlib.h index 3e30f6e88..44f153d29 100644 --- a/Source/astcenc_mathlib.h +++ b/Source/astcenc_mathlib.h @@ -258,7 +258,7 @@ static inline T max(T p, T q, T r, T s) } /** - * @brief Clamp a value value between @c mn and @c mx. + * @brief Clamp a value between @c mn and @c mx. * * For floats, NaNs are turned into @c mn. * @@ -272,7 +272,7 @@ template inline T clamp(T v, T mn, T mx) { // Do not reorder; correct NaN handling relies on the fact that comparison - // with NaN returns false and will fall-though to the "min" value. + // with NaN returns false and will fall-through to the "min" value. if (v > mx) return mx; if (v > mn) return v; return mn; @@ -427,7 +427,7 @@ static inline unsigned int int_as_uint(int v) */ static inline int uint_as_int(unsigned int v) { - // Future: Can use std:bit_cast with C++20git p + // Future: Can use std:bit_cast with C++20 int sv; std::memcpy(&sv, &v, sizeof(unsigned int)); return sv; diff --git a/Source/astcenc_pick_best_endpoint_format.cpp b/Source/astcenc_pick_best_endpoint_format.cpp index caff41b7a..485785def 100644 --- a/Source/astcenc_pick_best_endpoint_format.cpp +++ b/Source/astcenc_pick_best_endpoint_format.cpp @@ -263,14 +263,14 @@ static void compute_encoding_choice_errors( uncor_rgb_plines.amod = uncor_rgb_lines.a - uncor_rgb_lines.b * dot3(uncor_rgb_lines.a, uncor_rgb_lines.b); uncor_rgb_plines.bs = uncor_rgb_lines.b; - // Same chroma always goes though zero, so this is simpler than the others + // Same chroma always goes through zero, so this is simpler than the others samec_rgb_plines.amod = vfloat4::zero(); samec_rgb_plines.bs = samec_rgb_lines.b; rgb_luma_plines.amod = rgb_luma_lines.a - rgb_luma_lines.b * dot3(rgb_luma_lines.a, rgb_luma_lines.b); rgb_luma_plines.bs = rgb_luma_lines.b; - // Luminance always goes though zero, so this is simpler than the others + // Luminance always goes through zero, so this is simpler than the others luminance_plines.amod = vfloat4::zero(); luminance_plines.bs = unit3(); diff --git a/Source/astcenc_vecmathlib_avx2_8.h b/Source/astcenc_vecmathlib_avx2_8.h index 17147a149..1b50b1282 100644 --- a/Source/astcenc_vecmathlib_avx2_8.h +++ b/Source/astcenc_vecmathlib_avx2_8.h @@ -294,7 +294,7 @@ ASTCENC_SIMD_INLINE vmask8 operator~(vmask8 a) } /** - * @brief Return a 8-bit mask code indicating mask status. + * @brief Return an 8-bit mask code indicating mask status. * * bit0 = lane 0 */ diff --git a/Source/astcenc_vecmathlib_sve_8.h b/Source/astcenc_vecmathlib_sve_8.h index 4408c81b3..31c0efdda 100644 --- a/Source/astcenc_vecmathlib_sve_8.h +++ b/Source/astcenc_vecmathlib_sve_8.h @@ -283,7 +283,7 @@ ASTCENC_SIMD_INLINE vmask8 operator~(vmask8 a) } /** - * @brief Return a 8-bit mask code indicating mask status. + * @brief Return an 8-bit mask code indicating mask status. * * bit0 = lane 0 */ diff --git a/Source/astcenccli_image_load_store.cpp b/Source/astcenccli_image_load_store.cpp index 1741d7309..9efb62f4e 100644 --- a/Source/astcenccli_image_load_store.cpp +++ b/Source/astcenccli_image_load_store.cpp @@ -697,46 +697,6 @@ static void switch_endianness4( } } -/* - Notes about KTX: - - After the header and the key/value data area, the actual image data follows. - Each image starts with a 4-byte "imageSize" value indicating the number of bytes of image data follow. - (For cube-maps, this value appears only after first image; the remaining 5 images are all of equal size.) - If the size of an image is not a multiple of 4, then it is padded to the next multiple of 4. - Note that this padding is NOT included in the "imageSize" field. - In a cubemap, the padding appears after each face note that in a 2D/3D texture, padding does - NOT appear between the lines/planes of the texture! - - In a KTX file, there may be multiple images; they are organized as follows: - - For each mipmap_level in numberOfMipmapLevels - UInt32 imageSize; - For each array_element in numberOfArrayElements - * for each face in numberOfFaces - * for each z_slice in pixelDepth - * for each row or row_of_blocks in pixelHeight - * for each pixel or block_of_pixels in pixelWidth - Byte data[format-specific-number-of-bytes] - * end - * end - *end - Byte cubePadding[0-3] - *end - Byte mipPadding[3 - ((imageSize+ 3) % 4)] - *end - - In the ASTC codec, we will, for the time being only harvest the first image, - and we will support only a limited set of formats: - - gl_type: UNSIGNED_BYTE UNSIGNED_SHORT HALF_FLOAT FLOAT UNSIGNED_INT_8_8_8_8 UNSIGNED_INT_8_8_8_8_REV - gl_format: RED, RG. RGB, RGBA BGR, BGRA - gl_internal_format: used for upload to OpenGL; we can ignore it on uncompressed-load, but - need to provide a reasonable value on store: RGB8 RGBA8 RGB16F RGBA16F - gl_base_internal_format: same as gl_format unless texture is compressed (well, BGR is turned into RGB) - RED, RG, RGB, RGBA -*/ - // Khronos enums #define GL_RED 0x1903 #define GL_RG 0x8227 @@ -1182,17 +1142,17 @@ static astcenc_image_ptr load_ktx_uncompressed_image( if (hdr.number_of_mipmap_levels > 1) { - printf("WARNING: Only first of %u mipmap levels will be compressed '%s'.\n", hdr.number_of_mipmap_levels, filename); + printf("WARNING: Only the first of %u mipmap levels will be compressed '%s'.\n", hdr.number_of_mipmap_levels, filename); } if (hdr.number_of_array_elements > 1) { - printf("WARNING: Only first of %u array layers will be compressed '%s'.\n", hdr.number_of_array_elements, filename); + printf("WARNING: Only the first of %u array layers will be compressed '%s'.\n", hdr.number_of_array_elements, filename); } if (hdr.number_of_faces > 1) { - printf("WARNING: Only first of %u cube faces will be compressed '%s'.\n", hdr.number_of_faces, filename); + printf("WARNING: Only the first of %u cube faces will be compressed '%s'.\n", hdr.number_of_faces, filename); } unsigned int dim_x = hdr.pixel_width; diff --git a/Source/astcenccli_toplevel.cpp b/Source/astcenccli_toplevel.cpp index be3b9c3a3..80902d1eb 100644 --- a/Source/astcenccli_toplevel.cpp +++ b/Source/astcenccli_toplevel.cpp @@ -220,7 +220,7 @@ static bool is_float( // Leading whitespace is an error stream >> std::noskipws >> test; - // Ensure entire no remaining string in addition to parse failure + // Ensure no remaining string, in addition to checking for parse failure return stream.eof() && !stream.fail(); } @@ -670,7 +670,7 @@ static int init_astcenc_config( } else if (status == ASTCENC_ERR_BAD_DECODE_MODE) { - print_error("ERROR: Decode_unorm8 is not supported by HDR profiles\n"); + print_error("ERROR: decode_unorm8 is not supported by HDR profiles\n"); return 1; } else if (status == ASTCENC_ERR_BAD_CPU_FLOAT) @@ -885,7 +885,7 @@ static int edit_astcenc_config( swizzle_components[i] = ASTCENC_SWZ_Z; break; default: - print_error("ERROR: ERROR: -dsw component '%c' is not valid\n", argv[argidx - 1][i]); + print_error("ERROR: -dsw component '%c' is not valid\n", argv[argidx - 1][i]); return 1; } } diff --git a/Source/astcenccli_toplevel_help.cpp b/Source/astcenccli_toplevel_help.cpp index 1c201ed66..c7dcc9748 100644 --- a/Source/astcenccli_toplevel_help.cpp +++ b/Source/astcenccli_toplevel_help.cpp @@ -56,7 +56,7 @@ LDR profile, preventing use of the HDR encoding features. The -*s options are used to configure the codec to support only the sRGB LDR profile, preventing use of the HDR encoding features. Input -texture data must be encoded in the sRGB colorspace for this option to +texture data must be encoded in the sRGB color space for this option to provide correct output results. The -*h/-*H options are used to configure the codec to support the HDR ASTC @@ -77,18 +77,18 @@ SYNOPSIS astcenc {-h|-help} astcenc {-v|-version} astcenc {-cl|-cs|-ch|-cH} [options] - astcenc {-dl|-ds|-dh|-dH} [options] + astcenc {-dl|-ds|-dh|-dH} astcenc {-tl|-ts|-th|-tH} [options] DESCRIPTION astcenc compresses image files into the Adaptive Scalable Texture - Compression (ASTC) image format, a lossy compression format design - for use in real-time graphics applications. It is a fully featured - compressor implementation, supporting all of the compression - profiles and block sizes specified by the ASTC format: + Compression (ASTC) image format, a lossy compression format + designed for use in real-time graphics applications. astcenc + supports all of the compression profiles and block sizes allowed by + the ASTC format: All color profiles (LDR linear, LDR sRGB, and HDR) - All 2D block sizes (4x4 though to 12x12) + All 2D block sizes (4x4 through to 12x12) All 3D block sizes (3x3x3 through to 6x6x6) The compressor provides a flexible quality level, allowing users to @@ -186,7 +186,7 @@ COMPRESSION parameters. -rgbm - The input texture is an RGBM encoded texture, storing values HDR + The input texture is an RGBM encoded texture, storing HDR values between 0 and in an LDR container format with a shared multiplier. Shaders reconstruct the HDR value as: @@ -199,13 +199,13 @@ COMPRESSION -perceptual The codec should optimize perceptual error, instead of direct - RMS error. This aims to improves perceived image quality, but + RMS error. This aims to improve perceived image quality, but typically lowers the measured PSNR score. Perceptual methods are - currently only available for normal maps and RGB color data. + currently only available for RGB color data. -zdim Load a sequence of 2D image slices to use as a 3D image. - The input filename given is used is decorated with the postfix + The input filename given is decorated with the postfix "_" to find the file to load. For example, an input named "input.png" would load as input_0.png, input_1.png, etc. @@ -244,7 +244,7 @@ ADVANCED COMPRESSION computation, used to determine what good compression looks like. -a - For textures with alpha component, scale per-texel weights by + For textures with an alpha component, scale per-texel weights by the alpha value. The alpha value chosen for scaling of any particular texel is taken as an average across a neighborhood of the texel defined by the argument. Setting to @@ -272,8 +272,8 @@ ADVANCED COMPRESSION These options provide low-level control of the codec heuristics that drive the performance-quality trade off. The presets vary by block bitrate; the recommended starting point for a 4x4 block is very - different to a 8x8 block. The presets documented here are for the - high bitrate mode (fewer than 25 texels). + different to the one for an 8x8 block. The presets documented here + are for the high bitrate mode (fewer than 25 texels). -partitioncountlimit Test up to and including partitions for each block. @@ -471,15 +471,16 @@ DECOMPRESSION TEST To perform a compression test which round-trips a single image through compression and decompression and stores the decompressed - result back to file, you must specify same settings as COMPRESSION - other than swapping the color profile to select test mode. Note that - the compressed intermediate data is discarded in this mode. + result back to file, you must specify the same settings as + COMPRESSION other than swapping the color profile option to select + a test mode. Note that the compressed intermediate data is discarded + in this mode. The color profile is specified using the -tl (LDR linear), -ts (LDR sRGB), -th (HDR RGB, LDR A), or -tH (HDR RGBA) encoder options. This operation mode will print error metrics suitable for either LDR - and HDR images, allowing some assessment of the compression image + or HDR images, allowing some assessment of the compression image quality. COMPRESSION FILE FORMATS