Merge pull request #2361 from dreampiggy/refactor_uiimage_multiformat

Refactor the UIImage+MultiFormat and GIF/WebP category

SDWebImage/UIImage+GIF.h

@@ -9,24 +9,16 @@
 
 #import "SDWebImageCompat.h"
 
+// This category is just use as a convenience method. For more detail control, use methods in `UIImage+MultiFormat.h` or directlly use `SDImageCoder`
 @interface UIImage (GIF)
 
 /**
  Creates an animated UIImage from an NSData.
- For Static GIF, will create an UIImage with `images` array set to nil. For Animated GIF, will create an UIImage with valid `images` array.
+ This will create animated image if the data is Animated GIF. And will create a static image is the data is Static GIF.
 
  @param data The GIF data
  @return The created image
  */
-+ (nullable UIImage *)sd_animatedGIFWithData:(nullable NSData *)data;
++ (nullable UIImage *)sd_imageWithGIFData:(nullable NSData *)data;
-
-/**
- Creates an animated UIImage from an NSData.
- 
- @param data The GIF data
- @param firstFrameOnly Even if the image data is Animated GIF format, decode the first frame only
- @return The created image
- */
-+ (nullable UIImage *)sd_animatedGIFWithData:(nullable NSData *)data firstFrameOnly:(BOOL)firstFrameOnly;
 
 @end

SDWebImage/UIImage+GIF.m

@@ -12,16 +12,11 @@
 
 @implementation UIImage (GIF)
 
-+ (nullable UIImage *)sd_animatedGIFWithData:(nullable NSData *)data {
++ (nullable UIImage *)sd_imageWithGIFData:(nullable NSData *)data {
-    return [self sd_animatedGIFWithData:data firstFrameOnly:NO];
-}
-
-+ (nullable UIImage *)sd_animatedGIFWithData:(nullable NSData *)data firstFrameOnly:(BOOL)firstFrameOnly {
     if (!data) {
         return nil;
     }
-    SDImageCoderOptions *options = @{SDImageCoderDecodeFirstFrameOnly : @(firstFrameOnly)};
+    return [[SDImageGIFCoder sharedCoder] decodedImageWithData:data options:0];
-    return [[SDImageGIFCoder sharedCoder] decodedImageWithData:data options:options];
 }
 
 @end

SDWebImage/UIImage+MultiFormat.h

@@ -28,6 +28,16 @@
  */
 + (nullable UIImage *)sd_imageWithData:(nullable NSData *)data scale:(CGFloat)scale;
 
+/**
+ Create and decode a image with the specify image data and scale, allow specify animate/static control
+ 
+ @param data The image data
+ @param scale The image scale factor. Should be greater than or equal to 1.0.
+ @param firstFrameOnly Even if the image data is animated image format, decode the first frame only as static image.
+ @return The created image
+ */
++ (nullable UIImage *)sd_imageWithData:(nullable NSData *)data scale:(CGFloat)scale firstFrameOnly:(BOOL)firstFrameOnly;
+
 #pragma mark - Encode
 /**
  Encode the current image to the data, the image format is unspecified
@@ -53,4 +63,14 @@
  */
 - (nullable NSData *)sd_imageDataAsFormat:(SDImageFormat)imageFormat compressionQuality:(double)compressionQuality;
 
+/**
+ Encode the current image to data with the specify image format and compression quality, allow specify animate/static control
+ 
+ @param imageFormat The specify image format
+ @param compressionQuality The quality of the resulting image data. Value between 0.0-1.0. Some coders may not support compression quality.
+ @param firstFrameOnly Even if the image is animated image, encode the first frame only as static image.
+ @return The encoded data. If can't encode, return nil
+ */
+- (nullable NSData *)sd_imageDataAsFormat:(SDImageFormat)imageFormat compressionQuality:(double)compressionQuality firstFrameOnly:(BOOL)firstFrameOnly;
+
 @end

SDWebImage/UIImage+MultiFormat.m

@@ -16,13 +16,17 @@
 }
 
 + (nullable UIImage *)sd_imageWithData:(nullable NSData *)data scale:(CGFloat)scale {
+    return [self sd_imageWithData:data scale:scale firstFrameOnly:NO];
+}
+
++ (nullable UIImage *)sd_imageWithData:(nullable NSData *)data scale:(CGFloat)scale firstFrameOnly:(BOOL)firstFrameOnly {
     if (!data) {
         return nil;
     }
     if (scale < 1) {
         scale = 1;
     }
-    SDImageCoderOptions *options = @{SDImageCoderDecodeScaleFactor : @(scale)};
+    SDImageCoderOptions *options = @{SDImageCoderDecodeScaleFactor : @(scale), SDImageCoderDecodeFirstFrameOnly : @(firstFrameOnly)};
     return [[SDImageCodersManager sharedManager] decodedImageWithData:data options:options];
 }
 
