@img/sharp-libvips-dev 0.0.1 → 0.0.2

package/include/libheif/heif.h

@@ -1,6 +1,6 @@
 /*
  * HEIF codec.
- * Copyright (c) 2017 struktur AG, Dirk Farin <farin@struktur.de>
+ * Copyright (c) 2017-2023 Dirk Farin <dirk.farin@gmail.com>
  *
  * This file is part of libheif.
  *
@@ -25,6 +25,11 @@
 extern "C" {
 #endif
 
+/*! \file heif.h
+ *
+ * Public API for libheif.
+*/
+
 #include <stddef.h>
 #include <stdint.h>
 
@@ -318,20 +323,153 @@ struct heif_error
   const char* message;
 };
 
+// Default success return value. Intended for use in user-supplied callback functions.
+LIBHEIF_API extern const struct heif_error heif_error_success;
+
 
 typedef uint32_t heif_item_id;
 typedef uint32_t heif_property_id;
 
 
 
-// ========================= library initialization ======================
+// ========================= enum types ======================
 
-// You should call heif_init() when you start using libheif and heif_deinit() when you are finished.
-// These calls are reference counted. Each call to heif_init() should be matched by one call to heif_deinit().
-// For backwards compatibility, it is not really necessary to call heif_init(), but if you don't, the plugins
-// registered by default may not be freed correctly.
-// However, this should not be mixed, i.e. one part of your program does use heif_init()/heif_deinit() and another doesn't.
-// If in doubt, enclose everything with init/deinit.
+/**
+ * libheif known compression formats.
+ */
+enum heif_compression_format
+{
+  /**
+   * Unspecified / undefined compression format.
+   *
+   * This is used to mean "no match" or "any decoder" for some parts of the
+   * API. It does not indicate a specific compression format.
+   */
+  heif_compression_undefined = 0,
+  /**
+   * HEVC compression, used for HEIC images.
+   *
+   * This is equivalent to H.265.
+  */
+  heif_compression_HEVC = 1,
+  /**
+   * AVC compression. (Currently unused in libheif.)
+   *
+   * The compression is defined in ISO/IEC 14496-10. This is equivalent to H.264.
+   *
+   * The encapsulation is defined in ISO/IEC 23008-12:2022 Annex E.
+   */
+  heif_compression_AVC = 2,
+  /**
+   * JPEG compression.
+   *
+   * The compression format is defined in ISO/IEC 10918-1. The encapsulation
+   * of JPEG is specified in ISO/IEC 23008-12:2022 Annex H.
+  */
+  heif_compression_JPEG = 3,
+  /**
+   * AV1 compression, used for AVIF images.
+   *
+   * The compression format is provided at https://aomediacodec.github.io/av1-spec/
+   *
+   * The encapsulation is defined in https://aomediacodec.github.io/av1-avif/
+   */
+  heif_compression_AV1 = 4,
+  /**
+   * VVC compression. (Currently unused in libheif.)
+   *
+   * The compression format is defined in ISO/IEC 23090-3. This is equivalent to H.266.
+   *
+   * The encapsulation is defined in ISO/IEC 23008-12:2022 Annex L.
+   */
+  heif_compression_VVC = 5,
+  /**
+   * EVC compression. (Currently unused in libheif.)
+   *
+   * The compression format is defined in ISO/IEC 23094-1. This is equivalent to H.266.
+   *
+   * The encapsulation is defined in ISO/IEC 23008-12:2022 Annex M.
+   */
+  heif_compression_EVC = 6,
+  /**
+   * JPEG 2000 compression. (Currently unused in libheif.)
+   *
+   * The encapsulation of JPEG 2000 is specified in ISO/IEC 15444-16:2021.
+   * The core encoding is defined in ISO/IEC 15444-1, or ITU-T T.800.
+  */
+  heif_compression_JPEG2000 = 7,
+  /**
+   * Uncompressed encoding.
+   *
+   * This is defined in ISO/IEC 23001-17:2023 (Draft International Standard).
+  */
+  heif_compression_uncompressed = 8,
+  /**
+   * Mask image encoding.
+   *
+   * See ISO/IEC 23008-12:2022 Section 6.10.2
+   */
+  heif_compression_mask = 9
+};
+
+enum heif_chroma
+{
+  heif_chroma_undefined = 99,
+  heif_chroma_monochrome = 0,
+  heif_chroma_420 = 1,
+  heif_chroma_422 = 2,
+  heif_chroma_444 = 3,
+  heif_chroma_interleaved_RGB = 10,
+  heif_chroma_interleaved_RGBA = 11,
+  heif_chroma_interleaved_RRGGBB_BE = 12,   // HDR, big endian.
+  heif_chroma_interleaved_RRGGBBAA_BE = 13, // HDR, big endian.
+  heif_chroma_interleaved_RRGGBB_LE = 14,   // HDR, little endian.
+  heif_chroma_interleaved_RRGGBBAA_LE = 15  // HDR, little endian.
+};
+
+// DEPRECATED ENUM NAMES
+#define heif_chroma_interleaved_24bit  heif_chroma_interleaved_RGB
+#define heif_chroma_interleaved_32bit  heif_chroma_interleaved_RGBA
+
+
+enum heif_colorspace
+{
+  heif_colorspace_undefined = 99,
+
+  // heif_colorspace_YCbCr should be used with one of these heif_chroma values:
+  // * heif_chroma_444
+  // * heif_chroma_422
+  // * heif_chroma_420
+  heif_colorspace_YCbCr = 0,
+
+  // heif_colorspace_RGB should be used with one of these heif_chroma values:
+  // * heif_chroma_444 (for planar RGB)
+  // * heif_chroma_interleaved_RGB
+  // * heif_chroma_interleaved_RGBA
+  // * heif_chroma_interleaved_RRGGBB_BE
+  // * heif_chroma_interleaved_RRGGBBAA_BE
+  // * heif_chroma_interleaved_RRGGBB_LE
+  // * heif_chroma_interleaved_RRGGBBAA_LE
+  heif_colorspace_RGB = 1,
+
+  // heif_colorspace_monochrome should only be used with heif_chroma = heif_chroma_monochrome
+  heif_colorspace_monochrome = 2
+};
+
+enum heif_channel
+{
+  heif_channel_Y = 0,
+  heif_channel_Cb = 1,
+  heif_channel_Cr = 2,
+  heif_channel_R = 3,
+  heif_channel_G = 4,
+  heif_channel_B = 5,
+  heif_channel_Alpha = 6,
+  heif_channel_interleaved = 10
+};
+
+
+// ========================= library initialization ======================
 
 struct heif_init_params
 {
@@ -341,12 +479,26 @@ struct heif_init_params
 };
 
 
