libheif
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
25 extern "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 // 1.18 5 7 1 1 1 1
56 // 1.19 6 7 2 1 1 1
57 
58 #if (defined(_WIN32) || defined __CYGWIN__) && !defined(LIBHEIF_STATIC_BUILD)
59 #ifdef LIBHEIF_EXPORTS
60 #define LIBHEIF_API __declspec(dllexport)
61 #else
62 #define LIBHEIF_API __declspec(dllimport)
63 #endif
64 #elif defined(HAVE_VISIBILITY) && HAVE_VISIBILITY
65 #ifdef LIBHEIF_EXPORTS
66 #define LIBHEIF_API __attribute__((__visibility__("default")))
67 #else
68 #define LIBHEIF_API
69 #endif
70 #else
71 #define LIBHEIF_API
72 #endif
73 
74 #define heif_fourcc(a, b, c, d) ((uint32_t)((a<<24) | (b<<16) | (c<<8) | d))
75 
76 
77 /* === version numbers === */
78 
79 // Version string of linked libheif library.
80 LIBHEIF_API const char* heif_get_version(void);
81 
82 // Numeric version of linked libheif library, encoded as 0xHHMMLL00 = hh.mm.ll, where hh, mm, ll is the decimal representation of HH, MM, LL.
83 // For example: 0x02150300 is version 2.21.3
85 
86 // Numeric part "HH" from above. Returned as a decimal number.
88 // Numeric part "MM" from above. Returned as a decimal number.
90 // Numeric part "LL" from above. Returned as a decimal number.
92 
93 // Helper macros to check for given versions of libheif at compile time.
94 #define LIBHEIF_MAKE_VERSION(h, m, l) ((h) << 24 | (m) << 16 | (l) << 8)
95 #define LIBHEIF_HAVE_VERSION(h, m, l) (LIBHEIF_NUMERIC_VERSION >= LIBHEIF_MAKE_VERSION(h, m, l))
96 
97 struct heif_context;
98 struct heif_image_handle;
99 struct heif_image;
100 
101 
103 {
104  // Everything ok, no error occurred.
106 
107  // Input file does not exist.
109 
110  // Error in input file. Corrupted or invalid content.
112 
113  // Input file type is not supported.
115 
116  // Image requires an unsupported decoder feature.
118 
119  // Library API has been used in an invalid way.
121 
122  // Could not allocate enough memory.
124 
125  // The decoder plugin generated an error
127 
128  // The encoder plugin generated an error
130 
131  // Error during encoding or when writing to the output
133 
134  // Application has asked for a color profile type that does not exist
136 
137  // Error loading a dynamic plugin
139 
140  // Operation has been canceled
142 };
143 
144 
146 {
147  // no further information available
149 
150  // --- Invalid_input ---
151 
152  // End of data reached unexpectedly.
154 
155  // Size of box (defined in header) is wrong
157 
158  // Mandatory 'ftyp' box is missing
160 
162 
164 
166 
168 
170 
172 
174 
176 
178 
180 
182 
184 
185  // An item property referenced in the 'ipma' box is not existing in the 'ipco' container.
187 
188  // No properties have been assigned to an item.
190 
191  // Image has no (compressed) data
193 
194  // Invalid specification of image grid (tiled image)
196 
197  // Tile-images in a grid image are missing
199 
201 
202  // Invalid specification of overlay image
204 
205  // Overlay image completely outside of visible canvas area
207 
209 
211 
213 
215 
217 
219 
221 
223 
225 
227 
229 
231 
233 
234  // Invalid specification of region item
236 
237  // Image has no ispe property
239 
241 
243 
244  // Invalid JPEG 2000 codestream - usually a missing marker
246 
248 
249  // icbr is only needed in some situations, this error is for those cases
251 
253 
254  // we got a mini box, but could not read it properly
256 
257  // Decompressing generic compression or header compression data failed (e.g. bitstream corruption)
259 
260  // --- Memory_allocation_error ---
261 
262  // A security limit preventing unreasonable memory allocations was exceeded by the input file.
263  // Please check whether the file is valid. If it is, contact us so that we could increase the
264  // security limits further.
266 
267  // There was an error from the underlying compression / decompression library.
268  // One possibility is lack of resources (e.g. memory).
270 
271  // --- Usage_error ---
272 
273  // An item ID was used that is not present in the file.
274  heif_suberror_Nonexisting_item_referenced = 2000, // also used for Invalid_input
275 
276  // An API argument was given a NULL pointer, which is not allowed for that function.
278 
279  // Image channel referenced that does not exist in the image
281 
282  // The version of the passed plugin is not supported.
284 
285  // The version of the passed writer is not supported.
287 
288  // The given (encoder) parameter name does not exist.
290 
291  // The value for the given parameter is not in the valid range.
293 
294  // Error in property specification
296 
297  // Image reference cycle found in iref
299 
300 
301  // --- Unsupported_feature ---
302 
303  // Image was coded with an unsupported compression method.
305 
306  // Image is specified in an unknown way, e.g. as tiled grid image (which is supported)
308 
310 
311  // The conversion of the source image to the requested chroma / colorspace is not supported.
313 
315 
317 
318  // Generically compressed data used an unsupported compression method
320 
322 
323  // --- Encoder_plugin_error ---
324 
326 
327 
328  // --- Encoding_error ---
329 
331 
335 
337 
338 
339  // --- Plugin loading error ---
340 
341  heif_suberror_Plugin_loading_error = 6000, // a specific plugin file cannot be loaded
342  heif_suberror_Plugin_is_not_loaded = 6001, // trying to remove a plugin that is not loaded
343  heif_suberror_Cannot_read_plugin_directory = 6002, // error while scanning the directory for plugins
344  heif_suberror_No_matching_decoder_installed = 6003 // no decoder found for that compression format
345 };
346 
347 
349 {
350  // main error category
351  enum heif_error_code code;
352 
353  // more detailed error code
355 
356  // textual error message (is always defined, you do not have to check for NULL)
357  const char* message;
358 };
359 
360 // Default success return value. Intended for use in user-supplied callback functions.
361 LIBHEIF_API extern const struct heif_error heif_error_success;
362 
363 
364 typedef uint32_t heif_item_id;
365 typedef uint32_t heif_property_id;
366 
367 
368 
369 // ========================= enum types ======================
370 
375 {
454 };
455 
457 {
465  heif_chroma_interleaved_RRGGBB_BE = 12, // HDR, big endian.
466  heif_chroma_interleaved_RRGGBBAA_BE = 13, // HDR, big endian.
467  heif_chroma_interleaved_RRGGBB_LE = 14, // HDR, little endian.
468  heif_chroma_interleaved_RRGGBBAA_LE = 15 // HDR, little endian.
469 };
470 
471 // DEPRECATED ENUM NAMES
472 #define heif_chroma_interleaved_24bit heif_chroma_interleaved_RGB
473 #define heif_chroma_interleaved_32bit heif_chroma_interleaved_RGBA
474 
475 
477 {
479 
480  // heif_colorspace_YCbCr should be used with one of these heif_chroma values:
481  // * heif_chroma_444
482  // * heif_chroma_422
483  // * heif_chroma_420
485 
486  // heif_colorspace_RGB should be used with one of these heif_chroma values:
487  // * heif_chroma_444 (for planar RGB)
488  // * heif_chroma_interleaved_RGB
489  // * heif_chroma_interleaved_RGBA
490  // * heif_chroma_interleaved_RRGGBB_BE
491  // * heif_chroma_interleaved_RRGGBBAA_BE
492  // * heif_chroma_interleaved_RRGGBB_LE
493  // * heif_chroma_interleaved_RRGGBBAA_LE
495 
496  // heif_colorspace_monochrome should only be used with heif_chroma = heif_chroma_monochrome
498 
499  // Indicates that this image has no visual channels.
501 };
502 
504 {
516 };
517 
519 {
522  heif_metadata_compression_unknown = 2, // only used when reading unknown method from input file
524  heif_metadata_compression_zlib = 4, // do not use for header data
526 };
527 
528 // ========================= library initialization ======================
529 
531 {
532  int version;
533 
534  // currently no parameters
535 };
536 
537 
558 struct heif_error heif_init(struct heif_init_params*);
559 
573 void heif_deinit(void);
574 
575 
576 // --- Plugins are currently only supported on Unix platforms.
577 
579 {
582 };
583 
585 {
586  int version; // version of this info struct
587  enum heif_plugin_type type;
588  const void* plugin;
589  void* internal_handle; // for internal use only
590 };
591 
593 struct heif_error heif_load_plugin(const char* filename, struct heif_plugin_info const** out_plugin);
594 
596 struct heif_error heif_load_plugins(const char* directory,
597  const struct heif_plugin_info** out_plugins,
598  int* out_nPluginsLoaded,
599  int output_array_size);
600 
602 struct heif_error heif_unload_plugin(const struct heif_plugin_info* plugin);
603 
604 // Get a NULL terminated array of the plugin directories that are searched by libheif.
605 // This includes the paths specified in the environment variable LIBHEIF_PLUGIN_PATHS and the built-in path
606 // (if not overridden by the environment variable).
608 const char*const* heif_get_plugin_directories(void);
609 
611 void heif_free_plugin_directories(const char*const*);
612 
613 
614 // ========================= file type check ======================
615 
617 {
619  heif_filetype_yes_supported, // it is heif and can be read by libheif
620  heif_filetype_yes_unsupported, // it is heif, but cannot be read by libheif
621  heif_filetype_maybe // not sure whether it is an heif, try detection with more input data
622 };
623 
624 // input data should be at least 12 bytes
626 enum heif_filetype_result heif_check_filetype(const uint8_t* data, int len);
627 
638 struct heif_error heif_has_compatible_filetype(const uint8_t* data, int len);
639 
641 int heif_check_jpeg_filetype(const uint8_t* data, int len);
642 
643 
644 // DEPRECATED, use heif_brand2 and the heif_brand2_* constants below instead
646 {
648  heif_heic, // HEIF image with h265
649  heif_heix, // 10bit images, or anything that uses h265 with range extension
650  heif_hevc, heif_hevx, // brands for image sequences
651  heif_heim, // multiview
652  heif_heis, // scalable
653  heif_hevm, // multiview sequence
654  heif_hevs, // scalable sequence
655  heif_mif1, // image, any coding algorithm
656  heif_msf1, // sequence, any coding algorithm
657  heif_avif, // HEIF image with AV1
659  heif_vvic, // VVC image
660  heif_vvis, // VVC sequence
661  heif_evbi, // EVC image
662  heif_evbs, // EVC sequence
663  heif_j2ki, // JPEG2000 image
664  heif_j2is, // JPEG2000 image sequence
665 };
666 
667 // input data should be at least 12 bytes
668 // DEPRECATED, use heif_read_main_brand() instead
670 enum heif_brand heif_main_brand(const uint8_t* data, int len);
671 
672 
673 typedef uint32_t heif_brand2;
674 
682 #define heif_brand2_heic heif_fourcc('h','e','i','c')
683 
691 #define heif_brand2_heix heif_fourcc('h','e','i','x')
692 
700 #define heif_brand2_hevc heif_fourcc('h','e','v','c')
701 
709 #define heif_brand2_hevx heif_fourcc('h','e','v','x')
710 
718 #define heif_brand2_heim heif_fourcc('h','e','i','m')
719 
728 #define heif_brand2_heis heif_fourcc('h','e','i','s')
729 
737 #define heif_brand2_hevm heif_fourcc('h','e','v','m')
738 
747 #define heif_brand2_hevs heif_fourcc('h','e','v','s')
748 
754 #define heif_brand2_avif heif_fourcc('a','v','i','f')
755 
761 #define heif_brand2_avis heif_fourcc('a','v','i','s') // AVIF sequence
762 
770 #define heif_brand2_mif1 heif_fourcc('m','i','f','1')
771 
781 #define heif_brand2_mif2 heif_fourcc('m','i','f','2')
782 
788 #define heif_brand2_mif3 heif_fourcc('m','i','f','3')
789 
797 #define heif_brand2_msf1 heif_fourcc('m','s','f','1')
798 
804 #define heif_brand2_vvic heif_fourcc('v','v','i','c')
805 
811 #define heif_brand2_vvis heif_fourcc('v','v','i','s')
812 
818 #define heif_brand2_evbi heif_fourcc('e','v','b','i')
819 
825 #define heif_brand2_evmi heif_fourcc('e','v','m','i')
826 
832 #define heif_brand2_evbs heif_fourcc('e','v','b','s')
833 
839 #define heif_brand2_evms heif_fourcc('e','v','m','s')
840 
846 #define heif_brand2_jpeg heif_fourcc('j','p','e','g')
847 
853 #define heif_brand2_jpgs heif_fourcc('j','p','g','s')
854 
860 #define heif_brand2_j2ki heif_fourcc('j','2','k','i')
861 
867 #define heif_brand2_j2is heif_fourcc('j','2','i','s')
868 
876 #define heif_brand2_miaf heif_fourcc('m','i','a','f')
877 
885 #define heif_brand2_1pic heif_fourcc('1','p','i','c')
886 
887 // input data should be at least 12 bytes
889 heif_brand2 heif_read_main_brand(const uint8_t* data, int len);
890 
891 // input data should be at least 16 bytes
893 heif_brand2 heif_read_minor_version_brand(const uint8_t* data, int len);
894 
895 // 'brand_fourcc' must be 4 character long, but need not be 0-terminated
897 heif_brand2 heif_fourcc_to_brand(const char* brand_fourcc);
898 
899 // the output buffer must be at least 4 bytes long
901 void heif_brand_to_fourcc(heif_brand2 brand, char* out_fourcc);
902 
903 // 'brand_fourcc' must be 4 character long, but need not be 0-terminated
904 // returns 1 if file includes the brand, and 0 if it does not
905 // returns -1 if the provided data is not sufficient
906 // (you should input at least as many bytes as indicated in the first 4 bytes of the file, usually ~50 bytes will do)
907 // returns -2 on other errors
909 int heif_has_compatible_brand(const uint8_t* data, int len, const char* brand_fourcc);
910 
911 // 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()'.
912 // The number of entries is returned in out_size.
914 struct heif_error heif_list_compatible_brands(const uint8_t* data, int len, heif_brand2** out_brands, int* out_size);
915 
918 
919 
920 // Returns one of these MIME types:
921 // - image/heic HEIF file using h265 compression
922 // - image/heif HEIF file using any other compression
923 // - image/heic-sequence HEIF image sequence using h265 compression
924 // - image/heif-sequence HEIF image sequence using any other compression
925 // - image/avif AVIF image
926 // - image/avif-sequence AVIF sequence
927 // - image/jpeg JPEG image
928 // - image/png PNG image
929 // If the format could not be detected, an empty string is returned.
930 //
931 // Provide at least 12 bytes of input. With less input, its format might not
932 // be detected. You may also provide more input to increase detection accuracy.
933 //
934 // Note that JPEG and PNG images cannot be decoded by libheif even though the
935 // formats are detected by this function.
937 const char* heif_get_file_mime_type(const uint8_t* data, int len);
938 
939 
940 
941 // ========================= heif_context =========================
942 // A heif_context represents a HEIF file that has been read.
943 // In the future, you will also be able to add pictures to a heif_context
944 // and write it into a file again.
945 
946 
947 // Allocate a new context for reading HEIF files.
948 // Has to be freed again with heif_context_free().
950 struct heif_context* heif_context_alloc(void);
951 
952 // Free a previously allocated HEIF context. You should not free a context twice.
954 void heif_context_free(struct heif_context*);
955 
956 
957 
958 struct heif_reading_options;
959 
961 {
962  heif_reader_grow_status_size_reached, // requested size has been reached, we can read until this point
963  heif_reader_grow_status_timeout, // size has not been reached yet, but it may still grow further (deprecated)
964  heif_reader_grow_status_size_beyond_eof, // size has not been reached and never will. The file has grown to its full size
965  heif_reader_grow_status_error // an error has occurred
966 };
967 
969 {
970  enum heif_reader_grow_status status; // should not return 'heif_reader_grow_status_timeout'
971 
972  // Indicates up to what position the file has been read.
973  // If we cannot read the whole file range (status == 'heif_reader_grow_status_size_beyond_eof'), this is the actual end position.
974  // On the other hand, it may be that the reader was reading more data than requested. In that case, it should indicate the full size here
975  // and libheif may decide to make use of the additional data (e.g. for filling 'tili' offset tables).
976  uint64_t range_end;
977 
978  // for status == 'heif_reader_grow_status_error'
979  int reader_error_code; // a reader specific error code
980  const char* reader_error_msg; // libheif will call heif_reader.release_error_msg on this if it is not NULL
981 };
982 
983 
985 {
986  // API version supported by this reader
988 
989  // --- version 1 functions ---
990  int64_t (* get_position)(void* userdata);
991 
992  // The functions read(), and seek() return 0 on success.
993  // Generally, libheif will make sure that we do not read past the file size.
994  int (* read)(void* data,
995  size_t size,
996  void* userdata);
997 
998  int (* seek)(int64_t position,
999  void* userdata);
1000 
1001  // When calling this function, libheif wants to make sure that it can read the file
1002  // up to 'target_size'. This is useful when the file is currently downloaded and may
1003  // grow with time. You may, for example, extract the image sizes even before the actual
1004  // compressed image data has been completely downloaded.
1005  //
1006  // Even if your input files will not grow, you will have to implement at least
1007  // detection whether the target_size is above the (fixed) file length
1008  // (in this case, return 'size_beyond_eof').
1009  enum heif_reader_grow_status (* wait_for_file_size)(int64_t target_size, void* userdata);
1010 
1011  // --- version 2 functions ---
1012 
1013  // These two functions are for applications that want to stream HEIF files on demand.
1014  // For example, a large HEIF file that is served over HTTPS and we only want to download
1015  // it partially to decode individual tiles.
1016  // If you do not have this use case, you do not have to implement these functions and
1017  // you can set them to NULL. For simple linear loading, you may use the 'wait_for_file_size'
1018  // function above instead.
1019 
1020  // If this function is defined, libheif will often request a file range before accessing it.
1021  // The purpose of this function is that libheif will usually read very small chunks of data with the
1022  // read() callback above. However, it is inefficient to request such a small chunk of data over a network
1023  // and the network delay will significantly increase the decoding time.
1024  // Thus, libheif will call request_range() with a larger block of data that should be preloaded and the
1025  // subsequent read() calls will work within the requested ranges.
1026  //
1027  // Note: `end_pos` is one byte after the last position to be read.
1028  // You should return
1029  // - 'heif_reader_grow_status_size_reached' if the requested range is available, or
1030  // - 'heif_reader_grow_status_size_beyond_eof' if the requested range exceeds the file size
1031  // (the valid part of the range has been read).
1032  struct heif_reader_range_request_result (*request_range)(uint64_t start_pos, uint64_t end_pos, void* userdata);
1033 
1034  // libheif might issue hints when it assumes that a file range might be needed in the future.
1035  // This may happen, for example, when your are doing selective tile accesses and libheif proposes
1036  // to preload offset pointer tables.
1037  // Another difference to request_file_range() is that this call should be non-blocking.
1038  // If you preload any data, do this in a background thread.
1039  void (*preload_range_hint)(uint64_t start_pos, uint64_t end_pos, void* userdata);
1040 
1041  // If libheif does not need access to a file range anymore, it may call this function to
1042  // give a hint to the reader that it may release the range from a cache.
1043  // If you do not maintain a file cache that wants to reduce its size dynamically, you do not
1044  // need to implement this function.
1045  void (*release_file_range)(uint64_t start_pos, uint64_t end_pos, void* userdata);
1046 
1047  // Release an error message that was returned by heif_reader in an earlier call.
1048  // If this function is NULL, the error message string will not be released.
1049  // This is a viable option if you are only returning static strings.
1050  void (*release_error_msg)(const char* msg);
1051 };
1052 
1053 
1054 // Read a HEIF file from a named disk file.
1055 // The heif_reading_options should currently be set to NULL.
1057 struct heif_error heif_context_read_from_file(struct heif_context*, const char* filename,
1058  const struct heif_reading_options*);
1059 
1060 // Read a HEIF file stored completely in memory.
1061 // The heif_reading_options should currently be set to NULL.
1062 // DEPRECATED: use heif_context_read_from_memory_without_copy() instead.
1064 struct heif_error heif_context_read_from_memory(struct heif_context*,
1065  const void* mem, size_t size,
1066  const struct heif_reading_options*);
1067 
1068 // Same as heif_context_read_from_memory() except that the provided memory is not copied.
1069 // That means, you will have to keep the memory area alive as long as you use the heif_context.
1071 struct heif_error heif_context_read_from_memory_without_copy(struct heif_context*,
1072  const void* mem, size_t size,
1073  const struct heif_reading_options*);
1074 
1076 struct heif_error heif_context_read_from_reader(struct heif_context*,
1077  const struct heif_reader* reader,
1078  void* userdata,
1079  const struct heif_reading_options*);
1080 
1081 // Number of top-level images in the HEIF file. This does not include the thumbnails or the
1082 // tile images that are composed to an image grid. You can get access to the thumbnails via
1083 // the main image handle.
1085 int heif_context_get_number_of_top_level_images(struct heif_context* ctx);
1086 
1088 int heif_context_is_top_level_image_ID(struct heif_context* ctx, heif_item_id id);
1089 
1090 // Fills in image IDs into the user-supplied int-array 'ID_array', preallocated with 'count' entries.
1091 // Function returns the total number of IDs filled into the array.
1094  heif_item_id* ID_array,
1095  int count);
1096 
1098 struct heif_error heif_context_get_primary_image_ID(struct heif_context* ctx, heif_item_id* id);
1099 
1100 // Get a handle to the primary image of the HEIF file.
1101 // This is the image that should be displayed primarily when there are several images in the file.
1103 struct heif_error heif_context_get_primary_image_handle(struct heif_context* ctx,
1104  struct heif_image_handle**);
1105 
1106 // Get the image handle for a known image ID.
1108 struct heif_error heif_context_get_image_handle(struct heif_context* ctx,
1109  heif_item_id id,
1110  struct heif_image_handle**);
1111 
1112 // Print information about the boxes of a HEIF file to file descriptor.
1113 // This is for debugging and informational purposes only. You should not rely on
1114 // the output having a specific format. At best, you should not use this at all.
1116 void heif_context_debug_dump_boxes_to_file(struct heif_context* ctx, int fd);
1117 
1118 
1119 // Set the maximum image size security limit. This function will set the maximum image area (number of pixels)
1120 // to maximum_width ^ 2. Alternatively to using this function, you can also set the maximum image area
1121 // in the security limits structure returned by heif_context_get_security_limits().
1123 void heif_context_set_maximum_image_size_limit(struct heif_context* ctx, int maximum_width);
1124 
1125 // If the maximum threads number is set to 0, the image tiles are decoded in the main thread.
1126 // This is different from setting it to 1, which will generate a single background thread to decode the tiles.
1127 // Note that this setting only affects libheif itself. The codecs itself may still use multi-threaded decoding.
1128 // You can use it, for example, in cases where you are decoding several images in parallel anyway you thus want
1129 // to minimize parallelism in each decoder.
1131 void heif_context_set_max_decoding_threads(struct heif_context* ctx, int max_threads);
1132 
1133 
1134 // --- security limits
1135 
1136 // If you set a limit to 0, the limit is disabled.
1138  uint8_t version;
1139 
1140  // --- version 1
1141 
1142  // Limit on the maximum image size to avoid allocating too much memory.
1143  // For example, setting this to 32768^2 pixels = 1 Gigapixels results
1144  // in 1.5 GB memory need for YUV-4:2:0 or 4 GB for RGB32.
1148  uint32_t max_items;
1149 
1152 
1153  uint32_t max_components;
1154 
1157 
1158  uint32_t max_children_per_box; // for all boxes that are not covered by other limits
1159 };
1160 
1161 // The global security limits are the default for new heif_contexts.
1162 // These global limits cannot be changed, but you can override the limits for a specific heif_context.
1165 
1166 // Returns a set of fully disabled security limits. Use with care and only after user confirmation.
1169 
1170 // Returns the security limits for a heif_context.
1171 // By default, the limits are set to the global limits, but you can change them in the returned object.
1173 struct heif_security_limits* heif_context_get_security_limits(const struct heif_context*);
1174 
1175 // Overwrites the security limits of a heif_context.
1176 // This is a convenience function to easily copy limits.
1178 struct heif_error heif_context_set_security_limits(struct heif_context*, const struct heif_security_limits*);
1179 
1180 
1181 // ========================= heif_image_handle =========================
1182 
1183 // An heif_image_handle is a handle to a logical image in the HEIF file.
1184 // To get the actual pixel data, you have to decode the handle to an heif_image.
1185 // An heif_image_handle also gives you access to the thumbnails and Exif data
1186 // associated with an image.
1187 
1188 // Once you obtained an heif_image_handle, you can already release the heif_context,
1189 // since it is internally ref-counted.
1190 
1191 // Release image handle.
1193 void heif_image_handle_release(const struct heif_image_handle*);
1194 
1195 // Check whether the given image_handle is the primary image of the file.
1197 int heif_image_handle_is_primary_image(const struct heif_image_handle* handle);
1198 
1200 heif_item_id heif_image_handle_get_item_id(const struct heif_image_handle* handle);
1201 
1202 // Get the resolution of an image.
1204 int heif_image_handle_get_width(const struct heif_image_handle* handle);
1205 
1207 int heif_image_handle_get_height(const struct heif_image_handle* handle);
1208 
1210 int heif_image_handle_has_alpha_channel(const struct heif_image_handle*);
1211 
1213 int heif_image_handle_is_premultiplied_alpha(const struct heif_image_handle*);
1214 
1215 // Returns -1 on error, e.g. if this information is not present in the image.
1216 // Only defined for images coded in the YCbCr or monochrome colorspace.
1218 int heif_image_handle_get_luma_bits_per_pixel(const struct heif_image_handle*);
1219 
1220 // Returns -1 on error, e.g. if this information is not present in the image.
1221 // Only defined for images coded in the YCbCr colorspace.
1223 int heif_image_handle_get_chroma_bits_per_pixel(const struct heif_image_handle*);
1224 
1225 // Return the colorspace that libheif proposes to use for decoding.
1226 // Usually, these will be either YCbCr or Monochrome, but it may also propose RGB for images
1227 // encoded with matrix_coefficients=0 or for images coded natively in RGB.
1228 // It may also return *_undefined if the file misses relevant information to determine this without decoding.
1229 // These are only proposed values that avoid colorspace conversions as much as possible.
1230 // You can still request the output in your preferred colorspace, but this may involve an internal conversion.
1232 struct heif_error heif_image_handle_get_preferred_decoding_colorspace(const struct heif_image_handle* image_handle,
1233  enum heif_colorspace* out_colorspace,
1234  enum heif_chroma* out_chroma);
1235 
1236 // Get the image width from the 'ispe' box. This is the original image size without
1237 // any transformations applied to it. Do not use this unless you know exactly what
1238 // you are doing.
1240 int heif_image_handle_get_ispe_width(const struct heif_image_handle* handle);
1241 
1243 int heif_image_handle_get_ispe_height(const struct heif_image_handle* handle);
1244 
1245 // This gets the context associated with the image handle.
1246 // Note that you have to release the returned context with heif_context_free() in any case.
1247 //
1248 // This means: when you have several image-handles that originate from the same file and you get the
1249 // context of each of them, the returned pointer may be different even though it refers to the same
1250 // logical context. You have to call heif_context_free() on all those context pointers.
1251 // After you freed a context pointer, you can still use the context through a different pointer that you
1252 // might have acquired from elsewhere.
1254 struct heif_context* heif_image_handle_get_context(const struct heif_image_handle* handle);
1255 
1256 
1258 {
1259  int version;
1260 
1261  // --- version 1
1262 
1263  uint32_t num_columns;
1264  uint32_t num_rows;
1265  uint32_t tile_width;
1266  uint32_t tile_height;
1267 
1268  uint32_t image_width;
1269  uint32_t image_height;
1270 
1271  // Position of the top left tile.
1272  // Usually, this is (0;0), but if a tiled image is rotated or cropped, it may be that the top left tile should be placed at a negative position.
1273  // The offsets define this negative shift.
1274  uint32_t top_offset;
1275  uint32_t left_offset;
1276 
1277  uint8_t number_of_extra_dimensions; // 0 for normal images, 1 for volumetric (3D), ...
1278  uint32_t extra_dimension_size[8]; // size of extra dimensions (first 8 dimensions)
1279 };
1280 
1281 
1282 // If 'process_image_transformations' is true, this returns modified sizes.
1283 // If it is false, the top_offset and left_offset will always be (0;0).
1285 struct heif_error heif_image_handle_get_image_tiling(const struct heif_image_handle* handle, int process_image_transformations, struct heif_image_tiling* out_tiling);
1286 
1287 
1288 // For grid images, return the image item ID of a specific grid tile.
1289 // If 'process_image_transformations' is true, the tile positions are given in the transformed image coordinate system and
1290 // are internally mapped to the original image tile positions.
1292 struct heif_error heif_image_handle_get_grid_image_tile_id(const struct heif_image_handle* handle,
1293  int process_image_transformations,
1294  uint32_t tile_x, uint32_t tile_y,
1295  heif_item_id* out_tile_item_id);
1296 
1297 
1298 struct heif_decoding_options;
1299 
1300 // The tile position is given in tile indices, not in pixel coordinates.
1301 // If the image transformations are processed (option->ignore_image_transformations==false), the tile position
1302 // is given in the transformed coordinates.
1304 struct heif_error heif_image_handle_decode_image_tile(const struct heif_image_handle* in_handle,
1305  struct heif_image** out_img,
1306  enum heif_colorspace colorspace,
1307  enum heif_chroma chroma,
1308  const struct heif_decoding_options* options,
1309  uint32_t tile_x, uint32_t tile_y);
1310 
1311 
1312 // ------------------------- entity groups ------------------------
1313 
1314 typedef uint32_t heif_entity_group_id;
1315 
1317 {
1319  uint32_t entity_group_type; // this is a FourCC constant
1321  uint32_t num_entities;
1322 };
1323 
1324 // Use 0 for `type_filter` or `item_filter` to disable the filter.
1325 // Returns an array of heif_entity_group structs with *out_num_groups entries.
1327 struct heif_entity_group* heif_context_get_entity_groups(const struct heif_context*,
1328  uint32_t type_filter,
1329  heif_item_id item_filter,
1330  int* out_num_groups);
1331 
1332 // Release an array of entity groups returned by heif_context_get_entity_groups().
1334 void heif_entity_groups_release(struct heif_entity_group*, int num_groups);
1335 
1336 
1337 // ------------------------- depth images -------------------------
1338 
1340 int heif_image_handle_has_depth_image(const struct heif_image_handle*);
1341 
1343 int heif_image_handle_get_number_of_depth_images(const struct heif_image_handle* handle);
1344 
1346 int heif_image_handle_get_list_of_depth_image_IDs(const struct heif_image_handle* handle,
1347  heif_item_id* ids, int count);
1348 
1350 struct heif_error heif_image_handle_get_depth_image_handle(const struct heif_image_handle* handle,
1351  heif_item_id depth_image_id,
1352  struct heif_image_handle** out_depth_handle);
1353 
1354 
1356 {
1361 };
1362 
1364 {
1365  uint8_t version;
1366 
1367  // version 1 fields
1368 
1369  uint8_t has_z_near;
1370  uint8_t has_z_far;
1371  uint8_t has_d_min;
1372  uint8_t has_d_max;
1373 
1374  double z_near;
1375  double z_far;
1376  double d_min;
1377  double d_max;
1378 
1381 
1384 
1385  // version 2 fields below
1386 };
1387 
1388 
1391 
1392 // Returns true when there is depth_representation_info available
1393 // Note 1: depth_image_id is currently unused because we support only one depth channel per image, but
1394 // you should still provide the correct ID for future compatibility.
1395 // Note 2: Because of an API bug before v1.11.0, the function also works when 'handle' is the handle of the depth image.
1396 // However, you should pass the handle of the main image. Please adapt your code if needed.
1398 int heif_image_handle_get_depth_image_representation_info(const struct heif_image_handle* handle,
1399  heif_item_id depth_image_id,
1400  const struct heif_depth_representation_info** out);
1401 
1402 
1403 
1404 // ------------------------- thumbnails -------------------------
1405 
1406 // List the number of thumbnails assigned to this image handle. Usually 0 or 1.
1408 int heif_image_handle_get_number_of_thumbnails(const struct heif_image_handle* handle);
1409 
1411 int heif_image_handle_get_list_of_thumbnail_IDs(const struct heif_image_handle* handle,
1412  heif_item_id* ids, int count);
1413 
1414 // Get the image handle of a thumbnail image.
1416 struct heif_error heif_image_handle_get_thumbnail(const struct heif_image_handle* main_image_handle,
1417  heif_item_id thumbnail_id,
1418  struct heif_image_handle** out_thumbnail_handle);
1419 
1420 
1421 // ------------------------- auxiliary images -------------------------
1422 
1423 #define LIBHEIF_AUX_IMAGE_FILTER_OMIT_ALPHA (1UL<<1)
1424 #define LIBHEIF_AUX_IMAGE_FILTER_OMIT_DEPTH (2UL<<1)
1425 
1426 // List the number of auxiliary images assigned to this image handle.
1428 int heif_image_handle_get_number_of_auxiliary_images(const struct heif_image_handle* handle,
1429  int aux_filter);
1430 
1432 int heif_image_handle_get_list_of_auxiliary_image_IDs(const struct heif_image_handle* handle,
1433  int aux_filter,
1434  heif_item_id* ids, int count);
1435 
1436 // You are responsible to deallocate the returned buffer with heif_image_handle_release_auxiliary_type().
1438 struct heif_error heif_image_handle_get_auxiliary_type(const struct heif_image_handle* handle,
1439  const char** out_type);
1440 
1442 void heif_image_handle_release_auxiliary_type(const struct heif_image_handle* handle,
1443  const char** out_type);
1444 
1445 // DEPRECATED (because typo in function name). Use heif_image_handle_release_auxiliary_type() instead.
1447 void heif_image_handle_free_auxiliary_types(const struct heif_image_handle* handle,
1448  const char** out_type);
1449 
1450 // Get the image handle of an auxiliary image.
1452 struct heif_error heif_image_handle_get_auxiliary_image_handle(const struct heif_image_handle* main_image_handle,
1453  heif_item_id auxiliary_id,
1454  struct heif_image_handle** out_auxiliary_handle);
1455 
1456 
1457 // ------------------------- metadata (Exif / XMP) -------------------------
1458 
1459 // How many metadata blocks are attached to an image. If you only want to get EXIF data,
1460 // set the type_filter to "Exif". Otherwise, set the type_filter to NULL.
1462 int heif_image_handle_get_number_of_metadata_blocks(const struct heif_image_handle* handle,
1463  const char* type_filter);
1464 
1465 // 'type_filter' can be used to get only metadata of specific types, like "Exif".
1466 // If 'type_filter' is NULL, it will return all types of metadata IDs.
1468 int heif_image_handle_get_list_of_metadata_block_IDs(const struct heif_image_handle* handle,
1469  const char* type_filter,
1470  heif_item_id* ids, int count);
1471 
1472 // Return a string indicating the type of the metadata, as specified in the HEIF file.
1473 // Exif data will have the type string "Exif".
1474 // This string will be valid until the next call to a libheif function.
1475 // You do not have to free this string.
1477 const char* heif_image_handle_get_metadata_type(const struct heif_image_handle* handle,
1478  heif_item_id metadata_id);
1479 
1480 // For EXIF, the content type is empty.
1481 // For XMP, the content type is "application/rdf+xml".
1483 const char* heif_image_handle_get_metadata_content_type(const struct heif_image_handle* handle,
1484  heif_item_id metadata_id);
1485 
1486 // Get the size of the raw metadata, as stored in the HEIF file.
1488 size_t heif_image_handle_get_metadata_size(const struct heif_image_handle* handle,
1489  heif_item_id metadata_id);
1490 
1491 // 'out_data' must point to a memory area of the size reported by heif_image_handle_get_metadata_size().
1492 // The data is returned exactly as stored in the HEIF file.
1493 // For Exif data, you probably have to skip the first four bytes of the data, since they
1494 // indicate the offset to the start of the TIFF header of the Exif data.
1496 struct heif_error heif_image_handle_get_metadata(const struct heif_image_handle* handle,
1497  heif_item_id metadata_id,
1498  void* out_data);
1499 
1500 // Only valid for item type == "uri ", an absolute URI
1502 const char* heif_image_handle_get_metadata_item_uri_type(const struct heif_image_handle* handle,
1503  heif_item_id metadata_id);
1504 
1505 // ------------------------- color profiles -------------------------
1506 
1508 {
1512  heif_color_profile_type_prof = heif_fourcc('p', 'r', 'o', 'f')
1513 };
1514 
1515 
1516 // Returns 'heif_color_profile_type_not_present' if there is no color profile.
1517 // If there is an ICC profile and an NCLX profile, the ICC profile is returned.
1518 // TODO: we need a new API for this function as images can contain both NCLX and ICC at the same time.
1519 // However, you can still use heif_image_handle_get_raw_color_profile() and
1520 // heif_image_handle_get_nclx_color_profile() to access both profiles.
1522 enum heif_color_profile_type heif_image_handle_get_color_profile_type(const struct heif_image_handle* handle);
1523 
1525 size_t heif_image_handle_get_raw_color_profile_size(const struct heif_image_handle* handle);
1526 
1527 // Returns 'heif_error_Color_profile_does_not_exist' when there is no ICC profile.
1529 struct heif_error heif_image_handle_get_raw_color_profile(const struct heif_image_handle* handle,
1530  void* out_data);
1531 
1532 
1534 {
1535  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
1547 };
1548 
1550 {
1568 };
1569 
1571 {
1573  heif_matrix_coefficients_ITU_R_BT_709_5 = 1, // TODO: or 709-6 according to h.273
1577  heif_matrix_coefficients_ITU_R_BT_601_6 = 6, // TODO: or 601-7 according to h.273
1586 };
1587 
1589 {
1590  // === version 1 fields
1591 
1592  uint8_t version;
1593 
1598 
1599  // --- decoded values (not used when saving nclx)
1600 
1605 };
1606 
1609 
1611 struct heif_error heif_nclx_color_profile_set_transfer_characteristics(struct heif_color_profile_nclx* nclx, uint16_t transfer_characteristics);
1612 
1614 struct heif_error heif_nclx_color_profile_set_matrix_coefficients(struct heif_color_profile_nclx* nclx, uint16_t matrix_coefficients);
1615 
1616 // Returns 'heif_error_Color_profile_does_not_exist' when there is no NCLX profile.
1617 // TODO: This function does currently not return an NCLX profile if it is stored in the image bitstream.
1618 // Only NCLX profiles stored as colr boxes are returned. This may change in the future.
1620 struct heif_error heif_image_handle_get_nclx_color_profile(const struct heif_image_handle* handle,
1621  struct heif_color_profile_nclx** out_data);
1622 
1623 // Returned color profile has 'version' field set to the maximum allowed.
1624 // Do not fill values for higher versions as these might be outside the allocated structure size.
1625 // May return NULL.
1628 
1631 
1632 // Note: in early versions of HEIF, there could only be one color profile per image. However, this has been changed.
1633 // This function will now return ICC if one is present and NCLX only if there is no ICC.
1634 // You may better avoid this function and simply query for NCLX and ICC directly.
1636 enum heif_color_profile_type heif_image_get_color_profile_type(const struct heif_image* image);
1637 
1638 // Returns the size of the ICC profile if one is assigned to the image. Otherwise, it returns 0.
1640 size_t heif_image_get_raw_color_profile_size(const struct heif_image* image);
1641 
1642 // Returns the ICC profile if one is assigned to the image. Otherwise, it returns an error.
1644 struct heif_error heif_image_get_raw_color_profile(const struct heif_image* image,
1645  void* out_data);
1646 
1648 struct heif_error heif_image_get_nclx_color_profile(const struct heif_image* image,
1649  struct heif_color_profile_nclx** out_data);
1650 
1651 
1652 // ------------------------- intrinsic and extrinsic matrices -------------------------
1653 
1655 {
1660  double skew;
1661 };
1662 
1663 
1665 int heif_image_handle_has_camera_intrinsic_matrix(const struct heif_image_handle* handle);
1666 
1668 struct heif_error heif_image_handle_get_camera_intrinsic_matrix(const struct heif_image_handle* handle,
1669  struct heif_camera_intrinsic_matrix* out_matrix);
1670 
1671 
1672 struct heif_camera_extrinsic_matrix;
1673 
1675 int heif_image_handle_has_camera_extrinsic_matrix(const struct heif_image_handle* handle);
1676 
1678 struct heif_error heif_image_handle_get_camera_extrinsic_matrix(const struct heif_image_handle* handle,
1679  struct heif_camera_extrinsic_matrix** out_matrix);
1680 
1682 void heif_camera_extrinsic_matrix_release(struct heif_camera_extrinsic_matrix*);
1683 
1685 struct heif_error heif_camera_extrinsic_matrix_get_rotation_matrix(const struct heif_camera_extrinsic_matrix*,
1686  double* out_matrix_row_major);
1687 
1688 
1689 
1690 // ========================= heif_image =========================
1691 
1692 // An heif_image contains a decoded pixel image in various colorspaces, chroma formats,
1693 // and bit depths.
1694 
1695 // Note: when converting images to an interleaved chroma format, the resulting
1696 // image contains only a single channel of type channel_interleaved with, e.g., 3 bytes per pixel,
1697 // containing the interleaved R,G,B values.
1698 
1699 // Planar RGB images are specified as heif_colorspace_RGB / heif_chroma_444.
1700 
1702 {
1705 };
1706 
1707 
1709 {
1712 
1713  // Combine with 'heif_chroma_upsampling_bilinear' for best quality.
1714  // Makes edges look sharper when using YUV 420 with bilinear chroma upsampling.
1716 };
1717 
1719 {
1722 };
1723 
1724 
1726 {
1727  // 'version' must be 1.
1728  uint8_t version;
1729 
1730  // --- version 1 options
1731 
1734 
1735  // When set to 'false' libheif may also use a different algorithm if the preferred one is not available
1736  // or using a different algorithm is computationally less complex. Note that currently (v1.17.0) this
1737  // means that for RGB input it will usually choose nearest-neighbor sampling because this is computationally
1738  // the simplest.
1739  // Set this field to 'true' if you want to make sure that the specified algorithm is used even
1740  // at the cost of slightly higher computation times.
1742 
1743  // --- Note that we cannot extend this struct because it is embedded in
1744  // other structs (heif_decoding_options and heif_encoding_options).
1745 };
1746 
1747 // Assumes that it is a version=1 struct.
1750 
1751 
1753 {
1754  uint8_t version;
1755 
1756  // version 1 options
1757 
1758  // Ignore geometric transformations like cropping, rotation, mirroring.
1759  // Default: false (do not ignore).
1761 
1762  // Any of the progress functions may be called from background threads.
1763  void (* start_progress)(enum heif_progress_step step, int max_progress, void* progress_user_data);
1764 
1765  void (* on_progress)(enum heif_progress_step step, int progress, void* progress_user_data);
1766 
1768 
1770 
1771  // version 2 options
1772 
1774 
1775  // version 3 options
1776 
1777  // When enabled, an error is returned for invalid input. Otherwise, it will try its best and
1778  // add decoding warnings to the decoded heif_image. Default is non-strict.
1780 
1781  // version 4 options
1782 
1783  // name_id of the decoder to use for the decoding.
1784  // If set to NULL (default), the highest priority decoder is chosen.
1785  // The priority is defined in the plugin.
1786  const char* decoder_id;
1787 
1788  // version 5 options
1789 
1791 
1792  // version 6 options
1793 
1795 };
1796 
1797 
1798 // Allocate decoding options and fill with default values.
1799 // Note: you should always get the decoding options through this function since the
1800 // option structure may grow in size in future versions.
1803 
1806 
1807 // Decode an heif_image_handle into the actual pixel image and also carry out
1808 // all geometric transformations specified in the HEIF file (rotation, cropping, mirroring).
1809 //
1810 // If colorspace or chroma is set to heif_colorspace_undefined or heif_chroma_undefined,
1811 // respectively, the original colorspace is taken.
1812 // Decoding options may be NULL. If you want to supply options, always use
1813 // heif_decoding_options_alloc() to get the structure.
1815 struct heif_error heif_decode_image(const struct heif_image_handle* in_handle,
1816  struct heif_image** out_img,
1817  enum heif_colorspace colorspace,
1818  enum heif_chroma chroma,
1819  const struct heif_decoding_options* options);
1820 
1821 // Get the colorspace format of the image.
1823 enum heif_colorspace heif_image_get_colorspace(const struct heif_image*);
1824 
1825 // Get the chroma format of the image.
1827 enum heif_chroma heif_image_get_chroma_format(const struct heif_image*);
1828 
1837 int heif_image_get_width(const struct heif_image* img, enum heif_channel channel);
1838 
1847 int heif_image_get_height(const struct heif_image* img, enum heif_channel channel);
1848 
1858 int heif_image_get_primary_width(const struct heif_image* img);
1859 
1869 int heif_image_get_primary_height(const struct heif_image* img);
1870 
1872 struct heif_error heif_image_crop(struct heif_image* img,
1873  int left, int right, int top, int bottom);
1874 
1875 // Get the number of bits per pixel in the given image channel. Returns -1 if
1876 // a non-existing channel was given.
1877 // Note that the number of bits per pixel may be different for each color channel.
1878 // This function returns the number of bits used for storage of each pixel.
1879 // Especially for HDR images, this is probably not what you want. Have a look at
1880 // heif_image_get_bits_per_pixel_range() instead.
1882 int heif_image_get_bits_per_pixel(const struct heif_image*, enum heif_channel channel);
1883 
1884 // Get the number of bits per pixel in the given image channel. This function returns
1885 // the number of bits used for representing the pixel value, which might be smaller
1886 // than the number of bits used in memory.
1887 // For example, in 12bit HDR images, this function returns '12', while still 16 bits
1888 // are reserved for storage. For interleaved RGBA with 12 bit, this function also returns
1889 // '12', not '48' or '64' (heif_image_get_bits_per_pixel returns 64 in this case).
1891 int heif_image_get_bits_per_pixel_range(const struct heif_image*, enum heif_channel channel);
1892 
1894 int heif_image_has_channel(const struct heif_image*, enum heif_channel channel);
1895 
1896 // Get a pointer to the actual pixel data.
1897 // The 'out_stride' is returned as "bytes per line".
1898 // When out_stride is NULL, no value will be written.
1899 // Returns NULL if a non-existing channel was given.
1900 // TODO: it would be better if the 'stride' parameter would be size_t to prevent integer overflows when this value is multiplicated with large y coordinates.
1902 const uint8_t* heif_image_get_plane_readonly(const struct heif_image*,
1903  enum heif_channel channel,
1904  int* out_stride);
1905 
1907 uint8_t* heif_image_get_plane(struct heif_image*,
1908  enum heif_channel channel,
1909  int* out_stride);
1910 
1911 
1912 
1913 struct heif_scaling_options;
1914 
1915 // Currently, heif_scaling_options is not defined yet. Pass a NULL pointer.
1917 struct heif_error heif_image_scale_image(const struct heif_image* input,
1918  struct heif_image** output,
1919  int width, int height,
1920  const struct heif_scaling_options* options);
1921 
1922 // Extends the image size to match the given size by extending the right and bottom borders.
1923 // The border areas are filled with zero.
1925 struct heif_error heif_image_extend_to_size_fill_with_zero(struct heif_image* image,
1926  uint32_t width, uint32_t height);
1927 
1928 // The color profile is not attached to the image handle because we might need it
1929 // for color space transform and encoding.
1931 struct heif_error heif_image_set_raw_color_profile(struct heif_image* image,
1932  const char* profile_type_fourcc_string,
1933  const void* profile_data,
1934  const size_t profile_size);
1935 
1937 struct heif_error heif_image_set_nclx_color_profile(struct heif_image* image,
1938  const struct heif_color_profile_nclx* color_profile);
1939 
1940 
1941 // TODO: this function does not make any sense yet, since we currently cannot modify existing HEIF files.
1942 //LIBHEIF_API
1943 //void heif_image_remove_color_profile(struct heif_image* image);
1944 
1945 // Fills the image decoding warnings into the provided 'out_warnings' array.
1946 // The size of the array has to be provided in max_output_buffer_entries.
1947 // If max_output_buffer_entries==0, the number of decoder warnings is returned.
1948 // The function fills the warnings into the provided buffer, starting with 'first_warning_idx'.
1949 // It returns the number of warnings filled into the buffer.
1950 // Note: you can iterate through all warnings by using 'max_output_buffer_entries=1' and iterate 'first_warning_idx'.
1952 int heif_image_get_decoding_warnings(struct heif_image* image,
1953  int first_warning_idx,
1954  struct heif_error* out_warnings,
1955  int max_output_buffer_entries);
1956 
1957 // This function is only for decoder plugin implementors.
1959 void heif_image_add_decoding_warning(struct heif_image* image,
1960  struct heif_error err);
1961 
1962 // Release heif_image.
1964 void heif_image_release(const struct heif_image*);
1965 
1966 
1967 // Note: a value of 0 for any of these values indicates that the value is undefined.
1968 // The unit of these values is Candelas per square meter.
1970 {
1973 };
1974 
1976 int heif_image_has_content_light_level(const struct heif_image*);
1977 
1979 void heif_image_get_content_light_level(const struct heif_image*, struct heif_content_light_level* out);
1980 
1981 // Returns whether the image has 'content light level' information. If 0 is returned, the output is not filled.
1983 int heif_image_handle_get_content_light_level(const struct heif_image_handle*, struct heif_content_light_level* out);
1984 
1986 void heif_image_set_content_light_level(const struct heif_image*, const struct heif_content_light_level* in);
1987 
1988 
1989 // 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).
1991 {
1992  uint16_t display_primaries_x[3];
1993  uint16_t display_primaries_y[3];
1994  uint16_t white_point_x;
1995  uint16_t white_point_y;
1998 };
1999 
2000 // The units for max_display_mastering_luminance and min_display_mastering_luminance is Candelas per square meter.
2002 {
2009 };
2010 
2012 {
2016 };
2017 
2020 
2023 
2024 // Returns whether the image has 'mastering display colour volume' information. If 0 is returned, the output is not filled.
2027 
2030 
2031 
2032 // Converts the internal numeric representation of heif_mastering_display_colour_volume to the
2033 // normalized values, collected in heif_decoded_mastering_display_colour_volume.
2034 // Values that are out-of-range are decoded to 0, indicating an undefined value (as specified in ISO/IEC 23008-2).
2038 
2040 void heif_image_get_pixel_aspect_ratio(const struct heif_image*, uint32_t* aspect_h, uint32_t* aspect_v);
2041 
2042 // Returns whether the image has 'pixel aspect ratio information' information. If 0 is returned, the output is filled with the 1:1 default.
2044 int heif_image_handle_get_pixel_aspect_ratio(const struct heif_image_handle*, uint32_t* aspect_h, uint32_t* aspect_v);
2045 
2047 void heif_image_set_pixel_aspect_ratio(struct heif_image*, uint32_t aspect_h, uint32_t aspect_v);
2048 
2049 // ====================================================================================================
2050 // Encoding API
2051 
2053 struct heif_error heif_context_write_to_file(struct heif_context*,
2054  const char* filename);
2055 
2057 {
2058  // API version supported by this writer
2060 
2061  // --- version 1 functions ---
2062 
2063  // On success, the returned heif_error may have a NULL message. It will automatically be replaced with a "Success" string.
2064  struct heif_error (* write)(struct heif_context* ctx, // TODO: why do we need this parameter?
2065  const void* data,
2066  size_t size,
2067  void* userdata);
2068 };
2069 
2071 struct heif_error heif_context_write(struct heif_context*,
2072  struct heif_writer* writer,
2073  void* userdata);
2074 
2075 // Add a compatible brand that is now added automatically by libheif when encoding images (e.g. some application brands like 'geo1').
2077 void heif_context_add_compatible_brand(struct heif_context* ctx,
2078  heif_brand2 compatible_brand);
2079 
2080 // ----- encoder -----
2081 
2082 // The encoder used for actually encoding an image.
2083 struct heif_encoder;
2084 
2085 // A description of the encoder's capabilities and name.
2086 struct heif_encoder_descriptor;
2087 
2088 // A configuration parameter of the encoder. Each encoder implementation may have a different
2089 // set of parameters. For the most common settings (e.q. quality), special functions to set
2090 // the parameters are provided.
2091 struct heif_encoder_parameter;
2092 
2093 struct heif_decoder_descriptor;
2094 
2095 // Get a list of available decoders. You can filter the encoders by compression format.
2096 // Use format_filter==heif_compression_undefined to get all available decoders.
2097 // The returned list of decoders is sorted by their priority (which is a plugin property).
2098 // The number of decoders is returned, which are not more than 'count' if (out_decoders != nullptr).
2099 // By setting out_decoders==nullptr, you can query the number of decoders, 'count' is ignored.
2102  const struct heif_decoder_descriptor** out_decoders,
2103  int count);
2104 
2105 // Return a long, descriptive name of the decoder (including version information).
2107 const char* heif_decoder_descriptor_get_name(const struct heif_decoder_descriptor*);
2108 
2109 // Return a short, symbolic name for identifying the decoder.
2110 // This name should stay constant over different decoder versions.
2111 // Note: the returned ID may be NULL for old plugins that don't support this yet.
2113 const char* heif_decoder_descriptor_get_id_name(const struct heif_decoder_descriptor*);
2114 
2115 // DEPRECATED: use heif_get_encoder_descriptors() instead.
2116 // Get a list of available encoders. You can filter the encoders by compression format and name.
2117 // Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards.
2118 // The returned list of encoders is sorted by their priority (which is a plugin property).
2119 // The number of encoders is returned, which are not more than 'count' if (out_encoders != nullptr).
2120 // By setting out_encoders==nullptr, you can query the number of encoders, 'count' is ignored.
2121 // Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
2123 int heif_context_get_encoder_descriptors(struct heif_context*, // TODO: why do we need this parameter?
2124  enum heif_compression_format format_filter,
2125  const char* name_filter,
2126  const struct heif_encoder_descriptor** out_encoders,
2127  int count);
2128 
2129 // Get a list of available encoders. You can filter the encoders by compression format and name.
2130 // Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards.
2131 // The returned list of encoders is sorted by their priority (which is a plugin property).
2132 // The number of encoders is returned, which are not more than 'count' if (out_encoders != nullptr).
2133 // By setting out_encoders==nullptr, you can query the number of encoders, 'count' is ignored.
2134 // Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
2137  const char* name_filter,
2138  const struct heif_encoder_descriptor** out_encoders,
2139  int count);
2140 
2141 // Return a long, descriptive name of the encoder (including version information).
2143 const char* heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor*);
2144 
2145 // Return a short, symbolic name for identifying the encoder.
2146 // This name should stay constant over different encoder versions.
2148 const char* heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor*);
2149 
2152 heif_encoder_descriptor_get_compression_format(const struct heif_encoder_descriptor*);
2153 
2155 int heif_encoder_descriptor_supports_lossy_compression(const struct heif_encoder_descriptor*);
2156 
2158 int heif_encoder_descriptor_supports_lossless_compression(const struct heif_encoder_descriptor*);
2159 
2160 
2161 // Get an encoder instance that can be used to actually encode images from a descriptor.
2163 struct heif_error heif_context_get_encoder(struct heif_context* context,
2164  const struct heif_encoder_descriptor*,
2165  struct heif_encoder** out_encoder);
2166 
2167 // Quick check whether there is a decoder available for the given format.
2168 // Note that the decoder still may not be able to decode all variants of that format.
2169 // You will have to query that further (todo) or just try to decode and check the returned error.
2172 
2173 // Quick check whether there is an enoder available for the given format.
2174 // Note that the encoder may be limited to a certain subset of features (e.g. only 8 bit, only lossy).
2175 // You will have to query the specific capabilities further.
2178 
2179 // Get an encoder for the given compression format. If there are several encoder plugins
2180 // for this format, the encoder with the highest plugin priority will be returned.
2182 struct heif_error heif_context_get_encoder_for_format(struct heif_context* context,
2183  enum heif_compression_format format,
2184  struct heif_encoder**);
2185 
2186 // You have to release the encoder after use.
2188 void heif_encoder_release(struct heif_encoder*);
2189 
2190 // Get the encoder name from the encoder itself.
2192 const char* heif_encoder_get_name(const struct heif_encoder*);
2193 
2194 
2195 // --- Encoder Parameters ---
2196 
2197 // Libheif supports settings parameters through specialized functions and through
2198 // generic functions by parameter name. Sometimes, the same parameter can be set
2199 // in both ways.
2200 // We consider it best practice to use the generic parameter functions only in
2201 // dynamically generated user interfaces, as no guarantees are made that some specific
2202 // parameter names are supported by all plugins.
2203 
2204 
2205 // Set a 'quality' factor (0-100). How this is mapped to actual encoding parameters is
2206 // encoder dependent.
2208 struct heif_error heif_encoder_set_lossy_quality(struct heif_encoder*, int quality);
2209 
2211 struct heif_error heif_encoder_set_lossless(struct heif_encoder*, int enable);
2212 
2213 // level should be between 0 (= none) to 4 (= full)
2215 struct heif_error heif_encoder_set_logging_level(struct heif_encoder*, int level);
2216 
2217 // Get a generic list of encoder parameters.
2218 // Each encoder may define its own, additional set of parameters.
2219 // You do not have to free the returned list.
2221 const struct heif_encoder_parameter* const* heif_encoder_list_parameters(struct heif_encoder*);
2222 
2223 // Return the parameter name.
2225 const char* heif_encoder_parameter_get_name(const struct heif_encoder_parameter*);
2226 
2227 
2229 {
2233 };
2234 
2235 // Return the parameter type.
2237 enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter*);
2238 
2239 // DEPRECATED. Use heif_encoder_parameter_get_valid_integer_values() instead.
2241 struct heif_error heif_encoder_parameter_get_valid_integer_range(const struct heif_encoder_parameter*,
2242  int* have_minimum_maximum,
2243  int* minimum, int* maximum);
2244 
2245 // If integer is limited by a range, have_minimum and/or have_maximum will be != 0 and *minimum, *maximum is set.
2246 // If integer is limited by a fixed set of values, *num_valid_values will be >0 and *out_integer_array is set.
2248 struct heif_error heif_encoder_parameter_get_valid_integer_values(const struct heif_encoder_parameter*,
2249  int* have_minimum, int* have_maximum,
2250  int* minimum, int* maximum,
2251  int* num_valid_values,
2252  const int** out_integer_array);
2253 
2255 struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter*,
2256  const char* const** out_stringarray);
2257 
2258 
2260 struct heif_error heif_encoder_set_parameter_integer(struct heif_encoder*,
2261  const char* parameter_name,
2262  int value);
2263 
2265 struct heif_error heif_encoder_get_parameter_integer(struct heif_encoder*,
2266  const char* parameter_name,
2267  int* value);
2268 
2269 // TODO: name should be changed to heif_encoder_get_valid_integer_parameter_range
2270 LIBHEIF_API // DEPRECATED.
2271 struct heif_error heif_encoder_parameter_integer_valid_range(struct heif_encoder*,
2272  const char* parameter_name,
2273  int* have_minimum_maximum,
2274  int* minimum, int* maximum);
2275 
2277 struct heif_error heif_encoder_set_parameter_boolean(struct heif_encoder*,
2278  const char* parameter_name,
2279  int value);
2280 
2282 struct heif_error heif_encoder_get_parameter_boolean(struct heif_encoder*,
2283  const char* parameter_name,
2284  int* value);
2285 
2287 struct heif_error heif_encoder_set_parameter_string(struct heif_encoder*,
2288  const char* parameter_name,
2289  const char* value);
2290 
2292 struct heif_error heif_encoder_get_parameter_string(struct heif_encoder*,
2293  const char* parameter_name,
2294  char* value, int value_size);
2295 
2296 // returns a NULL-terminated list of valid strings or NULL if all values are allowed
2298 struct heif_error heif_encoder_parameter_string_valid_values(struct heif_encoder*,
2299  const char* parameter_name,
2300  const char* const** out_stringarray);
2301 
2303 struct heif_error heif_encoder_parameter_integer_valid_values(struct heif_encoder*,
2304  const char* parameter_name,
2305  int* have_minimum, int* have_maximum,
2306  int* minimum, int* maximum,
2307  int* num_valid_values,
2308  const int** out_integer_array);
2309 
2310 // Set a parameter of any type to the string value.
2311 // Integer values are parsed from the string.
2312 // Boolean values can be "true"/"false"/"1"/"0"
2313 //
2314 // x265 encoder specific note:
2315 // When using the x265 encoder, you may pass any of its parameters by
2316 // prefixing the parameter name with 'x265:'. Hence, to set the 'ctu' parameter,
2317 // you will have to set 'x265:ctu' in libheif.
2318 // Note that there is no checking for valid parameters when using the prefix.
2320 struct heif_error heif_encoder_set_parameter(struct heif_encoder*,
2321  const char* parameter_name,
2322  const char* value);
2323 
2324 // Get the current value of a parameter of any type as a human readable string.
2325 // The returned string is compatible with heif_encoder_set_parameter().
2327 struct heif_error heif_encoder_get_parameter(struct heif_encoder*,
2328  const char* parameter_name,
2329  char* value_ptr, int value_size);
2330 
2331 // Query whether a specific parameter has a default value.
2333 int heif_encoder_has_default(struct heif_encoder*,
2334  const char* parameter_name);
2335 
2336 
2337 // The orientation values are defined equal to the EXIF Orientation tag.
2339 {
2348 };
2349 
2350 
2352 {
2353  uint8_t version;
2354 
2355  // version 1 options
2356 
2357  uint8_t save_alpha_channel; // default: true
2358 
2359  // version 2 options
2360 
2361  // DEPRECATED. This option is not required anymore. Its value will be ignored.
2363 
2364  // version 3 options
2365 
2367 
2368  // version 4 options
2369 
2370  // Set this to the NCLX parameters to be used in the output image or set to NULL
2371  // when the same parameters as in the input image should be used.
2373 
2375 
2376  // version 5 options
2377 
2378  // libheif will generate irot/imir boxes to match these orientations
2380 
2381  // version 6 options
2382 
2384 
2385  // version 7 options
2386 
2387  // Set this to true to use compressed form of uncC where possible.
2389 
2390  // TODO: we should add a flag to force MIAF compatible outputs. E.g. this will put restrictions on grid tile sizes and
2391  // might add a clap box when the grid output size does not match the color subsampling factors.
2392  // Since some of these constraints have to be known before actually encoding the image, "forcing MIAF compatibility"
2393  // could also be a flag in the heif_context.
2394 };
2395 
2398 
2401 
2402 
2403 // Compress the input image.
2404 // Returns a handle to the coded image in 'out_image_handle' unless out_image_handle = NULL.
2405 // 'options' should be NULL for now.
2406 // The first image added to the context is also automatically set the primary image, but
2407 // you can change the primary image later with heif_context_set_primary_image().
2409 struct heif_error heif_context_encode_image(struct heif_context*,
2410  const struct heif_image* image,
2411  struct heif_encoder* encoder,
2412  const struct heif_encoding_options* options,
2413  struct heif_image_handle** out_image_handle);
2414 
2428 struct heif_error heif_context_encode_grid(struct heif_context* ctx,
2429  struct heif_image** tiles,
2430  uint16_t rows,
2431  uint16_t columns,
2432  struct heif_encoder* encoder,
2433  const struct heif_encoding_options* input_options,
2434  struct heif_image_handle** out_image_handle);
2435 
2437 struct heif_error heif_context_add_grid_image(struct heif_context* ctx,
2438  uint32_t image_width,
2439  uint32_t image_height,
2440  uint32_t tile_columns,
2441  uint32_t tile_rows,
2442  const struct heif_encoding_options* encoding_options,
2443  struct heif_image_handle** out_grid_image_handle);
2444 
2446 struct heif_error heif_context_add_image_tile(struct heif_context* ctx,
2447  struct heif_image_handle* tiled_image,
2448  uint32_t tile_x, uint32_t tile_y,
2449  const struct heif_image* image,
2450  struct heif_encoder* encoder);
2451 
2452 // offsets[] should either be NULL (all offsets==0) or an array of size 2*nImages with x;y offset pairs.
2453 // If background_rgba is NULL, the background is transparent.
2455 struct heif_error heif_context_add_overlay_image(struct heif_context* ctx,
2456  uint32_t image_width,
2457  uint32_t image_height,
2458  uint16_t nImages,
2459  const heif_item_id* image_ids,
2460  int32_t* offsets,
2461  const uint16_t background_rgba[4],
2462  struct heif_image_handle** out_iovl_image_handle);
2463 
2465 struct heif_error heif_context_set_primary_image(struct heif_context*,
2466  struct heif_image_handle* image_handle);
2467 
2468 // Encode the 'image' as a scaled down thumbnail image.
2469 // The image is scaled down to fit into a square area of width 'bbox_size'.
2470 // If the input image is already so small that it fits into this bounding box, no thumbnail
2471 // image is encoded and NULL is returned in 'out_thumb_image_handle'.
2472 // No error is returned in this case.
2473 // The encoded thumbnail is automatically assigned to the 'master_image_handle'. Hence, you
2474 // do not have to call heif_context_assign_thumbnail().
2476 struct heif_error heif_context_encode_thumbnail(struct heif_context*,
2477  const struct heif_image* image,
2478  const struct heif_image_handle* master_image_handle,
2479  struct heif_encoder* encoder,
2480  const struct heif_encoding_options* options,
2481  int bbox_size,
2482  struct heif_image_handle** out_thumb_image_handle);
2483 
2484 // Assign 'thumbnail_image' as the thumbnail image of 'master_image'.
2486 struct heif_error heif_context_assign_thumbnail(struct heif_context*,
2487  const struct heif_image_handle* master_image,
2488  const struct heif_image_handle* thumbnail_image);
2489 
2490 // Add EXIF metadata to an image.
2492 struct heif_error heif_context_add_exif_metadata(struct heif_context*,
2493  const struct heif_image_handle* image_handle,
2494  const void* data, int size);
2495 
2496 // Add XMP metadata to an image.
2498 struct heif_error heif_context_add_XMP_metadata(struct heif_context*,
2499  const struct heif_image_handle* image_handle,
2500  const void* data, int size);
2501 
2502 // New version of heif_context_add_XMP_metadata() with data compression (experimental).
2504 struct heif_error heif_context_add_XMP_metadata2(struct heif_context*,
2505  const struct heif_image_handle* image_handle,
2506  const void* data, int size,
2507  enum heif_metadata_compression compression);
2508 
2509 // Add generic, proprietary metadata to an image. You have to specify an 'item_type' that will
2510 // identify your metadata. 'content_type' can be an additional type, or it can be NULL.
2511 // For example, this function can be used to add IPTC metadata (IIM stream, not XMP) to an image.
2512 // Although not standard, we propose to store IPTC data with item type="iptc", content_type=NULL.
2514 struct heif_error heif_context_add_generic_metadata(struct heif_context* ctx,
2515  const struct heif_image_handle* image_handle,
2516  const void* data, int size,
2517  const char* item_type, const char* content_type);
2518 
2519 // Add generic metadata with item_type "uri ". Items with this type do not have a content_type, but
2520 // an item_uri_type and they have no content_encoding (they are always stored uncompressed).
2522 struct heif_error heif_context_add_generic_uri_metadata(struct heif_context* ctx,
2523  const struct heif_image_handle* image_handle,
2524  const void* data, int size,
2525  const char* item_uri_type,
2526  heif_item_id* out_item_id);
2527 
2528 // --- heif_image allocation
2529 
2544 struct heif_error heif_image_create(int width, int height,
2545  enum heif_colorspace colorspace,
2546  enum heif_chroma chroma,
2547  struct heif_image** out_image);
2548 
2578 struct heif_error heif_image_add_plane(struct heif_image* image,
2579  enum heif_channel channel,
2580  int width, int height, int bit_depth);
2581 
2582 // Signal that the image is premultiplied by the alpha pixel values.
2584 void heif_image_set_premultiplied_alpha(struct heif_image* image,
2585  int is_premultiplied_alpha);
2586 
2588 int heif_image_is_premultiplied_alpha(struct heif_image* image);
2589 
2590 // This function extends the padding of the image so that it has at least the given physical size.
2591 // The padding border is filled with the pixels along the right/bottom border.
2592 // This function may be useful if you want to process the image, but have some external padding requirements.
2593 // The image size will not be modified if it is already larger/equal than the given physical size.
2594 // I.e. you cannot assume that after calling this function, the stride will be equal to min_physical_width.
2596 struct heif_error heif_image_extend_padding_to_size(struct heif_image* image, int min_physical_width, int min_physical_height);
2597 
2598 
2599 
2600 // --- register plugins
2601 
2602 struct heif_decoder_plugin;
2603 struct heif_encoder_plugin;
2604 
2605 // DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead.
2607 struct heif_error heif_register_decoder(struct heif_context* heif, const struct heif_decoder_plugin*);
2608 
2610 struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin*);
2611 
2613 struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin*);
2614 
2615 // DEPRECATED, typo in function name
2617 int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor*);
2618 
2619 // DEPRECATED, typo in function name
2621 int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor*);
2622 
2623 
2624 #ifdef __cplusplus
2625 }
2626 #endif
2627 
2628 #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_handle_get_metadata(const struct heif_image_handle *handle, heif_item_id metadata_id, void *out_data)
int heif_image_handle_get_content_light_level(const struct heif_image_handle *, struct heif_content_light_level *out)
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:579
@ heif_plugin_type_decoder
Definition: heif.h:581
@ heif_plugin_type_encoder
Definition: heif.h:580
int heif_image_handle_get_height(const struct heif_image_handle *handle)
void heif_image_handle_release(const struct heif_image_handle *)
const char * heif_encoder_parameter_get_name(const struct heif_encoder_parameter *)
const char * heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor *)
int heif_encoder_descriptor_supports_lossy_compression(const struct heif_encoder_descriptor *)
uint32_t heif_brand2
Definition: heif.h:673
enum heif_colorspace heif_image_get_colorspace(const struct heif_image *)
const uint8_t * heif_image_get_plane_readonly(const struct heif_image *, enum heif_channel channel, int *out_stride)
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:504
@ heif_channel_interleaved
Definition: heif.h:512
@ heif_channel_filter_array
Definition: heif.h:513
@ heif_channel_depth
Definition: heif.h:514
@ heif_channel_G
Definition: heif.h:509
@ heif_channel_Y
Definition: heif.h:505
@ heif_channel_Cb
Definition: heif.h:506
@ heif_channel_B
Definition: heif.h:510
@ heif_channel_R
Definition: heif.h:508
@ heif_channel_Alpha
Definition: heif.h:511
@ heif_channel_Cr
Definition: heif.h:507
@ heif_channel_disparity
Definition: heif.h:515
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)
LIBHEIF_API void heif_image_set_premultiplied_alpha(struct heif_image *image, int is_premultiplied_alpha)
heif_colorspace
Definition: heif.h:477
@ heif_colorspace_monochrome
Definition: heif.h:497
@ heif_colorspace_undefined
Definition: heif.h:478
@ heif_colorspace_YCbCr
Definition: heif.h:484
@ heif_colorspace_RGB
Definition: heif.h:494
@ heif_colorspace_nonvisual
Definition: heif.h:500
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:457
@ heif_chroma_interleaved_RGB
Definition: heif.h:463
@ heif_chroma_444
Definition: heif.h:462
@ heif_chroma_monochrome
Definition: heif.h:459
@ heif_chroma_interleaved_RGBA
Definition: heif.h:464
@ heif_chroma_interleaved_RRGGBBAA_BE
Definition: heif.h:466
@ heif_chroma_422
Definition: heif.h:461
@ heif_chroma_interleaved_RRGGBB_BE
Definition: heif.h:465
@ heif_chroma_undefined
Definition: heif.h:458
@ heif_chroma_interleaved_RRGGBB_LE
Definition: heif.h:467
@ heif_chroma_interleaved_RRGGBBAA_LE
Definition: heif.h:468
@ heif_chroma_420
Definition: heif.h:460
int heif_image_handle_get_width(const struct heif_image_handle *handle)
void heif_entity_groups_release(struct heif_entity_group *, int num_groups)
heif_brand
Definition: heif.h:646
@ heif_heic
Definition: heif.h:648
@ heif_hevs
Definition: heif.h:654
@ heif_mif1
Definition: heif.h:655
@ heif_j2is
Definition: heif.h:664
@ heif_heix
Definition: heif.h:649
@ heif_hevc
Definition: heif.h:650
@ heif_avis
Definition: heif.h:658
@ heif_evbs
Definition: heif.h:662
@ heif_vvic
Definition: heif.h:659
@ heif_hevx
Definition: heif.h:650
@ heif_heis
Definition: heif.h:652
@ heif_msf1
Definition: heif.h:656
@ heif_j2ki
Definition: heif.h:663
@ heif_evbi
Definition: heif.h:661
@ heif_hevm
Definition: heif.h:653
@ heif_unknown_brand
Definition: heif.h:647
@ heif_vvis
Definition: heif.h:660
@ heif_avif
Definition: heif.h:657
@ heif_heim
Definition: heif.h:651
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)
uint8_t * heif_image_get_plane(struct heif_image *, enum heif_channel channel, int *out_stride)
uint32_t heif_property_id
Definition: heif.h:365
int heif_image_get_decoding_warnings(struct heif_image *image, int first_warning_idx, struct heif_error *out_warnings, int max_output_buffer_entries)
LIBHEIF_API int heif_image_is_premultiplied_alpha(struct heif_image *image)
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:1702
@ heif_progress_step_total
Definition: heif.h:1703
@ heif_progress_step_load_tile
Definition: heif.h:1704
struct heif_error heif_context_add_exif_metadata(struct heif_context *, const struct heif_image_handle *image_handle, const void *data, int size)
struct heif_error heif_unload_plugin(const struct heif_plugin_info *plugin)
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)
struct heif_error heif_context_add_grid_image(struct heif_context *ctx, uint32_t image_width, uint32_t image_height, uint32_t tile_columns, uint32_t tile_rows, const struct heif_encoding_options *encoding_options, struct heif_image_handle **out_grid_image_handle)
enum heif_color_profile_type heif_image_get_color_profile_type(const struct heif_image *image)
const char * heif_get_version(void)
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)
const char * heif_get_file_mime_type(const uint8_t *data, int len)
enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter *)
heif_suberror_code
Definition: heif.h:146
@ heif_suberror_Encoder_encoding
Definition: heif.h:333
@ heif_suberror_No_ipma_box
Definition: heif.h:173
@ heif_suberror_No_av1C_box
Definition: heif.h:224
@ heif_suberror_Null_pointer_argument
Definition: heif.h:277
@ heif_suberror_Invalid_region_data
Definition: heif.h:235
@ heif_suberror_Security_limit_exceeded
Definition: heif.h:265
@ heif_suberror_Invalid_property
Definition: heif.h:295
@ heif_suberror_Item_reference_cycle
Definition: heif.h:298
@ heif_suberror_Unsupported_parameter
Definition: heif.h:289
@ heif_suberror_No_properties_assigned_to_item
Definition: heif.h:189
@ heif_suberror_No_icbr_box
Definition: heif.h:250
@ heif_suberror_Plugin_is_not_loaded
Definition: heif.h:342
@ heif_suberror_Unsupported_header_compression_method
Definition: heif.h:316
@ heif_suberror_Unspecified
Definition: heif.h:148
@ heif_suberror_No_pitm_box
Definition: heif.h:169
@ heif_suberror_Encoder_initialization
Definition: heif.h:332
@ heif_suberror_Unsupported_plugin_version
Definition: heif.h:283
@ heif_suberror_Unsupported_color_conversion
Definition: heif.h:312
@ heif_suberror_Compression_initialisation_error
Definition: heif.h:269
@ heif_suberror_No_item_data
Definition: heif.h:192
@ heif_suberror_Unknown_NCLX_matrix_coefficients
Definition: heif.h:232
@ heif_suberror_Unknown_color_profile_type
Definition: heif.h:214
@ heif_suberror_No_infe_box
Definition: heif.h:212
@ heif_suberror_No_idat_box
Definition: heif.h:161
@ heif_suberror_Unsupported_essential_property
Definition: heif.h:321
@ heif_suberror_Ipma_box_references_nonexisting_property
Definition: heif.h:186
@ heif_suberror_Invalid_mini_box
Definition: heif.h:255
@ heif_suberror_Plugin_loading_error
Definition: heif.h:341
@ heif_suberror_Unknown_NCLX_transfer_characteristics
Definition: heif.h:230
@ heif_suberror_Missing_grid_images
Definition: heif.h:198
@ heif_suberror_Unsupported_bit_depth
Definition: heif.h:325
@ heif_suberror_No_iinf_box
Definition: heif.h:177
@ heif_suberror_Invalid_clean_aperture
Definition: heif.h:200
@ heif_suberror_Unsupported_generic_compression_method
Definition: heif.h:319
@ heif_suberror_Overlay_image_outside_of_canvas
Definition: heif.h:206
@ heif_suberror_No_ipco_box
Definition: heif.h:171
@ heif_suberror_No_vvcC_box
Definition: heif.h:247
@ heif_suberror_No_avcC_box
Definition: heif.h:252
@ heif_suberror_Auxiliary_image_type_unspecified
Definition: heif.h:208
@ heif_suberror_Too_many_regions
Definition: heif.h:336
@ heif_suberror_No_iref_box
Definition: heif.h:181
@ heif_suberror_No_pict_handler
Definition: heif.h:183
@ heif_suberror_No_or_invalid_primary_item
Definition: heif.h:210
@ heif_suberror_Unsupported_writer_version
Definition: heif.h:286
@ heif_suberror_Nonexisting_item_referenced
Definition: heif.h:274
@ heif_suberror_Invalid_image_size
Definition: heif.h:220
@ heif_suberror_No_iloc_box
Definition: heif.h:175
@ heif_suberror_No_iprp_box
Definition: heif.h:179
@ heif_suberror_End_of_data
Definition: heif.h:153
@ heif_suberror_No_ftyp_box
Definition: heif.h:159
@ heif_suberror_Unsupported_codec
Definition: heif.h:304
@ heif_suberror_Invalid_grid_data
Definition: heif.h:195
@ heif_suberror_Invalid_overlay_data
Definition: heif.h:203
@ heif_suberror_Invalid_box_size
Definition: heif.h:156
@ heif_suberror_Unsupported_item_construction_method
Definition: heif.h:314
@ heif_suberror_No_hdlr_box
Definition: heif.h:165
@ heif_suberror_Cannot_read_plugin_directory
Definition: heif.h:343
@ heif_suberror_No_ispe_property
Definition: heif.h:238
@ heif_suberror_Unknown_NCLX_color_primaries
Definition: heif.h:228
@ heif_suberror_Nonexisting_image_channel_referenced
Definition: heif.h:280
@ heif_suberror_Wrong_tile_image_chroma_format
Definition: heif.h:216
@ heif_suberror_Invalid_J2K_codestream
Definition: heif.h:245
@ heif_suberror_Unsupported_data_version
Definition: heif.h:309
@ heif_suberror_No_matching_decoder_installed
Definition: heif.h:344
@ heif_suberror_Invalid_pixi_box
Definition: heif.h:222
@ heif_suberror_Camera_extrinsic_matrix_undefined
Definition: heif.h:242
@ heif_suberror_Encoder_cleanup
Definition: heif.h:334
@ heif_suberror_Invalid_parameter_value
Definition: heif.h:292
@ heif_suberror_Invalid_fractional_number
Definition: heif.h:218
@ heif_suberror_Unsupported_image_type
Definition: heif.h:307
@ heif_suberror_Camera_intrinsic_matrix_undefined
Definition: heif.h:240
@ heif_suberror_Decompression_invalid_data
Definition: heif.h:258
@ heif_suberror_No_hvcC_box
Definition: heif.h:167
@ heif_suberror_Wrong_tile_image_pixel_depth
Definition: heif.h:226
@ heif_suberror_No_meta_box
Definition: heif.h:163
@ heif_suberror_Cannot_write_output_data
Definition: heif.h:330
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)
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)
const char * heif_decoder_descriptor_get_id_name(const struct heif_decoder_descriptor *)
const char * heif_decoder_descriptor_get_name(const struct heif_decoder_descriptor *)
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 *)
int heif_image_get_primary_height(const struct heif_image *img)
Get the height of the main channel.
const char * heif_image_handle_get_metadata_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
void heif_image_get_content_light_level(const struct heif_image *, struct heif_content_light_level *out)
struct heif_error heif_context_set_security_limits(struct heif_context *, const struct heif_security_limits *)
struct heif_error heif_image_handle_get_image_tiling(const struct heif_image_handle *handle, int process_image_transformations, struct heif_image_tiling *out_tiling)
LIBHEIF_API int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor *)
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:103
@ heif_error_Encoding_error
Definition: heif.h:132
@ heif_error_Invalid_input
Definition: heif.h:111
@ heif_error_Canceled
Definition: heif.h:141
@ heif_error_Memory_allocation_error
Definition: heif.h:123
@ heif_error_Input_does_not_exist
Definition: heif.h:108
@ heif_error_Decoder_plugin_error
Definition: heif.h:126
@ heif_error_Encoder_plugin_error
Definition: heif.h:129
@ heif_error_Plugin_loading_error
Definition: heif.h:138
@ heif_error_Unsupported_filetype
Definition: heif.h:114
@ heif_error_Ok
Definition: heif.h:105
@ heif_error_Unsupported_feature
Definition: heif.h:117
@ heif_error_Color_profile_does_not_exist
Definition: heif.h:135
@ heif_error_Usage_error
Definition: heif.h:120
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)
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:375
@ heif_compression_EVC
EVC compression.
Definition: heif.h:427
@ heif_compression_JPEG2000
JPEG 2000 compression.
Definition: heif.h:434
@ heif_compression_AVC
AVC compression.
Definition: heif.h:396
@ heif_compression_uncompressed
Uncompressed encoding.
Definition: heif.h:440
@ heif_compression_mask
Mask image encoding.
Definition: heif.h:446
@ heif_compression_undefined
Unspecified / undefined compression format.
Definition: heif.h:382
@ heif_compression_VVC
VVC compression.
Definition: heif.h:419
@ heif_compression_JPEG
JPEG compression.
Definition: heif.h:403
@ heif_compression_HEVC
HEVC compression, used for HEIC images.
Definition: heif.h:388
@ heif_compression_HTJ2K
High Throughput JPEG 2000 (HT-J2K) compression.
Definition: heif.h:453
@ heif_compression_AV1
AV1 compression, used for AVIF images.
Definition: heif.h:411
struct heif_error heif_image_get_nclx_color_profile(const struct heif_image *image, struct heif_color_profile_nclx **out_data)
struct heif_entity_group * heif_context_get_entity_groups(const struct heif_context *, uint32_t type_filter, heif_item_id item_filter, int *out_num_groups)
struct heif_error heif_image_get_raw_color_profile(const struct heif_image *image, void *out_data)
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)
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:2339
@ heif_orientation_rotate_180
Definition: heif.h:2342
@ heif_orientation_rotate_90_cw_then_flip_horizontally
Definition: heif.h:2344
@ heif_orientation_rotate_90_cw_then_flip_vertically
Definition: heif.h:2346
@ heif_orientation_flip_vertically
Definition: heif.h:2343
@ heif_orientation_rotate_270_cw
Definition: heif.h:2347
@ heif_orientation_flip_horizontally
Definition: heif.h:2341
@ heif_orientation_normal
Definition: heif.h:2340
@ heif_orientation_rotate_90_cw
Definition: heif.h:2345
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_context * heif_image_handle_get_context(const struct heif_image_handle *handle)
struct heif_color_profile_nclx * heif_nclx_color_profile_alloc(void)
struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter *, const char *const **out_stringarray)
struct heif_error heif_image_handle_decode_image_tile(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, uint32_t tile_x, uint32_t tile_y)
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:364
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)
const struct heif_security_limits * heif_get_disabled_security_limits()
void heif_context_add_compatible_brand(struct heif_context *ctx, heif_brand2 compatible_brand)
heif_reader_grow_status
Definition: heif.h:961
@ heif_reader_grow_status_timeout
Definition: heif.h:963
@ heif_reader_grow_status_size_beyond_eof
Definition: heif.h:964
@ heif_reader_grow_status_size_reached
Definition: heif.h:962
@ heif_reader_grow_status_error
Definition: heif.h:965
LIBHEIF_API int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor *)
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)
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)
const char * heif_image_handle_get_metadata_item_uri_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
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)
struct heif_error heif_image_extend_to_size_fill_with_zero(struct heif_image *image, uint32_t width, uint32_t height)
int heif_image_get_bits_per_pixel(const struct heif_image *, enum heif_channel channel)
const struct heif_encoder_parameter *const * heif_encoder_list_parameters(struct heif_encoder *)
struct heif_context * heif_context_alloc(void)
const char * heif_encoder_get_name(const struct heif_encoder *)
heif_brand2 heif_read_minor_version_brand(const uint8_t *data, int len)
int heif_image_handle_get_ispe_width(const struct heif_image_handle *handle)
const char * heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor *)
int heif_image_handle_get_pixel_aspect_ratio(const struct heif_image_handle *, uint32_t *aspect_h, uint32_t *aspect_v)
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)
LIBHEIF_API 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.
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)
LIBHEIF_API struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin *)
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:519
@ heif_metadata_compression_deflate
Definition: heif.h:523
@ heif_metadata_compression_zlib
Definition: heif.h:524
@ heif_metadata_compression_off
Definition: heif.h:520
@ heif_metadata_compression_brotli
Definition: heif.h:525
@ heif_metadata_compression_auto
Definition: heif.h:521
@ heif_metadata_compression_unknown
Definition: heif.h:522
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:71
#define heif_fourcc(a, b, c, d)
Definition: heif.h:74
int heif_image_handle_get_mastering_display_colour_volume(const struct heif_image_handle *, struct heif_mastering_display_colour_volume *out)
LIBHEIF_API struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin *)
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)
const struct heif_security_limits * heif_get_global_security_limits()
LIBHEIF_API struct heif_error heif_image_extend_padding_to_size(struct heif_image *image, int min_physical_width, int min_physical_height)
struct heif_error heif_image_set_nclx_color_profile(struct heif_image *image, const struct heif_color_profile_nclx *color_profile)
struct heif_error heif_context_add_overlay_image(struct heif_context *ctx, uint32_t image_width, uint32_t image_height, uint16_t nImages, const heif_item_id *image_ids, int32_t *offsets, const uint16_t background_rgba[4], struct heif_image_handle **out_iovl_image_handle)
heif_filetype_result
Definition: heif.h:617
@ heif_filetype_maybe
Definition: heif.h:621
@ heif_filetype_yes_unsupported
Definition: heif.h:620
@ heif_filetype_yes_supported
Definition: heif.h:619
@ heif_filetype_no
Definition: heif.h:618
const char * heif_image_handle_get_metadata_content_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
struct heif_error heif_context_get_primary_image_handle(struct heif_context *ctx, struct heif_image_handle **)
struct heif_error heif_image_handle_get_grid_image_tile_id(const struct heif_image_handle *handle, int process_image_transformations, uint32_t tile_x, uint32_t tile_y, heif_item_id *out_tile_item_id)
heif_depth_representation_type
Definition: heif.h:1356
@ heif_depth_representation_type_nonuniform_disparity
Definition: heif.h:1360
@ heif_depth_representation_type_uniform_inverse_Z
Definition: heif.h:1357
@ heif_depth_representation_type_uniform_disparity
Definition: heif.h:1358
@ heif_depth_representation_type_uniform_Z
Definition: heif.h:1359
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)
struct heif_error heif_context_add_image_tile(struct heif_context *ctx, struct heif_image_handle *tiled_image, uint32_t tile_x, uint32_t tile_y, const struct heif_image *image, struct heif_encoder *encoder)
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_camera_extrinsic_matrix_get_rotation_matrix(const struct heif_camera_extrinsic_matrix *, double *out_matrix_row_major)
heif_color_profile_type
Definition: heif.h:1508
@ heif_color_profile_type_rICC
Definition: heif.h:1511
@ heif_color_profile_type_prof
Definition: heif.h:1512
@ heif_color_profile_type_nclx
Definition: heif.h:1510
@ heif_color_profile_type_not_present
Definition: heif.h:1509
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)
enum heif_filetype_result heif_check_filetype(const uint8_t *data, int len)
struct heif_decoding_options * heif_decoding_options_alloc(void)
heif_transfer_characteristics
Definition: heif.h:1550
@ heif_transfer_characteristic_linear
Definition: heif.h:1557
@ heif_transfer_characteristic_unspecified
Definition: heif.h:1552
@ heif_transfer_characteristic_ITU_R_BT_2020_2_12bit
Definition: heif.h:1564
@ heif_transfer_characteristic_ITU_R_BT_470_6_System_B_G
Definition: heif.h:1554
@ heif_transfer_characteristic_ITU_R_BT_2100_0_PQ
Definition: heif.h:1565
@ heif_transfer_characteristic_ITU_R_BT_2100_0_HLG
Definition: heif.h:1567
@ heif_transfer_characteristic_SMPTE_ST_428_1
Definition: heif.h:1566
@ heif_transfer_characteristic_ITU_R_BT_709_5
Definition: heif.h:1551
@ heif_transfer_characteristic_ITU_R_BT_1361
Definition: heif.h:1561
@ heif_transfer_characteristic_IEC_61966_2_1
Definition: heif.h:1562
@ heif_transfer_characteristic_SMPTE_240M
Definition: heif.h:1556
@ heif_transfer_characteristic_logarithmic_100_sqrt10
Definition: heif.h:1559
@ heif_transfer_characteristic_ITU_R_BT_601_6
Definition: heif.h:1555
@ heif_transfer_characteristic_IEC_61966_2_4
Definition: heif.h:1560
@ heif_transfer_characteristic_logarithmic_100
Definition: heif.h:1558
@ heif_transfer_characteristic_ITU_R_BT_2020_2_10bit
Definition: heif.h:1563
@ heif_transfer_characteristic_ITU_R_BT_470_6_System_M
Definition: heif.h:1553
void heif_color_conversion_options_set_defaults(struct heif_color_conversion_options *)
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)
LIBHEIF_API struct heif_error heif_register_decoder(struct heif_context *heif, const struct heif_decoder_plugin *)
heif_brand2 heif_fourcc_to_brand(const char *brand_fourcc)
uint32_t heif_entity_group_id
Definition: heif.h:1314
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_encoding_options * heif_encoding_options_alloc(void)
const char *const * heif_get_plugin_directories(void)
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_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:1719
@ heif_chroma_upsampling_bilinear
Definition: heif.h:1721
@ heif_chroma_upsampling_nearest_neighbor
Definition: heif.h:1720
heif_chroma_downsampling_algorithm
Definition: heif.h:1709
@ heif_chroma_downsampling_nearest_neighbor
Definition: heif.h:1710
@ heif_chroma_downsampling_sharp_yuv
Definition: heif.h:1715
@ heif_chroma_downsampling_average
Definition: heif.h:1711
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:2229
@ heif_encoder_parameter_type_boolean
Definition: heif.h:2231
@ heif_encoder_parameter_type_integer
Definition: heif.h:2230
@ heif_encoder_parameter_type_string
Definition: heif.h:2232
int heif_image_has_mastering_display_colour_volume(const struct heif_image *)
heif_matrix_coefficients
Definition: heif.h:1571
@ heif_matrix_coefficients_chromaticity_derived_non_constant_luminance
Definition: heif.h:1583
@ heif_matrix_coefficients_ITU_R_BT_601_6
Definition: heif.h:1577
@ heif_matrix_coefficients_US_FCC_T47
Definition: heif.h:1575
@ heif_matrix_coefficients_chromaticity_derived_constant_luminance
Definition: heif.h:1584
@ heif_matrix_coefficients_RGB_GBR
Definition: heif.h:1572
@ heif_matrix_coefficients_ITU_R_BT_2020_2_constant_luminance
Definition: heif.h:1581
@ heif_matrix_coefficients_ICtCp
Definition: heif.h:1585
@ heif_matrix_coefficients_ITU_R_BT_470_6_System_B_G
Definition: heif.h:1576
@ heif_matrix_coefficients_unspecified
Definition: heif.h:1574
@ heif_matrix_coefficients_YCgCo
Definition: heif.h:1579
@ heif_matrix_coefficients_SMPTE_240M
Definition: heif.h:1578
@ heif_matrix_coefficients_ITU_R_BT_2020_2_non_constant_luminance
Definition: heif.h:1580
@ heif_matrix_coefficients_SMPTE_ST_2085
Definition: heif.h:1582
@ heif_matrix_coefficients_ITU_R_BT_709_5
Definition: heif.h:1573
LIBHEIF_API 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_security_limits * heif_context_get_security_limits(const struct heif_context *)
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:1534
@ heif_color_primaries_SMPTE_ST_428_1
Definition: heif.h:1543
@ heif_color_primaries_ITU_R_BT_709_5
Definition: heif.h:1535
@ heif_color_primaries_generic_film
Definition: heif.h:1541
@ heif_color_primaries_EBU_Tech_3213_E
Definition: heif.h:1546
@ heif_color_primaries_ITU_R_BT_601_6
Definition: heif.h:1539
@ heif_color_primaries_ITU_R_BT_470_6_System_M
Definition: heif.h:1537
@ heif_color_primaries_unspecified
Definition: heif.h:1536
@ heif_color_primaries_SMPTE_240M
Definition: heif.h:1540
@ heif_color_primaries_ITU_R_BT_470_6_System_B_G
Definition: heif.h:1538
@ heif_color_primaries_ITU_R_BT_2020_2_and_2100_0
Definition: heif.h:1542
@ heif_color_primaries_SMPTE_EG_432_1
Definition: heif.h:1545
@ heif_color_primaries_SMPTE_RP_431_2
Definition: heif.h:1544
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:2012
uint32_t ambient_illumination
Definition: heif.h:2013
uint16_t ambient_light_x
Definition: heif.h:2014
uint16_t ambient_light_y
Definition: heif.h:2015
Definition: heif.h:1655
double principal_point_x
Definition: heif.h:1658
double focal_length_y
Definition: heif.h:1657
double principal_point_y
Definition: heif.h:1659
double skew
Definition: heif.h:1660
double focal_length_x
Definition: heif.h:1656
Definition: heif.h:1726
uint8_t only_use_preferred_chroma_algorithm
Definition: heif.h:1741
uint8_t version
Definition: heif.h:1728
enum heif_chroma_upsampling_algorithm preferred_chroma_upsampling_algorithm
Definition: heif.h:1733
enum heif_chroma_downsampling_algorithm preferred_chroma_downsampling_algorithm
Definition: heif.h:1732
Definition: heif.h:1589
enum heif_transfer_characteristics transfer_characteristics
Definition: heif.h:1595
float color_primary_green_x
Definition: heif.h:1602
enum heif_matrix_coefficients matrix_coefficients
Definition: heif.h:1596
float color_primary_blue_x
Definition: heif.h:1603
float color_primary_white_y
Definition: heif.h:1604
float color_primary_red_x
Definition: heif.h:1601
float color_primary_red_y
Definition: heif.h:1601
float color_primary_white_x
Definition: heif.h:1604
enum heif_color_primaries color_primaries
Definition: heif.h:1594
float color_primary_green_y
Definition: heif.h:1602
uint8_t version
Definition: heif.h:1592
float color_primary_blue_y
Definition: heif.h:1603
uint8_t full_range_flag
Definition: heif.h:1597
Definition: heif.h:1970
uint16_t max_content_light_level
Definition: heif.h:1971
uint16_t max_pic_average_light_level
Definition: heif.h:1972
double min_display_mastering_luminance
Definition: heif.h:2008
float white_point_y
Definition: heif.h:2006
float display_primaries_y[3]
Definition: heif.h:2004
double max_display_mastering_luminance
Definition: heif.h:2007
float white_point_x
Definition: heif.h:2005
float display_primaries_x[3]
Definition: heif.h:2003
Definition: heif.h:1753
void(* start_progress)(enum heif_progress_step step, int max_progress, void *progress_user_data)
Definition: heif.h:1763
void(* on_progress)(enum heif_progress_step step, int progress, void *progress_user_data)
Definition: heif.h:1765
uint8_t convert_hdr_to_8bit
Definition: heif.h:1773
const char * decoder_id
Definition: heif.h:1786
uint8_t ignore_transformations
Definition: heif.h:1760
void * progress_user_data
Definition: heif.h:1769
uint8_t version
Definition: heif.h:1754
void(* end_progress)(enum heif_progress_step step, void *progress_user_data)
Definition: heif.h:1767
int(* cancel_decoding)(void *progress_user_data)
Definition: heif.h:1794
struct heif_color_conversion_options color_conversion_options
Definition: heif.h:1790
uint8_t strict_decoding
Definition: heif.h:1779
Definition: heif.h:1364
uint8_t * depth_nonlinear_representation_model
Definition: heif.h:1383
double z_near
Definition: heif.h:1374
double d_min
Definition: heif.h:1376
double d_max
Definition: heif.h:1377
enum heif_depth_representation_type depth_representation_type
Definition: heif.h:1379
uint8_t has_z_far
Definition: heif.h:1370
uint32_t disparity_reference_view
Definition: heif.h:1380
double z_far
Definition: heif.h:1375
uint32_t depth_nonlinear_representation_model_size
Definition: heif.h:1382
uint8_t has_z_near
Definition: heif.h:1369
uint8_t has_d_min
Definition: heif.h:1371
uint8_t version
Definition: heif.h:1365
uint8_t has_d_max
Definition: heif.h:1372
Definition: heif.h:2352
enum heif_orientation image_orientation
Definition: heif.h:2379
uint8_t prefer_uncC_short_form
Definition: heif.h:2388
uint8_t save_alpha_channel
Definition: heif.h:2357
uint8_t version
Definition: heif.h:2353
uint8_t macOS_compatibility_workaround_no_nclx_profile
Definition: heif.h:2374
uint8_t macOS_compatibility_workaround
Definition: heif.h:2362
uint8_t save_two_colr_boxes_when_ICC_and_nclx_available
Definition: heif.h:2366
struct heif_color_profile_nclx * output_nclx_profile
Definition: heif.h:2372
struct heif_color_conversion_options color_conversion_options
Definition: heif.h:2383
Definition: heif.h:1317
heif_item_id * entities
Definition: heif.h:1320
heif_entity_group_id entity_group_id
Definition: heif.h:1318
uint32_t entity_group_type
Definition: heif.h:1319
uint32_t num_entities
Definition: heif.h:1321
Definition: heif.h:349
const char * message
Definition: heif.h:357
enum heif_suberror_code subcode
Definition: heif.h:354
enum heif_error_code code
Definition: heif.h:351
Definition: heif.h:1258
uint32_t num_columns
Definition: heif.h:1263
uint32_t image_width
Definition: heif.h:1268
uint32_t num_rows
Definition: heif.h:1264
int version
Definition: heif.h:1259
uint32_t top_offset
Definition: heif.h:1274
uint32_t tile_height
Definition: heif.h:1266
uint32_t left_offset
Definition: heif.h:1275
uint32_t image_height
Definition: heif.h:1269
uint32_t tile_width
Definition: heif.h:1265
uint32_t extra_dimension_size[8]
Definition: heif.h:1278
uint8_t number_of_extra_dimensions
Definition: heif.h:1277
Definition: heif.h:531
int version
Definition: heif.h:532
uint16_t white_point_y
Definition: heif.h:1995
uint16_t display_primaries_y[3]
Definition: heif.h:1993
uint32_t min_display_mastering_luminance
Definition: heif.h:1997
uint32_t max_display_mastering_luminance
Definition: heif.h:1996
uint16_t white_point_x
Definition: heif.h:1994
uint16_t display_primaries_x[3]
Definition: heif.h:1992
Definition: heif.h:585
void * internal_handle
Definition: heif.h:589
const void * plugin
Definition: heif.h:588
int version
Definition: heif.h:586
enum heif_plugin_type type
Definition: heif.h:587
Definition: heif.h:969
int reader_error_code
Definition: heif.h:979
uint64_t range_end
Definition: heif.h:976
enum heif_reader_grow_status status
Definition: heif.h:970
const char * reader_error_msg
Definition: heif.h:980
Definition: heif.h:985
void(* release_file_range)(uint64_t start_pos, uint64_t end_pos, void *userdata)
Definition: heif.h:1045
int reader_api_version
Definition: heif.h:987
struct heif_reader_range_request_result(* request_range)(uint64_t start_pos, uint64_t end_pos, void *userdata)
Definition: heif.h:1032
enum heif_reader_grow_status(* wait_for_file_size)(int64_t target_size, void *userdata)
Definition: heif.h:1009
int64_t(* get_position)(void *userdata)
Definition: heif.h:990
int(* read)(void *data, size_t size, void *userdata)
Definition: heif.h:994
void(* preload_range_hint)(uint64_t start_pos, uint64_t end_pos, void *userdata)
Definition: heif.h:1039
int(* seek)(int64_t position, void *userdata)
Definition: heif.h:998
void(* release_error_msg)(const char *msg)
Definition: heif.h:1050
Definition: heif.h:1137
uint32_t max_iloc_extents_per_item
Definition: heif.h:1155
uint64_t max_number_of_tiles
Definition: heif.h:1146
uint32_t max_children_per_box
Definition: heif.h:1158
uint8_t version
Definition: heif.h:1138
uint64_t max_image_size_pixels
Definition: heif.h:1145
uint32_t max_items
Definition: heif.h:1148
uint32_t max_components
Definition: heif.h:1153
uint64_t max_memory_block_size
Definition: heif.h:1151
uint32_t max_color_profile_size
Definition: heif.h:1150
uint32_t max_size_entity_group
Definition: heif.h:1156
uint32_t max_bayer_pattern_pixels
Definition: heif.h:1147
Definition: heif.h:2057
struct heif_error(* write)(struct heif_context *ctx, const void *data, size_t size, void *userdata)
Definition: heif.h:2064
int writer_api_version
Definition: heif.h:2059