feat: added encodeToHDR related options for Apple ImageIO coder

This just forward the options, no extra logic

Author: dreampiggy

SDWebImage/Core/SDImageCoder.h

@@ -15,7 +15,7 @@ typedef NSString * SDImageCoderOption NS_STRING_ENUM;
 typedef NSDictionary<SDImageCoderOption, id> SDImageCoderOptions;
 typedef NSMutableDictionary<SDImageCoderOption, id> SDImageCoderMutableOptions;
 
-#pragma mark - Coder Options
+#pragma mark - Image Decoding Options
 // These options are for image decoding
 /**
  A Boolean value indicating whether to decode the first frame only for animated image during decoding. (NSNumber). If not provide, decode animated image if need.
@@ -96,7 +96,18 @@ FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeScaleDownL
  */
 FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeToHDR;
 
-// These options are for image encoding
+#pragma mark - Image Encoding Options
+/**
+ A NSUInteger value (NSNumber) to provide converting to HDR during encoding. Read the below carefully to choose the value.
+ @note 0 means SDR; 1 means ISO HDR (at least using 10 bits per components or above, supported by AVIF/HEIF/JPEG-XL); 2 means ISO Gain Map Image (may use 8 bits per components, supported AVIF/HEIF/JPEG-XL, as well as traditional JPEG)
+ @note Gain Map like a mask image with metadata, which contains the depth/bright information for each pixel (or smaller, 1/4 resolution), which used to convert between HDR and SDR.
+ @note If you use CIImage as HDR pipeline, you can export as CGImage for encoding. (But it's also recommanded to use CIImage's `JPEGRepresentationOfImage` or `HEIFRepresentationOfImage`)
+ @note Supported by iOS 18 and above when using ImageIO coder (third-party coder can support lower firmware)
+ Defaults to @(0), encoder will automatically convert SDR.
+ @note works for `SDImageCoder`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeToHDR;
+
 /**
  A Boolean value indicating whether to encode the first frame only for animated image during encoding. (NSNumber). If not provide, encode animated image if need.
  @note works for `SDImageCoder`.

SDWebImage/Core/SDImageCoder.m

@@ -18,6 +18,7 @@
 SDImageCoderOption const SDImageCoderDecodeScaleDownLimitBytes = @"decodeScaleDownLimitBytes";
 SDImageCoderOption const SDImageCoderDecodeToHDR = @"decodeToHDR";
 
+SDImageCoderOption const SDImageCoderEncodeToHDR = @"encodeToHDR";
 SDImageCoderOption const SDImageCoderEncodeFirstFrameOnly = @"encodeFirstFrameOnly";
 SDImageCoderOption const SDImageCoderEncodeCompressionQuality = @"encodeCompressionQuality";
 SDImageCoderOption const SDImageCoderEncodeBackgroundColor = @"encodeBackgroundColor";

SDWebImage/Core/SDImageIOAnimatedCoder.m

@@ -895,6 +895,21 @@ - (NSData *)encodedDataWithFrames:(NSArray<SDImageFrame *> *)frames loopCount:(N
         maxPixelSize = maxPixelSizeValue.CGSizeValue;
 #endif
     }
+    // HDR Encoding
+    NSUInteger encodeToHDR = 0;
+    if (options[SDImageCoderEncodeToHDR]) {
+        encodeToHDR = [options[SDImageCoderEncodeToHDR] unsignedIntegerValue];
+    }
+    if (@available(macOS 15, iOS 18, tvOS 18, watchOS 11, *)) {
+        if (encodeToHDR == 1) {
+            properties[(__bridge NSString *)kCGImageDestinationEncodeRequest] = (__bridge NSString *)kCGImageDestinationEncodeToISOHDR;
+        } else if (encodeToHDR == 2) {
+            properties[(__bridge NSString *)kCGImageDestinationEncodeRequest] = (__bridge NSString *)kCGImageDestinationEncodeToISOGainmap;
+        } else {
+            properties[(__bridge NSString *)kCGImageDestinationEncodeRequest] = (__bridge NSString *)kCGImageDestinationEncodeToSDR;
+        }
+    }
+    
     CGFloat pixelWidth = (CGFloat)CGImageGetWidth(imageRef);
     CGFloat pixelHeight = (CGFloat)CGImageGetHeight(imageRef);
     CGFloat finalPixelSize = 0;

SDWebImage/Core/SDImageIOCoder.m

@@ -381,6 +381,21 @@ - (NSData *)encodedDataWithImage:(UIImage *)image format:(SDImageFormat)format o
         maxPixelSize = maxPixelSizeValue.CGSizeValue;
 #endif
     }
+    // HDR Encoding
+    NSUInteger encodeToHDR = 0;
+    if (options[SDImageCoderEncodeToHDR]) {
+        encodeToHDR = [options[SDImageCoderEncodeToHDR] unsignedIntegerValue];
+    }
+    if (@available(macOS 15, iOS 18, tvOS 18, watchOS 11, *)) {
+        if (encodeToHDR == 1) {
+            properties[(__bridge NSString *)kCGImageDestinationEncodeRequest] = (__bridge NSString *)kCGImageDestinationEncodeToISOHDR;
+        } else if (encodeToHDR == 2) {
+            properties[(__bridge NSString *)kCGImageDestinationEncodeRequest] = (__bridge NSString *)kCGImageDestinationEncodeToISOGainmap;
+        } else {
+            properties[(__bridge NSString *)kCGImageDestinationEncodeRequest] = (__bridge NSString *)kCGImageDestinationEncodeToSDR;
+        }
+    }
+    
     CGFloat pixelWidth = (CGFloat)CGImageGetWidth(imageRef);
     CGFloat pixelHeight = (CGFloat)CGImageGetHeight(imageRef);
     CGFloat finalPixelSize = 0;