//
|
// YYImageCoder.h
|
// YYImage <https://github.com/ibireme/YYImage>
|
//
|
// Created by ibireme on 15/5/13.
|
// Copyright (c) 2015 ibireme.
|
//
|
// This source code is licensed under the MIT-style license found in the
|
// LICENSE file in the root directory of this source tree.
|
//
|
|
#import <UIKit/UIKit.h>
|
|
NS_ASSUME_NONNULL_BEGIN
|
|
/**
|
Image file type.
|
*/
|
typedef NS_ENUM(NSUInteger, YYImageType) {
|
YYImageTypeUnknown = 0, ///< unknown
|
YYImageTypeJPEG, ///< jpeg, jpg
|
YYImageTypeJPEG2000, ///< jp2
|
YYImageTypeTIFF, ///< tiff, tif
|
YYImageTypeBMP, ///< bmp
|
YYImageTypeICO, ///< ico
|
YYImageTypeICNS, ///< icns
|
YYImageTypeGIF, ///< gif
|
YYImageTypePNG, ///< png
|
YYImageTypeWebP, ///< webp
|
YYImageTypeOther, ///< other image format
|
};
|
|
|
/**
|
Dispose method specifies how the area used by the current frame is to be treated
|
before rendering the next frame on the canvas.
|
*/
|
typedef NS_ENUM(NSUInteger, YYImageDisposeMethod) {
|
|
/**
|
No disposal is done on this frame before rendering the next; the contents
|
of the canvas are left as is.
|
*/
|
YYImageDisposeNone = 0,
|
|
/**
|
The frame's region of the canvas is to be cleared to fully transparent black
|
before rendering the next frame.
|
*/
|
YYImageDisposeBackground,
|
|
/**
|
The frame's region of the canvas is to be reverted to the previous contents
|
before rendering the next frame.
|
*/
|
YYImageDisposePrevious,
|
};
|
|
/**
|
Blend operation specifies how transparent pixels of the current frame are
|
blended with those of the previous canvas.
|
*/
|
typedef NS_ENUM(NSUInteger, YYImageBlendOperation) {
|
|
/**
|
All color components of the frame, including alpha, overwrite the current
|
contents of the frame's canvas region.
|
*/
|
YYImageBlendNone = 0,
|
|
/**
|
The frame should be composited onto the output buffer based on its alpha.
|
*/
|
YYImageBlendOver,
|
};
|
|
/**
|
An image frame object.
|
*/
|
@interface YYImageFrame : NSObject <NSCopying>
|
@property (nonatomic) NSUInteger index; ///< Frame index (zero based)
|
@property (nonatomic) NSUInteger width; ///< Frame width
|
@property (nonatomic) NSUInteger height; ///< Frame height
|
@property (nonatomic) NSUInteger offsetX; ///< Frame origin.x in canvas (left-bottom based)
|
@property (nonatomic) NSUInteger offsetY; ///< Frame origin.y in canvas (left-bottom based)
|
@property (nonatomic) NSTimeInterval duration; ///< Frame duration in seconds
|
@property (nonatomic) YYImageDisposeMethod dispose; ///< Frame dispose method.
|
@property (nonatomic) YYImageBlendOperation blend; ///< Frame blend operation.
|
@property (nullable, nonatomic, strong) UIImage *image; ///< The image.
|
+ (instancetype)frameWithImage:(UIImage *)image;
|
@end
|
|
|
#pragma mark - Decoder
|
|
/**
|
An image decoder to decode image data.
|
|
@discussion This class supports decoding animated WebP, APNG, GIF and system
|
image format such as PNG, JPG, JP2, BMP, TIFF, PIC, ICNS and ICO. It can be used
|
to decode complete image data, or to decode incremental image data during image
|
download. This class is thread-safe.
|
|
Example:
|
|
// Decode single image:
|
NSData *data = [NSData dataWithContentOfFile:@"/tmp/image.webp"];
|
YYImageDecoder *decoder = [YYImageDecoder decoderWithData:data scale:2.0];
|
UIImage image = [decoder frameAtIndex:0 decodeForDisplay:YES].image;
|
|
// Decode image during download:
|
NSMutableData *data = [NSMutableData new];
|
YYImageDecoder *decoder = [[YYImageDecoder alloc] initWithScale:2.0];
|
while(newDataArrived) {
|
[data appendData:newData];
|
[decoder updateData:data final:NO];
|
if (decoder.frameCount > 0) {
|
UIImage image = [decoder frameAtIndex:0 decodeForDisplay:YES].image;
|
// progressive display...
|
}
|
}
|
[decoder updateData:data final:YES];
|
UIImage image = [decoder frameAtIndex:0 decodeForDisplay:YES].image;
|
// final display...
|
|
*/
|
@interface YYImageDecoder : NSObject
|
|
@property (nullable, nonatomic, readonly) NSData *data; ///< Image data.
|
@property (nonatomic, readonly) YYImageType type; ///< Image data type.
|
@property (nonatomic, readonly) CGFloat scale; ///< Image scale.
|
@property (nonatomic, readonly) NSUInteger frameCount; ///< Image frame count.
|
@property (nonatomic, readonly) NSUInteger loopCount; ///< Image loop count, 0 means infinite.
|
@property (nonatomic, readonly) NSUInteger width; ///< Image canvas width.
|
@property (nonatomic, readonly) NSUInteger height; ///< Image canvas height.
|
@property (nonatomic, readonly, getter=isFinalized) BOOL finalized;
|
|
/**
|
Creates an image decoder.
|
|
@param scale Image's scale.
|
@return An image decoder.
|
*/
|
- (instancetype)initWithScale:(CGFloat)scale NS_DESIGNATED_INITIALIZER;
|
|
/**
|
Updates the incremental image with new data.
|
|
@discussion You can use this method to decode progressive/interlaced/baseline
|
image when you do not have the complete image data. The `data` was retained by
|
decoder, you should not modify the data in other thread during decoding.
|
|
@param data The data to add to the image decoder. Each time you call this
|
function, the 'data' parameter must contain all of the image file data
|
accumulated so far.
|
|
@param final A value that specifies whether the data is the final set.
|
Pass YES if it is, NO otherwise. When the data is already finalized, you can
|
not update the data anymore.
|
|
@return Whether succeed.
|
*/
|
- (BOOL)updateData:(nullable NSData *)data final:(BOOL)final;
|
|
/**
|
Convenience method to create a decoder with specified data.
|
@param data Image data.
|
@param scale Image's scale.
|
@return A new decoder, or nil if an error occurs.
|
*/
|
+ (nullable instancetype)decoderWithData:(NSData *)data scale:(CGFloat)scale;
|
|
/**
|
Decodes and returns a frame from a specified index.
|
@param index Frame image index (zero-based).
|
@param decodeForDisplay Whether decode the image to memory bitmap for display.
|
If NO, it will try to returns the original frame data without blend.
|
@return A new frame with image, or nil if an error occurs.
|
*/
|
- (nullable YYImageFrame *)frameAtIndex:(NSUInteger)index decodeForDisplay:(BOOL)decodeForDisplay;
|
|
/**
|
Returns the frame duration from a specified index.
|
@param index Frame image (zero-based).
|
@return Duration in seconds.
|
*/
|
- (NSTimeInterval)frameDurationAtIndex:(NSUInteger)index;
|
|
/**
|
Returns the frame's properties. See "CGImageProperties.h" in ImageIO.framework
|
for more information.
|
|
@param index Frame image index (zero-based).
|
@return The ImageIO frame property.
|
*/
|
- (nullable NSDictionary *)framePropertiesAtIndex:(NSUInteger)index;
|
|
/**
|
Returns the image's properties. See "CGImageProperties.h" in ImageIO.framework
|
for more information.
|
*/
|
- (nullable NSDictionary *)imageProperties;
|
|
@end
|
|
|
|
#pragma mark - Encoder
|
|
/**
|
An image encoder to encode image to data.
|
|
@discussion It supports encoding single frame image with the type defined in YYImageType.
|
It also supports encoding multi-frame image with GIF, APNG and WebP.
|
|
Example:
|
|
YYImageEncoder *jpegEncoder = [[YYImageEncoder alloc] initWithType:YYImageTypeJPEG];
|
jpegEncoder.quality = 0.9;
|
[jpegEncoder addImage:image duration:0];
|
NSData jpegData = [jpegEncoder encode];
|
|
YYImageEncoder *gifEncoder = [[YYImageEncoder alloc] initWithType:YYImageTypeGIF];
|
gifEncoder.loopCount = 5;
|
[gifEncoder addImage:image0 duration:0.1];
|
[gifEncoder addImage:image1 duration:0.15];
|
[gifEncoder addImage:image2 duration:0.2];
|
NSData gifData = [gifEncoder encode];
|
|
@warning It just pack the images together when encoding multi-frame image. If you
|
want to reduce the image file size, try imagemagick/ffmpeg for GIF and WebP,
|
and apngasm for APNG.
|
*/
|
@interface YYImageEncoder : NSObject
|
|
@property (nonatomic, readonly) YYImageType type; ///< Image type.
|
@property (nonatomic) NSUInteger loopCount; ///< Loop count, 0 means infinit, only available for GIF/APNG/WebP.
|
@property (nonatomic) BOOL lossless; ///< Lossless, only available for WebP.
|
@property (nonatomic) CGFloat quality; ///< Compress quality, 0.0~1.0, only available for JPG/JP2/WebP.
|
|
- (instancetype)init UNAVAILABLE_ATTRIBUTE;
|
+ (instancetype)new UNAVAILABLE_ATTRIBUTE;
|
|
/**
|
Create an image encoder with a specified type.
|
@param type Image type.
|
@return A new encoder, or nil if an error occurs.
|
*/
|
- (nullable instancetype)initWithType:(YYImageType)type NS_DESIGNATED_INITIALIZER;
|
|
/**
|
Add an image to encoder.
|
@param image Image.
|
@param duration Image duration for animation. Pass 0 to ignore this parameter.
|
*/
|
- (void)addImage:(UIImage *)image duration:(NSTimeInterval)duration;
|
|
/**
|
Add an image with image data to encoder.
|
@param data Image data.
|
@param duration Image duration for animation. Pass 0 to ignore this parameter.
|
*/
|
- (void)addImageWithData:(NSData *)data duration:(NSTimeInterval)duration;
|
|
/**
|
Add an image from a file path to encoder.
|
@param image Image file path.
|
@param duration Image duration for animation. Pass 0 to ignore this parameter.
|
*/
|
- (void)addImageWithFile:(NSString *)path duration:(NSTimeInterval)duration;
|
|
/**
|
Encodes the image and returns the image data.
|
@return The image data, or nil if an error occurs.
|
*/
|
- (nullable NSData *)encode;
|
|
/**
|
Encodes the image to a file.
|
@param path The file path (overwrite if exist).
|
@return Whether succeed.
|
*/
|
- (BOOL)encodeToFile:(NSString *)path;
|
|
/**
|
Convenience method to encode single frame image.
|
@param image The image.
|
@param type The destination image type.
|
@param quality Image quality, 0.0~1.0.
|
@return The image data, or nil if an error occurs.
|
*/
|
+ (nullable NSData *)encodeImage:(UIImage *)image type:(YYImageType)type quality:(CGFloat)quality;
|
|
/**
|
Convenience method to encode image from a decoder.
|
@param decoder The image decoder.
|
@param type The destination image type;
|
@param quality Image quality, 0.0~1.0.
|
@return The image data, or nil if an error occurs.
|
*/
|
+ (nullable NSData *)encodeImageWithDecoder:(YYImageDecoder *)decoder type:(YYImageType)type quality:(CGFloat)quality;
|
|
@end
|
|
|
#pragma mark - UIImage
|
|
@interface UIImage (YYImageCoder)
|
|
/**
|
Decompress this image to bitmap, so when the image is displayed on screen,
|
the main thread won't be blocked by additional decode. If the image has already
|
been decoded or unable to decode, it just returns itself.
|
|
@return an image decoded, or just return itself if no needed.
|
@see yy_isDecodedForDisplay
|
*/
|
- (instancetype)yy_imageByDecoded;
|
|
/**
|
Wherher the image can be display on screen without additional decoding.
|
@warning It just a hint for your code, change it has no other effect.
|
*/
|
@property (nonatomic) BOOL yy_isDecodedForDisplay;
|
|
/**
|
Saves this image to iOS Photos Album.
|
|
@discussion This method attempts to save the original data to album if the
|
image is created from an animated GIF/APNG, otherwise, it will save the image
|
as JPEG or PNG (based on the alpha information).
|
|
@param completionBlock The block invoked (in main thread) after the save operation completes.
|
assetURL: An URL that identifies the saved image file. If the image is not saved, assetURL is nil.
|
error: If the image is not saved, an error object that describes the reason for failure, otherwise nil.
|
*/
|
- (void)yy_saveToAlbumWithCompletionBlock:(nullable void(^)(NSURL * _Nullable assetURL, NSError * _Nullable error))completionBlock;
|
|
/**
|
Return a 'best' data representation for this image.
|
|
@discussion The convertion based on these rule:
|
1. If the image is created from an animated GIF/APNG/WebP, it returns the original data.
|
2. It returns PNG or JPEG(0.9) representation based on the alpha information.
|
|
@return Image data, or nil if an error occurs.
|
*/
|
- (nullable NSData *)yy_imageDataRepresentation;
|
|
@end
|
|
|
|
#pragma mark - Helper
|
|
/// Detect a data's image type by reading the data's header 16 bytes (very fast).
|
CG_EXTERN YYImageType YYImageDetectType(CFDataRef data);
|
|
/// Convert YYImageType to UTI (such as kUTTypeJPEG).
|
CG_EXTERN CFStringRef _Nullable YYImageTypeToUTType(YYImageType type);
|
|
/// Convert UTI (such as kUTTypeJPEG) to YYImageType.
|
CG_EXTERN YYImageType YYImageTypeFromUTType(CFStringRef uti);
|
|
/// Get image type's file extension (such as @"jpg").
|
CG_EXTERN NSString *_Nullable YYImageTypeGetExtension(YYImageType type);
|
|
|
|
/// Returns the shared DeviceRGB color space.
|
CG_EXTERN CGColorSpaceRef YYCGColorSpaceGetDeviceRGB();
|
|
/// Returns the shared DeviceGray color space.
|
CG_EXTERN CGColorSpaceRef YYCGColorSpaceGetDeviceGray();
|
|
/// Returns whether a color space is DeviceRGB.
|
CG_EXTERN BOOL YYCGColorSpaceIsDeviceRGB(CGColorSpaceRef space);
|
|
/// Returns whether a color space is DeviceGray.
|
CG_EXTERN BOOL YYCGColorSpaceIsDeviceGray(CGColorSpaceRef space);
|
|
|
|
/// Convert EXIF orientation value to UIImageOrientation.
|
CG_EXTERN UIImageOrientation YYUIImageOrientationFromEXIFValue(NSInteger value);
|
|
/// Convert UIImageOrientation to EXIF orientation value.
|
CG_EXTERN NSInteger YYUIImageOrientationToEXIFValue(UIImageOrientation orientation);
|
|
|
|
/**
|
Create a decoded image.
|
|
@discussion If the source image is created from a compressed image data (such as
|
PNG or JPEG), you can use this method to decode the image. After decoded, you can
|
access the decoded bytes with CGImageGetDataProvider() and CGDataProviderCopyData()
|
without additional decode process. If the image has already decoded, this method
|
just copy the decoded bytes to the new image.
|
|
@param imageRef The source image.
|
@param decodeForDisplay If YES, this method will decode the image and convert
|
it to BGRA8888 (premultiplied) or BGRX8888 format for CALayer display.
|
|
@return A decoded image, or NULL if an error occurs.
|
*/
|
CG_EXTERN CGImageRef _Nullable YYCGImageCreateDecodedCopy(CGImageRef imageRef, BOOL decodeForDisplay);
|
|
/**
|
Create an image copy with an orientation.
|
|
@param imageRef Source image
|
@param orientation Image orientation which will applied to the image.
|
@param destBitmapInfo Destimation image bitmap, only support 32bit format (such as ARGB8888).
|
@return A new image, or NULL if an error occurs.
|
*/
|
CG_EXTERN CGImageRef _Nullable YYCGImageCreateCopyWithOrientation(CGImageRef imageRef,
|
UIImageOrientation orientation,
|
CGBitmapInfo destBitmapInfo);
|
|
/**
|
Create an image copy with CGAffineTransform.
|
|
@param imageRef Source image.
|
@param transform Transform applied to image (left-bottom based coordinate system).
|
@param destSize Destination image size
|
@param destBitmapInfo Destimation image bitmap, only support 32bit format (such as ARGB8888).
|
@return A new image, or NULL if an error occurs.
|
*/
|
CG_EXTERN CGImageRef _Nullable YYCGImageCreateAffineTransformCopy(CGImageRef imageRef,
|
CGAffineTransform transform,
|
CGSize destSize,
|
CGBitmapInfo destBitmapInfo);
|
|
/**
|
Encode an image to data with CGImageDestination.
|
|
@param imageRef The image.
|
@param type The image destination data type.
|
@param quality The quality (0.0~1.0)
|
@return A new image data, or nil if an error occurs.
|
*/
|
CG_EXTERN CFDataRef _Nullable YYCGImageCreateEncodedData(CGImageRef imageRef, YYImageType type, CGFloat quality);
|
|
|
/**
|
Whether WebP is available in YYImage.
|
*/
|
CG_EXTERN BOOL YYImageWebPAvailable();
|
|
/**
|
Get a webp image frame count;
|
|
@param webpData WebP data.
|
@return Image frame count, or 0 if an error occurs.
|
*/
|
CG_EXTERN NSUInteger YYImageGetWebPFrameCount(CFDataRef webpData);
|
|
/**
|
Decode an image from WebP data, returns NULL if an error occurs.
|
|
@param webpData The WebP data.
|
@param decodeForDisplay If YES, this method will decode the image and convert it
|
to BGRA8888 (premultiplied) format for CALayer display.
|
@param useThreads YES to enable multi-thread decode.
|
(speed up, but cost more CPU)
|
@param bypassFiltering YES to skip the in-loop filtering.
|
(speed up, but may lose some smooth)
|
@param noFancyUpsampling YES to use faster pointwise upsampler.
|
(speed down, and may lose some details).
|
@return The decoded image, or NULL if an error occurs.
|
*/
|
CG_EXTERN CGImageRef _Nullable YYCGImageCreateWithWebPData(CFDataRef webpData,
|
BOOL decodeForDisplay,
|
BOOL useThreads,
|
BOOL bypassFiltering,
|
BOOL noFancyUpsampling);
|
|
typedef NS_ENUM(NSUInteger, YYImagePreset) {
|
YYImagePresetDefault = 0, ///< default preset.
|
YYImagePresetPicture, ///< digital picture, like portrait, inner shot
|
YYImagePresetPhoto, ///< outdoor photograph, with natural lighting
|
YYImagePresetDrawing, ///< hand or line drawing, with high-contrast details
|
YYImagePresetIcon, ///< small-sized colorful images
|
YYImagePresetText ///< text-like
|
};
|
|
/**
|
Encode a CGImage to WebP data
|
|
@param imageRef image
|
@param lossless YES=lossless (similar to PNG), NO=lossy (similar to JPEG)
|
@param quality 0.0~1.0 (0=smallest file, 1.0=biggest file)
|
For lossless image, try the value near 1.0; for lossy, try the value near 0.8.
|
@param compressLevel 0~6 (0=fast, 6=slower-better). Default is 4.
|
@param preset Preset for different image type, default is YYImagePresetDefault.
|
@return WebP data, or nil if an error occurs.
|
*/
|
CG_EXTERN CFDataRef _Nullable YYCGImageCreateEncodedWebPData(CGImageRef imageRef,
|
BOOL lossless,
|
CGFloat quality,
|
int compressLevel,
|
YYImagePreset preset);
|
|
NS_ASSUME_NONNULL_END
|
