Add experimental support for HEIF images #1105

Requires a custom, globally-installed libvips compiled with libheif

docs/api-input.md

@@ -34,8 +34,9 @@ A `Promise` is returned when `callback` is not provided.
 -   `density`: Number of pixels per inch (DPI), if present
 -   `chromaSubsampling`: String containing JPEG chroma subsampling, `4:2:0` or `4:4:4` for RGB, `4:2:0:4` or `4:4:4:4` for CMYK
 -   `isProgressive`: Boolean indicating whether the image is interlaced using a progressive scan
--   `pages`: Number of pages/frames contained within the image, with support for TIFF, PDF, animated GIF and animated WebP
+-   `pages`: Number of pages/frames contained within the image, with support for TIFF, HEIF, PDF, animated GIF and animated WebP
 -   `pageHeight`: Number of pixels high each page in this PDF image will be.
+-   `pagePrimary`: Number of the primary page in a HEIF image
 -   `hasProfile`: Boolean indicating the presence of an embedded ICC profile
 -   `hasAlpha`: Boolean indicating the presence of an alpha transparency channel
 -   `orientation`: Number value of the EXIF Orientation header, if present

docs/api-output.md

@@ -232,6 +232,29 @@ sharp('input.svg')
   .then(info => { ... });
 ```
 
+-   Throws **[Error][3]** Invalid options
+
+Returns **Sharp** 
+
+## heif
+
+Use these HEIF options for output image.
+
+Support for HEIF (HEIC/AVIF) is experimental.
+Do not use this in production systems.
+
+Requires a custom, globally-installed libvips compiled with support for libheif.
+
+Most versions of libheif support only the patent-encumbered HEVC compression format.
+
+### Parameters
+
+-   `options` **[Object][5]?** output options
+    -   `options.quality` **[Number][8]** quality, integer 1-100 (optional, default `80`)
+    -   `options.compression` **[Boolean][6]** compression format: hevc, avc, jpeg, av1 (optional, default `'hevc'`)
+    -   `options.lossless` **[Boolean][6]** use lossless compression (optional, default `false`)
+
+
 -   Throws **[Error][3]** Invalid options
 
 Returns **Sharp** 

docs/changelog.md

@@ -8,6 +8,9 @@ Requires libvips v8.8.0.
 
 * Remove `overlayWith` previously deprecated in v0.22.0.
 
+* Add experimental support for HEIF images. Requires libvips compiled with libheif.
+  [#1105](https://github.com/lovell/sharp/issues/1105)
+
 * Add experimental support for Worker Threads.
   [#1558](https://github.com/lovell/sharp/issues/1558)