Add --{assign.convert}-texcoord-origin option to ktx create (KhronosGroup#976)

MarkCallow · web-flow · commit 91e61d6fa3f0 · 2025-01-19T07:48:08.000+09:00
Bring toktx's --lower_left_maps_to_s0t0 and --upper_left_maps_to_s0t0
to ktx create.

Includes a fix to EXR input to stop it Y flipping files with decreasing
Y line order. It now always produces top-left origin images.
diff --git a/tests/cts b/tests/cts
@@ -1 +1 @@
-Subproject commit 66b97a5b342889d5332a6485882fa549b8aaffe0
+Subproject commit 10559cce066bff1916b2a7300c792c67c6c898d3
diff --git a/tools/imageio/exr.imageio/exrinput.cc b/tools/imageio/exr.imageio/exrinput.cc
@@ -167,6 +167,8 @@ void ExrInput::open(ImageSpec& newspec) {
                             width,
                             height,
                             1,
+                            // We make TinyEXR decode to top-left.
+                            ImageSpec::Origin(ImageSpec::Origin::eLeft, ImageSpec::Origin::eTop),
                             header.num_channels,
                             bitDepth,
                             static_cast<khr_df_sample_datatype_qualifiers_e>(qualifiers),
@@ -236,6 +238,13 @@ void ExrInput::readImage(void* outputBuffer, size_t bufferByteCount,
             fmt::format("EXR load error: {}.", "Unsupported EXR version (2.0)"));
 
     // Load image data
+
+    // TinyEXR decodes images so that the first bytes in the returned buffer
+    // are the top-left corner of the image with line_order == 0 "increasing Y"
+    // and the bottom-left corner otherwise, "decreasing Y". Force a top-left
+    // origin regardless of the line_order in the file. See
+    // https://github.com/syoyo/tinyexr/issues/213 for more information.
+    header.line_order = 0;
     ec = LoadEXRImageFromMemory(&image, &header, exrBuffer.data(), exrBuffer.size(), &err);
     if (ec != TINYEXR_SUCCESS)
         throw std::runtime_error(fmt::format("EXR load error: {} - {}.", ec, err));
@@ -263,6 +272,9 @@ void ExrInput::readImage(void* outputBuffer, size_t bufferByteCount,
             channels[3] = i;
         else
             warning(fmt::format("EXR load warning: Unrecognized channel \"{}\" is ignored.", header.channels[i].name));
+        // TODO: check for 1 channel "Y" and make greyscale texture.
+        // TODO: check for "Y", "RY" and "BY" (luminance/chroma) and reject as unsupported.
+        // TODO: check for "AR", "AG", "AB" and make texture with pre-multipled alpha provided there is also an A channel? Or reject?
     }
 
     // Copy the data
diff --git a/tools/imageio/imageio.h b/tools/imageio/imageio.h
@@ -50,18 +50,49 @@ const stride_t AutoStride = std::numeric_limits<stride_t>::min();
 typedef bool (*ProgressCallback)(void *opaque_data, float portion_done);
 
 class ImageSpec {
+  public:
+    struct Origin {
+        uint8_t x;
+        uint8_t y;
+        uint8_t z;
+
+        static const uint8_t eLeft = 0;
+        static const uint8_t eRight = 1;
+        static const uint8_t eTop = 0;
+        static const uint8_t eBottom = 1;
+        static const uint8_t eFront = 0;
+        static const uint8_t eBack = 1;
+        static const uint8_t eUnspecified = 0xff;
+
+        // This is the most common origin among image file formats, hence
+        // the no arg constructor sets it. If unspecified, use the 3 arg ctor.
+        Origin() : x(eLeft), y(eTop), z(eFront) { };
+        Origin(uint8_t _x, uint8_t _y) : x(_x), y(_y), z(eFront) { }
+        Origin(uint8_t _x, uint8_t _y, uint8_t _z) : x(_x), y(_y), z(_z) { }
+
+        bool unspecified() {
+            return x == eUnspecified || y == eUnspecified || z == eUnspecified;
+        }
+    };
+
   protected:
     FormatDescriptor formatDesc;
     uint32_t imageWidth;           ///< width of the pixel data
     uint32_t imageHeight;          ///< height of the pixel data
     uint32_t imageDepth;           ///< depth of pixel data, >1 indicates a "volume"
+    Origin imageOrigin;            ///< logical corner of image that is the first pixel in the data stream
 
   public:
-    ImageSpec() : imageWidth(0), imageHeight(0), imageDepth(0) { }
+    ImageSpec() : imageWidth(0), imageHeight(0),
+                  imageDepth(0), imageOrigin() { }
+
+    ImageSpec(uint32_t w, uint32_t h, uint32_t d, FormatDescriptor& formatDesc)
+        : ImageSpec(w, h, d, Origin(), formatDesc) { }
 
-    ImageSpec(uint32_t w, uint32_t h, uint32_t d, FormatDescriptor formatDesc)
+    ImageSpec(uint32_t w, uint32_t h, uint32_t d, Origin&& o,
+              FormatDescriptor formatDesc)
         : formatDesc(std::move(formatDesc)),
-          imageWidth(w), imageHeight(h), imageDepth(d) { }
+          imageWidth(w), imageHeight(h), imageDepth(d), imageOrigin(o) { }
 
     ImageSpec(uint32_t w, uint32_t h, uint32_t d,
                uint32_t channelCount, uint32_t channelBitCount,
@@ -71,8 +102,19 @@ class ImageSpec {
                khr_df_primaries_e p = KHR_DF_PRIMARIES_BT709,
                khr_df_model_e m = KHR_DF_MODEL_RGBSDA,
                khr_df_flags_e f = KHR_DF_FLAG_ALPHA_STRAIGHT)
+        : ImageSpec(w, h, d, Origin(), channelCount,
+                    channelBitCount, dt, t, p, m, f) { }
+
+    ImageSpec(uint32_t w, uint32_t h, uint32_t d, Origin&& o,
+               uint32_t channelCount, uint32_t channelBitCount,
+               khr_df_sample_datatype_qualifiers_e dt
+                  = static_cast<khr_df_sample_datatype_qualifiers_e>(0),
+               khr_df_transfer_e t = KHR_DF_TRANSFER_UNSPECIFIED,
+               khr_df_primaries_e p = KHR_DF_PRIMARIES_BT709,
+               khr_df_model_e m = KHR_DF_MODEL_RGBSDA,
+               khr_df_flags_e f = KHR_DF_FLAG_ALPHA_STRAIGHT)
         : formatDesc(channelCount, channelBitCount, dt, t, p, m, f),
-          imageWidth(w), imageHeight(h), imageDepth(d) { }
+          imageWidth(w), imageHeight(h), imageDepth(d), imageOrigin(o) { }
 
     ImageSpec(uint32_t w, uint32_t h, uint32_t d,
                uint32_t channelCount, uint32_t channelBitCount,
@@ -83,10 +125,23 @@ class ImageSpec {
                khr_df_primaries_e p = KHR_DF_PRIMARIES_BT709,
                khr_df_model_e m = KHR_DF_MODEL_RGBSDA,
                khr_df_flags_e f = KHR_DF_FLAG_ALPHA_STRAIGHT)
+       : ImageSpec(w, h, d, Origin(), channelCount,
+                   channelBitCount,channelLower, channelUpper,
+                   dt, t, p, m, f) { }
+
+    ImageSpec(uint32_t w, uint32_t h, uint32_t d, Origin&& o,
+               uint32_t channelCount, uint32_t channelBitCount,
+               uint32_t channelLower, uint32_t channelUpper,
+               khr_df_sample_datatype_qualifiers_e dt
+                  = static_cast<khr_df_sample_datatype_qualifiers_e>(0),
+               khr_df_transfer_e t = KHR_DF_TRANSFER_UNSPECIFIED,
+               khr_df_primaries_e p = KHR_DF_PRIMARIES_BT709,
+               khr_df_model_e m = KHR_DF_MODEL_RGBSDA,
+               khr_df_flags_e f = KHR_DF_FLAG_ALPHA_STRAIGHT)
         : formatDesc(channelCount, channelBitCount,
                      channelLower, channelUpper,
                      dt, t, p, m, f),
-          imageWidth(w), imageHeight(h), imageDepth(d) { }
+          imageWidth(w), imageHeight(h), imageDepth(d), imageOrigin(o) { }
 
     ImageSpec(uint32_t w, uint32_t h, uint32_t d,
                uint32_t channelCount, std::vector<uint32_t>& channelBitLengths,
@@ -97,9 +152,21 @@ class ImageSpec {
                khr_df_primaries_e p = KHR_DF_PRIMARIES_BT709,
                khr_df_model_e m = KHR_DF_MODEL_RGBSDA,
                khr_df_flags_e f = KHR_DF_FLAG_ALPHA_STRAIGHT)
+        : ImageSpec(w, h, d, Origin(), channelCount,
+                  channelBitLengths, channelTypes, dt, t, p, m, f) { }
+
+    ImageSpec(uint32_t w, uint32_t h, uint32_t d, Origin&& o,
+               uint32_t channelCount, std::vector<uint32_t>& channelBitLengths,
+               std::vector<khr_df_model_channels_e>& channelTypes,
+               khr_df_sample_datatype_qualifiers_e dt
+                  = static_cast<khr_df_sample_datatype_qualifiers_e>(0),
+               khr_df_transfer_e t = KHR_DF_TRANSFER_UNSPECIFIED,
+               khr_df_primaries_e p = KHR_DF_PRIMARIES_BT709,
+               khr_df_model_e m = KHR_DF_MODEL_RGBSDA,
+               khr_df_flags_e f = KHR_DF_FLAG_ALPHA_STRAIGHT)
         : formatDesc(channelCount, channelBitLengths,
                      channelTypes, dt, t, p, m, f),
-          imageWidth(w), imageHeight(h), imageDepth(d) { }
+          imageWidth(w), imageHeight(h), imageDepth(d), imageOrigin(o) { }
 
 
     FormatDescriptor& format() { return formatDesc; }
@@ -108,10 +175,12 @@ class ImageSpec {
     uint32_t width() const noexcept { return imageWidth; }
     uint32_t height() const noexcept { return imageHeight; }
     uint32_t depth() const noexcept { return imageDepth; }
+    const Origin& origin() const noexcept { return imageOrigin; }
 
     void setWidth(uint32_t w) { imageWidth = w; }
     void setHeight(uint32_t h) { imageHeight = h; }
     void setDepth(uint32_t d) { imageDepth = d; }
+    void setOrigin(const Origin& o) { imageOrigin = o; }
 
     size_t imagePixelCount() const noexcept {
         return depth() * width() * height();
@@ -134,6 +203,14 @@ class ImageSpec {
     }
 };
 
+constexpr bool operator==(const ImageSpec::Origin& lhs, const ImageSpec::Origin& rhs) {
+    return lhs.x == rhs.x && lhs.y == rhs.y && lhs.z == rhs.z;
+}
+
+constexpr bool operator!=(const ImageSpec::Origin& lhs, const ImageSpec::Origin& rhs) {
+    return lhs.x != rhs.x || lhs.y != rhs.y || lhs.z != rhs.z;
+}
+
 typedef std::function<void(const std::string&)> WarningCallbackFunction;
 
 enum class ImageInputFormatType {
diff --git a/tools/imageio/jpg.imageio/jpginput.cc b/tools/imageio/jpg.imageio/jpginput.cc
@@ -213,6 +213,7 @@ JpegInput::readHeader()
     // return what the decode() method will return not what is in the file.
 
     images.emplace_back(ImageSpec(pJd->get_width(), pJd->get_height(), 1,
+                                ImageSpec::Origin(ImageSpec::Origin::eLeft, ImageSpec::Origin::eTop),
                                 pJd->get_num_components(), 8, // component bit length
                                 static_cast<khr_df_sample_datatype_qualifiers_e>(0),
                                 KHR_DF_TRANSFER_SRGB,
diff --git a/tools/imageio/npbm.imageio/npbminput.cc b/tools/imageio/npbm.imageio/npbminput.cc
@@ -404,12 +404,13 @@ void NpbmInput::parseGPHeader(filetype ftype)
     }
 
     images.emplace_back(ImageSpec(width, height, 1,
-                                     ftype == filetype::PPM ? 3 : 1, 8,
-                                     0, maxVal,
-                                     static_cast<khr_df_sample_datatype_qualifiers_e>(0),
-                                     KHR_DF_TRANSFER_ITU,
-                                     KHR_DF_PRIMARIES_BT709,
-                                     ftype == filetype::PPM
+                                  ImageSpec::Origin(ImageSpec::Origin::eLeft, ImageSpec::Origin::eTop),
+                                  ftype == filetype::PPM ? 3 : 1, 8,
+                                  0, maxVal,
+                                  static_cast<khr_df_sample_datatype_qualifiers_e>(0),
+                                  KHR_DF_TRANSFER_ITU,
+                                  KHR_DF_PRIMARIES_BT709,
+                                  ftype == filetype::PPM
                                           ? KHR_DF_MODEL_RGBSDA
                                           : KHR_DF_MODEL_YUVSDA),
                         ImageInputFormatType::npbm);
diff --git a/tools/imageio/png.imageio/pnginput.cc b/tools/imageio/png.imageio/pnginput.cc
@@ -227,7 +227,9 @@ PngInput::readHeader()
         break;
     }
 
-    images.emplace_back(ImageSpec(w, h, 1, componentCount,
+  images.emplace_back(ImageSpec(w, h, 1,
+                            ImageSpec::Origin(ImageSpec::Origin::eLeft, ImageSpec::Origin::eTop),
+                            componentCount,
                             bitDepth,
                             static_cast<khr_df_sample_datatype_qualifiers_e>(0),
                             KHR_DF_TRANSFER_UNSPECIFIED,
diff --git a/tools/ktx/command_create.cpp b/tools/ktx/command_create.cpp
