Commit add01ddc for libheif

commit add01ddc3f6a08af4cdb327bbe9fa11dfc464864
Author: Dirk Farin <dirk.farin@gmail.com>
Date:   Thu Jun 25 17:42:53 2026 +0200

    add comment about mc=0 preferred colorspace output

diff --git a/libheif/api/libheif/heif_decoding.h b/libheif/api/libheif/heif_decoding.h
index 34c9e4fc..6723bb83 100644
--- a/libheif/api/libheif/heif_decoding.h
+++ b/libheif/api/libheif/heif_decoding.h
@@ -200,6 +200,9 @@ const char* heif_decoder_descriptor_get_id_name(const heif_decoder_descriptor*);
 //
 // If colorspace or chroma is set to heif_colorspace_undefined or heif_chroma_undefined,
 // respectively, the original colorspace is taken.
+// Note: for images with matrix_coefficients=0 the "original colorspace" is YCbCr
+// (tagged with matrix_coefficients=0); this is not specified and may change in a future
+// version. See heif_image_handle_get_preferred_decoding_colorspace().
 // Decoding options may be NULL. If you want to supply options, always use
 // heif_decoding_options_alloc() to get the structure.
 LIBHEIF_API
diff --git a/libheif/api/libheif/heif_image_handle.h b/libheif/api/libheif/heif_image_handle.h
index d883bfcc..724c1a2b 100644
--- a/libheif/api/libheif/heif_image_handle.h
+++ b/libheif/api/libheif/heif_image_handle.h
@@ -89,6 +89,15 @@ int heif_image_handle_get_chroma_bits_per_pixel(const heif_image_handle*);
 // It may also return *_undefined if the file misses relevant information to determine this without decoding.
 // These are only proposed values that avoid colorspace conversions as much as possible.
 // You can still request the output in your preferred colorspace, but this may involve an internal conversion.
+//
+// Note on matrix_coefficients=0 (H.273 identity, i.e. RGB carried in YCbCr planes):
+// for such images this function proposes RGB. However, heif_decode_image() called with
+// heif_colorspace_undefined currently returns the image still tagged as YCbCr (with
+// matrix_coefficients=0). That tagging is self-consistent. Converting it to RGB applies
+// the identity mapping and yields correct colors, so request heif_colorspace_RGB
+// explicitly if you need RGB output. This exact behavior is not specified and may change.
+// A later version may return RGB directly when decoding with an undefined colorspace.
+// See heif_decode_image().
 LIBHEIF_API
 heif_error heif_image_handle_get_preferred_decoding_colorspace(const heif_image_handle* image_handle,
                                                                heif_colorspace* out_colorspace,