+// You should call heif_init() when you start using libheif and heif_deinit() when you are finished.
+// These calls are reference counted. Each call to heif_init() should be matched by one call to heif_deinit().
+//
+// For backwards compatibility, it is not really necessary to call heif_init(), but some library memory objects
+// will never be freed if you do not call heif_init()/heif_deinit().
+//
+// heif_init() will load the external modules installed in the default plugin path. Thus, you need it when you
+// want to load external plugins from the default path.
+// Codec plugins that are compiled into the library directly (selected by the compile-time parameters of libheif)
+// will be available even without heif_init().
+//
+// Make sure that you don't have one part of your program use heif_init()/heif_deinit() and another part that doesn't
+// use it as the latter may try to use an uninitialized library. If in doubt, enclose everything with init/deinit.
+
 // You may pass nullptr to get default parameters. Currently, no parameters are supported.
 LIBHEIF_API
 struct heif_error heif_init(struct heif_init_params*);
 
 LIBHEIF_API
-void heif_deinit();
+void heif_deinit(void);
 
 
 // --- Plugins are currently only supported on Unix platforms.
@@ -377,6 +529,15 @@ struct heif_error heif_load_plugins(const char* directory,
 LIBHEIF_API
 struct heif_error heif_unload_plugin(const struct heif_plugin_info* plugin);
 
+// Get a NULL terminated array of the plugin directories that are searched by libheif.
+// This includes the paths specified in the environment variable LIBHEIF_PLUGIN_PATHS and the built-in path
+// (if not overridden by the environment variable).
+LIBHEIF_API
+const char*const* heif_get_plugin_directories(void);
+
+LIBHEIF_API
+void heif_free_plugin_directories(const char*const*);
+
 
 // ========================= file type check ======================
 
@@ -415,6 +576,8 @@ enum heif_brand
   heif_vvis, // VVC sequence
   heif_evbi, // EVC image
   heif_evbs, // EVC sequence
+  heif_j2ki, // JPEG2000 image
+  heif_j2is, // JPEG2000 image sequence
 };
 
 // input data should be at least 12 bytes
@@ -425,24 +588,210 @@ enum heif_brand heif_main_brand(const uint8_t* data, int len);
 
 typedef uint32_t heif_brand2;
 
