- Added features v1_17 and v1_18 to choose a minimal

  version of supported `libheif`.
- Added feature `embedded-libheif` to compile and then link statically
  the embedded sources of `libheif` from the `libheif-sys` crate.
- **BREAKING**: Features `compile-libheif`, `embedded-libheif-plugins` and
  `use-bindgen` were removed.
- `libheif-sys` updated to version 4.0.0+1.19.7.
- `vcpkg` updated to version 2025.03.19.

Author: Cykooz

.github/workflows/check_and_test.yaml

@@ -44,10 +44,15 @@ jobs:
         with:
           cache-on-failure: "true"
 
-      - name: Run tests
+      - name: Run tests for v1.17
         run: |
-          cargo check -p libheif-rs --features embedded-libheif-plugins
-          cargo test --features embedded-libheif-plugins
+          cargo check -p libheif-rs --features embedded-libheif,v1_17
+          cargo test --features embedded-libheif,v1_17
+
+      - name: Run tests for v1.18
+        run: |
+          cargo check -p libheif-rs --features embedded-libheif,v1_18
+          cargo test --features embedded-libheif,v1_18
 
 
 #  run_tests_on_windows:

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## [Unreleased] - ReleaseDate
+
+### Added
+
+- Added features `v1_17` and `v1_18` to choose a minimal
+  version of supported `libheif`.
+- Added feature `embedded-libheif` to compile and then link statically
+  the embedded sources of `libheif` from the `libheif-sys` crate.
+
+### Changes
+
+- **BREAKING**: Features `compile-libheif`, `embedded-libheif-plugins` and
+  `use-bindgen` were removed.
+- `libheif-sys` updated to version 4.0.0+1.19.7.
+- `vcpkg` updated to version 2025.03.19.
+
 ## [1.1.0] - 2025-01-23
 
 ### Added

Cargo.toml

@@ -12,23 +12,24 @@ documentation = "https://docs.rs/crate/libheif-rs"
 
 
 [dependencies]
+cfg-if = "1.0"
 enumn = "0.1.14"
 four-cc = "0.4"
-libc = "0.2.169"
-libheif-sys = { version = "3.1", default-features = false }
+libc = "0.2.171"
+libheif-sys = "4.0"
 
 
 [features]
-compile-libheif = ["libheif-sys/compile-libheif"]
-embedded-libheif-plugins = ["libheif-sys/embedded-libheif-plugins"]
-# Use bindgen to generate bindings for libheif,
-# instead using of pre-generated bindings.rs.
-use-bindgen = ["libheif-sys/use-bindgen"]
+default = ["latest"]
+v1_17 = ["libheif-sys/v1_17"]
+v1_18 = ["v1_17", "libheif-sys/v1_18"]
+latest = ["v1_18"]
+embedded-libheif = ["libheif-sys/embedded-libheif"]
 
 
 [dev-dependencies]
 kamadak-exif = "0.6.1"
-tempfile = "3.15"
+tempfile = "3.19"
 
 
 [profile.release]
@@ -42,7 +43,7 @@ codegen-units = 1
 
 [package.metadata.vcpkg]
 git = "https://github.com/microsoft/vcpkg"
-tag = "2025.01.13"
+tag = "2025.03.19"
 dependencies = ["libheif"]
 
 

README.md

@@ -1,16 +1,47 @@
 # libheif-rs
 
