SDImageCoder

@protocol SDImageCoder <NSObject>

This is the image coder protocol to provide custom image decoding/encoding. These methods are all required to implement.

Note

Pay attention that these methods are not called from main queue.

Decoding

  • Returns YES if this coder can decode some data. Otherwise, the data should be passed to another coder.

    Declaration

    Objective-C

    - (BOOL)canDecodeFromData:(nullable NSData *)data;

    Swift

    func canDecode(from data: Data?) -> Bool

    Parameters

    data

    The image data so we can look at it

    Return Value

    YES if this coder can decode the data, NO otherwise

  • Decode the image data to image.

    Note

    This protocol may supports decode animated image frames. You can use +[SDImageCoderHelper animatedImageWithFrames:] to produce an animated image with frames.

    Declaration

    Objective-C

    - (nullable UIImage *)decodedImageWithData:(nullable NSData *)data
                                       options:
                                           (nullable SDImageCoderOptions *)options;

    Swift

    func decodedImage(with data: Data?, options: [SDImageCoderOption : Any]? = nil) -> UIImage?

    Parameters

    data

    The image data to be decoded

    options

    A dictionary containing any decoding options. Pass @{SDImageCoderDecodeScaleFactor: @(1.0)} to specify scale factor for image. Pass @{SDImageCoderDecodeFirstFrameOnly: @(YES)} to decode the first frame only.

    Return Value

    The decoded image from data

Encoding

  • Returns YES if this coder can encode some image. Otherwise, it should be passed to another coder. For custom coder which introduce new image format, you’d better define a new SDImageFormat using like this. If you’re creating public coder plugin for new image format, also update https://github.com/rs/SDWebImage/wiki/Coder-Plugin-List to avoid same value been defined twice.

    • “` static const SDImageFormat SDImageFormatHEIF = 10;

    Declaration

    Objective-C

    - (BOOL)canEncodeToFormat:(SDImageFormat)format;

    Swift

    func canEncode(to format: SDImageFormat) -> Bool

    Parameters

    format

    The image format

    Return Value

    YES if this coder can encode the image, NO otherwise

  • Encode the image to image data.

    Note

    This protocol may supports encode animated image frames. You can use +[SDImageCoderHelper framesFromAnimatedImage:] to assemble an animated image with frames.

    Declaration

    Objective-C

    - (nullable NSData *)encodedDataWithImage:(nullable UIImage *)image
                                       format:(SDImageFormat)format
                                      options:
                                          (nullable SDImageCoderOptions *)options;

    Swift

    func encodedData(with image: UIImage?, format: SDImageFormat, options: [SDImageCoderOption : Any]? = nil) -> Data?

    Parameters

    image

    The image to be encoded

    format

    The image format to encode, you should note SDImageFormatUndefined format is also possible

    options

    A dictionary containing any encoding options. Pass @{SDImageCoderEncodeCompressionQuality: @(1)} to specify compression quality.

    Return Value

    The encoded image data