-#define heif_brand2_heic   heif_fourcc('h','e','i','c') // HEIF image with h265
-#define heif_brand2_heix   heif_fourcc('h','e','i','x') // 10bit images, or anything that uses h265 with range extension
-#define heif_brand2_hevc   heif_fourcc('h','e','v','c') // image sequences
-#define heif_brand2_hevx   heif_fourcc('h','e','v','x') // HDR image sequence
-#define heif_brand2_heim   heif_fourcc('h','e','i','m') // multiview
-#define heif_brand2_heis   heif_fourcc('h','e','i','s') // scalable
-#define heif_brand2_hevm   heif_fourcc('h','e','v','m') // multiview sequence
-#define heif_brand2_hevs   heif_fourcc('h','e','v','s') // scalable sequence
-#define heif_brand2_avif   heif_fourcc('a','v','i','f') // AVIF image (AV1)
+/**
+ * HEVC image (`heic`) brand.
+ *
+ * Image conforms to HEVC (H.265) Main or Main Still profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.1.
+ */
+#define heif_brand2_heic   heif_fourcc('h','e','i','c')
+
+/**
+ * HEVC image (`heix`) brand.
+ *
+ * Image conforms to HEVC (H.265) Main 10 profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.1.
+ */
+#define heif_brand2_heix   heif_fourcc('h','e','i','x')
+
+/**
+ * HEVC image sequence (`hevc`) brand.
+ *
+ * Image sequence conforms to HEVC (H.265) Main profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.2.
+ */
+#define heif_brand2_hevc   heif_fourcc('h','e','v','c')
+
+/**
+ * HEVC image sequence (`hevx`) brand.
+ *
+ * Image sequence conforms to HEVC (H.265) Main 10 profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.2.
+ */
+#define heif_brand2_hevx   heif_fourcc('h','e','v','x')
+
+/**
+ * HEVC layered image (`heim`) brand.
+ *
+ * Image layers conform to HEVC (H.265) Main or Multiview Main profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.3.
+ */
+#define heif_brand2_heim   heif_fourcc('h','e','i','m')
+
+/**
+ * HEVC layered image (`heis`) brand.
+ *
+ * Image layers conform to HEVC (H.265) Main, Main 10, Scalable Main
+ * or Scalable Main 10 profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.3.
+ */
+#define heif_brand2_heis   heif_fourcc('h','e','i','s')
+
+/**
+ * HEVC layered image sequence (`hevm`) brand.
+ *
+ * Image sequence layers conform to HEVC (H.265) Main or Multiview Main profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.4.
+ */
+#define heif_brand2_hevm   heif_fourcc('h','e','v','m')
+
+/**
+ * HEVC layered image sequence (`hevs`) brand.
+ *
+ * Image sequence layers conform to HEVC (H.265) Main, Main 10, Scalable Main
+ * or Scalable Main 10 profile.
+ *
+ * See ISO/IEC 23008-12:2022 Section B.4.4.
+ */
+#define heif_brand2_hevs   heif_fourcc('h','e','v','s')
+
+/**
+ * AV1 image (`avif`) brand.
+ *
+ * See https://aomediacodec.github.io/av1-avif/#image-and-image-collection-brand
+ */
+#define heif_brand2_avif   heif_fourcc('a','v','i','f')
+
+/**
+ * AV1 image sequence (`avis`) brand.
+ *
+ * See https://aomediacodec.github.io/av1-avif/#image-sequence-brand
+ */
 #define heif_brand2_avis   heif_fourcc('a','v','i','s') // AVIF sequence
-#define heif_brand2_mif1   heif_fourcc('m','i','f','1') // image, any coding algorithm
-#define heif_brand2_mif2   heif_fourcc('m','i','f','2') // image, any coding algorithm
-#define heif_brand2_msf1   heif_fourcc('m','s','f','1') // sequence, any coding algorithm
-#define heif_brand2_vvic   heif_fourcc('v','v','i','c') // VVC image
-#define heif_brand2_vvis   heif_fourcc('v','v','i','s') // VVC sequence
-#define heif_brand2_evbi   heif_fourcc('e','v','b','i') // EVC image
-#define heif_brand2_evbs   heif_fourcc('e','v','b','s') // EVC sequence
 
