@octane-xplat/nativescript-mason-core 0.0.1 → 1.0.0-beta.1

package/platforms/ios/include/SDWebImage/SDImageCoder.h

@@ -0,0 +1,347 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import <Foundation/Foundation.h>
+#import "SDWebImageCompat.h"
+#import "NSData+ImageContentType.h"
+#import "SDImageFrame.h"
+
+/// Image Decoding/Encoding Options
+typedef NSString * SDImageCoderOption NS_STRING_ENUM;
+typedef NSDictionary<SDImageCoderOption, id> SDImageCoderOptions;
+typedef NSMutableDictionary<SDImageCoderOption, id> SDImageCoderMutableOptions;
+
+#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.
+ @note works for `SDImageCoder`.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeFirstFrameOnly;
+
+/**
+ A CGFloat value which is greater than or equal to 1.0. This value specify the image scale factor for decoding. If not provide, use 1.0. (NSNumber)
+ @note works for `SDImageCoder`, `SDProgressiveImageCoder`, `SDAnimatedImageCoder`.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeScaleFactor;
+
+/**
+ A Boolean value indicating whether to keep the original aspect ratio when generating thumbnail images (or bitmap images from vector format).
+ Defaults to YES.
+ @note works for `SDImageCoder`, `SDProgressiveImageCoder`, `SDAnimatedImageCoder`.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodePreserveAspectRatio;
+
+/**
+ A CGSize value indicating whether or not to generate the thumbnail images (or bitmap images from vector format). When this value is provided, the decoder will generate a thumbnail image which pixel size is smaller than or equal to (depends the `.preserveAspectRatio`) the value size.
+ Defaults to CGSizeZero, which means no thumbnail generation at all.
+ @note Supports for animated image as well.
+ @note When you pass `.preserveAspectRatio == NO`, the thumbnail image is stretched to match each dimension. When `.preserveAspectRatio == YES`, the thumbnail image's width is limited to pixel size's width, the thumbnail image's height is limited to pixel size's height. For common cases, you can just pass a square size to limit both.
+ @note works for `SDImageCoder`, `SDProgressiveImageCoder`, `SDAnimatedImageCoder`.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeThumbnailPixelSize;
+
+/**
+ A NSString value indicating the source image's file extension. Example: "jpg", "nef", "tif", don't prefix the dot
+ Some image file format share the same data structure but has different tag explanation, like TIFF and NEF/SRW, see https://en.wikipedia.org/wiki/TIFF
+ Changing the file extension cause the different image result. The coder (like ImageIO) may use file extension to choose the correct parser
+ @note However, different UTType may share the same file extension, like `public.jpeg` and `public.jpeg-2000` both use `.jpg`. If you want detail control, use `TypeIdentifierHint` below
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeFileExtensionHint;
+
+/**
+ A NSString value (UTI) indicating the source image's file extension. Example: "public.jpeg-2000", "com.nikon.raw-image", "public.tiff"
+ Some image file format share the same data structure but has different tag explanation, like TIFF and NEF/SRW, see https://en.wikipedia.org/wiki/TIFF
+ Changing the file extension cause the different image result. The coder (like ImageIO) may use file extension to choose the correct parser
+ @note If you provide `TypeIdentifierHint`, the `FileExtensionHint` option above will be ignored (because UTType has high priority)
+ @note If you really don't want any hint which effect the image result, pass `NSNull.null` instead
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeTypeIdentifierHint;
+
+/**
+ A BOOL value indicating whether to use lazy-decoding. Defaults to NO on animated image coder, but defaults to YES on static image coder.
+ CGImageRef, this image object typically support lazy-decoding, via the `CGDataProviderCreateDirectAccess` or `CGDataProviderCreateSequential`
+ Which allows you to provide a lazy-called callback to access bitmap buffer, so that you can achieve lazy-decoding when consumer actually need bitmap buffer
+ UIKit on iOS use heavy on this and ImageIO codec prefers to lazy-decoding for common Hardware-Accelerate format like JPEG/PNG/HEIC
+ But however, the consumer may access bitmap buffer when running on main queue, like CoreAnimation layer render image. So this is a trade-off
+ You can force us to disable the lazy-decoding and always allocate bitmap buffer on RAM, but this may have higher ratio of OOM (out of memory)
+ @note The default value is NO for animated image coder (means `animatedImageFrameAtIndex:`)
+ @note The default value is YES for static image coder (means `decodedImageWithData:`)
+ @note works for `SDImageCoder`, `SDProgressiveImageCoder`, `SDAnimatedImageCoder`.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeUseLazyDecoding;
+
+/**
+ A NSUInteger value to provide the limit bytes during decoding. This can help to avoid OOM on large frame count animated image or large pixel static image when you don't know how much RAM it occupied before decoding
+ The decoder will do these logic based on limit bytes:
+ 1. Get the total frame count (static image means 1)
+ 2. Calculate the `framePixelSize` width/height to `sqrt(limitBytes / frameCount / bytesPerPixel)`, keeping aspect ratio (at least 1x1)
+ 3. If the `framePixelSize < originalImagePixelSize`, then do thumbnail decoding (see `SDImageCoderDecodeThumbnailPixelSize`) use the `framePixelSize` and `preseveAspectRatio = YES`
+ 4. Else, use the full pixel decoding (small than limit bytes)
+ 5. Whatever result, this does not effect the animated/static behavior of image. So even if you set `limitBytes = 1 && frameCount = 100`, we will stll create animated image with each frame `1x1` pixel size.
+ @note You can use the logic from `+[SDImageCoder scaledSizeWithImageSize:limitBytes:bytesPerPixel:frameCount:]`
+ @note This option has higher priority than `.decodeThumbnailPixelSize`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeScaleDownLimitBytes;
+
+/**
+ 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`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderDecodeToHDR;
+
+#pragma mark - Image Encoding Options
+/**
+ 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.
+ @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`.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeFirstFrameOnly;
+/**
+ A double value between 0.0-1.0 indicating the encode compression quality to produce the image data. 1.0 resulting in no compression and 0.0 resulting in the maximum compression possible. If not provide, use 1.0. (NSNumber)
+ @note works for `SDImageCoder`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeCompressionQuality;
+
+/**
+ A UIColor(NSColor) value to used for non-alpha image encoding when the input image has alpha channel, the background color will be used to compose the alpha one. If not provide, use white color.
+ @note works for `SDImageCoder`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeBackgroundColor;
+
+/**
+ A CGSize value indicating the max image resolution in pixels during encoding. For vector image, this also effect the output vector data information about width and height. The encoder will not generate the encoded image larger than this limit. Note it always use the aspect ratio of input image..
+ Defaults to CGSizeZero, which means no max size limit at all.
+ @note Supports for animated image as well.
+ @note The output image's width is limited to pixel size's width, the output image's height is limited to pixel size's height. For common cases, you can just pass a square size to limit both.
+ @note works for `SDImageCoder`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeMaxPixelSize;
+
+/**
+ A NSUInteger value specify the max output data bytes size after encoding. Some lossy format like JPEG/HEIF supports the hint for codec to automatically reduce the quality and match the file size you want. Note this option will override the `SDImageCoderEncodeCompressionQuality`, because now the quality is decided by the encoder. (NSNumber)
+ @note This is a hint, no guarantee for output size because of compression algorithm limit. And this options does not works for vector images.
+ @note works for `SDImageCoder`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeMaxFileSize;
+
+/**
+ A Boolean value indicating the encoding format should contains a thumbnail image into the output data. Only some of image format (like JPEG/HEIF/AVIF) support this behavior. The embed thumbnail will be used during next time thumbnail decoding (provided `.thumbnailPixelSize`), which is faster than full image thumbnail decoding. (NSNumber)
+ Defaults to NO, which does not embed any thumbnail.
+ @note The thumbnail image's pixel size is not defined, the encoder can choose the proper pixel size which is suitable for encoding quality.
+ @note works for `SDImageCoder`
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderEncodeEmbedThumbnail;
+
+/**
+ A SDWebImageContext object which hold the original context options from top-level API. (SDWebImageContext)
+ This option is ignored for all built-in coders and take no effect.
+ But this may be useful for some custom coders, because some business logic may dependent on things other than image or image data information only.
+ Only the unknown context from top-level API (See SDWebImageDefine.h) may be passed in during image loading.
+ See `SDWebImageContext` for more detailed information.
+ @warning Deprecated. This does nothing from 5.14.0. Use `SDWebImageContextImageDecodeOptions` to pass additional information in top-level API, and use `SDImageCoderOptions` to retrieve options from coder.
+ */
+FOUNDATION_EXPORT SDImageCoderOption _Nonnull const SDImageCoderWebImageContext API_DEPRECATED("No longer supported. Use SDWebImageContextDecodeOptions in loader API to provide options. Use SDImageCoderOptions in coder API to retrieve options.", macos(10.10, 10.10), ios(8.0, 8.0), tvos(9.0, 9.0), watchos(2.0, 2.0));
+
+#pragma mark - Coder
+/**
+ This is the image coder protocol to provide custom image decoding/encoding.
+ These methods are all required to implement.
+ @note Pay attention that these methods are not called from main queue.
+ */
+@protocol SDImageCoder <NSObject>
+
+@required
+#pragma mark - Decoding
+/**
+ Returns YES if this coder can decode some data. Otherwise, the data should be passed to another coder.
+ 
+ @param data The image data so we can look at it
+ @return YES if this coder can decode the data, NO otherwise
+ */
+- (BOOL)canDecodeFromData:(nullable NSData *)data;
+
+/**
+ Decode the image data to image.
+ @note This protocol may supports decode animated image frames. You can use `+[SDImageCoderHelper animatedImageWithFrames:]` to produce an animated image with frames.
+
+ @param data The image data to be decoded
+ @param options A dictionary containing any decoding options. Pass @{SDImageCoderDecodeScaleFactor: @(1.0)} to specify scale factor for image. Pass @{SDImageCoderDecodeFirstFrameOnly: @(YES)} to decode the first frame only.
+ @return The decoded image from data
+ */
+- (nullable UIImage *)decodedImageWithData:(nullable NSData *)data
+                                   options:(nullable SDImageCoderOptions *)options;
+
+#pragma mark - Encoding
+
+/**
+ Returns YES if this coder can encode some image. Otherwise, it should be passed to another coder.
+ For custom coder which introduce new image format, you'd better define a new `SDImageFormat` using like this. If you're creating public coder plugin for new image format, also update `https://github.com/rs/SDWebImage/wiki/Coder-Plugin-List` to avoid same value been defined twice.
+ * @code
+ static const SDImageFormat SDImageFormatHEIF = 10;
+ * @endcode
+ 
+ @param format The image format
+ @return YES if this coder can encode the image, NO otherwise
+ */
+- (BOOL)canEncodeToFormat:(SDImageFormat)format NS_SWIFT_NAME(canEncode(to:));
+
+/**
+ Encode the image to image data.
+ @note This protocol may supports encode animated image frames. You can use `+[SDImageCoderHelper framesFromAnimatedImage:]` to assemble an animated image with frames. But this consume time is not always reversible. In 5.15.0, we introduce `encodedDataWithFrames` API for better animated image encoding. Use that instead.
+ @note Which means, this just forward to `encodedDataWithFrames([SDImageFrame(image: image, duration: 0], image.sd_imageLoopCount))`
+
+ @param image The image to be encoded
+ @param format The image format to encode, you should note `SDImageFormatUndefined` format is also  possible
+ @param options A dictionary containing any encoding options. Pass @{SDImageCoderEncodeCompressionQuality: @(1)} to specify compression quality.
+ @return The encoded image data
+ */
+- (nullable NSData *)encodedDataWithImage:(nullable UIImage *)image
+                                   format:(SDImageFormat)format
+                                  options:(nullable SDImageCoderOptions *)options;
+
+#pragma mark - Animated Encoding
+@optional
+/**
+ Encode the animated image frames to image data.
+
+ @param frames The animated image frames to be encoded, should be at least 1 element, or it will fallback to static image encode.
+ @param loopCount The final animated image loop count. 0 means infinity loop. This config ignore each frame's `sd_imageLoopCount`
+ @param format The image format to encode, you should note `SDImageFormatUndefined` format is also  possible
+ @param options A dictionary containing any encoding options. Pass @{SDImageCoderEncodeCompressionQuality: @(1)} to specify compression quality.
+ @return The encoded image data
+ */
+- (nullable NSData *)encodedDataWithFrames:(nonnull NSArray<SDImageFrame *>*)frames
+                                 loopCount:(NSUInteger)loopCount
+                                    format:(SDImageFormat)format
+                                   options:(nullable SDImageCoderOptions *)options;
+@end
+
+#pragma mark - Progressive Coder
+/**
+ This is the image coder protocol to provide custom progressive image decoding.
+ These methods are all required to implement.
+ @note Pay attention that these methods are not called from main queue.
+ */
+@protocol SDProgressiveImageCoder <SDImageCoder>
+
+@required
+/**
+ Returns YES if this coder can incremental decode some data. Otherwise, it should be passed to another coder.
+ 
+ @param data The image data so we can look at it
+ @return YES if this coder can decode the data, NO otherwise
+ */
+- (BOOL)canIncrementalDecodeFromData:(nullable NSData *)data;
+
+/**
+ Because incremental decoding need to keep the decoded context, we will alloc a new instance with the same class for each download operation to avoid conflicts
+ This init method should not return nil
+
+ @param options A dictionary containing any progressive decoding options (instance-level). Pass @{SDImageCoderDecodeScaleFactor: @(1.0)} to specify scale factor for progressive animated image (each frames should use the same scale).
+ @return A new instance to do incremental decoding for the specify image format
+ */
+- (nonnull instancetype)initIncrementalWithOptions:(nullable SDImageCoderOptions *)options;
+
+/**
+ Update the incremental decoding when new image data available
+
+ @param data The image data has been downloaded so far
+ @param finished Whether the download has finished
+ */
+- (void)updateIncrementalData:(nullable NSData *)data finished:(BOOL)finished;
+
+/**
+ Incremental decode the current image data to image.
+ @note Due to the performance issue for progressive decoding and the integration for image view. This method may only return the first frame image even if the image data is animated image. If you want progressive animated image decoding, conform to `SDAnimatedImageCoder` protocol as well and use `animatedImageFrameAtIndex:` instead.
+
+ @param options A dictionary containing any progressive decoding options. Pass @{SDImageCoderDecodeScaleFactor: @(1.0)} to specify scale factor for progressive image
+ @return The decoded image from current data
+ */
+- (nullable UIImage *)incrementalDecodedImageWithOptions:(nullable SDImageCoderOptions *)options;
+
+@end
+
+#pragma mark - Animated Image Provider
+/**
+ This is the animated image protocol to provide the basic function for animated image rendering. It's adopted by `SDAnimatedImage` and `SDAnimatedImageCoder`
+ */
+@protocol SDAnimatedImageProvider <NSObject>
+
+@required
+/**
+ The original animated image data for current image. If current image is not an animated format, return nil.
+ We may use this method to grab back the original image data if need, such as NSCoding or compare.
+ 
+ @return The animated image data
+ */
+@property (nonatomic, copy, readonly, nullable) NSData *animatedImageData;
+
+/**
+ Total animated frame count.
+ If the frame count is less than 1, then the methods below will be ignored.
+ 
+ @return Total animated frame count.
+ */
+@property (nonatomic, assign, readonly) NSUInteger animatedImageFrameCount;
+/**
+ Animation loop count, 0 means infinite looping.
+ 
+ @return Animation loop count
+ */
+@property (nonatomic, assign, readonly) NSUInteger animatedImageLoopCount;
+/**
+ Returns the frame image from a specified index.
+ @note The index maybe randomly if one image was set to different imageViews, keep it re-entrant. (It's not recommend to store the images into array because it's memory consuming)
+ 
+ @param index Frame index (zero based).
+ @return Frame's image
+ */
+- (nullable UIImage *)animatedImageFrameAtIndex:(NSUInteger)index;
+/**
+ Returns the frames's duration from a specified index.
+ @note The index maybe randomly if one image was set to different imageViews, keep it re-entrant. (It's recommend to store the durations into array because it's not memory-consuming)
+ 
+ @param index Frame index (zero based).
+ @return Frame's duration
+ */
+- (NSTimeInterval)animatedImageDurationAtIndex:(NSUInteger)index;
+
+@end
+
+#pragma mark - Animated Coder
+/**
+ This is the animated image coder protocol for custom animated image class like  `SDAnimatedImage`. Through it inherit from `SDImageCoder`. We currentlly only use the method `canDecodeFromData:` to detect the proper coder for specify animated image format.
+ */
+@protocol SDAnimatedImageCoder <SDImageCoder, SDAnimatedImageProvider>
+
+@required
+/**
+ Because animated image coder should keep the original data, we will alloc a new instance with the same class for the specify animated image data
+ The init method should return nil if it can't decode the specify animated image data to produce any frame.
+ After the instance created, we may call methods in `SDAnimatedImageProvider` to produce animated image frame.
+
+ @param data The animated image data to be decode
+ @param options A dictionary containing any animated decoding options (instance-level). Pass @{SDImageCoderDecodeScaleFactor: @(1.0)} to specify scale factor for animated image (each frames should use the same scale).
+ @return A new instance to do animated decoding for specify image data
+ */
+- (nullable instancetype)initWithAnimatedImageData:(nullable NSData *)data options:(nullable SDImageCoderOptions *)options;
+
+@end

