Add withGainMap to process HDR JPEGs with embedded gain map #4314

docs/src/content/docs/api-input.md

@@ -50,6 +50,7 @@ A `Promise` is returned when `callback` is not provided.
 - `tifftagPhotoshop`: Buffer containing raw TIFFTAG_PHOTOSHOP data, if present
 - `formatMagick`: String containing format for images loaded via *magick
 - `comments`: Array of keyword/text pairs representing PNG text blocks, if present.
+- `gainMap.image`: HDR gain map, if present, as compressed JPEG image.
 
 
 

docs/src/content/docs/api-output.md

@@ -250,6 +250,27 @@ const outputWithP3 = await sharp(input)
 ```
 
 
+## withGainMap
+> withGainMap() ⇒ <code>Sharp</code>
+
+If the input contains gain map metadata, use it to convert the main image to HDR (High Dynamic Range) before further processing.
+The input gain map is discarded.
+
+If the output is JPEG, generate and attach a new ISO 21496-1 gain map.
+JPEG output options other than `quality` are ignored.
+
+This feature is experimental and the API may change.
+
+
+**Since**: 0.35.0  
+**Example**  
+```js
+const outputWithGainMap = await sharp(inputWithGainMap)
+  .withGainMap()
+  .toBuffer();
+```
+
+
 ## keepXmp
 > keepXmp() ⇒ <code>Sharp</code>
 

docs/src/content/docs/changelog/v0.35.0.md

@@ -6,3 +6,6 @@ slug: changelog/v0.35.0
 * Upgrade to libvips v8.18.0 for upstream bug fixes.
 
 * Drop support for Node.js 18, now requires Node.js >= 20.9.0.
+
+* Add `withGainMap` to process HDR JPEG images with embedded gain maps.
+  [#4314](https://github.com/lovell/sharp/issues/4314)