+/**
+ * HEIF image structural brand (`mif1`).
+ *
+ * This does not imply a specific coding algorithm.
+ *
+ * See ISO/IEC 23008-12:2022 Section 10.2.2.
+ */
+#define heif_brand2_mif1   heif_fourcc('m','i','f','1')
+
+/**
+ * HEIF image structural brand (`mif2`).
+ *
+ * This does not imply a specific coding algorithm. `mif2` extends
+ * the requirements of `mif1` to include the `rref` and `iscl` item
+ * properties.
+ *
+ * See ISO/IEC 23008-12:2022 Section 10.2.3.
+ */
+#define heif_brand2_mif2   heif_fourcc('m','i','f','2')
+
+/**
+ * HEIF image sequence structural brand (`msf1`).
+ *
+ * This does not imply a specific coding algorithm.
+ *
+ * See ISO/IEC 23008-12:2022 Section 10.3.1.
+ */
+#define heif_brand2_msf1   heif_fourcc('m','s','f','1')
+
+/**
+ * VVC image (`vvic`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Section L.4.1.
+ */
+#define heif_brand2_vvic   heif_fourcc('v','v','i','c')
+
+/**
+ * VVC image sequence (`vvis`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Section L.4.2.
+ */
+#define heif_brand2_vvis   heif_fourcc('v','v','i','s')
+
+/**
+ * EVC baseline image (`evbi`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Section M.4.1.
+ */
+#define heif_brand2_evbi   heif_fourcc('e','v','b','i')
+
+/**
+ * EVC main profile image (`evmi`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Section M.4.2.
+ */
+#define heif_brand2_evmi   heif_fourcc('e','v','m','i')
+
+/**
+ * EVC baseline image sequence (`evbs`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Section M.4.3.
+ */
+#define heif_brand2_evbs   heif_fourcc('e','v','b','s')
+
+/**
+ * EVC main profile image sequence (`evms`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Section M.4.4.
+ */
+#define heif_brand2_evms   heif_fourcc('e','v','m','s')
+
+/**
+ * JPEG image (`jpeg`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Annex H.4
+ */
+#define heif_brand2_jpeg   heif_fourcc('j','p','e','g')
+
+/**
+ * JPEG image sequence (`jpgs`) brand.
+ *
+ * See ISO/IEC 23008-12:2022 Annex H.5
+ */
+#define heif_brand2_jpgs   heif_fourcc('j','p','g','s')
+
+/**
+ * JPEG 2000 image (`j2ki`) brand.
+ *
+ * See ISO/IEC 15444-16:2021 Section 6.5 
+ */
+#define heif_brand2_j2ki   heif_fourcc('j','2','k','i')
+
+/**
+ * JPEG 2000 image sequence (`j2is`) brand.
+ *
+ * See ISO/IEC 15444-16:2021 Section 7.6
+ */
+#define heif_brand2_j2is   heif_fourcc('j','2','i','s')
+
+/**
+ * Multi-image application format (MIAF) brand.
+ *
+ * This is HEIF with additional constraints for interoperability.
+ *
+ * See ISO/IEC 23000-22.
+ */
+#define heif_brand2_miaf   heif_fourcc('m','i','a','f')
+
+/**
+ * Single picture file brand.
+ *
+ * This is a compatible brand indicating the file contains a single intra-coded picture.
+ *
+ * See ISO/IEC 23008-12:2022 Section 10.2.5.
+*/
+#define heif_brand2_1pic   heif_fourcc('1','p','i','c')
 
 // input data should be at least 12 bytes
 LIBHEIF_API
@@ -527,7 +876,7 @@ struct heif_reader
   // --- version 1 functions ---
   int64_t (* get_position)(void* userdata);
 
