Crate libheif_sys

Source

Expand description

§libheif-sys

libheif-sys is a binding to libheif.

A high-level wrapper libheif-rs is also available.

CHANGELOG

§System dependencies

libheif-dev >= 1.17.0.

§Minimal supported API version

This crate supports libheif versions 1.17, 1.18, 1.19 and 1.20.

You MUST specify a minimal version of libheif that is required for you. To do this, enable the corresponding feature: v1_17, v1_18, v1_19 or v1_20.

Example:

[dependencies]
libheif-sys = { version = "4.0", features = ["v1_18"] }

There is also the latest feature. It always corresponds to the maximal supported by the crate version of libheif.

§Linux

The crate uses pkg-confing to find installed libheif (with help of system-deps crate).

You can also enable embedded-libheif feature to compile libheif v1.20.2 from embedded sources and then link it statically.

Note: Static linked version of libheif doesn’t have statically linked it dependencies, such as libde256, libaom and other.

§Windows

The crate uses vcpkg crate to find libheif installed with help of vcpkg.

You can use cargo-vcpkg to install libheif with help of cargo command:

cargo vcpkg -v build

cargo-vcpkg can fetch and build a vcpkg installation of required packages from scratch. It merges package requirements specified in the Cargo.toml of all crates in the dependency tree.

§Example of reading and decoding HEIF-image

use std::ffi;
use std::ptr;

use libheif_sys as lh;

#[test]
fn read_and_decode_heif_file() {
    unsafe {
        lh::heif_init(ptr::null_mut());

        let ctx = lh::heif_context_alloc();
        assert!(!ctx.is_null());

        let c_name = ffi::CString::new("data/test.heif").unwrap();
        let err = lh::heif_context_read_from_file(
            ctx,
            c_name.as_ptr(),
            ptr::null()
        );
        assert_eq!(err.code, lh::heif_error_code_heif_error_Ok);

        let mut handle = ptr::null_mut();
        let err = lh::heif_context_get_primary_image_handle(
            ctx,
            &mut handle
        );
        assert_eq!(err.code, lh::heif_error_code_heif_error_Ok);
        assert!(!handle.is_null());

        let width = lh::heif_image_handle_get_width(handle);
        assert_eq!(width, 4032);
        let height = lh::heif_image_handle_get_height(handle);
        assert_eq!(height, 3024);

        let mut image = ptr::null_mut();
        let options = lh::heif_decoding_options_alloc();
        let err = lh::heif_decode_image(
            handle,
            &mut image,
            lh::heif_colorspace_heif_colorspace_RGB,
            lh::heif_chroma_heif_chroma_interleaved_RGB,
            options,
        );
        lh::heif_decoding_options_free(options);
        assert_eq!(err.code, lh::heif_error_code_heif_error_Ok);
        assert!(!image.is_null());

        let colorspace = lh::heif_image_get_colorspace(image);
        assert_eq!(
            colorspace,
            lh::heif_colorspace_heif_colorspace_RGB
        );
        let chroma_format = lh::heif_image_get_chroma_format(image);
        assert_eq!(
            chroma_format,
            lh::heif_chroma_heif_chroma_interleaved_RGB
        );
        let width = lh::heif_image_get_width(
            image,
            lh::heif_channel_heif_channel_interleaved
        );
        assert_eq!(width, 4032);
        let height = lh::heif_image_get_height(
            image,
            lh::heif_channel_heif_channel_interleaved
        );
        assert_eq!(height, 3024);

        lh::heif_context_free(ctx);

        lh::heif_deinit();
    };
}

Structs§

heif_ambient_viewing_environment
heif_camera_extrinsic_matrix
heif_camera_intrinsic_matrix: ———————–– intrinsic and extrinsic matrices ———————––
heif_color_conversion_options
heif_color_conversion_options_ext
heif_color_profile_nclx
heif_content_light_level: Note: a value of 0 for any of these values indicates that the value is undefined. The unit of these values is Candelas per square meter.
heif_context
heif_decoded_mastering_display_colour_volume: The units for max_display_mastering_luminance and min_display_mastering_luminance is Candelas per square meter.
heif_decoder_descriptor
heif_decoder_plugin
heif_decoding_options
heif_depth_representation_info
heif_encoder
heif_encoder_descriptor
heif_encoder_parameter
heif_encoder_plugin
heif_encoding_options
heif_entity_group
heif_error
heif_image
heif_image_handle
heif_image_tiling
heif_init_params: ========================= library initialization ======================
heif_mastering_display_colour_volume: 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).
heif_plugin_info
heif_property_user_description: The strings are managed by libheif. They will be deleted in heif_property_user_description_release().
heif_raw_sequence_sample
heif_reader
heif_reader_range_request_result
heif_reading_options
heif_region
heif_region_item
heif_sample_aux_info_type: Contains the type of sample auxiliary data assigned to the track samples.
heif_scaling_options
heif_security_limits: If you set a limit to 0, the limit is disabled.
heif_sequence_encoding_options: This structure is for future use. It is not defined yet.
heif_tai_clock_info
heif_tai_timestamp_packet
heif_track
heif_track_options
heif_writer

Constants§