package/platforms/ios/include/SDWebImage/SDImageCoderHelper.h

@@ -0,0 +1,251 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import <ImageIO/ImageIO.h>
+#import "SDWebImageCompat.h"
+#import "SDImageFrame.h"
+
+/// The options controls how we force pre-draw the image (to avoid lazy-decoding). Which need OS's framework compatibility
+typedef NS_ENUM(NSUInteger, SDImageCoderDecodeSolution) {
+    /// automatically choose the solution based on image format, hardware, OS version. This keep balance for compatibility and performance. Default after SDWebImage 5.13.0
+    SDImageCoderDecodeSolutionAutomatic,
+    /// always use CoreGraphics to draw on bitmap context and trigger decode. Best compatibility. Default before SDWebImage 5.13.0
+    SDImageCoderDecodeSolutionCoreGraphics,
+    /// available on iOS/tvOS 15+, use UIKit's new CGImageDecompressor/CMPhoto to decode. Best performance. If failed, will fallback to CoreGraphics as well
+    SDImageCoderDecodeSolutionUIKit
+};
+
+/// The policy to force-decode the origin CGImage (produced by Image Coder Plugin)
+/// Some CGImage may be lazy, or not lazy, but need extra copy to render on screen
+/// The force-decode step help to `pre-process` to get the best suitable CGImage to render, which can increase frame rate
+/// The downside is that force-decode may consume RAM and CPU, and may loss the `lazy` support (lazy CGImage can be purged when memory warning, and re-created if need), see more: `SDImageCoderDecodeUseLazyDecoding`
+typedef NS_ENUM(NSUInteger, SDImageForceDecodePolicy) {
+    /// Based on input CGImage's colorspace, alignment, bitmapinfo, if it may trigger `CA::copy_image` extra copy, we will force-decode, else don't
+    SDImageForceDecodePolicyAutomatic,
+    /// Never force decode input CGImage
+    SDImageForceDecodePolicyNever,
+    /// Always force decode input CGImage (only once)
+    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
+///   - alignment: The alignment, in bytes
+static inline size_t SDByteAlign(size_t size, size_t alignment) {
+    return ((size + (alignment - 1)) / alignment) * alignment;
+}
+
+/// The pixel format about the information to call `CGImageCreate` suitable for current hardware rendering
+typedef struct SDImagePixelFormat {
+    /// Typically is pre-multiplied RGBA8888 for alpha image, RGBX8888 for non-alpha image.
+    CGBitmapInfo bitmapInfo;
+    /// Typically is 32, the 8 pixels bytesPerRow.
+    size_t alignment;
+} SDImagePixelFormat;
+
+/**
+ Provide some common helper methods for building the image decoder/encoder.
+ */
+@interface SDImageCoderHelper : NSObject
+
+/**
+ Return an animated image with frames array.
+ For UIKit, this will apply the patch and then create animated UIImage. The patch is because that `+[UIImage animatedImageWithImages:duration:]` just use the average of duration for each image. So it will not work if different frame has different duration. Therefore we repeat the specify frame for specify times to let it work.
+ For AppKit before macOS 10.13, NSImage does not support animates other than GIF. This will try to encode the frames to GIF format and then create an animated NSImage for rendering. Attention the animated image may loss some detail if the input frames contain full alpha channel because GIF only supports 1 bit alpha channel. (For 1 pixel, either transparent or not)
+ For AppKit after macOS 10.14, use APNG format, which has a better render result.
+
+ @param frames The frames array. If no frames or frames is empty, return nil
+ @return A animated image for rendering on UIImageView(UIKit) or NSImageView(AppKit)
+ */
++ (UIImage * _Nullable)animatedImageWithFrames:(NSArray<SDImageFrame *> * _Nullable)frames;
+
+/**
+ Return frames array from an animated image.
+ For UIKit, this will unapply the patch for the description above and then create frames array. This will also work for normal animated UIImage.
+ For AppKit, NSImage does not support animates other than GIF. This will try to decode the GIF imageRep and then create frames array.
+
+ @param animatedImage A animated image. If it's not animated, return nil
+ @return The frames array
+ */
++ (NSArray<SDImageFrame *> * _Nullable)framesFromAnimatedImage:(UIImage * _Nullable)animatedImage NS_SWIFT_NAME(frames(from:));
+
+#pragma mark - Preferred Rendering Format
+/// For coders who use `CGImageCreate`, use the information below to create an effient CGImage which can be render on GPU without Core Animation's extra copy (`CA::Render::copy_image`), which can be debugged using `Color Copied Image` in Xcode Instruments
+/// `CGImageCreate`'s `bytesPerRow`, `space`, `bitmapInfo` params should use the information below.
+/**
+ Return the shared device-dependent RGB color space. This follows The Get Rule.
+ Because it's shared, you should not retain or release this object.
+ Typically is sRGB for iOS, screen color space (like Color LCD) for macOS.
+ 
+ @return The device-dependent RGB color space
+ */
++ (CGColorSpaceRef _Nonnull)colorSpaceGetDeviceRGB CF_RETURNS_NOT_RETAINED;
+
+/**
+ Tthis returns the pixel format **Preferred from current hardward && OS using runtime detection**
+ @param containsAlpha Whether the image to render contains alpha channel
+ */
++ (SDImagePixelFormat)preferredPixelFormat:(BOOL)containsAlpha;
+
+/**
+ Check whether CGImage is hardware supported to rendering on screen, without the trigger of `CA::Render::copy_image`
+ You can debug the copied image by using Xcode's `Color Copied Image`, the copied image will turn Cyan and occupy double RAM for bitmap buffer.
+ Typically, when the CGImage's using the method above (`colorspace` / `alignment` / `bitmapInfo`) can render withtout the copy.
+ */
++ (BOOL)CGImageIsHardwareSupported:(_Nonnull CGImageRef)cgImage;
+
+/**
+ Check whether CGImage contains alpha channel.
+ 
+ @param cgImage The CGImage
+ @return Return YES if CGImage contains alpha channel, otherwise return NO
+ */
++ (BOOL)CGImageContainsAlpha:(_Nonnull CGImageRef)cgImage;
+
+/**
+ Detect whether the CGImage is lazy and not-yet decoded. (lazy means, only when the caller access the underlying bitmap buffer via provider like `CGDataProviderCopyData` or `CGDataProviderRetainBytePtr`, the decoder will allocate memory, it's a lazy allocation)
+ The implementation use the Core Graphics internal to check whether the CGImage is `CGImageProvider` based, or `CGDataProvider` based. The `CGDataProvider` based is treated as non-lazy.
+ */
++ (BOOL)CGImageIsLazy:(_Nonnull CGImageRef)cgImage;
+
+/**
+ Check if the CGImage is using HDR color space.
+ @note This use the same implementation like Apple, to checkl if color space uses transfer functions defined in ITU Rec.2100
+ */
++ (BOOL)CGImageIsHDR:(_Nonnull CGImageRef)cgImage;
+
+/**
+ Create a decoded CGImage by the provided CGImage. This follows The Create Rule and you are response to call release after usage.
+ It will detect whether image contains alpha channel, then create a new bitmap context with the same size of image, and draw it. This can ensure that the image do not need extra decoding after been set to the imageView.
+ @note This actually call `CGImageCreateDecoded:orientation:` with the Up orientation.
+
+ @param cgImage The CGImage
+ @return A new created decoded image
+ */
++ (CGImageRef _Nullable)CGImageCreateDecoded:(_Nonnull CGImageRef)cgImage CF_RETURNS_RETAINED;
+
+/**
+ Create a decoded CGImage by the provided CGImage and orientation. This follows The Create Rule and you are response to call release after usage.
+ It will detect whether image contains alpha channel, then create a new bitmap context with the same size of image, and draw it. This can ensure that the image do not need extra decoding after been set to the imageView.
+ 
+ @param cgImage The CGImage
+ @param orientation The EXIF image orientation.
+ @return A new created decoded image
+ */
++ (CGImageRef _Nullable)CGImageCreateDecoded:(_Nonnull CGImageRef)cgImage orientation:(CGImagePropertyOrientation)orientation CF_RETURNS_RETAINED;
+
+/**
+ Create a scaled CGImage by the provided CGImage and size. This follows The Create Rule and you are response to call release after usage.
+ It will detect whether the image size matching the scale size, if not, stretch the image to the target size.
+ @note If you need to keep aspect ratio, you can calculate the scale size by using `scaledSizeWithImageSize` first.
+ @note This scale does not change bits per components (which means RGB888 in, RGB888 out), supports 8/16/32(float) bpc. But the method in UIImage+Transform does not gurantee this.
+ @note All supported CGImage pixel format: https://developer.apple.com/library/archive/documentation/GraphicsImaging/Conceptual/drawingwithquartz2d/dq_context/dq_context.html#//apple_ref/doc/uid/TP30001066-CH203-BCIBHHBB
+ 
+ @param cgImage The CGImage
+ @param size The scale size in pixel.
+ @return A new created scaled image
+ */
++ (CGImageRef _Nullable)CGImageCreateScaled:(_Nonnull CGImageRef)cgImage size:(CGSize)size CF_RETURNS_RETAINED;
+
+/** Scale the image size based on provided scale size, whether or not to preserve aspect ratio, whether or not to scale up.
+ @note For example, if you implements thumnail decoding, pass `shouldScaleUp` to NO to avoid the calculated size larger than image size.
+ 
+ @param imageSize The image size (in pixel or point defined by caller)
+ @param scaleSize The scale size (in pixel or point defined by caller)
+ @param preserveAspectRatio Whether or not to preserve aspect ratio
+ @param shouldScaleUp Whether or not to scale up (or scale down only)
+ */
++ (CGSize)scaledSizeWithImageSize:(CGSize)imageSize scaleSize:(CGSize)scaleSize preserveAspectRatio:(BOOL)preserveAspectRatio shouldScaleUp:(BOOL)shouldScaleUp;
+
+/// Calculate the limited image size with the bytes, when using `SDImageCoderDecodeScaleDownLimitBytes`. This preserve aspect ratio and never scale up
+/// @param imageSize The image size (in pixel or point defined by caller)
+/// @param limitBytes The limit bytes
+/// @param bytesPerPixel The bytes per pixel
+/// @param frameCount The image frame count, 0 means 1 frame as well
++ (CGSize)scaledSizeWithImageSize:(CGSize)imageSize limitBytes:(NSUInteger)limitBytes bytesPerPixel:(NSUInteger)bytesPerPixel frameCount:(NSUInteger)frameCount;
+/**
+ Return the decoded image by the provided image. This one unlike `CGImageCreateDecoded:`, will not decode the image which contains alpha channel or animated image. On iOS 15+, this may use `UIImage.preparingForDisplay()` to use CMPhoto for better performance than the old solution.
+ @param image The image to be decoded
+ @note This translate to `decodedImageWithImage:policy:` with automatic policy
+ @return The decoded image
+ */
++ (UIImage * _Nullable)decodedImageWithImage:(UIImage * _Nullable)image;
+
+/**
+ Return the decoded image by the provided image. This one unlike `CGImageCreateDecoded:`, will not decode the image which contains alpha channel or animated image. On iOS 15+, this may use `UIImage.preparingForDisplay()` to use CMPhoto for better performance than the old solution.
+ @param image The image to be decoded
+ @param policy The force decode policy to decode image, will effect the check whether input image need decode
+ @return The decoded image
+ */
++ (UIImage * _Nullable)decodedImageWithImage:(UIImage * _Nullable)image policy:(SDImageForceDecodePolicy)policy;
+
+/**
+ Return the decoded and probably scaled down image by the provided image. If the image pixels bytes size large than the limit bytes, will try to scale down. Or just works as `decodedImageWithImage:`, never scale up.
+ @warning You should not pass too small bytes, the suggestion value should be larger than 1MB. Even we use Tile Decoding to avoid OOM, however, small bytes will consume much more CPU time because we need to iterate more times to draw each tile.
+
+ @param image The image to be decoded and scaled down
+ @param bytes The limit bytes size. Provide 0 to use the build-in limit.
+ @note This translate to `decodedAndScaledDownImageWithImage:limitBytes:policy:` with automatic policy
+ @return The decoded and probably scaled down image
+ */
++ (UIImage * _Nullable)decodedAndScaledDownImageWithImage:(UIImage * _Nullable)image limitBytes:(NSUInteger)bytes;
+
+/**
+ Return the decoded and probably scaled down image by the provided image. If the image pixels bytes size large than the limit bytes, will try to scale down. Or just works as `decodedImageWithImage:`, never scale up.
+ @warning You should not pass too small bytes, the suggestion value should be larger than 1MB. Even we use Tile Decoding to avoid OOM, however, small bytes will consume much more CPU time because we need to iterate more times to draw each tile.
+
+ @param image The image to be decoded and scaled down
+ @param bytes The limit bytes size. Provide 0 to use the build-in limit.
+ @param policy The force decode policy to decode image, will effect the check whether input image need decode
+ @return The decoded and probably scaled down image
+ */
++ (UIImage * _Nullable)decodedAndScaledDownImageWithImage:(UIImage * _Nullable)image limitBytes:(NSUInteger)bytes policy:(SDImageForceDecodePolicy)policy;
+
+/**
+ Control the default force decode solution. Available solutions  in `SDImageCoderDecodeSolution`.
+ @note Defaults to `SDImageCoderDecodeSolutionAutomatic`, which prefers to use UIKit for JPEG/HEIF, and fallback on CoreGraphics. If you want control on your hand, set the other solution.
+ */
+@property (class, readwrite) SDImageCoderDecodeSolution defaultDecodeSolution;
+
+/**
+ Control the default limit bytes to scale down largest images.
+ This value must be larger than 4 Bytes (at least 1x1 pixel). Defaults to 60MB on iOS/tvOS, 90MB on macOS, 30MB on watchOS.
+ */
+@property (class, readwrite) NSUInteger defaultScaleDownLimitBytes;
+
+#if SD_UIKIT || SD_WATCH
+/**
+ Convert an EXIF image orientation to an iOS one.
+
+ @param exifOrientation EXIF orientation
+ @return iOS orientation
+ */
++ (UIImageOrientation)imageOrientationFromEXIFOrientation:(CGImagePropertyOrientation)exifOrientation NS_SWIFT_NAME(imageOrientation(from:));
+
+/**
+ Convert an iOS orientation to an EXIF image orientation.
+
+ @param imageOrientation iOS orientation
+ @return EXIF orientation
+ */
++ (CGImagePropertyOrientation)exifOrientationFromImageOrientation:(UIImageOrientation)imageOrientation;
+#endif
+
+@end

package/platforms/ios/include/SDWebImage/SDImageCodersManager.h

@@ -0,0 +1,58 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import <Foundation/Foundation.h>
+#import "SDImageCoder.h"
+
+/**
+ Global object holding the array of coders, so that we avoid passing them from object to object.
+ Uses a priority queue behind scenes, which means the latest added coders have the highest priority.
+ This is done so when encoding/decoding something, we go through the list and ask each coder if they can handle the current data.
+ That way, users can add their custom coders while preserving our existing prebuilt ones
+ 
+ Note: the `coders` getter will return the coders in their reversed order
+ Example:
+ - by default we internally set coders = `IOCoder`, `GIFCoder`, `APNGCoder`
+ - calling `coders` will return `@[IOCoder, GIFCoder, APNGCoder]`
+ - call `[addCoder:[MyCrazyCoder new]]`
+ - calling `coders` now returns `@[IOCoder, GIFCoder, APNGCoder, MyCrazyCoder]`
+ 
+ Coders
+ ------
+ A coder must conform to the `SDImageCoder` protocol or even to `SDProgressiveImageCoder` if it supports progressive decoding
+ Conformance is important because that way, they will implement `canDecodeFromData` or `canEncodeToFormat`
+ Those methods are called on each coder in the array (using the priority order) until one of them returns YES.
+ That means that coder can decode that data / encode to that format
+ */
+@interface SDImageCodersManager : NSObject <SDImageCoder>
+
+/**
+ Returns the global shared coders manager instance.
+ */
+@property (nonatomic, class, readonly, nonnull) SDImageCodersManager *sharedManager;
+
+/**
+ All coders in coders manager. The coders array is a priority queue, which means the later added coder will have the highest priority
+ */
+@property (nonatomic, copy, nullable) NSArray<id<SDImageCoder>> *coders;
+
+/**
+ Add a new coder to the end of coders array. Which has the highest priority.
+
+ @param coder coder
+ */
+- (void)addCoder:(nonnull id<SDImageCoder>)coder;
+
+/**
+ Remove a coder in the coders array.
+
+ @param coder coder
+ */
+- (void)removeCoder:(nonnull id<SDImageCoder>)coder;
+
+@end