SDWebImageOptions

enum SDWebImageOptions {}

WebCache options

  • By default, when a URL fail to be downloaded, the URL is blacklisted so the library won’t keep trying. This flag disable this blacklisting.

    Declaration

    Objective-C

    SDWebImageRetryFailed = 1 << 0

    Swift

    static var retryFailed: SDWebImageOptions { get }
  • By default, image downloads are started during UI interactions, this flags disable this feature, leading to delayed download on UIScrollView deceleration for instance.

    Declaration

    Objective-C

    SDWebImageLowPriority = 1 << 1

    Swift

    static var lowPriority: SDWebImageOptions { get }
  • This flag enables progressive download, the image is displayed progressively during download as a browser would do. By default, the image is only displayed once completely downloaded.

    Declaration

    Objective-C

    SDWebImageProgressiveLoad = 1 << 2

    Swift

    static var progressiveLoad: SDWebImageOptions { get }
  • Even if the image is cached, respect the HTTP response cache control, and refresh the image from remote location if needed. The disk caching will be handled by NSURLCache instead of SDWebImage leading to slight performance degradation. This option helps deal with images changing behind the same request URL, e.g. Facebook graph api profile pics. If a cached image is refreshed, the completion block is called once with the cached image and again with the final image.

    Use this flag only if you can’t make your URLs static with embedded cache busting parameter.

    Declaration

    Objective-C

    SDWebImageRefreshCached = 1 << 3

    Swift

    static var refreshCached: SDWebImageOptions { get }
  • In iOS 4+, continue the download of the image if the app goes to background. This is achieved by asking the system for extra time in background to let the request finish. If the background task expires the operation will be cancelled.

    Declaration

    Objective-C

    SDWebImageContinueInBackground = 1 << 4

    Swift

    static var continueInBackground: SDWebImageOptions { get }
  • Handles cookies stored in NSHTTPCookieStore by setting NSMutableURLRequest.HTTPShouldHandleCookies = YES;

    Declaration

    Objective-C

    SDWebImageHandleCookies = 1 << 5

    Swift

    static var handleCookies: SDWebImageOptions { get }
  • Enable to allow untrusted SSL certificates. Useful for testing purposes. Use with caution in production.

    Declaration

    Objective-C

    SDWebImageAllowInvalidSSLCertificates = 1 << 6

    Swift

    static var allowInvalidSSLCertificates: SDWebImageOptions { get }
  • By default, images are loaded in the order in which they were queued. This flag moves them to the front of the queue.

    Declaration

    Objective-C

    SDWebImageHighPriority = 1 << 7

    Swift

    static var highPriority: SDWebImageOptions { get }
  • By default, placeholder images are loaded while the image is loading. This flag will delay the loading of the placeholder image until after the image has finished loading.

    Declaration

    Objective-C

    SDWebImageDelayPlaceholder = 1 << 8

    Swift

    static var delayPlaceholder: SDWebImageOptions { get }
  • We usually don’t apply transform on animated images as most transformers could not manage animated images. Use this flag to transform them anyway.

    Declaration

    Objective-C

    SDWebImageTransformAnimatedImage = 1 << 9

    Swift

    static var transformAnimatedImage: SDWebImageOptions { get }
  • By default, image is added to the imageView after download. But in some cases, we want to have the hand before setting the image (apply a filter or add it with cross-fade animation for instance) Use this flag if you want to manually set the image in the completion when success

    Declaration

    Objective-C

    SDWebImageAvoidAutoSetImage = 1 << 10

    Swift

    static var avoidAutoSetImage: SDWebImageOptions { get }
  • By default, images are decoded respecting their original size. This flag will scale down the images to a size compatible with the constrained memory of devices. To control the limit memory bytes, check SDImageCoderHelper.defaultScaleDownLimitBytes (Defaults to 60MB on iOS) This will actually translate to use context option .imageThumbnailPixelSize from v5.5.0 (Defaults to (3966, 3966) on iOS). Previously does not. This flags effect the progressive and animated images as well from v5.5.0. Previously does not.

    Note

    If you need detail controls, it’s better to use context option imageThumbnailPixelSize and imagePreserveAspectRatio instead.

    Declaration

    Objective-C

    SDWebImageScaleDownLargeImages = 1 << 11

    Swift

    static var scaleDownLargeImages: SDWebImageOptions { get }
  • By default, we do not query image data when the image is already cached in memory. This mask can force to query image data at the same time. However, this query is asynchronously unless you specify SDWebImageQueryMemoryDataSync

    Declaration

    Objective-C

    SDWebImageQueryMemoryData = 1 << 12

    Swift

    static var queryMemoryData: SDWebImageOptions { get }
  • By default, when you only specify SDWebImageQueryMemoryData, we query the memory image data asynchronously. Combined this mask as well to query the memory image data synchronously.

    Note

    Query data synchronously is not recommend, unless you want to ensure the image is loaded in the same runloop to avoid flashing during cell reusing.

    Declaration

    Objective-C

    SDWebImageQueryMemoryDataSync = 1 << 13

    Swift

    static var queryMemoryDataSync: SDWebImageOptions { get }
  • By default, when the memory cache miss, we query the disk cache asynchronously. This mask can force to query disk cache (when memory cache miss) synchronously.

    Note

    These 3 query options can be combined together. For the full list about these masks combination, see wiki page.

    Note

    Query data synchronously is not recommend, unless you want to ensure the image is loaded in the same runloop to avoid flashing during cell reusing.

    Declaration

    Objective-C

    SDWebImageQueryDiskDataSync = 1 << 14

    Swift

    static var queryDiskDataSync: SDWebImageOptions { get }
  • By default, when the cache missed, the image is load from the loader. This flag can prevent this to load from cache only.

    Declaration

    Objective-C

    SDWebImageFromCacheOnly = 1 << 15

    Swift

    static var fromCacheOnly: SDWebImageOptions { get }
  • By default, we query the cache before the image is load from the loader. This flag can prevent this to load from loader only.

    Declaration

    Objective-C

    SDWebImageFromLoaderOnly = 1 << 16

    Swift

    static var fromLoaderOnly: SDWebImageOptions { get }
  • By default, when you use SDWebImageTransition to do some view transition after the image load finished, this transition is only applied for image download from the network. This mask can force to apply view transition for memory and disk cache as well.

    Declaration

    Objective-C

    SDWebImageForceTransition = 1 << 17

    Swift

    static var forceTransition: SDWebImageOptions { get }
  • By default, we will decode the image in the background during cache query and download from the network. This can help to improve performance because when rendering image on the screen, it need to be firstly decoded. But this happen on the main queue by Core Animation. However, this process may increase the memory usage as well. If you are experiencing a issue due to excessive memory consumption, This flag can prevent decode the image.

    Declaration

    Objective-C

    SDWebImageAvoidDecodeImage = 1 << 18

    Swift

    static var avoidDecodeImage: SDWebImageOptions { get }
  • By default, we decode the animated image. This flag can force decode the first frame only and produce the static image.

    Declaration

    Objective-C

    SDWebImageDecodeFirstFrameOnly = 1 << 19

    Swift

    static var decodeFirstFrameOnly: SDWebImageOptions { get }
  • By default, for SDAnimatedImage, we decode the animated image frame during rendering to reduce memory usage. However, you can specify to preload all frames into memory to reduce CPU usage when the animated image is shared by lots of imageViews. This will actually trigger preloadAllAnimatedImageFrames in the background queue(Disk Cache & Download only).

    Declaration

    Objective-C

    SDWebImagePreloadAllFrames = 1 << 20

    Swift

    static var preloadAllFrames: SDWebImageOptions { get }
  • By default, when you use SDWebImageContextAnimatedImageClass context option (like using SDAnimatedImageView which designed to use SDAnimatedImage), we may still use UIImage when the memory cache hit, or image decoder is not available to produce one exactlly matching your custom class as a fallback solution. Using this option, can ensure we always callback image with your provided class. If failed to produce one, a error with code SDWebImageErrorBadImageData will been used. Note this options is not compatible with SDWebImageDecodeFirstFrameOnly, which always produce a UIImage/NSImage.

    Declaration

    Objective-C

    SDWebImageMatchAnimatedImageClass = 1 << 21

    Swift

    static var matchAnimatedImageClass: SDWebImageOptions { get }
  • By default, when we load the image from network, the image will be written to the cache (memory and disk, controlled by your storeCacheType context option) This maybe an asynchronously operation and the final SDInternalCompletionBlock callback does not guarantee the disk cache written is finished and may cause logic error. (For example, you modify the disk data just in completion block, however, the disk cache is not ready) If you need to process with the disk cache in the completion block, you should use this option to ensure the disk cache already been written when callback. Note if you use this when using the custom cache serializer, or using the transformer, we will also wait until the output image data written is finished.

    Declaration

    Objective-C

    SDWebImageWaitStoreCache = 1 << 22

    Swift

    static var waitStoreCache: SDWebImageOptions { get }
  • We usually don’t apply transform on vector images, because vector images supports dynamically changing to any size, rasterize to a fixed size will loss details. To modify vector images, you can process the vector data at runtime (such as modifying PDF tag / SVG element). Use this flag to transform them anyway.

    Declaration

    Objective-C

    SDWebImageTransformVectorImage = 1 << 23

    Swift

    static var transformVectorImage: SDWebImageOptions { get }