heif_alpha_composition_mode_heif_alpha_composition_mode_checkerboard
heif_alpha_composition_mode_heif_alpha_composition_mode_none
heif_alpha_composition_mode_heif_alpha_composition_mode_solid_color
heif_brand_heif_avif: HEIF image with AV1
heif_brand_heif_avis
heif_brand_heif_evbi: EVC image
heif_brand_heif_evbs: EVC sequence
heif_brand_heif_heic: HEIF image with h265
heif_brand_heif_heim: multiview
heif_brand_heif_heis: scalable
heif_brand_heif_heix: 10bit images, or anything that uses h265 with range extension
heif_brand_heif_hevc: brands for image sequences
heif_brand_heif_hevm: multiview sequence
heif_brand_heif_hevs: scalable sequence
heif_brand_heif_hevx: brands for image sequences
heif_brand_heif_j2is: JPEG2000 image sequence
heif_brand_heif_j2ki: JPEG2000 image
heif_brand_heif_mif1: image, any coding algorithm
heif_brand_heif_msf1: sequence, any coding algorithm
heif_brand_heif_unknown_brand
heif_brand_heif_vvic: VVC image
heif_brand_heif_vvis: VVC sequence
heif_channel_heif_channel_Alpha
heif_channel_heif_channel_B
heif_channel_heif_channel_Cb
heif_channel_heif_channel_Cr
heif_channel_heif_channel_G
heif_channel_heif_channel_R
heif_channel_heif_channel_Y
heif_channel_heif_channel_depth
heif_channel_heif_channel_disparity
heif_channel_heif_channel_filter_array
heif_channel_heif_channel_interleaved
heif_chroma_downsampling_algorithm_heif_chroma_downsampling_average
heif_chroma_downsampling_algorithm_heif_chroma_downsampling_nearest_neighbor
heif_chroma_downsampling_algorithm_heif_chroma_downsampling_sharp_yuv: Combine with ‘heif_chroma_upsampling_bilinear’ for best quality. Makes edges look sharper when using YUV 420 with bilinear chroma upsampling.
heif_chroma_heif_chroma_420
heif_chroma_heif_chroma_422
heif_chroma_heif_chroma_444
heif_chroma_heif_chroma_interleaved_RGB
heif_chroma_heif_chroma_interleaved_RGBA
heif_chroma_heif_chroma_interleaved_RRGGBBAA_BE: HDR, big endian.
heif_chroma_heif_chroma_interleaved_RRGGBBAA_LE: HDR, little endian.
heif_chroma_heif_chroma_interleaved_RRGGBB_BE: HDR, big endian.
heif_chroma_heif_chroma_interleaved_RRGGBB_LE: HDR, little endian.
heif_chroma_heif_chroma_monochrome
heif_chroma_heif_chroma_undefined
heif_chroma_upsampling_algorithm_heif_chroma_upsampling_bilinear
heif_chroma_upsampling_algorithm_heif_chroma_upsampling_nearest_neighbor
heif_color_primaries_heif_color_primaries_EBU_Tech_3213_E
heif_color_primaries_heif_color_primaries_ITU_R_BT_470_6_System_B_G
heif_color_primaries_heif_color_primaries_ITU_R_BT_470_6_System_M
heif_color_primaries_heif_color_primaries_ITU_R_BT_601_6
heif_color_primaries_heif_color_primaries_ITU_R_BT_709_5: g=0.3;0.6, b=0.15;0.06, r=0.64;0.33, w=0.3127,0.3290
heif_color_primaries_heif_color_primaries_ITU_R_BT_2020_2_and_2100_0
heif_color_primaries_heif_color_primaries_SMPTE_240M
heif_color_primaries_heif_color_primaries_SMPTE_EG_432_1
heif_color_primaries_heif_color_primaries_SMPTE_RP_431_2
heif_color_primaries_heif_color_primaries_SMPTE_ST_428_1
heif_color_primaries_heif_color_primaries_generic_film
heif_color_primaries_heif_color_primaries_unspecified
heif_color_profile_type_heif_color_profile_type_nclx
heif_color_profile_type_heif_color_profile_type_not_present
heif_color_profile_type_heif_color_profile_type_prof
heif_color_profile_type_heif_color_profile_type_rICC
heif_colorspace_heif_colorspace_RGB: heif_colorspace_RGB should be used with one of these heif_chroma values:
heif_colorspace_heif_colorspace_YCbCr: heif_colorspace_YCbCr should be used with one of these heif_chroma values:
heif_colorspace_heif_colorspace_monochrome: heif_colorspace_monochrome should only be used with heif_chroma = heif_chroma_monochrome
heif_colorspace_heif_colorspace_nonvisual: Indicates that this image has no visual channels.
heif_colorspace_heif_colorspace_undefined
heif_compression_format_heif_compression_AV1: AV1 compression, used for AVIF images.
heif_compression_format_heif_compression_AVC: AVC compression. (Currently unused in libheif.)
heif_compression_format_heif_compression_EVC: EVC compression. (Currently unused in libheif.)
heif_compression_format_heif_compression_HEVC: HEVC compression, used for HEIC images.
heif_compression_format_heif_compression_HTJ2K: High Throughput JPEG 2000 (HT-J2K) compression.
heif_compression_format_heif_compression_JPEG: JPEG compression.
heif_compression_format_heif_compression_JPEG2000: JPEG 2000 compression.
heif_compression_format_heif_compression_VVC: VVC compression.
heif_compression_format_heif_compression_mask: Mask image encoding.
heif_compression_format_heif_compression_uncompressed: Uncompressed encoding.
heif_compression_format_heif_compression_undefined: Unspecified / undefined compression format.
heif_depth_representation_type_heif_depth_representation_type_nonuniform_disparity
heif_depth_representation_type_heif_depth_representation_type_uniform_Z
heif_depth_representation_type_heif_depth_representation_type_uniform_disparity
heif_depth_representation_type_heif_depth_representation_type_uniform_inverse_Z
heif_encoder_parameter_type_heif_encoder_parameter_type_boolean
heif_encoder_parameter_type_heif_encoder_parameter_type_integer
heif_encoder_parameter_type_heif_encoder_parameter_type_string
heif_error_code_heif_error_Canceled: Operation has been canceled
heif_error_code_heif_error_Color_profile_does_not_exist: Application has asked for a color profile type that does not exist
heif_error_code_heif_error_Decoder_plugin_error: The decoder plugin generated an error
heif_error_code_heif_error_Encoder_plugin_error: The encoder plugin generated an error
heif_error_code_heif_error_Encoding_error: Error during encoding or when writing to the output
heif_error_code_heif_error_End_of_sequence: Operation has been canceled
heif_error_code_heif_error_Input_does_not_exist: Input file does not exist.
heif_error_code_heif_error_Invalid_input: Error in input file. Corrupted or invalid content.
heif_error_code_heif_error_Memory_allocation_error: Could not allocate enough memory.
heif_error_code_heif_error_Ok: Everything ok, no error occurred.
heif_error_code_heif_error_Plugin_loading_error: Error loading a dynamic plugin
heif_error_code_heif_error_Unsupported_feature: Image requires an unsupported decoder feature.
heif_error_code_heif_error_Unsupported_filetype: Input file type is not supported.
heif_error_code_heif_error_Usage_error: Library API has been used in an invalid way.
heif_filetype_result_heif_filetype_maybe: not sure whether it is an heif, try detection with more input data
heif_filetype_result_heif_filetype_no
heif_filetype_result_heif_filetype_yes_supported: it is heif and can be read by libheif
heif_filetype_result_heif_filetype_yes_unsupported: it is heif, but cannot be read by libheif
heif_item_property_type_heif_item_property_type_image_size: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_invalid: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_tai_clock_info: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_tai_timestamp: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_transform_crop: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_transform_mirror: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_transform_rotation: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_user_description: heif_item_property_unknown = -1,
heif_item_property_type_heif_item_property_type_uuid: heif_item_property_unknown = -1,
heif_matrix_coefficients_heif_matrix_coefficients_ICtCp
heif_matrix_coefficients_heif_matrix_coefficients_ITU_R_BT_470_6_System_B_G
heif_matrix_coefficients_heif_matrix_coefficients_ITU_R_BT_601_6: TODO: or 601-7 according to h.273
heif_matrix_coefficients_heif_matrix_coefficients_ITU_R_BT_709_5: TODO: or 709-6 according to h.273
heif_matrix_coefficients_heif_matrix_coefficients_ITU_R_BT_2020_2_constant_luminance
heif_matrix_coefficients_heif_matrix_coefficients_ITU_R_BT_2020_2_non_constant_luminance
heif_matrix_coefficients_heif_matrix_coefficients_RGB_GBR
heif_matrix_coefficients_heif_matrix_coefficients_SMPTE_240M
heif_matrix_coefficients_heif_matrix_coefficients_SMPTE_ST_2085
heif_matrix_coefficients_heif_matrix_coefficients_US_FCC_T47
heif_matrix_coefficients_heif_matrix_coefficients_YCgCo
heif_matrix_coefficients_heif_matrix_coefficients_chromaticity_derived_constant_luminance
heif_matrix_coefficients_heif_matrix_coefficients_chromaticity_derived_non_constant_luminance
heif_matrix_coefficients_heif_matrix_coefficients_unspecified
heif_metadata_compression_heif_metadata_compression_auto
heif_metadata_compression_heif_metadata_compression_brotli
heif_metadata_compression_heif_metadata_compression_deflate
heif_metadata_compression_heif_metadata_compression_off
heif_metadata_compression_heif_metadata_compression_unknown: only used when reading unknown method from input file
heif_metadata_compression_heif_metadata_compression_zlib: do not use for header data
heif_orientation_heif_orientation_flip_horizontally
heif_orientation_heif_orientation_flip_vertically
heif_orientation_heif_orientation_normal
heif_orientation_heif_orientation_rotate_90_cw
heif_orientation_heif_orientation_rotate_90_cw_then_flip_horizontally
heif_orientation_heif_orientation_rotate_90_cw_then_flip_vertically
heif_orientation_heif_orientation_rotate_180
heif_orientation_heif_orientation_rotate_270_cw
heif_plugin_type_heif_plugin_type_decoder
heif_plugin_type_heif_plugin_type_encoder
heif_progress_step_heif_progress_step_load_tile
heif_progress_step_heif_progress_step_total
heif_reader_grow_status_heif_reader_grow_status_error: an error has occurred
heif_reader_grow_status_heif_reader_grow_status_size_beyond_eof: size has not been reached and never will. The file has grown to its full size
heif_reader_grow_status_heif_reader_grow_status_size_reached: requested size has been reached, we can read until this point
heif_reader_grow_status_heif_reader_grow_status_timeout: size has not been reached yet, but it may still grow further (deprecated)
heif_region_type_heif_region_type_ellipse: Ellipse geometry.
heif_region_type_heif_region_type_inline_mask: Inline mask.
heif_region_type_heif_region_type_point: Point gemetry.
heif_region_type_heif_region_type_polygon: Polygon geometry.
heif_region_type_heif_region_type_polyline: Polyline geometry.
heif_region_type_heif_region_type_rectangle: Rectangle geometry.
heif_region_type_heif_region_type_referenced_mask: Reference mask.
heif_sample_aux_info_presence_heif_sample_aux_info_presence_mandatory
heif_sample_aux_info_presence_heif_sample_aux_info_presence_none
heif_sample_aux_info_presence_heif_sample_aux_info_presence_optional
heif_suberror_code_heif_suberror_Auxiliary_image_type_unspecified: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Camera_extrinsic_matrix_undefined: Image has no ispe property
heif_suberror_code_heif_suberror_Camera_intrinsic_matrix_undefined: Image has no ispe property
heif_suberror_code_heif_suberror_Cannot_read_plugin_directory: error while scanning the directory for plugins
heif_suberror_code_heif_suberror_Cannot_write_output_data: — Encoding_error —
heif_suberror_code_heif_suberror_Compression_initialisation_error: There was an error from the underlying compression / decompression library. One possibility is lack of resources (e.g. memory).
heif_suberror_code_heif_suberror_Decompression_invalid_data: Decompressing generic compression or header compression data failed (e.g. bitstream corruption)
heif_suberror_code_heif_suberror_Encoder_cleanup: — Encoding_error —
heif_suberror_code_heif_suberror_Encoder_encoding: — Encoding_error —
heif_suberror_code_heif_suberror_Encoder_initialization: — Encoding_error —
heif_suberror_code_heif_suberror_End_of_data: End of data reached unexpectedly.
heif_suberror_code_heif_suberror_Invalid_J2K_codestream: Invalid JPEG 2000 codestream - usually a missing marker
heif_suberror_code_heif_suberror_Invalid_box_size: Size of box (defined in header) is wrong
heif_suberror_code_heif_suberror_Invalid_clean_aperture: Tile-images in a grid image are missing
heif_suberror_code_heif_suberror_Invalid_fractional_number: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Invalid_grid_data: Invalid specification of image grid (tiled image)
heif_suberror_code_heif_suberror_Invalid_image_size: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Invalid_mini_box: we got a mini box, but could not read it properly
heif_suberror_code_heif_suberror_Invalid_overlay_data: Invalid specification of overlay image
heif_suberror_code_heif_suberror_Invalid_parameter_value: The value for the given parameter is not in the valid range.
heif_suberror_code_heif_suberror_Invalid_pixi_box: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Invalid_property: Error in property specification
heif_suberror_code_heif_suberror_Invalid_region_data: Invalid specification of region item
heif_suberror_code_heif_suberror_Ipma_box_references_nonexisting_property: An item property referenced in the ‘ipma’ box is not existing in the ‘ipco’ container.
heif_suberror_code_heif_suberror_Item_reference_cycle: Image reference cycle found in iref
heif_suberror_code_heif_suberror_Missing_grid_images: Tile-images in a grid image are missing
heif_suberror_code_heif_suberror_No_av1C_box: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_No_avcC_box: icbr is only needed in some situations, this error is for those cases
heif_suberror_code_heif_suberror_No_ftyp_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_hdlr_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_hvcC_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_icbr_box: icbr is only needed in some situations, this error is for those cases
heif_suberror_code_heif_suberror_No_idat_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_iinf_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_iloc_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_infe_box: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_No_ipco_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_ipma_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_iprp_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_iref_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_ispe_property: Image has no ispe property
heif_suberror_code_heif_suberror_No_item_data: Image has no (compressed) data
heif_suberror_code_heif_suberror_No_matching_decoder_installed: no decoder found for that compression format
heif_suberror_code_heif_suberror_No_meta_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_moov_box: Decompressing generic compression or header compression data failed (e.g. bitstream corruption)
heif_suberror_code_heif_suberror_No_or_invalid_primary_item: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_No_pict_handler: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_pitm_box: Mandatory ‘ftyp’ box is missing
heif_suberror_code_heif_suberror_No_properties_assigned_to_item: No properties have been assigned to an item.
heif_suberror_code_heif_suberror_No_vvcC_box: Invalid JPEG 2000 codestream - usually a missing marker
heif_suberror_code_heif_suberror_Nonexisting_image_channel_referenced: Image channel referenced that does not exist in the image
heif_suberror_code_heif_suberror_Nonexisting_item_referenced: also used for Invalid_input
heif_suberror_code_heif_suberror_Null_pointer_argument: An API argument was given a NULL pointer, which is not allowed for that function.
heif_suberror_code_heif_suberror_Overlay_image_outside_of_canvas: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Plugin_is_not_loaded: trying to remove a plugin that is not loaded
heif_suberror_code_heif_suberror_Plugin_loading_error: a specific plugin file cannot be loaded
heif_suberror_code_heif_suberror_Security_limit_exceeded: A security limit preventing unreasonable memory allocations was exceeded by the input file. Please check whether the file is valid. If it is, contact us so that we could increase the security limits further.
heif_suberror_code_heif_suberror_Too_many_regions: — Encoding_error —
heif_suberror_code_heif_suberror_Unknown_NCLX_color_primaries: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Unknown_NCLX_matrix_coefficients: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Unknown_NCLX_transfer_characteristics: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Unknown_color_profile_type: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Unspecified: no further information available
heif_suberror_code_heif_suberror_Unsupported_bit_depth: — Encoder_plugin_error —
heif_suberror_code_heif_suberror_Unsupported_codec: Image was coded with an unsupported compression method.
heif_suberror_code_heif_suberror_Unsupported_color_conversion: The conversion of the source image to the requested chroma / colorspace is not supported.
heif_suberror_code_heif_suberror_Unsupported_data_version: Image is specified in an unknown way, e.g. as tiled grid image (which is supported)
heif_suberror_code_heif_suberror_Unsupported_essential_property: Generically compressed data used an unsupported compression method
heif_suberror_code_heif_suberror_Unsupported_generic_compression_method: Generically compressed data used an unsupported compression method
heif_suberror_code_heif_suberror_Unsupported_header_compression_method: The conversion of the source image to the requested chroma / colorspace is not supported.
heif_suberror_code_heif_suberror_Unsupported_image_type: Image is specified in an unknown way, e.g. as tiled grid image (which is supported)
heif_suberror_code_heif_suberror_Unsupported_item_construction_method: The conversion of the source image to the requested chroma / colorspace is not supported.
heif_suberror_code_heif_suberror_Unsupported_parameter: The given (encoder) parameter name does not exist.
heif_suberror_code_heif_suberror_Unsupported_plugin_version: The version of the passed plugin is not supported.
heif_suberror_code_heif_suberror_Unsupported_writer_version: The version of the passed writer is not supported.
heif_suberror_code_heif_suberror_Wrong_tile_image_chroma_format: Overlay image completely outside of visible canvas area
heif_suberror_code_heif_suberror_Wrong_tile_image_pixel_depth: Overlay image completely outside of visible canvas area
heif_track_reference_type_heif_track_reference_type_auxiliary: auxiliary data (e.g. depth maps or alpha channel)
heif_track_reference_type_heif_track_reference_type_description: track_description
heif_track_reference_type_heif_track_reference_type_thumbnails: thumbnails
heif_track_type_4cc_heif_track_type_image_sequence
heif_track_type_4cc_heif_track_type_metadata
heif_track_type_4cc_heif_track_type_video
heif_transfer_characteristics_heif_transfer_characteristic_IEC_61966_2_1
heif_transfer_characteristics_heif_transfer_characteristic_IEC_61966_2_4
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_470_6_System_B_G
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_470_6_System_M
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_601_6
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_709_5
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_1361
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_2020_2_10bit
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_2020_2_12bit
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_2100_0_HLG
heif_transfer_characteristics_heif_transfer_characteristic_ITU_R_BT_2100_0_PQ
heif_transfer_characteristics_heif_transfer_characteristic_SMPTE_240M
heif_transfer_characteristics_heif_transfer_characteristic_SMPTE_ST_428_1
heif_transfer_characteristics_heif_transfer_characteristic_linear
heif_transfer_characteristics_heif_transfer_characteristic_logarithmic_100
heif_transfer_characteristics_heif_transfer_characteristic_logarithmic_100_sqrt10
heif_transfer_characteristics_heif_transfer_characteristic_unspecified
heif_transform_mirror_direction_heif_transform_mirror_direction_horizontal: flip image horizontally
heif_transform_mirror_direction_heif_transform_mirror_direction_invalid
heif_transform_mirror_direction_heif_transform_mirror_direction_vertical: flip image vertically

