Constants

The following constants are available globally.

Coder Options

  • 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.

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderDecodeFirstFrameOnly

    Swift

    static let decodeFirstFrameOnly: SDImageCoderOption
  • 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)

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderDecodeScaleFactor

    Swift

    static let decodeScaleFactor: SDImageCoderOption
  • A Boolean value indicating whether to keep the original aspect ratio when generating thumbnail images (or bitmap images from vector format). Defaults to YES.

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderDecodePreserveAspectRatio

    Swift

    static let decodePreserveAspectRatio: SDImageCoderOption
  • 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.

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderDecodeThumbnailPixelSize

    Swift

    static let decodeThumbnailPixelSize: SDImageCoderOption
  • 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.

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderEncodeFirstFrameOnly

    Swift

    static let encodeFirstFrameOnly: SDImageCoderOption
  • 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

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderEncodeCompressionQuality

    Swift

    static let encodeCompressionQuality: SDImageCoderOption
  • 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

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderEncodeBackgroundColor

    Swift

    static let encodeBackgroundColor: SDImageCoderOption
  • 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

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderEncodeMaxPixelSize

    Swift

    static let encodeMaxPixelSize: SDImageCoderOption
  • 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

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderEncodeMaxFileSize

    Swift

    static let encodeMaxFileSize: SDImageCoderOption
  • 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

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderEncodeEmbedThumbnail

    Swift

    static let encodeEmbedThumbnail: SDImageCoderOption
  • 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. See SDWebImageContext for more detailed information.

    Declaration

    Objective-C

    extern SDImageCoderOption _Nonnull const SDImageCoderWebImageContext

    Swift

    static let webImageContext: SDImageCoderOption

