libheif
Loading...
Searching...
No Matches
heif.h
Go to the documentation of this file.
1/*
2 * HEIF codec.
3 * Copyright (c) 2017-2023 Dirk Farin <dirk.farin@gmail.com>
4 *
5 * This file is part of libheif.
6 *
7 * libheif is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation, either version 3 of
10 * the License, or (at your option) any later version.
11 *
12 * libheif is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with libheif. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21#ifndef LIBHEIF_HEIF_H
22#define LIBHEIF_HEIF_H
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
33#include <stddef.h>
34#include <stdint.h>
35
36#include <libheif/heif_version.h>
37
38
39// API versions table
40//
41// release dec.options enc.options heif_reader heif_writer depth.rep col.profile
42// ------------------------------------------------------------------------------------------
43// 1.0 1 N/A N/A N/A 1 N/A
44// 1.1 1 N/A N/A 1 1 N/A
45// 1.3 1 1 1 1 1 N/A
46// 1.4 1 1 1 1 1 1
47// 1.7 2 1 1 1 1 1
48// 1.9.2 2 2 1 1 1 1
49// 1.10 2 3 1 1 1 1
50// 1.11 2 4 1 1 1 1
51// 1.13 3 4 1 1 1 1
52// 1.14 3 5 1 1 1 1
53// 1.15 4 5 1 1 1 1
54// 1.16 5 6 1 1 1 1
55// 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.
80LIBHEIF_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
97struct heif_context;
98struct heif_image_handle;
99struct 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
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
346
347
349{
350 // main error category
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.
361LIBHEIF_API extern const struct heif_error heif_error_success;
362
363
364typedef uint32_t heif_item_id;
365typedef uint32_t heif_property_id;
366
367
368
369// ========================= enum types ======================
370
455
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.
502
517
527
528// ========================= library initialization ======================
529
531{
533
534 // currently no parameters
535};
536
537
559
573void heif_deinit(void);
574
575
576// --- Plugins are currently only supported on Unix platforms.
577
583
585{
586 int version; // version of this info struct
588 const void* plugin;
589 void* internal_handle; // for internal use only
590};
591
593struct heif_error heif_load_plugin(const char* filename, struct heif_plugin_info const** out_plugin);
594
596struct 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
602struct 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).
608const char*const* heif_get_plugin_directories(void);
609
611void 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
623
624// input data should be at least 12 bytes
626enum heif_filetype_result heif_check_filetype(const uint8_t* data, int len);
627
638struct heif_error heif_has_compatible_filetype(const uint8_t* data, int len);
639
641int 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
670enum heif_brand heif_main_brand(const uint8_t* data, int len);
671
672
673typedef 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
889heif_brand2 heif_read_main_brand(const uint8_t* data, int len);
890
891// input data should be at least 16 bytes
893heif_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
897heif_brand2 heif_fourcc_to_brand(const char* brand_fourcc);
898
899// the output buffer must be at least 4 bytes long
901void 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
909int 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.
914struct 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.
937const 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().
950struct heif_context* heif_context_alloc(void);
951
952// Free a previously allocated HEIF context. You should not free a context twice.
954void heif_context_free(struct heif_context*);
955
956
957
958struct 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
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.
1057struct 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.
1064struct 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.
1072 const void* mem, size_t size,
1073 const struct heif_reading_options*);
1074
1076struct 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.
1086
1088int 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
1098struct 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.
1104 struct heif_image_handle**);
1105
1106// Get the image handle for a known image ID.
1108struct 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.
1116void 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().
1123void 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.
1131void 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
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.
1173struct 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.
1178struct 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.
1193void heif_image_handle_release(const struct heif_image_handle*);
1194
1195// Check whether the given image_handle is the primary image of the file.
1197int heif_image_handle_is_primary_image(const struct heif_image_handle* handle);
1198
1200heif_item_id heif_image_handle_get_item_id(const struct heif_image_handle* handle);
1201
1202// Get the resolution of an image.
1204int heif_image_handle_get_width(const struct heif_image_handle* handle);
1205
1207int heif_image_handle_get_height(const struct heif_image_handle* handle);
1208
1210int heif_image_handle_has_alpha_channel(const struct heif_image_handle*);
1211
1213int 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.
1218int 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.
1223int 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.
1232struct 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.
1240int heif_image_handle_get_ispe_width(const struct heif_image_handle* handle);
1241
1243int 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.
1254struct heif_context* heif_image_handle_get_context(const struct heif_image_handle* handle);
1255
1256
1258{
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;
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).
1285struct 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.
1292struct 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
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.
1304struct 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
1314typedef uint32_t heif_entity_group_id;
1315
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.
1327struct 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().
1334void heif_entity_groups_release(struct heif_entity_group*, int num_groups);
1335
1336
1337// ------------------------- depth images -------------------------
1338
1340int heif_image_handle_has_depth_image(const struct heif_image_handle*);
1341
1343int heif_image_handle_get_number_of_depth_images(const struct heif_image_handle* handle);
1344
1346int heif_image_handle_get_list_of_depth_image_IDs(const struct heif_image_handle* handle,
1347 heif_item_id* ids, int count);
1348
1350struct 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
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.
1398int 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.
1408int heif_image_handle_get_number_of_thumbnails(const struct heif_image_handle* handle);
1409
1411int 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.
1416struct 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.
1428int heif_image_handle_get_number_of_auxiliary_images(const struct heif_image_handle* handle,
1429 int aux_filter);
1430
1432int 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().
1438struct heif_error heif_image_handle_get_auxiliary_type(const struct heif_image_handle* handle,
1439 const char** out_type);
1440
1442void 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.
1447void 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.
1452struct 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.
1462int 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.
1468int 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.
1477const 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".
1483const 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.
1488size_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.
1496struct 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
1502const 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
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.
1522enum heif_color_profile_type heif_image_handle_get_color_profile_type(const struct heif_image_handle* handle);
1523
1525size_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.
1529struct heif_error heif_image_handle_get_raw_color_profile(const struct heif_image_handle* handle,
1530 void* out_data);
1531
1532
1548
1569
1587
1606
1609
1612
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.
1620struct 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.
1637
1638// Returns the size of the ICC profile if one is assigned to the image. Otherwise, it returns 0.
1640size_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.
1644struct heif_error heif_image_get_raw_color_profile(const struct heif_image* image,
1645 void* out_data);
1646
1648struct 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
1662
1663
1665int heif_image_handle_has_camera_intrinsic_matrix(const struct heif_image_handle* handle);
1666
1668struct 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
1672struct heif_camera_extrinsic_matrix;
1673
1675int heif_image_handle_has_camera_extrinsic_matrix(const struct heif_image_handle* handle);
1676
1678struct heif_error heif_image_handle_get_camera_extrinsic_matrix(const struct heif_image_handle* handle,
1679 struct heif_camera_extrinsic_matrix** out_matrix);
1680
1682void heif_camera_extrinsic_matrix_release(struct heif_camera_extrinsic_matrix*);
1683
1685struct 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
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.
1717
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.
1815struct 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.
1823enum heif_colorspace heif_image_get_colorspace(const struct heif_image*);
1824
1825// Get the chroma format of the image.
1827enum heif_chroma heif_image_get_chroma_format(const struct heif_image*);
1828
1837int heif_image_get_width(const struct heif_image* img, enum heif_channel channel);
1838
1847int heif_image_get_height(const struct heif_image* img, enum heif_channel channel);
1848
1858int heif_image_get_primary_width(const struct heif_image* img);
1859
1869int heif_image_get_primary_height(const struct heif_image* img);
1870
1872struct 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.
1882int 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).
1891int heif_image_get_bits_per_pixel_range(const struct heif_image*, enum heif_channel channel);
1892
1894int 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.
1902const uint8_t* heif_image_get_plane_readonly(const struct heif_image*,
1903 enum heif_channel channel,
1904 int* out_stride);
1905
1907uint8_t* heif_image_get_plane(struct heif_image*,
1908 enum heif_channel channel,
1909 int* out_stride);
1910
1911
1912
1913struct heif_scaling_options;
1914
1915// Currently, heif_scaling_options is not defined yet. Pass a NULL pointer.
1917struct 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.
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.
1931struct 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
1937struct 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'.
1952int 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.
1959void heif_image_add_decoding_warning(struct heif_image* image,
1960 struct heif_error err);
1961
1962// Release heif_image.
1964void 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.
1974
1976int heif_image_has_content_light_level(const struct heif_image*);
1977
1979void 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.
1983int heif_image_handle_get_content_light_level(const struct heif_image_handle*, struct heif_content_light_level* out);
1984
1986void 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).
1999
2000// The units for max_display_mastering_luminance and min_display_mastering_luminance is Candelas per square meter.
2010
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
2040void 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.
2044int heif_image_handle_get_pixel_aspect_ratio(const struct heif_image_handle*, uint32_t* aspect_h, uint32_t* aspect_v);
2045
2047void heif_image_set_pixel_aspect_ratio(struct heif_image*, uint32_t aspect_h, uint32_t aspect_v);
2048
2049// ====================================================================================================
2050// Encoding API
2051
2053struct 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 struct heif_error (* write)(struct heif_context* ctx, // TODO: why do we need this parameter?
2063 const void* data,
2064 size_t size,
2065 void* userdata);
2066};
2067
2069struct heif_error heif_context_write(struct heif_context*,
2070 struct heif_writer* writer,
2071 void* userdata);
2072
2073// Add a compatible brand that is now added automatically by libheif when encoding images (e.g. some application brands like 'geo1').
2075void heif_context_add_compatible_brand(struct heif_context* ctx,
2076 heif_brand2 compatible_brand);
2077
2078// ----- encoder -----
2079
2080// The encoder used for actually encoding an image.
2081struct heif_encoder;
2082
2083// A description of the encoder's capabilities and name.
2084struct heif_encoder_descriptor;
2085
2086// A configuration parameter of the encoder. Each encoder implementation may have a different
2087// set of parameters. For the most common settings (e.q. quality), special functions to set
2088// the parameters are provided.
2089struct heif_encoder_parameter;
2090
2091struct heif_decoder_descriptor;
2092
2093// Get a list of available decoders. You can filter the encoders by compression format.
2094// Use format_filter==heif_compression_undefined to get all available decoders.
2095// The returned list of decoders is sorted by their priority (which is a plugin property).
2096// The number of decoders is returned, which are not more than 'count' if (out_decoders != nullptr).
2097// By setting out_decoders==nullptr, you can query the number of decoders, 'count' is ignored.
2100 const struct heif_decoder_descriptor** out_decoders,
2101 int count);
2102
2103// Return a long, descriptive name of the decoder (including version information).
2105const char* heif_decoder_descriptor_get_name(const struct heif_decoder_descriptor*);
2106
2107// Return a short, symbolic name for identifying the decoder.
2108// This name should stay constant over different decoder versions.
2109// Note: the returned ID may be NULL for old plugins that don't support this yet.
2111const char* heif_decoder_descriptor_get_id_name(const struct heif_decoder_descriptor*);
2112
2113// DEPRECATED: use heif_get_encoder_descriptors() instead.
2114// Get a list of available encoders. You can filter the encoders by compression format and name.
2115// Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards.
2116// The returned list of encoders is sorted by their priority (which is a plugin property).
2117// The number of encoders is returned, which are not more than 'count' if (out_encoders != nullptr).
2118// By setting out_encoders==nullptr, you can query the number of encoders, 'count' is ignored.
2119// Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
2121int heif_context_get_encoder_descriptors(struct heif_context*, // TODO: why do we need this parameter?
2122 enum heif_compression_format format_filter,
2123 const char* name_filter,
2124 const struct heif_encoder_descriptor** out_encoders,
2125 int count);
2126
2127// Get a list of available encoders. You can filter the encoders by compression format and name.
2128// Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards.
2129// The returned list of encoders is sorted by their priority (which is a plugin property).
2130// The number of encoders is returned, which are not more than 'count' if (out_encoders != nullptr).
2131// By setting out_encoders==nullptr, you can query the number of encoders, 'count' is ignored.
2132// Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
2135 const char* name_filter,
2136 const struct heif_encoder_descriptor** out_encoders,
2137 int count);
2138
2139// Return a long, descriptive name of the encoder (including version information).
2141const char* heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor*);
2142
2143// Return a short, symbolic name for identifying the encoder.
2144// This name should stay constant over different encoder versions.
2146const char* heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor*);
2147
2150heif_encoder_descriptor_get_compression_format(const struct heif_encoder_descriptor*);
2151
2153int heif_encoder_descriptor_supports_lossy_compression(const struct heif_encoder_descriptor*);
2154
2156int heif_encoder_descriptor_supports_lossless_compression(const struct heif_encoder_descriptor*);
2157
2158
2159// Get an encoder instance that can be used to actually encode images from a descriptor.
2161struct heif_error heif_context_get_encoder(struct heif_context* context,
2162 const struct heif_encoder_descriptor*,
2163 struct heif_encoder** out_encoder);
2164
2165// Quick check whether there is a decoder available for the given format.
2166// Note that the decoder still may not be able to decode all variants of that format.
2167// You will have to query that further (todo) or just try to decode and check the returned error.
2170
2171// Quick check whether there is an enoder available for the given format.
2172// Note that the encoder may be limited to a certain subset of features (e.g. only 8 bit, only lossy).
2173// You will have to query the specific capabilities further.
2176
2177// Get an encoder for the given compression format. If there are several encoder plugins
2178// for this format, the encoder with the highest plugin priority will be returned.
2180struct heif_error heif_context_get_encoder_for_format(struct heif_context* context,
2181 enum heif_compression_format format,
2182 struct heif_encoder**);
2183
2184// You have to release the encoder after use.
2186void heif_encoder_release(struct heif_encoder*);
2187
2188// Get the encoder name from the encoder itself.
2190const char* heif_encoder_get_name(const struct heif_encoder*);
2191
2192
2193// --- Encoder Parameters ---
2194
2195// Libheif supports settings parameters through specialized functions and through
2196// generic functions by parameter name. Sometimes, the same parameter can be set
2197// in both ways.
2198// We consider it best practice to use the generic parameter functions only in
2199// dynamically generated user interfaces, as no guarantees are made that some specific
2200// parameter names are supported by all plugins.
2201
2202
2203// Set a 'quality' factor (0-100). How this is mapped to actual encoding parameters is
2204// encoder dependent.
2206struct heif_error heif_encoder_set_lossy_quality(struct heif_encoder*, int quality);
2207
2209struct heif_error heif_encoder_set_lossless(struct heif_encoder*, int enable);
2210
2211// level should be between 0 (= none) to 4 (= full)
2213struct heif_error heif_encoder_set_logging_level(struct heif_encoder*, int level);
2214
2215// Get a generic list of encoder parameters.
2216// Each encoder may define its own, additional set of parameters.
2217// You do not have to free the returned list.
2219const struct heif_encoder_parameter* const* heif_encoder_list_parameters(struct heif_encoder*);
2220
2221// Return the parameter name.
2223const char* heif_encoder_parameter_get_name(const struct heif_encoder_parameter*);
2224
2225
2232
2233// Return the parameter type.
2235enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter*);
2236
2237// DEPRECATED. Use heif_encoder_parameter_get_valid_integer_values() instead.
2239struct heif_error heif_encoder_parameter_get_valid_integer_range(const struct heif_encoder_parameter*,
2240 int* have_minimum_maximum,
2241 int* minimum, int* maximum);
2242
2243// If integer is limited by a range, have_minimum and/or have_maximum will be != 0 and *minimum, *maximum is set.
2244// If integer is limited by a fixed set of values, *num_valid_values will be >0 and *out_integer_array is set.
2246struct heif_error heif_encoder_parameter_get_valid_integer_values(const struct heif_encoder_parameter*,
2247 int* have_minimum, int* have_maximum,
2248 int* minimum, int* maximum,
2249 int* num_valid_values,
2250 const int** out_integer_array);
2251
2253struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter*,
2254 const char* const** out_stringarray);
2255
2256
2259 const char* parameter_name,
2260 int value);
2261
2264 const char* parameter_name,
2265 int* value);
2266
2267// TODO: name should be changed to heif_encoder_get_valid_integer_parameter_range
2268LIBHEIF_API // DEPRECATED.
2270 const char* parameter_name,
2271 int* have_minimum_maximum,
2272 int* minimum, int* maximum);
2273
2276 const char* parameter_name,
2277 int value);
2278
2281 const char* parameter_name,
2282 int* value);
2283
2286 const char* parameter_name,
2287 const char* value);
2288
2291 const char* parameter_name,
2292 char* value, int value_size);
2293
2294// returns a NULL-terminated list of valid strings or NULL if all values are allowed
2297 const char* parameter_name,
2298 const char* const** out_stringarray);
2299
2302 const char* parameter_name,
2303 int* have_minimum, int* have_maximum,
2304 int* minimum, int* maximum,
2305 int* num_valid_values,
2306 const int** out_integer_array);
2307
2308// Set a parameter of any type to the string value.
2309// Integer values are parsed from the string.
2310// Boolean values can be "true"/"false"/"1"/"0"
2311//
2312// x265 encoder specific note:
2313// When using the x265 encoder, you may pass any of its parameters by
2314// prefixing the parameter name with 'x265:'. Hence, to set the 'ctu' parameter,
2315// you will have to set 'x265:ctu' in libheif.
2316// Note that there is no checking for valid parameters when using the prefix.
2318struct heif_error heif_encoder_set_parameter(struct heif_encoder*,
2319 const char* parameter_name,
2320 const char* value);
2321
2322// Get the current value of a parameter of any type as a human readable string.
2323// The returned string is compatible with heif_encoder_set_parameter().
2325struct heif_error heif_encoder_get_parameter(struct heif_encoder*,
2326 const char* parameter_name,
2327 char* value_ptr, int value_size);
2328
2329// Query whether a specific parameter has a default value.
2331int heif_encoder_has_default(struct heif_encoder*,
2332 const char* parameter_name);
2333
2334
2335// The orientation values are defined equal to the EXIF Orientation tag.
2347
2348
2350{
2351 uint8_t version;
2352
2353 // version 1 options
2354
2355 uint8_t save_alpha_channel; // default: true
2356
2357 // version 2 options
2358
2359 // DEPRECATED. This option is not required anymore. Its value will be ignored.
2361
2362 // version 3 options
2363
2365
2366 // version 4 options
2367
2368 // Set this to the NCLX parameters to be used in the output image or set to NULL
2369 // when the same parameters as in the input image should be used.
2371
2373
2374 // version 5 options
2375
2376 // libheif will generate irot/imir boxes to match these orientations
2378
2379 // version 6 options
2380
2382
2383 // version 7 options
2384
2385 // Set this to true to use compressed form of uncC where possible.
2387
2388 // TODO: we should add a flag to force MIAF compatible outputs. E.g. this will put restrictions on grid tile sizes and
2389 // might add a clap box when the grid output size does not match the color subsampling factors.
2390 // Since some of these constraints have to be known before actually encoding the image, "forcing MIAF compatibility"
2391 // could also be a flag in the heif_context.
2392};
2393
2396
2399
2400
2401// Compress the input image.
2402// Returns a handle to the coded image in 'out_image_handle' unless out_image_handle = NULL.
2403// 'options' should be NULL for now.
2404// The first image added to the context is also automatically set the primary image, but
2405// you can change the primary image later with heif_context_set_primary_image().
2407struct heif_error heif_context_encode_image(struct heif_context*,
2408 const struct heif_image* image,
2409 struct heif_encoder* encoder,
2410 const struct heif_encoding_options* options,
2411 struct heif_image_handle** out_image_handle);
2412
2426struct heif_error heif_context_encode_grid(struct heif_context* ctx,
2427 struct heif_image** tiles,
2428 uint16_t rows,
2429 uint16_t columns,
2430 struct heif_encoder* encoder,
2431 const struct heif_encoding_options* input_options,
2432 struct heif_image_handle** out_image_handle);
2433
2435struct heif_error heif_context_add_grid_image(struct heif_context* ctx,
2436 uint32_t image_width,
2437 uint32_t image_height,
2438 uint32_t tile_columns,
2439 uint32_t tile_rows,
2440 const struct heif_encoding_options* encoding_options,
2441 struct heif_image_handle** out_grid_image_handle);
2442
2444struct heif_error heif_context_add_image_tile(struct heif_context* ctx,
2445 struct heif_image_handle* tiled_image,
2446 uint32_t tile_x, uint32_t tile_y,
2447 const struct heif_image* image,
2448 struct heif_encoder* encoder);
2449
2450// offsets[] should either be NULL (all offsets==0) or an array of size 2*nImages with x;y offset pairs.
2451// If background_rgba is NULL, the background is transparent.
2453struct heif_error heif_context_add_overlay_image(struct heif_context* ctx,
2454 uint32_t image_width,
2455 uint32_t image_height,
2456 uint16_t nImages,
2457 const heif_item_id* image_ids,
2458 int32_t* offsets,
2459 const uint16_t background_rgba[4],
2460 struct heif_image_handle** out_iovl_image_handle);
2461
2463struct heif_error heif_context_set_primary_image(struct heif_context*,
2464 struct heif_image_handle* image_handle);
2465
2466// Encode the 'image' as a scaled down thumbnail image.
2467// The image is scaled down to fit into a square area of width 'bbox_size'.
2468// If the input image is already so small that it fits into this bounding box, no thumbnail
2469// image is encoded and NULL is returned in 'out_thumb_image_handle'.
2470// No error is returned in this case.
2471// The encoded thumbnail is automatically assigned to the 'master_image_handle'. Hence, you
2472// do not have to call heif_context_assign_thumbnail().
2474struct heif_error heif_context_encode_thumbnail(struct heif_context*,
2475 const struct heif_image* image,
2476 const struct heif_image_handle* master_image_handle,
2477 struct heif_encoder* encoder,
2478 const struct heif_encoding_options* options,
2479 int bbox_size,
2480 struct heif_image_handle** out_thumb_image_handle);
2481
2482// Assign 'thumbnail_image' as the thumbnail image of 'master_image'.
2484struct heif_error heif_context_assign_thumbnail(struct heif_context*,
2485 const struct heif_image_handle* master_image,
2486 const struct heif_image_handle* thumbnail_image);
2487
2488// Add EXIF metadata to an image.
2490struct heif_error heif_context_add_exif_metadata(struct heif_context*,
2491 const struct heif_image_handle* image_handle,
2492 const void* data, int size);
2493
2494// Add XMP metadata to an image.
2496struct heif_error heif_context_add_XMP_metadata(struct heif_context*,
2497 const struct heif_image_handle* image_handle,
2498 const void* data, int size);
2499
2500// New version of heif_context_add_XMP_metadata() with data compression (experimental).
2502struct heif_error heif_context_add_XMP_metadata2(struct heif_context*,
2503 const struct heif_image_handle* image_handle,
2504 const void* data, int size,
2505 enum heif_metadata_compression compression);
2506
2507// Add generic, proprietary metadata to an image. You have to specify an 'item_type' that will
2508// identify your metadata. 'content_type' can be an additional type, or it can be NULL.
2509// For example, this function can be used to add IPTC metadata (IIM stream, not XMP) to an image.
2510// Although not standard, we propose to store IPTC data with item type="iptc", content_type=NULL.
2512struct heif_error heif_context_add_generic_metadata(struct heif_context* ctx,
2513 const struct heif_image_handle* image_handle,
2514 const void* data, int size,
2515 const char* item_type, const char* content_type);
2516
2517// Add generic metadata with item_type "uri ". Items with this type do not have a content_type, but
2518// an item_uri_type and they have no content_encoding (they are always stored uncompressed).
2521 const struct heif_image_handle* image_handle,
2522 const void* data, int size,
2523 const char* item_uri_type,
2524 heif_item_id* out_item_id);
2525
2526// --- heif_image allocation
2527
2542struct heif_error heif_image_create(int width, int height,
2543 enum heif_colorspace colorspace,
2544 enum heif_chroma chroma,
2545 struct heif_image** out_image);
2546
2576struct heif_error heif_image_add_plane(struct heif_image* image,
2577 enum heif_channel channel,
2578 int width, int height, int bit_depth);
2579
2580// Signal that the image is premultiplied by the alpha pixel values.
2582void heif_image_set_premultiplied_alpha(struct heif_image* image,
2583 int is_premultiplied_alpha);
2584
2586int heif_image_is_premultiplied_alpha(struct heif_image* image);
2587
2588// This function extends the padding of the image so that it has at least the given physical size.
2589// The padding border is filled with the pixels along the right/bottom border.
2590// This function may be useful if you want to process the image, but have some external padding requirements.
2591// The image size will not be modified if it is already larger/equal than the given physical size.
2592// I.e. you cannot assume that after calling this function, the stride will be equal to min_physical_width.
2594struct heif_error heif_image_extend_padding_to_size(struct heif_image* image, int min_physical_width, int min_physical_height);
2595
2596
2597
2598// --- register plugins
2599
2600struct heif_decoder_plugin;
2601struct heif_encoder_plugin;
2602
2603// DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead.
2605struct heif_error heif_register_decoder(struct heif_context* heif, const struct heif_decoder_plugin*);
2606
2608struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin*);
2609
2611struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin*);
2612
2613// DEPRECATED, typo in function name
2615int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor*);
2616
2617// DEPRECATED, typo in function name
2619int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor*);
2620
2621
2622#ifdef __cplusplus
2623}
2624#endif
2625
2626#endif
struct heif_error heif_encoder_set_parameter_boolean(struct heif_encoder *, const char *parameter_name, int value)
void heif_image_handle_release_auxiliary_type(const struct heif_image_handle *handle, const char **out_type)
int heif_image_handle_has_alpha_channel(const struct heif_image_handle *)
struct heif_error heif_image_create(int width, int height, enum heif_colorspace colorspace, enum heif_chroma chroma, struct heif_image **out_image)
Create a new image of the specified resolution and colorspace.
struct heif_error heif_image_handle_get_metadata(const struct heif_image_handle *handle, heif_item_id metadata_id, void *out_data)
int heif_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 *)
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 *)
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)
const struct heif_security_limits * heif_get_disabled_security_limits()
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)
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)
const char * heif_image_handle_get_metadata_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
uint32_t heif_property_id
Definition heif.h: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)
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_context * heif_context_alloc(void)
struct heif_error heif_context_add_exif_metadata(struct heif_context *, const struct heif_image_handle *image_handle, const void *data, int size)
const struct heif_encoder_parameter *const * heif_encoder_list_parameters(struct heif_encoder *)
struct heif_error heif_unload_plugin(const struct heif_plugin_info *plugin)
const char * heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor *)
int heif_image_handle_get_number_of_thumbnails(const struct heif_image_handle *handle)
struct heif_error heif_decode_image(const struct heif_image_handle *in_handle, struct heif_image **out_img, enum heif_colorspace colorspace, enum heif_chroma chroma, const struct heif_decoding_options *options)
int heif_image_has_content_light_level(const struct heif_image *)
struct heif_error heif_image_crop(struct heif_image *img, int left, int right, int top, int bottom)
struct heif_error heif_image_handle_get_camera_extrinsic_matrix(const struct heif_image_handle *handle, struct heif_camera_extrinsic_matrix **out_matrix)
const struct heif_security_limits * heif_get_global_security_limits()
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)
struct heif_error heif_nclx_color_profile_set_matrix_coefficients(struct heif_color_profile_nclx *nclx, uint16_t matrix_coefficients)
heif_brand2 heif_read_main_brand(const uint8_t *data, int len)
struct heif_error heif_list_compatible_brands(const uint8_t *data, int len, heif_brand2 **out_brands, int *out_size)
enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter *)
const uint8_t * heif_image_get_plane_readonly(const struct heif_image *, enum heif_channel channel, int *out_stride)
heif_suberror_code
Definition heif.h: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)
struct heif_decoding_options * heif_decoding_options_alloc(void)
void heif_image_release(const struct heif_image *)
size_t heif_image_get_raw_color_profile_size(const struct heif_image *image)
int heif_image_handle_has_camera_extrinsic_matrix(const struct heif_image_handle *handle)
void heif_image_get_mastering_display_colour_volume(const struct heif_image *, struct heif_mastering_display_colour_volume *out)
struct heif_error heif_has_compatible_filetype(const uint8_t *data, int len)
Check the filetype box content for a supported file type.
void heif_context_free(struct heif_context *)
void heif_context_set_maximum_image_size_limit(struct heif_context *ctx, int maximum_width)
void heif_decoding_options_free(struct heif_decoding_options *)
struct heif_context * heif_image_handle_get_context(const struct heif_image_handle *handle)
int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor *)
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)
uint8_t * heif_image_get_plane(struct heif_image *, enum heif_channel channel, int *out_stride)
const char * heif_encoder_get_name(const struct heif_encoder *)
int heif_image_get_primary_height(const struct heif_image *img)
Get the height of the main channel.
void heif_image_get_content_light_level(const struct heif_image *, struct heif_content_light_level *out)
struct heif_error heif_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)
struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin *)
struct heif_error heif_image_handle_get_auxiliary_image_handle(const struct heif_image_handle *main_image_handle, heif_item_id auxiliary_id, struct heif_image_handle **out_auxiliary_handle)
heif_error_code
Definition heif.h: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)
const char * heif_image_handle_get_metadata_content_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
const char * heif_get_file_mime_type(const uint8_t *data, int len)
struct heif_error heif_context_read_from_file(struct heif_context *, const char *filename, const struct heif_reading_options *)
int heif_image_handle_get_ispe_height(const struct heif_image_handle *handle)
heif_compression_format
libheif known compression formats.
Definition heif.h: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_error heif_image_get_raw_color_profile(const struct heif_image *image, void *out_data)
const char * heif_decoder_descriptor_get_id_name(const struct heif_decoder_descriptor *)
struct heif_error heif_image_scale_image(const struct heif_image *input, struct heif_image **output, int width, int height, const struct heif_scaling_options *options)
void heif_image_set_premultiplied_alpha(struct heif_image *image, int is_premultiplied_alpha)
enum heif_brand heif_main_brand(const uint8_t *data, int len)
int heif_get_version_number_major(void)
int heif_image_has_channel(const struct heif_image *, enum heif_channel channel)
struct heif_error heif_encoder_set_lossy_quality(struct heif_encoder *, int quality)
int heif_get_decoder_descriptors(enum heif_compression_format format_filter, const struct heif_decoder_descriptor **out_decoders, int count)
struct heif_error heif_encoder_set_logging_level(struct heif_encoder *, int level)
struct heif_error heif_context_get_image_handle(struct heif_context *ctx, heif_item_id id, struct heif_image_handle **)
heif_orientation
Definition heif.h:2337
@ heif_orientation_rotate_180
Definition heif.h:2340
@ heif_orientation_rotate_90_cw_then_flip_horizontally
Definition heif.h:2342
@ heif_orientation_rotate_90_cw_then_flip_vertically
Definition heif.h:2344
@ heif_orientation_flip_vertically
Definition heif.h:2341
@ heif_orientation_rotate_270_cw
Definition heif.h:2345
@ heif_orientation_flip_horizontally
Definition heif.h:2339
@ heif_orientation_normal
Definition heif.h:2338
@ heif_orientation_rotate_90_cw
Definition heif.h:2343
int heif_image_handle_get_number_of_metadata_blocks(const struct heif_image_handle *handle, const char *type_filter)
int heif_context_is_top_level_image_ID(struct heif_context *ctx, heif_item_id id)
struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter *, const char *const **out_stringarray)
struct heif_error heif_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)
void heif_context_add_compatible_brand(struct heif_context *ctx, heif_brand2 compatible_brand)
int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor *)
struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin *)
heif_reader_grow_status
Definition heif.h: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
void heif_nclx_color_profile_free(struct heif_color_profile_nclx *nclx_profile)
struct heif_error heif_nclx_color_profile_set_color_primaries(struct heif_color_profile_nclx *nclx, uint16_t cp)
struct heif_error heif_context_get_encoder(struct heif_context *context, const struct heif_encoder_descriptor *, struct heif_encoder **out_encoder)
struct heif_error heif_register_decoder(struct heif_context *heif, const struct heif_decoder_plugin *)
int heif_image_get_width(const struct heif_image *img, enum heif_channel channel)
Get the width of a specified image channel.
void heif_image_add_decoding_warning(struct heif_image *image, struct heif_error err)
int heif_encoder_descriptor_supports_lossless_compression(const struct heif_encoder_descriptor *)
struct heif_error heif_context_add_XMP_metadata2(struct heif_context *, const struct heif_image_handle *image_handle, const void *data, int size, enum heif_metadata_compression compression)
int heif_image_handle_get_number_of_depth_images(const struct heif_image_handle *handle)
void heif_camera_extrinsic_matrix_release(struct heif_camera_extrinsic_matrix *)
struct heif_error heif_context_write(struct heif_context *, struct heif_writer *writer, void *userdata)
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)
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)
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)
int heif_image_handle_get_list_of_thumbnail_IDs(const struct heif_image_handle *handle, heif_item_id *ids, int count)
int heif_have_decoder_for_format(enum heif_compression_format format)
int heif_image_handle_get_number_of_auxiliary_images(const struct heif_image_handle *handle, int aux_filter)
int heif_context_get_list_of_top_level_image_IDs(struct heif_context *ctx, heif_item_id *ID_array, int count)
struct heif_error heif_encoder_set_parameter(struct heif_encoder *, const char *parameter_name, const char *value)
struct heif_error heif_image_handle_get_raw_color_profile(const struct heif_image_handle *handle, void *out_data)
int heif_image_get_height(const struct heif_image *img, enum heif_channel channel)
Get the height of a specified image channel.
size_t heif_image_handle_get_raw_color_profile_size(const struct heif_image_handle *handle)
struct heif_error heif_image_handle_get_nclx_color_profile(const struct heif_image_handle *handle, struct heif_color_profile_nclx **out_data)
struct heif_security_limits * heif_context_get_security_limits(const struct heif_context *)
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
struct heif_error heif_image_extend_padding_to_size(struct heif_image *image, int min_physical_width, int min_physical_height)
const char * heif_get_version(void)
void heif_brand_to_fourcc(heif_brand2 brand, char *out_fourcc)
int heif_image_handle_get_list_of_auxiliary_image_IDs(const struct heif_image_handle *handle, int aux_filter, heif_item_id *ids, int count)
const struct heif_error heif_error_success
void heif_image_handle_free_auxiliary_types(const struct heif_image_handle *handle, const char **out_type)
void heif_free_plugin_directories(const char *const *)
void heif_depth_representation_info_free(const struct heif_depth_representation_info *info)
struct heif_error heif_context_assign_thumbnail(struct heif_context *, const struct heif_image_handle *master_image, const struct heif_image_handle *thumbnail_image)
struct heif_error heif_context_read_from_memory(struct heif_context *, const void *mem, size_t size, const struct heif_reading_options *)
int heif_image_handle_is_premultiplied_alpha(const struct heif_image_handle *)
struct heif_error heif_nclx_color_profile_set_transfer_characteristics(struct heif_color_profile_nclx *nclx, uint16_t transfer_characteristics)
#define LIBHEIF_API
Definition heif.h: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)
const char * heif_encoder_parameter_get_name(const struct heif_encoder_parameter *)
int heif_image_handle_get_list_of_metadata_block_IDs(const struct heif_image_handle *handle, const char *type_filter, heif_item_id *ids, int count)
struct heif_color_profile_nclx * heif_nclx_color_profile_alloc(void)
struct heif_error heif_image_set_nclx_color_profile(struct heif_image *image, const struct heif_color_profile_nclx *color_profile)
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 *const * heif_get_plugin_directories(void)
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)
const char * heif_image_handle_get_metadata_item_uri_type(const struct heif_image_handle *handle, heif_item_id metadata_id)
struct heif_error heif_encoder_parameter_string_valid_values(struct heif_encoder *, const char *parameter_name, const char *const **out_stringarray)
struct heif_error heif_mastering_display_colour_volume_decode(const struct heif_mastering_display_colour_volume *in, struct heif_decoded_mastering_display_colour_volume *out)
int heif_encoder_has_default(struct heif_encoder *, const char *parameter_name)
struct heif_error heif_image_add_plane(struct heif_image *image, enum heif_channel channel, int width, int height, int bit_depth)
Add an image plane to the image.
struct heif_error heif_camera_extrinsic_matrix_get_rotation_matrix(const struct heif_camera_extrinsic_matrix *, double *out_matrix_row_major)
heif_color_profile_type
Definition heif.h: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
const char * heif_decoder_descriptor_get_name(const struct heif_decoder_descriptor *)
struct heif_error heif_image_handle_get_depth_image_handle(const struct heif_image_handle *handle, heif_item_id depth_image_id, struct heif_image_handle **out_depth_handle)
struct heif_error heif_init(struct heif_init_params *)
Initialise library.
int heif_have_encoder_for_format(enum heif_compression_format format)
struct heif_encoding_options * heif_encoding_options_alloc(void)
enum heif_filetype_result heif_check_filetype(const uint8_t *data, int len)
heif_transfer_characteristics
Definition heif.h: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
const char * heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor *)
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)
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_error heif_encoder_set_parameter_string(struct heif_encoder *, const char *parameter_name, const char *value)
struct heif_error heif_image_handle_get_preferred_decoding_colorspace(const struct heif_image_handle *image_handle, enum heif_colorspace *out_colorspace, enum heif_chroma *out_chroma)
struct heif_error heif_image_handle_get_auxiliary_type(const struct heif_image_handle *handle, const char **out_type)
int heif_image_is_premultiplied_alpha(struct heif_image *image)
int heif_check_jpeg_filetype(const uint8_t *data, int len)
void heif_image_set_pixel_aspect_ratio(struct heif_image *, uint32_t aspect_h, uint32_t aspect_v)
struct heif_error heif_encoder_parameter_integer_valid_range(struct heif_encoder *, const char *parameter_name, int *have_minimum_maximum, int *minimum, int *maximum)
int heif_has_compatible_brand(const uint8_t *data, int len, const char *brand_fourcc)
heif_chroma_upsampling_algorithm
Definition heif.h: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:2227
@ heif_encoder_parameter_type_boolean
Definition heif.h:2229
@ heif_encoder_parameter_type_integer
Definition heif.h:2228
@ heif_encoder_parameter_type_string
Definition heif.h:2230
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
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:2350
enum heif_orientation image_orientation
Definition heif.h:2377
uint8_t prefer_uncC_short_form
Definition heif.h:2386
uint8_t save_alpha_channel
Definition heif.h:2355
uint8_t version
Definition heif.h:2351
uint8_t macOS_compatibility_workaround_no_nclx_profile
Definition heif.h:2372
uint8_t macOS_compatibility_workaround
Definition heif.h:2360
uint8_t save_two_colr_boxes_when_ICC_and_nclx_available
Definition heif.h:2364
struct heif_color_profile_nclx * output_nclx_profile
Definition heif.h:2370
struct heif_color_conversion_options color_conversion_options
Definition heif.h:2381
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
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:2062
int writer_api_version
Definition heif.h:2059