Functions§

heif_brand_to_fourcc^⚠: the output buffer must be at least 4 bytes long
heif_camera_extrinsic_matrix_get_rotation_matrix^⚠
heif_camera_extrinsic_matrix_release^⚠
heif_check_filetype^⚠: input data should be at least 12 bytes
heif_check_jpeg_filetype^⚠
heif_color_conversion_options_ext_alloc^⚠
heif_color_conversion_options_ext_copy^⚠
heif_color_conversion_options_ext_free^⚠
heif_color_conversion_options_set_defaults^⚠: Assumes that it is a version=1 struct.
heif_context_add_XMP_metadata^⚠: Add XMP metadata to an image.
heif_context_add_XMP_metadata2^⚠: New version of heif_context_add_XMP_metadata() with data compression (experimental).
heif_context_add_compatible_brand^⚠: Add a compatible brand that is now added automatically by libheif when encoding images (e.g. some application brands like ‘geo1’).
heif_context_add_exif_metadata^⚠: Add EXIF metadata to an image.
heif_context_add_generic_metadata^⚠: Add generic, proprietary metadata to an image. You have to specify an ‘item_type’ that will identify your metadata. ‘content_type’ can be an additional type, or it can be NULL. For example, this function can be used to add IPTC metadata (IIM stream, not XMP) to an image. Although not standard, we propose to store IPTC data with item type=“iptc”, content_type=NULL.
heif_context_add_generic_uri_metadata^⚠: Add generic metadata with item_type “uri “. Items with this type do not have a content_type, but an item_uri_type and they have no content_encoding (they are always stored uncompressed).
heif_context_add_grid_image^⚠
heif_context_add_image_tile^⚠
heif_context_add_item^⚠: ———————–– adding new items ———————––
heif_context_add_item_reference^⚠
heif_context_add_item_references^⚠
heif_context_add_mime_item^⚠
heif_context_add_overlay_image^⚠: offsets[] should either be NULL (all offsets==0) or an array of size 2*nImages with x;y offset pairs. If background_rgba is NULL, the background is transparent.
heif_context_add_precompressed_mime_item^⚠
heif_context_add_uri_item^⚠
heif_context_add_uri_metadata_sequence_track^⚠: Add a metadata track. The track content type is specified by the ‘uri’ parameter. This will be created as a ‘urim’ “URI Meta Sample Entry”.
heif_context_add_visual_sequence_track^⚠: Add a visual track to the sequence. The track ID is assigned automatically.
heif_context_alloc^⚠: Allocate a new context for reading HEIF files. Has to be freed again with heif_context_free().
heif_context_assign_thumbnail^⚠: Assign ‘thumbnail_image’ as the thumbnail image of ‘master_image’.
heif_context_debug_dump_boxes_to_file^⚠: Print information about the boxes of a HEIF file to file descriptor. This is for debugging and informational purposes only. You should not rely on the output having a specific format. At best, you should not use this at all.
heif_context_encode_grid^⚠: @brief Encodes an array of images into a grid.
heif_context_encode_image^⚠: Compress the input image. Returns a handle to the coded image in ‘out_image_handle’ unless out_image_handle = NULL. ‘options’ should be NULL for now. The first image added to the context is also automatically set the primary image, but you can change the primary image later with heif_context_set_primary_image().
heif_context_encode_thumbnail^⚠: Encode the ‘image’ as a scaled down thumbnail image. The image is scaled down to fit into a square area of width ‘bbox_size’. If the input image is already so small that it fits into this bounding box, no thumbnail image is encoded and NULL is returned in ‘out_thumb_image_handle’. No error is returned in this case. The encoded thumbnail is automatically assigned to the ‘master_image_handle’. Hence, you do not have to call heif_context_assign_thumbnail().
heif_context_free^⚠: Free a previously allocated HEIF context. You should not free a context twice.
heif_context_get_encoder^⚠: Get an encoder instance that can be used to actually encode images from a descriptor.
heif_context_get_encoder_descriptors^⚠: DEPRECATED: use heif_get_encoder_descriptors() instead. Get a list of available encoders. You can filter the encoders by compression format and name. Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards. The returned list of encoders is sorted by their priority (which is a plugin property). The number of encoders is returned, which are not more than ‘count’ if (out_encoders != nullptr). By setting out_encoders==nullptr, you can query the number of encoders, ‘count’ is ignored. Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
heif_context_get_encoder_for_format^⚠: Get an encoder for the given compression format. If there are several encoder plugins for this format, the encoder with the highest plugin priority will be returned.
heif_context_get_entity_groups^⚠: Use 0 for type_filter or item_filter to disable the filter. Returns an array of heif_entity_group structs with *out_num_groups entries.
heif_context_get_image_handle^⚠: Get the image handle for a known image ID.
heif_context_get_item_references^⚠: Get the item ids that reference the given item.
heif_context_get_list_of_item_IDs^⚠: Get the item identifiers.
heif_context_get_list_of_top_level_image_IDs^⚠: Fills in image IDs into the user-supplied int-array ‘ID_array’, preallocated with ‘count’ entries. Function returns the total number of IDs filled into the array.
heif_context_get_number_of_items^⚠: Gets the number of items.
heif_context_get_number_of_top_level_images^⚠: Number of top-level images in the HEIF file. This does not include the thumbnails or the tile images that are composed to an image grid. You can get access to the thumbnails via the main image handle.
heif_context_get_primary_image_ID^⚠
heif_context_get_primary_image_handle^⚠: Get a handle to the primary image of the HEIF file. This is the image that should be displayed primarily when there are several images in the file.
heif_context_get_region_item^⚠: Get the region item.
heif_context_get_security_limits^⚠: Returns the security limits for a heif_context. By default, the limits are set to the global limits, but you can change them in the returned object.
heif_context_get_sequence_duration^⚠: Get the total duration of the sequence in timescale clock ticks. Use heif_context_get_sequence_timescale() to get the clock ticks per second.
heif_context_get_sequence_timescale^⚠: Get the timescale (clock ticks per second) for timing values in the sequence.
heif_context_get_track^⚠: Get the heif_track object for the given track ID. If you pass id=0, the first visual track will be returned. If there is no track with the given ID or if 0 is passed and there is no visual track, NULL will be returned.
heif_context_get_track_ids^⚠: Returns the IDs for each of the tracks stored in the HEIF file. The output array must have heif_context_number_of_sequence_tracks() entries.
heif_context_has_sequence^⚠: Check whether there is an image sequence in the HEIF file.
heif_context_is_top_level_image_ID^⚠
heif_context_number_of_sequence_tracks^⚠: Get the number of tracks in the HEIF file.
heif_context_read_from_file^⚠: Read a HEIF file from a named disk file. The heif_reading_options should currently be set to NULL.
heif_context_read_from_memory^⚠: Read a HEIF file stored completely in memory. The heif_reading_options should currently be set to NULL. DEPRECATED: use heif_context_read_from_memory_without_copy() instead.
heif_context_read_from_memory_without_copy^⚠: Same as heif_context_read_from_memory() except that the provided memory is not copied. That means, you will have to keep the memory area alive as long as you use the heif_context.
heif_context_read_from_reader^⚠
heif_context_set_major_brand^⚠: Set the major brand of the file. If this function is not called, the major brand is determined automatically from the image or sequence content.
heif_context_set_max_decoding_threads^⚠: If the maximum threads number is set to 0, the image tiles are decoded in the main thread. This is different from setting it to 1, which will generate a single background thread to decode the tiles. Note that this setting only affects libheif itself. The codecs itself may still use multi-threaded decoding. You can use it, for example, in cases where you are decoding several images in parallel anyway you thus want to minimize parallelism in each decoder.
heif_context_set_maximum_image_size_limit^⚠: Set the maximum image size security limit. This function will set the maximum image area (number of pixels) to maximum_width ^ 2. Alternatively to using this function, you can also set the maximum image area in the security limits structure returned by heif_context_get_security_limits().
heif_context_set_primary_image^⚠
heif_context_set_security_limits^⚠: Overwrites the security limits of a heif_context. This is a convenience function to easily copy limits.
heif_context_set_sequence_timescale^⚠: Set an independent global timescale for the sequence. If no timescale is set with this function, the timescale of the first track will be used.
heif_context_write^⚠
heif_context_write_to_file^⚠: ==================================================================================================== Write the heif_context to a HEIF file
heif_decode_image^⚠: Decode an heif_image_handle into the actual pixel image and also carry out all geometric transformations specified in the HEIF file (rotation, cropping, mirroring).
heif_decoder_descriptor_get_id_name^⚠: Return a short, symbolic name for identifying the decoder. This name should stay constant over different decoder versions. Note: the returned ID may be NULL for old plugins that don’t support this yet.
heif_decoder_descriptor_get_name^⚠: Return a long, descriptive name of the decoder (including version information).
heif_decoding_options_alloc^⚠: Allocate decoding options and fill with default values. Note: you should always get the decoding options through this function since the option structure may grow in size in future versions.
heif_decoding_options_copy^⚠
heif_decoding_options_free^⚠
heif_deinit^⚠: Deinitialise and clean up library.
heif_depth_representation_info_free^⚠
heif_encoder_descriptor_get_compression_format^⚠
heif_encoder_descriptor_get_id_name^⚠: Return a short, symbolic name for identifying the encoder. This name should stay constant over different encoder versions.
heif_encoder_descriptor_get_name^⚠: Return a long, descriptive name of the encoder (including version information).
heif_encoder_descriptor_supportes_lossless_compression^⚠: DEPRECATED, typo in function name
heif_encoder_descriptor_supportes_lossy_compression^⚠: DEPRECATED, typo in function name
heif_encoder_descriptor_supports_lossless_compression^⚠
heif_encoder_descriptor_supports_lossy_compression^⚠
heif_encoder_get_name^⚠: Get the encoder name from the encoder itself.
heif_encoder_get_parameter^⚠: Get the current value of a parameter of any type as a human readable string. The returned string is compatible with heif_encoder_set_parameter().
heif_encoder_get_parameter_boolean^⚠
heif_encoder_get_parameter_integer^⚠
heif_encoder_get_parameter_string^⚠
heif_encoder_has_default^⚠: Query whether a specific parameter has a default value.
heif_encoder_list_parameters^⚠: Get a generic list of encoder parameters. Each encoder may define its own, additional set of parameters. You do not have to free the returned list.
heif_encoder_parameter_get_name^⚠: Return the parameter name.
heif_encoder_parameter_get_type^⚠: Return the parameter type.
heif_encoder_parameter_get_valid_integer_range^⚠: DEPRECATED. Use heif_encoder_parameter_get_valid_integer_values() instead.
heif_encoder_parameter_get_valid_integer_values^⚠: If integer is limited by a range, have_minimum and/or have_maximum will be != 0 and *minimum, *maximum is set. If integer is limited by a fixed set of values, *num_valid_values will be >0 and *out_integer_array is set.
heif_encoder_parameter_get_valid_string_values^⚠
heif_encoder_parameter_integer_valid_range^⚠
heif_encoder_parameter_integer_valid_values^⚠
heif_encoder_parameter_string_valid_values^⚠: returns a NULL-terminated list of valid strings or NULL if all values are allowed
heif_encoder_release^⚠: You have to release the encoder after use.
heif_encoder_set_logging_level^⚠: level should be between 0 (= none) to 4 (= full)
heif_encoder_set_lossless^⚠
heif_encoder_set_lossy_quality^⚠: Set a ‘quality’ factor (0-100). How this is mapped to actual encoding parameters is encoder dependent.
heif_encoder_set_parameter^⚠: Set a parameter of any type to the string value. Integer values are parsed from the string. Boolean values can be “true”/“false”/“1”/“0”
heif_encoder_set_parameter_boolean^⚠
heif_encoder_set_parameter_integer^⚠
heif_encoder_set_parameter_string^⚠
heif_encoding_options_alloc^⚠
heif_encoding_options_copy^⚠
heif_encoding_options_free^⚠
heif_entity_groups_release^⚠: Release an array of entity groups returned by heif_context_get_entity_groups().
heif_fourcc_to_brand^⚠: ‘brand_fourcc’ must be 4 character long, but need not be 0-terminated
heif_free_list_of_compatible_brands^⚠
heif_free_plugin_directories^⚠
heif_get_decoder_descriptors^⚠: Get a list of available decoders. You can filter the encoders by compression format. Use format_filter==heif_compression_undefined to get all available decoders. The returned list of decoders is sorted by their priority (which is a plugin property). The number of decoders is returned, which are not more than ‘count’ if (out_decoders != nullptr). By setting out_decoders==nullptr, you can query the number of decoders, ‘count’ is ignored.
heif_get_disabled_security_limits^⚠: Returns a set of fully disabled security limits. Use with care and only after user confirmation.
heif_get_encoder_descriptors^⚠: Get a list of available encoders. You can filter the encoders by compression format and name. Use format_filter==heif_compression_undefined and name_filter==NULL as wildcards. The returned list of encoders is sorted by their priority (which is a plugin property). The number of encoders is returned, which are not more than ‘count’ if (out_encoders != nullptr). By setting out_encoders==nullptr, you can query the number of encoders, ‘count’ is ignored. Note: to get the actual encoder from the descriptors returned here, use heif_context_get_encoder().
heif_get_file_mime_type^⚠: Returns one of these MIME types:
heif_get_global_security_limits^⚠: The global security limits are the default for new heif_contexts. These global limits cannot be changed, but you can override the limits for a specific heif_context.
heif_get_plugin_directories^⚠: Get a NULL terminated array of the plugin directories that are searched by libheif. This includes the paths specified in the environment variable LIBHEIF_PLUGIN_PATHS and the built-in path (if not overridden by the environment variable).
heif_get_version^⚠: Version string of linked libheif library.
heif_get_version_number^⚠: Numeric version of linked libheif library, encoded as 0xHHMMLL00 = hh.mm.ll, where hh, mm, ll is the decimal representation of HH, MM, LL. For example: 0x02150300 is version 2.21.3
heif_get_version_number_maintenance^⚠: Numeric part “LL” from above. Returned as a decimal number.
heif_get_version_number_major^⚠: Numeric part “HH” from above. Returned as a decimal number.
heif_get_version_number_minor^⚠: Numeric part “MM” from above. Returned as a decimal number.
heif_has_compatible_brand^⚠: ‘brand_fourcc’ must be 4 character long, but need not be 0-terminated returns 1 if file includes the brand, and 0 if it does not returns -1 if the provided data is not sufficient (you should input at least as many bytes as indicated in the first 4 bytes of the file, usually ~50 bytes will do) returns -2 on other errors
heif_has_compatible_filetype^⚠: Check the filetype box content for a supported file type.
heif_have_decoder_for_format^⚠: Quick check whether there is a decoder available for the given format. Note that the decoder still may not be able to decode all variants of that format. You will have to query that further (todo) or just try to decode and check the returned error.
heif_have_encoder_for_format^⚠: Quick check whether there is an enoder available for the given format. Note that the encoder may be limited to a certain subset of features (e.g. only 8 bit, only lossy). You will have to query the specific capabilities further.
heif_image_add_decoding_warning^⚠: This function is only for decoder plugin implementors.
heif_image_add_plane^⚠: Add an image plane to the image.
heif_image_add_plane_safe^⚠: The security limits should preferably be the limits from a heif_context. The memory allocated will then be registered in the memory budget of that context.
heif_image_create^⚠: Create a new image of the specified resolution and colorspace.
heif_image_crop^⚠
heif_image_extend_padding_to_size^⚠: This function extends the padding of the image so that it has at least the given physical size. The padding border is filled with the pixels along the right/bottom border. This function may be useful if you want to process the image, but have some external padding requirements. The image size will not be modified if it is already larger/equal than the given physical size. I.e. you cannot assume that after calling this function, the stride will be equal to min_physical_width.
heif_image_extend_to_size_fill_with_zero^⚠: Extends the image size to match the given size by extending the right and bottom borders. The border areas are filled with zero.
heif_image_extract_area^⚠
heif_image_get_bits_per_pixel^⚠: Get the number of bits per pixel in the given image channel. Returns -1 if a non-existing channel was given. Note that the number of bits per pixel may be different for each color channel. This function returns the number of bits used for storage of each pixel. Especially for HDR images, this is probably not what you want. Have a look at heif_image_get_bits_per_pixel_range() instead.
heif_image_get_bits_per_pixel_range^⚠: Get the number of bits per pixel in the given image channel. This function returns the number of bits used for representing the pixel value, which might be smaller than the number of bits used in memory. For example, in 12bit HDR images, this function returns ‘12’, while still 16 bits are reserved for storage. For interleaved RGBA with 12 bit, this function also returns ‘12’, not ‘48’ or ‘64’ (heif_image_get_bits_per_pixel returns 64 in this case).
heif_image_get_chroma_format^⚠: Get the chroma format of the image.
heif_image_get_color_profile_type^⚠: Note: in early versions of HEIF, there could only be one color profile per image. However, this has been changed. This function will now return ICC if one is present and NCLX only if there is no ICC. You may better avoid this function and simply query for NCLX and ICC directly.
heif_image_get_colorspace^⚠: Get the colorspace format of the image.
heif_image_get_content_light_level^⚠
heif_image_get_decoding_warnings^⚠: Fills the image decoding warnings into the provided ‘out_warnings’ array. The size of the array has to be provided in max_output_buffer_entries. If max_output_buffer_entries==0, the number of decoder warnings is returned. The function fills the warnings into the provided buffer, starting with ‘first_warning_idx’. It returns the number of warnings filled into the buffer. Note: you can iterate through all warnings by using ‘max_output_buffer_entries=1’ and iterate ‘first_warning_idx’.
heif_image_get_duration^⚠: Get the image display duration in clock ticks of this track. Make sure to use the timescale of the track and not the timescale of the total sequence.
heif_image_get_gimi_sample_content_id^⚠: Get the GIMI content ID stored in the image sample. If there is no content ID, NULL is returned. @return
heif_image_get_height^⚠: Get the height of a specified image channel.
heif_image_get_mastering_display_colour_volume^⚠
heif_image_get_nclx_color_profile^⚠
heif_image_get_pixel_aspect_ratio^⚠
heif_image_get_plane^⚠: Deprecated, use the safer version heif_image_get_plane2() instead.
heif_image_get_plane2^⚠
heif_image_get_plane_readonly^⚠: Get a pointer to the actual pixel data. The ‘out_stride’ is returned as “bytes per line”. When out_stride is NULL, no value will be written. Returns NULL if a non-existing channel was given. Deprecated, use the safer version heif_image_get_plane_readonly2() instead.
heif_image_get_plane_readonly2^⚠: These are safer variants of the two functions above. The ‘stride’ parameter is often multiplied by the image height in the client application. For very large images, this can lead to integer overflows and, consequently, illegal memory accesses. The changed ‘stride’ parameter types eliminates this common error.
heif_image_get_primary_height^⚠: Get the height of the main channel.
heif_image_get_primary_width^⚠: Get the width of the main channel.
heif_image_get_raw_color_profile^⚠: Returns the ICC profile if one is assigned to the image. Otherwise, it returns an error.
heif_image_get_raw_color_profile_size^⚠: Returns the size of the ICC profile if one is assigned to the image. Otherwise, it returns 0.
heif_image_get_tai_timestamp^⚠: Get the heif_tai_timestamp_packet attached to the image. The main use of this function is for image sequences, but it can also be used for still images. This function allocates a new heif_tai_timestamp_packet and returns it through out_timestamp.
heif_image_get_width^⚠: Get the width of a specified image channel.
heif_image_handle_add_region_item^⚠: Add a region item to an image.
heif_image_handle_decode_image_tile^⚠: The tile position is given in tile indices, not in pixel coordinates. If the image transformations are processed (option->ignore_image_transformations==false), the tile position is given in the transformed coordinates.
heif_image_handle_free_auxiliary_types^⚠: DEPRECATED (because typo in function name). Use heif_image_handle_release_auxiliary_type() instead.
heif_image_handle_get_auxiliary_image_handle^⚠: Get the image handle of an auxiliary image.
heif_image_handle_get_auxiliary_type^⚠: You are responsible to deallocate the returned buffer with heif_image_handle_release_auxiliary_type().
heif_image_handle_get_camera_extrinsic_matrix^⚠
heif_image_handle_get_camera_intrinsic_matrix^⚠
heif_image_handle_get_chroma_bits_per_pixel^⚠: Returns -1 on error, e.g. if this information is not present in the image. Only defined for images coded in the YCbCr colorspace.
heif_image_handle_get_color_profile_type^⚠: Returns ‘heif_color_profile_type_not_present’ if there is no color profile. If there is an ICC profile and an NCLX profile, the ICC profile is returned. TODO: we need a new API for this function as images can contain both NCLX and ICC at the same time. However, you can still use heif_image_handle_get_raw_color_profile() and heif_image_handle_get_nclx_color_profile() to access both profiles.
heif_image_handle_get_content_light_level^⚠: Returns whether the image has ‘content light level’ information. If 0 is returned, the output is not filled.
heif_image_handle_get_context^⚠: This gets the context associated with the image handle. Note that you have to release the returned context with heif_context_free() in any case.
heif_image_handle_get_depth_image_handle^⚠
heif_image_handle_get_depth_image_representation_info^⚠: Returns true when there is depth_representation_info available Note 1: depth_image_id is currently unused because we support only one depth channel per image, but you should still provide the correct ID for future compatibility. Note 2: Because of an API bug before v1.11.0, the function also works when ‘handle’ is the handle of the depth image. However, you should pass the handle of the main image. Please adapt your code if needed.
heif_image_handle_get_grid_image_tile_id^⚠: For grid images, return the image item ID of a specific grid tile. If ‘process_image_transformations’ is true, the tile positions are given in the transformed image coordinate system and are internally mapped to the original image tile positions.
heif_image_handle_get_height^⚠
heif_image_handle_get_image_tiling^⚠: If ‘process_image_transformations’ is true, this returns modified sizes. If it is false, the top_offset and left_offset will always be (0;0).
heif_image_handle_get_ispe_height^⚠
heif_image_handle_get_ispe_width^⚠: Get the image width from the ‘ispe’ box. This is the original image size without any transformations applied to it. Do not use this unless you know exactly what you are doing.
heif_image_handle_get_item_id^⚠
heif_image_handle_get_list_of_auxiliary_image_IDs^⚠
heif_image_handle_get_list_of_depth_image_IDs^⚠
heif_image_handle_get_list_of_metadata_block_IDs^⚠: ‘type_filter’ can be used to get only metadata of specific types, like “Exif”. If ‘type_filter’ is NULL, it will return all types of metadata IDs.
heif_image_handle_get_list_of_region_item_ids^⚠: Get the region item identifiers for the region items attached to an image.
heif_image_handle_get_list_of_thumbnail_IDs^⚠
heif_image_handle_get_luma_bits_per_pixel^⚠: Returns -1 on error, e.g. if this information is not present in the image. Only defined for images coded in the YCbCr or monochrome colorspace.
heif_image_handle_get_mastering_display_colour_volume^⚠: Returns whether the image has ‘mastering display colour volume’ information. If 0 is returned, the output is not filled.
heif_image_handle_get_metadata^⚠: ‘out_data’ must point to a memory area of the size reported by heif_image_handle_get_metadata_size(). The data is returned exactly as stored in the HEIF file. For Exif data, you probably have to skip the first four bytes of the data, since they indicate the offset to the start of the TIFF header of the Exif data.
heif_image_handle_get_metadata_content_type^⚠: For EXIF, the content type is empty. For XMP, the content type is “application/rdf+xml”.
heif_image_handle_get_metadata_item_uri_type^⚠: Only valid for item type == “uri “, an absolute URI
heif_image_handle_get_metadata_size^⚠: Get the size of the raw metadata, as stored in the HEIF file.
heif_image_handle_get_metadata_type^⚠: Return a string indicating the type of the metadata, as specified in the HEIF file. Exif data will have the type string “Exif”. This string will be valid until the next call to a libheif function. You do not have to free this string.
heif_image_handle_get_nclx_color_profile^⚠: Returns ‘heif_error_Color_profile_does_not_exist’ when there is no NCLX profile. TODO: This function does currently not return an NCLX profile if it is stored in the image bitstream. Only NCLX profiles stored as colr boxes are returned. This may change in the future.
heif_image_handle_get_number_of_auxiliary_images^⚠: List the number of auxiliary images assigned to this image handle.
heif_image_handle_get_number_of_depth_images^⚠
heif_image_handle_get_number_of_metadata_blocks^⚠: How many metadata blocks are attached to an image. If you only want to get EXIF data, set the type_filter to “Exif”. Otherwise, set the type_filter to NULL.
heif_image_handle_get_number_of_region_items^⚠: Get the number of region items that are attached to an image.
heif_image_handle_get_number_of_thumbnails^⚠: List the number of thumbnails assigned to this image handle. Usually 0 or 1.
heif_image_handle_get_pixel_aspect_ratio^⚠: Returns whether the image has ‘pixel aspect ratio information’ information. If 0 is returned, the output is filled with the 1:1 default.
heif_image_handle_get_preferred_decoding_colorspace^⚠: Return the colorspace that libheif proposes to use for decoding. Usually, these will be either YCbCr or Monochrome, but it may also propose RGB for images encoded with matrix_coefficients=0 or for images coded natively in RGB. It may also return *_undefined if the file misses relevant information to determine this without decoding. These are only proposed values that avoid colorspace conversions as much as possible. You can still request the output in your preferred colorspace, but this may involve an internal conversion.
heif_image_handle_get_raw_color_profile^⚠: Returns ‘heif_error_Color_profile_does_not_exist’ when there is no ICC profile.
heif_image_handle_get_raw_color_profile_size^⚠
heif_image_handle_get_thumbnail^⚠: Get the image handle of a thumbnail image.
heif_image_handle_get_width^⚠: Get the resolution of an image.
heif_image_handle_has_alpha_channel^⚠
heif_image_handle_has_camera_extrinsic_matrix^⚠
heif_image_handle_has_camera_intrinsic_matrix^⚠
heif_image_handle_has_depth_image^⚠: ———————–– depth images ———————––
heif_image_handle_is_premultiplied_alpha^⚠
heif_image_handle_is_primary_image^⚠: Check whether the given image_handle is the primary image of the file.
heif_image_handle_release^⚠: Release image handle.
heif_image_handle_release_auxiliary_type^⚠
heif_image_has_channel^⚠
heif_image_has_content_light_level^⚠
heif_image_has_mastering_display_colour_volume^⚠
heif_image_is_premultiplied_alpha^⚠
heif_image_release^⚠: Release heif_image.
heif_image_scale_image^⚠: Currently, heif_scaling_options is not defined yet. Pass a NULL pointer.
heif_image_set_content_light_level^⚠
heif_image_set_duration^⚠: Set the image display duration in the track’s timescale units.
heif_image_set_gimi_sample_content_id^⚠: Set the GIMI content ID for an image sample. It will be stored as SAI. When passing NULL, a previously set ID will be removed.
heif_image_set_mastering_display_colour_volume^⚠
heif_image_set_nclx_color_profile^⚠
heif_image_set_pixel_aspect_ratio^⚠
heif_image_set_premultiplied_alpha^⚠: Signal that the image is premultiplied by the alpha pixel values.
heif_image_set_raw_color_profile^⚠: The color profile is not attached to the image handle because we might need it for color space transform and encoding.
heif_image_set_tai_timestamp^⚠: Attach a TAI timestamp to the image. The main use of this function is for image sequences, but it can also be used for still images. If used for still images, note that you also have to set the heif_tai_clock_info to the image item through heif_item_set_property_tai_clock_info().
heif_init^⚠: Initialise library.
heif_item_add_property_user_description^⚠: Add a “udes” user description property to the item. If any string pointers are NULL, an empty string will be used instead.
heif_item_add_raw_property^⚠: @param context The heif_context for the file @param itemId The image item id to which this property belongs. @param fourcc_type The short four-cc type of the property to add. @param uuid_type If fourcc_type==‘uuid’, this should point to a 16-byte UUID type. It is ignored otherwise and can be NULL. @param data Data to insert for this property (including a full-box header, if required for this box). @param size Length of data in bytes. @param is_essential Whether this property is essential (boolean). @param out_propertyId Outputs the id of the inserted property. Can be NULL.
heif_item_get_item_data^⚠: Gets the raw metadata, as stored in the HEIF file.
heif_item_get_item_name^⚠
heif_item_get_item_type^⚠: Gets the item type.
heif_item_get_mime_item_content_encoding^⚠: Gets the content_encoding for a MIME item.
heif_item_get_mime_item_content_type^⚠: Gets the MIME content_type for an item.
heif_item_get_properties_of_type^⚠: Get the heif_property_id for a heif_item_id. You may specify which property ‘type’ you want to receive. If you specify ‘heif_item_property_type_invalid’, all properties associated to that item are returned. The number of properties is returned, which are not more than ‘count’ if (out_list != nullptr). By setting out_list==nullptr, you can query the number of properties, ‘count’ is ignored.
heif_item_get_property_raw_data^⚠: @param out_data User-supplied array to write the property data to. The required size of the output array is given by heif_item_get_property_raw_size().
heif_item_get_property_raw_size^⚠
heif_item_get_property_tai_clock_info^⚠: Get the heif_tai_clock_info attached to the item. This function allocates a new heif_tai_clock_info and returns it through out_clock.
heif_item_get_property_tai_timestamp^⚠: Get the heif_tai_timestamp_packet attached to the item. This function allocates a new heif_tai_timestamp_packet and returns it through out_timestamp.
heif_item_get_property_transform_crop_borders^⚠: Returns the number of pixels that should be removed from the four edges. Because of the way this data is stored, you have to pass the image size at the moment of the crop operation to compute the cropped border sizes.
heif_item_get_property_transform_mirror^⚠: Will return ‘heif_transform_mirror_direction_invalid’ in case of error.
heif_item_get_property_transform_rotation_ccw^⚠: Returns only 0, 90, 180, or 270 angle values. Returns -1 in case of error (but it will only return an error in case of wrong usage).
heif_item_get_property_type^⚠
heif_item_get_property_user_description^⚠: Get the “udes” user description property content. Undefined strings are returned as empty strings.
heif_item_get_property_uuid_type^⚠: Get the extended type for an extended “uuid” box.
heif_item_get_transformation_properties^⚠: Returns all transformative properties in the correct order. This includes “irot”, “imir”, “clap”. The number of properties is returned, which are not more than ‘count’ if (out_list != nullptr). By setting out_list==nullptr, you can query the number of properties, ‘count’ is ignored.
heif_item_get_uri_item_uri_type^⚠: Gets the item_uri_type for an item.
heif_item_is_item_hidden^⚠
heif_item_set_item_name^⚠
heif_item_set_property_tai_clock_info^⚠: Creates a new clock info property if it doesn’t exist yet. You can only add one tai_clock_info to an image.
heif_item_set_property_tai_timestamp^⚠: Creates a new TAI timestamp property if it doesn’t exist yet. You can only add one tai_timestamp to an image.
heif_list_compatible_brands^⚠: 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()’. The number of entries is returned in out_size.
heif_load_plugin^⚠
heif_load_plugins^⚠
heif_main_brand^⚠: input data should be at least 12 bytes DEPRECATED, use heif_read_main_brand() instead
heif_mastering_display_colour_volume_decode^⚠: Converts the internal numeric representation of heif_mastering_display_colour_volume to the normalized values, collected in heif_decoded_mastering_display_colour_volume. Values that are out-of-range are decoded to 0, indicating an undefined value (as specified in ISO/IEC 23008-2).
heif_nclx_color_profile_alloc^⚠: Returned color profile has ‘version’ field set to the maximum allowed. Do not fill values for higher versions as these might be outside the allocated structure size. May return NULL.
heif_nclx_color_profile_free^⚠
heif_nclx_color_profile_set_color_primaries^⚠
heif_nclx_color_profile_set_matrix_coefficients^⚠
heif_nclx_color_profile_set_transfer_characteristics^⚠
heif_property_user_description_release^⚠: Release all strings and the object itself. Only call for objects that you received from heif_item_get_property_user_description().
heif_raw_sequence_sample_alloc^⚠: Allocate a new heif_raw_sequence_sample object. Free with heif_raw_sequence_sample_release().
heif_raw_sequence_sample_get_data^⚠: Get a pointer to the data of the (metadata) sample. The data pointer stays valid until the heif_raw_sequence_sample object is released.
heif_raw_sequence_sample_get_data_size^⚠: Return the size of the raw data contained in the sample. This is the same as returned through the ‘out_array_size’ parameter of ‘heif_raw_sequence_sample_get_data()’.
heif_raw_sequence_sample_get_duration^⚠: Get the sample duration in clock ticks of this track. Make sure to use the timescale of the track and not the timescale of the total sequence.
heif_raw_sequence_sample_get_gimi_sample_content_id^⚠: Get the GIMI content ID stored in the metadata sample. If there is no content ID, NULL is returned. @return
heif_raw_sequence_sample_get_tai_timestamp^⚠: Get the TAI timestamp of the (metadata) sample. If there is no timestamp assigned to it, NULL will be returned.
heif_raw_sequence_sample_has_tai_timestamp^⚠: Returns whether the raw (metadata) sample has a TAI timestamp attached to it (stored as SAI).
heif_raw_sequence_sample_release^⚠: Release a heif_raw_sequence_sample object. You may pass NULL.
heif_raw_sequence_sample_set_data^⚠: Set the raw sequence sample data.
heif_raw_sequence_sample_set_duration^⚠: Set the sample duration in track timescale units.
heif_raw_sequence_sample_set_gimi_sample_content_id^⚠: Set the GIMI content ID for a (metadata) sample. It will be stored as SAI. When passing NULL, a previously set ID will be removed.
heif_raw_sequence_sample_set_tai_timestamp^⚠: Set the TAI timestamp for a raw sequence sample. The timestamp will be copied, you can release it after calling this function.
heif_read_main_brand^⚠: input data should be at least 12 bytes
heif_read_minor_version_brand^⚠: input data should be at least 16 bytes
heif_region_get_ellipse^⚠: Get the values for an ellipse region.
heif_region_get_ellipse_transformed^⚠: Get the transformed values for an ellipse region.
heif_region_get_inline_mask_data^⚠: Get data for an inline mask region.
heif_region_get_inline_mask_data_len^⚠: Get the length of the data in an inline mask region.
heif_region_get_mask_image^⚠: Get a mask region image.
heif_region_get_point^⚠: Get the values for a point region.
heif_region_get_point_transformed^⚠: Get the transformed values for a point region.
heif_region_get_polygon_num_points^⚠: Get the number of points in a polygon.
heif_region_get_polygon_points^⚠: Get the points in a polygon region.
heif_region_get_polygon_points_transformed^⚠: Get the transformed points in a polygon region.
heif_region_get_polyline_num_points^⚠: Get the number of points in a polyline.
heif_region_get_polyline_points^⚠: Get the points in a polyline region.
heif_region_get_polyline_points_transformed^⚠: Get the transformed points in a polyline region.
heif_region_get_rectangle^⚠: Get the values for a rectangle region.
heif_region_get_rectangle_transformed^⚠: Get the transformed values for a rectangle region.
heif_region_get_referenced_mask_ID^⚠: Get a referenced item mask region.
heif_region_get_type^⚠: Get the region type for a specified region.
heif_region_item_add_region_ellipse^⚠: Add a ellipse region to the region item.
heif_region_item_add_region_inline_mask^⚠: Add an inline mask region image to the region item.
heif_region_item_add_region_inline_mask_data^⚠: Add an inline mask region to the region item.
heif_region_item_add_region_point^⚠: Add a point region to the region item.
heif_region_item_add_region_polygon^⚠: Add a polygon region to the region item.
heif_region_item_add_region_polyline^⚠: Add a polyline region to the region item.
heif_region_item_add_region_rectangle^⚠: Add a rectangle region to the region item.
heif_region_item_add_region_referenced_mask^⚠: Add a referenced mask region to the region item.
heif_region_item_get_id^⚠: Get the item identifier for a region item.
heif_region_item_get_list_of_regions^⚠: Get the regions that are part of a region item.
heif_region_item_get_number_of_regions^⚠: Get the number of regions within a region item.
heif_region_item_get_reference_size^⚠: Get the reference size for a region item.
heif_region_item_release^⚠: Release a region item.
heif_region_release^⚠: Release a region.
heif_region_release_many^⚠: Release a list of regions.
heif_register_decoder^⚠: DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead.
heif_register_decoder_plugin^⚠
heif_register_encoder_plugin^⚠
heif_release_item_data^⚠: Free the item data.
heif_release_item_references^⚠
heif_sequence_encoding_options_alloc^⚠
heif_sequence_encoding_options_release^⚠
heif_string_release^⚠: Free a string returned by libheif in various API functions. You may pass NULL.
heif_tai_clock_info_alloc^⚠: Allocate a new heif_tai_clock_info object and initialize with default values.
heif_tai_clock_info_copy^⚠: Copies the source object into the destination object. Only the fields that are present in both objects are copied. The version property has to be set in both structs.
heif_tai_clock_info_release^⚠
heif_tai_timestamp_packet_alloc^⚠: Allocate a new heif_tai_timestamp_packet object and initialize with default values.
heif_tai_timestamp_packet_copy^⚠: Copies the source object into the destination object. Only the fields that are present in both objects are copied. The version property has to be set in both structs.
heif_tai_timestamp_packet_release^⚠
heif_track_add_raw_sequence_sample^⚠: Add a raw sequence sample (usually a metadata sample) to the (metadata) track.
heif_track_add_reference_to_track^⚠: Add a reference between tracks. ‘reference_type’ can be one of the four-cc codes listed in heif_track_reference_type or any other type.
heif_track_decode_next_image^⚠: Decode the next image in the passed sequence track. If there is no more image in the sequence, heif_error_End_of_sequence is returned. The parameters colorspace, chroma and options are similar to heif_decode_image(). If you want to let libheif decide the output colorspace and chroma, set these parameters to heif_colorspace_undefined / heif_chroma_undefined. Usually, libheif will return the image in the input colorspace, but it may also modify it for example when it has to rotate the image. If you want to get the image in a specific colorspace/chroma format, you can specify this and libheif will convert the image to match this format.
heif_track_encode_sequence_image^⚠: Encode the image into a visual track. If the passed track is no visual track, an error will be returned.
heif_track_find_referring_tracks^⚠: Find tracks that are referring to the current track through the passed reference_type. The found track IDs will be filled into the passed array, but no more than array_size entries will be filled.
heif_track_get_gimi_track_content_id^⚠: Get the GIMI content ID for the track (as a whole). If there is no content ID, nullptr is returned.
heif_track_get_id^⚠: Get the ID of the passed track. The track ID will never be 0.
heif_track_get_image_resolution^⚠: Get the image resolution of the track. If the passed track is no visual track, an error is returned.
heif_track_get_next_raw_sequence_sample^⚠: Get the next raw sample from the (metadata) sequence track. You have to free the returned sample with heif_raw_sequence_sample_release().
heif_track_get_number_of_sample_aux_infos^⚠: Returns how many different types of sample auxiliary data units are assigned to this track’s samples.
heif_track_get_number_of_track_reference_of_type^⚠: Get the number of references of the passed type.
heif_track_get_number_of_track_reference_types^⚠: Return the number of different reference types used in this track’s tref box.
heif_track_get_references_from_track^⚠: List the track ids this track points to with the passed reference type. The passed array must have heif_track_get_number_of_track_reference_of_type() entries.
heif_track_get_sample_aux_info_types^⚠: Get get the list of sample auxiliary data types used in the track. The passed array has to have heif_track_get_number_of_sample_aux_infos() entries.
heif_track_get_sample_entry_type_of_first_cluster^⚠: Get the “sample entry type” of the first sample sample cluster in the track. In the case of metadata tracks, this will usually be “urim” for “URI Meta Sample Entry”. The exact URI can then be obtained with ‘heif_track_get_urim_sample_entry_uri_of_first_cluster’.
heif_track_get_tai_clock_info_of_first_cluster^⚠: Returns the TAI clock info of the track. If there is no TAI clock info, NULL is returned. You should NOT free the returned heif_tai_clock_info. The structure stays valid until the heif_track object is released.
heif_track_get_timescale^⚠: Get the timescale (clock ticks per second) for this track. Note that this can be different from the timescale used at sequence level.
heif_track_get_track_handler_type^⚠: Get the four-cc track handler type. Typical codes are “vide” for video sequences, “pict” for image sequences, “meta” for metadata tracks. These are defined in heif_track_type_4cc, but files may also contain other types.
heif_track_get_track_reference_types^⚠: List the reference types used in this track. The passed array must have heif_track_get_number_of_track_reference_types() entries.
heif_track_get_urim_sample_entry_uri_of_first_cluster^⚠: Get the URI of the first sample cluster in an ‘urim’ track. Only call this for tracks with ‘urim’ sample entry types. It will return an error otherwise.
heif_track_options_alloc^⚠: Allocate track options object that is required to set options for a new track. When you create a new track, you can also pass a NULL heif_track_options pointer, in which case the default options are used.
heif_track_options_enable_sample_gimi_content_ids^⚠
heif_track_options_enable_sample_tai_timestamps^⚠
heif_track_options_release^⚠
heif_track_options_set_gimi_track_id^⚠: Set the GIMI format track ID string. If NULL is passed, no track ID is saved. @param track_id
heif_track_options_set_interleaved_sample_aux_infos^⚠: Set whether the aux-info data should be stored interleaved with the sequence samples. Default is: false.
heif_track_options_set_timescale^⚠: Set the track specific timescale. This is the number of clock ticks per second. The default is 90,000 Hz. @param timescale
heif_track_release^⚠: Free a heif_track object received from libheif. Passing NULL is ok.
heif_unload_plugin^⚠

