Decode GIF image frames on demand.

Source/core/platform/graphics/ImageSource.h

 /*
  * Copyright (C) 2004, 2005, 2006 Apple Computer, Inc.  All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
@@ skipping 61 matching lines @@
     };
 
     enum GammaAndColorProfileOption {
         GammaAndColorProfileApplied,
         GammaAndColorProfileIgnored
     };
 
     ImageSource(AlphaOption alphaOption = AlphaPremultiplied, GammaAndColorProfileOption gammaAndColorProfileOption = GammaAndColorProfileApplied);
     ~ImageSource();
 
     // Tells the ImageSource that the Image no longer cares about decoded frame

[Peter Kasting, 2013/05/29 02:02:18]

Nit: How about this comment:

Tells the ImageSource that the Image no longer cares about decoded frame data
except for the specified frame.  Callers may pass WTF::notFound to clear all
frames.

In response, the ImageSource should delete cached decoded data for other frames
where possible to keep memory use low.  The expectation is that in the future,
the caller may call createFrameAtIndex() with an index larger than the one
passed to this function, and the implementation may then make use of the
preserved frame data here in decoding that frame.  By contrast, callers who call
this function and then later ask for an earlier frame may require more work to
be done, e.g. redecoding the image from the beginning.

Implementations may elect to preserve more frames than the one requested here if
doing so is likely to save CPU time in the future, but will pay an increased
memory cost to do so.

Returns the number of bytes of frame data actually cleared.

[Xianzhu, 2013/05/29 18:37:01]

Done.

-    // data -- at all (if |destroyAll| is true), or before frame
-    // |clearBeforeFrame| (if |destroyAll| is false).  The ImageSource should
-    // delete cached decoded data for these frames where possible to keep memory
-    // usage low.  When |destroyAll| is true, the ImageSource should also reset
-    // any local state so that decoding can begin again.
+    // data except the specified frame (|notFound| to clear all frames).
+    // The ImageSource should delete cached decoded data for these frames
+    // where possible to keep memory usage low.
     //
-    // Implementations that delete less than what's specified above waste
+    // The caller is supposed to request for a frame on/after the provided frame
+    // index after this call. If the caller violate this by clearing and then
+    // requesting a frame before the provided frame number, the decoder may need
+    // to redecode the image from the beginning.
+    //
+    // Implementations that delete less than what's specified above may waste
     // memory.  Implementations that delete more may burn CPU re-decoding frames
     // that could otherwise have been cached, or encounter errors if they're
     // asked to decode frames they can't decode due to the loss of previous
     // decoded frames.
     //
-    // Callers should not call clear(false, n) and subsequently call
-    // createFrameAtIndex(m) with m < n, unless they first call clear(true).
-    // This ensures that stateful ImageSources/decoders will work properly.
-    //
-    // The |data| and |allDataReceived| parameters should be supplied by callers
-    // who set |destroyAll| to true if they wish to be able to continue using
-    // the ImageSource.  This way implementations which choose to destroy their
-    // decoders in some cases can reconstruct them correctly.
-    void clear(bool destroyAll,
-               size_t clearBeforeFrame = 0,
-               SharedBuffer* data = NULL,
-               bool allDataReceived = false);
+    // Returns number of bytes of the cleared frames.
+    size_t clearCacheExceptFrame(size_t);
 
     bool initialized() const;
 
     void setData(SharedBuffer* data, bool allDataReceived);
     String filenameExtension() const;
 
     bool isSizeAvailable();
     IntSize size(RespectImageOrientationEnum = DoNotRespectImageOrientation) const;
     IntSize frameSizeAtIndex(size_t, RespectImageOrientationEnum = DoNotRespectImageOrientation) const;
 
     bool getHotSpot(IntPoint&) const;
 
     size_t bytesDecodedToDetermineProperties() const;
 
     int repetitionCount();
 
     size_t frameCount() const;
 
     // Callers should not call this after calling clear() with a higher index;
     // see comments on clear() above.

[Peter Kasting, 2013/05/29 02:02:18]

Nit: This comment should be removed.

[Xianzhu, 2013/05/29 18:37:01]

Done.

     PassNativeImagePtr createFrameAtIndex(size_t);
 
     float frameDurationAtIndex(size_t) const;
     bool frameHasAlphaAtIndex(size_t) const; // Whether or not the frame actually used any alpha.
     bool frameIsCompleteAtIndex(size_t) const; // Whether or not the frame is fully received.
     ImageOrientation orientationAtIndex(size_t) const; // EXIF image orientation
 
     // Return the number of bytes in the decoded frame. If the frame is not yet
     // decoded then return 0.
     unsigned frameBytesAtIndex(size_t) const;
 
     void reportMemoryUsage(MemoryObjectInfo*) const;
 
 private:
     OwnPtr<NativeImageDecoderPtr> m_decoder;
 
     AlphaOption m_alphaOption;
     GammaAndColorProfileOption m_gammaAndColorProfileOption;
 };
 
 }
 
 #endif