Commit 1ff18cc8 for libheif

commit 1ff18cc8b8609b2fd7f5ed6f7af9b07553611fce
Author: Dirk Farin <dirk.farin@gmail.com>
Date:   Mon Oct 5 17:59:44 2026 +0200

    Document that all tiles of a grid image need the same format

    The decoder refuses a grid image whose tiles differ in their colorspace,
    chroma format, bit depths or components (770b0d8d), for example when
    only some of the tiles have an alpha channel. v1.23.5 decoded such a
    grid. heif_context_add_image_tile() and heif_context_encode_grid() still
    write it without an error. heif-enc does so when it gets the tiles as
    separate files (-T) of which only some have an alpha channel.

    State the requirement in the documentation of both functions. Checking
    it when the tiles are added is left for v1.24.x (TODO).

diff --git a/libheif/api/libheif/heif_tiling.h b/libheif/api/libheif/heif_tiling.h
index 5ec68a9c..050649f2 100644
--- a/libheif/api/libheif/heif_tiling.h
+++ b/libheif/api/libheif/heif_tiling.h
@@ -99,6 +99,10 @@ heif_error heif_image_handle_decode_image_tile(const heif_image_handle* in_handl
 /**
  * @brief Encodes an array of images into a grid.
  *
+ * All tiles have to have the same size, colorspace, chroma format and bit depths, and they have
+ * to consist of the same components. For example, either all tiles have an alpha channel or
+ * none of them has. A grid whose tiles differ in this is refused when it is decoded.
+ *
  * @param ctx The file context
  * @param tiles User allocated array of images that will form the grid.
  * @param rows The number of rows in the grid.
@@ -126,6 +130,11 @@ heif_error heif_context_add_grid_image(heif_context* ctx,
                                        const heif_encoding_options* encoding_options,
                                        heif_image_handle** out_grid_image_handle);

+// Encodes an image and adds it as the tile at position (tile_x; tile_y) of a tiled image,
+// for example one that was created with heif_context_add_grid_image().
+// All tiles of an image have to have the same colorspace, chroma format and bit depths, and
+// they have to consist of the same components. For example, either all tiles have an alpha
+// channel or none of them has. A grid whose tiles differ in this is refused when it is decoded.
 LIBHEIF_API
 heif_error heif_context_add_image_tile(heif_context* ctx,
                                        heif_image_handle* tiled_image,
diff --git a/libheif/image-items/grid.cc b/libheif/image-items/grid.cc
index f297ec7c..76246831 100644
--- a/libheif/image-items/grid.cc
+++ b/libheif/image-items/grid.cc
@@ -939,6 +939,11 @@ Error ImageItem_Grid::add_image_tile(uint32_t tile_x, uint32_t tile_y,
                                      const std::shared_ptr<HeifPixelImage>& image,
                                      heif_encoder* encoder)
 {
+  // TODO(v1.24.x): return an error when the tile does not have the format of the tiles that
+  // were added before (colorspace, chroma format, bit depths and components, e.g. an alpha
+  // plane that only some of the tiles have). Such a grid is still written here, but the
+  // decoder refuses it (check_tile_format()).
+
   auto encodingResult = get_context()->encode_image(image,
                                             encoder,
                                             *m_tile_encoding_options,
@@ -999,6 +1004,9 @@ Result<std::shared_ptr<ImageItem_Grid>> ImageItem_Grid::add_and_encode_full_grid
 {
   std::shared_ptr<ImageItem_Grid> griditem;

+  // TODO(v1.24.x): return an error when the tiles do not all have the same format (see
+  // add_image_tile()).
+
   // Create ImageGrid

   ImageGrid grid;