Type Aliases§

heif_alpha_composition_mode
heif_brand: DEPRECATED, use heif_brand2 and the heif_brand2_* constants instead
heif_brand2
heif_channel
heif_chroma
heif_chroma_downsampling_algorithm
heif_chroma_upsampling_algorithm
heif_color_primaries
heif_color_profile_type: ———————–– color profiles ———————––
heif_colorspace
heif_compression_format: libheif known compression formats.
heif_depth_representation_type
heif_encoder_parameter_type
heif_entity_group_id: ———————–– entity groups ————————
heif_error_code
heif_filetype_result: ========================= file type check ======================
heif_item_id
heif_item_property_type: ———————–– item properties ———————––
heif_matrix_coefficients
heif_metadata_compression
heif_orientation: The orientation values are defined equal to the EXIF Orientation tag.
heif_plugin_type: — Plugins are currently only supported on Unix platforms.
heif_progress_step
heif_property_id
heif_reader_grow_status
heif_region_type: Region type.
heif_sample_aux_info_presence: Specifies whether a ‘sample auxiliary info’ is stored with the samples. The difference between heif_sample_aux_info_presence_optional and heif_sample_aux_info_presence_mandatory is that heif_sample_aux_info_presence_mandatory will throw an error if the data is missing when writing a sample.
heif_suberror_code
heif_track_reference_type: — track references
heif_track_type
heif_track_type_4cc
heif_transfer_characteristics
heif_transform_mirror_direction

Crate libheif_sysCopy item path