Fix recreateBytesPlane0 and add test (KhronosGroup#856)

of correct result for all valid VkFormats.

Modify mkvkformatfiles to generate the list of valid format names
to populate the table that drives the new test.

Fix dfdutils Doxygen config file to include queries.c in the input.

Author: MarkCallow

cmake/mkvk.cmake

@@ -22,8 +22,9 @@ if (NOT IOS AND NOT ANDROID)
 #    # I haven't investigated why.
 #    find_package(Vulkan REQUIRED)
 
-# This file is included from so has the same scope as the including file.
-# If we change Vulkan_INCLUDE_DIR, other users will be effected.
+# This file is included from its parent so has the same scope as the
+# including file. If we change Vulkan_INCLUDE_DIR, other users will
+# be affected.
     set(mkvk_vulkan_include_dir lib/dfdutils)
 else()
     # Skip mkvk. There is no need to use iOS or Android to regenerate
@@ -59,6 +60,7 @@ list(APPEND mkvkformatfiles_output
     "${PROJECT_SOURCE_DIR}/lib/vkformat_enum.h"
     "${PROJECT_SOURCE_DIR}/lib/vkformat_typesize.c"
     "${PROJECT_SOURCE_DIR}/lib/vkformat_check.c"
+    "${PROJECT_SOURCE_DIR}/lib/vkformat_list.c"
     "${PROJECT_SOURCE_DIR}/lib/vkformat_str.c")
 
 # CAUTION: When a COMMAND contains VAR="Value" CMake messes up the escaping

lib/dfdutils/dfd.h

@@ -198,9 +198,12 @@ getDFDComponentInfoUnpacked(const uint32_t* DFD, uint32_t* numComponents,
 /* Return the number of components described by a DFD. */
 uint32_t getDFDNumComponents(const uint32_t* DFD);
 
-/* Recreate and return the value of bytesPlane0 as it should be for the data
+/* Reconstruct and return the value of bytesPlane0 as it should be for the data
  * post-inflation from variable-rate compression.
  */
+uint32_t
+reconstructDFDBytesPlane0FromSamples(const uint32_t* DFD);
+/* Deprecated. For backward compatibility. */
 void
 recreateBytesPlane0FromSampleInfo(const uint32_t* DFD, uint32_t* bytesPlane0);
 

lib/dfdutils/dfdutils.doxy

@@ -943,6 +943,7 @@ INPUT                  = LICENSE.adoc \
                          dfd2vk.c \
                          interpretdfd.c \
                          printdfd.c \
+                         queries.c \
                          vk2dfd.c
 
 # This tag can be used to specify the character encoding of the source files

lib/dfdutils/queries.c

@@ -41,15 +41,15 @@ getDFDComponentInfoUnpacked(const uint32_t* DFD, uint32_t* numComponents,
 {
     const uint32_t *BDFDB = DFD+1;
     uint32_t numSamples = KHR_DFDSAMPLECOUNT(BDFDB);
-    uint32_t sampleCounter;
+    uint32_t sampleNumber;
     uint32_t currentChannel = ~0U; /* Don't start matched. */
 
     /* This is specifically for unpacked formats which means the size of */
     /* each component is the same. */
     *numComponents = 0;
-    for (sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
-        uint32_t sampleByteLength = (KHR_DFDSVAL(BDFDB, sampleCounter, BITLENGTH) + 1) >> 3U;
-        uint32_t sampleChannel = KHR_DFDSVAL(BDFDB, sampleCounter, CHANNELID);
+    for (sampleNumber = 0; sampleNumber < numSamples; ++sampleNumber) {
+        uint32_t sampleByteLength = (KHR_DFDSVAL(BDFDB, sampleNumber, BITLENGTH) + 1) >> 3U;
+        uint32_t sampleChannel = KHR_DFDSVAL(BDFDB, sampleNumber, CHANNELID);
 
         if (sampleChannel == currentChannel) {
             /* Continuation of the same channel. */
@@ -85,10 +85,10 @@ uint32_t getDFDNumComponents(const uint32_t* DFD)
     uint32_t currentChannel = ~0U; /* Don't start matched. */
     uint32_t numComponents = 0;
     uint32_t numSamples = KHR_DFDSAMPLECOUNT(BDFDB);
-    uint32_t sampleCounter;
+    uint32_t sampleNumber;
 
-    for (sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
-        uint32_t sampleChannel = KHR_DFDSVAL(BDFDB, sampleCounter, CHANNELID);
+    for (sampleNumber = 0; sampleNumber < numSamples; ++sampleNumber) {
+        uint32_t sampleChannel = KHR_DFDSVAL(BDFDB, sampleNumber, CHANNELID);
         if (sampleChannel != currentChannel) {
             numComponents++;
             currentChannel = sampleChannel;
@@ -97,50 +97,83 @@ uint32_t getDFDNumComponents(const uint32_t* DFD)
     return numComponents;
 }
 
+
 /**
  * @~English
- * @brief Recreate the value of bytesPlane0 from sample info.
+ * @brief Reconstruct the value of bytesPlane0 from sample info.
  *
- * This can be use to recreate the value of bytesPlane0 for data that
- * has been variable-rate compressed so has bytesPlane0 = 0.  For DFDs
- * that are valid for KTX files. Little-endian data only and no multi-plane
- * formats.
+ * Reconstruct the value for data that has been variable-rate compressed so
+ * has bytesPlane0 = 0.  For DFDs that are valid for KTX files. Little-endian
+ * data only and no multi-plane formats.
  *
  * @param DFD Pointer to a Data Format Descriptor for which,
  *            described as 32-bit words in native endianness.
  *            Note that this is the whole descriptor, not just
  *            the basic descriptor block.
- * @param bytesPlane0  pointer to a 32-bit word in which the recreated
- *                    value of bytesPlane0 will be written.
  */
-void
-recreateBytesPlane0FromSampleInfo(const uint32_t* DFD, uint32_t* bytesPlane0)
+uint32_t
+reconstructDFDBytesPlane0FromSamples(const uint32_t* DFD)
 {
     const uint32_t *BDFDB = DFD+1;
     uint32_t numSamples = KHR_DFDSAMPLECOUNT(BDFDB);
-    uint32_t sampleCounter;
+    uint32_t sampleNumber;
 
     uint32_t bitsPlane0 = 0;
-    uint32_t* bitOffsets = malloc(sizeof(uint32_t) * numSamples);
-    memset(bitOffsets, -1, sizeof(uint32_t) * numSamples);
-    for (sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
-        uint32_t sampleBitOffset = KHR_DFDSVAL(BDFDB, sampleCounter, BITOFFSET);
-        /* The sample bitLength field stores the bit length - 1. */
-        uint32_t sampleBitLength = KHR_DFDSVAL(BDFDB, sampleCounter, BITLENGTH) + 1;
-        uint32_t i;
-        for (i = 0; i < numSamples; i++) {
-            if (sampleBitOffset == bitOffsets[i]) {
-                // This sample is being repeated as in e.g. RGB9E5.
-                break;
+    int32_t largestOffset = 0;
+    uint32_t sampleNumberWithLargestOffset = 0;
+
+    // Special case these depth{,-stencil} formats. The unused bits are
+    // in the MSBs so have no visibility in the DFD therefore the max offset
+    // algorithm below returns a value that is too small.
+    if (KHR_DFDSVAL(BDFDB, 0, CHANNELID) == KHR_DF_CHANNEL_COMMON_DEPTH) {
+        if (numSamples == 1) {
+            if (KHR_DFDSVAL(BDFDB, 0, BITLENGTH) + 1 == 24) {
+                // X8_D24_UNORM_PACK32,
+                return 4;
+            }
+        } else if (numSamples == 2) {
+            if (KHR_DFDSVAL(BDFDB, 0, BITLENGTH) + 1 == 16) {
+                // D16_UNORM_S8_UINT
+                return 4;
+            }
+            if (KHR_DFDSVAL(BDFDB, 0, BITLENGTH) + 1 == 32
+                && KHR_DFDSVAL(BDFDB, 1, CHANNELID) == KHR_DF_CHANNEL_COMMON_STENCIL) {
+                // D32_SFLOAT_S8_UINT
+                return 8;
             }
         }
-        if (i == numSamples) {
-            // Previously unseen bitOffset. Bump size.
-            bitsPlane0 += sampleBitLength;
-            bitOffsets[sampleCounter] = sampleBitOffset;
+    }
+    for (sampleNumber = 0; sampleNumber < numSamples; ++sampleNumber) {
+        int32_t sampleBitOffset = KHR_DFDSVAL(BDFDB, sampleNumber, BITOFFSET);
+        if (sampleBitOffset > largestOffset) {
+            largestOffset = sampleBitOffset;
+            sampleNumberWithLargestOffset = sampleNumber;
         }
     }
-    free(bitOffsets);
-    *bytesPlane0 = bitsPlane0 >> 3U;
+
+    /* The sample bitLength field stores the bit length - 1. */
+    uint32_t sampleBitLength = KHR_DFDSVAL(BDFDB, sampleNumberWithLargestOffset, BITLENGTH) + 1;
+    bitsPlane0 = largestOffset + sampleBitLength;
+    return bitsPlane0 >> 3U;
 }
 
+/**
+ * @~English
+ * @brief Reconstruct the value of bytesPlane0 from sample info.
+ *
+ * @see reconstructDFDBytesPlane0FromSamples for details.
+ * @deprecated For backward comparibility only. Use
+ *             reconstructDFDBytesPlane0FromSamples.
+ *
+ * @param DFD Pointer to a Data Format Descriptor for which,
+ *            described as 32-bit words in native endianness.
+ *            Note that this is the whole descriptor, not just
+ *            the basic descriptor block.
+ * @param bytesPlane0  pointer to a 32-bit word in which the recreated
+ *                    value of bytesPlane0 will be written.
+ */
+void
+recreateBytesPlane0FromSampleInfo(const uint32_t* DFD, uint32_t* bytesPlane0)
+{
+    *bytesPlane0 = reconstructDFDBytesPlane0FromSamples(DFD);
+}

lib/internalexport.def

@@ -43,6 +43,7 @@ EXPORTS
     ktxTexture2_GetImageOffset
     ktxTexture2_calcLevelOffset
     ktxTexture2_destruct
+    reconstructDFDBytesPlane0FromSamples
     vk2dfd
     vkFormatString
     vkFormatTypeSize

lib/internalexport_mingw.def

@@ -43,6 +43,7 @@ EXPORTS
     ktxTexture2_GetImageOffset
     ktxTexture2_calcLevelOffset
     ktxTexture2_destruct
+    reconstructDFDBytesPlane0FromSamples
     vk2dfd
     vkFormatString
     vkFormatTypeSize

lib/mkvkformatfiles

@@ -2,12 +2,16 @@
 # Copyright 2019-2024 Mark Callow
 # SPDX-License-Identifier: Apache-2.0
 
-# This script creates 3 files from vulkan/vulkan_core.h:
+# This script creates 5 files from vulkan/vulkan_core.h:
 #
 # - vkformat_enum.h, the VkFormat enum declaration for those who don't
 #   want to include vulkan_core.h.
+# - vkformat_list.inl, a list of VkFormat enum names for use in
+#   initializing tables, etc.
 # - vkformat_str.c, a switch statement for converting VkFormat enums to
 #   to strings corresponding to the format names.
+# - vkformat_typesize.c, function to return the type-size for each
+#   format.
 # - vkformat_check.c, 2 functions: 1 to checking if a format is prohibited in
 #   KTX2 and the other to see if a format is valid.
 #   KTX2.
@@ -24,6 +28,7 @@ BEGIN {
     copyright = "/*" ORS
     banner = ""
     format_decl = ""
+    format_name_list = ""
     core_formats = ""
     extension_formats = ""
     end_range = ""
@@ -41,6 +46,7 @@ BEGIN {
     }
     format_hdr = output_dir "vkformat_enum.h"
     format_typesize = output_dir "vkformat_typesize.c"
+    format_inl = output_dir "vkformat_list.inl"
     format_strings = output_dir "vkformat_str.c"
     format_check = output_dir "vkformat_check.c"
     if (ENVIRON["Vulkan_INCLUDE_DIR"]) {
@@ -83,6 +89,9 @@ $2 == "VK_HEADER_VERSION" {
       if (enum_val+0 > max_std_format_enum) {
         max_std_format_enum = enum_val+0;
       }
+      if ($1 !~ /UNDEFINED/) {
+        format_name_list = format_name_list $1 "," ORS
+      }
     }
   }
   if ($1 ~ /}/) {
@@ -103,6 +112,7 @@ $2 == "VK_HEADER_VERSION" {
 # Extract valid formats with values > VK_FORMAT_END_RANGE.
 /VK_FORMAT_[^F].* = 1000/ && ! /PLANE/ && !/420/ {
   valid = valid "        case " $1 ":" ORS;
+  format_name_list = format_name_list $1 "," ORS
 }
 
 function removePrefix(string, prefix) {
@@ -170,6 +180,7 @@ function write_source_file(body, filename) {
 END {
     # vkformat_enum.h
     write_header_file("_VKFORMAT_ENUM_H_", "VULKAN_CORE_H_", format_decl ORS end_range, format_hdr);
+    write_source_file(format_name_list ORS, format_inl)
 
     # vkformat_typesize.c
     begin_vktypesize = ORS