BitmapFrameCache.java

/*
 * Copyright (c) 2015-present, Facebook, Inc.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree. An additional grant
 * of patent rights can be found in the PATENTS file in the same directory.
 */
package com.facebook.fresco.animation.bitmap;

import javax.annotation.Nullable;

import android.graphics.Bitmap;

import com.facebook.common.references.CloseableReference;

/**
 * Bitmap frame cache that is used for animated images.
 */
public interface BitmapFrameCache {

  interface FrameCacheListener {

    /**
     * Called when the frame for the given frame number has been put in the frame cache.
     * @param bitmapFrameCache the frame cache that holds the frame
     * @param frameNumber the cached frame number
     */
    void onFrameCached(BitmapFrameCache bitmapFrameCache, int frameNumber);

    /**
     * Called when the frame for the given frame number has been evicted from the frame cache.
     *
     * @param bitmapFrameCache the frame cache that evicted the frame
     * @param frameNumber the frame number of the evicted frame
     */
    void onFrameEvicted(BitmapFrameCache bitmapFrameCache, int frameNumber);
  }

  /**
   * Get the cached frame for the given frame number.
   *
   * @param frameNumber the frame number to get the cached frame for
   * @return the cached frame or null if not cached
   */
  @Nullable
  CloseableReference<Bitmap> getCachedFrame(int frameNumber);

  /**
   * Get a fallback frame for the given frame number. This method is called if all other attempts
   * to draw a frame failed.
   * The bitmap returned could for example be the last drawn frame (if any).
   *
   * @param frameNumber the frame number to get the fallback
   * @return the fallback frame or null if not cached
   */
  @Nullable
  CloseableReference<Bitmap> getFallbackFrame(int frameNumber);

  /**
   * Return a reusable bitmap that should be used to render the given frame.
   *
   * @param frameNumber the frame number to be rendered
   * @param width the width of the target bitmap
   * @param height the height of the target bitmap
   * @return the reusable bitmap or null if no reusable bitmaps available
   */
  @Nullable
  CloseableReference<Bitmap> getBitmapToReuseForFrame(int frameNumber, int width, int height);

  /**
   * Check whether the cache contains a certain frame.
   *
   * @param frameNumber the frame number to check
   * @return true if the frame is cached
   */
  boolean contains(int frameNumber);

  /**
   * @return the size in bytes of all cached data
   */
  int getSizeInBytes();

  /**
   * Clear the cache.
   */
  void clear();

  /**
   * Callback when the given bitmap has been drawn to a canvas.
   * This bitmap can either be a reused bitmap returned by
   * {@link #getBitmapToReuseForFrame(int, int, int)} or a new bitmap.
   *
   * Note: the implementation of this interface must manually clone the given bitmap reference
   * if it wants to hold on to the bitmap.
   * The original reference will be automatically closed after this call.
   *
   * @param frameNumber the frame number that has been rendered
   * @param bitmapReference the bitmap reference that has been rendered
   * @param frameType the frame type that has been rendered
   */
  void onFrameRendered(
      int frameNumber,
      CloseableReference<Bitmap> bitmapReference,
      @BitmapAnimationBackend.FrameType int frameType);

  /**
   * Callback when a bitmap reference for a given frame has been prepared for future rendering.
   *
   * This method is called ahead of render time (i.e. when future frames have been prepared
   * in the background), whereas {@link #onFrameRendered(int, CloseableReference, int)}
   * is invoked when the actual frame has been drawn on a Canvas.
   *
   * The supplied bitmap reference can either hold a reused bitmap returned by
   * {@link #getBitmapToReuseForFrame(int, int, int)} or a new bitmap as indicated by the
   * frame type parameter.
   *
   * Note: the implementation of this interface must manually clone the given bitmap reference
   * if it wants to hold on to the bitmap.
   * The original reference will be automatically closed after this call.
   *
   * @param frameNumber the frame number of the passed bitmapReference
   * @param bitmapReference the bitmap reference that has been prepared for future rendering
   * @param frameType the frame type of the prepared frame
   * @return true if the frame has been successfully cached
   */
  void onFramePrepared(
      int frameNumber,
      CloseableReference<Bitmap> bitmapReference,
      @BitmapAnimationBackend.FrameType int frameType);

  /**
   * Set a frame cache listener that gets notified about caching events.
   *
   * @param frameCacheListener the listener to use
   */
  void setFrameCacheListener(FrameCacheListener frameCacheListener);
}