Commit 578ab47a for libheif

commit 578ab47a3dd998436435f6d5f690ec1179dabbce
Author: Dirk Farin <dirk.farin@gmail.com>
Date:   Mon Aug 24 01:42:19 2026 +0200

    improve documentation for image handle sizes

diff --git a/libheif/api/libheif/heif_image.h b/libheif/api/libheif/heif_image.h
index c7a7cc88..b21efed2 100644
--- a/libheif/api/libheif/heif_image.h
+++ b/libheif/api/libheif/heif_image.h
@@ -269,6 +269,13 @@ uint8_t* heif_image_get_plane(heif_image*,
 // The 'stride' parameter is often multiplied by the image height in the client application.
 // For very large images, this can lead to integer overflows and, consequently, illegal memory accesses.
 // The changed 'stride' parameter type eliminates this common error.
+//
+// Size any copy loop that reads or writes this plane from *this* channel's own
+// heif_image_get_width()/heif_image_get_height() and this 'out_stride' -- never from
+// heif_image_handle_get_width()/heif_image_handle_get_height() (the signalled item size, which
+// is not guaranteed to match the decoded plane) and never by assuming stride equals
+// width * bytes_per_pixel: the row may be padded, so require stride >= bytes_per_pixel * width
+// and use the returned stride for row-to-row offsets.
 LIBHEIF_API
 const uint8_t* heif_image_get_plane_readonly2(const heif_image*,
                                               heif_channel channel,
diff --git a/libheif/api/libheif/heif_image_handle.h b/libheif/api/libheif/heif_image_handle.h
index 724c1a2b..b3054b86 100644
--- a/libheif/api/libheif/heif_image_handle.h
+++ b/libheif/api/libheif/heif_image_handle.h
@@ -54,6 +54,14 @@ LIBHEIF_API
 heif_item_id heif_image_handle_get_item_id(const heif_image_handle* handle);

 /** Get the image width.
+ *
+ * This is the *signalled* size declared for the item, available without decoding. It is not
+ * guaranteed to match the size of the image you get back from heif_decode_image(): do not use
+ * this value to allocate or bound access to a decoded pixel buffer. Once you have decoded the
+ * image, use heif_image_get_width(heif_image*, heif_channel) (or heif_image_get_primary_width())
+ * for the actual plane size, and size any copy loop from that together with the stride returned
+ * by heif_image_get_plane_readonly2() / heif_image_get_plane2() -- never from this handle value
+ * or from width * bytes_per_pixel.
  *
  * If 'handle' is invalid (NULL) or if the image size exceeds the range of `int`, 0 is returned.
  */
@@ -61,6 +69,14 @@ LIBHEIF_API
 int heif_image_handle_get_width(const heif_image_handle* handle);

 /** Get the image height.
+ *
+ * This is the *signalled* size declared for the item, available without decoding. It is not
+ * guaranteed to match the size of the image you get back from heif_decode_image(): do not use
+ * this value to allocate or bound access to a decoded pixel buffer. Once you have decoded the
+ * image, use heif_image_get_height(heif_image*, heif_channel) (or heif_image_get_primary_height())
+ * for the actual plane size, and size any copy loop from that together with the stride returned
+ * by heif_image_get_plane_readonly2() / heif_image_get_plane2() -- never from this handle value
+ * or from height * stride.
  *
  * If 'handle' is invalid (NULL) or if the image size exceeds the range of `int`, 0 is returned.
  */