Context Options

  • A UIImage instance from SDWebImageManager when you specify SDWebImageRefreshCached and image cache hit. This can be a hint for image loader to load the image from network and refresh the image from remote location if needed. If the image from remote location does not change, you should call the completion with SDWebImageErrorCacheNotModified error. (UIImage)

    Note

    If you don’t implement SDWebImageRefreshCached support, you do not need to care about this context option.

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextLoaderCachedImage

    Swift

    static let loaderCachedImage: SDWebImageContextOption
  • A String to be used as the operation key for view category to store the image load operation. This is used for view instance which supports different image loading process. If nil, will use the class name as operation key. (NSString *)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextSetImageOperationKey

    Swift

    static let setImageOperationKey: SDWebImageContextOption
  • A SDWebImageManager instance to control the image download and cache process using in UIImageView+WebCache category and likes. If not provided, use the shared manager (SDWebImageManager *) @deprecated Deprecated in the future. This context options can be replaced by other context option control like .imageCache, .imageLoader, .imageTransformer (See below), which already matches all the properties in SDWebImageManager.

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextCustomManager

    Swift

    static let customManager: SDWebImageContextOption
  • A id instance which conforms to SDImageCache protocol. It’s used to override the image manager’s cache during the image loading pipeline. In other word, if you just want to specify a custom cache during image loading, you don’t need to re-create a dummy SDWebImageManager instance with the cache. If not provided, use the image manager’s cache (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImageCache

    Swift

    static let imageCache: SDWebImageContextOption
  • A id instance which conforms to SDImageLoader protocol. It’s used to override the image manager’s loader during the image loading pipeline. In other word, if you just want to specify a custom loader during image loading, you don’t need to re-create a dummy SDWebImageManager instance with the loader. If not provided, use the image manager’s cache (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImageLoader

    Swift

    static let imageLoader: SDWebImageContextOption
  • A id instance which conforms to SDImageCoder protocol. It’s used to override the default image coder for image decoding(including progressive) and encoding during the image loading process. If you use this context option, we will not always use SDImageCodersManager.shared to loop through all registered coders and find the suitable one. Instead, we will arbitrarily use the exact provided coder without extra checking (We may not call canDecodeFromData:).

    Note

    This is only useful for cases which you can ensure the loading url matches your coder, or you find it’s too hard to write a common coder which can used for generic usage. This will bind the loading url with the coder logic, which is not always a good design, but possible. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImageCoder

    Swift

    static let imageCoder: SDWebImageContextOption
  • A id instance which conforms SDImageTransformer protocol. It’s used for image transform after the image load finished and store the transformed image to cache. If you provide one, it will ignore the transformer in manager and use provided one instead. If you pass NSNull, the transformer feature will be disabled. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImageTransformer

    Swift

    static let imageTransformer: SDWebImageContextOption
  • A CGFloat raw value which specify the image scale factor. The number should be greater than or equal to 1.0. If not provide or the number is invalid, we will use the cache key to specify the scale factor. (NSNumber)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImageScaleFactor

    Swift

    static let imageScaleFactor: SDWebImageContextOption
  • A Boolean value indicating whether to keep the original aspect ratio when generating thumbnail images (or bitmap images from vector format). Defaults to YES. (NSNumber)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImagePreserveAspectRatio

    Swift

    static let imagePreserveAspectRatio: SDWebImageContextOption
  • A CGSize raw 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 .imagePreserveAspectRatio) the value size.

    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. Defaults to CGSizeZero, which means no thumbnail generation at all. (NSValue)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextImageThumbnailPixelSize

    Swift

    static let imageThumbnailPixelSize: SDWebImageContextOption
  • A SDImageCacheType raw value which specify the source of cache to query. Specify SDImageCacheTypeDisk to query from disk cache only; SDImageCacheTypeMemory to query from memory only. And SDImageCacheTypeAll to query from both memory cache and disk cache. Specify SDImageCacheTypeNone is invalid and totally ignore the cache query. If not provide or the value is invalid, we will use SDImageCacheTypeAll. (NSNumber)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextQueryCacheType

    Swift

    static let queryCacheType: SDWebImageContextOption
  • A SDImageCacheType raw value which specify the store cache type when the image has just been downloaded and will be stored to the cache. Specify SDImageCacheTypeNone to disable cache storage; SDImageCacheTypeDisk to store in disk cache only; SDImageCacheTypeMemory to store in memory only. And SDImageCacheTypeAll to store in both memory cache and disk cache. If you use image transformer feature, this actually apply for the transformed image, but not the original image itself. Use SDWebImageContextOriginalStoreCacheType if you want to control the original image’s store cache type at the same time. If not provide or the value is invalid, we will use SDImageCacheTypeAll. (NSNumber)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextStoreCacheType

    Swift

    static let storeCacheType: SDWebImageContextOption
  • The same behavior like SDWebImageContextQueryCacheType, but control the query cache type for the original image when you use image transformer feature. This allows the detail control of cache query for these two images. For example, if you want to query the transformed image from both memory/disk cache, query the original image from disk cache only, use [.queryCacheType : .all, .originalQueryCacheType : .disk] If not provide or the value is invalid, we will use SDImageCacheTypeNone, which does not query the original image from cache. (NSNumber)

    Note

    Which means, if you set this value to not be .none, we will query the original image from cache, then do transform with transformer, instead of actual downloading, which can save bandwidth usage.

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextOriginalQueryCacheType

    Swift

    static let originalQueryCacheType: SDWebImageContextOption
  • The same behavior like SDWebImageContextStoreCacheType, but control the store cache type for the original image when you use image transformer feature. This allows the detail control of cache storage for these two images. For example, if you want to store the transformed image into both memory/disk cache, store the original image into disk cache only, use [.storeCacheType : .all, .originalStoreCacheType : .disk] If not provide or the value is invalid, we will use SDImageCacheTypeNone, which does not store the original image into cache. (NSNumber)

    Note

    This only store the original image, if you want to use the original image without downloading in next query, specify SDWebImageContextOriginalQueryCacheType as well.

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextOriginalStoreCacheType

    Swift

    static let originalStoreCacheType: SDWebImageContextOption
  • A Class object which the instance is a UIImage/NSImage subclass and adopt SDAnimatedImage protocol. We will call initWithData:scale:options: to create the instance (or initWithAnimatedCoder:scale: when using progressive download) . If the instance create failed, fallback to normal UIImage/NSImage. This can be used to improve animated images rendering performance (especially memory usage on big animated images) with SDAnimatedImageView (Class).

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextAnimatedImageClass

    Swift

    static let animatedImageClass: SDWebImageContextOption
  • A id instance to modify the image download request. It’s used for downloader to modify the original request from URL and options. If you provide one, it will ignore the requestModifier in downloader and use provided one instead. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextDownloadRequestModifier

    Swift

    static let downloadRequestModifier: SDWebImageContextOption
  • A id instance to modify the image download response. It’s used for downloader to modify the original response from URL and options. If you provide one, it will ignore the responseModifier in downloader and use provided one instead. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextDownloadResponseModifier

    Swift

    static let downloadResponseModifier: SDWebImageContextOption
  • A id instance to decrypt the image download data. This can be used for image data decryption, such as Base64 encoded image. If you provide one, it will ignore the decryptor in downloader and use provided one instead. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextDownloadDecryptor

    Swift

    static let downloadDecryptor: SDWebImageContextOption
  • A id instance to convert an URL into a cache key. It’s used when manager need cache key to use image cache. If you provide one, it will ignore the cacheKeyFilter in manager and use provided one instead. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextCacheKeyFilter

    Swift

    static let cacheKeyFilter: SDWebImageContextOption
  • A id instance to convert the decoded image, the source downloaded data, to the actual data. It’s used for manager to store image to the disk cache. If you provide one, it will ignore the cacheSerializer in manager and use provided one instead. (id)

    Declaration

    Objective-C

    extern SDWebImageContextOption _Nonnull const SDWebImageContextCacheSerializer

    Swift

    static let cacheSerializer: SDWebImageContextOption
  • Declaration

    Objective-C

    FOUNDATION_EXPORT NSNotificationName _Nonnull const SDWebImageDownloadStartNotification

    Swift

    static let SDWebImageDownloadStart: NSNotification.Name
  • Declaration

    Objective-C

    FOUNDATION_EXPORT NSNotificationName _Nonnull const SDWebImageDownloadReceiveResponseNotification

    Swift

    static let SDWebImageDownloadReceiveResponse: NSNotification.Name
  • Declaration

    Objective-C

    FOUNDATION_EXPORT NSNotificationName _Nonnull const SDWebImageDownloadStopNotification

    Swift

    static let SDWebImageDownloadStop: NSNotification.Name
  • Declaration

    Objective-C

    FOUNDATION_EXPORT NSNotificationName _Nonnull const SDWebImageDownloadFinishNotification

    Swift

    static let SDWebImageDownloadFinish: NSNotification.Name
  • Declaration

    Objective-C

    FOUNDATION_EXPORT NSErrorDomain const _Nonnull SDWebImageErrorDomain

    Swift

    let SDWebImageErrorDomain: String
  • The HTTP status code for invalid download response (NSNumber *)

    Declaration

    Objective-C

    extern NSErrorUserInfoKey _Nonnull const SDWebImageErrorDownloadStatusCodeKey

    Swift

    let SDWebImageErrorDownloadStatusCodeKey: String
  • The value specify that the image progress unit count cannot be determined because the progressBlock is not been called.

    Declaration

    Objective-C

    extern const int64_t SDWebImageProgressUnitCountUnknown

    Swift

    let SDWebImageProgressUnitCountUnknown: Int64
  • Declaration

    Objective-C

    extern double SDWebImageVersionNumber

    Swift

    var SDWebImageVersionNumber: Double
  • Declaration

    Objective-C

    extern const unsigned char SDWebImageVersionString[]