Add gainmap_dimension_same_as_main_item_flag (#3446)

Read and write the bit(1) gainmap_dimension_same_as_main_item_flag of
the MinimizedImageBox, right after gainmap_flag. The
gainmap_width_minus1 and gainmap_height_minus1 fields are now only
present when the gain map and main image dimensions differ. This saves
13 or 29 bits when the gain map is as large as the main image, at the
cost of 1 bit otherwise.

This is the MinimizedImageBox syntax already implemented by libheif
(checked against v1.23.7). Files with a gain map written by previous
versions of libavif with AVIF_ENABLE_EXPERIMENTAL_MINI are
incompatible.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1322c76..311be50 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,10 @@
 * Keep the premultiplied alpha flag of a MinimizedImageBox. The one bit
   alpha_is_premultiplied value was stored in a field compared against the alpha
   item ID, so such an image used to decode as straight alpha.
+* Add gainmap_dimension_same_as_main_item_flag to the experimental
+  MinimizedImageBox. The gain map dimensions are only signaled when they differ
+  from the main image dimensions. Files with a gain map written by previous
+  versions of libavif with AVIF_ENABLE_EXPERIMENTAL_MINI are incompatible.
 
 ## [1.4.2] - 2026-05-26
 
diff --git a/src/read.c b/src/read.c
index 6d08c48..d2b1946 100644
--- a/src/read.c
+++ b/src/read.c
@@ -4333,12 +4333,20 @@
             AVIF_CHECKERR(brand != NULL, AVIF_RESULT_OUT_OF_MEMORY);
             memcpy(brand, "tmap", sizeof(avifBrand));
 
-            AVIF_CHECKERR(avifROStreamReadBitsU32(&s, &gainmapWidth, largeDimensionsFlag ? 15 : 7),
-                          AVIF_RESULT_BMFF_PARSE_FAILED); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_width_minus1;
-            ++gainmapWidth;
-            AVIF_CHECKERR(avifROStreamReadBitsU32(&s, &gainmapHeight, largeDimensionsFlag ? 15 : 7),
-                          AVIF_RESULT_BMFF_PARSE_FAILED); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_height_minus1;
-            ++gainmapHeight;
+            uint32_t gainmapDimensionSameAsMainItemFlag;
+            AVIF_CHECKERR(avifROStreamReadBitsU32(&s, &gainmapDimensionSameAsMainItemFlag, 1),
+                          AVIF_RESULT_BMFF_PARSE_FAILED); // bit(1) gainmap_dimension_same_as_main_item_flag;
+            if (gainmapDimensionSameAsMainItemFlag) {
+                gainmapWidth = width;
+                gainmapHeight = height;
+            } else {
+                AVIF_CHECKERR(avifROStreamReadBitsU32(&s, &gainmapWidth, largeDimensionsFlag ? 15 : 7),
+                              AVIF_RESULT_BMFF_PARSE_FAILED); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_width_minus1;
+                ++gainmapWidth;
+                AVIF_CHECKERR(avifROStreamReadBitsU32(&s, &gainmapHeight, largeDimensionsFlag ? 15 : 7),
+                              AVIF_RESULT_BMFF_PARSE_FAILED); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_height_minus1;
+                ++gainmapHeight;
+            }
             AVIF_CHECKERR(avifROStreamReadBitsU8(&s, &gainmapMatrixCoefficients, 8), AVIF_RESULT_BMFF_PARSE_FAILED); // bit(8) gainmap_matrix_coefficients;
             AVIF_CHECKERR(avifROStreamReadBitsU32(&s, &gainmapFullRange, 1), AVIF_RESULT_BMFF_PARSE_FAILED); // bit(1) gainmap_full_range_flag;
 
diff --git a/src/write.c b/src/write.c
index f6653d1..7843e8b 100644
--- a/src/write.c
+++ b/src/write.c
@@ -2917,8 +2917,12 @@
         if (hasGainmap) {
             const avifImage * tmap = encoder->data->altImageMetadata;
             const avifImage * gainmap = image->gainMap->image;
-            AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmap->width - 1, largeDimensionsFlag ? 15 : 7)); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_width_minus1;
-            AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmap->height - 1, largeDimensionsFlag ? 15 : 7)); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_height_minus1;
+            const avifBool gainmapDimensionSameAsMainItemFlag = gainmap->width == image->width && gainmap->height == image->height;
+            AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmapDimensionSameAsMainItemFlag, 1)); // bit(1) gainmap_dimension_same_as_main_item_flag;
+            if (!gainmapDimensionSameAsMainItemFlag) {
+                AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmap->width - 1, largeDimensionsFlag ? 15 : 7)); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_width_minus1;
+                AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmap->height - 1, largeDimensionsFlag ? 15 : 7)); // unsigned int(large_dimensions_flag ? 15 : 7) gainmap_height_minus1;
+            }
             AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmap->matrixCoefficients, 8)); // bit(8) gainmap_matrix_coefficients;
             AVIF_CHECKRES(avifRWStreamWriteBits(s, gainmap->yuvRange == AVIF_RANGE_FULL, 1)); // bit(1) gainmap_full_range_flag;
             const uint32_t gainmapChromaSubsampling = gainmap->yuvFormat == AVIF_PIXEL_FORMAT_YUV400   ? 0
