Add support for multiple frames in SkCodec

include/codec/SkCodec.h

Index: include/codec/SkCodec.h
diff --git a/include/codec/SkCodec.h b/include/codec/SkCodec.h
index 363347dd72c08f0e05f97433bf9a5da473df05ea..664dc561080bb39a76c8d09a35b6cb19fad8a0a7 100644
--- a/include/codec/SkCodec.h
+++ b/include/codec/SkCodec.h
@@ -220,6 +220,38 @@ public:
     };
 
     /**
+     *  Additional options that only apply to multiframe images.
+     */
+    struct MultiFrameOptions {

[msarett, 2016/09/26 14:13:13]

I like how this looks, but don't feel strongly.  Might be convenient to have
this is a struct if we decide to add/remove multi-frame options.

Also might be nice to do something similar for "ColorTableOptions".

[scroggo, 2016/09/26 15:51:43]

+1

+        MultiFrameOptions()
+            : fIndex(0)
+            , fHasPriorFrame(false)
+        {}
+
+        /**
+         *  The frame to decode.
+         */
+        size_t fIndex;
+
+        /**
+         *  If true, the dst already contains the prior frame.
+         *
+         *  If fIndex needs to be blended with a prior frame (as reported by
+         *  getRequiredFrame(fIndex)), the client can set this to either
+         *  true or false:
+         *
+         *  true means that the prior frame is already in the dst, and this
+         *  codec only needs to decode fIndex and blend it with the dst.
+         *  Options.fZeroInitialized is ignored in this case.
+         *
+         *  false means that the dst does not contain the prior frame, so this
+         *  codec needs to first decode the prior frame (which in turn may need
+         *  to decode its prior frame).
+         */
+        bool   fHasPriorFrame;
+    };
+
+    /**
      *  Whether or not the memory passed to getPixels is zero initialized.
      */
     enum ZeroInitialized {
@@ -243,10 +275,11 @@ public:
     struct Options {
         Options()
             : fZeroInitialized(kNo_ZeroInitialized)
-            , fSubset(NULL)
+            , fSubset(nullptr)
+            , fFrameOptions(nullptr)
         {}
 
-        ZeroInitialized fZeroInitialized;
+        ZeroInitialized     fZeroInitialized;
         /**
          *  If not NULL, represents a subset of the original image to decode.
          *  Must be within the bounds returned by getInfo().
@@ -264,7 +297,14 @@ public:
          *  subset left and subset width to decode partial scanlines on calls
          *  to getScanlines().
          */
-        SkIRect*        fSubset;
+        SkIRect*            fSubset;
+
+        /**
+         *  Options that are only relevant for multi-frame images.
+         *
+         *  Unowned pointer.
+         */
+        MultiFrameOptions*  fFrameOptions;
     };
 
     /**
@@ -566,6 +606,40 @@ public:
      */
     int outputScanline(int inputScanline) const;
 
+    /**
+     *  Return the number of frames in the image.
+     *
+     *  May require reading through the stream to determine the number of
+     *  frames.
+     *
+     *  As such, future decoding calls may require a rewind.
+     */
+    size_t getFrameCount() {
+        return this->onGetFrameCount();
+    }
+
+    // The required frame for an independent frame is marked as
+    // kIndependentFrame.
+    static constexpr size_t kIndependentFrame = static_cast<size_t>(-1);
+
+    /**
+     *  For a multiframed image, return the image that frame |index| needs to
+     *  be blended with.
+     *
+     *  If the frame needs no blending, return kIndependentFrame.
+     */
+    size_t getRequiredFrame(size_t index) {
+        return this->onGetRequiredFrame(index);
+    }
+
+    /**
+     *  For a multiframed image, return the number of 1/100 seconds to
+     *  show frame |index|.
+     */
+    size_t getFrameDuration(size_t index) {
+        return this->onGetFrameDuration(index);
+    }
+
 protected:
     /**
      *  Takes ownership of SkStream*
@@ -706,6 +780,18 @@ protected:
 
     virtual int onOutputScanline(int inputScanline) const;
 
+    virtual size_t onGetFrameCount() {
+        return 1;
+    }
+
+    virtual size_t onGetRequiredFrame(size_t) {
+        return kIndependentFrame;
+    }
+
+    virtual size_t onGetFrameDuration(size_t) {
+        return 0;
+    }
+
     /**
      *  Used for testing with qcms.
      *  FIXME: Remove this when we are done comparing with qcms.