-  // The functions read(), and seek() return 0 on success.
+  // The functions read(), and seek() return heif_error_ok on success.
   // Generally, libheif will make sure that we do not read past the file size.
   int (* read)(void* data,
                size_t size,
@@ -600,7 +949,7 @@ LIBHEIF_API
 struct heif_error heif_context_get_primary_image_handle(struct heif_context* ctx,
                                                         struct heif_image_handle**);
 
-// Get the handle for a specific top-level image from an image ID.
+// Get the image handle for a known image ID.
 LIBHEIF_API
 struct heif_error heif_context_get_image_handle(struct heif_context* ctx,
                                                 heif_item_id id,
@@ -667,6 +1016,15 @@ int heif_image_handle_get_luma_bits_per_pixel(const struct heif_image_handle*);
 LIBHEIF_API
 int heif_image_handle_get_chroma_bits_per_pixel(const struct heif_image_handle*);
 
+// Return the colorspace that libheif proposes to use for decoding.
+// Usually, these will be either YCbCr or Monochrome, but it may also propose RGB for images
+// encoded with matrix_coefficients=0.
+// It may also return *_undefined if the file misses relevant information to determine this without decoding.
+LIBHEIF_API
+struct heif_error heif_image_handle_get_preferred_decoding_colorspace(const struct heif_image_handle* image_handle,
+                                                                      enum heif_colorspace* out_colorspace,
+                                                                      enum heif_chroma* out_chroma);
+
 // Get the image width from the 'ispe' box. This is the original image size without
 // any transformations applied to it. Do not use this unless you know exactly what
 // you are doing.
@@ -676,6 +1034,17 @@ int heif_image_handle_get_ispe_width(const struct heif_image_handle* handle);
 LIBHEIF_API
 int heif_image_handle_get_ispe_height(const struct heif_image_handle* handle);
 
+// This gets the context associated with the image handle.
+// Note that you have to release the returned context with heif_context_free() in any case.
+//
+// This means: when you have several image-handles that originate from the same file and you get the
+// context of each of them, the returned pointer may be different even though it refers to the same
+// logical context. You have to call heif_context_free() on all those context pointers.
+// After you freed a context pointer, you can still use the context through a different pointer that you
+// might have acquired from elsewhere.
+LIBHEIF_API
+struct heif_context* heif_image_handle_get_context(const struct heif_image_handle* handle);
+
 
 // ------------------------- depth images -------------------------
 
@@ -840,6 +1209,10 @@ struct heif_error heif_image_handle_get_metadata(const struct heif_image_handle*
                                                  heif_item_id metadata_id,
                                                  void* out_data);
 
+// Only valid for item type == "uri ", an absolute URI
+LIBHEIF_API
+const char* heif_image_handle_get_metadata_item_uri_type(const struct heif_image_handle* handle,
+                                                         heif_item_id metadata_id);
 
 // ------------------------- color profiles -------------------------
 
@@ -963,7 +1336,7 @@ struct heif_error heif_image_handle_get_nclx_color_profile(const struct heif_ima
 // Do not fill values for higher versions as these might be outside the allocated structure size.
 // May return NULL.
 LIBHEIF_API
-struct heif_color_profile_nclx* heif_nclx_color_profile_alloc();
+struct heif_color_profile_nclx* heif_nclx_color_profile_alloc(void);
 
 LIBHEIF_API
 void heif_nclx_color_profile_free(struct heif_color_profile_nclx* nclx_profile);
@@ -984,109 +1357,6 @@ struct heif_error heif_image_get_nclx_color_profile(const struct heif_image* ima
                                                     struct heif_color_profile_nclx** out_data);
 
 
-// ------------------------- item properties -------------------------
-
-enum heif_item_property_type
-{
-//  heif_item_property_unknown = -1,
-  heif_item_property_type_invalid = 0,
-  heif_item_property_type_user_description = heif_fourcc('u', 'd', 'e', 's'),
-  heif_item_property_type_transform_mirror = heif_fourcc('i', 'm', 'i', 'r'),
-  heif_item_property_type_transform_rotation = heif_fourcc('i', 'r', 'o', 't'),
-  heif_item_property_type_transform_crop = heif_fourcc('c', 'l', 'a', 'p'),
-  heif_item_property_type_image_size = heif_fourcc('i', 's', 'p', 'e')
-};
-
-// Get the heif_property_id for a heif_item_id.
-// You may specify which property 'type' you want to receive.
-// If you specify 'heif_item_property_type_invalid', all properties associated to that item are returned.
-// The number of properties is returned, which are not more than 'count' if (out_list != nullptr).
-// By setting out_list==nullptr, you can query the number of properties, 'count' is ignored.
-LIBHEIF_API
-int heif_item_get_properties_of_type(const struct heif_context* context,
-                                     heif_item_id id,
-                                     enum heif_item_property_type type,
-                                     heif_property_id* out_list,
-                                     int count);
-
-// Returns all transformative properties in the correct order.
-// This includes "irot", "imir", "clap".
-// The number of properties is returned, which are not more than 'count' if (out_list != nullptr).
-// By setting out_list==nullptr, you can query the number of properties, 'count' is ignored.
-LIBHEIF_API
-int heif_item_get_transformation_properties(const struct heif_context* context,
-                                            heif_item_id id,
-                                            heif_property_id* out_list,
-                                            int count);
-
-LIBHEIF_API
-enum heif_item_property_type heif_item_get_property_type(const struct heif_context* context,
-                                                         heif_item_id id,
-                                                         heif_property_id property_id);
-
-// The strings are managed by libheif. They will be deleted in heif_property_user_description_release().
-struct heif_property_user_description
-{
-  int version;
-
-  // version 1
-
-  const char* lang;
-  const char* name;
-  const char* description;
-  const char* tags;
-};
-
-// Get the "udes" user description property content.
-// Undefined strings are returned as empty strings.
-LIBHEIF_API
-struct heif_error heif_item_get_property_user_description(const struct heif_context* context,
-                                                          heif_item_id itemId,
-                                                          heif_property_id propertyId,
-                                                          struct heif_property_user_description** out);
-
-// Add a "udes" user description property to the item.
-// If any string pointers are NULL, an empty string will be used instead.
-LIBHEIF_API
-struct heif_error heif_item_add_property_user_description(const struct heif_context* context,
-                                                          heif_item_id itemId,
-                                                          const struct heif_property_user_description* description,
-                                                          heif_property_id* out_propertyId);
-
-// Release all strings and the object itself.
-// Only call for objects that you received from heif_item_get_property_user_description().
-LIBHEIF_API
-void heif_property_user_description_release(struct heif_property_user_description*);
-
-enum heif_transform_mirror_direction
-{
-  heif_transform_mirror_direction_vertical = 0,    // flip image vertically
-  heif_transform_mirror_direction_horizontal = 1   // flip image horizontally
-};
-
-LIBHEIF_API
-enum heif_transform_mirror_direction heif_item_get_property_transform_mirror(const struct heif_context* context,
-                                                                             heif_item_id itemId,
-                                                                             heif_property_id propertyId);
-
-// Returns only 0, 90, 180, or 270 angle values.
-// Returns -1 in case of error (but it will only return an error in case of wrong usage).
-LIBHEIF_API
-int heif_item_get_property_transform_rotation_ccw(const struct heif_context* context,
-                                                  heif_item_id itemId,
-                                                  heif_property_id propertyId);
-
-// Returns the number of pixels that should be removed from the four edges.
-// Because of the way this data is stored, you have to pass the image size at the moment of the crop operation
-// to compute the cropped border sizes.
-LIBHEIF_API
-void heif_item_get_property_transform_crop_borders(const struct heif_context* context,
-                                                   heif_item_id itemId,
-                                                   heif_property_id propertyId,
-                                                   int image_width, int image_height,
-                                                   int* left, int* top, int* right, int* bottom);
-
-
 // ========================= heif_image =========================
 
 // An heif_image contains a decoded pixel image in various colorspaces, chroma formats,
@@ -1098,76 +1368,6 @@ void heif_item_get_property_transform_crop_borders(const struct heif_context* co
 
 // Planar RGB images are specified as heif_colorspace_RGB / heif_chroma_444.
 
-enum heif_compression_format
-{
-  heif_compression_undefined = 0,
-  heif_compression_HEVC = 1,
-  heif_compression_AVC = 2,
-  heif_compression_JPEG = 3,
-  heif_compression_AV1 = 4,
-  heif_compression_VVC = 5,
-  heif_compression_EVC = 6,
-  heif_compression_JPEG2000 = 7,  // ISO/IEC 15444-16:2021
-  heif_compression_uncompressed = 8 // ISO/IEC 23001-17:2023
-};
-
-enum heif_chroma
-{
-  heif_chroma_undefined = 99,
-  heif_chroma_monochrome = 0,
-  heif_chroma_420 = 1,
-  heif_chroma_422 = 2,
-  heif_chroma_444 = 3,
-  heif_chroma_interleaved_RGB = 10,
-  heif_chroma_interleaved_RGBA = 11,
-  heif_chroma_interleaved_RRGGBB_BE = 12,   // HDR, big endian.
-  heif_chroma_interleaved_RRGGBBAA_BE = 13, // HDR, big endian.
-  heif_chroma_interleaved_RRGGBB_LE = 14,   // HDR, little endian.
-  heif_chroma_interleaved_RRGGBBAA_LE = 15  // HDR, little endian.
-};
-
-// DEPRECATED ENUM NAMES
-#define heif_chroma_interleaved_24bit  heif_chroma_interleaved_RGB
-#define heif_chroma_interleaved_32bit  heif_chroma_interleaved_RGBA
-
-
-enum heif_colorspace
-{
-  heif_colorspace_undefined = 99,
-
-  // heif_colorspace_YCbCr should be used with one of these heif_chroma values:
-  // * heif_chroma_444
-  // * heif_chroma_422
-  // * heif_chroma_420
-  heif_colorspace_YCbCr = 0,
-
-  // heif_colorspace_RGB should be used with one of these heif_chroma values:
-  // * heif_chroma_444 (for planar RGB)
-  // * heif_chroma_interleaved_RGB
-  // * heif_chroma_interleaved_RGBA
-  // * heif_chroma_interleaved_RRGGBB_BE
-  // * heif_chroma_interleaved_RRGGBBAA_BE
-  // * heif_chroma_interleaved_RRGGBB_LE
-  // * heif_chroma_interleaved_RRGGBBAA_LE
-  heif_colorspace_RGB = 1,
-
-  // heif_colorspace_monochrome should only be used with heif_chroma = heif_chroma_monochrome
-  heif_colorspace_monochrome = 2
-};
-
-enum heif_channel
-{
-  heif_channel_Y = 0,
-  heif_channel_Cb = 1,
-  heif_channel_Cr = 2,
-  heif_channel_R = 3,
-  heif_channel_G = 4,
-  heif_channel_B = 5,
-  heif_channel_Alpha = 6,
-  heif_channel_interleaved = 10
-};
-
-
 enum heif_progress_step
 {
   heif_progress_step_total = 0,
@@ -1200,7 +1400,12 @@ struct heif_color_conversion_options
   enum heif_chroma_downsampling_algorithm preferred_chroma_downsampling_algorithm;
   enum heif_chroma_upsampling_algorithm preferred_chroma_upsampling_algorithm;
 
-  // When set to 'false', libheif may also use a different algorithm if the preferred one is not available.
+  // When set to 'false' libheif may also use a different algorithm if the preferred one is not available
+  // or using a different algorithm is computationally less complex. Note that currently (v1.17.0) this
+  // means that for RGB input it will usually choose nearest-neighbor sampling because this is computationally
+  // the simplest.
+  // Set this field to 'true' if you want to make sure that the specified algorithm is used even
+  // at the cost of slightly higher computation times.
   uint8_t only_use_preferred_chroma_algorithm;
 };
 
@@ -1251,7 +1456,7 @@ struct heif_decoding_options
 // Note: you should always get the decoding options through this function since the
 // option structure may grow in size in future versions.
 LIBHEIF_API
-struct heif_decoding_options* heif_decoding_options_alloc();
+struct heif_decoding_options* heif_decoding_options_alloc(void);
 
 LIBHEIF_API
 void heif_decoding_options_free(struct heif_decoding_options*);
@@ -1278,22 +1483,47 @@ enum heif_colorspace heif_image_get_colorspace(const struct heif_image*);
 LIBHEIF_API
 enum heif_chroma heif_image_get_chroma_format(const struct heif_image*);
 
-// Get width of the given image channel in pixels. Returns -1 if a non-existing
-// channel was given.
+/**
+ * Get the width of a specified image channel.
+ *
+ * @param img the image to get the width for
+ * @param channel the channel to select
+ * @return the width of the channel in pixels, or -1 the channel does not exist in the image
+ */
 LIBHEIF_API
-int heif_image_get_width(const struct heif_image*, enum heif_channel channel);
+int heif_image_get_width(const struct heif_image* img, enum heif_channel channel);
 
-// Get height of the given image channel in pixels. Returns -1 if a non-existing
-// channel was given.
+/**
+ * Get the height of a specified image channel.
+ *
+ * @param img the image to get the height for
+ * @param channel the channel to select
+ * @return the height of the channel in pixels, or -1 the channel does not exist in the image
+ */
 LIBHEIF_API
-int heif_image_get_height(const struct heif_image*, enum heif_channel channel);
+int heif_image_get_height(const struct heif_image* img, enum heif_channel channel);
 
-// Get the width of the main channel (Y in YCbCr, or any in RGB).
+/**
+ * Get the width of the main channel.
+ *
+ * This is the Y channel in YCbCr or mono, or any in RGB.
+ *
+ * @param img the image to get the primary width for
+ * @return the width in pixels
+ */
 LIBHEIF_API
-int heif_image_get_primary_width(const struct heif_image*);
+int heif_image_get_primary_width(const struct heif_image* img);
 
+/**
+ * Get the height of the main channel.
+ *
+ * This is the Y channel in YCbCr or mono, or any in RGB.
+ *
+ * @param img the image to get the primary height for
+ * @return the height in pixels
+ */
 LIBHEIF_API
-int heif_image_get_primary_height(const struct heif_image*);
+int heif_image_get_primary_height(const struct heif_image* img);
 
 LIBHEIF_API
 struct heif_error heif_image_crop(struct heif_image* img,
@@ -1778,7 +2008,7 @@ struct heif_encoding_options
 };
 
 LIBHEIF_API
-struct heif_encoding_options* heif_encoding_options_alloc();
+struct heif_encoding_options* heif_encoding_options_alloc(void);
 
 LIBHEIF_API
 void heif_encoding_options_free(struct heif_encoding_options*);
@@ -1921,170 +2151,6 @@ LIBHEIF_API
 int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor*);
 
 
-// --- region items and annotations
-
-// See ISO/IEC 23008-12:2022 Section 6.10 "Region items and region annotations"
-
-struct heif_region_item;
-
-enum heif_region_type
-{
-  heif_region_type_point = 0,
-  heif_region_type_rectangle = 1,
-  heif_region_type_ellipse = 2,
-  heif_region_type_polygon = 3,
-  heif_region_type_referenced_mask = 4, // TODO
-  heif_region_type_inline_mask = 5,     // TODO
-  heif_region_type_polyline = 6
-};
-
-struct heif_region;
-
-// How many region items are attached to an image.
-LIBHEIF_API
-int heif_image_handle_get_number_of_region_items(const struct heif_image_handle* image_handle);
-
-// Get the region_item IDs assigned to an image.
-// Returns the number of region items outputted.
-LIBHEIF_API
-int heif_image_handle_get_list_of_region_item_ids(const struct heif_image_handle* image_handle,
-                                                  heif_item_id* region_item_ids_array,
-                                                  int max_count);
-
-// You have to release the output heif_region_item with heif_region_item_release().
-LIBHEIF_API
-struct heif_error heif_context_get_region_item(const struct heif_context* context,
-                                               heif_item_id region_item_id,
-                                               struct heif_region_item** out);
-
-LIBHEIF_API
-heif_item_id heif_region_item_get_id(struct heif_region_item*);
-
-LIBHEIF_API
-void heif_region_item_release(struct heif_region_item*);
-
-// The reference size specifies the coordinate space using for the region items.
-// It is the size of the area of the encoded image prior to any transformations.
-LIBHEIF_API
-void heif_region_item_get_reference_size(struct heif_region_item*, uint32_t* width, uint32_t* height);
-
-LIBHEIF_API
-int heif_region_item_get_number_of_regions(const struct heif_region_item* region_item);
-
-// You will have to release all returned heif_region objects with heif_region_release() or heif_region_release_many().
-// 'out_regions' should point to an array of size 'max_count'.
-// The function returns the number of regions filled into the 'out_regions' array.
-LIBHEIF_API
-int heif_region_item_get_list_of_regions(const struct heif_region_item* region_item,
-                                         struct heif_region** out_regions_array,
-                                         int max_count);
-
-LIBHEIF_API
-void heif_region_release(const struct heif_region* region);
-
-LIBHEIF_API
-void heif_region_release_many(const struct heif_region* const* regions_array, int num);
-
-LIBHEIF_API
-enum heif_region_type heif_region_get_type(const struct heif_region* region);
-
-// When querying the region geometry, there is a version without and a version with "_transformed" suffix.
-// The version without returns the coordinates in the reference coordinate space.
-// The version with "_transformed" suffix give the coordinates in pixels after all transformative properties have been applied.
-
-LIBHEIF_API
-struct heif_error heif_region_get_point(const struct heif_region* region, int32_t* x, int32_t* y);
-
-LIBHEIF_API
-struct heif_error heif_region_get_point_transformed(const struct heif_region* region, double* x, double* y,
-                                                    heif_item_id image_id);
-
-LIBHEIF_API
-struct heif_error heif_region_get_rectangle(const struct heif_region* region,
-                                            int32_t* x, int32_t* y,
-                                            uint32_t* width, uint32_t* height);
-
-LIBHEIF_API
-struct heif_error heif_region_get_rectangle_transformed(const struct heif_region* region,
-                                                        double* x, double* y,
-                                                        double* width, double* height,
-                                                        heif_item_id image_id);
-
-LIBHEIF_API
-struct heif_error heif_region_get_ellipse(const struct heif_region* region,
-                                          int32_t* x, int32_t* y,
-                                          uint32_t* radius_x, uint32_t* radius_y);
-
-LIBHEIF_API
-struct heif_error heif_region_get_ellipse_transformed(const struct heif_region* region,
-                                                      double* x, double* y,
-                                                      double* radius_x, double* radius_y,
-                                                      heif_item_id image_id);
-
-LIBHEIF_API
-int heif_region_get_polygon_num_points(const struct heif_region* region);
-
-// Point coordinates are stored in the output array 'pts'. This must have twice as many entries as there are points.
-// Each point is stored as consecutive x and y positions.
-LIBHEIF_API
-struct heif_error heif_region_get_polygon_points(const struct heif_region* region,
-                                                 int32_t* out_pts_array);
-
-LIBHEIF_API
-struct heif_error heif_region_get_polygon_points_transformed(const struct heif_region* region,
-                                                             double* out_pts_array,
-                                                             heif_item_id image_id);
-
-LIBHEIF_API
-int heif_region_get_polyline_num_points(const struct heif_region* region);
-
-LIBHEIF_API
-struct heif_error heif_region_get_polyline_points(const struct heif_region* region,
-                                                  int32_t* out_pts_array);
-
-LIBHEIF_API
-struct heif_error heif_region_get_polyline_points_transformed(const struct heif_region* region,
-                                                              double* out_pts_array,
-                                                              heif_item_id image_id);
-
-// --- adding region items
-
-LIBHEIF_API
-struct heif_error heif_image_handle_add_region_item(struct heif_image_handle* image_handle,
-                                                    uint32_t reference_width, uint32_t reference_height,
-                                                    struct heif_region_item** out_region_item);
-
-// When adding regions, there is an optional 'out_region' parameter.
-// This is usually not needed. You may set it to NULL.
-
-LIBHEIF_API
-struct heif_error heif_region_item_add_region_point(struct heif_region_item*,
-                                                    int32_t x, int32_t y,
-                                                    struct heif_region** out_region);
-
-LIBHEIF_API
-struct heif_error heif_region_item_add_region_rectangle(struct heif_region_item*,
-                                                        int32_t x, int32_t y,
-                                                        uint32_t width, uint32_t height,
-                                                        struct heif_region** out_region);
-
-LIBHEIF_API
-struct heif_error heif_region_item_add_region_ellipse(struct heif_region_item*,
-                                                      int32_t x, int32_t y,
-                                                      uint32_t radius_x, uint32_t radius_y,
-                                                      struct heif_region** out_region);
-
-// pts[] is an array of 2*nPoints, each pair representing x and y.
-LIBHEIF_API
-struct heif_error heif_region_item_add_region_polygon(struct heif_region_item*,
-                                                      const int32_t* pts_array, int nPoints,
-                                                      struct heif_region** out_region);
-
-LIBHEIF_API
-struct heif_error heif_region_item_add_region_polyline(struct heif_region_item*,
-                                                       const int32_t* pts_array, int nPoints,
-                                                       struct heif_region** out_region);
-
 #ifdef __cplusplus
 }
 #endif