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

package/include/libheif/heif_error.h

@@ -0,0 +1,302 @@
+/*
+ * 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_ERROR_H
+#define LIBHEIF_HEIF_ERROR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+
+
+enum heif_error_code
+{
+  // Everything ok, no error occurred.
+  heif_error_Ok = 0,
+
+  // Input file does not exist.
+  heif_error_Input_does_not_exist = 1,
+
+  // Error in input file. Corrupted or invalid content.
+  heif_error_Invalid_input = 2,
+
+  // Input file type is not supported.
+  heif_error_Unsupported_filetype = 3,
+
+  // Image requires an unsupported decoder feature.
+  heif_error_Unsupported_feature = 4,
+
+  // Library API has been used in an invalid way.
+  heif_error_Usage_error = 5,
+
+  // Could not allocate enough memory.
+  heif_error_Memory_allocation_error = 6,
+
+  // The decoder plugin generated an error
+  heif_error_Decoder_plugin_error = 7,
+
+  // The encoder plugin generated an error
+  heif_error_Encoder_plugin_error = 8,
+
+  // Error during encoding or when writing to the output
+  heif_error_Encoding_error = 9,
+
+  // Application has asked for a color profile type that does not exist
+  heif_error_Color_profile_does_not_exist = 10,
+
+  // Error loading a dynamic plugin
+  heif_error_Plugin_loading_error = 11,
+
+  // Operation has been canceled
+  heif_error_Canceled = 12,
+
+  heif_error_End_of_sequence = 13
+};
+
+
+enum heif_suberror_code
+{
+  // no further information available
+  heif_suberror_Unspecified = 0,
+
+  // --- Invalid_input ---
+
+  // End of data reached unexpectedly.
+  heif_suberror_End_of_data = 100,
+
+  // Size of box (defined in header) is wrong
+  heif_suberror_Invalid_box_size = 101,
+
+  // Mandatory 'ftyp' box is missing
+  heif_suberror_No_ftyp_box = 102,
+
+  heif_suberror_No_idat_box = 103,
+
+  heif_suberror_No_meta_box = 104,
+
+  heif_suberror_No_hdlr_box = 105,
+
+  heif_suberror_No_hvcC_box = 106,
+
+  heif_suberror_No_pitm_box = 107,
+
+  heif_suberror_No_ipco_box = 108,
+
+  heif_suberror_No_ipma_box = 109,
+
+  heif_suberror_No_iloc_box = 110,
+
+  heif_suberror_No_iinf_box = 111,
+
+  heif_suberror_No_iprp_box = 112,
+
+  heif_suberror_No_iref_box = 113,
+
+  heif_suberror_No_pict_handler = 114,
+
+  // An item property referenced in the 'ipma' box is not existing in the 'ipco' container.
+  heif_suberror_Ipma_box_references_nonexisting_property = 115,
+
+  // No properties have been assigned to an item.
+  heif_suberror_No_properties_assigned_to_item = 116,
+
+  // Image has no (compressed) data
+  heif_suberror_No_item_data = 117,
+
+  // Invalid specification of image grid (tiled image)
+  heif_suberror_Invalid_grid_data = 118,
+
+  // Tile-images in a grid image are missing
+  heif_suberror_Missing_grid_images = 119,
+
+  heif_suberror_Invalid_clean_aperture = 120,
+
+  // Invalid specification of overlay image
+  heif_suberror_Invalid_overlay_data = 121,
+
+  // Overlay image completely outside of visible canvas area
+  heif_suberror_Overlay_image_outside_of_canvas = 122,
+
+  heif_suberror_Auxiliary_image_type_unspecified = 123,
+
+  heif_suberror_No_or_invalid_primary_item = 124,
+
+  heif_suberror_No_infe_box = 125,
+
+  heif_suberror_Unknown_color_profile_type = 126,
+
+  heif_suberror_Wrong_tile_image_chroma_format = 127,
+
+  heif_suberror_Invalid_fractional_number = 128,
+
+  heif_suberror_Invalid_image_size = 129,
+
+  heif_suberror_Invalid_pixi_box = 130,
+
+  heif_suberror_No_av1C_box = 131,
+
+  heif_suberror_Wrong_tile_image_pixel_depth = 132,
+
+  heif_suberror_Unknown_NCLX_color_primaries = 133,
+
+  heif_suberror_Unknown_NCLX_transfer_characteristics = 134,
+
+  heif_suberror_Unknown_NCLX_matrix_coefficients = 135,
+
+  // Invalid specification of region item
+  heif_suberror_Invalid_region_data = 136,
+
+  // Image has no ispe property
+  heif_suberror_No_ispe_property = 137,
+
+  heif_suberror_Camera_intrinsic_matrix_undefined = 138,
+
+  heif_suberror_Camera_extrinsic_matrix_undefined = 139,
+
+  // Invalid JPEG 2000 codestream - usually a missing marker
+  heif_suberror_Invalid_J2K_codestream = 140,
+
+  heif_suberror_No_vvcC_box = 141,
+
+  // icbr is only needed in some situations, this error is for those cases
+  heif_suberror_No_icbr_box = 142,
+
+  heif_suberror_No_avcC_box = 143,
+
+  // we got a mini box, but could not read it properly
+  heif_suberror_Invalid_mini_box = 149,
+
+  // Decompressing generic compression or header compression data failed (e.g. bitstream corruption)
+  heif_suberror_Decompression_invalid_data = 150,
+
+  heif_suberror_No_moov_box = 151,
+
+  // --- Memory_allocation_error ---
+
+  // A security limit preventing unreasonable memory allocations was exceeded by the input file.
+  // Please check whether the file is valid. If it is, contact us so that we could increase the
+  // security limits further.
+  heif_suberror_Security_limit_exceeded = 1000,
+
+  // There was an error from the underlying compression / decompression library.
+  // One possibility is lack of resources (e.g. memory).
+  heif_suberror_Compression_initialisation_error = 1001,
+
+  // --- Usage_error ---
+
+  // An item ID was used that is not present in the file.
+  heif_suberror_Nonexisting_item_referenced = 2000, // also used for Invalid_input
+
+  // An API argument was given a NULL pointer, which is not allowed for that function.
+  heif_suberror_Null_pointer_argument = 2001,
+
+  // Image channel referenced that does not exist in the image
+  heif_suberror_Nonexisting_image_channel_referenced = 2002,
+
+  // The version of the passed plugin is not supported.
+  heif_suberror_Unsupported_plugin_version = 2003,
+
+  // The version of the passed writer is not supported.
+  heif_suberror_Unsupported_writer_version = 2004,
+
+  // The given (encoder) parameter name does not exist.
+  heif_suberror_Unsupported_parameter = 2005,
+
+  // The value for the given parameter is not in the valid range.
+  heif_suberror_Invalid_parameter_value = 2006,
+
+  // Error in property specification
+  heif_suberror_Invalid_property = 2007,
+
+  // Image reference cycle found in iref
+  heif_suberror_Item_reference_cycle = 2008,
+
+
+  // --- Unsupported_feature ---
+
+  // Image was coded with an unsupported compression method.
+  heif_suberror_Unsupported_codec = 3000,
+
+  // Image is specified in an unknown way, e.g. as tiled grid image (which is supported)
+  heif_suberror_Unsupported_image_type = 3001,
+
+  heif_suberror_Unsupported_data_version = 3002,
+
+  // The conversion of the source image to the requested chroma / colorspace is not supported.
+  heif_suberror_Unsupported_color_conversion = 3003,
+
+  heif_suberror_Unsupported_item_construction_method = 3004,
+
+  heif_suberror_Unsupported_header_compression_method = 3005,
+
+  // Generically compressed data used an unsupported compression method
+  heif_suberror_Unsupported_generic_compression_method = 3006,
+
+  heif_suberror_Unsupported_essential_property = 3007,
+
+  // --- Encoder_plugin_error ---
+
+  heif_suberror_Unsupported_bit_depth = 4000,
+
+
+  // --- Encoding_error ---
+
+  heif_suberror_Cannot_write_output_data = 5000,
+
+  heif_suberror_Encoder_initialization = 5001,
+  heif_suberror_Encoder_encoding = 5002,
+  heif_suberror_Encoder_cleanup = 5003,
+
+  heif_suberror_Too_many_regions = 5004,
+
+
+  // --- Plugin loading error ---
+
+  heif_suberror_Plugin_loading_error = 6000,         // a specific plugin file cannot be loaded
+  heif_suberror_Plugin_is_not_loaded = 6001,         // trying to remove a plugin that is not loaded
+  heif_suberror_Cannot_read_plugin_directory = 6002, // error while scanning the directory for plugins
+  heif_suberror_No_matching_decoder_installed = 6003 // no decoder found for that compression format
+};
+
+
+typedef struct heif_error
+{
+  // main error category
+  enum heif_error_code code;
+
+  // more detailed error code
+  enum heif_suberror_code subcode;
+
+  // textual error message (is always defined, you do not have to check for NULL)
+  const char* message;
+} heif_error;
+
+// Default success return value. Intended for use in user-supplied callback functions.
+LIBHEIF_API extern const heif_error heif_error_success;
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/include/libheif/heif_image.h

@@ -0,0 +1,352 @@
+/*
+ * 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_IMAGE_H
+#define LIBHEIF_HEIF_IMAGE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <libheif/heif_library.h>
+#include <libheif/heif_error.h>
+#include <stddef.h>
+#include <stdint.h>
+
+
+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,
+
+  // Indicates that this image has no visual channels.
+  heif_colorspace_nonvisual = 3
+};
+
+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,
+  heif_channel_filter_array = 11,
+  heif_channel_depth = 12,
+  heif_channel_disparity = 13
+};
+
+
+// An heif_image contains a decoded pixel image in various colorspaces, chroma formats,
+// and bit depths.
+
+// Note: when converting images to an interleaved chroma format, the resulting
+// image contains only a single channel of type channel_interleaved with, e.g., 3 bytes per pixel,
+// containing the interleaved R,G,B values.
+
+// Planar RGB images are specified as heif_colorspace_RGB / heif_chroma_444.
+
+typedef struct heif_image heif_image;
+typedef struct heif_image_handle heif_image_handle;
+typedef struct heif_security_limits heif_security_limits;
+
+
+// Get the colorspace format of the image.
+LIBHEIF_API
+enum heif_colorspace heif_image_get_colorspace(const heif_image*);
+
+// Get the chroma format of the image.
+LIBHEIF_API
+enum heif_chroma heif_image_get_chroma_format(const heif_image*);
+
+/**
+ * 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 heif_image* img, enum heif_channel channel);
+
+/**
+ * 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 heif_image* img, enum heif_channel channel);
+
+/**
+ * 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 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 heif_image* img);
+
+LIBHEIF_API
+heif_error heif_image_crop(heif_image* img,
+                           int left, int right, int top, int bottom);
+
+LIBHEIF_API
+heif_error heif_image_extract_area(const heif_image*,
+                                   uint32_t x0, uint32_t y0, uint32_t w, uint32_t h,
+                                   const heif_security_limits* limits,
+                                   heif_image** out_image);
+
+// Get the number of bits per pixel in the given image channel. Returns -1 if
+// a non-existing channel was given.
+// Note that the number of bits per pixel may be different for each color channel.
+// This function returns the number of bits used for storage of each pixel.
+// Especially for HDR images, this is probably not what you want. Have a look at
+// heif_image_get_bits_per_pixel_range() instead.
+LIBHEIF_API
+int heif_image_get_bits_per_pixel(const heif_image*, enum heif_channel channel);
+
+// Get the number of bits per pixel in the given image channel. This function returns
+// the number of bits used for representing the pixel value, which might be smaller
+// than the number of bits used in memory.
+// For example, in 12bit HDR images, this function returns '12', while still 16 bits
+// are reserved for storage. For interleaved RGBA with 12 bit, this function also returns
+// '12', not '48' or '64' (heif_image_get_bits_per_pixel returns 64 in this case).
+LIBHEIF_API
+int heif_image_get_bits_per_pixel_range(const heif_image*, enum heif_channel channel);
+
+LIBHEIF_API
+int heif_image_has_channel(const heif_image*, enum heif_channel channel);
+
+// Get a pointer to the actual pixel data.
+// The 'out_stride' is returned as "bytes per line".
+// When out_stride is NULL, no value will be written.
+// Returns NULL if a non-existing channel was given.
+// Deprecated, use the safer version heif_image_get_plane_readonly2() instead.
+LIBHEIF_API
+const uint8_t* heif_image_get_plane_readonly(const heif_image*,
+                                             enum heif_channel channel,
+                                             int* out_stride);
+
+// Deprecated, use the safer version heif_image_get_plane2() instead.
+LIBHEIF_API
+uint8_t* heif_image_get_plane(heif_image*,
+                              enum heif_channel channel,
+                              int* out_stride);
+
+// These are safer variants of the two functions above.
+// The 'stride' parameter is often multiplied by the image height in the client application.
+// For very large images, this can lead to integer overflows and, consequently, illegal memory accesses.
+// The changed 'stride' parameter types eliminates this common error.
+LIBHEIF_API
+const uint8_t* heif_image_get_plane_readonly2(const heif_image*,
+                                              enum heif_channel channel,
+                                              size_t* out_stride);
+
+LIBHEIF_API
+uint8_t* heif_image_get_plane2(heif_image*,
+                               enum heif_channel channel,
+                               size_t* out_stride);
+
+
+typedef struct heif_scaling_options heif_scaling_options;
+
+// Currently, heif_scaling_options is not defined yet. Pass a NULL pointer.
+LIBHEIF_API
+heif_error heif_image_scale_image(const heif_image* input,
+                                  heif_image** output,
+                                  int width, int height,
+                                  const heif_scaling_options* options);
+
+// Extends the image size to match the given size by extending the right and bottom borders.
+// The border areas are filled with zero.
+LIBHEIF_API
+heif_error heif_image_extend_to_size_fill_with_zero(heif_image* image,
+                                                    uint32_t width, uint32_t height);
+
+// Fills the image decoding warnings into the provided 'out_warnings' array.
+// The size of the array has to be provided in max_output_buffer_entries.
+// If max_output_buffer_entries==0, the number of decoder warnings is returned.
+// The function fills the warnings into the provided buffer, starting with 'first_warning_idx'.
+// It returns the number of warnings filled into the buffer.
+// Note: you can iterate through all warnings by using 'max_output_buffer_entries=1' and iterate 'first_warning_idx'.
+LIBHEIF_API
+int heif_image_get_decoding_warnings(heif_image* image,
+                                     int first_warning_idx,
+                                     heif_error* out_warnings,
+                                     int max_output_buffer_entries);
+
+// This function is only for decoder plugin implementors.
+LIBHEIF_API
+void heif_image_add_decoding_warning(heif_image* image,
+                                     heif_error err);
+
+// Release heif_image.
+LIBHEIF_API
+void heif_image_release(const heif_image*);
+
+LIBHEIF_API
+void heif_image_get_pixel_aspect_ratio(const heif_image*, uint32_t* aspect_h, uint32_t* aspect_v);
+
+LIBHEIF_API
+void heif_image_set_pixel_aspect_ratio(heif_image*, uint32_t aspect_h, uint32_t aspect_v);
+
+
+// --- heif_image allocation
+
+/**
+ * Create a new image of the specified resolution and colorspace.
+ *
+ * <p>This does not allocate memory for the image data. Use {@link heif_image_add_plane} to
+ * add the corresponding planes to match the specified {@code colorspace} and {@code chroma}.
+ *
+ * @param width the width of the image in pixels
+ * @param height the height of the image in pixels
+ * @param colorspace the colorspace of the image
+ * @param chroma the chroma of the image
+ * @param out_image pointer to pointer of the resulting image
+ * @return whether the creation succeeded or there was an error
+*/
+LIBHEIF_API
+heif_error heif_image_create(int width, int height,
+                             enum heif_colorspace colorspace,
+                             enum heif_chroma chroma,
+                             heif_image** out_image);
+
+/**
+ * Add an image plane to the image.
+ *
+ * <p>The image plane needs to match the colorspace and chroma of the image. Note
+ * that this does not need to be a single "planar" format - interleaved pixel channels
+ * can also be used if the chroma is interleaved.
+ *
+ * <p>The indicated bit_depth corresponds to the bit depth per channel. For example,
+ * with an interleaved format like RRGGBB where each color is represented by 10 bits,
+ * the {@code bit_depth} would be {@code 10} rather than {@code 30}.
+ *
+ * <p>For backward compatibility, one can also specify 24bits for RGB and 32bits for RGBA,
+ * instead of the preferred 8 bits. However, this use is deprecated.
+ *
+ * @param image the parent image to add the channel plane to
+ * @param channel the channel of the plane to add
+ * @param width the width of the plane
+ * @param height the height of the plane
+ * @param bit_depth the bit depth per color channel
+ * @return whether the addition succeeded or there was an error
+ *
+ * @note The width and height are usually the same as the parent image, but can be
+ * less for subsampling.
+ *
+ * @note The specified width can differ from the row stride of the resulting image plane.
+ * Always use the result of {@link heif_image_get_plane} or {@link heif_image_get_plane_readonly}
+ * to determine row stride.
+ */
+LIBHEIF_API
+heif_error heif_image_add_plane(heif_image* image,
+                                enum heif_channel channel,
+                                int width, int height, int bit_depth);
+
+/*
+ * The security limits should preferably be the limits from a heif_context.
+ * The memory allocated will then be registered in the memory budget of that context.
+ */
+LIBHEIF_API
+heif_error heif_image_add_plane_safe(heif_image* image,
+                                     enum heif_channel channel,
+                                     int width, int height, int bit_depth,
+                                     const heif_security_limits* limits);
+
+// Signal that the image is premultiplied by the alpha pixel values.
+LIBHEIF_API
+void heif_image_set_premultiplied_alpha(heif_image* image,
+                                        int is_premultiplied_alpha);
+
+LIBHEIF_API
+int heif_image_is_premultiplied_alpha(heif_image* image);
+
+// This function extends the padding of the image so that it has at least the given physical size.
+// The padding border is filled with the pixels along the right/bottom border.
+// This function may be useful if you want to process the image, but have some external padding requirements.
+// The image size will not be modified if it is already larger/equal than the given physical size.
+// I.e. you cannot assume that after calling this function, the stride will be equal to min_physical_width.
+LIBHEIF_API
+heif_error heif_image_extend_padding_to_size(heif_image* image,
+                                             int min_physical_width, int min_physical_height);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif