Math: utilities for flipping BC1/3/4/5 blocks.

Most of the testing scaffolding here is a preparation for the actually
complex formats like BC6/7 or ASTC. Also, it's great to be able to use
Magnum from Python to prepare data for testing the C++ Magnum APIs.

doc/changelog.dox

@@ -214,6 +214,8 @@ See also:
     @ref Math::Quaternion::reflectVector(), but mainly just for documentation
     purposes as reflections cannot be combined with rotations and thus are
     mostly useless in practice
+-   New @ref Magnum/Math/ColorBatch.h header with utilities for performing Y
+    flip of various block-compressed formats
 
 @subsubsection changelog-latest-new-materialtools MaterialTools library
 

src/Magnum/CMakeLists.txt

@@ -140,6 +140,7 @@ set(MagnumMath_SRCS
     Math/instantiation.cpp)
 
 set(MagnumMath_GracefulAssert_SRCS
+    Math/ColorBatch.cpp
     Math/Functions.cpp
     Math/PackingBatch.cpp)
 

src/Magnum/Math/CMakeLists.txt

@@ -32,6 +32,7 @@ set(MagnumMath_HEADERS
     Bezier.h
     BitVector.h
     Color.h
+    ColorBatch.h
     Complex.h
     Constants.h
     ConfigurationValue.h

src/Magnum/Math/ColorBatch.cpp

@@ -0,0 +1,201 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
+                2020, 2021, 2022 Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+#include "ColorBatch.h"
+
+#include <cstring>
+#include <Corrade/Containers/StridedArrayView.h>
+
+#include "Magnum/Magnum.h"
+
+namespace Magnum { namespace Math {
+
+namespace {
+
+inline void yFlipBc1BlockInPlace(char* const data) {
+    /* The 64-bit block is laid out as follows:
+
+        - 2 bytes for first endpoint color
+        - 2 bytes for second endpoint color
+        - 4 bytes for 4x4 2-bit color indices in this order:
+
+            a b c d
+            e f g h
+            i j k l
+            m n o p
+
+       Which means each row is one byte, so the Y-flip reduces down to a simple
+       byte swap. See the official specification for details:
+       https://learn.microsoft.com/cs-cz/windows/win32/direct3d10/d3d10-graphics-programming-guide-resources-block-compression#bc1 */
+    {
+        char tmp = data[4];
+        data[4] = data[7];
+        data[7] = tmp;
+    } {
+        char tmp = data[5];
+        data[5] = data[6];
+        data[6] = tmp;
+    }
+}
+
+inline void yFlipBc4BlockInPlace(char* data) {
+    /* The 64-bit block is laid out as follows:
+
+       - 1 byte for first endpoint color channel
+       - 1 byte for second endpoint color channel
+       - 6 bytes for 4x4 3-bit color indices + interpolation factors, same
+         order as BC1
+
+       Compared to BC1, this means swapping groups of 12 bits instead of 8.
+       https://learn.microsoft.com/cs-cz/windows/win32/direct3d10/d3d10-graphics-programming-guide-resources-block-compression#bc4 */
+
+    /* Load & byte-swap the whole block */
+    union {
+        char bytes[8];
+        UnsignedLong value;
+    } block;
+    for(std::size_t i = 0; i != 8; ++i) {
+        #ifndef CORRADE_TARGET_BIG_ENDIAN
+        block.bytes[i] = data[i];
+        #else
+        block.bytes[i] = data[7 - i];
+        #endif
+    }
+
+    /* Flip the 12-bit groups */
+    block.value =
+        (block.value & 0x000000000000ffffull) |
+        (block.value & 0xfff0000000000000ull) >> 36 |
+        (block.value & 0x000fff0000000000ull) >> 12 |
+        (block.value & 0x000000fff0000000ull) << 12 |
+        (block.value & 0x000000000fff0000ull) << 36;
+
+    /* Byte-swap & store the block back */
+    for(std::size_t i = 0; i != 8; ++i) {
+        #ifndef CORRADE_TARGET_BIG_ENDIAN
+        data[i] = block.bytes[i];
+        #else
+        data[i] = block.bytes[7 - i];
+        #endif
+    }
+}
+
+inline void yFlipBc3BlockInPlace(char* const data) {
+    yFlipBc4BlockInPlace(data);
+    yFlipBc1BlockInPlace(data + 8);
+}
+
+inline void yFlipBc5BlockInPlace(char* const data) {
+    yFlipBc4BlockInPlace(data);
+    yFlipBc4BlockInPlace(data + 8);
+}
+
+template<std::size_t blockSize, void(*flipBlock)(char*)> void yFlipBlocksInPlace(const Containers::StridedArrayView4D<char>& blocks
+    #ifndef CORRADE_NO_ASSERT
+    , const char* messagePrefix
+    #endif
+) {
+    const std::size_t* const size = blocks.size().begin();
+    CORRADE_ASSERT(size[3] == blockSize,
+        messagePrefix << "expected last dimension to be" << blockSize << "bytes but got" << size[3], );
+    CORRADE_ASSERT(blocks.isContiguous<3>(),
+        messagePrefix << "last dimension is not contiguous", );
+
+    /* The high-level logic is mostly a copy of Utility::flipInPlace() without
+       the "leftovers" part. It's however not calling that function directly
+       because it'd mean going through memory twice, once for copying whole
+       blocks and once for recalculating each block. */
+
+    CORRADE_INTERNAL_ASSERT(blocks.template isContiguous<3>());
+
+    char* const ptr = static_cast<char*>(blocks.data());
+    const std::ptrdiff_t* const stride = blocks.stride().begin();
+    for(std::size_t z = 0; z != size[0]; ++z) {
+        char* const ptrZ = ptr + z*stride[0];
+
+        /* Go through half of the items in Y and swap them with the other
+           half, flipping their contents along the way */
+        for(std::size_t y = 0, yMax = size[1]/2; y != yMax; ++y) {
+            char* const ptrYTop = ptrZ + y*stride[1];
+            char* const ptrYBottom = ptrZ + (size[1] - y - 1)*stride[1];
+
+            /* Copy a block at a time and flip its contents as well */
+            alignas(blockSize) char tmp[blockSize];
+            for(std::size_t x = 0; x != size[2]; ++x) {
+                char* const ptrXTop = ptrYTop + x*stride[2];
+                char* const ptrXBottom = ptrYBottom + x*stride[2];
+                flipBlock(ptrXTop);
+                flipBlock(ptrXBottom);
+                std::memcpy(tmp, ptrXTop, blockSize);
+                std::memcpy(ptrXTop, ptrXBottom, blockSize);
+                std::memcpy(ptrXBottom, tmp, blockSize);
+            }
+        }
+
+        /* If there was an odd number of rows, make sure to flip contents of
+           the middle row as well */
+        if(size[1] % 2) {
+            char* const ptrYMid = ptrZ + (size[1]/2)*stride[1];
+            for(std::size_t x = 0; x != size[2]; ++x)
+                flipBlock(ptrYMid + x*stride[2]);
+        }
+    }
+}
+
+}
+
+void yFlipBc1InPlace(const Containers::StridedArrayView4D<char>& blocks) {
+    yFlipBlocksInPlace<8, yFlipBc1BlockInPlace>(blocks
+        #ifndef CORRADE_NO_ASSERT
+        , "Math::yFlipBc1InPlace():"
+        #endif
+    );
+}
+
+void yFlipBc3InPlace(const Containers::StridedArrayView4D<char>& blocks) {
+    yFlipBlocksInPlace<16, yFlipBc3BlockInPlace>(blocks
+        #ifndef CORRADE_NO_ASSERT
+        , "Math::yFlipBc3InPlace():"
+        #endif
+    );
+}
+
+void yFlipBc4InPlace(const Containers::StridedArrayView4D<char>& blocks) {
+    yFlipBlocksInPlace<8, yFlipBc4BlockInPlace>(blocks
+        #ifndef CORRADE_NO_ASSERT
+        , "Math::yFlipBc4InPlace():"
+        #endif
+    );
+}
+
+void yFlipBc5InPlace(const Containers::StridedArrayView4D<char>& blocks) {
+    yFlipBlocksInPlace<16, yFlipBc5BlockInPlace>(blocks
+        #ifndef CORRADE_NO_ASSERT
+        , "Math::yFlipBc5InPlace():"
+        #endif
+    );
+}
+
+}}

src/Magnum/Math/ColorBatch.h

@@ -0,0 +1,126 @@
+#ifndef Magnum_Math_ColorBatch_h
+#define Magnum_Math_ColorBatch_h
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
+                2020, 2021, 2022 Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+/** @file
+ * @brief Function @ref Magnum::Math::yFlipBc1InPlace(), @ref Magnum::Math::yFlipBc3InPlace(), @ref Magnum::Math::yFlipBc4InPlace(), @ref Magnum::Math::yFlipBc5InPlace()
+ * @m_since_latest
+ */
+
+#include <Corrade/Containers/Containers.h>
+
+#include "Magnum/visibility.h"
+
+namespace Magnum { namespace Math {
+
+/**
+@brief Y-flip BC1 texture blocks in-place
+@m_since_latest
+
+Performs a Y flip of given 3D image by flipping block order and modifying
+internal block representation to encode the same information, just upside down.
+No decoding or re-encoding of the block data is performed, thus the operation
+is lossless. However note that this operation flips full blocks --- if size of
+the actual image isn't whole blocks, the flipped image will be shifted compared
+to the original, possibly with garbage data appearing in the first few rows.
+
+First dimension is expected to be image slices, second block rows, third
+2D blocks, fourth the 64-bit 4x4 block data, i.e. the last dimension is
+expected to be contiguous with size of 8.
+@see @ref CompressedPixelFormat::Bc1RGBUnorm,
+    @ref CompressedPixelFormat::Bc1RGBSrgb,
+    @ref CompressedPixelFormat::Bc1RGBAUnorm,
+    @ref CompressedPixelFormat::Bc1RGBASrgb
+*/
+MAGNUM_EXPORT void yFlipBc1InPlace(const Corrade::Containers::StridedArrayView4D<char>& blocks);
+
+/** @todo BC2, if used at all for anything */
+
+/**
+@brief Y-flip BC3 texture blocks in-place
+@m_since_latest
+
+Performs a Y flip of given 3D image by flipping block order and modifying
+internal block representation to encode the same information, just upside down.
+No decoding or re-encoding of the block data is performed, thus the operation
+is lossless. However note that this operation flips full blocks --- if size of
+the actual image isn't whole blocks, the flipped image will be shifted compared
+to the original, possibly with garbage data appearing in the first few rows.
+
+First dimension is expected to be image slices, second block rows, third
+2D blocks, fourth the 128-bit 4x4 block data, i.e. the last dimension is
+expected to be contiguous with size of 16. As BC3 is internally a 64-bit BC4
+block for alpha followed by a 64-bit BC1 block for RGB, the operation is the
+same as performing @ref yFlipBc4InPlace() on the first half and
+@ref yFlipBc1InPlace() on second half of each block.
+@see @ref CompressedPixelFormat::Bc3RGBAUnorm,
+    @ref CompressedPixelFormat::Bc3RGBASrgb
+*/
+MAGNUM_EXPORT void yFlipBc3InPlace(const Corrade::Containers::StridedArrayView4D<char>& blocks);
+
+/**
+@brief Y-flip BC4 texture blocks in-place
+@m_since_latest
+
+Performs a Y flip of given 3D image by flipping block order and modifying
+internal block representation to encode the same information, just upside down.
+No decoding or re-encoding of the block data is performed, thus the operation
+is lossless. However note that this operation flips full blocks --- if size of
+the actual image isn't whole blocks, the flipped image will be shifted compared
+to the original, possibly with garbage data appearing in the first few rows.
+
+First dimension is expected to be image slices, second block rows, third
+2D blocks, fourth the 64-bit 4x4 block data, i.e. the last dimension is
+expected to be contiguous with size of 8.
+@see @ref CompressedPixelFormat::Bc4RUnorm,
+    @ref CompressedPixelFormat::Bc4RSnorm
+*/
+MAGNUM_EXPORT void yFlipBc4InPlace(const Corrade::Containers::StridedArrayView4D<char>& blocks);
+
+/**
+@brief Y-flip BC5 texture blocks in-place
+@m_since_latest
+
+Performs a Y flip of given 3D image by flipping block order and modifying
+internal block representation to encode the same information, just upside down.
+No decoding or re-encoding of the block data is performed, thus the operation
+is lossless. However note that this operation flips full blocks --- if size of
+the actual image isn't whole blocks, the flipped image will be shifted compared
+to the original, possibly with garbage data appearing in the first few rows.
+
+First dimension is expected to be image slices, second block rows, third
+2D blocks, fourth the 128-bit 4x4 block data, i.e. the last dimension is
+expected to be contiguous with size of 16. As BC5 is internally two 64-bit BC4
+blocks, the operation is the same as performing @ref yFlipBc4InPlace() on both
+halves of each block.
+@see @ref CompressedPixelFormat::Bc5RGUnorm,
+    @ref CompressedPixelFormat::Bc5RGSnorm
+*/
+MAGNUM_EXPORT void yFlipBc5InPlace(const Corrade::Containers::StridedArrayView4D<char>& blocks);
+
+}}
+
+#endif

src/Magnum/Math/Test/CMakeLists.txt

@@ -43,6 +43,20 @@ corrade_add_test(MathVector3Test Vector3Test.cpp LIBRARIES MagnumMathTestLib)
 corrade_add_test(MathVector4Test Vector4Test.cpp LIBRARIES MagnumMathTestLib)
 corrade_add_test(MathColorTest ColorTest.cpp LIBRARIES MagnumMathTestLib)
 
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake
+               ${CMAKE_CURRENT_BINARY_DIR}/configure.h)
+
+corrade_add_test(MathColorBatchTest ColorBatchTest.cpp
+    LIBRARIES MagnumMathTestLib MagnumDebugTools
+    FILES
+        ColorBatchTestFiles/bc1.png
+        ColorBatchTestFiles/bc3.png
+        ColorBatchTestFiles/bc4.png
+        ColorBatchTestFiles/bc5.png
+        ColorBatchTestFiles/checkerboard.png
+        ColorBatchTestFiles/checkerboard-odd.png)
+target_include_directories(MathColorBatchTest PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
+
 corrade_add_test(MathRectangularMatrixTest RectangularMatrixTest.cpp LIBRARIES MagnumMathTestLib)
 corrade_add_test(MathMatrixTest MatrixTest.cpp LIBRARIES MagnumMathTestLib)
 corrade_add_test(MathMatrix3Test Matrix3Test.cpp LIBRARIES MagnumMathTestLib)