SDAnimatedImagePlayer

@interface SDAnimatedImagePlayer : NSObject

A player to control the playback of animated image, which can be used to drive Animated ImageView or any rendering usage, like CALayer/WatchKit/SwiftUI rendering.

  • Current playing frame image. This value is KVO Compliance.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) UIImage *currentFrame;

    Swift

    var currentFrame: UIImage? { get }
  • Current frame index, zero based. This value is KVO Compliance.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger currentFrameIndex;

    Swift

    var currentFrameIndex: UInt { get }
  • Current loop count since its latest animating. This value is KVO Compliance.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger currentLoopCount;

    Swift

    var currentLoopCount: UInt { get }
  • Total frame count for animated image rendering. Defaults is animated image’s frame count.

    Note

    For progressive animation, you can update this value when your provider receive more frames.

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger totalFrameCount;

    Swift

    var totalFrameCount: UInt { get set }
  • Total loop count for animated image rendering. Default is animated image’s loop count.

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger totalLoopCount;

    Swift

    var totalLoopCount: UInt { get set }
  • The animation playback rate. Default is 1.0 1.0 means the normal speed. 0.0 means stopping the animation. 0.0-1.0 means the slow speed. > 1.0 means the fast speed. < 0.0 is not supported currently and stop animation. (may support reverse playback in the future)

    Declaration

    Objective-C

    @property (nonatomic) double playbackRate;

    Swift

    var playbackRate: Double { get set }
  • Provide a max buffer size by bytes. This is used to adjust frame buffer count and can be useful when the decoding cost is expensive (such as Animated WebP software decoding). Default is 0. 0 means automatically adjust by calculating current memory usage. 1 means without any buffer cache, each of frames will be decoded and then be freed after rendering. (Lowest Memory and Highest CPU) NSUIntegerMax means cache all the buffer. (Lowest CPU and Highest Memory)

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger maxBufferSize;

    Swift

    var maxBufferSize: UInt { get set }
  • You can specify a runloop mode to let it rendering. Default is NSRunLoopCommonModes on multi-core device, NSDefaultRunLoopMode on single-core device

    Declaration

    Objective-C

    @property (copy, nonatomic, nonnull) NSRunLoopMode runLoopMode;

    Swift

    var runLoopMode: RunLoop.Mode { get set }
  • Create a player with animated image provider. If the provider’s animatedImageFrameCount is less than 1, returns nil. The provider can be any protocol implementation, like SDAnimatedImage, SDImageGIFCoder, etc.

    Note

    This provider can represent mutable content, like progressive animated loading. But you need to update the frame count by yourself

    Declaration

    Objective-C

    - (nullable instancetype)initWithProvider:
        (nonnull id<SDAnimatedImageProvider>)provider;

    Swift

    init?(provider: SDAnimatedImageProvider)

    Parameters

    provider

    The animated provider

  • Create a player with animated image provider. If the provider’s animatedImageFrameCount is less than 1, returns nil. The provider can be any protocol implementation, like SDAnimatedImage or SDImageGIFCoder, etc.

    Note

    This provider can represent mutable content, like progressive animated loading. But you need to update the frame count by yourself

    Declaration

    Objective-C

    + (nullable instancetype)playerWithProvider:
        (nonnull id<SDAnimatedImageProvider>)provider;

    Parameters

    provider

    The animated provider

  • The handler block when current frame and index changed.

    Declaration

    Objective-C

    @property (copy, nonatomic, nullable) void (^) (NSUInteger, UIImage *_Nonnull) animationFrameHandler;

    Swift

    var animationFrameHandler: ((UInt, UIImage) -> Void)? { get set }
  • The handler block when one loop count finished.

    Declaration

    Objective-C

    @property (copy, nonatomic, nullable) void (^)(NSUInteger) animationLoopHandler;

    Swift

    var animationLoopHandler: ((UInt) -> Void)? { get set }
  • Return the status whether animation is playing.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL isPlaying;

    Swift

    var isPlaying: Bool { get }
  • Start the animation. Or resume the previously paused animation.

    Declaration

    Objective-C

    - (void)startPlaying;

    Swift

    func startPlaying()
  • Pause the animation. Keep the current frame index and loop count.

    Declaration

    Objective-C

    - (void)pausePlaying;

    Swift

    func pausePlaying()
  • Stop the animation. Reset the current frame index and loop count.

    Declaration

    Objective-C

    - (void)stopPlaying;

    Swift

    func stopPlaying()
  • Seek to the desired frame index and loop count.

    Note

    This can be used for advanced control like progressive loading, or skipping specify frames.

    Declaration

    Objective-C

    - (void)seekToFrameAtIndex:(NSUInteger)index loopCount:(NSUInteger)loopCount;

    Swift

    func seekToFrame(at index: UInt, loopCount: UInt)

    Parameters

    index

    The frame index

    loopCount

    The loop count

  • Clear the frame cache buffer. The frame cache buffer size can be controlled by maxBufferSize. By default, when stop or pause the animation, the frame buffer is still kept to ready for the next restart

    Declaration

    Objective-C

    - (void)clearFrameBuffer;

    Swift

    func clearFrameBuffer()