diff --git a/tests/gtest/avifminitest.cc b/tests/gtest/avifminitest.cc
index 1517fa1..16c677d 100644
--- a/tests/gtest/avifminitest.cc
+++ b/tests/gtest/avifminitest.cc
@@ -245,5 +245,82 @@
 
 //------------------------------------------------------------------------------
 
+class AvifMinimizedImageBoxGainMapTest
+    : public testing::TestWithParam<
+          std::tuple</*width=*/int, /*height=*/int, /*gain_map_width=*/int,
+                     /*gain_map_height=*/int>> {};
+
+// The gain map dimensions are only signaled in a MinimizedImageBox when they
+// differ from the main image dimensions
+// (gainmap_dimension_same_as_main_item_flag).
+TEST_P(AvifMinimizedImageBoxGainMapTest, Dimensions) {
+  const int width = std::get<0>(GetParam());
+  const int height = std::get<1>(GetParam());
+  const int gain_map_width = std::get<2>(GetParam());
+  const int gain_map_height = std::get<3>(GetParam());
+
+  ImagePtr image = testutil::CreateImage(width, height, /*depth=*/8,
+                                         AVIF_PIXEL_FORMAT_YUV420,
+                                         AVIF_PLANES_YUV, AVIF_RANGE_FULL);
+  ASSERT_NE(image, nullptr);
+  testutil::FillImageGradient(image.get());
+  image->gainMap = avifGainMapCreate();
+  ASSERT_NE(image->gainMap, nullptr);
+  image->gainMap->image =
+      testutil::CreateImage(gain_map_width, gain_map_height, /*depth=*/8,
+                            AVIF_PIXEL_FORMAT_YUV400, AVIF_PLANES_YUV,
+                            AVIF_RANGE_FULL)
+          .release();
+  ASSERT_NE(image->gainMap->image, nullptr);
+  testutil::FillImageGradient(image->gainMap->image);
+
+  testutil::AvifRwData encoded;
+  EncoderPtr encoder(avifEncoderCreate());
+  ASSERT_NE(encoder, nullptr);
+  encoder->speed = AVIF_SPEED_FASTEST;
+  encoder->headerFormat = AVIF_HEADER_MINI;
+  ASSERT_EQ(avifEncoderWrite(encoder.get(), image.get(), &encoded),
+            AVIF_RESULT_OK);
+
+  DecoderPtr decoder(avifDecoderCreate());
+  ASSERT_NE(decoder, nullptr);
+  decoder->imageContentToDecode |= AVIF_IMAGE_CONTENT_GAIN_MAP;
+  ASSERT_EQ(avifDecoderSetIOMemory(decoder.get(), encoded.data, encoded.size),
+            AVIF_RESULT_OK);
+  // The dimensions are known from the MinimizedImageBox alone.
+  ASSERT_EQ(avifDecoderParse(decoder.get()), AVIF_RESULT_OK);
+  EXPECT_EQ(decoder->image->width, static_cast<uint32_t>(width));
+  EXPECT_EQ(decoder->image->height, static_cast<uint32_t>(height));
+  ASSERT_NE(decoder->image->gainMap, nullptr);
+  ASSERT_NE(decoder->image->gainMap->image, nullptr);
+  EXPECT_EQ(decoder->image->gainMap->image->width,
+            static_cast<uint32_t>(gain_map_width));
+  EXPECT_EQ(decoder->image->gainMap->image->height,
+            static_cast<uint32_t>(gain_map_height));
+
+  // The dimensions must match the decoded samples.
+  ASSERT_EQ(avifDecoderNextImage(decoder.get()), AVIF_RESULT_OK);
+  EXPECT_EQ(decoder->image->width, static_cast<uint32_t>(width));
+  EXPECT_EQ(decoder->image->height, static_cast<uint32_t>(height));
+  ASSERT_NE(decoder->image->gainMap, nullptr);
+  ASSERT_NE(decoder->image->gainMap->image, nullptr);
+  EXPECT_EQ(decoder->image->gainMap->image->width,
+            static_cast<uint32_t>(gain_map_width));
+  EXPECT_EQ(decoder->image->gainMap->image->height,
+            static_cast<uint32_t>(gain_map_height));
+}
+
+INSTANTIATE_TEST_SUITE_P(SmallDimensions, AvifMinimizedImageBoxGainMapTest,
+                         Combine(/*width=*/Values(8), /*height=*/Values(10),
+                                 /*gain_map_width=*/Values(1, 8),
+                                 /*gain_map_height=*/Values(5, 10)));
+
+INSTANTIATE_TEST_SUITE_P(LargeDimensions, AvifMinimizedImageBoxGainMapTest,
+                         Combine(/*width=*/Values(200), /*height=*/Values(150),
+                                 /*gain_map_width=*/Values(100, 200),
+                                 /*gain_map_height=*/Values(150)));
+
+//------------------------------------------------------------------------------
+
 }  // namespace
 }  // namespace avif