1 /* 2 * HEIF codec. 3 * Copyright (c) 2017 struktur AG, Dirk Farin <farin@struktur.de> 4 * 5 * This file is part of libheif. 6 * 7 * libheif is free software: you can redistribute it and/or modify 8 * it under the terms of the GNU Lesser General Public License as 9 * published by the Free Software Foundation, either version 3 of 10 * the License, or (at your option) any later version. 11 * 12 * libheif is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public License 18 * along with libheif. If not, see <http://www.gnu.org/licenses/>. 19 */ 20 21 #ifndef LIBHEIF_HEIF_H 22 #define LIBHEIF_HEIF_H 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #include <stddef.h> 29 #include <stdint.h> 30 31 #include <libheif/heif_version.h> 32 33 34 // API versions table 35 // 36 // release depth.rep dec.options enc.options heif_reader heif_writer col.profile 37 // ----------------------------------------------------------------------------------------- 38 // 1.0 1 1 N/A N/A N/A N/A 39 // 1.1 1 1 N/A N/A 1 N/A 40 // 1.3 1 1 1 1 1 N/A 41 // 1.4 1 1 1 1 1 1 42 // 1.7 1 2 1 1 1 1 43 // 1.9.2 1 2 2 1 1 1 44 // 1.10 1 2 3 1 1 1 45 46 47 #if defined(_MSC_VER) && !defined(LIBHEIF_STATIC_BUILD) 48 #ifdef LIBHEIF_EXPORTS 49 #define LIBHEIF_API __declspec(dllexport) 50 #else 51 #define LIBHEIF_API __declspec(dllimport) 52 #endif 53 #elif defined(HAVE_VISIBILITY) && HAVE_VISIBILITY 54 #ifdef LIBHEIF_EXPORTS 55 #define LIBHEIF_API __attribute__((__visibility__("default"))) 56 #else 57 #define LIBHEIF_API 58 #endif 59 #else 60 #define LIBHEIF_API 61 #endif 62 63 #define heif_fourcc(a, b, c, d) ((a<<24) | (b<<16) | (c<<8) | d) 64 65 66 /* === version numbers === */ 67 68 // Version string of linked libheif library. 69 LIBHEIF_API const char* heif_get_version(void); 70 // Numeric version of linked libheif library, encoded as 0xHHMMLL00 = HH.MM.LL. 71 LIBHEIF_API uint32_t heif_get_version_number(void); 72 73 // Numeric part "HH" from above. 74 LIBHEIF_API int heif_get_version_number_major(void); 75 // Numeric part "MM" from above. 76 LIBHEIF_API int heif_get_version_number_minor(void); 77 // Numeric part "LL" from above. 78 LIBHEIF_API int heif_get_version_number_maintenance(void); 79 80 // Helper macros to check for given versions of libheif at compile time. 81 #define LIBHEIF_MAKE_VERSION(h, m, l) ((h) << 24 | (m) << 16 | (l) << 8) 82 #define LIBHEIF_HAVE_VERSION(h, m, l) (LIBHEIF_NUMERIC_VERSION >= LIBHEIF_MAKE_VERSION(h, m, l)) 83 84 struct heif_context; 85 struct heif_image_handle; 86 struct heif_image; 87 88 89 enum heif_error_code 90 { 91 // Everything ok, no error occurred. 92 heif_error_Ok = 0, 93 94 // Input file does not exist. 95 heif_error_Input_does_not_exist = 1, 96 97 // Error in input file. Corrupted or invalid content. 98 heif_error_Invalid_input = 2, 99 100 // Input file type is not supported. 101 heif_error_Unsupported_filetype = 3, 102 103 // Image requires an unsupported decoder feature. 104 heif_error_Unsupported_feature = 4, 105 106 // Library API has been used in an invalid way. 107 heif_error_Usage_error = 5, 108 109 // Could not allocate enough memory. 110 heif_error_Memory_allocation_error = 6, 111 112 // The decoder plugin generated an error 113 heif_error_Decoder_plugin_error = 7, 114 115 // The encoder plugin generated an error 116 heif_error_Encoder_plugin_error = 8, 117 118 // Error during encoding or when writing to the output 119 heif_error_Encoding_error = 9, 120 121 // Application has asked for a color profile type that does not exist 122 heif_error_Color_profile_does_not_exist = 10 123 }; 124 125 126 enum heif_suberror_code 127 { 128 // no further information available 129 heif_suberror_Unspecified = 0, 130 131 // --- Invalid_input --- 132 133 // End of data reached unexpectedly. 134 heif_suberror_End_of_data = 100, 135 136 // Size of box (defined in header) is wrong 137 heif_suberror_Invalid_box_size = 101, 138 139 // Mandatory 'ftyp' box is missing 140 heif_suberror_No_ftyp_box = 102, 141 142 heif_suberror_No_idat_box = 103, 143 144 heif_suberror_No_meta_box = 104, 145 146 heif_suberror_No_hdlr_box = 105, 147 148 heif_suberror_No_hvcC_box = 106, 149 150 heif_suberror_No_pitm_box = 107, 151 152 heif_suberror_No_ipco_box = 108, 153 154 heif_suberror_No_ipma_box = 109, 155 156 heif_suberror_No_iloc_box = 110, 157 158 heif_suberror_No_iinf_box = 111, 159 160 heif_suberror_No_iprp_box = 112, 161 162 heif_suberror_No_iref_box = 113, 163 164 heif_suberror_No_pict_handler = 114, 165 166 // An item property referenced in the 'ipma' box is not existing in the 'ipco' container. 167 heif_suberror_Ipma_box_references_nonexisting_property = 115, 168 169 // No properties have been assigned to an item. 170 heif_suberror_No_properties_assigned_to_item = 116, 171 172 // Image has no (compressed) data 173 heif_suberror_No_item_data = 117, 174 175 // Invalid specification of image grid (tiled image) 176 heif_suberror_Invalid_grid_data = 118, 177 178 // Tile-images in a grid image are missing 179 heif_suberror_Missing_grid_images = 119, 180 181 heif_suberror_Invalid_clean_aperture = 120, 182 183 // Invalid specification of overlay image 184 heif_suberror_Invalid_overlay_data = 121, 185 186 // Overlay image completely outside of visible canvas area 187 heif_suberror_Overlay_image_outside_of_canvas = 122, 188 189 heif_suberror_Auxiliary_image_type_unspecified = 123, 190 191 heif_suberror_No_or_invalid_primary_item = 124, 192 193 heif_suberror_No_infe_box = 125, 194 195 heif_suberror_Unknown_color_profile_type = 126, 196 197 heif_suberror_Wrong_tile_image_chroma_format = 127, 198 199 heif_suberror_Invalid_fractional_number = 128, 200 201 heif_suberror_Invalid_image_size = 129, 202 203 heif_suberror_Invalid_pixi_box = 130, 204 205 heif_suberror_No_av1C_box = 131, 206 207 208 209 // --- Memory_allocation_error --- 210 211 // A security limit preventing unreasonable memory allocations was exceeded by the input file. 212 // Please check whether the file is valid. If it is, contact us so that we could increase the 213 // security limits further. 214 heif_suberror_Security_limit_exceeded = 1000, 215 216 217 // --- Usage_error --- 218 219 // An item ID was used that is not present in the file. 220 heif_suberror_Nonexisting_item_referenced = 2000, // also used for Invalid_input 221 222 // An API argument was given a NULL pointer, which is not allowed for that function. 223 heif_suberror_Null_pointer_argument = 2001, 224 225 // Image channel referenced that does not exist in the image 226 heif_suberror_Nonexisting_image_channel_referenced = 2002, 227 228 // The version of the passed plugin is not supported. 229 heif_suberror_Unsupported_plugin_version = 2003, 230 231 // The version of the passed writer is not supported. 232 heif_suberror_Unsupported_writer_version = 2004, 233 234 // The given (encoder) parameter name does not exist. 235 heif_suberror_Unsupported_parameter = 2005, 236 237 // The value for the given parameter is not in the valid range. 238 heif_suberror_Invalid_parameter_value = 2006, 239 240 241 // --- Unsupported_feature --- 242 243 // Image was coded with an unsupported compression method. 244 heif_suberror_Unsupported_codec = 3000, 245 246 // Image is specified in an unknown way, e.g. as tiled grid image (which is supported) 247 heif_suberror_Unsupported_image_type = 3001, 248 249 heif_suberror_Unsupported_data_version = 3002, 250 251 // The conversion of the source image to the requested chroma / colorspace is not supported. 252 heif_suberror_Unsupported_color_conversion = 3003, 253 254 heif_suberror_Unsupported_item_construction_method = 3004, 255 256 257 // --- Encoder_plugin_error --- 258 259 heif_suberror_Unsupported_bit_depth = 4000, 260 261 262 // --- Encoding_error --- 263 264 heif_suberror_Cannot_write_output_data = 5000, 265 }; 266 267 268 struct heif_error 269 { 270 // main error category 271 enum heif_error_code code; 272 273 // more detailed error code 274 enum heif_suberror_code subcode; 275 276 // textual error message (is always defined, you do not have to check for NULL) 277 const char* message; 278 }; 279 280 281 typedef uint32_t heif_item_id; 282 283 284 285 // ========================= file type check ====================== 286 287 enum heif_filetype_result 288 { 289 heif_filetype_no, 290 heif_filetype_yes_supported, // it is heif and can be read by libheif 291 heif_filetype_yes_unsupported, // it is heif, but cannot be read by libheif 292 heif_filetype_maybe // not sure whether it is an heif, try detection with more input data 293 }; 294 295 // input data should be at least 12 bytes 296 LIBHEIF_API 297 enum heif_filetype_result heif_check_filetype(const uint8_t* data, int len); 298 299 300 enum heif_brand 301 { 302 heif_unknown_brand, 303 heif_heic, // the usual HEIF images 304 heif_heix, // 10bit images, or anything that uses h265 with range extension 305 heif_hevc, heif_hevx, // brands for image sequences 306 heif_heim, // multiview 307 heif_heis, // scalable 308 heif_hevm, // multiview sequence 309 heif_hevs, // scalable sequence 310 heif_mif1, // image, any coding algorithm 311 heif_msf1, // sequence, any coding algorithm 312 heif_avif, 313 heif_avis 314 }; 315 316 // input data should be at least 12 bytes 317 LIBHEIF_API 318 enum heif_brand heif_main_brand(const uint8_t* data, int len); 319 320 321 // Returns one of these MIME types: 322 // - image/heic HEIF file using h265 compression 323 // - image/heif HEIF file using any other compression 324 // - image/heic-sequence HEIF image sequence using h265 compression 325 // - image/heif-sequence HEIF image sequence using any other compression 326 // - image/jpeg JPEG image 327 // - image/png PNG image 328 // If the format could not be detected, an empty string is returned. 329 // 330 // Provide at least 12 bytes of input. With less input, its format might not 331 // be detected. You may also provide more input to increase detection accuracy. 332 // 333 // Note that JPEG and PNG images cannot be decoded by libheif even though the 334 // formats are detected by this function. 335 LIBHEIF_API 336 const char* heif_get_file_mime_type(const uint8_t* data, int len); 337 338 339 340 // ========================= heif_context ========================= 341 // A heif_context represents a HEIF file that has been read. 342 // In the future, you will also be able to add pictures to a heif_context 343 // and write it into a file again. 344 345 346 // Allocate a new context for reading HEIF files. 347 // Has to be freed again with heif_context_free(). 348 LIBHEIF_API 349 struct heif_context* heif_context_alloc(void); 350 351 // Free a previously allocated HEIF context. You should not free a context twice. 352 LIBHEIF_API 353 void heif_context_free(struct heif_context*); 354 355 356 struct heif_reading_options; 357 358 enum heif_reader_grow_status 359 { 360 heif_reader_grow_status_size_reached, // requested size has been reached, we can read until this point 361 heif_reader_grow_status_timeout, // size has not been reached yet, but it may still grow further 362 heif_reader_grow_status_size_beyond_eof // size has not been reached and never will. The file has grown to its full size 363 }; 364 365 struct heif_reader 366 { 367 // API version supported by this reader 368 int reader_api_version; 369 370 // --- version 1 functions --- 371 int64_t (* get_position)(void* userdata); 372 373 // The functions read(), and seek() return 0 on success. 374 // Generally, libheif will make sure that we do not read past the file size. 375 int (* read)(void* data, 376 size_t size, 377 void* userdata); 378 379 int (* seek)(int64_t position, 380 void* userdata); 381 382 // When calling this function, libheif wants to make sure that it can read the file 383 // up to 'target_size'. This is useful when the file is currently downloaded and may 384 // grow with time. You may, for example, extract the image sizes even before the actual 385 // compressed image data has been completely downloaded. 386 // 387 // Even if your input files will not grow, you will have to implement at least 388 // detection whether the target_size is above the (fixed) file length 389 // (in this case, return 'size_beyond_eof'). 390 enum heif_reader_grow_status (* wait_for_file_size)(int64_t target_size, void* userdata); 391 }; 392 393 394 // Read a HEIF file from a named disk file. 395 // The heif_reading_options should currently be set to NULL. 396 LIBHEIF_API 397 struct heif_error heif_context_read_from_file(struct heif_context*, const char* filename, 398 const struct heif_reading_options*); 399 400 // Read a HEIF file stored completely in memory. 401 // The heif_reading_options should currently be set to NULL. 402 // DEPRECATED: use heif_context_read_from_memory_without_copy() instead. 403 LIBHEIF_API 404 struct heif_error heif_context_read_from_memory(struct heif_context*, 405 const void* mem, size_t size, 406 const struct heif_reading_options*); 407 408 // Same as heif_context_read_from_memory() except that the provided memory is not copied. 409 // That means, you will have to keep the memory area alive as long as you use the heif_context. 410 LIBHEIF_API 411 struct heif_error heif_context_read_from_memory_without_copy(struct heif_context*, 412 const void* mem, size_t size, 413 const struct heif_reading_options*); 414 415 LIBHEIF_API 416 struct heif_error heif_context_read_from_reader(struct heif_context*, 417 const struct heif_reader* reader, 418 void* userdata, 419 const struct heif_reading_options*); 420 421 // Number of top-level images in the HEIF file. This does not include the thumbnails or the 422 // tile images that are composed to an image grid. You can get access to the thumbnails via 423 // the main image handle. 424 LIBHEIF_API 425 int heif_context_get_number_of_top_level_images(struct heif_context* ctx); 426 427 LIBHEIF_API 428 int heif_context_is_top_level_image_ID(struct heif_context* ctx, heif_item_id id); 429 430 // Fills in image IDs into the user-supplied int-array 'ID_array', preallocated with 'count' entries. 431 // Function returns the total number of IDs filled into the array. 432 LIBHEIF_API 433 int heif_context_get_list_of_top_level_image_IDs(struct heif_context* ctx, 434 heif_item_id* ID_array, 435 int count); 436 437 LIBHEIF_API 438 struct heif_error heif_context_get_primary_image_ID(struct heif_context* ctx, heif_item_id* id); 439 440 // Get a handle to the primary image of the HEIF file. 441 // This is the image that should be displayed primarily when there are several images in the file. 442 LIBHEIF_API 443 struct heif_error heif_context_get_primary_image_handle(struct heif_context* ctx, 444 struct heif_image_handle**); 445 446 // Get the handle for a specific top-level image from an image ID. 447 LIBHEIF_API 448 struct heif_error heif_context_get_image_handle(struct heif_context* ctx, 449 heif_item_id id, 450 struct heif_image_handle**); 451 452 // Print information about the boxes of a HEIF file to file descriptor. 453 // This is for debugging and informational purposes only. You should not rely on 454 // the output having a specific format. At best, you should not use this at all. 455 LIBHEIF_API 456 void heif_context_debug_dump_boxes_to_file(struct heif_context* ctx, int fd); 457 458 459 LIBHEIF_API 460 void heif_context_set_maximum_image_size_limit(struct heif_context* ctx, int maximum_width); 461 462 463 // ========================= heif_image_handle ========================= 464 465 // An heif_image_handle is a handle to a logical image in the HEIF file. 466 // To get the actual pixel data, you have to decode the handle to an heif_image. 467 // An heif_image_handle also gives you access to the thumbnails and Exif data 468 // associated with an image. 469 470 // Once you obtained an heif_image_handle, you can already release the heif_context, 471 // since it is internally ref-counted. 472 473 // Release image handle. 474 LIBHEIF_API 475 void heif_image_handle_release(const struct heif_image_handle*); 476 477 // Check whether the given image_handle is the primary image of the file. 478 LIBHEIF_API 479 int heif_image_handle_is_primary_image(const struct heif_image_handle* handle); 480 481 // Get the resolution of an image. 482 LIBHEIF_API 483 int heif_image_handle_get_width(const struct heif_image_handle* handle); 484 485 LIBHEIF_API 486 int heif_image_handle_get_height(const struct heif_image_handle* handle); 487 488 LIBHEIF_API 489 int heif_image_handle_has_alpha_channel(const struct heif_image_handle*); 490 491 // Returns -1 on error, e.g. if this information is not present in the image. 492 LIBHEIF_API 493 int heif_image_handle_get_luma_bits_per_pixel(const struct heif_image_handle*); 494 495 // Returns -1 on error, e.g. if this information is not present in the image. 496 LIBHEIF_API 497 int heif_image_handle_get_chroma_bits_per_pixel(const struct heif_image_handle*); 498 499 // Get the image width from the 'ispe' box. This is the original image size without 500 // any transformations applied to it. Do not use this unless you know exactly what 501 // you are doing. 502 LIBHEIF_API 503 int heif_image_handle_get_ispe_width(const struct heif_image_handle* handle); 504 505 LIBHEIF_API 506 int heif_image_handle_get_ispe_height(const struct heif_image_handle* handle); 507 508 509 // ------------------------- depth images ------------------------- 510 511 LIBHEIF_API 512 int heif_image_handle_has_depth_image(const struct heif_image_handle*); 513 514 LIBHEIF_API 515 int heif_image_handle_get_number_of_depth_images(const struct heif_image_handle* handle); 516 517 LIBHEIF_API 518 int heif_image_handle_get_list_of_depth_image_IDs(const struct heif_image_handle* handle, 519 heif_item_id* ids, int count); 520 521 LIBHEIF_API 522 struct heif_error heif_image_handle_get_depth_image_handle(const struct heif_image_handle* handle, 523 heif_item_id depth_image_id, 524 struct heif_image_handle** out_depth_handle); 525 526 527 enum heif_depth_representation_type 528 { 529 heif_depth_representation_type_uniform_inverse_Z = 0, 530 heif_depth_representation_type_uniform_disparity = 1, 531 heif_depth_representation_type_uniform_Z = 2, 532 heif_depth_representation_type_nonuniform_disparity = 3 533 }; 534 535 struct heif_depth_representation_info 536 { 537 uint8_t version; 538 539 // version 1 fields 540 541 uint8_t has_z_near; 542 uint8_t has_z_far; 543 uint8_t has_d_min; 544 uint8_t has_d_max; 545 546 double z_near; 547 double z_far; 548 double d_min; 549 double d_max; 550 551 enum heif_depth_representation_type depth_representation_type; 552 uint32_t disparity_reference_view; 553 554 uint32_t depth_nonlinear_representation_model_size; 555 uint8_t* depth_nonlinear_representation_model; 556 557 // version 2 fields below 558 }; 559 560 561 LIBHEIF_API 562 void heif_depth_representation_info_free(const struct heif_depth_representation_info* info); 563 564 // Returns true when there is depth_representation_info available 565 LIBHEIF_API 566 int heif_image_handle_get_depth_image_representation_info(const struct heif_image_handle* handle, 567 heif_item_id depth_image_id, 568 const struct heif_depth_representation_info** out); 569 570 571 572 // ------------------------- thumbnails ------------------------- 573 574 // List the number of thumbnails assigned to this image handle. Usually 0 or 1. 575 LIBHEIF_API 576 int heif_image_handle_get_number_of_thumbnails(const struct heif_image_handle* handle); 577 578 LIBHEIF_API 579 int heif_image_handle_get_list_of_thumbnail_IDs(const struct heif_image_handle* handle, 580 heif_item_id* ids, int count); 581 582 // Get the image handle of a thumbnail image. 583 LIBHEIF_API 584 struct heif_error heif_image_handle_get_thumbnail(const struct heif_image_handle* main_image_handle, 585 heif_item_id thumbnail_id, 586 struct heif_image_handle** out_thumbnail_handle); 587 588 589 // ------------------------- auxiliary images ------------------------- 590 591 #define LIBHEIF_AUX_IMAGE_FILTER_OMIT_ALPHA (1UL<<1) 592 #define LIBHEIF_AUX_IMAGE_FILTER_OMIT_DEPTH (2UL<<1) 593 594 // List the number of auxiliary images assigned to this image handle. 595 LIBHEIF_API 596 int heif_image_handle_get_number_of_auxiliary_images(const struct heif_image_handle* handle, 597 int aux_filter); 598 599 LIBHEIF_API 600 int heif_image_handle_get_list_of_auxiliary_image_IDs(const struct heif_image_handle* handle, 601 int aux_filter, 602 heif_item_id* ids, int count); 603 604 // You are responsible to deallocate the returned buffer with free(). 605 LIBHEIF_API 606 struct heif_error heif_image_handle_get_auxiliary_type(const struct heif_image_handle* handle, 607 const char** out_type); 608 609 // Get the image handle of an auxiliary image. 610 LIBHEIF_API 611 struct heif_error heif_image_handle_get_auxiliary_image_handle(const struct heif_image_handle* main_image_handle, 612 heif_item_id auxiliary_id, 613 struct heif_image_handle** out_auxiliary_handle); 614 615 616 // ------------------------- metadata (Exif / XMP) ------------------------- 617 618 // How many metadata blocks are attached to an image. Usually, the only metadata is 619 // an "Exif" block. 620 LIBHEIF_API 621 int heif_image_handle_get_number_of_metadata_blocks(const struct heif_image_handle* handle, 622 const char* type_filter); 623 624 // 'type_filter' can be used to get only metadata of specific types, like "Exif". 625 // If 'type_filter' is NULL, it will return all types of metadata IDs. 626 LIBHEIF_API 627 int heif_image_handle_get_list_of_metadata_block_IDs(const struct heif_image_handle* handle, 628 const char* type_filter, 629 heif_item_id* ids, int count); 630 631 // Return a string indicating the type of the metadata, as specified in the HEIF file. 632 // Exif data will have the type string "Exif". 633 // This string will be valid until the next call to a libheif function. 634 // You do not have to free this string. 635 LIBHEIF_API 636 const char* heif_image_handle_get_metadata_type(const struct heif_image_handle* handle, 637 heif_item_id metadata_id); 638 639 LIBHEIF_API 640 const char* heif_image_handle_get_metadata_content_type(const struct heif_image_handle* handle, 641 heif_item_id metadata_id); 642 643 // Get the size of the raw metadata, as stored in the HEIF file. 644 LIBHEIF_API 645 size_t heif_image_handle_get_metadata_size(const struct heif_image_handle* handle, 646 heif_item_id metadata_id); 647 648 // 'out_data' must point to a memory area of the size reported by heif_image_handle_get_metadata_size(). 649 // The data is returned exactly as stored in the HEIF file. 650 // For Exif data, you probably have to skip the first four bytes of the data, since they 651 // indicate the offset to the start of the TIFF header of the Exif data. 652 LIBHEIF_API 653 struct heif_error heif_image_handle_get_metadata(const struct heif_image_handle* handle, 654 heif_item_id metadata_id, 655 void* out_data); 656 657 enum heif_color_profile_type 658 { 659 heif_color_profile_type_not_present = 0, 660 heif_color_profile_type_nclx = heif_fourcc('n', 'c', 'l', 'x'), 661 heif_color_profile_type_rICC = heif_fourcc('r', 'I', 'C', 'C'), 662 heif_color_profile_type_prof = heif_fourcc('p', 'r', 'o', 'f') 663 }; 664 665 666 // Returns 'heif_color_profile_type_not_present' if there is no color profile. 667 // If there is an ICC profile and an NCLX profile, the ICC profile is returned. 668 // TODO: we need a new API for this function as images can contain both NCLX and ICC at the same time. 669 // However, you can still use heif_image_handle_get_raw_color_profile() and 670 // heif_image_handle_get_nclx_color_profile() to access both profiles. 671 LIBHEIF_API 672 enum heif_color_profile_type heif_image_handle_get_color_profile_type(const struct heif_image_handle* handle); 673 674 LIBHEIF_API 675 size_t heif_image_handle_get_raw_color_profile_size(const struct heif_image_handle* handle); 676 677 // Returns 'heif_error_Color_profile_does_not_exist' when there is no ICC profile. 678 LIBHEIF_API 679 struct heif_error heif_image_handle_get_raw_color_profile(const struct heif_image_handle* handle, 680 void* out_data); 681 682 683 enum heif_color_primaries 684 { 685 heif_color_primaries_ITU_R_BT_709_5 = 1, // g=0.3;0.6, b=0.15;0.06, r=0.64;0.33, w=0.3127,0.3290 686 heif_color_primaries_unspecified = 2, 687 heif_color_primaries_ITU_R_BT_470_6_System_M = 4, 688 heif_color_primaries_ITU_R_BT_470_6_System_B_G = 5, 689 heif_color_primaries_ITU_R_BT_601_6 = 6, 690 heif_color_primaries_SMPTE_240M = 7, 691 heif_color_primaries_generic_film = 8, 692 heif_color_primaries_ITU_R_BT_2020_2_and_2100_0 = 9, 693 heif_color_primaries_SMPTE_ST_428_1 = 10, 694 heif_color_primaries_SMPTE_RP_431_2 = 11, 695 heif_color_primaries_SMPTE_EG_432_1 = 12, 696 heif_color_primaries_EBU_Tech_3213_E = 22 697 }; 698 699 enum heif_transfer_characteristics 700 { 701 heif_transfer_characteristic_ITU_R_BT_709_5 = 1, 702 heif_transfer_characteristic_unspecified = 2, 703 heif_transfer_characteristic_ITU_R_BT_470_6_System_M = 4, 704 heif_transfer_characteristic_ITU_R_BT_470_6_System_B_G = 5, 705 heif_transfer_characteristic_ITU_R_BT_601_6 = 6, 706 heif_transfer_characteristic_SMPTE_240M = 7, 707 heif_transfer_characteristic_linear = 8, 708 heif_transfer_characteristic_logarithmic_100 = 9, 709 heif_transfer_characteristic_logarithmic_100_sqrt10 = 10, 710 heif_transfer_characteristic_IEC_61966_2_4 = 11, 711 heif_transfer_characteristic_ITU_R_BT_1361 = 12, 712 heif_transfer_characteristic_IEC_61966_2_1 = 13, 713 heif_transfer_characteristic_ITU_R_BT_2020_2_10bit = 14, 714 heif_transfer_characteristic_ITU_R_BT_2020_2_12bit = 15, 715 heif_transfer_characteristic_ITU_R_BT_2100_0_PQ = 16, 716 heif_transfer_characteristic_SMPTE_ST_428_1 = 17, 717 heif_transfer_characteristic_ITU_R_BT_2100_0_HLG = 18 718 }; 719 720 enum heif_matrix_coefficients 721 { 722 heif_matrix_coefficients_RGB_GBR = 0, 723 heif_matrix_coefficients_ITU_R_BT_709_5 = 1, // TODO: or 709-6 according to h.273 724 heif_matrix_coefficients_unspecified = 2, 725 heif_matrix_coefficients_US_FCC_T47 = 4, 726 heif_matrix_coefficients_ITU_R_BT_470_6_System_B_G = 5, 727 heif_matrix_coefficients_ITU_R_BT_601_6 = 6, // TODO: or 601-7 according to h.273 728 heif_matrix_coefficients_SMPTE_240M = 7, 729 heif_matrix_coefficients_YCgCo = 8, 730 heif_matrix_coefficients_ITU_R_BT_2020_2_non_constant_luminance = 9, 731 heif_matrix_coefficients_ITU_R_BT_2020_2_constant_luminance = 10, 732 heif_matrix_coefficients_SMPTE_ST_2085 = 11, 733 heif_matrix_coefficients_chromaticity_derived_non_constant_luminance = 12, 734 heif_matrix_coefficients_chromaticity_derived_constant_luminance = 13, 735 heif_matrix_coefficients_ICtCp = 14 736 }; 737 738 struct heif_color_profile_nclx 739 { 740 // === version 1 fields 741 742 uint8_t version; 743 744 enum heif_color_primaries color_primaries; 745 enum heif_transfer_characteristics transfer_characteristics; 746 enum heif_matrix_coefficients matrix_coefficients; 747 uint8_t full_range_flag; 748 749 // --- decoded values (not used when saving nclx) 750 751 float color_primary_red_x, color_primary_red_y; 752 float color_primary_green_x, color_primary_green_y; 753 float color_primary_blue_x, color_primary_blue_y; 754 float color_primary_white_x, color_primary_white_y; 755 }; 756 757 // Returns 'heif_error_Color_profile_does_not_exist' when there is no NCLX profile. 758 // TODO: This function does currently not return an NCLX profile if it is stored in the image bitstream. 759 // Only NCLX profiles stored as colr boxes are returned. This may change in the future. 760 LIBHEIF_API 761 struct heif_error heif_image_handle_get_nclx_color_profile(const struct heif_image_handle* handle, 762 struct heif_color_profile_nclx** out_data); 763 764 // Returned color profile has 'version' field set to the maximum allowed. 765 // Do not fill values for higher versions as these might be outside the allocated structure size. 766 // May return NULL. 767 LIBHEIF_API 768 struct heif_color_profile_nclx* heif_nclx_color_profile_alloc(); 769 770 LIBHEIF_API 771 void heif_nclx_color_profile_free(struct heif_color_profile_nclx* nclx_profile); 772 773 774 LIBHEIF_API 775 enum heif_color_profile_type heif_image_get_color_profile_type(const struct heif_image* image); 776 777 LIBHEIF_API 778 size_t heif_image_get_raw_color_profile_size(const struct heif_image* image); 779 780 LIBHEIF_API 781 struct heif_error heif_image_get_raw_color_profile(const struct heif_image* image, 782 void* out_data); 783 784 LIBHEIF_API 785 struct heif_error heif_image_get_nclx_color_profile(const struct heif_image* image, 786 struct heif_color_profile_nclx** out_data); 787 788 789 790 // ========================= heif_image ========================= 791 792 // An heif_image contains a decoded pixel image in various colorspaces, chroma formats, 793 // and bit depths. 794 795 // Note: when converting images to an interleaved chroma format, the resulting 796 // image contains only a single channel of type channel_interleaved with, e.g., 3 bytes per pixel, 797 // containing the interleaved R,G,B values. 798 799 // Planar RGB images are specified as heif_colorspace_RGB / heif_chroma_444. 800 801 enum heif_compression_format 802 { 803 heif_compression_undefined = 0, 804 heif_compression_HEVC = 1, 805 heif_compression_AVC = 2, 806 heif_compression_JPEG = 3, 807 heif_compression_AV1 = 4 808 }; 809 810 enum heif_chroma 811 { 812 heif_chroma_undefined = 99, 813 heif_chroma_monochrome = 0, 814 heif_chroma_420 = 1, 815 heif_chroma_422 = 2, 816 heif_chroma_444 = 3, 817 heif_chroma_interleaved_RGB = 10, 818 heif_chroma_interleaved_RGBA = 11, 819 heif_chroma_interleaved_RRGGBB_BE = 12, 820 heif_chroma_interleaved_RRGGBBAA_BE = 13, 821 heif_chroma_interleaved_RRGGBB_LE = 14, 822 heif_chroma_interleaved_RRGGBBAA_LE = 15 823 }; 824 825 // DEPRECATED ENUM NAMES 826 #define heif_chroma_interleaved_24bit heif_chroma_interleaved_RGB 827 #define heif_chroma_interleaved_32bit heif_chroma_interleaved_RGBA 828 829 830 enum heif_colorspace 831 { 832 heif_colorspace_undefined = 99, 833 heif_colorspace_YCbCr = 0, 834 heif_colorspace_RGB = 1, 835 heif_colorspace_monochrome = 2 836 }; 837 838 enum heif_channel 839 { 840 heif_channel_Y = 0, 841 heif_channel_Cb = 1, 842 heif_channel_Cr = 2, 843 heif_channel_R = 3, 844 heif_channel_G = 4, 845 heif_channel_B = 5, 846 heif_channel_Alpha = 6, 847 heif_channel_interleaved = 10 848 }; 849 850 851 enum heif_progress_step 852 { 853 heif_progress_step_total = 0, 854 heif_progress_step_load_tile = 1 855 }; 856 857 858 struct heif_decoding_options 859 { 860 uint8_t version; 861 862 // version 1 options 863 864 // Ignore geometric transformations like cropping, rotation, mirroring. 865 // Default: false (do not ignore). 866 uint8_t ignore_transformations; 867 868 void (* start_progress)(enum heif_progress_step step, int max_progress, void* progress_user_data); 869 870 void (* on_progress)(enum heif_progress_step step, int progress, void* progress_user_data); 871 872 void (* end_progress)(enum heif_progress_step step, void* progress_user_data); 873 874 void* progress_user_data; 875 876 // version 2 options 877 878 uint8_t convert_hdr_to_8bit; 879 }; 880 881 882 // Allocate decoding options and fill with default values. 883 // Note: you should always get the decoding options through this function since the 884 // option structure may grow in size in future versions. 885 LIBHEIF_API 886 struct heif_decoding_options* heif_decoding_options_alloc(); 887 888 LIBHEIF_API 889 void heif_decoding_options_free(struct heif_decoding_options*); 890 891 // Decode an heif_image_handle into the actual pixel image and also carry out 892 // all geometric transformations specified in the HEIF file (rotation, cropping, mirroring). 893 // 894 // If colorspace or chroma is set to heif_colorspace_undefined or heif_chroma_undefined, 895 // respectively, the original colorspace is taken. 896 // Decoding options may be NULL. If you want to supply options, always use 897 // heif_decoding_options_alloc() to get the structure. 898 LIBHEIF_API 899 struct heif_error heif_decode_image(const struct heif_image_handle* in_handle, 900 struct heif_image** out_img, 901 enum heif_colorspace colorspace, 902 enum heif_chroma chroma, 903 const struct heif_decoding_options* options); 904 905 // Get the colorspace format of the image. 906 LIBHEIF_API 907 enum heif_colorspace heif_image_get_colorspace(const struct heif_image*); 908 909 // Get the chroma format of the image. 910 LIBHEIF_API 911 enum heif_chroma heif_image_get_chroma_format(const struct heif_image*); 912 913 // Get width of the given image channel in pixels. Returns -1 if a non-existing 914 // channel was given. 915 LIBHEIF_API 916 int heif_image_get_width(const struct heif_image*, enum heif_channel channel); 917 918 // Get height of the given image channel in pixels. Returns -1 if a non-existing 919 // channel was given. 920 LIBHEIF_API 921 int heif_image_get_height(const struct heif_image*, enum heif_channel channel); 922 923 // Get the width of the main channel (Y in YCbCr, or any in RGB). 924 LIBHEIF_API 925 int heif_image_get_primary_width(const struct heif_image*); 926 927 LIBHEIF_API 928 int heif_image_get_primary_height(const struct heif_image*); 929 930 LIBHEIF_API 931 struct heif_error heif_image_crop(struct heif_image* img, 932 int left, int right, int top, int bottom); 933 934 // Get the number of bits per pixel in the given image channel. Returns -1 if 935 // a non-existing channel was given. 936 // Note that the number of bits per pixel may be different for each color channel. 937 // This function returns the number of bits used for storage of each pixel. 938 // Especially for HDR images, this is probably not what you want. Have a look at 939 // heif_image_get_bits_per_pixel_range() instead. 940 LIBHEIF_API 941 int heif_image_get_bits_per_pixel(const struct heif_image*, enum heif_channel channel); 942 943 944 // Get the number of bits per pixel in the given image channel. This function returns 945 // the number of bits used for representing the pixel value, which might be smaller 946 // than the number of bits used in memory. 947 // For example, in 12bit HDR images, this function returns '12', while still 16 bits 948 // are reserved for storage. For interleaved RGBA with 12 bit, this function also returns 949 // '12', not '48' or '64' (heif_image_get_bits_per_pixel returns 64 in this case). 950 LIBHEIF_API 951 int heif_image_get_bits_per_pixel_range(const struct heif_image*, enum heif_channel channel); 952 953 LIBHEIF_API 954 int heif_image_has_channel(const struct heif_image*, enum heif_channel channel); 955 956 // Get a pointer to the actual pixel data. 957 // The 'out_stride' is returned as "bytes per line". 958 // When out_stride is NULL, no value will be written. 959 // Returns NULL if a non-existing channel was given. 960 LIBHEIF_API 961 const uint8_t* heif_image_get_plane_readonly(const struct heif_image*, 962 enum heif_channel channel, 963 int* out_stride); 964 965 LIBHEIF_API 966 uint8_t* heif_image_get_plane(struct heif_image*, 967 enum heif_channel channel, 968 int* out_stride); 969 970 971 struct heif_scaling_options; 972 973 // Currently, heif_scaling_options is not defined yet. Pass a NULL pointer. 974 LIBHEIF_API 975 struct heif_error heif_image_scale_image(const struct heif_image* input, 976 struct heif_image** output, 977 int width, int height, 978 const struct heif_scaling_options* options); 979 980 // The color profile is not attached to the image handle because we might need it 981 // for color space transform and encoding. 982 LIBHEIF_API 983 struct heif_error heif_image_set_raw_color_profile(struct heif_image* image, 984 const char* profile_type_fourcc_string, 985 const void* profile_data, 986 const size_t profile_size); 987 988 LIBHEIF_API 989 struct heif_error heif_image_set_nclx_color_profile(struct heif_image* image, 990 const struct heif_color_profile_nclx* color_profile); 991 992 993 // TODO: this function does not make any sense yet, since we currently cannot modify existing HEIF files. 994 //LIBHEIF_API 995 //void heif_image_remove_color_profile(struct heif_image* image); 996 997 // Release heif_image. 998 LIBHEIF_API 999 void heif_image_release(const struct heif_image*); 1000 1001 1002 // ==================================================================================================== 1003 // Encoding API 1004 1005 LIBHEIF_API 1006 struct heif_error heif_context_write_to_file(struct heif_context*, 1007 const char* filename); 1008 1009 struct heif_writer 1010 { 1011 // API version supported by this writer 1012 int writer_api_version; 1013 1014 // --- version 1 functions --- 1015 struct heif_error (* write)(struct heif_context* ctx, // TODO: why do we need this parameter? 1016 const void* data, 1017 size_t size, 1018 void* userdata); 1019 }; 1020 1021 LIBHEIF_API 1022 struct heif_error heif_context_write(struct heif_context*, 1023 struct heif_writer* writer, 1024 void* userdata); 1025 1026 1027 // ----- encoder ----- 1028 1029 // The encoder used for actually encoding an image. 1030 struct heif_encoder; 1031 1032 // A description of the encoder's capabilities and name. 1033 struct heif_encoder_descriptor; 1034 1035 // A configuration parameter of the encoder. Each encoder implementation may have a different 1036 // set of parameters. For the most common settings (e.q. quality), special functions to set 1037 // the parameters are provided. 1038 struct heif_encoder_parameter; 1039 1040 1041 // Get a list of available encoders. You can filter the encoders by compression format and name. 1042 // Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards. 1043 // The returned list of encoders is sorted by their priority (which is a plugin property). 1044 // Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder(). 1045 LIBHEIF_API 1046 int heif_context_get_encoder_descriptors(struct heif_context*, // TODO: why do we need this parameter? 1047 enum heif_compression_format format_filter, 1048 const char* name_filter, 1049 const struct heif_encoder_descriptor** out_encoders, 1050 int count); 1051 1052 // Return a long, descriptive name of the encoder (including version information). 1053 LIBHEIF_API 1054 const char* heif_encoder_descriptor_get_name(const struct heif_encoder_descriptor*); 1055 1056 // Return a short, symbolic name for identifying the encoder. 1057 // This name should stay constant over different encoder versions. 1058 LIBHEIF_API 1059 const char* heif_encoder_descriptor_get_id_name(const struct heif_encoder_descriptor*); 1060 1061 LIBHEIF_API 1062 enum heif_compression_format 1063 heif_encoder_descriptor_get_compression_format(const struct heif_encoder_descriptor*); 1064 1065 LIBHEIF_API 1066 int heif_encoder_descriptor_supports_lossy_compression(const struct heif_encoder_descriptor*); 1067 1068 LIBHEIF_API 1069 int heif_encoder_descriptor_supports_lossless_compression(const struct heif_encoder_descriptor*); 1070 1071 1072 // Get an encoder instance that can be used to actually encode images from a descriptor. 1073 LIBHEIF_API 1074 struct heif_error heif_context_get_encoder(struct heif_context* context, 1075 const struct heif_encoder_descriptor*, 1076 struct heif_encoder** out_encoder); 1077 1078 // Quick check whether there is a decoder available for the given format. 1079 // Note that the decoder still may not be able to decode all variants of that format. 1080 // You will have to query that further (todo) or just try to decode and check the returned error. 1081 LIBHEIF_API 1082 int heif_have_decoder_for_format(enum heif_compression_format format); 1083 1084 // Quick check whether there is an enoder available for the given format. 1085 // Note that the encoder may be limited to a certain subset of features (e.g. only 8 bit, only lossy). 1086 // You will have to query the specific capabilities further. 1087 LIBHEIF_API 1088 int heif_have_encoder_for_format(enum heif_compression_format format); 1089 1090 // Get an encoder for the given compression format. If there are several encoder plugins 1091 // for this format, the encoder with the highest plugin priority will be returned. 1092 LIBHEIF_API 1093 struct heif_error heif_context_get_encoder_for_format(struct heif_context* context, 1094 enum heif_compression_format format, 1095 struct heif_encoder**); 1096 1097 // You have to release the encoder after use. 1098 LIBHEIF_API 1099 void heif_encoder_release(struct heif_encoder*); 1100 1101 // Get the encoder name from the encoder itself. 1102 LIBHEIF_API 1103 const char* heif_encoder_get_name(const struct heif_encoder*); 1104 1105 1106 // --- Encoder Parameters --- 1107 1108 // Libheif supports settings parameters through specialized functions and through 1109 // generic functions by parameter name. Sometimes, the same parameter can be set 1110 // in both ways. 1111 // We consider it best practice to use the generic parameter functions only in 1112 // dynamically generated user interfaces, as no guarantees are made that some specific 1113 // parameter names are supported by all plugins. 1114 1115 1116 // Set a 'quality' factor (0-100). How this is mapped to actual encoding parameters is 1117 // encoder dependent. 1118 LIBHEIF_API 1119 struct heif_error heif_encoder_set_lossy_quality(struct heif_encoder*, int quality); 1120 1121 LIBHEIF_API 1122 struct heif_error heif_encoder_set_lossless(struct heif_encoder*, int enable); 1123 1124 // level should be between 0 (= none) to 4 (= full) 1125 LIBHEIF_API 1126 struct heif_error heif_encoder_set_logging_level(struct heif_encoder*, int level); 1127 1128 // Get a generic list of encoder parameters. 1129 // Each encoder may define its own, additional set of parameters. 1130 // You do not have to free the returned list. 1131 LIBHEIF_API 1132 const struct heif_encoder_parameter* const* heif_encoder_list_parameters(struct heif_encoder*); 1133 1134 // Return the parameter name. 1135 LIBHEIF_API 1136 const char* heif_encoder_parameter_get_name(const struct heif_encoder_parameter*); 1137 1138 1139 enum heif_encoder_parameter_type 1140 { 1141 heif_encoder_parameter_type_integer = 1, 1142 heif_encoder_parameter_type_boolean = 2, 1143 heif_encoder_parameter_type_string = 3 1144 }; 1145 1146 // Return the parameter type. 1147 LIBHEIF_API 1148 enum heif_encoder_parameter_type heif_encoder_parameter_get_type(const struct heif_encoder_parameter*); 1149 1150 // DEPRECATED. Use heif_encoder_parameter_get_valid_integer_values() instead. 1151 LIBHEIF_API 1152 struct heif_error heif_encoder_parameter_get_valid_integer_range(const struct heif_encoder_parameter*, 1153 int* have_minimum_maximum, 1154 int* minimum, int* maximum); 1155 1156 // If integer is limited by a range, have_minimum and/or have_maximum will be != 0 and *minimum, *maximum is set. 1157 // If integer is limited by a fixed set of values, *num_valid_values will be >0 and *out_integer_array is set. 1158 LIBHEIF_API 1159 struct heif_error heif_encoder_parameter_get_valid_integer_values(const struct heif_encoder_parameter*, 1160 int* have_minimum, int* have_maximum, 1161 int* minimum, int* maximum, 1162 int* num_valid_values, 1163 const int** out_integer_array); 1164 1165 LIBHEIF_API 1166 struct heif_error heif_encoder_parameter_get_valid_string_values(const struct heif_encoder_parameter*, 1167 const char* const** out_stringarray); 1168 1169 1170 LIBHEIF_API 1171 struct heif_error heif_encoder_set_parameter_integer(struct heif_encoder*, 1172 const char* parameter_name, 1173 int value); 1174 1175 LIBHEIF_API 1176 struct heif_error heif_encoder_get_parameter_integer(struct heif_encoder*, 1177 const char* parameter_name, 1178 int* value); 1179 1180 // TODO: name should be changed to heif_encoder_get_valid_integer_parameter_range 1181 LIBHEIF_API // DEPRECATED. 1182 struct heif_error heif_encoder_parameter_integer_valid_range(struct heif_encoder*, 1183 const char* parameter_name, 1184 int* have_minimum_maximum, 1185 int* minimum, int* maximum); 1186 1187 LIBHEIF_API 1188 struct heif_error heif_encoder_set_parameter_boolean(struct heif_encoder*, 1189 const char* parameter_name, 1190 int value); 1191 1192 LIBHEIF_API 1193 struct heif_error heif_encoder_get_parameter_boolean(struct heif_encoder*, 1194 const char* parameter_name, 1195 int* value); 1196 1197 LIBHEIF_API 1198 struct heif_error heif_encoder_set_parameter_string(struct heif_encoder*, 1199 const char* parameter_name, 1200 const char* value); 1201 1202 LIBHEIF_API 1203 struct heif_error heif_encoder_get_parameter_string(struct heif_encoder*, 1204 const char* parameter_name, 1205 char* value, int value_size); 1206 1207 // returns a NULL-terminated list of valid strings or NULL if all values are allowed 1208 LIBHEIF_API 1209 struct heif_error heif_encoder_parameter_string_valid_values(struct heif_encoder*, 1210 const char* parameter_name, 1211 const char* const** out_stringarray); 1212 1213 LIBHEIF_API 1214 struct heif_error heif_encoder_parameter_integer_valid_values(struct heif_encoder*, 1215 const char* parameter_name, 1216 int* have_minimum, int* have_maximum, 1217 int* minimum, int* maximum, 1218 int* num_valid_values, 1219 const int** out_integer_array); 1220 1221 // Set a parameter of any type to the string value. 1222 // Integer values are parsed from the string. 1223 // Boolean values can be "true"/"false"/"1"/"0" 1224 // 1225 // x265 encoder specific note: 1226 // When using the x265 encoder, you may pass any of its parameters by 1227 // prefixing the parameter name with 'x265:'. Hence, to set the 'ctu' parameter, 1228 // you will have to set 'x265:ctu' in libheif. 1229 // Note that there is no checking for valid parameters when using the prefix. 1230 LIBHEIF_API 1231 struct heif_error heif_encoder_set_parameter(struct heif_encoder*, 1232 const char* parameter_name, 1233 const char* value); 1234 1235 // Get the current value of a parameter of any type as a human readable string. 1236 // The returned string is compatible with heif_encoder_set_parameter(). 1237 LIBHEIF_API 1238 struct heif_error heif_encoder_get_parameter(struct heif_encoder*, 1239 const char* parameter_name, 1240 char* value_ptr, int value_size); 1241 1242 // Query whether a specific parameter has a default value. 1243 LIBHEIF_API 1244 int heif_encoder_has_default(struct heif_encoder*, 1245 const char* parameter_name); 1246 1247 1248 struct heif_encoding_options 1249 { 1250 uint8_t version; 1251 1252 // version 1 options 1253 1254 uint8_t save_alpha_channel; // default: true 1255 1256 // version 2 options 1257 1258 // Crops heif images with a grid wrapper instead of a 'clap' transform. 1259 // Results in slightly larger file size. 1260 // Default: on. 1261 uint8_t macOS_compatibility_workaround; 1262 1263 // version 3 options 1264 1265 uint8_t save_two_colr_boxes_when_ICC_and_nclx_available; // default: false 1266 }; 1267 1268 LIBHEIF_API 1269 struct heif_encoding_options* heif_encoding_options_alloc(); 1270 1271 LIBHEIF_API 1272 void heif_encoding_options_free(struct heif_encoding_options*); 1273 1274 1275 // Compress the input image. 1276 // Returns a handle to the coded image in 'out_image_handle' unless out_image_handle = NULL. 1277 // 'options' should be NULL for now. 1278 // The first image added to the context is also automatically set the primary image, but 1279 // you can change the primary image later with heif_context_set_primary_image(). 1280 LIBHEIF_API 1281 struct heif_error heif_context_encode_image(struct heif_context*, 1282 const struct heif_image* image, 1283 struct heif_encoder* encoder, 1284 const struct heif_encoding_options* options, 1285 struct heif_image_handle** out_image_handle); 1286 1287 LIBHEIF_API 1288 struct heif_error heif_context_set_primary_image(struct heif_context*, 1289 struct heif_image_handle* image_handle); 1290 1291 // Encode the 'image' as a scaled down thumbnail image. 1292 // The image is scaled down to fit into a square area of width 'bbox_size'. 1293 // If the input image is already so small that it fits into this bounding box, no thumbnail 1294 // image is encoded and NULL is returned in 'out_thumb_image_handle'. 1295 // No error is returned in this case. 1296 // The encoded thumbnail is automatically assigned to the 'master_image_handle'. Hence, you 1297 // do not have to call heif_context_assign_thumbnail(). 1298 LIBHEIF_API 1299 struct heif_error heif_context_encode_thumbnail(struct heif_context*, 1300 const struct heif_image* image, 1301 const struct heif_image_handle* master_image_handle, 1302 struct heif_encoder* encoder, 1303 const struct heif_encoding_options* options, 1304 int bbox_size, 1305 struct heif_image_handle** out_thumb_image_handle); 1306 1307 // Assign 'thumbnail_image' as the thumbnail image of 'master_image'. 1308 LIBHEIF_API 1309 struct heif_error heif_context_assign_thumbnail(struct heif_context*, 1310 const struct heif_image_handle* master_image, 1311 const struct heif_image_handle* thumbnail_image); 1312 1313 // Add EXIF metadata to an image. 1314 LIBHEIF_API 1315 struct heif_error heif_context_add_exif_metadata(struct heif_context*, 1316 const struct heif_image_handle* image_handle, 1317 const void* data, int size); 1318 1319 // Add XMP metadata to an image. 1320 LIBHEIF_API 1321 struct heif_error heif_context_add_XMP_metadata(struct heif_context*, 1322 const struct heif_image_handle* image_handle, 1323 const void* data, int size); 1324 1325 // Add generic, proprietary metadata to an image. You have to specify an 'item_type' that will 1326 // identify your metadata. 'content_type' can be an additional type, or it can be NULL. 1327 // For example, this function can be used to add IPTC metadata (IIM stream, not XMP) to an image. 1328 // Even not standard, we propose to store IPTC data with item type="iptc", content_type=NULL. 1329 LIBHEIF_API 1330 struct heif_error heif_context_add_generic_metadata(struct heif_context* ctx, 1331 const struct heif_image_handle* image_handle, 1332 const void* data, int size, 1333 const char* item_type, const char* content_type); 1334 1335 // --- heif_image allocation 1336 1337 // Create a new image of the specified resolution and colorspace. 1338 // Note: no memory for the actual image data is reserved yet. You have to use 1339 // heif_image_add_plane() to add the image planes required by your colorspace/chroma. 1340 LIBHEIF_API 1341 struct heif_error heif_image_create(int width, int height, 1342 enum heif_colorspace colorspace, 1343 enum heif_chroma chroma, 1344 struct heif_image** out_image); 1345 1346 // The indicated bit_depth corresponds to the bit depth per channel. 1347 // I.e. for interleaved formats like RRGGBB, the bit_depth would be, e.g., 10 bit instead 1348 // of 30 bits or 3*16=48 bits. 1349 // For backward compatibility, one can also specify 24bits for RGB and 32bits for RGBA, 1350 // instead of the preferred 8 bits. 1351 LIBHEIF_API 1352 struct heif_error heif_image_add_plane(struct heif_image* image, 1353 enum heif_channel channel, 1354 int width, int height, int bit_depth); 1355 1356 1357 1358 1359 // --- register plugins 1360 1361 struct heif_decoder_plugin; 1362 struct heif_encoder_plugin; 1363 1364 // DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead. 1365 LIBHEIF_API 1366 struct heif_error heif_register_decoder(struct heif_context* heif, const struct heif_decoder_plugin*); 1367 1368 LIBHEIF_API 1369 struct heif_error heif_register_decoder_plugin(const struct heif_decoder_plugin*); 1370 1371 LIBHEIF_API 1372 struct heif_error heif_register_encoder_plugin(const struct heif_encoder_plugin*); 1373 1374 1375 1376 // DEPRECATED, typo in function name 1377 LIBHEIF_API 1378 int heif_encoder_descriptor_supportes_lossy_compression(const struct heif_encoder_descriptor*); 1379 1380 // DEPRECATED, typo in function name 1381 LIBHEIF_API 1382 int heif_encoder_descriptor_supportes_lossless_compression(const struct heif_encoder_descriptor*); 1383 1384 #ifdef __cplusplus 1385 } 1386 #endif 1387 1388 #endif 1389