@img/sharp-libvips-dev 1.2.0-rc.3 → 1.2.0

package/include/libheif/heif_color.h

@@ -0,0 +1,357 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2017-2023 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * This file is part of libheif.
+ *
+ * libheif is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * libheif is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef LIBHEIF_HEIF_COLOR_H
+#define LIBHEIF_HEIF_COLOR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <libheif/heif_library.h>
+
+// forward declaration from other header files
+typedef struct heif_image heif_image;
+
+
+enum heif_chroma_downsampling_algorithm
+{
+  heif_chroma_downsampling_nearest_neighbor = 1,
+  heif_chroma_downsampling_average = 2,
+
+  // Combine with 'heif_chroma_upsampling_bilinear' for best quality.
+  // Makes edges look sharper when using YUV 420 with bilinear chroma upsampling.
+  heif_chroma_downsampling_sharp_yuv = 3
+};
+
+enum heif_chroma_upsampling_algorithm
+{
+  heif_chroma_upsampling_nearest_neighbor = 1,
+  heif_chroma_upsampling_bilinear = 2
+};
+
+
+typedef struct heif_color_conversion_options
+{
+  // 'version' must be 1.
+  uint8_t version;
+
+  // --- version 1 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
+  // 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;
+
+  // --- Note that we cannot extend this struct because it is embedded in
+  //     other structs (heif_decoding_options and heif_encoding_options).
+} heif_color_conversion_options;
+
+
+enum heif_alpha_composition_mode
+{
+  heif_alpha_composition_mode_none,
+  heif_alpha_composition_mode_solid_color,
+  heif_alpha_composition_mode_checkerboard,
+};
+
+
+typedef struct heif_color_conversion_options_ext
+{
+  uint8_t version;
+
+  // --- version 1 options
+
+  enum heif_alpha_composition_mode alpha_composition_mode;
+
+  // color values should be specified in the range [0, 65535]
+  uint16_t background_red, background_green, background_blue;
+  uint16_t secondary_background_red, secondary_background_green, secondary_background_blue;
+  uint16_t checkerboard_square_size;
+} heif_color_conversion_options_ext;
+
+
+// Assumes that it is a version=1 struct.
+LIBHEIF_API
+void heif_color_conversion_options_set_defaults(heif_color_conversion_options*);
+
+LIBHEIF_API
+heif_color_conversion_options_ext* heif_color_conversion_options_ext_alloc(void);
+
+LIBHEIF_API
+void heif_color_conversion_options_ext_copy(heif_color_conversion_options_ext* dst,
+                                            const heif_color_conversion_options_ext* src);
+
+LIBHEIF_API
+void heif_color_conversion_options_ext_free(heif_color_conversion_options_ext*);
+
+
+// ------------------------- color profiles -------------------------
+
+enum heif_color_profile_type
+{
+  heif_color_profile_type_not_present = 0,
+  heif_color_profile_type_nclx = heif_fourcc('n', 'c', 'l', 'x'),
+  heif_color_profile_type_rICC = heif_fourcc('r', 'I', 'C', 'C'),
+  heif_color_profile_type_prof = heif_fourcc('p', 'r', 'o', 'f')
+};
+
+
+// Returns 'heif_color_profile_type_not_present' if there is no color profile.
+// If there is an ICC profile and an NCLX profile, the ICC profile is returned.
+// TODO: we need a new API for this function as images can contain both NCLX and ICC at the same time.
+//       However, you can still use heif_image_handle_get_raw_color_profile() and
+//       heif_image_handle_get_nclx_color_profile() to access both profiles.
+LIBHEIF_API
+enum heif_color_profile_type heif_image_handle_get_color_profile_type(const heif_image_handle* handle);
+
+LIBHEIF_API
+size_t heif_image_handle_get_raw_color_profile_size(const heif_image_handle* handle);
+
+// Returns 'heif_error_Color_profile_does_not_exist' when there is no ICC profile.
+LIBHEIF_API
+struct heif_error heif_image_handle_get_raw_color_profile(const heif_image_handle* handle,
+                                                          void* out_data);
+
+
+enum heif_color_primaries
+{
+  heif_color_primaries_ITU_R_BT_709_5 = 1, // g=0.3;0.6, b=0.15;0.06, r=0.64;0.33, w=0.3127,0.3290
+  heif_color_primaries_unspecified = 2,
+  heif_color_primaries_ITU_R_BT_470_6_System_M = 4,
+  heif_color_primaries_ITU_R_BT_470_6_System_B_G = 5,
+  heif_color_primaries_ITU_R_BT_601_6 = 6,
+  heif_color_primaries_SMPTE_240M = 7,
+  heif_color_primaries_generic_film = 8,
+  heif_color_primaries_ITU_R_BT_2020_2_and_2100_0 = 9,
+  heif_color_primaries_SMPTE_ST_428_1 = 10,
+  heif_color_primaries_SMPTE_RP_431_2 = 11,
+  heif_color_primaries_SMPTE_EG_432_1 = 12,
+  heif_color_primaries_EBU_Tech_3213_E = 22
+};
+
+enum heif_transfer_characteristics
+{
+  heif_transfer_characteristic_ITU_R_BT_709_5 = 1,
+  heif_transfer_characteristic_unspecified = 2,
+  heif_transfer_characteristic_ITU_R_BT_470_6_System_M = 4,
+  heif_transfer_characteristic_ITU_R_BT_470_6_System_B_G = 5,
+  heif_transfer_characteristic_ITU_R_BT_601_6 = 6,
+  heif_transfer_characteristic_SMPTE_240M = 7,
+  heif_transfer_characteristic_linear = 8,
+  heif_transfer_characteristic_logarithmic_100 = 9,
+  heif_transfer_characteristic_logarithmic_100_sqrt10 = 10,
+  heif_transfer_characteristic_IEC_61966_2_4 = 11,
+  heif_transfer_characteristic_ITU_R_BT_1361 = 12,
+  heif_transfer_characteristic_IEC_61966_2_1 = 13,
+  heif_transfer_characteristic_ITU_R_BT_2020_2_10bit = 14,
+  heif_transfer_characteristic_ITU_R_BT_2020_2_12bit = 15,
+  heif_transfer_characteristic_ITU_R_BT_2100_0_PQ = 16,
+  heif_transfer_characteristic_SMPTE_ST_428_1 = 17,
+  heif_transfer_characteristic_ITU_R_BT_2100_0_HLG = 18
+};
+
+enum heif_matrix_coefficients
+{
+  heif_matrix_coefficients_RGB_GBR = 0,
+  heif_matrix_coefficients_ITU_R_BT_709_5 = 1,  // TODO: or 709-6 according to h.273
+  heif_matrix_coefficients_unspecified = 2,
+  heif_matrix_coefficients_US_FCC_T47 = 4,
+  heif_matrix_coefficients_ITU_R_BT_470_6_System_B_G = 5,
+  heif_matrix_coefficients_ITU_R_BT_601_6 = 6,  // TODO: or 601-7 according to h.273
+  heif_matrix_coefficients_SMPTE_240M = 7,
+  heif_matrix_coefficients_YCgCo = 8,
+  heif_matrix_coefficients_ITU_R_BT_2020_2_non_constant_luminance = 9,
+  heif_matrix_coefficients_ITU_R_BT_2020_2_constant_luminance = 10,
+  heif_matrix_coefficients_SMPTE_ST_2085 = 11,
+  heif_matrix_coefficients_chromaticity_derived_non_constant_luminance = 12,
+  heif_matrix_coefficients_chromaticity_derived_constant_luminance = 13,
+  heif_matrix_coefficients_ICtCp = 14
+};
+
+typedef struct heif_color_profile_nclx
+{
+  // === version 1 fields
+
+  uint8_t version;
+
+  enum heif_color_primaries color_primaries;
+  enum heif_transfer_characteristics transfer_characteristics;
+  enum heif_matrix_coefficients matrix_coefficients;
+  uint8_t full_range_flag;
+
+  // --- decoded values (not used when saving nclx)
+
+  float color_primary_red_x, color_primary_red_y;
+  float color_primary_green_x, color_primary_green_y;
+  float color_primary_blue_x, color_primary_blue_y;
+  float color_primary_white_x, color_primary_white_y;
+} heif_color_profile_nclx;
+
+LIBHEIF_API
+heif_error heif_nclx_color_profile_set_color_primaries(heif_color_profile_nclx* nclx, uint16_t cp);
+
+LIBHEIF_API
+heif_error heif_nclx_color_profile_set_transfer_characteristics(heif_color_profile_nclx* nclx, uint16_t transfer_characteristics);
+
+LIBHEIF_API
+heif_error heif_nclx_color_profile_set_matrix_coefficients(heif_color_profile_nclx* nclx, uint16_t matrix_coefficients);
+
+// Returns 'heif_error_Color_profile_does_not_exist' when there is no NCLX profile.
+// TODO: This function does currently not return an NCLX profile if it is stored in the image bitstream.
+//       Only NCLX profiles stored as colr boxes are returned. This may change in the future.
+LIBHEIF_API
+heif_error heif_image_handle_get_nclx_color_profile(const heif_image_handle* handle,
+                                                    heif_color_profile_nclx** out_data);
+
+// Returned color profile has 'version' field set to the maximum allowed.
+// Do not fill values for higher versions as these might be outside the allocated structure size.
+// May return NULL.
+LIBHEIF_API
+heif_color_profile_nclx* heif_nclx_color_profile_alloc(void);
+
+LIBHEIF_API
+void heif_nclx_color_profile_free(heif_color_profile_nclx* nclx_profile);
+
+// Note: in early versions of HEIF, there could only be one color profile per image. However, this has been changed.
+// This function will now return ICC if one is present and NCLX only if there is no ICC.
+// You may better avoid this function and simply query for NCLX and ICC directly.
+LIBHEIF_API
+enum heif_color_profile_type heif_image_get_color_profile_type(const heif_image* image);
+
+// Returns the size of the ICC profile if one is assigned to the image. Otherwise, it returns 0.
+LIBHEIF_API
+size_t heif_image_get_raw_color_profile_size(const heif_image* image);
+
+// Returns the ICC profile if one is assigned to the image. Otherwise, it returns an error.
+LIBHEIF_API
+heif_error heif_image_get_raw_color_profile(const heif_image* image,
+                                            void* out_data);
+
+LIBHEIF_API
+heif_error heif_image_get_nclx_color_profile(const heif_image* image,
+                                             heif_color_profile_nclx** out_data);
+
+
+// The color profile is not attached to the image handle because we might need it
+// for color space transform and encoding.
+LIBHEIF_API
+heif_error heif_image_set_raw_color_profile(heif_image* image,
+                                            const char* profile_type_fourcc_string,
+                                            const void* profile_data,
+                                            const size_t profile_size);
+
+LIBHEIF_API
+heif_error heif_image_set_nclx_color_profile(heif_image* image,
+                                             const heif_color_profile_nclx* color_profile);
+
+
+// TODO: this function does not make any sense yet, since we currently cannot modify existing HEIF files.
+//LIBHEIF_API
+//void heif_image_remove_color_profile(struct heif_image* image);
+
+
+// --- content light level ---
+
+// Note: a value of 0 for any of these values indicates that the value is undefined.
+// The unit of these values is Candelas per square meter.
+typedef struct heif_content_light_level
+{
+  uint16_t max_content_light_level;
+  uint16_t max_pic_average_light_level;
+} heif_content_light_level;
+
+LIBHEIF_API
+int heif_image_has_content_light_level(const heif_image*);
+
+LIBHEIF_API
+void heif_image_get_content_light_level(const heif_image*, heif_content_light_level* out);
+
+// Returns whether the image has 'content light level' information. If 0 is returned, the output is not filled.
+LIBHEIF_API
+int heif_image_handle_get_content_light_level(const heif_image_handle*, heif_content_light_level* out);
+
+LIBHEIF_API
+void heif_image_set_content_light_level(const heif_image*, const heif_content_light_level* in);
+
+
+// --- mastering display colour volume ---
+
+// Note: color coordinates are defined according to the CIE 1931 definition of x as specified in ISO 11664-1 (see also ISO 11664-3 and CIE 15).
+typedef struct heif_mastering_display_colour_volume
+{
+  uint16_t display_primaries_x[3];
+  uint16_t display_primaries_y[3];
+  uint16_t white_point_x;
+  uint16_t white_point_y;
+  uint32_t max_display_mastering_luminance;
+  uint32_t min_display_mastering_luminance;
+} heif_mastering_display_colour_volume;
+
+// The units for max_display_mastering_luminance and min_display_mastering_luminance is Candelas per square meter.
+typedef struct heif_decoded_mastering_display_colour_volume
+{
+  float display_primaries_x[3];
+  float display_primaries_y[3];
+  float white_point_x;
+  float white_point_y;
+  double max_display_mastering_luminance;
+  double min_display_mastering_luminance;
+} heif_decoded_mastering_display_colour_volume;
+
+typedef struct heif_ambient_viewing_environment
+{
+  uint32_t ambient_illumination;
+  uint16_t ambient_light_x;
+  uint16_t ambient_light_y;
+} heif_ambient_viewing_environment;
+
+LIBHEIF_API
+int heif_image_has_mastering_display_colour_volume(const heif_image*);
+
+LIBHEIF_API
+void heif_image_get_mastering_display_colour_volume(const heif_image*, heif_mastering_display_colour_volume* out);
+
+// Returns whether the image has 'mastering display colour volume' information. If 0 is returned, the output is not filled.
+LIBHEIF_API
+int heif_image_handle_get_mastering_display_colour_volume(const heif_image_handle*, heif_mastering_display_colour_volume* out);
+
+LIBHEIF_API
+void heif_image_set_mastering_display_colour_volume(const heif_image*, const heif_mastering_display_colour_volume* in);
+
+
+// Converts the internal numeric representation of heif_mastering_display_colour_volume to the
+// normalized values, collected in heif_decoded_mastering_display_colour_volume.
+// Values that are out-of-range are decoded to 0, indicating an undefined value (as specified in ISO/IEC 23008-2).
+LIBHEIF_API
+struct heif_error heif_mastering_display_colour_volume_decode(const heif_mastering_display_colour_volume* in,
+                                                              heif_decoded_mastering_display_colour_volume* out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/include/libheif/heif_context.h

@@ -0,0 +1,329 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2017-2025 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * This file is part of libheif.
+ *
+ * libheif is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * libheif is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef LIBHEIF_HEIF_CONTEXT_H
+#define LIBHEIF_HEIF_CONTEXT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <libheif/heif_library.h>
+#include <libheif/heif_error.h>
+
+
+/**
+ * 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.
+   *
+   * 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.
+   *
+   * The encapsulation is defined in ISO/IEC 23008-12:2022 Annex M.
+   */
+  heif_compression_EVC = 6,
+  /**
+   * JPEG 2000 compression.
+   *
+   * 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:2024.
+  */
+  heif_compression_uncompressed = 8,
+  /**
+   * Mask image encoding.
+   *
+   * See ISO/IEC 23008-12:2022 Section 6.10.2
+   */
+  heif_compression_mask = 9,
+  /**
+   * High Throughput JPEG 2000 (HT-J2K) compression.
+   *
+   * The encapsulation of HT-J2K is specified in ISO/IEC 15444-16:2021.
+   * The core encoding is defined in ISO/IEC 15444-15, or ITU-T T.814.
+  */
+  heif_compression_HTJ2K = 10
+};
+
+
+// ========================= heif_context =========================
+// A heif_context represents a HEIF file that has been read.
+// In the future, you will also be able to add pictures to a heif_context
+// and write it into a file again.
+
+
+// Allocate a new context for reading HEIF files.
+// Has to be freed again with heif_context_free().
+LIBHEIF_API
+heif_context* heif_context_alloc(void);
+
+// Free a previously allocated HEIF context. You should not free a context twice.
+LIBHEIF_API
+void heif_context_free(heif_context*);
+
+
+typedef struct heif_reading_options heif_reading_options;
+
+enum heif_reader_grow_status
+{
+  heif_reader_grow_status_size_reached,    // requested size has been reached, we can read until this point
+  heif_reader_grow_status_timeout,         // size has not been reached yet, but it may still grow further (deprecated)
+  heif_reader_grow_status_size_beyond_eof, // size has not been reached and never will. The file has grown to its full size
+  heif_reader_grow_status_error            // an error has occurred
+};
+
+
+typedef struct heif_reader_range_request_result
+{
+  enum heif_reader_grow_status status; // should not return 'heif_reader_grow_status_timeout'
+
+  // Indicates up to what position the file has been read.
+  // If we cannot read the whole file range (status == 'heif_reader_grow_status_size_beyond_eof'), this is the actual end position.
+  // On the other hand, it may be that the reader was reading more data than requested. In that case, it should indicate the full size here
+  // and libheif may decide to make use of the additional data (e.g. for filling 'tili' offset tables).
+  uint64_t range_end;
+
+  // for status == 'heif_reader_grow_status_error'
+  int reader_error_code;        // a reader specific error code
+  const char* reader_error_msg; // libheif will call heif_reader.release_error_msg on this if it is not NULL
+} heif_reader_range_request_result;
+
+
+typedef struct heif_reader
+{
+  // API version supported by this reader
+  int reader_api_version;
+
+  // --- version 1 functions ---
+  int64_t (* get_position)(void* userdata);
+
+  // The functions read(), and seek() return 0 on success.
+  // Generally, libheif will make sure that we do not read past the file size.
+  int (* read)(void* data,
+               size_t size,
+               void* userdata);
+
+  int (* seek)(int64_t position,
+               void* userdata);
+
+  // When calling this function, libheif wants to make sure that it can read the file
+  // up to 'target_size'. This is useful when the file is currently downloaded and may
+  // grow with time. You may, for example, extract the image sizes even before the actual
+  // compressed image data has been completely downloaded.
+  //
+  // Even if your input files will not grow, you will have to implement at least
+  // detection whether the target_size is above the (fixed) file length
+  // (in this case, return 'size_beyond_eof').
+  enum heif_reader_grow_status (* wait_for_file_size)(int64_t target_size, void* userdata);
+
+  // --- version 2 functions ---
+
+  // These two functions are for applications that want to stream HEIF files on demand.
+  // For example, a large HEIF file that is served over HTTPS and we only want to download
+  // it partially to decode individual tiles.
+  // If you do not have this use case, you do not have to implement these functions and
+  // you can set them to NULL. For simple linear loading, you may use the 'wait_for_file_size'
+  // function above instead.
+
+  // If this function is defined, libheif will often request a file range before accessing it.
+  // The purpose of this function is that libheif will usually read very small chunks of data with the
+  // read() callback above. However, it is inefficient to request such a small chunk of data over a network
+  // and the network delay will significantly increase the decoding time.
+  // Thus, libheif will call request_range() with a larger block of data that should be preloaded and the
+  // subsequent read() calls will work within the requested ranges.
+  //
+  // Note: `end_pos` is one byte after the last position to be read.
+  // You should return
+  // - 'heif_reader_grow_status_size_reached' if the requested range is available, or
+  // - 'heif_reader_grow_status_size_beyond_eof' if the requested range exceeds the file size
+  //   (the valid part of the range has been read).
+  heif_reader_range_request_result (* request_range)(uint64_t start_pos, uint64_t end_pos, void* userdata);
+
+  // libheif might issue hints when it assumes that a file range might be needed in the future.
+  // This may happen, for example, when your are doing selective tile accesses and libheif proposes
+  // to preload offset pointer tables.
+  // Another difference to request_file_range() is that this call should be non-blocking.
+  // If you preload any data, do this in a background thread.
+  void (* preload_range_hint)(uint64_t start_pos, uint64_t end_pos, void* userdata);
+
+  // If libheif does not need access to a file range anymore, it may call this function to
+  // give a hint to the reader that it may release the range from a cache.
+  // If you do not maintain a file cache that wants to reduce its size dynamically, you do not
+  // need to implement this function.
+  void (* release_file_range)(uint64_t start_pos, uint64_t end_pos, void* userdata);
+
+  // Release an error message that was returned by heif_reader in an earlier call.
+  // If this function is NULL, the error message string will not be released.
+  // This is a viable option if you are only returning static strings.
+  void (* release_error_msg)(const char* msg);
+} heif_reader;
+
+
+// Read a HEIF file from a named disk file.
+// The heif_reading_options should currently be set to NULL.
+LIBHEIF_API
+heif_error heif_context_read_from_file(heif_context*, const char* filename,
+                                       const heif_reading_options*);
+
+// Read a HEIF file stored completely in memory.
+// The heif_reading_options should currently be set to NULL.
+// DEPRECATED: use heif_context_read_from_memory_without_copy() instead.
+LIBHEIF_API
+heif_error heif_context_read_from_memory(heif_context*,
+                                         const void* mem, size_t size,
+                                         const heif_reading_options*);
+
+// Same as heif_context_read_from_memory() except that the provided memory is not copied.
+// That means, you will have to keep the memory area alive as long as you use the heif_context.
+LIBHEIF_API
+heif_error heif_context_read_from_memory_without_copy(heif_context*,
+                                                      const void* mem, size_t size,
+                                                      const heif_reading_options*);
+
+LIBHEIF_API
+heif_error heif_context_read_from_reader(heif_context*,
+                                         const heif_reader* reader,
+                                         void* userdata,
+                                         const heif_reading_options*);
+
+// Number of top-level images in the HEIF file. This does not include the thumbnails or the
+// tile images that are composed to an image grid. You can get access to the thumbnails via
+// the main image handle.
+LIBHEIF_API
+int heif_context_get_number_of_top_level_images(heif_context* ctx);
+
+LIBHEIF_API
+int heif_context_is_top_level_image_ID(heif_context* ctx, heif_item_id id);
+
+// Fills in image IDs into the user-supplied int-array 'ID_array', preallocated with 'count' entries.
+// Function returns the total number of IDs filled into the array.
+LIBHEIF_API
+int heif_context_get_list_of_top_level_image_IDs(heif_context* ctx,
+                                                 heif_item_id* ID_array,
+                                                 int count);
+
+LIBHEIF_API
+heif_error heif_context_get_primary_image_ID(heif_context* ctx, heif_item_id* id);
+
+// Get a handle to the primary image of the HEIF file.
+// This is the image that should be displayed primarily when there are several images in the file.
+LIBHEIF_API
+heif_error heif_context_get_primary_image_handle(heif_context* ctx,
+                                                 heif_image_handle**);
+
+// Get the image handle for a known image ID.
+LIBHEIF_API
+heif_error heif_context_get_image_handle(heif_context* ctx,
+                                         heif_item_id id,
+                                         heif_image_handle**);
+
+// Print information about the boxes of a HEIF file to file descriptor.
+// This is for debugging and informational purposes only. You should not rely on
+// the output having a specific format. At best, you should not use this at all.
+LIBHEIF_API
+void heif_context_debug_dump_boxes_to_file(heif_context* ctx, int fd);
+
+// ====================================================================================================
+//   Write the heif_context to a HEIF file
+
+LIBHEIF_API
+heif_error heif_context_write_to_file(heif_context*,
+                                      const char* filename);
+
+typedef struct heif_writer
+{
+  // API version supported by this writer
+  int writer_api_version;
+
+  // --- version 1 functions ---
+
+  // On success, the returned heif_error may have a NULL message. It will automatically be replaced with a "Success" string.
+  heif_error (* write)(heif_context* ctx, // TODO: why do we need this parameter?
+                       const void* data,
+                       size_t size,
+                       void* userdata);
+} heif_writer;
+
+
+LIBHEIF_API
+heif_error heif_context_write(heif_context*,
+                              heif_writer* writer,
+                              void* userdata);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif