diff --git a/FastImageCache/FICImageCache.h b/FastImageCache/FICImageCache.h index 4110f5a..d648b3f 100644 --- a/FastImageCache/FICImageCache.h +++ b/FastImageCache/FICImageCache.h @@ -162,6 +162,20 @@ typedef void (^FICImageRequestCompletionBlock)(UIImage *sourceImage); */ - (void)deleteImageForEntity:(id )entity withFormatName:(NSString *)formatName; +///------------------------------- +/// @name Canceling Image Requests +///------------------------------- + +/** + Cancels an active request for an image from the image cache. + + @param entity The entity that uniquely identifies the source image. + + @param formatName The format name that uniquely identifies which image table to look in for the cached image. + + @discussion After this method is called, the completion block of the <[FICImageCacheDelegate imageCache:wantsSourceImageForEntity:withFormatName:completionBlock:]> delegate + method for the corresponding entity, if called, does nothing. + */ - (void)cancelImageRetrievalForEntity:(id )entity withFormatName:(NSString *)formatName; ///----------------------------------- @@ -229,9 +243,22 @@ typedef void (^FICImageRequestCompletionBlock)(UIImage *sourceImage); @optional +/** + This method is called on the delegate when the image cache has received an image retrieval cancellation request. + + @param imageCache The image cache that has received the image retrieval cancellation request. + + @param entity The entity that uniquely identifies the source image. + + @param formatName The format name that uniquely identifies which image table to look in for the cached image. + + @discussion When an image retrieval cancellation request is made to the image cache, it removes all of its internal bookkeeping for requests. However, it is still the + delegate's responsibility to cancel whatever logic is it performing to provide a source image to the cache (e.g., a network request). + + @see [FICImageCache cancelImageRetrievalForEntity:withFormatName:] + */ - (void)imageCache:(FICImageCache *)imageCache cancelImageLoadingForEntity:(id )entity withFormatName:(NSString *)formatName; - /** This method is called on the delegate to determine whether or not all formats in a family should be processed right now. diff --git a/FastImageCache/FICImageFormat.h b/FastImageCache/FICImageFormat.h index 885cb67..66612dd 100644 --- a/FastImageCache/FICImageFormat.h +++ b/FastImageCache/FICImageFormat.h @@ -15,13 +15,6 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatDevices) { FICImageFormatDevicePad = 1 << UIUserInterfaceIdiomPad, }; -/** - `FICImageFormat` acts as a definition for the types of images that are stored in the image cache. Each image format must have a unique name, but multiple formats can belong to the same family. - All images associated with a particular format must have the same image dimentions and opacity preference. You can define the maximum number of entries that an image format can accommodate to - prevent the image cache from consuming too much disk space. Each `` managed by the image cache is associated with a single image format. - */ - - typedef NS_OPTIONS(NSUInteger, FICImageFormatStyle) { FICImageFormatStyle32BitBGRA, FICImageFormatStyle32BitBGR, @@ -29,6 +22,12 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatStyle) { FICImageFormatStyle8BitGrayscale, }; +/** + `FICImageFormat` acts as a definition for the types of images that are stored in the image cache. Each image format must have a unique name, but multiple formats can belong to the same family. + All images associated with a particular format must have the same image dimentions and opacity preference. You can define the maximum number of entries that an image format can accommodate to + prevent the image cache from consuming too much disk space. Each `` managed by the image cache is associated with a single image format. + */ + @interface FICImageFormat : NSObject ///------------------------------ @@ -61,17 +60,21 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatStyle) { @property (nonatomic, assign) CGSize imageSize; /** - The size, in pixels, of the images stored in the image table created by this format. This takes into account the screen scale. + A bitmask of type `` that defines the style of the image format. + + `FICImageFormatStyle` has the following values: + + - `FICImageFormatStyle32BitBGRA`: Full-color image format with alpha channel. 8 bits per color component, and 8 bits for the alpha channel. + - `FICImageFormatStyle32BitBGR`: Full-color image format with no alpha channel. 8 bits per color component. The remaining 8 bits are unused. + - `FICImageFormatStyle16BitBGR`: Reduced-color image format with no alpha channel. 5 bits per color component. The remaining bit is unused. + - `FICImageFormatStyle8BitGrayscale`: Grayscale-only image format with no alpha channel. + + If you are storing images without an alpha component (e.g., JPEG images), then you should use the `FICImageFormatStyle32BitBGR` style for performance reasons. If you are storing very small images or images + without a great deal of color complexity, the `FICImageFormatStyle16BitBGR` style may be sufficient and uses less disk space than the 32-bit styles use. For grayscale-only image formats, the + `FICImageFormatStyle8BitGrayscale` style is sufficient and further reduces disk space usage. */ -@property (nonatomic, assign, readonly) CGSize pixelSize; - @property (nonatomic, assign) FICImageFormatStyle style; -@property (nonatomic, readonly) CGBitmapInfo bitmapInfo; -@property (nonatomic, readonly) NSInteger bytesPerPixel; -@property (nonatomic, readonly) NSInteger bitsPerComponent; -@property (nonatomic, readonly) BOOL isGrayscale; - /** The maximum number of entries that an image table can contain for this image format. @@ -86,6 +89,31 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatStyle) { */ @property (nonatomic, assign) FICImageFormatDevices devices; +/** + The size, in pixels, of the images stored in the image table created by this format. This takes into account the screen scale. + */ +@property (nonatomic, assign, readonly) CGSize pixelSize; + +/** + The bitmap info associated with the images created with this image format. + */ +@property (nonatomic, assign, readonly) CGBitmapInfo bitmapInfo; + +/** + The number of bytes each pixel of an image created with this image format occupies. + */ +@property (nonatomic, assign, readonly) NSInteger bytesPerPixel; + +/** + The number of bits each pixel component (e.g., blue, green, red color channels) uses for images created with this image format. + */ +@property (nonatomic, assign, readonly) NSInteger bitsPerComponent; + +/** + Whether or not the the images represented by this image format are grayscale. + */ +@property (nonatomic, assign, readonly) BOOL isGrayscale; + /** The dictionary representation of this image format. @@ -106,7 +134,7 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatStyle) { @param imageSize The size, in points, of the images stored in the image table created by this format. - @param isOpaque Whether or not the image table's backing bitmap data provider is opaque. + @param style The style of the image format. See the `