feat: Added SDImageHDRType enum, to make it more standard instead of raw int value 0/1/2

Author: dreampiggy

SDWebImage/Core/SDImageCoder.h

@@ -89,7 +89,7 @@ FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeUseLazyDec
 FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeScaleDownLimitBytes;
 
 /**
- A Boolean value (NSNumber) to provide converting to HDR during decoding. Currently if number is 0, use SDR, else use HDR. But we may extend this option to use `NSUInteger` in the future (means, think this options as int number, but not actual boolean)
+ A Boolean (`SDImageHDRType.rawValue`) value (stored inside NSNumber) to provide converting to HDR during decoding. Currently if number is 0 (`SDImageHDRTypeSDR`), use SDR, else use HDR. But we may extend this option to represent `SDImageHDRType` all cases in the future (means, think this options as uint number, but not actual boolean)
  @note Supported by iOS 17 and above when using ImageIO coder (third-party coder can support lower firmware)
  Defaults to @(NO), decoder will automatically convert SDR.
  @note works for `SDImageCoder`
@@ -98,9 +98,9 @@ FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeToHDR;
 
 #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 HDR (may use 8 bits per components, supported by 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.
+ A NSUInteger (`SDImageHDRType.rawValue`) value (stored inside NSNumber) to provide converting to HDR during encoding. Read the below carefully to choose the value.
+ @note 0(`SDImageHDRTypeSDR`) means SDR; 1(`SDImageHDRTypeISOHDR`) means ISO HDR (at least using 10 bits per components or above, supported by AVIF/HEIF/JPEG-XL); 2(`SDImageHDRTypeISOGainMap`) means ISO Gain Map HDR (may use 8 bits per components, supported by 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 pixels (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.

SDWebImage/Core/SDImageCoderHelper.h

@@ -33,6 +33,17 @@ typedef NS_ENUM(NSUInteger, SDImageForceDecodePolicy) {
     SDImageForceDecodePolicyAlways
 };
 
+/// These enum is used to represent the High Dynamic Range type during image encoding/decoding.
+/// There are alao other HDR type in history before ISO Standard (ISO 21496-1), including Google and Apple's old OSs captured photos, but which is non-standard and we do not support.
+typedef NS_ENUM(NSUInteger, SDImageHDRType) {
+    /// SDR, mostly only 8 bits color per components, RGBA8
+    SDImageHDRTypeSDR = 0,
+    /// ISO HDR (supported by modern format only, like HEIF/AVIF/JPEG-XL)
+    SDImageHDRTypeISOHDR = 1,
+    /// ISO Gain Map based HDR (supported by nearly all format, including tranditional JPEG, which stored the gain map into XMP)
+    SDImageHDRTypeISOGainMap = 2,
+};
+
 /// Byte alignment the bytes size with alignment
 /// - Parameters:
 ///   - size: The bytes size

SDWebImage/Core/SDImageIOAnimatedCoder.m

@@ -919,9 +919,9 @@ - (NSData *)encodedDataWithFrames:(NSArray<SDImageFrame *> *)frames loopCount:(N
         encodeToHDR = [options[SDImageCoderEncodeToHDR] unsignedIntegerValue];
     }
     if (@available(macOS 15, iOS 18, tvOS 18, watchOS 11, *)) {
-        if (encodeToHDR == 1) {
+        if (encodeToHDR == SDImageHDRTypeISOHDR) {
             properties[kSDCGImageDestinationEncodeRequest] = kSDCGImageDestinationEncodeToISOHDR;
-        } else if (encodeToHDR == 2) {
+        } else if (encodeToHDR == SDImageHDRTypeISOGainMap) {
             properties[kSDCGImageDestinationEncodeRequest] = kSDCGImageDestinationEncodeToISOGainmap;
         } else {
             properties[kSDCGImageDestinationEncodeRequest] = kSDCGImageDestinationEncodeToSDR;

SDWebImage/Core/SDImageIOCoder.m

@@ -405,9 +405,9 @@ - (NSData *)encodedDataWithImage:(UIImage *)image format:(SDImageFormat)format o
         encodeToHDR = [options[SDImageCoderEncodeToHDR] unsignedIntegerValue];
     }
     if (@available(macOS 15, iOS 18, tvOS 18, watchOS 11, *)) {
-        if (encodeToHDR == 1) {
+        if (encodeToHDR == SDImageHDRTypeISOHDR) {
             properties[kSDCGImageDestinationEncodeRequest] = kSDCGImageDestinationEncodeToISOHDR;
-        } else if (encodeToHDR == 2) {
+        } else if (encodeToHDR == SDImageHDRTypeISOGainMap) {
             properties[kSDCGImageDestinationEncodeRequest] = kSDCGImageDestinationEncodeToISOGainmap;
         } else {
             properties[kSDCGImageDestinationEncodeRequest] = kSDCGImageDestinationEncodeToSDR;

Tests/Tests/SDImageCoderTests.m

@@ -704,7 +704,7 @@ - (void)test33ThatGainMapHDRDecodeWorks {
 }
 
 - (void)test34ThatHDREncodeWorks {
-    // FIXME: Encoding need iOS 18+/macOS 15+
+    // FIXME: Encoding need iOS 18+/macOS 15+, No simulator
     // GitHub Action virtualization framework contains issue for Gain Map HDR convert:
     if (SDTestCase.isCI) {
         return;
@@ -720,7 +720,7 @@ - (void)test34ThatHDREncodeWorks {
             UIImage *HDRImage = [SDImageIOCoder.sharedCoder decodedImageWithData:data options:@{SDImageCoderDecodeToHDR : @(YES)}];
             float headroom = CGImageGetContentHeadroom(HDRImage.CGImage);
             expect(headroom).beGreaterThan(1);
-            
+#if !TARGET_OS_SIMULATOR
             NSArray *encodeFormats = @[@"heic", @"jpeg"];
             for (NSString *encodeFormat in encodeFormats) {
                 NSLog(@"Testing HDR encodde from original : %@ to %@", decodeFormat, encodeFormat);
@@ -730,9 +730,9 @@ - (void)test34ThatHDREncodeWorks {
                     // JPEG with XMP Gain Map
                     format = SDImageFormatJPEG;
                 }
-                NSData *SDRData = [SDImageIOCoder.sharedCoder encodedDataWithImage:HDRImage format:format options:@{SDImageCoderEncodeToHDR : @(0)}];
-                NSData *HDRData = [SDImageIOCoder.sharedCoder encodedDataWithImage:HDRImage format:format options:@{SDImageCoderEncodeToHDR : @(1)}];
-                NSData *HDRGainMapData = [SDImageIOCoder.sharedCoder encodedDataWithImage:HDRImage format:format options:@{SDImageCoderEncodeToHDR : @(2)}];
+                NSData *SDRData = [SDImageIOCoder.sharedCoder encodedDataWithImage:HDRImage format:format options:@{SDImageCoderEncodeToHDR : @(SDImageHDRTypeSDR)}];
+                NSData *HDRData = [SDImageIOCoder.sharedCoder encodedDataWithImage:HDRImage format:format options:@{SDImageCoderEncodeToHDR : @(SDImageHDRTypeISOHDR)}];
+                NSData *HDRGainMapData = [SDImageIOCoder.sharedCoder encodedDataWithImage:HDRImage format:format options:@{SDImageCoderEncodeToHDR : @(SDImageHDRTypeISOGainMap)}];
                 expect(SDRData).notTo.beNil();
                 expect(HDRData).notTo.beNil();
                 expect(HDRGainMapData).notTo.beNil();
@@ -756,6 +756,7 @@ - (void)test34ThatHDREncodeWorks {
                 expect(headroom).equal(1);
                 CFRelease(source);
             }
+#endif
         }
     }
 }