@img/sharp-libvips-dev-wasm32 1.3.0-rc.6 → 1.3.0-rc.8

package/include/libheif/heif_library.h

@@ -48,22 +48,14 @@ extern "C" {
 //  1.18           5            7             1             1            1            1
 //  1.19           6            7             2             1            1            1
 //  1.20           7            7             2             1            1            1
+//  1.21           8            7             2             1            1            1
+//  1.22           9            8             2             1            1            1
+//  1.23          10            8             2             1            1            1
 
-#if (defined(_WIN32) || defined __CYGWIN__) && !defined(LIBHEIF_STATIC_BUILD)
-#ifdef LIBHEIF_EXPORTS
-#define LIBHEIF_API __declspec(dllexport)
-#else
-#define LIBHEIF_API __declspec(dllimport)
-#endif
-#elif defined(HAVE_VISIBILITY) && HAVE_VISIBILITY
-#ifdef LIBHEIF_EXPORTS
-#define LIBHEIF_API __attribute__((__visibility__("default")))
-#else
-#define LIBHEIF_API
-#endif
-#else
-#define LIBHEIF_API
-#endif
+// The LIBHEIF_API export macro is defined in its own dependency-free header so
+// that heif_error.h (which is needed by this header) can use it without
+// creating an include cycle.
+#include <libheif/heif_export.h>
 
 /**
  * Build a 32 bit integer from a 4-character code.
@@ -169,7 +161,7 @@ typedef enum heif_plugin_type
 typedef struct heif_plugin_info
 {
   int version; // version of this info struct
-  enum heif_plugin_type type;
+  heif_plugin_type type;
   const void* plugin;
   void* internal_handle; // for internal use only
 } heif_plugin_info;

package/include/libheif/heif_omaf.h

@@ -0,0 +1,104 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2026 Brad Hards <bradh@frogmouth.net>
+ * Copyright (c) 2026 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_OMAF_H
+#define LIBHEIF_HEIF_OMAF_H
+
+#include <libheif/heif_library.h>
+#include <libheif/heif_error.h>
+#include <libheif/heif_image.h>
+#include <libheif/heif_image_handle.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// ------------------------- OMAF projection information -------------------------
+//
+// ISO/IEC 23090-2 "Omnidirectional media format" describes formats for
+// representing immersive / 360-degree imagery. The 'prfr' (projection format)
+// item property records the kind of projection used by the encoded image.
+
+/**
+ * OMAF Image projection.
+ *
+ * The image projection for most images is flat - it is projected as intended to be shown on
+ * a flat screen or print. For immersive or omnidirectional media (e.g. VR headsets, or
+ * equivalent), there are alternatives such as an equirectangular projection or cubemap projection.
+ *
+ * See ISO/IEC 23090-2 "Omnidirectional media format" for more information.
+ */
+typedef enum heif_omaf_image_projection
+{
+  /**
+   * Equirectangular projection.
+   */
+  heif_omaf_image_projection_equirectangular = 0x00,
+
+  /**
+   * Cube map.
+   */
+  heif_omaf_image_projection_cube_map = 0x01,
+
+  /*
+   * Values 2 through 31 are reserved in ISO/IEC 23090-2:2023 Table 10.
+   * Files may carry any of them; libheif passes the raw projection_type
+   * value through unchanged, so callers can log or round-trip it.
+   * Handle anything outside the named constants in a `default:` arm.
+   */
+
+  /**
+   * Flat projection. Also returned by the get-projection accessors when no
+   * projection information is present on the image, so callers can use
+   * `result == heif_omaf_image_projection_flat` to test for "no prfr box".
+   * 0xFF lies outside the prfr value range reserved by ISO 23090-2:2023
+   * Table 10, so it cannot collide with a value read from a file.
+   */
+  heif_omaf_image_projection_flat = 0xFF,
+} heif_omaf_image_projection;
+
+
+// To test whether projection information is present, compare the getter's
+// result against heif_omaf_image_projection_flat.
+
+LIBHEIF_API
+heif_omaf_image_projection heif_image_handle_get_omaf_image_projection(const heif_image_handle* handle);
+
+LIBHEIF_API
+void heif_image_handle_set_omaf_image_projection(heif_image_handle* handle,
+                                                 heif_omaf_image_projection image_projection);
+
+// Variants operating on a heif_image (a decoded or about-to-be-encoded pixel
+// image). Setting the projection on a heif_image before encoding causes the
+// resulting image item to carry the corresponding prfr property.
+
+LIBHEIF_API
+heif_omaf_image_projection heif_image_get_omaf_image_projection(const heif_image* image);
+
+LIBHEIF_API
+void heif_image_set_omaf_image_projection(heif_image* image,
+                                          heif_omaf_image_projection image_projection);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/include/libheif/heif_plugin.h

@@ -45,8 +45,9 @@ extern "C" {
 //  1.15         3         3          2
 //  1.20         4         3          2
 //  1.21         5         4          2
+//  1.22         6         4          2
 
-#define heif_decoder_plugin_latest_version 5
+#define heif_decoder_plugin_latest_version 6
 #define heif_encoder_plugin_latest_version 4
 
 // The minimum plugin versions that can be used with this libheif version.
@@ -61,17 +62,23 @@ extern "C" {
 
 typedef struct heif_decoder_plugin_compressed_format_description
 {
-  enum heif_compression_format format;
+  heif_compression_format format;
 
 } heif_decoder_plugin_compressed_format_description;
 
 
 typedef struct heif_decoder_plugin_options
 {
-  enum heif_compression_format format;
+  heif_compression_format format;
   int strict_decoding; // bool
   int num_threads; // 0 - undefined, use decoder default
 
+  // --- added in plugin_api_version 6 ---
+  // Security limits the plugin must enforce for image allocations during decoding.
+  // The pointee must outlive the decoder instance (typically the context's limits).
+  // Only read by plugins reporting plugin_api_version >= 6.
+  const heif_security_limits* limits;
+
 } heif_decoder_plugin_options;
 
 
@@ -95,7 +102,7 @@ typedef struct heif_decoder_plugin
   // Query whether the plugin supports decoding of the given format
   // Result is a priority value. The plugin with the largest value wins.
   // Default priority is 100. Returning 0 indicates that the plugin cannot decode this format.
-  int (* does_support_format)(enum heif_compression_format format);
+  int (* does_support_format)(heif_compression_format format);
 
   // Create a new decoder context for decoding an image
   heif_error (* new_decoder)(void** decoder);
@@ -191,7 +198,7 @@ typedef struct heif_encoder_plugin
   // --- version 1 functions ---
 
   // The compression format generated by this plugin.
-  enum heif_compression_format compression_format;
+  heif_compression_format compression_format;
 
   // Short name of the encoder that can be used as command line parameter when selecting an encoder.
   // Hence, it should stay stable and not contain any version numbers that will change.
@@ -250,8 +257,8 @@ typedef struct heif_encoder_plugin
 
   // Replace the input colorspace/chroma with the one that is supported by the encoder and that
   // comes as close to the input colorspace/chroma as possible.
-  void (* query_input_colorspace)(enum heif_colorspace* inout_colorspace,
-                                  enum heif_chroma* inout_chroma);
+  void (* query_input_colorspace)(heif_colorspace* inout_colorspace,
+                                  heif_chroma* inout_chroma);
 
   // Encode an image.
   // After pushing an image into the encoder, you should call get_compressed_data() to
@@ -268,8 +275,8 @@ typedef struct heif_encoder_plugin
   // --- version 2 ---
 
   void (* query_input_colorspace2)(void* encoder,
-                                   enum heif_colorspace* inout_colorspace,
-                                   enum heif_chroma* inout_chroma);
+                                   heif_colorspace* inout_colorspace,
+                                   heif_chroma* inout_chroma);
 
   // --- version 3 ---
 

package/include/libheif/heif_properties.h

@@ -192,6 +192,256 @@ heif_error heif_item_get_property_uuid_type(const heif_context* context,
                                             uint8_t out_extended_type[16]);
 
 
+// ------------------------- ISO/IEC 23001-17 properties -------------------------
+//
+// Imaging-metadata properties defined by ISO/IEC 23001-17 (uncompressed-image
+// format) and currently surfaced on uncompressed images. They operate on a
+// heif_image (the in-memory pixel image) rather than on (context, item_id) like
+// the box-level property API above.
+
+
+// --- Bayer / filter array pattern (cpat box)
+
+typedef struct heif_bayer_pattern_pixel
+{
+  uint32_t component_id;
+  float component_gain;
+} heif_bayer_pattern_pixel;
+
+
+// Set a Bayer / filter array pattern on an image.
+// The pattern is a 2D array of component indices with dimensions pattern_width x pattern_height.
+// The number of entries in patternPixels must be pattern_width * pattern_height.
+// The component_index values are indices into the cmpd component definition table.
+// On the encoder path, these indices are generated by heif_image_add_component() and the
+// encoder adds reference components to cmpd for pattern entries that don't have image planes.
+// On the decoder path, they come directly from the cpat box.
+LIBHEIF_API
+heif_error heif_image_set_bayer_pattern(heif_image*,
+                                        uint32_t bayer_component_id,
+                                        uint16_t pattern_width,
+                                        uint16_t pattern_height,
+                                        const heif_bayer_pattern_pixel* patternPixels);
+
+// Add a reference-only component to the image's component description table for use as
+// a Bayer pattern entry. The component is registered (its component_type appears in the
+// cmpd box) but carries no pixel plane of its own — the actual pixel data lives in the
+// single combined Bayer component (added with heif_image_add_component()).
+//
+// Use this for the per-cell colors that the Bayer pattern references (e.g. red, green,
+// blue) when those colors have no standalone plane. Pass the returned component_id in
+// heif_bayer_pattern_pixel::component_id of the patternPixels array given to
+// heif_image_set_bayer_pattern().
+//
+// component_type: one of heif_cmpd_component_type_* (e.g. _red, _green, _blue).
+// out_component_id: receives the minted component id. Must not be NULL.
+LIBHEIF_API
+heif_error heif_image_add_bayer_component(heif_image*,
+                                          uint16_t component_type,
+                                          uint32_t* out_component_id);
+
+// Returns whether the image has a Bayer / filter array pattern.
+// If the image has a pattern, out_pattern_width and out_pattern_height are set.
+// Either output pointer may be NULL if the caller does not need that value.
+LIBHEIF_API
+int heif_image_get_bayer_pattern_size(const heif_image*,
+                                      uint32_t bayer_component_id,
+                                      uint16_t* out_pattern_width,
+                                      uint16_t* out_pattern_height);
+
+// Get the Bayer / filter array pattern pixels.
+// The caller must provide an array large enough for pattern_width * pattern_height entries
+// (use heif_image_get_bayer_pattern_size() to query the dimensions first).
+// Returns heif_error_Ok on success, or an error if no pattern is set.
+LIBHEIF_API
+heif_error heif_image_get_bayer_pattern(const heif_image*,
+                                        uint32_t bayer_component_id,
+                                        heif_bayer_pattern_pixel* out_patternPixels);
+
+
+// --- Polarization pattern (ISO 23001-17, Section 6.1.5)
+
+// Special float value indicating "no polarization filter" at a pattern position.
+// On the wire this is the IEEE 754 bit pattern 0xFFFFFFFF (a signaling NaN).
+// Test with heif_polarization_angle_is_no_filter() below, or with isnan()/std::isnan().
+
+// Returns a float with the 0xFFFFFFFF bit pattern (NaN) representing "no polarization filter".
+LIBHEIF_API
+float heif_polarization_angle_no_filter(void);
+
+// Returns non-zero if the given angle has the "no filter" bit pattern (0xFFFFFFFF).
+LIBHEIF_API
+int heif_polarization_angle_is_no_filter(float angle);
+
+// Add a polarization pattern to an image.
+// component_indices: array of component indices this pattern applies to (may be NULL if num_component_indices == 0,
+//                    meaning the pattern applies to all components).
+// polarization_angles: array of pattern_width * pattern_height float values.
+//                      Each is an angle in degrees [0.0, 360.0), or heif_polarization_angle_no_filter() for "no filter".
+// Multiple patterns can be added (one per distinct component group).
+LIBHEIF_API
+heif_error heif_image_add_polarization_pattern(heif_image*,
+                                               uint32_t num_component_indices,
+                                               const uint32_t* component_indices,
+                                               uint16_t pattern_width,
+                                               uint16_t pattern_height,
+                                               const float* polarization_angles);
+
+// Returns the number of polarization patterns on this image (0 if none).
+LIBHEIF_API
+int heif_image_get_number_of_polarization_patterns(const heif_image*);
+
+// Get the sizes/dimensions of a polarization pattern (to allocate arrays for the data query).
+LIBHEIF_API
+heif_error heif_image_get_polarization_pattern_info(const heif_image*,
+                                                    int pattern_index,
+                                                    uint32_t* out_num_component_indices,
+                                                    uint16_t* out_pattern_width,
+                                                    uint16_t* out_pattern_height);
+
+// Get the actual data of a polarization pattern.
+// Caller must provide pre-allocated arrays:
+//   out_component_indices: num_component_indices entries (may be NULL if num_component_indices == 0)
+//   out_polarization_angles: pattern_width * pattern_height entries
+LIBHEIF_API
+heif_error heif_image_get_polarization_pattern_data(const heif_image*,
+                                                    int pattern_index,
+                                                    uint32_t* out_component_indices,
+                                                    float* out_polarization_angles);
+
+// Find the polarization pattern index that applies to a given component index.
+// Returns the pattern index (>= 0), or -1 if no pattern matches.
+// A pattern with an empty component list (component_count == 0) matches all components.
+LIBHEIF_API
+int heif_image_get_polarization_pattern_index_for_component(const heif_image*,
+                                                            uint32_t component_index);
+
+
+// --- Sensor bad pixels map (ISO 23001-17, Section 6.1.7)
+
+typedef struct heif_bad_pixel
+{
+  uint32_t row; uint32_t column;
+} heif_bad_pixel;
+
+// Add a sensor bad pixels map to an image.
+// component_indices: array of component indices this map applies to (may be NULL if num_component_indices == 0,
+//                    meaning the map applies to all components).
+// Multiple maps can be added (one per distinct component group with different defects).
+LIBHEIF_API
+heif_error heif_image_add_sensor_bad_pixels_map(heif_image*,
+                                                 uint32_t num_component_indices,
+                                                 const uint32_t* component_indices,
+                                                 int correction_applied,
+                                                 uint32_t num_bad_rows,
+                                                 const uint32_t* bad_rows,
+                                                 uint32_t num_bad_columns,
+                                                 const uint32_t* bad_columns,
+                                                 uint32_t num_bad_pixels,
+                                                 const heif_bad_pixel* bad_pixels);
+
+// Returns the number of sensor bad pixels maps on this image (0 if none).
+LIBHEIF_API
+int heif_image_get_number_of_sensor_bad_pixels_maps(const heif_image*);
+
+// Get the sizes of a sensor bad pixels map (to allocate arrays for the data query).
+LIBHEIF_API
+heif_error heif_image_get_sensor_bad_pixels_map_info(const heif_image*,
+                                                      int map_index,
+                                                      uint32_t* out_num_component_indices,
+                                                      int* out_correction_applied,
+                                                      uint32_t* out_num_bad_rows,
+                                                      uint32_t* out_num_bad_columns,
+                                                      uint32_t* out_num_bad_pixels);
+
+// Get the actual data of a sensor bad pixels map.
+// Caller must provide pre-allocated arrays:
+//   out_component_indices: num_component_indices entries (may be NULL if num_component_indices == 0)
+//   out_bad_rows: num_bad_rows entries (may be NULL if num_bad_rows == 0)
+//   out_bad_columns: num_bad_columns entries (may be NULL if num_bad_columns == 0)
+//   out_bad_pixels: num_bad_pixels entries (may be NULL if num_bad_pixels == 0)
+LIBHEIF_API
+heif_error heif_image_get_sensor_bad_pixels_map_data(const heif_image*,
+                                                      int map_index,
+                                                      uint32_t* out_component_indices,
+                                                      uint32_t* out_bad_rows,
+                                                      uint32_t* out_bad_columns,
+                                                      struct heif_bad_pixel* out_bad_pixels);
+
+
+// --- Sensor non-uniformity correction (ISO 23001-17, Section 6.1.6)
+
+// Add a sensor non-uniformity correction table to an image.
+// component_indices: array of component indices this NUC applies to (may be NULL if num_component_indices == 0,
+//                    meaning it applies to all components).
+// nuc_gains and nuc_offsets: arrays of image_width * image_height float values.
+// Correction equation: y = nuc_gain * x + nuc_offset.
+// Multiple NUC tables can be added (one per distinct component group).
+LIBHEIF_API
+heif_error heif_image_add_sensor_nuc(heif_image*,
+                                      uint32_t num_component_indices,
+                                      const uint32_t* component_indices,
+                                      int nuc_is_applied,
+                                      uint32_t image_width,
+                                      uint32_t image_height,
+                                      const float* nuc_gains,
+                                      const float* nuc_offsets);
+
+// Returns the number of sensor NUC tables on this image (0 if none).
+LIBHEIF_API
+int heif_image_get_number_of_sensor_nucs(const heif_image*);
+
+// Get the sizes of a sensor NUC table (to allocate arrays for the data query).
+LIBHEIF_API
+heif_error heif_image_get_sensor_nuc_info(const heif_image*,
+                                           int nuc_index,
+                                           uint32_t* out_num_component_indices,
+                                           int* out_nuc_is_applied,
+                                           uint32_t* out_image_width,
+                                           uint32_t* out_image_height);
+
+// Get the actual data of a sensor NUC table.
+// Caller must provide pre-allocated arrays:
+//   out_component_indices: num_component_indices entries (may be NULL if num_component_indices == 0)
+//   out_nuc_gains: image_width * image_height entries
+//   out_nuc_offsets: image_width * image_height entries
+LIBHEIF_API
+heif_error heif_image_get_sensor_nuc_data(const heif_image*,
+                                           int nuc_index,
+                                           uint32_t* out_component_indices,
+                                           float* out_nuc_gains,
+                                           float* out_nuc_offsets);
+
+
+// --- Chroma sample location (ISO 23091-2 / ITU-T H.273 + ISO 23001-17, Section 6.1.4) [cloc box]
+
+typedef enum heif_chroma420_sample_location {
+  // values 0-5 according to ISO 23091-2 / ITU-T H.273
+  heif_chroma420_sample_location_00_05 = 0,
+  heif_chroma420_sample_location_05_05 = 1,
+  heif_chroma420_sample_location_00_00 = 2,
+  heif_chroma420_sample_location_05_00 = 3,
+  heif_chroma420_sample_location_00_10 = 4,
+  heif_chroma420_sample_location_05_10 = 5,
+
+  // value 6 according to ISO 23001-17
+  heif_chroma420_sample_location_00_00_01_00 = 6
+} heif_chroma420_sample_location;
+
+// Set the chroma sample location on an image.
+// chroma_location must be in the range 0-6 (see heif_chroma420_sample_location).
+LIBHEIF_API
+heif_error heif_image_set_chroma_location(heif_image*, uint8_t chroma_location);
+
+// Returns non-zero if the image has a chroma sample location set.
+LIBHEIF_API
+int heif_image_has_chroma_location(const heif_image*);
+
+// Returns the chroma sample location (0-6), or 0 if none is set.
+LIBHEIF_API
+uint8_t heif_image_get_chroma_location(const heif_image*);
+
+
 // ------------------------- intrinsic and extrinsic matrices -------------------------
 
 typedef struct heif_camera_intrinsic_matrix
@@ -228,18 +478,6 @@ LIBHEIF_API
 heif_error heif_camera_extrinsic_matrix_get_rotation_matrix(const heif_camera_extrinsic_matrix*,
                                                             double* out_matrix_row_major);
 
-#if HEIF_WITH_OMAF
-// ------------------------- OMAF projection information -------------------------
-LIBHEIF_API
-int heif_image_handle_has_omaf_image_projection(const heif_image_handle* handle);
-
-LIBHEIF_API
-heif_omaf_image_projection heif_image_handle_get_omaf_image_projection(const heif_image_handle* handle);
-
-LIBHEIF_API
-void heif_image_handle_set_omaf_image_projection(const heif_image_handle* handle, heif_omaf_image_projection image_projection);
-#endif
-
 #ifdef __cplusplus
 }
 #endif

package/include/libheif/heif_security.h

@@ -38,7 +38,7 @@ typedef struct heif_security_limits
 {
   uint8_t version;
 
-  // --- version 1
+  // --- version 1 (v1.19.0)
 
   // Limit on the maximum image size to avoid allocating too much memory.
   // For example, setting this to 32768^2 pixels = 1 Gigapixels results
@@ -59,20 +59,32 @@ typedef struct heif_security_limits
 
   uint32_t max_children_per_box; // for all boxes that are not covered by other limits
 
-  // --- version 2
+  // --- version 2 (v1.20.0)
 
   uint64_t max_total_memory;
   uint32_t max_sample_description_box_entries;
   uint32_t max_sample_group_description_box_entries;
 
-  // --- version 3
+  // --- version 3 (v1.21.0)
 
   uint32_t max_sequence_frames;
   uint32_t max_number_of_file_brands;
 
-  // --- version 4
+  // --- version 4 (v1.22.0)
 
   uint32_t max_bad_pixels;
+
+  // Upper bound (in bytes) on the pixel_size field of an uncompressed (ISO 23001-17)
+  // uncC box. Caps the byte stride between adjacent pixels and prevents pathological
+  // padding values from blowing up tile-size arithmetic.
+  uint32_t max_iso23001_17_pixel_size_bytes;
+
+  // Internal: when libheif derives a limits struct from another one (e.g. to
+  // tighten the maximum image size for a specific decode), this points back to
+  // the registered context whose total-memory budget the allocation should be
+  // accounted against. nullptr means "this is a root context" (the registered
+  // one). User code should leave this as nullptr; the field is set internally.
+  const struct heif_security_limits* parent;
 } heif_security_limits;
 
 

package/include/libheif/heif_sequences.h

@@ -82,7 +82,12 @@ int heif_context_number_of_sequence_tracks(const heif_context*);
 
 /**
  * Returns the IDs for each of the tracks stored in the HEIF file.
- * The output array must have heif_context_number_of_sequence_tracks() entries.
+ *
+ * The caller MUST allocate `out_track_id_array` with exactly
+ * heif_context_number_of_sequence_tracks() entries. The function writes
+ * that many IDs unconditionally. Passing a smaller array results in a
+ * buffer overflow (undefined behavior); there is no capacity parameter
+ * and no truncation.
  */
 LIBHEIF_API
 void heif_context_get_track_ids(const heif_context* ctx, uint32_t out_track_id_array[]);
@@ -154,6 +159,41 @@ int heif_track_has_alpha_channel(const heif_track*);
 LIBHEIF_API
 uint32_t heif_track_get_timescale(const heif_track*);
 
+/**
+ * Special return value of `heif_track_get_number_of_repetitions()` indicating that
+ * the editlist requests indefinite repetition (the mvhd duration is the ISOBMFF
+ * "duration unknown" sentinel and the editlist is in repeat mode).
+ */
+#define heif_sequence_track_number_of_repetitions_infinite 0xFFFFFFFFu
+
+/**
+ * How many times the media segment should be played according to the track's edit list.
+ *
+ * Returns:
+ *  - 0 if an edit list box is present but follows a pattern libheif does not interpret
+ *    as a loop count. Callers should fall back to a single playback in that case.
+ *  - 1 when no edit list is present. The media plays exactly once.
+ *  - `heif_sequence_track_number_of_repetitions_infinite` (= UINT32_MAX) when the file
+ *    signals indefinite playback (mvhd duration is the all-1s sentinel together with an
+ *    editlist in repeat mode), or when the repetition count does not fit in uint32_t.
+ *  - Otherwise the number of times the media segment is played.
+ *
+ * The reported value is informational; it does not change how
+ * `heif_track_decode_next_image()` walks samples. By default, that function applies
+ * the edit list and (for repeated playback) returns samples for every requested
+ * repetition; iterating until end-of-sequence on an infinite-loop file therefore
+ * never terminates.
+ *
+ * Clients that want to handle repetition themselves (e.g. to honor an "infinite"
+ * value with their own looping policy or to enforce an application-level cap) should
+ * set `heif_decoding_options::ignore_sequence_editlist` when calling
+ * `heif_track_decode_next_image()`. With that flag set, libheif plays the media
+ * timeline exactly once. Use the value returned by this function to decide how often
+ * to replay the track at the application level.
+ */
+LIBHEIF_API
+uint32_t heif_track_get_number_of_repetitions(const heif_track*);
+
 
 // --- reading visual tracks
 
@@ -177,8 +217,8 @@ heif_error heif_track_get_image_resolution(const heif_track*, uint16_t* out_widt
 LIBHEIF_API
 heif_error heif_track_decode_next_image(heif_track* track,
                                         heif_image** out_img,
-                                        enum heif_colorspace colorspace,
-                                        enum heif_chroma chroma,
+                                        heif_colorspace colorspace,
+                                        heif_chroma chroma,
                                         const heif_decoding_options* options);
 
 /**
@@ -352,6 +392,23 @@ typedef enum heif_sequence_gop_structure
 } heif_sequence_gop_structure;
 
 
+// Describes the intent of the encoded sequence content. Encoder plugins may
+// use this to choose different default tunings (e.g. perceptual quality vs.
+// rate-distortion) for slide-show-style image sequences vs. video.
+//
+// Pass `_auto` to let libheif pick a value. Today libheif derives the kind
+// from the track's handler type (`pict` -> image_sequence, `vide` -> video);
+// in the future it may use additional input signals (e.g. frame rate or
+// frame-to-frame similarity). Plugins never see `_auto`: libheif resolves it
+// to a concrete kind before passing the options to the encoder plugin.
+typedef enum heif_sequence_content_kind
+{
+  heif_sequence_content_kind_auto = 0,
+  heif_sequence_content_kind_image_sequence = 1,
+  heif_sequence_content_kind_video = 2
+} heif_sequence_content_kind;
+
+
 typedef struct heif_sequence_encoding_options
 {
   uint8_t version;
@@ -371,12 +428,32 @@ typedef struct heif_sequence_encoding_options
   int keyframe_distance_max; // 0 - undefined
 
   int save_alpha_channel;
+
+  // version 3 options
+
+  // Intent of the encoded content. Encoder plugins may use this to choose
+  // different tunings for slide-show-style image sequences vs. video.
+  // Set to `_auto` (the default) to let libheif pick. libheif resolves the
+  // value to a concrete kind before passing the options to the encoder
+  // plugin, so plugins never see `_auto`.
+  enum heif_sequence_content_kind content_kind;
 } heif_sequence_encoding_options;
 
 
 LIBHEIF_API
 heif_sequence_encoding_options* heif_sequence_encoding_options_alloc(void);
 
+/**
+ * Copy fields from `src` into `dst`, respecting both structs' version numbers.
+ * Only fields present in `min(dst->version, src->version)` are copied, so this
+ * is safe when libheif and the caller were built against different header
+ * versions of `heif_sequence_encoding_options`. Pass NULL `src` to leave `dst`
+ * unchanged.
+ */
+LIBHEIF_API
+void heif_sequence_encoding_options_copy(heif_sequence_encoding_options* dst,
+                                         const heif_sequence_encoding_options* src);
+
 LIBHEIF_API
 void heif_sequence_encoding_options_release(heif_sequence_encoding_options*);
 
@@ -610,7 +687,12 @@ size_t heif_track_get_number_of_track_reference_types(const heif_track*);
 
 /**
  * List the reference types used in this track.
- * The passed array must have heif_track_get_number_of_track_reference_types() entries.
+ *
+ * The caller MUST allocate `out_reference_types` with exactly
+ * heif_track_get_number_of_track_reference_types() entries. The function
+ * writes that many values unconditionally. Passing a smaller array
+ * results in a buffer overflow (undefined behavior); there is no
+ * capacity parameter and no truncation.
  */
 LIBHEIF_API
 void heif_track_get_track_reference_types(const heif_track*, uint32_t out_reference_types[]);