-Safe wrapper around the libheif-sys crate for parsing heif/heic files.
+Safe wrapper around the [libheif-sys](https://github.com/Cykooz/libheif-sys)
+crate for parsing heif/heic files.
 
 [CHANGELOG](https://github.com/Cykooz/libheif-rs/blob/master/CHANGELOG.md)
 
 ## System dependencies
 
-- `libheif-dev` >= 1.18.0
+- `libheif-dev` >= 1.17.0
+
+## Minimal supported libheif version
+
+Minimal supported version of `libheif` library is 1.17.
+But there are some functions in the crate that require a newer version of
+`libheif` library.
+
+You may specify a minimal version of `libheif` library that is required for you.
+To do this, enable the corresponding feature `v1_17` or `v1_18`.
+
+Example:
+
+```toml
+[dependencies]
+libheif = { version = "2.0", default-features = false, features = ["v1_17"] }
+```
+
+There is also the `latest` feature. It always corresponds to
+the maximal supported by the crate version of `libheif` API.
+This feature is enabled by default.
 
 ### Linux
 
-Crate `libheif-sys` uses `pkg-confing` to find installed `libheif`.
+Crate `libheif-sys` uses `pkg-confing` command to find installed `libheif`.
+
+You can also enable `embedded-libheif` feature to compile `libheif` from
+embedded into `libheif-sys` crate sources and then link it statically.
+
+<div class="warning">
+
+Note: Static linked version of `libheif` doesn't have statically linked
+it dependencies, such as `libde256`, `libaom` and other.
+
+</div>
 
 ### Windows
 
@@ -29,7 +60,7 @@ packages from scratch. It merges package requirements specified in
 the `Cargo.toml` of crates in the dependency tree.
 
 PS: I tried build `libheif` for Windows, but `libheif-rs` tests
-filed because `libheif` doesn't have any encoder plugins available.
+failed because `libheif` for Windows doesn't have any encoder plugins available.
 
 ## Examples
 

rustfmt.toml

@@ -0,0 +1,4 @@
+unstable_features = true
+
+imports_granularity = "Module"
+group_imports = "StdExternalCrate"

src/context.rs

@@ -1,7 +1,7 @@
-use std::ffi;
+#[cfg(feature = "v1_18")]
 use std::num::NonZeroU16;
 use std::os::raw::c_void;
-use std::ptr;
+use std::{ffi, ptr};
 
 use four_cc::FourCC;
 use libheif_sys as lh;
@@ -71,7 +71,8 @@ impl HeifContext<'static> {
 
     /// # Safety
     ///
-    /// The given pointer must be valid.  
+    /// The given pointer must be valid.
+    #[cfg(feature = "v1_18")]
     pub(crate) unsafe fn from_ptr(ctx: *mut lh::heif_context) -> HeifContext<'static> {
         HeifContext {
             inner: ctx,
@@ -80,7 +81,7 @@ impl HeifContext<'static> {
     }
 }
 
-impl<'a> HeifContext<'a> {
+impl HeifContext<'_> {
     /// Create a new context from bytes.
     ///
     /// The provided memory buffer is not copied.
@@ -259,6 +260,8 @@ impl<'a> HeifContext<'a> {
     /// * `encoding_options` - Optional, may be None.
     ///
     /// Returns an error if `tiles` slice is empty.
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     pub fn encode_grid(
         &mut self,
         tiles: &[Image],
@@ -385,10 +388,10 @@ impl<'a> HeifContext<'a> {
     }
 }
 
-impl<'a> Drop for HeifContext<'a> {
+impl Drop for HeifContext<'_> {
     fn drop(&mut self) {
         unsafe { lh::heif_context_free(self.inner) };
     }
 }
 
-unsafe impl<'a> Send for HeifContext<'a> {}
+unsafe impl Send for HeifContext<'_> {}

src/encoder.rs

@@ -39,6 +39,8 @@ pub enum CompressionFormat {
     Uncompressed = lh::heif_compression_format_heif_compression_uncompressed as _,
     /// Rust equivalent of [lh::heif_compression_format_heif_compression_mask]
     Mask = lh::heif_compression_format_heif_compression_mask as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     /// Rust equivalent of [lh::heif_compression_format_heif_compression_HTJ2K]
     HtJ2k = lh::heif_compression_format_heif_compression_HTJ2K as _,
 }

src/errors.rs

@@ -105,19 +105,39 @@ pub enum HeifErrorSubCode {
     EncoderEncoding = lh::heif_suberror_code_heif_suberror_Encoder_encoding as _,
     EncoderCleanup = lh::heif_suberror_code_heif_suberror_Encoder_cleanup as _,
     TooManyRegions = lh::heif_suberror_code_heif_suberror_Too_many_regions as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     NoIspeProperty = lh::heif_suberror_code_heif_suberror_No_ispe_property as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     CameraIntrinsicMatrixUndefined =
         lh::heif_suberror_code_heif_suberror_Camera_intrinsic_matrix_undefined as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     CameraExtrinsicMatrixUndefined =
         lh::heif_suberror_code_heif_suberror_Camera_extrinsic_matrix_undefined as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     InvalidJ2kCodeStream = lh::heif_suberror_code_heif_suberror_Invalid_J2K_codestream as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     NoVvccBox = lh::heif_suberror_code_heif_suberror_No_vvcC_box as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     NoIcbrBox = lh::heif_suberror_code_heif_suberror_No_icbr_box as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     DecompressionInvalidData = lh::heif_suberror_code_heif_suberror_Decompression_invalid_data as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     CompressionInitialisationError =
         lh::heif_suberror_code_heif_suberror_Compression_initialisation_error as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     UnsupportedGenericCompressionMethod =
         lh::heif_suberror_code_heif_suberror_Unsupported_generic_compression_method as _,
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     NoMatchingDecoderInstalled =
         lh::heif_suberror_code_heif_suberror_No_matching_decoder_installed as _,
     /// This value is used when library `libheif` returns unknown value of error sub-code.

src/image_handle.rs

@@ -1,17 +1,24 @@
-use four_cc::FourCC;
-use libheif_sys as lh;
 use std::ffi::CString;
 use std::mem::MaybeUninit;
 use std::os::raw::c_char;
 use std::ptr;
 
-use crate::regions::RegionItem;
+use four_cc::FourCC;
+use libheif_sys as lh;
+
 use crate::utils::cstr_to_str;
 use crate::{
-    ColorProfileNCLX, ColorProfileRaw, ColorProfileType, ColorSpace, HeifContext, HeifError,
-    HeifErrorCode, HeifErrorSubCode, ImageMetadata, Result,
+    ColorProfileNCLX, ColorProfileRaw, ColorProfileType, ColorSpace, HeifError, HeifErrorCode,
+    HeifErrorSubCode, ImageMetadata, Result,
 };
 
+cfg_if::cfg_if! {
+    if #[cfg(feature = "v1_18")] {
+        use crate::regions::RegionItem;
+        use crate::HeifContext;
+    }
+}
+
 /// Encoded image.
 pub struct ImageHandle {
     pub(crate) inner: *mut lh::heif_image_handle,
@@ -24,6 +31,7 @@ impl ImageHandle {
         ImageHandle { inner: handle }
     }
 
+    #[cfg(feature = "v1_18")]
     fn context(&self) -> HeifContext {
         unsafe { HeifContext::from_ptr(lh::heif_image_handle_get_context(self.inner)) }
     }
@@ -357,6 +365,8 @@ impl ImageHandle {
     ///
     /// The concept is to add the region item, then add one or more regions
     /// to the region item.
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     pub fn add_region_item(
         &mut self,
         reference_width: u32,
@@ -380,6 +390,8 @@ impl ImageHandle {
         Ok(RegionItem::new(item_ptr))
     }
 
+    #[cfg(feature = "v1_18")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
     /// Get the region items attached to the image.
     pub fn region_items(&self) -> Vec<RegionItem> {
         let num_items = unsafe { lh::heif_image_handle_get_number_of_region_items(self.inner) };

src/lib.rs

@@ -24,5 +24,7 @@ mod image;
 mod image_handle;
 mod metadata;
 mod reader;
+#[cfg(feature = "v1_18")]
+#[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
 pub mod regions;
 mod utils;