SDImageCoderHelper.h 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127
  1. /*
  2. * This file is part of the SDWebImage package.
  3. * (c) Olivier Poitrey <rs@dailymotion.com>
  4. *
  5. * For the full copyright and license information, please view the LICENSE
  6. * file that was distributed with this source code.
  7. */
  8. #import <ImageIO/ImageIO.h>
  9. #import "SDWebImageCompat.h"
  10. #import "SDImageFrame.h"
  11. /**
  12. Provide some common helper methods for building the image decoder/encoder.
  13. */
  14. @interface SDImageCoderHelper : NSObject
  15. /**
  16. Return an animated image with frames array.
  17. 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.
  18. For AppKit, 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)
  19. @param frames The frames array. If no frames or frames is empty, return nil
  20. @return A animated image for rendering on UIImageView(UIKit) or NSImageView(AppKit)
  21. */
  22. + (UIImage * _Nullable)animatedImageWithFrames:(NSArray<SDImageFrame *> * _Nullable)frames;
  23. /**
  24. Return frames array from an animated image.
  25. For UIKit, this will unapply the patch for the description above and then create frames array. This will also work for normal animated UIImage.
  26. For AppKit, NSImage does not support animates other than GIF. This will try to decode the GIF imageRep and then create frames array.
  27. @param animatedImage A animated image. If it's not animated, return nil
  28. @return The frames array
  29. */
  30. + (NSArray<SDImageFrame *> * _Nullable)framesFromAnimatedImage:(UIImage * _Nullable)animatedImage NS_SWIFT_NAME(frames(from:));
  31. /**
  32. Return the shared device-dependent RGB color space. This follows The Get Rule.
  33. On iOS, it's created with deviceRGB (if available, use sRGB).
  34. On macOS, it's from the screen colorspace (if failed, use deviceRGB)
  35. Because it's shared, you should not retain or release this object.
  36. @return The device-dependent RGB color space
  37. */
  38. + (CGColorSpaceRef _Nonnull)colorSpaceGetDeviceRGB CF_RETURNS_NOT_RETAINED;
  39. /**
  40. Check whether CGImage contains alpha channel.
  41. @param cgImage The CGImage
  42. @return Return YES if CGImage contains alpha channel, otherwise return NO
  43. */
  44. + (BOOL)CGImageContainsAlpha:(_Nonnull CGImageRef)cgImage;
  45. /**
  46. Create a decoded CGImage by the provided CGImage. This follows The Create Rule and you are response to call release after usage.
  47. 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.
  48. @note This actually call `CGImageCreateDecoded:orientation:` with the Up orientation.
  49. @param cgImage The CGImage
  50. @return A new created decoded image
  51. */
  52. + (CGImageRef _Nullable)CGImageCreateDecoded:(_Nonnull CGImageRef)cgImage CF_RETURNS_RETAINED;
  53. /**
  54. Create a decoded CGImage by the provided CGImage and orientation. This follows The Create Rule and you are response to call release after usage.
  55. 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.
  56. @param cgImage The CGImage
  57. @param orientation The EXIF image orientation.
  58. @return A new created decoded image
  59. */
  60. + (CGImageRef _Nullable)CGImageCreateDecoded:(_Nonnull CGImageRef)cgImage orientation:(CGImagePropertyOrientation)orientation CF_RETURNS_RETAINED;
  61. /**
  62. Create a scaled CGImage by the provided CGImage and size. This follows The Create Rule and you are response to call release after usage.
  63. It will detect whether the image size matching the scale size, if not, stretch the image to the target size.
  64. @param cgImage The CGImage
  65. @param size The scale size in pixel.
  66. @return A new created scaled image
  67. */
  68. + (CGImageRef _Nullable)CGImageCreateScaled:(_Nonnull CGImageRef)cgImage size:(CGSize)size CF_RETURNS_RETAINED;
  69. /**
  70. Return the decoded image by the provided image. This one unlike `CGImageCreateDecoded:`, will not decode the image which contains alpha channel or animated image
  71. @param image The image to be decoded
  72. @return The decoded image
  73. */
  74. + (UIImage * _Nullable)decodedImageWithImage:(UIImage * _Nullable)image;
  75. /**
  76. 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.
  77. @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.
  78. @param image The image to be decoded and scaled down
  79. @param bytes The limit bytes size. Provide 0 to use the build-in limit.
  80. @return The decoded and probably scaled down image
  81. */
  82. + (UIImage * _Nullable)decodedAndScaledDownImageWithImage:(UIImage * _Nullable)image limitBytes:(NSUInteger)bytes;
  83. /**
  84. Control the default limit bytes to scale down largest images.
  85. This value must be larger than 4 Bytes (at least 1x1 pixel). Defaults to 60MB on iOS/tvOS, 90MB on macOS, 30MB on watchOS.
  86. */
  87. @property (class, readwrite) NSUInteger defaultScaleDownLimitBytes;
  88. #if SD_UIKIT || SD_WATCH
  89. /**
  90. Convert an EXIF image orientation to an iOS one.
  91. @param exifOrientation EXIF orientation
  92. @return iOS orientation
  93. */
  94. + (UIImageOrientation)imageOrientationFromEXIFOrientation:(CGImagePropertyOrientation)exifOrientation NS_SWIFT_NAME(imageOrientation(from:));
  95. /**
  96. Convert an iOS orientation to an EXIF image orientation.
  97. @param imageOrientation iOS orientation
  98. @return EXIF orientation
  99. */
  100. + (CGImagePropertyOrientation)exifOrientationFromImageOrientation:(UIImageOrientation)imageOrientation;
  101. #endif
  102. @end