libheif
Loading...
Searching...
No Matches
heif.h
Go to the documentation of this file.
1/*
2 * HEIF codec.
3 * Copyright (c) 2017-2023 Dirk Farin <dirk.farin@gmail.com>
4 *
5 * This file is part of libheif.
6 *
7 * libheif is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation, either version 3 of
10 * the License, or (at your option) any later version.
11 *
12 * libheif is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with libheif. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21#ifndef LIBHEIF_HEIF_H
22#define LIBHEIF_HEIF_H
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
33#include <stddef.h>
34#include <stdint.h>
35
36#include <libheif/heif_version.h>
37
38
39// API versions table
40//
41// release dec.options enc.options heif_reader heif_writer depth.rep col.profile
42// ------------------------------------------------------------------------------------------
43// 1.0 1 N/A N/A N/A 1 N/A
44// 1.1 1 N/A N/A 1 1 N/A
45// 1.3 1 1 1 1 1 N/A
46// 1.4 1 1 1 1 1 1
47// 1.7 2 1 1 1 1 1
48// 1.9.2 2 2 1 1 1 1
49// 1.10 2 3 1 1 1 1
50// 1.11 2 4 1 1 1 1
51// 1.13 3 4 1 1 1 1
52// 1.14 3 5 1 1 1 1
53// 1.15 4 5 1 1 1 1
54// 1.16 5 6 1 1 1 1
55
56#if defined(_MSC_VER) && !defined(LIBHEIF_STATIC_BUILD)
57#ifdef LIBHEIF_EXPORTS
58#define LIBHEIF_API __declspec(dllexport)
59#else
60#define LIBHEIF_API __declspec(dllimport)
61#endif
62#elif defined(HAVE_VISIBILITY) && HAVE_VISIBILITY
63#ifdef LIBHEIF_EXPORTS
64#define LIBHEIF_API __attribute__((__visibility__("default")))
65#else
66#define LIBHEIF_API
67#endif
68#else
69#define LIBHEIF_API
70#endif
71
72#define heif_fourcc(a, b, c, d) ((uint32_t)((a<<24) | (b<<16) | (c<<8) | d))
73
74
75/* === version numbers === */
76
77// Version string of linked libheif library.
78LIBHEIF_API const char* heif_get_version(void);
79
80// Numeric version of linked libheif library, encoded as 0xHHMMLL00 = hh.mm.ll, where hh, mm, ll is the decimal representation of HH, MM, LL.
81// For example: 0x02150300 is version 2.21.3
83
84// Numeric part "HH" from above. Returned as a decimal number.
86// Numeric part "MM" from above. Returned as a decimal number.
88// Numeric part "LL" from above. Returned as a decimal number.
90
91// Helper macros to check for given versions of libheif at compile time.
92#define LIBHEIF_MAKE_VERSION(h, m, l) ((h) << 24 | (m) << 16 | (l) << 8)
93#define LIBHEIF_HAVE_VERSION(h, m, l) (LIBHEIF_NUMERIC_VERSION >= LIBHEIF_MAKE_VERSION(h, m, l))
94
95struct heif_context;
96struct heif_image_handle;
97struct heif_image;
98
99
101{
102 // Everything ok, no error occurred.
104
105 // Input file does not exist.
107
108 // Error in input file. Corrupted or invalid content.
110
111 // Input file type is not supported.
113
114 // Image requires an unsupported decoder feature.
116
117 // Library API has been used in an invalid way.
119
120 // Could not allocate enough memory.
122
123 // The decoder plugin generated an error
125
126 // The encoder plugin generated an error
128
129 // Error during encoding or when writing to the output
131
132 // Application has asked for a color profile type that does not exist
134
135 // Error loading a dynamic plugin
138
139
141{
142 // no further information available
144
145 // --- Invalid_input ---
146
147 // End of data reached unexpectedly.
149
150 // Size of box (defined in header) is wrong
152
153 // Mandatory 'ftyp' box is missing
155
157
159
161
163
165
167
169
171
173
175
177
179
180 // An item property referenced in the 'ipma' box is not existing in the 'ipco' container.
182
183 // No properties have been assigned to an item.
185
186 // Image has no (compressed) data
188
189 // Invalid specification of image grid (tiled image)
191
192 // Tile-images in a grid image are missing
194
196
197 // Invalid specification of overlay image
199
200 // Overlay image completely outside of visible canvas area
202
204
206
208
210
212
214
216
218
220
222
224
226
228
229 // Invalid specification of region item
231
232 // Image has no ispe property
234
236
238
239 // Invalid JPEG 2000 codestream - usually a missing marker
241
243
244 // icbr is only needed in some situations, this error is for those cases
246
247 // Decompressing generic compression or header compression data failed (e.g. bitstream corruption)
249
250 // --- Memory_allocation_error ---
251
252 // A security limit preventing unreasonable memory allocations was exceeded by the input file.
253 // Please check whether the file is valid. If it is, contact us so that we could increase the
254 // security limits further.
256
257 // There was an error from the underlying compression / decompression library.
258 // One possibility is lack of resources (e.g. memory).
260
261 // --- Usage_error ---
262
263 // An item ID was used that is not present in the file.
264 heif_suberror_Nonexisting_item_referenced = 2000, // also used for Invalid_input
265
266 // An API argument was given a NULL pointer, which is not allowed for that function.
268
269 // Image channel referenced that does not exist in the image
271
272 // The version of the passed plugin is not supported.
274
275 // The version of the passed writer is not supported.
277
278 // The given (encoder) parameter name does not exist.
280
281 // The value for the given parameter is not in the valid range.
283
284 // Error in property specification
286
287 // Image reference cycle found in iref
289
290
291 // --- Unsupported_feature ---
292
293 // Image was coded with an unsupported compression method.
295
296 // Image is specified in an unknown way, e.g. as tiled grid image (which is supported)
298
300
301 // The conversion of the source image to the requested chroma / colorspace is not supported.
303
305
307
308 // Generically compressed data used an unsupported compression method
310
311 // --- Encoder_plugin_error ---
312
314
315
316 // --- Encoding_error ---
317
319
323
325
326
327 // --- Plugin loading error ---
328
329 heif_suberror_Plugin_loading_error = 6000, // a specific plugin file cannot be loaded
330 heif_suberror_Plugin_is_not_loaded = 6001, // trying to remove a plugin that is not loaded
331 heif_suberror_Cannot_read_plugin_directory = 6002, // error while scanning the directory for plugins
332 heif_suberror_No_matching_decoder_installed = 6003 // no decoder found for that compression format
334
335
337{
338 // main error category
340
341 // more detailed error code
343
344 // textual error message (is always defined, you do not have to check for NULL)
345 const char* message;
346};
347
348// Default success return value. Intended for use in user-supplied callback functions.
349LIBHEIF_API extern const struct heif_error heif_error_success;
350
351
352typedef uint32_t heif_item_id;
353typedef uint32_t heif_property_id;
354
355
356
357// ========================= enum types ======================
358
363{
443
445{
453 heif_chroma_interleaved_RRGGBB_BE = 12, // HDR, big endian.
454 heif_chroma_interleaved_RRGGBBAA_BE = 13, // HDR, big endian.
455 heif_chroma_interleaved_RRGGBB_LE = 14, // HDR, little endian.
456 heif_chroma_interleaved_RRGGBBAA_LE = 15 // HDR, little endian.
458
459// DEPRECATED ENUM NAMES
460#define heif_chroma_interleaved_24bit heif_chroma_interleaved_RGB
461#define heif_chroma_interleaved_32bit heif_chroma_interleaved_RGBA
462
463
465{
467
468 // heif_colorspace_YCbCr should be used with one of these heif_chroma values:
469 // * heif_chroma_444
470 // * heif_chroma_422
471 // * heif_chroma_420
473
474 // heif_colorspace_RGB should be used with one of these heif_chroma values:
475 // * heif_chroma_444 (for planar RGB)
476 // * heif_chroma_interleaved_RGB
477 // * heif_chroma_interleaved_RGBA
478 // * heif_chroma_interleaved_RRGGBB_BE
479 // * heif_chroma_interleaved_RRGGBBAA_BE
480 // * heif_chroma_interleaved_RRGGBB_LE
481 // * heif_chroma_interleaved_RRGGBBAA_LE
483
484 // heif_colorspace_monochrome should only be used with heif_chroma = heif_chroma_monochrome
487
489{
499
500
501// ========================= library initialization ======================
502
504{
506
507 // currently no parameters
508};
509
510
532
542void heif_deinit(void);
543
544
545// --- Plugins are currently only supported on Unix platforms.
546
548{
552
554{
555 int version; // version of this info struct
557 const void* plugin;
558 void* internal_handle; // for internal use only
559};
560
562struct heif_error heif_load_plugin(const char* filename, struct heif_plugin_info const** out_plugin);
563
565struct heif_error heif_load_plugins(const char* directory,
566 const struct heif_plugin_info** out_plugins,
567 int* out_nPluginsLoaded,
568 int output_array_size);
569
571struct heif_error heif_unload_plugin(const struct heif_plugin_info* plugin);
572
573// Get a NULL terminated array of the plugin directories that are searched by libheif.
574// This includes the paths specified in the environment variable LIBHEIF_PLUGIN_PATHS and the built-in path
575// (if not overridden by the environment variable).
577const char*const* heif_get_plugin_directories(void);
578
580void heif_free_plugin_directories(const char*const*);
581
582
583// ========================= file type check ======================
584
586{
588 heif_filetype_yes_supported, // it is heif and can be read by libheif
589 heif_filetype_yes_unsupported, // it is heif, but cannot be read by libheif
590 heif_filetype_maybe // not sure whether it is an heif, try detection with more input data
592
593// input data should be at least 12 bytes
595enum heif_filetype_result heif_check_filetype(const uint8_t* data, int len);
596
607struct heif_error heif_has_compatible_filetype(const uint8_t* data, int len);
608
610int heif_check_jpeg_filetype(const uint8_t* data, int len);
611
612
613// DEPRECATED, use heif_brand2 and the heif_brand2_* constants below instead
615{
617 heif_heic, // HEIF image with h265
618 heif_heix, // 10bit images, or anything that uses h265 with range extension
619 heif_hevc, heif_hevx, // brands for image sequences
620 heif_heim, // multiview
621 heif_heis, // scalable
622 heif_hevm, // multiview sequence
623 heif_hevs, // scalable sequence
624 heif_mif1, // image, any coding algorithm
625 heif_msf1, // sequence, any coding algorithm
626 heif_avif, // HEIF image with AV1
628 heif_vvic, // VVC image
629 heif_vvis, // VVC sequence
630 heif_evbi, // EVC image
631 heif_evbs, // EVC sequence
632 heif_j2ki, // JPEG2000 image
633 heif_j2is, // JPEG2000 image sequence
634};
635
636// input data should be at least 12 bytes
637// DEPRECATED, use heif_read_main_brand() instead
639enum heif_brand heif_main_brand(const uint8_t* data, int len);
640
641
642typedef uint32_t heif_brand2;
643
651#define heif_brand2_heic heif_fourcc('h','e','i','c')
652
660#define heif_brand2_heix heif_fourcc('h','e','i','x')
661
669#define heif_brand2_hevc heif_fourcc('h','e','v','c')
670
678#define heif_brand2_hevx heif_fourcc('h','e','v','x')
679
687#define heif_brand2_heim heif_fourcc('h','e','i','m')
688
697#define heif_brand2_heis heif_fourcc('h','e','i','s')
698
706#define heif_brand2_hevm heif_fourcc('h','e','v','m')
707
716#define heif_brand2_hevs heif_fourcc('h','e','v','s')
717
723#define heif_brand2_avif heif_fourcc('a','v','i','f')
724
730#define heif_brand2_avis heif_fourcc('a','v','i','s') // AVIF sequence
731
739#define heif_brand2_mif1 heif_fourcc('m','i','f','1')
740
750#define heif_brand2_mif2 heif_fourcc('m','i','f','2')
751
759#define heif_brand2_msf1 heif_fourcc('m','s','f','1')
760
766#define heif_brand2_vvic heif_fourcc('v','v','i','c')
767
773#define heif_brand2_vvis heif_fourcc('v','v','i','s')
774
780#define heif_brand2_evbi heif_fourcc('e','v','b','i')
781
787#define heif_brand2_evmi heif_fourcc('e','v','m','i')
788
794#define heif_brand2_evbs heif_fourcc('e','v','b','s')
795
801#define heif_brand2_evms heif_fourcc('e','v','m','s')
802
808#define heif_brand2_jpeg heif_fourcc('j','p','e','g')
809
815#define heif_brand2_jpgs heif_fourcc('j','p','g','s')
816
822#define heif_brand2_j2ki heif_fourcc('j','2','k','i')
823
829#define heif_brand2_j2is heif_fourcc('j','2','i','s')
830
838#define heif_brand2_miaf heif_fourcc('m','i','a','f')
839
847#define heif_brand2_1pic heif_fourcc('1','p','i','c')
848
849// input data should be at least 12 bytes
851heif_brand2 heif_read_main_brand(const uint8_t* data, int len);
852
853// 'brand_fourcc' must be 4 character long, but need not be 0-terminated
855heif_brand2 heif_fourcc_to_brand(const char* brand_fourcc);
856
857// the output buffer must be at least 4 bytes long
859void heif_brand_to_fourcc(heif_brand2 brand, char* out_fourcc);
860
861// 'brand_fourcc' must be 4 character long, but need not be 0-terminated
862// returns 1 if file includes the brand, and 0 if it does not
863// returns -1 if the provided data is not sufficient
864// (you should input at least as many bytes as indicated in the first 4 bytes of the file, usually ~50 bytes will do)
865// returns -2 on other errors
867int heif_has_compatible_brand(const uint8_t* data, int len, const char* brand_fourcc);
868
869// Returns an array of compatible brands. The array is allocated by this function and has to be freed with 'heif_free_list_of_compatible_brands()'.
870// The number of entries is returned in out_size.
872struct heif_error heif_list_compatible_brands(const uint8_t* data, int len, heif_brand2** out_brands, int* out_size);
873
876
877
878// Returns one of these MIME types:
879// - image/heic HEIF file using h265 compression
880// - image/heif HEIF file using any other compression
881// - image/heic-sequence HEIF image sequence using h265 compression
882// - image/heif-sequence HEIF image sequence using any other compression
883// - image/avif AVIF image
884// - image/avif-sequence AVIF sequence
885// - image/jpeg JPEG image
886// - image/png PNG image
887// If the format could not be detected, an empty string is returned.
888//
889// Provide at least 12 bytes of input. With less input, its format might not
890// be detected. You may also provide more input to increase detection accuracy.
891//
892// Note that JPEG and PNG images cannot be decoded by libheif even though the
893// formats are detected by this function.
895const char* heif_get_file_mime_type(const uint8_t* data, int len);
896
897
898
899// ========================= heif_context =========================
900// A heif_context represents a HEIF file that has been read.
901// In the future, you will also be able to add pictures to a heif_context
902// and write it into a file again.
903
904
905// Allocate a new context for reading HEIF files.
906// Has to be freed again with heif_context_free().
908struct heif_context* heif_context_alloc(void);
909
910// Free a previously allocated HEIF context. You should not free a context twice.
912void heif_context_free(struct heif_context*);
913
914
915struct heif_reading_options;
916
918{
919 heif_reader_grow_status_size_reached, // requested size has been reached, we can read until this point
920 heif_reader_grow_status_timeout, // size has not been reached yet, but it may still grow further
921 heif_reader_grow_status_size_beyond_eof // size has not been reached and never will. The file has grown to its full size
923
925{
926 // API version supported by this reader
928
929 // --- version 1 functions ---
930 int64_t (* get_position)(void* userdata);
931
932 // The functions read(), and seek() return heif_error_ok on success.
933 // Generally, libheif will make sure that we do not read past the file size.
934 int (* read)(void* data,
935 size_t size,
936 void* userdata);
937
938 int (* seek)(int64_t position,
939 void* userdata);
940
941 // When calling this function, libheif wants to make sure that it can read the file
942 // up to 'target_size'. This is useful when the file is currently downloaded and may
943 // grow with time. You may, for example, extract the image sizes even before the actual
944 // compressed image data has been completely downloaded.
945 //
946 // Even if your input files will not grow, you will have to implement at least
947 // detection whether the target_size is above the (fixed) file length
948 // (in this case, return 'size_beyond_eof').
949 enum heif_reader_grow_status (* wait_for_file_size)(int64_t target_size, void* userdata);
950};
951
952
953// Read a HEIF file from a named disk file.
954// The heif_reading_options should currently be set to NULL.
956struct heif_error heif_context_read_from_file(struct heif_context*, const char* filename,
957 const struct heif_reading_options*);
958
959// Read a HEIF file stored completely in memory.
960// The heif_reading_options should currently be set to NULL.
961// DEPRECATED: use heif_context_read_from_memory_without_copy() instead.
963struct heif_error heif_context_read_from_memory(struct heif_context*,
964 const void* mem, size_t size,
965 const struct heif_reading_options*);
966
967// Same as heif_context_read_from_memory() except that the provided memory is not copied.
968// That means, you will have to keep the memory area alive as long as you use the heif_context.
971 const void* mem, size_t size,
972 const struct heif_reading_options*);
973
975struct heif_error heif_context_read_from_reader(struct heif_context*,
976 const struct heif_reader* reader,
977 void* userdata,
978 const struct heif_reading_options*);
979
980// Number of top-level images in the HEIF file. This does not include the thumbnails or the
981// tile images that are composed to an image grid. You can get access to the thumbnails via
982// the main image handle.
985
987int heif_context_is_top_level_image_ID(struct heif_context* ctx, heif_item_id id);
988
989// Fills in image IDs into the user-supplied int-array 'ID_array', preallocated with 'count' entries.
990// Function returns the total number of IDs filled into the array.
993 heif_item_id* ID_array,
994 int count);
995
997struct heif_error heif_context_get_primary_image_ID(struct heif_context* ctx, heif_item_id* id);
998
999// Get a handle to the primary image of the HEIF file.
1000// This is the image that should be displayed primarily when there are several images in the file.
1003 struct heif_image_handle**);
1004
1005// Get the image handle for a known image ID.
1007struct heif_error heif_context_get_image_handle(struct heif_context* ctx,
1008 heif_item_id id,
1009 struct heif_image_handle**);
1010
1011// Print information about the boxes of a HEIF file to file descriptor.
1012// This is for debugging and informational purposes only. You should not rely on
1013// the output having a specific format. At best, you should not use this at all.
1015void heif_context_debug_dump_boxes_to_file(struct heif_context* ctx, int fd);
1016
1017
1019void heif_context_set_maximum_image_size_limit(struct heif_context* ctx, int maximum_width);
1020
1021// If the maximum threads number is set to 0, the image tiles are decoded in the main thread.
1022// This is different from setting it to 1, which will generate a single background thread to decode the tiles.
1023// Note that this setting only affects libheif itself. The codecs itself may still use multi-threaded decoding.
1024// You can use it, for example, in cases where you are decoding several images in parallel anyway you thus want
1025// to minimize parallelism in each decoder.
1027void heif_context_set_max_decoding_threads(struct heif_context* ctx, int max_threads);
1028
1029
1030// ========================= heif_image_handle =========================
1031
1032// An heif_image_handle is a handle to a logical image in the HEIF file.
1033// To get the actual pixel data, you have to decode the handle to an heif_image.
1034// An heif_image_handle also gives you access to the thumbnails and Exif data
1035// associated with an image.
1036
1037// Once you obtained an heif_image_handle, you can already release the heif_context,
1038// since it is internally ref-counted.
1039
1040// Release image handle.
1042void heif_image_handle_release(const struct heif_image_handle*);
1043
1044// Check whether the given image_handle is the primary image of the file.
1046int heif_image_handle_is_primary_image(const struct heif_image_handle* handle);
1047
1049heif_item_id heif_image_handle_get_item_id(const struct heif_image_handle* handle);
1050
1051// Get the resolution of an image.
1053int heif_image_handle_get_width(const struct heif_image_handle* handle);
1054
1056int heif_image_handle_get_height(const struct heif_image_handle* handle);
1057
1059int heif_image_handle_has_alpha_channel(const struct heif_image_handle*);
1060
1062int heif_image_handle_is_premultiplied_alpha(const struct heif_image_handle*);
1063
1064// Returns -1 on error, e.g. if this information is not present in the image.
1066int heif_image_handle_get_luma_bits_per_pixel(const struct heif_image_handle*);
1067
1068// Returns -1 on error, e.g. if this information is not present in the image.
1070int heif_image_handle_get_chroma_bits_per_pixel(const struct heif_image_handle*);
1071
1072// Return the colorspace that libheif proposes to use for decoding.
1073// Usually, these will be either YCbCr or Monochrome, but it may also propose RGB for images
1074// encoded with matrix_coefficients=0.
1075// It may also return *_undefined if the file misses relevant information to determine this without decoding.
1077struct heif_error heif_image_handle_get_preferred_decoding_colorspace(const struct heif_image_handle* image_handle,
1078 enum heif_colorspace* out_colorspace,
1079 enum heif_chroma* out_chroma);
1080
1081// Get the image width from the 'ispe' box. This is the original image size without
1082// any transformations applied to it. Do not use this unless you know exactly what
1083// you are doing.
1085int heif_image_handle_get_ispe_width(const struct heif_image_handle* handle);
1086
1088int heif_image_handle_get_ispe_height(const struct heif_image_handle* handle);
1089
1090// This gets the context associated with the image handle.
1091// Note that you have to release the returned context with heif_context_free() in any case.
1092//
1093// This means: when you have several image-handles that originate from the same file and you get the
1094// context of each of them, the returned pointer may be different even though it refers to the same
1095// logical context. You have to call heif_context_free() on all those context pointers.
1096// After you freed a context pointer, you can still use the context through a different pointer that you
1097// might have acquired from elsewhere.
1099struct heif_context* heif_image_handle_get_context(const struct heif_image_handle* handle);
1100
1101
1102// ------------------------- depth images -------------------------
1103
1105int heif_image_handle_has_depth_image(const struct heif_image_handle*);
1106
1108int heif_image_handle_get_number_of_depth_images(const struct heif_image_handle* handle);
1109
1111int heif_image_handle_get_list_of_depth_image_IDs(const struct heif_image_handle* handle,
1112 heif_item_id* ids, int count);
1113
1115struct heif_error heif_image_handle_get_depth_image_handle(const struct heif_image_handle* handle,
1116 heif_item_id depth_image_id,
1117 struct heif_image_handle** out_depth_handle);
1118
1119
1121{
1127
1129{
1130 uint8_t version;
1131
1132 // version 1 fields
1133
1134 uint8_t has_z_near;
1135 uint8_t has_z_far;
1136 uint8_t has_d_min;
1137 uint8_t has_d_max;
1138
1139 double z_near;
1140 double z_far;
1141 double d_min;
1142 double d_max;
1143
1146
1149
1150 // version 2 fields below
1151};
1152
1153
1156
1157// Returns true when there is depth_representation_info available
1158// Note 1: depth_image_id is currently unused because we support only one depth channel per image, but
1159// you should still provide the correct ID for future compatibility.
1160// Note 2: Because of an API bug before v1.11.0, the function also works when 'handle' is the handle of the depth image.
1161// However, you should pass the handle of the main image. Please adapt your code if needed.
1163int heif_image_handle_get_depth_image_representation_info(const struct heif_image_handle* handle,
1164 heif_item_id depth_image_id,
1165 const struct heif_depth_representation_info** out);
1166
1167
1168
1169// ------------------------- thumbnails -------------------------
1170
1171// List the number of thumbnails assigned to this image handle. Usually 0 or 1.
1173int heif_image_handle_get_number_of_thumbnails(const struct heif_image_handle* handle);
1174
1176int heif_image_handle_get_list_of_thumbnail_IDs(const struct heif_image_handle* handle,
1177 heif_item_id* ids, int count);
1178
1179// Get the image handle of a thumbnail image.
1181struct heif_error heif_image_handle_get_thumbnail(const struct heif_image_handle* main_image_handle,
1182 heif_item_id thumbnail_id,
1183 struct heif_image_handle** out_thumbnail_handle);
1184
1185
1186// ------------------------- auxiliary images -------------------------
1187
1188#define LIBHEIF_AUX_IMAGE_FILTER_OMIT_ALPHA (1UL<<1)
1189#define LIBHEIF_AUX_IMAGE_FILTER_OMIT_DEPTH (2UL<<1)
1190
1191// List the number of auxiliary images assigned to this image handle.
1193int heif_image_handle_get_number_of_auxiliary_images(const struct heif_image_handle* handle,
1194 int aux_filter);
1195
1197int heif_image_handle_get_list_of_auxiliary_image_IDs(const struct heif_image_handle* handle,
1198 int aux_filter,
1199 heif_item_id* ids, int count);
1200
1201// You are responsible to deallocate the returned buffer with heif_image_handle_release_auxiliary_type().
1203struct heif_error heif_image_handle_get_auxiliary_type(const struct heif_image_handle* handle,
1204 const char** out_type);
1205
1207void heif_image_handle_release_auxiliary_type(const struct heif_image_handle* handle,
1208 const char** out_type);
1209
1210// DEPRECATED (because typo in function name). Use heif_image_handle_release_auxiliary_type() instead.
1212void heif_image_handle_free_auxiliary_types(const struct heif_image_handle* handle,
1213 const char** out_type);
1214
1215// Get the image handle of an auxiliary image.
1217struct heif_error heif_image_handle_get_auxiliary_image_handle(const struct heif_image_handle* main_image_handle,
1218 heif_item_id auxiliary_id,
1219 struct heif_image_handle** out_auxiliary_handle);
1220
1221
1222// ------------------------- metadata (Exif / XMP) -------------------------
1223
1224// How many metadata blocks are attached to an image. If you only want to get EXIF data,
1225// set the type_filter to "Exif". Otherwise, set the type_filter to NULL.
1227int heif_image_handle_get_number_of_metadata_blocks(const struct heif_image_handle* handle,
1228 const char* type_filter);
1229
1230// 'type_filter' can be used to get only metadata of specific types, like "Exif".
1231// If 'type_filter' is NULL, it will return all types of metadata IDs.
1233int heif_image_handle_get_list_of_metadata_block_IDs(const struct heif_image_handle* handle,
1234 const char* type_filter,
1235 heif_item_id* ids, int count);
1236
1237// Return a string indicating the type of the metadata, as specified in the HEIF file.
1238// Exif data will have the type string "Exif".
1239// This string will be valid until the next call to a libheif function.
1240// You do not have to free this string.
1242const char* heif_image_handle_get_metadata_type(const struct heif_image_handle* handle,
1243 heif_item_id metadata_id);
1244
1245// For EXIF, the content type is empty.
1246// For XMP, the content type is "application/rdf+xml".
1248const char* heif_image_handle_get_metadata_content_type(const struct heif_image_handle* handle,
1249 heif_item_id metadata_id);
1250
1251// Get the size of the raw metadata, as stored in the HEIF file.
1253size_t heif_image_handle_get_metadata_size(const struct heif_image_handle* handle,
1254 heif_item_id metadata_id);
1255
1256// 'out_data' must point to a memory area of the size reported by heif_image_handle_get_metadata_size().
1257// The data is returned exactly as stored in the HEIF file.
1258// For Exif data, you probably have to skip the first four bytes of the data, since they
1259// indicate the offset to the start of the TIFF header of the Exif data.
1261struct heif_error heif_image_handle_get_metadata(const struct heif_image_handle* handle,
1262 heif_item_id metadata_id,
1263 void* out_data);
1264
1265// Only valid for item type == "uri ", an absolute URI
1267const char* heif_image_handle_get_metadata_item_uri_type(const struct heif_image_handle* handle,
1268 heif_item_id metadata_id);
1269
1270// ------------------------- color profiles -------------------------
1271
1273{
1277 heif_color_profile_type_prof = heif_fourcc('p', 'r', 'o', 'f')
1279
1280
1281// Returns 'heif_color_profile_type_not_present' if there is no color profile.
1282// If there is an ICC profile and an NCLX profile, the ICC profile is returned.
1283// TODO: we need a new API for this function as images can contain both NCLX and ICC at the same time.
1284// However, you can still use heif_image_handle_get_raw_color_profile() and
1285// heif_image_handle_get_nclx_color_profile() to access both profiles.
1287enum heif_color_profile_type heif_image_handle_get_color_profile_type(const struct heif_image_handle* handle);
1288
1290size_t heif_image_handle_get_raw_color_profile_size(const struct heif_image_handle* handle);
1291
1292// Returns 'heif_error_Color_profile_does_not_exist' when there is no ICC profile.
1294struct heif_error heif_image_handle_get_raw_color_profile(const struct heif_image_handle* handle,
1295 void* out_data);
1296
1297
1299{
1300 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
1313
1315{
1334
1336{
1338 heif_matrix_coefficients_ITU_R_BT_709_5 = 1, // TODO: or 709-6 according to h.273
1342 heif_matrix_coefficients_ITU_R_BT_601_6 = 6, // TODO: or 601-7 according to h.273
1352
1354{
1355 // === version 1 fields
1356
1357 uint8_t version;
1358
1363
1364 // --- decoded values (not used when saving nclx)
1365
1370};
1371
1374
1377
1380
1381// Returns 'heif_error_Color_profile_does_not_exist' when there is no NCLX profile.
1382// TODO: This function does currently not return an NCLX profile if it is stored in the image bitstream.
1383// Only NCLX profiles stored as colr boxes are returned. This may change in the future.
1385struct heif_error heif_image_handle_get_nclx_color_profile(const struct heif_image_handle* handle,
1386 struct heif_color_profile_nclx** out_data);
1387
1388// Returned color profile has 'version' field set to the maximum allowed.
1389// Do not fill values for higher versions as these might be outside the allocated structure size.
1390// May return NULL.
1393
1396
1397
1400
1402size_t heif_image_get_raw_color_profile_size(const struct heif_image* image);
1403
1405struct heif_error heif_image_get_raw_color_profile(const struct heif_image* image,
1406 void* out_data);
1407
1409struct heif_error heif_image_get_nclx_color_profile(const struct heif_image* image,
1410 struct heif_color_profile_nclx** out_data);
1411
1412
1413// ------------------------- intrinsic and extrinsic matrices -------------------------
1414
1416{
1421 double skew;
1422};
1423
1424
1426int heif_image_handle_has_camera_intrinsic_matrix(const struct heif_image_handle* handle);
1427
1429struct heif_error heif_image_handle_get_camera_intrinsic_matrix(const struct heif_image_handle* handle,
1430 struct heif_camera_intrinsic_matrix* out_matrix);
1431
1432
1433struct heif_camera_extrinsic_matrix;
1434
1436int heif_image_handle_has_camera_extrinsic_matrix(const struct heif_image_handle* handle);
1437
1439struct heif_error heif_image_handle_get_camera_extrinsic_matrix(const struct heif_image_handle* handle,
1440 struct heif_camera_extrinsic_matrix** out_matrix);
1441
1443void heif_camera_extrinsic_matrix_release(struct heif_camera_extrinsic_matrix*);
1444
1446struct heif_error heif_camera_extrinsic_matrix_get_rotation_matrix(const struct heif_camera_extrinsic_matrix*,
1447 double* out_matrix_row_major);
1448
1449
1450
1451// ========================= heif_image =========================
1452
1453// An heif_image contains a decoded pixel image in various colorspaces, chroma formats,
1454// and bit depths.
1455
1456// Note: when converting images to an interleaved chroma format, the resulting
1457// image contains only a single channel of type channel_interleaved with, e.g., 3 bytes per pixel,
1458// containing the interleaved R,G,B values.
1459
1460// Planar RGB images are specified as heif_colorspace_RGB / heif_chroma_444.
1461
1463{
1467
1468
1470{
1473
1474 // Combine with 'heif_chroma_upsampling_bilinear' for best quality.
1475 // Makes edges look sharper when using YUV 420 with bilinear chroma upsampling.
1478
1480{
1484
1486{
1487 uint8_t version;
1488
1489 // --- version 1 options
1490
1493
1494 // When set to 'false' libheif may also use a different algorithm if the preferred one is not available
1495 // or using a different algorithm is computationally less complex. Note that currently (v1.17.0) this
1496 // means that for RGB input it will usually choose nearest-neighbor sampling because this is computationally
1497 // the simplest.
1498 // Set this field to 'true' if you want to make sure that the specified algorithm is used even
1499 // at the cost of slightly higher computation times.
1501};
1502
1503
1505{
1506 uint8_t version;
1507
1508 // version 1 options
1509
1510 // Ignore geometric transformations like cropping, rotation, mirroring.
1511 // Default: false (do not ignore).
1513
1514 void (* start_progress)(enum heif_progress_step step, int max_progress, void* progress_user_data);
1515
1516 void (* on_progress)(enum heif_progress_step step, int progress, void* progress_user_data);
1517
1519
1521
1522 // version 2 options
1523
1525
1526 // version 3 options
1527
1528 // When enabled, an error is returned for invalid input. Otherwise, it will try its best and
1529 // add decoding warnings to the decoded heif_image. Default is non-strict.
1531
1532 // version 4 options
1533
1534 // name_id of the decoder to use for the decoding.
1535 // If set to NULL (default), the highest priority decoder is chosen.
1536 // The priority is defined in the plugin.
1537 const char* decoder_id;
1538
1539
1540 // version 5 options
1541
1543};
1544
1545
1546// Allocate decoding options and fill with default values.
1547// Note: you should always get the decoding options through this function since the
1548// option structure may grow in size in future versions.
1551
1554
1555// Decode an heif_image_handle into the actual pixel image and also carry out
1556// all geometric transformations specified in the HEIF file (rotation, cropping, mirroring).
1557//
1558// If colorspace or chroma is set to heif_colorspace_undefined or heif_chroma_undefined,
1559// respectively, the original colorspace is taken.
1560// Decoding options may be NULL. If you want to supply options, always use
1561// heif_decoding_options_alloc() to get the structure.
1563struct heif_error heif_decode_image(const struct heif_image_handle* in_handle,
1564 struct heif_image** out_img,
1565 enum heif_colorspace colorspace,
1566 enum heif_chroma chroma,
1567 const struct heif_decoding_options* options);
1568
1569// Get the colorspace format of the image.
1571enum heif_colorspace heif_image_get_colorspace(const struct heif_image*);
1572
1573// Get the chroma format of the image.
1575enum heif_chroma heif_image_get_chroma_format(const struct heif_image*);
1576
1585int heif_image_get_width(const struct heif_image* img, enum heif_channel channel);
1586
1595int heif_image_get_height(const struct heif_image* img, enum heif_channel channel);
1596
1606int heif_image_get_primary_width(const struct heif_image* img);
1607
1617int heif_image_get_primary_height(const struct heif_image* img);
1618
1620struct heif_error heif_image_crop(struct heif_image* img,
1621 int left, int right, int top, int bottom);
1622
1623// Get the number of bits per pixel in the given image channel. Returns -1 if
1624// a non-existing channel was given.
1625// Note that the number of bits per pixel may be different for each color channel.
1626// This function returns the number of bits used for storage of each pixel.
1627// Especially for HDR images, this is probably not what you want. Have a look at
1628// heif_image_get_bits_per_pixel_range() instead.
1630int heif_image_get_bits_per_pixel(const struct heif_image*, enum heif_channel channel);
1631
1632
1633// Get the number of bits per pixel in the given image channel. This function returns
1634// the number of bits used for representing the pixel value, which might be smaller
1635// than the number of bits used in memory.
1636// For example, in 12bit HDR images, this function returns '12', while still 16 bits
1637// are reserved for storage. For interleaved RGBA with 12 bit, this function also returns
1638// '12', not '48' or '64' (heif_image_get_bits_per_pixel returns 64 in this case).
1640int heif_image_get_bits_per_pixel_range(const struct heif_image*, enum heif_channel channel);
1641
1643int heif_image_has_channel(const struct heif_image*, enum heif_channel channel);
1644
1645// Get a pointer to the actual pixel data.
1646// The 'out_stride' is returned as "bytes per line".
1647// When out_stride is NULL, no value will be written.
1648// Returns NULL if a non-existing channel was given.
1650const uint8_t* heif_image_get_plane_readonly(const struct heif_image*,
1651 enum heif_channel channel,
1652 int* out_stride);
1653
1655uint8_t* heif_image_get_plane(struct heif_image*,
1656 enum heif_channel channel,
1657 int* out_stride);
1658
1659
1660struct heif_scaling_options;
1661
1662// Currently, heif_scaling_options is not defined yet. Pass a NULL pointer.
1664struct heif_error heif_image_scale_image(const struct heif_image* input,
1665 struct heif_image** output,
1666 int width, int height,
1667 const struct heif_scaling_options* options);
1668
1669// The color profile is not attached to the image handle because we might need it
1670// for color space transform and encoding.
1672struct heif_error heif_image_set_raw_color_profile(struct heif_image* image,
1673 const char* profile_type_fourcc_string,
1674 const void* profile_data,
1675 const size_t profile_size);
1676
1678struct heif_error heif_image_set_nclx_color_profile(struct heif_image* image,
1679 const struct heif_color_profile_nclx* color_profile);
1680
1681
1682// TODO: this function does not make any sense yet, since we currently cannot modify existing HEIF files.
1683//LIBHEIF_API
1684//void heif_image_remove_color_profile(struct heif_image* image);
1685
1686// Fills the image decoding warnings into the provided 'out_warnings' array.
1687// The size of the array has to be provided in max_output_buffer_entries.
1688// If max_output_buffer_entries==0, the number of decoder warnings is returned.
1689// The function fills the warnings into the provided buffer, starting with 'first_warning_idx'.
1690// It returns the number of warnings filled into the buffer.
1691// Note: you can iterate through all warnings by using 'max_output_buffer_entries=1' and iterate 'first_warning_idx'.
1693int heif_image_get_decoding_warnings(struct heif_image* image,
1694 int first_warning_idx,
1695 struct heif_error* out_warnings,
1696 int max_output_buffer_entries);
1697
1698// This function is only for decoder plugin implementors.
1700void heif_image_add_decoding_warning(struct heif_image* image,
1701 struct heif_error err);
1702
1703// Release heif_image.
1705void heif_image_release(const struct heif_image*);
1706
1707
1708// Note: a value of 0 for any of these values indicates that the value is undefined.
1709// The unit of these values is Candelas per square meter.
1711{
1714};
1715
1717int heif_image_has_content_light_level(const struct heif_image*);
1718
1720void heif_image_get_content_light_level(const struct heif_image*, struct heif_content_light_level* out);
1721
1723void heif_image_set_content_light_level(const struct heif_image*, const struct heif_content_light_level* in);
1724
1725
1726// 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).
1728{
1735};
1736
1737// The units for max_display_mastering_luminance and min_display_mastering_luminance is Candelas per square meter.
1739{
1746};
1747
1750
1753
1756
1757// Converts the internal numeric representation of heif_mastering_display_colour_volume to the
1758// normalized values, collected in heif_decoded_mastering_display_colour_volume.
1759// Values that are out-of-range are decoded to 0, indicating an undefined value (as specified in ISO/IEC 23008-2).
1763
1765void heif_image_get_pixel_aspect_ratio(const struct heif_image*, uint32_t* aspect_h, uint32_t* aspect_v);
1766
1768void heif_image_set_pixel_aspect_ratio(struct heif_image*, uint32_t aspect_h, uint32_t aspect_v);
1769
1770// ====================================================================================================
1771// Encoding API
1772
1774struct heif_error heif_context_write_to_file(struct heif_context*,
1775 const char* filename);
1776
1778{
1779 // API version supported by this writer
1781
1782 // --- version 1 functions ---
1783 struct heif_error (* write)(struct heif_context* ctx, // TODO: why do we need this parameter?
1784 const void* data,
1785 size_t size,
1786 void* userdata);
1787};
1788
1790struct heif_error heif_context_write(struct heif_context*,
1791 struct heif_writer* writer,
1792 void* userdata);
1793
1794// Add a compatible brand that is now added automatically by libheif when encoding images (e.g. some application brands like 'geo1').
1796void heif_context_add_compatible_brand(struct heif_context* ctx,
1797 heif_brand2 compatible_brand);
1798
1799// ----- encoder -----
1800
1801// The encoder used for actually encoding an image.
1802struct heif_encoder;
1803
1804// A description of the encoder's capabilities and name.
1805struct heif_encoder_descriptor;
1806
1807// A configuration parameter of the encoder. Each encoder implementation may have a different
1808// set of parameters. For the most common settings (e.q. quality), special functions to set
1809// the parameters are provided.
1810struct heif_encoder_parameter;
1811
1812struct heif_decoder_descriptor;
1813
1814// Get a list of available decoders. You can filter the encoders by compression format.
1815// Use format_filter==heif_compression_undefined to get all available decoders.
1816// The returned list of decoders is sorted by their priority (which is a plugin property).
1817// The number of decoders is returned, which are not more than 'count' if (out_decoders != nullptr).
1818// By setting out_decoders==nullptr, you can query the number of decoders, 'count' is ignored.
1821 const struct heif_decoder_descriptor** out_decoders,
1822 int count);
1823
1824// Return a long, descriptive name of the decoder (including version information).
1826const char* heif_decoder_descriptor_get_name(const struct heif_decoder_descriptor*);
1827
1828// Return a short, symbolic name for identifying the decoder.
1829// This name should stay constant over different decoder versions.
1830// Note: the returned ID may be NULL for old plugins that don't support this yet.
1832const char* heif_decoder_descriptor_get_id_name(const struct heif_decoder_descriptor*);
1833
1834// DEPRECATED: use heif_get_encoder_descriptors() instead.
1835// Get a list of available encoders. You can filter the encoders by compression format and name.
1836// Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards.
1837// The returned list of encoders is sorted by their priority (which is a plugin property).
1838// The number of encoders is returned, which are not more than 'count' if (out_encoders != nullptr).
1839// By setting out_encoders==nullptr, you can query the number of encoders, 'count' is ignored.
1840// Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
1842int heif_context_get_encoder_descriptors(struct heif_context*, // TODO: why do we need this parameter?
1843 enum heif_compression_format format_filter,
1844 const char* name_filter,
1845 const struct heif_encoder_descriptor** out_encoders,
1846 int count);
1847
1848// Get a list of available encoders. You can filter the encoders by compression format and name.
1849// Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards.
1850// The returned list of encoders is sorted by their priority (which is a plugin property).
1851// The number of encoders is returned, which are not more than 'count' if (out_encoders != nullptr).
1852// By setting out_encoders==nullptr, you can query the number of encoders, 'count' is ignored.
1853// Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
1856 const char* name_filter,
1857 const struct heif_encoder_descriptor** out_encoders,
1858 int count);
1859
1860// Return a long, descriptive name of the encoder (including version information).
1862const char* heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor*);
1863
1864// Return a short, symbolic name for identifying the encoder.
1865// This name should stay constant over different encoder versions.
1867const char* heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor*);
1868
1871heif_encoder_descriptor_get_compression_format(const struct heif_encoder_descriptor*);
1872
1874int heif_encoder_descriptor_supports_lossy_compression(const struct heif_encoder_descriptor*);
1875
1877int heif_encoder_descriptor_supports_lossless_compression(const struct heif_encoder_descriptor*);
1878
1879
1880// Get an encoder instance that can be used to actually encode images from a descriptor.
1882struct heif_error heif_context_get_encoder(struct heif_context* context,
1883 const struct heif_encoder_descriptor*,
1884 struct heif_encoder** out_encoder);
1885
1886// Quick check whether there is a decoder available for the given format.
1887// Note that the decoder still may not be able to decode all variants of that format.
1888// You will have to query that further (todo) or just try to decode and check the returned error.
1891
1892// Quick check whether there is an enoder available for the given format.
1893// Note that the encoder may be limited to a certain subset of features (e.g. only 8 bit, only lossy).
1894// You will have to query the specific capabilities further.
1897
1898// Get an encoder for the given compression format. If there are several encoder plugins
1899// for this format, the encoder with the highest plugin priority will be returned.
1901struct heif_error heif_context_get_encoder_for_format(struct heif_context* context,
1902 enum heif_compression_format format,
1903 struct heif_encoder**);
1904
1905// You have to release the encoder after use.
1907void heif_encoder_release(struct heif_encoder*);
1908
1909// Get the encoder name from the encoder itself.
1911const char* heif_encoder_get_name(const struct heif_encoder*);
1912
1913
1914// --- Encoder Parameters ---
1915
1916// Libheif supports settings parameters through specialized functions and through
1917// generic functions by parameter name. Sometimes, the same parameter can be set
1918// in both ways.
1919// We consider it best practice to use the generic parameter functions only in
1920// dynamically generated user interfaces, as no guarantees are made that some specific
1921// parameter names are supported by all plugins.
1922
1923
1924// Set a 'quality' factor (0-100). How this is mapped to actual encoding parameters is
1925// encoder dependent.
1927struct heif_error heif_encoder_set_lossy_quality(struct heif_encoder*, int quality);
1928
1930struct heif_error heif_encoder_set_lossless(struct heif_encoder*, int enable);
1931
1932// level should be between 0 (= none) to 4 (= full)
1934struct heif_error heif_encoder_set_logging_level(struct heif_encoder*, int level);
1935
1936// Get a generic list of encoder parameters.
1937// Each encoder may define its own, additional set of parameters.
1938// You do not have to free the returned list.
1940const struct heif_encoder_parameter* const* heif_encoder_list_parameters(struct heif_encoder*);
1941
1942// Return the parameter name.
1944const char* heif_encoder_parameter_get_name(const struct heif_encoder_parameter*);
1945
1946
1948{
1953
1954// Return the parameter type.
1956enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter*);
1957
1958// DEPRECATED. Use heif_encoder_parameter_get_valid_integer_values() instead.
1960struct heif_error heif_encoder_parameter_get_valid_integer_range(const struct heif_encoder_parameter*,
1961 int* have_minimum_maximum,
1962 int* minimum, int* maximum);
1963
1964// If integer is limited by a range, have_minimum and/or have_maximum will be != 0 and *minimum, *maximum is set.
1965// If integer is limited by a fixed set of values, *num_valid_values will be >0 and *out_integer_array is set.
1967struct heif_error heif_encoder_parameter_get_valid_integer_values(const struct heif_encoder_parameter*,
1968 int* have_minimum, int* have_maximum,
1969 int* minimum, int* maximum,
1970 int* num_valid_values,
1971 const int** out_integer_array);
1972
1974struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter*,
1975 const char* const** out_stringarray);
1976
1977
1980 const char* parameter_name,
1981 int value);
1982
1985 const char* parameter_name,
1986 int* value);
1987
1988// TODO: name should be changed to heif_encoder_get_valid_integer_parameter_range
1989LIBHEIF_API // DEPRECATED.
1991 const char* parameter_name,
1992 int* have_minimum_maximum,
1993 int* minimum, int* maximum);
1994
1997 const char* parameter_name,
1998 int value);
1999
2002 const char* parameter_name,
2003 int* value);
2004
2007 const char* parameter_name,
2008 const char* value);
2009
2012 const char* parameter_name,
2013 char* value, int value_size);
2014
2015// returns a NULL-terminated list of valid strings or NULL if all values are allowed
2018 const char* parameter_name,
2019 const char* const** out_stringarray);
2020
2023 const char* parameter_name,
2024 int* have_minimum, int* have_maximum,
2025 int* minimum, int* maximum,
2026 int* num_valid_values,
2027 const int** out_integer_array);
2028
2029// Set a parameter of any type to the string value.
2030// Integer values are parsed from the string.
2031// Boolean values can be "true"/"false"/"1"/"0"
2032//
2033// x265 encoder specific note:
2034// When using the x265 encoder, you may pass any of its parameters by
2035// prefixing the parameter name with 'x265:'. Hence, to set the 'ctu' parameter,
2036// you will have to set 'x265:ctu' in libheif.
2037// Note that there is no checking for valid parameters when using the prefix.
2039struct heif_error heif_encoder_set_parameter(struct heif_encoder*,
2040 const char* parameter_name,
2041 const char* value);
2042
2043// Get the current value of a parameter of any type as a human readable string.
2044// The returned string is compatible with heif_encoder_set_parameter().
2046struct heif_error heif_encoder_get_parameter(struct heif_encoder*,
2047 const char* parameter_name,
2048 char* value_ptr, int value_size);
2049
2050// Query whether a specific parameter has a default value.
2052int heif_encoder_has_default(struct heif_encoder*,
2053 const char* parameter_name);
2054
2055
2056// The orientation values are defined equal to the EXIF Orientation tag.
2058{
2068
2069
2071{
2072 uint8_t version;
2073
2074 // version 1 options
2075
2076 uint8_t save_alpha_channel; // default: true
2077
2078 // version 2 options
2079
2080 // DEPRECATED. This option is not required anymore. Its value will be ignored.
2082
2083 // version 3 options
2084
2086
2087 // version 4 options
2088
2089 // Set this to the NCLX parameters to be used in the output image or set to NULL
2090 // when the same parameters as in the input image should be used.
2092
2094
2095 // version 5 options
2096
2097 // libheif will generate irot/imir boxes to match these orientations
2099
2100 // version 6 options
2101
2103
2104 // version 7 options
2105
2106 // Set this to true to use compressed form of uncC where possible
2108};
2109
2112
2115
2116
2117// Compress the input image.
2118// Returns a handle to the coded image in 'out_image_handle' unless out_image_handle = NULL.
2119// 'options' should be NULL for now.
2120// The first image added to the context is also automatically set the primary image, but
2121// you can change the primary image later with heif_context_set_primary_image().
2123struct heif_error heif_context_encode_image(struct heif_context*,
2124 const struct heif_image* image,
2125 struct heif_encoder* encoder,
2126 const struct heif_encoding_options* options,
2127 struct heif_image_handle** out_image_handle);
2128
2142struct heif_error heif_context_encode_grid(struct heif_context* ctx,
2143 struct heif_image** tiles,
2144 uint16_t rows,
2145 uint16_t columns,
2146 struct heif_encoder* encoder,
2147 const struct heif_encoding_options* input_options,
2148 struct heif_image_handle** out_image_handle);
2149
2151struct heif_error heif_context_set_primary_image(struct heif_context*,
2152 struct heif_image_handle* image_handle);
2153
2154// Encode the 'image' as a scaled down thumbnail image.
2155// The image is scaled down to fit into a square area of width 'bbox_size'.
2156// If the input image is already so small that it fits into this bounding box, no thumbnail
2157// image is encoded and NULL is returned in 'out_thumb_image_handle'.
2158// No error is returned in this case.
2159// The encoded thumbnail is automatically assigned to the 'master_image_handle'. Hence, you
2160// do not have to call heif_context_assign_thumbnail().
2162struct heif_error heif_context_encode_thumbnail(struct heif_context*,
2163 const struct heif_image* image,
2164 const struct heif_image_handle* master_image_handle,
2165 struct heif_encoder* encoder,
2166 const struct heif_encoding_options* options,
2167 int bbox_size,
2168 struct heif_image_handle** out_thumb_image_handle);
2169
2171{
2174 heif_metadata_compression_unknown = 2, // only used when reading unknown method from input file
2176 heif_metadata_compression_zlib = 4, // do not use for header data
2179
2180// Assign 'thumbnail_image' as the thumbnail image of 'master_image'.
2182struct heif_error heif_context_assign_thumbnail(struct heif_context*,
2183 const struct heif_image_handle* master_image,
2184 const struct heif_image_handle* thumbnail_image);
2185
2186// Add EXIF metadata to an image.
2188struct heif_error heif_context_add_exif_metadata(struct heif_context*,
2189 const struct heif_image_handle* image_handle,
2190 const void* data, int size);
2191
2192// Add XMP metadata to an image.
2194struct heif_error heif_context_add_XMP_metadata(struct heif_context*,
2195 const struct heif_image_handle* image_handle,
2196 const void* data, int size);
2197
2198// New version of heif_context_add_XMP_metadata() with data compression (experimental).
2200struct heif_error heif_context_add_XMP_metadata2(struct heif_context*,
2201 const struct heif_image_handle* image_handle,
2202 const void* data, int size,
2203 enum heif_metadata_compression compression);
2204
2205// Add generic, proprietary metadata to an image. You have to specify an 'item_type' that will
2206// identify your metadata. 'content_type' can be an additional type, or it can be NULL.
2207// For example, this function can be used to add IPTC metadata (IIM stream, not XMP) to an image.
2208// Although not standard, we propose to store IPTC data with item type="iptc", content_type=NULL.
2210struct heif_error heif_context_add_generic_metadata(struct heif_context* ctx,
2211 const struct heif_image_handle* image_handle,
2212 const void* data, int size,
2213 const char* item_type, const char* content_type);
2214
2215// Add generic metadata with item_type "uri ". Items with this type do not have a content_type, but
2216// an item_uri_type and they have no content_encoding (they are always stored uncompressed).
2219 const struct heif_image_handle* image_handle,
2220 const void* data, int size,
2221 const char* item_uri_type,
2222 heif_item_id* out_item_id);
2223
2224// --- heif_image allocation
2225
2240struct heif_error heif_image_create(int width, int height,
2241 enum heif_colorspace colorspace,
2242 enum heif_chroma chroma,
2243 struct heif_image** out_image);
2244
2274struct heif_error heif_image_add_plane(struct heif_image* image,
2275 enum heif_channel channel,
2276 int width, int height, int bit_depth);
2277
2278// Signal that the image is premultiplied by the alpha pixel values.
2280void heif_image_set_premultiplied_alpha(struct heif_image* image,
2281 int is_premultiplied_alpha);
2282
2284int heif_image_is_premultiplied_alpha(struct heif_image* image);
2285
2286// This function extends the padding of the image so that it has at least the given physical size.
2287// The padding border is filled with the pixels along the right/bottom border.
2288// This function may be useful if you want to process the image, but have some external padding requirements.
2289// The image size will not be modified if it is already larger/equal than the given physical size.
2290// I.e. you cannot assume that after calling this function, the stride will be equal to min_physical_width.
2292struct heif_error heif_image_extend_padding_to_size(struct heif_image* image, int min_physical_width, int min_physical_height);
2293
2294
2295
2296// --- register plugins
2297
2298struct heif_decoder_plugin;
2299struct heif_encoder_plugin;
2300
2301// DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead.
2303struct heif_error heif_register_decoder(struct heif_context* heif, const struct heif_decoder_plugin*);
2304
2306struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin*);
2307
2309struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin*);
2310
2311// DEPRECATED, typo in function name
2313int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor*);
2314
2315// DEPRECATED, typo in function name
2317int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor*);
2318
2319
2320#ifdef __cplusplus
2321}
2322#endif
2323
2324#endif
struct heif_error heif_encoder_set_parameter_boolean(struct heif_encoder *, const char *parameter_name, int value)
void heif_image_handle_release_auxiliary_type(const struct heif_image_handle *handle, const char **out_type)
int heif_image_handle_has_alpha_channel(const struct heif_image_handle *)
struct heif_error heif_image_create(int width, int height, enum heif_colorspace colorspace, enum heif_chroma chroma, struct heif_image **out_image)
Create a new image of the specified resolution and colorspace.
struct heif_error heif_image_handle_get_metadata(const struct heif_image_handle *handle, heif_item_id metadata_id, void *out_data)
int heif_context_get_number_of_top_level_images(struct heif_context *ctx)
void heif_deinit(void)
Deinitialise and clean up library.
heif_plugin_type
Definition heif.h:548
@ heif_plugin_type_decoder
Definition heif.h:550
@ heif_plugin_type_encoder
Definition heif.h:549
int heif_image_handle_get_height(const struct heif_image_handle *handle)
void heif_image_handle_release(const struct heif_image_handle *)
int heif_encoder_descriptor_supports_lossy_compression(const struct heif_encoder_descriptor *)
uint32_t heif_brand2
Definition heif.h:642
enum heif_colorspace heif_image_get_colorspace(const struct heif_image *)
struct heif_error heif_encoder_get_parameter(struct heif_encoder *, const char *parameter_name, char *value_ptr, int value_size)
struct heif_error heif_encoder_get_parameter_string(struct heif_encoder *, const char *parameter_name, char *value, int value_size)
heif_channel
Definition heif.h:489
@ heif_channel_interleaved
Definition heif.h:497
@ heif_channel_G
Definition heif.h:494
@ heif_channel_Y
Definition heif.h:490
@ heif_channel_Cb
Definition heif.h:491
@ heif_channel_B
Definition heif.h:495
@ heif_channel_R
Definition heif.h:493
@ heif_channel_Alpha
Definition heif.h:496
@ heif_channel_Cr
Definition heif.h:492
heif_item_id heif_image_handle_get_item_id(const struct heif_image_handle *handle)
enum heif_compression_format heif_encoder_descriptor_get_compression_format(const struct heif_encoder_descriptor *)
int heif_image_handle_has_camera_intrinsic_matrix(const struct heif_image_handle *handle)
heif_colorspace
Definition heif.h:465
@ heif_colorspace_monochrome
Definition heif.h:485
@ heif_colorspace_undefined
Definition heif.h:466
@ heif_colorspace_YCbCr
Definition heif.h:472
@ heif_colorspace_RGB
Definition heif.h:482
struct heif_error heif_context_read_from_reader(struct heif_context *, const struct heif_reader *reader, void *userdata, const struct heif_reading_options *)
void heif_image_set_mastering_display_colour_volume(const struct heif_image *, const struct heif_mastering_display_colour_volume *in)
heif_chroma
Definition heif.h:445
@ heif_chroma_interleaved_RGB
Definition heif.h:451
@ heif_chroma_444
Definition heif.h:450
@ heif_chroma_monochrome
Definition heif.h:447
@ heif_chroma_interleaved_RGBA
Definition heif.h:452
@ heif_chroma_interleaved_RRGGBBAA_BE
Definition heif.h:454
@ heif_chroma_422
Definition heif.h:449
@ heif_chroma_interleaved_RRGGBB_BE
Definition heif.h:453
@ heif_chroma_undefined
Definition heif.h:446
@ heif_chroma_interleaved_RRGGBB_LE
Definition heif.h:455
@ heif_chroma_interleaved_RRGGBBAA_LE
Definition heif.h:456
@ heif_chroma_420
Definition heif.h:448
int heif_image_handle_get_width(const struct heif_image_handle *handle)
heif_brand
Definition heif.h:615
@ heif_heic
Definition heif.h:617
@ heif_hevs
Definition heif.h:623
@ heif_mif1
Definition heif.h:624
@ heif_j2is
Definition heif.h:633
@ heif_heix
Definition heif.h:618
@ heif_hevc
Definition heif.h:619
@ heif_avis
Definition heif.h:627
@ heif_evbs
Definition heif.h:631
@ heif_vvic
Definition heif.h:628
@ heif_hevx
Definition heif.h:619
@ heif_heis
Definition heif.h:621
@ heif_msf1
Definition heif.h:625
@ heif_j2ki
Definition heif.h:632
@ heif_evbi
Definition heif.h:630
@ heif_hevm
Definition heif.h:622
@ heif_unknown_brand
Definition heif.h:616
@ heif_vvis
Definition heif.h:629
@ heif_avif
Definition heif.h:626
@ heif_heim
Definition heif.h:620
int heif_image_handle_get_luma_bits_per_pixel(const struct heif_image_handle *)
void heif_context_debug_dump_boxes_to_file(struct heif_context *ctx, int fd)
struct heif_error heif_context_encode_grid(struct heif_context *ctx, struct heif_image **tiles, uint16_t rows, uint16_t columns, struct heif_encoder *encoder, const struct heif_encoding_options *input_options, struct heif_image_handle **out_image_handle)
Encodes an array of images into a grid.
struct heif_error heif_load_plugin(const char *filename, struct heif_plugin_info const **out_plugin)
void heif_context_set_max_decoding_threads(struct heif_context *ctx, int max_threads)
const char * heif_image_handle_get_metadata_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
uint32_t heif_property_id
Definition heif.h:353
int heif_image_get_decoding_warnings(struct heif_image *image, int first_warning_idx, struct heif_error *out_warnings, int max_output_buffer_entries)
struct heif_error heif_encoder_parameter_get_valid_integer_values(const struct heif_encoder_parameter *, int *have_minimum, int *have_maximum, int *minimum, int *maximum, int *num_valid_values, const int **out_integer_array)
int heif_image_handle_has_depth_image(const struct heif_image_handle *)
heif_progress_step
Definition heif.h:1463
@ heif_progress_step_total
Definition heif.h:1464
@ heif_progress_step_load_tile
Definition heif.h:1465
struct heif_context * heif_context_alloc(void)
struct heif_error heif_context_add_exif_metadata(struct heif_context *, const struct heif_image_handle *image_handle, const void *data, int size)
const struct heif_encoder_parameter *const * heif_encoder_list_parameters(struct heif_encoder *)
struct heif_error heif_unload_plugin(const struct heif_plugin_info *plugin)
const char * heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor *)
int heif_image_handle_get_number_of_thumbnails(const struct heif_image_handle *handle)
struct heif_error heif_decode_image(const struct heif_image_handle *in_handle, struct heif_image **out_img, enum heif_colorspace colorspace, enum heif_chroma chroma, const struct heif_decoding_options *options)
int heif_image_has_content_light_level(const struct heif_image *)
struct heif_error heif_image_crop(struct heif_image *img, int left, int right, int top, int bottom)
struct heif_error heif_image_handle_get_camera_extrinsic_matrix(const struct heif_image_handle *handle, struct heif_camera_extrinsic_matrix **out_matrix)
size_t heif_image_handle_get_metadata_size(const struct heif_image_handle *handle, heif_item_id metadata_id)
struct heif_error heif_context_encode_image(struct heif_context *, const struct heif_image *image, struct heif_encoder *encoder, const struct heif_encoding_options *options, struct heif_image_handle **out_image_handle)
enum heif_color_profile_type heif_image_get_color_profile_type(const struct heif_image *image)
struct heif_error heif_nclx_color_profile_set_matrix_coefficients(struct heif_color_profile_nclx *nclx, uint16_t matrix_coefficients)
heif_brand2 heif_read_main_brand(const uint8_t *data, int len)
struct heif_error heif_list_compatible_brands(const uint8_t *data, int len, heif_brand2 **out_brands, int *out_size)
enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter *)
const uint8_t * heif_image_get_plane_readonly(const struct heif_image *, enum heif_channel channel, int *out_stride)
heif_suberror_code
Definition heif.h:141
@ heif_suberror_Encoder_encoding
Definition heif.h:321
@ heif_suberror_No_ipma_box
Definition heif.h:168
@ heif_suberror_No_av1C_box
Definition heif.h:219
@ heif_suberror_Null_pointer_argument
Definition heif.h:267
@ heif_suberror_Invalid_region_data
Definition heif.h:230
@ heif_suberror_Security_limit_exceeded
Definition heif.h:255
@ heif_suberror_Invalid_property
Definition heif.h:285
@ heif_suberror_Item_reference_cycle
Definition heif.h:288
@ heif_suberror_Unsupported_parameter
Definition heif.h:279
@ heif_suberror_No_properties_assigned_to_item
Definition heif.h:184
@ heif_suberror_No_icbr_box
Definition heif.h:245
@ heif_suberror_Plugin_is_not_loaded
Definition heif.h:330
@ heif_suberror_Unsupported_header_compression_method
Definition heif.h:306
@ heif_suberror_Unspecified
Definition heif.h:143
@ heif_suberror_No_pitm_box
Definition heif.h:164
@ heif_suberror_Encoder_initialization
Definition heif.h:320
@ heif_suberror_Unsupported_plugin_version
Definition heif.h:273
@ heif_suberror_Unsupported_color_conversion
Definition heif.h:302
@ heif_suberror_Compression_initialisation_error
Definition heif.h:259
@ heif_suberror_No_item_data
Definition heif.h:187
@ heif_suberror_Unknown_NCLX_matrix_coefficients
Definition heif.h:227
@ heif_suberror_Unknown_color_profile_type
Definition heif.h:209
@ heif_suberror_No_infe_box
Definition heif.h:207
@ heif_suberror_No_idat_box
Definition heif.h:156
@ heif_suberror_Ipma_box_references_nonexisting_property
Definition heif.h:181
@ heif_suberror_Plugin_loading_error
Definition heif.h:329
@ heif_suberror_Unknown_NCLX_transfer_characteristics
Definition heif.h:225
@ heif_suberror_Missing_grid_images
Definition heif.h:193
@ heif_suberror_Unsupported_bit_depth
Definition heif.h:313
@ heif_suberror_No_iinf_box
Definition heif.h:172
@ heif_suberror_Invalid_clean_aperture
Definition heif.h:195
@ heif_suberror_Unsupported_generic_compression_method
Definition heif.h:309
@ heif_suberror_Overlay_image_outside_of_canvas
Definition heif.h:201
@ heif_suberror_No_ipco_box
Definition heif.h:166
@ heif_suberror_No_vvcC_box
Definition heif.h:242
@ heif_suberror_Auxiliary_image_type_unspecified
Definition heif.h:203
@ heif_suberror_Too_many_regions
Definition heif.h:324
@ heif_suberror_No_iref_box
Definition heif.h:176
@ heif_suberror_No_pict_handler
Definition heif.h:178
@ heif_suberror_No_or_invalid_primary_item
Definition heif.h:205
@ heif_suberror_Unsupported_writer_version
Definition heif.h:276
@ heif_suberror_Nonexisting_item_referenced
Definition heif.h:264
@ heif_suberror_Invalid_image_size
Definition heif.h:215
@ heif_suberror_No_iloc_box
Definition heif.h:170
@ heif_suberror_No_iprp_box
Definition heif.h:174
@ heif_suberror_End_of_data
Definition heif.h:148
@ heif_suberror_No_ftyp_box
Definition heif.h:154
@ heif_suberror_Unsupported_codec
Definition heif.h:294
@ heif_suberror_Invalid_grid_data
Definition heif.h:190
@ heif_suberror_Invalid_overlay_data
Definition heif.h:198
@ heif_suberror_Invalid_box_size
Definition heif.h:151
@ heif_suberror_Unsupported_item_construction_method
Definition heif.h:304
@ heif_suberror_No_hdlr_box
Definition heif.h:160
@ heif_suberror_Cannot_read_plugin_directory
Definition heif.h:331
@ heif_suberror_No_ispe_property
Definition heif.h:233
@ heif_suberror_Unknown_NCLX_color_primaries
Definition heif.h:223
@ heif_suberror_Nonexisting_image_channel_referenced
Definition heif.h:270
@ heif_suberror_Wrong_tile_image_chroma_format
Definition heif.h:211
@ heif_suberror_Invalid_J2K_codestream
Definition heif.h:240
@ heif_suberror_Unsupported_data_version
Definition heif.h:299
@ heif_suberror_No_matching_decoder_installed
Definition heif.h:332
@ heif_suberror_Invalid_pixi_box
Definition heif.h:217
@ heif_suberror_Camera_extrinsic_matrix_undefined
Definition heif.h:237
@ heif_suberror_Encoder_cleanup
Definition heif.h:322
@ heif_suberror_Invalid_parameter_value
Definition heif.h:282
@ heif_suberror_Invalid_fractional_number
Definition heif.h:213
@ heif_suberror_Unsupported_image_type
Definition heif.h:297
@ heif_suberror_Camera_intrinsic_matrix_undefined
Definition heif.h:235
@ heif_suberror_Decompression_invalid_data
Definition heif.h:248
@ heif_suberror_No_hvcC_box
Definition heif.h:162
@ heif_suberror_Wrong_tile_image_pixel_depth
Definition heif.h:221
@ heif_suberror_No_meta_box
Definition heif.h:158
@ heif_suberror_Cannot_write_output_data
Definition heif.h:318
int heif_image_handle_get_chroma_bits_per_pixel(const struct heif_image_handle *)
struct heif_error heif_context_get_encoder_for_format(struct heif_context *context, enum heif_compression_format format, struct heif_encoder **)
void heif_image_set_content_light_level(const struct heif_image *, const struct heif_content_light_level *in)
enum heif_color_profile_type heif_image_handle_get_color_profile_type(const struct heif_image_handle *handle)
struct heif_decoding_options * heif_decoding_options_alloc(void)
void heif_image_release(const struct heif_image *)
size_t heif_image_get_raw_color_profile_size(const struct heif_image *image)
int heif_image_handle_has_camera_extrinsic_matrix(const struct heif_image_handle *handle)
void heif_image_get_mastering_display_colour_volume(const struct heif_image *, struct heif_mastering_display_colour_volume *out)
struct heif_error heif_has_compatible_filetype(const uint8_t *data, int len)
Check the filetype box content for a supported file type.
void heif_context_free(struct heif_context *)
void heif_context_set_maximum_image_size_limit(struct heif_context *ctx, int maximum_width)
void heif_decoding_options_free(struct heif_decoding_options *)
struct heif_context * heif_image_handle_get_context(const struct heif_image_handle *handle)
int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor *)
uint8_t * heif_image_get_plane(struct heif_image *, enum heif_channel channel, int *out_stride)
const char * heif_encoder_get_name(const struct heif_encoder *)
int heif_image_get_primary_height(const struct heif_image *img)
Get the height of the main channel.
void heif_image_get_content_light_level(const struct heif_image *, struct heif_content_light_level *out)
struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin *)
struct heif_error heif_image_handle_get_auxiliary_image_handle(const struct heif_image_handle *main_image_handle, heif_item_id auxiliary_id, struct heif_image_handle **out_auxiliary_handle)
heif_error_code
Definition heif.h:101
@ heif_error_Encoding_error
Definition heif.h:130
@ heif_error_Invalid_input
Definition heif.h:109
@ heif_error_Memory_allocation_error
Definition heif.h:121
@ heif_error_Input_does_not_exist
Definition heif.h:106
@ heif_error_Decoder_plugin_error
Definition heif.h:124
@ heif_error_Encoder_plugin_error
Definition heif.h:127
@ heif_error_Plugin_loading_error
Definition heif.h:136
@ heif_error_Unsupported_filetype
Definition heif.h:112
@ heif_error_Ok
Definition heif.h:103
@ heif_error_Unsupported_feature
Definition heif.h:115
@ heif_error_Color_profile_does_not_exist
Definition heif.h:133
@ heif_error_Usage_error
Definition heif.h:118
struct heif_error heif_image_handle_get_camera_intrinsic_matrix(const struct heif_image_handle *handle, struct heif_camera_intrinsic_matrix *out_matrix)
struct heif_error heif_context_add_XMP_metadata(struct heif_context *, const struct heif_image_handle *image_handle, const void *data, int size)
struct heif_error heif_load_plugins(const char *directory, const struct heif_plugin_info **out_plugins, int *out_nPluginsLoaded, int output_array_size)
int heif_get_version_number_maintenance(void)
const char * heif_image_handle_get_metadata_content_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
const char * heif_get_file_mime_type(const uint8_t *data, int len)
struct heif_error heif_context_read_from_file(struct heif_context *, const char *filename, const struct heif_reading_options *)
int heif_image_handle_get_ispe_height(const struct heif_image_handle *handle)
heif_compression_format
libheif known compression formats.
Definition heif.h:363
@ heif_compression_EVC
EVC compression.
Definition heif.h:415
@ heif_compression_JPEG2000
JPEG 2000 compression.
Definition heif.h:422
@ heif_compression_AVC
AVC compression.
Definition heif.h:384
@ heif_compression_uncompressed
Uncompressed encoding.
Definition heif.h:428
@ heif_compression_mask
Mask image encoding.
Definition heif.h:434
@ heif_compression_undefined
Unspecified / undefined compression format.
Definition heif.h:370
@ heif_compression_VVC
VVC compression.
Definition heif.h:407
@ heif_compression_JPEG
JPEG compression.
Definition heif.h:391
@ heif_compression_HEVC
HEVC compression, used for HEIC images.
Definition heif.h:376
@ heif_compression_HTJ2K
High Throughput JPEG 2000 (HT-J2K) compression.
Definition heif.h:441
@ heif_compression_AV1
AV1 compression, used for AVIF images.
Definition heif.h:399
struct heif_error heif_image_get_nclx_color_profile(const struct heif_image *image, struct heif_color_profile_nclx **out_data)
struct heif_error heif_image_get_raw_color_profile(const struct heif_image *image, void *out_data)
const char * heif_decoder_descriptor_get_id_name(const struct heif_decoder_descriptor *)
struct heif_error heif_image_scale_image(const struct heif_image *input, struct heif_image **output, int width, int height, const struct heif_scaling_options *options)
void heif_image_set_premultiplied_alpha(struct heif_image *image, int is_premultiplied_alpha)
enum heif_brand heif_main_brand(const uint8_t *data, int len)
int heif_get_version_number_major(void)
int heif_image_has_channel(const struct heif_image *, enum heif_channel channel)
struct heif_error heif_encoder_set_lossy_quality(struct heif_encoder *, int quality)
int heif_get_decoder_descriptors(enum heif_compression_format format_filter, const struct heif_decoder_descriptor **out_decoders, int count)
struct heif_error heif_encoder_set_logging_level(struct heif_encoder *, int level)
struct heif_error heif_context_get_image_handle(struct heif_context *ctx, heif_item_id id, struct heif_image_handle **)
heif_orientation
Definition heif.h:2058
@ heif_orientation_rotate_180
Definition heif.h:2061
@ heif_orientation_rotate_90_cw_then_flip_horizontally
Definition heif.h:2063
@ heif_orientation_rotate_90_cw_then_flip_vertically
Definition heif.h:2065
@ heif_orientation_flip_vertically
Definition heif.h:2062
@ heif_orientation_rotate_270_cw
Definition heif.h:2066
@ heif_orientation_flip_horizontally
Definition heif.h:2060
@ heif_orientation_normal
Definition heif.h:2059
@ heif_orientation_rotate_90_cw
Definition heif.h:2064
int heif_image_handle_get_number_of_metadata_blocks(const struct heif_image_handle *handle, const char *type_filter)
int heif_context_is_top_level_image_ID(struct heif_context *ctx, heif_item_id id)
struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter *, const char *const **out_stringarray)
struct heif_error heif_encoder_parameter_integer_valid_values(struct heif_encoder *, const char *parameter_name, int *have_minimum, int *have_maximum, int *minimum, int *maximum, int *num_valid_values, const int **out_integer_array)
uint32_t heif_item_id
Definition heif.h:352
uint32_t heif_get_version_number(void)
void heif_encoding_options_free(struct heif_encoding_options *)
void heif_image_get_pixel_aspect_ratio(const struct heif_image *, uint32_t *aspect_h, uint32_t *aspect_v)
struct heif_error heif_encoder_get_parameter_boolean(struct heif_encoder *, const char *parameter_name, int *value)
struct heif_error heif_encoder_parameter_get_valid_integer_range(const struct heif_encoder_parameter *, int *have_minimum_maximum, int *minimum, int *maximum)
struct heif_error heif_context_encode_thumbnail(struct heif_context *, const struct heif_image *image, const struct heif_image_handle *master_image_handle, struct heif_encoder *encoder, const struct heif_encoding_options *options, int bbox_size, struct heif_image_handle **out_thumb_image_handle)
struct heif_error heif_context_get_primary_image_ID(struct heif_context *ctx, heif_item_id *id)
void heif_context_add_compatible_brand(struct heif_context *ctx, heif_brand2 compatible_brand)
int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor *)
struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin *)
heif_reader_grow_status
Definition heif.h:918
@ heif_reader_grow_status_timeout
Definition heif.h:920
@ heif_reader_grow_status_size_beyond_eof
Definition heif.h:921
@ heif_reader_grow_status_size_reached
Definition heif.h:919
void heif_nclx_color_profile_free(struct heif_color_profile_nclx *nclx_profile)
struct heif_error heif_nclx_color_profile_set_color_primaries(struct heif_color_profile_nclx *nclx, uint16_t cp)
struct heif_error heif_context_get_encoder(struct heif_context *context, const struct heif_encoder_descriptor *, struct heif_encoder **out_encoder)
struct heif_error heif_register_decoder(struct heif_context *heif, const struct heif_decoder_plugin *)
int heif_image_get_width(const struct heif_image *img, enum heif_channel channel)
Get the width of a specified image channel.
void heif_image_add_decoding_warning(struct heif_image *image, struct heif_error err)
int heif_encoder_descriptor_supports_lossless_compression(const struct heif_encoder_descriptor *)
struct heif_error heif_context_add_XMP_metadata2(struct heif_context *, const struct heif_image_handle *image_handle, const void *data, int size, enum heif_metadata_compression compression)
int heif_image_handle_get_number_of_depth_images(const struct heif_image_handle *handle)
void heif_camera_extrinsic_matrix_release(struct heif_camera_extrinsic_matrix *)
struct heif_error heif_context_write(struct heif_context *, struct heif_writer *writer, void *userdata)
int heif_image_get_bits_per_pixel(const struct heif_image *, enum heif_channel channel)
int heif_image_handle_get_ispe_width(const struct heif_image_handle *handle)
struct heif_error heif_context_add_generic_uri_metadata(struct heif_context *ctx, const struct heif_image_handle *image_handle, const void *data, int size, const char *item_uri_type, heif_item_id *out_item_id)
int heif_image_handle_get_list_of_thumbnail_IDs(const struct heif_image_handle *handle, heif_item_id *ids, int count)
int heif_have_decoder_for_format(enum heif_compression_format format)
int heif_image_handle_get_number_of_auxiliary_images(const struct heif_image_handle *handle, int aux_filter)
int heif_context_get_list_of_top_level_image_IDs(struct heif_context *ctx, heif_item_id *ID_array, int count)
struct heif_error heif_encoder_set_parameter(struct heif_encoder *, const char *parameter_name, const char *value)
struct heif_error heif_image_handle_get_raw_color_profile(const struct heif_image_handle *handle, void *out_data)
int heif_image_get_height(const struct heif_image *img, enum heif_channel channel)
Get the height of a specified image channel.
size_t heif_image_handle_get_raw_color_profile_size(const struct heif_image_handle *handle)
struct heif_error heif_image_handle_get_nclx_color_profile(const struct heif_image_handle *handle, struct heif_color_profile_nclx **out_data)
struct heif_error heif_image_handle_get_thumbnail(const struct heif_image_handle *main_image_handle, heif_item_id thumbnail_id, struct heif_image_handle **out_thumbnail_handle)
int heif_get_encoder_descriptors(enum heif_compression_format format_filter, const char *name_filter, const struct heif_encoder_descriptor **out_encoders, int count)
int heif_image_handle_get_depth_image_representation_info(const struct heif_image_handle *handle, heif_item_id depth_image_id, const struct heif_depth_representation_info **out)
int heif_image_get_primary_width(const struct heif_image *img)
Get the width of the main channel.
void heif_encoder_release(struct heif_encoder *)
heif_metadata_compression
Definition heif.h:2171
@ heif_metadata_compression_deflate
Definition heif.h:2175
@ heif_metadata_compression_zlib
Definition heif.h:2176
@ heif_metadata_compression_off
Definition heif.h:2172
@ heif_metadata_compression_brotli
Definition heif.h:2177
@ heif_metadata_compression_auto
Definition heif.h:2173
@ heif_metadata_compression_unknown
Definition heif.h:2174
struct heif_error heif_image_extend_padding_to_size(struct heif_image *image, int min_physical_width, int min_physical_height)
const char * heif_get_version(void)
void heif_brand_to_fourcc(heif_brand2 brand, char *out_fourcc)
int heif_image_handle_get_list_of_auxiliary_image_IDs(const struct heif_image_handle *handle, int aux_filter, heif_item_id *ids, int count)
const struct heif_error heif_error_success
void heif_image_handle_free_auxiliary_types(const struct heif_image_handle *handle, const char **out_type)
void heif_free_plugin_directories(const char *const *)
void heif_depth_representation_info_free(const struct heif_depth_representation_info *info)
struct heif_error heif_context_assign_thumbnail(struct heif_context *, const struct heif_image_handle *master_image, const struct heif_image_handle *thumbnail_image)
struct heif_error heif_context_read_from_memory(struct heif_context *, const void *mem, size_t size, const struct heif_reading_options *)
int heif_image_handle_is_premultiplied_alpha(const struct heif_image_handle *)
struct heif_error heif_nclx_color_profile_set_transfer_characteristics(struct heif_color_profile_nclx *nclx, uint16_t transfer_characteristics)
#define LIBHEIF_API
Definition heif.h:69
#define heif_fourcc(a, b, c, d)
Definition heif.h:72
const char * heif_encoder_parameter_get_name(const struct heif_encoder_parameter *)
int heif_image_handle_get_list_of_metadata_block_IDs(const struct heif_image_handle *handle, const char *type_filter, heif_item_id *ids, int count)
struct heif_color_profile_nclx * heif_nclx_color_profile_alloc(void)
struct heif_error heif_image_set_nclx_color_profile(struct heif_image *image, const struct heif_color_profile_nclx *color_profile)
heif_filetype_result
Definition heif.h:586
@ heif_filetype_maybe
Definition heif.h:590
@ heif_filetype_yes_unsupported
Definition heif.h:589
@ heif_filetype_yes_supported
Definition heif.h:588
@ heif_filetype_no
Definition heif.h:587
const char *const * heif_get_plugin_directories(void)
struct heif_error heif_context_get_primary_image_handle(struct heif_context *ctx, struct heif_image_handle **)
heif_depth_representation_type
Definition heif.h:1121
@ heif_depth_representation_type_nonuniform_disparity
Definition heif.h:1125
@ heif_depth_representation_type_uniform_inverse_Z
Definition heif.h:1122
@ heif_depth_representation_type_uniform_disparity
Definition heif.h:1123
@ heif_depth_representation_type_uniform_Z
Definition heif.h:1124
struct heif_error heif_context_write_to_file(struct heif_context *, const char *filename)
struct heif_error heif_encoder_set_parameter_integer(struct heif_encoder *, const char *parameter_name, int value)
const char * heif_image_handle_get_metadata_item_uri_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
struct heif_error heif_encoder_parameter_string_valid_values(struct heif_encoder *, const char *parameter_name, const char *const **out_stringarray)
struct heif_error heif_mastering_display_colour_volume_decode(const struct heif_mastering_display_colour_volume *in, struct heif_decoded_mastering_display_colour_volume *out)
int heif_encoder_has_default(struct heif_encoder *, const char *parameter_name)
struct heif_error heif_image_add_plane(struct heif_image *image, enum heif_channel channel, int width, int height, int bit_depth)
Add an image plane to the image.
struct heif_error heif_camera_extrinsic_matrix_get_rotation_matrix(const struct heif_camera_extrinsic_matrix *, double *out_matrix_row_major)
heif_color_profile_type
Definition heif.h:1273
@ heif_color_profile_type_rICC
Definition heif.h:1276
@ heif_color_profile_type_prof
Definition heif.h:1277
@ heif_color_profile_type_nclx
Definition heif.h:1275
@ heif_color_profile_type_not_present
Definition heif.h:1274
const char * heif_decoder_descriptor_get_name(const struct heif_decoder_descriptor *)
struct heif_error heif_image_handle_get_depth_image_handle(const struct heif_image_handle *handle, heif_item_id depth_image_id, struct heif_image_handle **out_depth_handle)
struct heif_error heif_init(struct heif_init_params *)
Initialise library.
int heif_have_encoder_for_format(enum heif_compression_format format)
struct heif_encoding_options * heif_encoding_options_alloc(void)
enum heif_filetype_result heif_check_filetype(const uint8_t *data, int len)
heif_transfer_characteristics
Definition heif.h:1315
@ heif_transfer_characteristic_linear
Definition heif.h:1322
@ heif_transfer_characteristic_unspecified
Definition heif.h:1317
@ heif_transfer_characteristic_ITU_R_BT_2020_2_12bit
Definition heif.h:1329
@ heif_transfer_characteristic_ITU_R_BT_470_6_System_B_G
Definition heif.h:1319
@ heif_transfer_characteristic_ITU_R_BT_2100_0_PQ
Definition heif.h:1330
@ heif_transfer_characteristic_ITU_R_BT_2100_0_HLG
Definition heif.h:1332
@ heif_transfer_characteristic_SMPTE_ST_428_1
Definition heif.h:1331
@ heif_transfer_characteristic_ITU_R_BT_709_5
Definition heif.h:1316
@ heif_transfer_characteristic_ITU_R_BT_1361
Definition heif.h:1326
@ heif_transfer_characteristic_IEC_61966_2_1
Definition heif.h:1327
@ heif_transfer_characteristic_SMPTE_240M
Definition heif.h:1321
@ heif_transfer_characteristic_logarithmic_100_sqrt10
Definition heif.h:1324
@ heif_transfer_characteristic_ITU_R_BT_601_6
Definition heif.h:1320
@ heif_transfer_characteristic_IEC_61966_2_4
Definition heif.h:1325
@ heif_transfer_characteristic_logarithmic_100
Definition heif.h:1323
@ heif_transfer_characteristic_ITU_R_BT_2020_2_10bit
Definition heif.h:1328
@ heif_transfer_characteristic_ITU_R_BT_470_6_System_M
Definition heif.h:1318
const char * heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor *)
int heif_context_get_encoder_descriptors(struct heif_context *, enum heif_compression_format format_filter, const char *name_filter, const struct heif_encoder_descriptor **out_encoders, int count)
struct heif_error heif_context_add_generic_metadata(struct heif_context *ctx, const struct heif_image_handle *image_handle, const void *data, int size, const char *item_type, const char *content_type)
struct heif_error heif_context_set_primary_image(struct heif_context *, struct heif_image_handle *image_handle)
heif_brand2 heif_fourcc_to_brand(const char *brand_fourcc)
int heif_image_handle_is_primary_image(const struct heif_image_handle *handle)
enum heif_chroma heif_image_get_chroma_format(const struct heif_image *)
struct heif_error heif_encoder_set_parameter_string(struct heif_encoder *, const char *parameter_name, const char *value)
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)
struct heif_error heif_image_handle_get_auxiliary_type(const struct heif_image_handle *handle, const char **out_type)
int heif_image_is_premultiplied_alpha(struct heif_image *image)
int heif_check_jpeg_filetype(const uint8_t *data, int len)
void heif_image_set_pixel_aspect_ratio(struct heif_image *, uint32_t aspect_h, uint32_t aspect_v)
struct heif_error heif_encoder_parameter_integer_valid_range(struct heif_encoder *, const char *parameter_name, int *have_minimum_maximum, int *minimum, int *maximum)
int heif_has_compatible_brand(const uint8_t *data, int len, const char *brand_fourcc)
heif_chroma_upsampling_algorithm
Definition heif.h:1480
@ heif_chroma_upsampling_bilinear
Definition heif.h:1482
@ heif_chroma_upsampling_nearest_neighbor
Definition heif.h:1481
heif_chroma_downsampling_algorithm
Definition heif.h:1470
@ heif_chroma_downsampling_nearest_neighbor
Definition heif.h:1471
@ heif_chroma_downsampling_sharp_yuv
Definition heif.h:1476
@ heif_chroma_downsampling_average
Definition heif.h:1472
int heif_get_version_number_minor(void)
struct heif_error heif_encoder_set_lossless(struct heif_encoder *, int enable)
struct heif_error heif_encoder_get_parameter_integer(struct heif_encoder *, const char *parameter_name, int *value)
void heif_free_list_of_compatible_brands(heif_brand2 *brands_list)
heif_encoder_parameter_type
Definition heif.h:1948
@ heif_encoder_parameter_type_boolean
Definition heif.h:1950
@ heif_encoder_parameter_type_integer
Definition heif.h:1949
@ heif_encoder_parameter_type_string
Definition heif.h:1951
int heif_image_has_mastering_display_colour_volume(const struct heif_image *)
heif_matrix_coefficients
Definition heif.h:1336
@ heif_matrix_coefficients_chromaticity_derived_non_constant_luminance
Definition heif.h:1348
@ heif_matrix_coefficients_ITU_R_BT_601_6
Definition heif.h:1342
@ heif_matrix_coefficients_US_FCC_T47
Definition heif.h:1340
@ heif_matrix_coefficients_chromaticity_derived_constant_luminance
Definition heif.h:1349
@ heif_matrix_coefficients_RGB_GBR
Definition heif.h:1337
@ heif_matrix_coefficients_ITU_R_BT_2020_2_constant_luminance
Definition heif.h:1346
@ heif_matrix_coefficients_ICtCp
Definition heif.h:1350
@ heif_matrix_coefficients_ITU_R_BT_470_6_System_B_G
Definition heif.h:1341
@ heif_matrix_coefficients_unspecified
Definition heif.h:1339
@ heif_matrix_coefficients_YCgCo
Definition heif.h:1344
@ heif_matrix_coefficients_SMPTE_240M
Definition heif.h:1343
@ heif_matrix_coefficients_ITU_R_BT_2020_2_non_constant_luminance
Definition heif.h:1345
@ heif_matrix_coefficients_SMPTE_ST_2085
Definition heif.h:1347
@ heif_matrix_coefficients_ITU_R_BT_709_5
Definition heif.h:1338
int heif_image_handle_get_list_of_depth_image_IDs(const struct heif_image_handle *handle, heif_item_id *ids, int count)
struct heif_error heif_context_read_from_memory_without_copy(struct heif_context *, const void *mem, size_t size, const struct heif_reading_options *)
heif_color_primaries
Definition heif.h:1299
@ heif_color_primaries_SMPTE_ST_428_1
Definition heif.h:1308
@ heif_color_primaries_ITU_R_BT_709_5
Definition heif.h:1300
@ heif_color_primaries_generic_film
Definition heif.h:1306
@ heif_color_primaries_EBU_Tech_3213_E
Definition heif.h:1311
@ heif_color_primaries_ITU_R_BT_601_6
Definition heif.h:1304
@ heif_color_primaries_ITU_R_BT_470_6_System_M
Definition heif.h:1302
@ heif_color_primaries_unspecified
Definition heif.h:1301
@ heif_color_primaries_SMPTE_240M
Definition heif.h:1305
@ heif_color_primaries_ITU_R_BT_470_6_System_B_G
Definition heif.h:1303
@ heif_color_primaries_ITU_R_BT_2020_2_and_2100_0
Definition heif.h:1307
@ heif_color_primaries_SMPTE_EG_432_1
Definition heif.h:1310
@ heif_color_primaries_SMPTE_RP_431_2
Definition heif.h:1309
int heif_image_get_bits_per_pixel_range(const struct heif_image *, enum heif_channel channel)
struct heif_error heif_image_set_raw_color_profile(struct heif_image *image, const char *profile_type_fourcc_string, const void *profile_data, const size_t profile_size)
Definition heif.h:1416
double principal_point_x
Definition heif.h:1419
double focal_length_y
Definition heif.h:1418
double principal_point_y
Definition heif.h:1420
double skew
Definition heif.h:1421
double focal_length_x
Definition heif.h:1417
Definition heif.h:1486
uint8_t only_use_preferred_chroma_algorithm
Definition heif.h:1500
uint8_t version
Definition heif.h:1487
enum heif_chroma_upsampling_algorithm preferred_chroma_upsampling_algorithm
Definition heif.h:1492
enum heif_chroma_downsampling_algorithm preferred_chroma_downsampling_algorithm
Definition heif.h:1491
Definition heif.h:1354
enum heif_transfer_characteristics transfer_characteristics
Definition heif.h:1360
float color_primary_green_x
Definition heif.h:1367
enum heif_matrix_coefficients matrix_coefficients
Definition heif.h:1361
float color_primary_blue_x
Definition heif.h:1368
float color_primary_white_y
Definition heif.h:1369
float color_primary_red_x
Definition heif.h:1366
float color_primary_red_y
Definition heif.h:1366
float color_primary_white_x
Definition heif.h:1369
enum heif_color_primaries color_primaries
Definition heif.h:1359
float color_primary_green_y
Definition heif.h:1367
uint8_t version
Definition heif.h:1357
float color_primary_blue_y
Definition heif.h:1368
uint8_t full_range_flag
Definition heif.h:1362
Definition heif.h:1711
uint16_t max_content_light_level
Definition heif.h:1712
uint16_t max_pic_average_light_level
Definition heif.h:1713
double min_display_mastering_luminance
Definition heif.h:1745
float white_point_y
Definition heif.h:1743
float display_primaries_y[3]
Definition heif.h:1741
double max_display_mastering_luminance
Definition heif.h:1744
float white_point_x
Definition heif.h:1742
float display_primaries_x[3]
Definition heif.h:1740
Definition heif.h:1505
void(* start_progress)(enum heif_progress_step step, int max_progress, void *progress_user_data)
Definition heif.h:1514
void(* on_progress)(enum heif_progress_step step, int progress, void *progress_user_data)
Definition heif.h:1516
uint8_t convert_hdr_to_8bit
Definition heif.h:1524
const char * decoder_id
Definition heif.h:1537
uint8_t ignore_transformations
Definition heif.h:1512
void * progress_user_data
Definition heif.h:1520
uint8_t version
Definition heif.h:1506
void(* end_progress)(enum heif_progress_step step, void *progress_user_data)
Definition heif.h:1518
struct heif_color_conversion_options color_conversion_options
Definition heif.h:1542
uint8_t strict_decoding
Definition heif.h:1530
Definition heif.h:1129
uint8_t * depth_nonlinear_representation_model
Definition heif.h:1148
double z_near
Definition heif.h:1139
double d_min
Definition heif.h:1141
double d_max
Definition heif.h:1142
enum heif_depth_representation_type depth_representation_type
Definition heif.h:1144
uint8_t has_z_far
Definition heif.h:1135
uint32_t disparity_reference_view
Definition heif.h:1145
double z_far
Definition heif.h:1140
uint32_t depth_nonlinear_representation_model_size
Definition heif.h:1147
uint8_t has_z_near
Definition heif.h:1134
uint8_t has_d_min
Definition heif.h:1136
uint8_t version
Definition heif.h:1130
uint8_t has_d_max
Definition heif.h:1137
Definition heif.h:2071
enum heif_orientation image_orientation
Definition heif.h:2098
uint8_t prefer_uncC_short_form
Definition heif.h:2107
uint8_t save_alpha_channel
Definition heif.h:2076
uint8_t version
Definition heif.h:2072
uint8_t macOS_compatibility_workaround_no_nclx_profile
Definition heif.h:2093
uint8_t macOS_compatibility_workaround
Definition heif.h:2081
uint8_t save_two_colr_boxes_when_ICC_and_nclx_available
Definition heif.h:2085
struct heif_color_profile_nclx * output_nclx_profile
Definition heif.h:2091
struct heif_color_conversion_options color_conversion_options
Definition heif.h:2102
Definition heif.h:337
const char * message
Definition heif.h:345
enum heif_suberror_code subcode
Definition heif.h:342
enum heif_error_code code
Definition heif.h:339
Definition heif.h:504
int version
Definition heif.h:505
uint16_t white_point_y
Definition heif.h:1732
uint16_t display_primaries_y[3]
Definition heif.h:1730
uint32_t min_display_mastering_luminance
Definition heif.h:1734
uint32_t max_display_mastering_luminance
Definition heif.h:1733
uint16_t white_point_x
Definition heif.h:1731
uint16_t display_primaries_x[3]
Definition heif.h:1729
Definition heif.h:554
void * internal_handle
Definition heif.h:558
const void * plugin
Definition heif.h:557
int version
Definition heif.h:555
enum heif_plugin_type type
Definition heif.h:556
Definition heif.h:925
int reader_api_version
Definition heif.h:927
enum heif_reader_grow_status(* wait_for_file_size)(int64_t target_size, void *userdata)
Definition heif.h:949
int64_t(* get_position)(void *userdata)
Definition heif.h:930
int(* read)(void *data, size_t size, void *userdata)
Definition heif.h:934
int(* seek)(int64_t position, void *userdata)
Definition heif.h:938
Definition heif.h:1778
struct heif_error(* write)(struct heif_context *ctx, const void *data, size_t size, void *userdata)
Definition heif.h:1783
int writer_api_version
Definition heif.h:1780