@@ -35,7 +39,11 @@
 }
 
 - (nullable NSData *)sd_imageDataAsFormat:(SDImageFormat)imageFormat compressionQuality:(double)compressionQuality {
-    SDImageCoderOptions *options = @{SDImageCoderEncodeCompressionQuality : @(compressionQuality)};
+    return [self sd_imageDataAsFormat:imageFormat compressionQuality:compressionQuality firstFrameOnly:NO];
+}
+
+- (nullable NSData *)sd_imageDataAsFormat:(SDImageFormat)imageFormat compressionQuality:(double)compressionQuality firstFrameOnly:(BOOL)firstFrameOnly {
+    SDImageCoderOptions *options = @{SDImageCoderEncodeCompressionQuality : @(compressionQuality), SDImageCoderEncodeFirstFrameOnly : @(firstFrameOnly)};
     return [[SDImageCodersManager sharedManager] encodedDataWithImage:self format:imageFormat options:options];
 }
 

SDWebImage/WebP/UIImage+WebP.h

@@ -10,26 +10,18 @@
 
 #import "SDWebImageCompat.h"
 
+// This category is just use as a convenience method. For more detail control, use methods in `UIImage+MultiFormat.h` or directlly use `SDImageCoder`
 @interface UIImage (WebP)
 
 /**
  Create a image from the WebP data.
- This may create animated image if the data is Animated WebP.
+ This will create animated image if the data is Animated WebP. And will create a static image is the data is Static WebP.
 
  @param data The WebP data
  @return The created image
  */
 + (nullable UIImage *)sd_imageWithWebPData:(nullable NSData *)data;
 
-/**
- Create a image from the WebP data.
- 
- @param data The WebP data
- @param firstFrameOnly Even if the image data is Animated WebP format, decode the first frame only
- @return The created image
- */
-+ (nullable UIImage *)sd_imageWithWebPData:(nullable NSData *)data firstFrameOnly:(BOOL)firstFrameOnly;
-
 @end
 
 #endif

SDWebImage/WebP/UIImage+WebP.m

@@ -14,15 +14,10 @@
 @implementation UIImage (WebP)
 
 + (nullable UIImage *)sd_imageWithWebPData:(nullable NSData *)data {
-    return [self sd_imageWithWebPData:data firstFrameOnly:NO];
-}
-
-+ (nullable UIImage *)sd_imageWithWebPData:(nullable NSData *)data firstFrameOnly:(BOOL)firstFrameOnly {
     if (!data) {
         return nil;
     }
-    SDImageCoderOptions *options = @{SDImageCoderDecodeFirstFrameOnly : @(firstFrameOnly)};
+    return [[SDImageWebPCoder sharedCoder] decodedImageWithData:data options:0];
-    return [[SDImageWebPCoder sharedCoder] decodedImageWithData:data options:options];
 }
 
 @end

Tests/Tests/SDCategoriesTests.m

@@ -43,11 +43,11 @@
 
 - (void)test03UIImageGIFCategory {
     // Test invalid image data
-    UIImage *image = [UIImage sd_animatedGIFWithData:nil];
+    UIImage *image = [UIImage sd_imageWithGIFData:nil];
     expect(image).to.beNil();
     // Test valid image data
     NSData *data = [NSData dataWithContentsOfFile:[self testGIFPath]];
-    image = [UIImage sd_animatedGIFWithData:data];
+    image = [UIImage sd_imageWithGIFData:data];
     expect(image).notTo.beNil();
 }