Add support for multiple frames in SkCodec

include/codec/SkCodec.h

 /*
  * Copyright 2015 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkCodec_DEFINED
 #define SkCodec_DEFINED
 
 #include "../private/SkTemplates.h"
 #include "SkColor.h"
 #include "SkEncodedFormat.h"
 #include "SkEncodedInfo.h"
 #include "SkImageInfo.h"
 #include "SkSize.h"
 #include "SkStream.h"
 #include "SkTypes.h"
 #include "SkYUVSizeInfo.h"
 
+#include <vector>
+
 class SkColorSpace;
 class SkData;
 class SkPngChunkReader;
 class SkSampler;
 
 namespace DM {
 class CodecSrc;
 class ColorCodecSrc;
 }
 class ColorCodecBench;
@@ skipping 182 matching lines @@
          */
         kCouldNotRewind,
         /**
          *  This method is not implemented by this codec.
          *  FIXME: Perhaps this should be kUnsupported?
          */
         kUnimplemented,
     };
 
     /**
+     *  Additional options that only apply to multiframe images.
+     */
+    struct MultiFrameOptions {
+        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
+         *  getFrameInfo[fIndex].fRequiredFrame), 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 {
         /**
          *  The memory passed to getPixels is zero initialized. The SkCodec
          *  may take advantage of this by skipping writing zeroes.
          */
         kYes_ZeroInitialized,
         /**
          *  The memory passed to getPixels has not been initialized to zero,
          *  so the SkCodec must write all zeroes to memory.
          *
          *  This is the default. It will be used if no Options struct is used.
          */
         kNo_ZeroInitialized,
     };
 
     /**
      *  Additional options to pass to getPixels.
      */
     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().
          *  If the EncodedFormat is kWEBP_SkEncodedFormat (the only one which
          *  currently supports subsets), the top and left values must be even.
          *
          *  In getPixels and incremental decode, we will attempt to decode the
          *  exact rectangular subset specified by fSubset.
          *
          *  In a scanline decode, it does not make sense to specify a subset
          *  top or subset height, since the client already controls which rows
          *  to get and which rows to skip.  During scanline decodes, we will
          *  require that the subset top be zero and the subset height be equal
          *  to the full height.  We will, however, use the values of
          *  subset left and subset width to decode partial scanlines on calls
          *  to getScanlines().
          */
-        SkIRect*        fSubset;
+        const SkIRect*              fSubset;
+
+        /**
+         *  Options that are only relevant for multi-frame images.
+         *
+         *  Unowned pointer.
+         */
+        const MultiFrameOptions*    fFrameOptions;
     };
 
     /**
      *  Decode into the given pixels, a block of memory of size at
      *  least (info.fHeight - 1) * rowBytes + (info.fWidth *
      *  bytesPerPixel)
      *
      *  Repeated calls to this function should give the same results,
      *  allowing the PixelRef to be immutable.
      *
@@ skipping 237 matching lines @@
          * For subset decodes and sampling, it is simplest to get and skip
          * scanlines one at a time, using the nextScanline() API.  It is
          * possible to ask for larger chunks at a time, but this should be used
          * with caution.  As with full image decodes, the decoder will handle
          * inverting the requested rows, but rows will still be delivered
          * starting from the bottom of the image.
          *
          * Upside down bmps are an example.
          */
         kBottomUp_SkScanlineOrder,
-
-        /*
-         * This indicates that the scanline decoder reliably outputs rows, but
-         * they will not be in logical order.  If the scanline format is
-         * kOutOfOrder, the nextScanline() API should be used to determine the
-         * actual y-coordinate of the next output row.
-         *
-         * For this scanline ordering, it is advisable to get and skip
-         * scanlines one at a time.
-         *
-         * Interlaced gifs are an example.
-         */
-        kOutOfOrder_SkScanlineOrder,
     };
 
     /**
      *  An enum representing the order in which scanlines will be returned by
      *  the scanline decoder.
      *
      *  This is undefined before startScanlineDecode() is called.
      */
     SkScanlineOrder getScanlineOrder() const { return this->onGetScanlineOrder(); }
 
     /**
      *  Returns the y-coordinate of the next row to be returned by the scanline
      *  decoder.
      *
      *  This will equal fCurrScanline, except in the case of strangely
-     *  encoded image types (bottom-up bmps, interlaced gifs).
+     *  encoded image types (bottom-up bmps).
      *
      *  Results are undefined when not in scanline decoding mode.
      */
     int nextScanline() const { return this->outputScanline(fCurrScanline); }
 
     /**
      *  Returns the output y-coordinate of the row that corresponds to an input
      *  y-coordinate.  The input y-coordinate represents where the scanline
      *  is located in the encoded data.
      *
      *  This will equal inputScanline, except in the case of strangely
      *  encoded image types (bottom-up bmps, interlaced gifs).
      */
     int outputScanline(int inputScanline) const;
 
+    // The required frame for an independent frame is marked as
+    // kIndependentFrame.
+    static constexpr size_t kIndependentFrame = static_cast<size_t>(-1);
+
+    /**
+     *  Information about individual frames in a multi-framed image.
+     */
+    struct FrameInfo {
+        /**
+         *  The frame that this frame needs to be blended with, or
+         *  kIndependentFrame.
+         */
+        size_t fRequiredFrame;
+
+        /**
+         *  Number of milliseconds to show this frame.
+         */
+        size_t fDuration;
+    };
+
+    /**
+     *  Return info about the 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.
+     *
+     *  For single-frame images, this will return an empty vector.
+     */
+    std::vector<FrameInfo> getFrameInfo() {
+        return this->onGetFrameInfo();
+    }
+
 protected:
     /**
      *  Takes ownership of SkStream*
      */
     SkCodec(int width,
             int height,
             const SkEncodedInfo&,
             SkStream*,
             sk_sp<SkColorSpace> = nullptr,
             Origin = kTopLeft_Origin);
@@ skipping 120 matching lines @@
     /**
      *  Returns the number of scanlines that have been decoded so far.
      *  This is unaffected by the SkScanlineOrder.
      *
      *  Returns -1 if we have not started a scanline decode.
      */
     int currScanline() const { return fCurrScanline; }
 
     virtual int onOutputScanline(int inputScanline) const;
 
+    virtual std::vector<FrameInfo> onGetFrameInfo() {
+        // empty vector - this is not animated.
+        return {};
+    }
+
     /**
      *  Used for testing with qcms.
      *  FIXME: Remove this when we are done comparing with qcms.
      */
     virtual sk_sp<SkData> getICCData() const { return nullptr; }
 private:
     const SkEncodedInfo         fEncodedInfo;
     const SkImageInfo           fSrcInfo;
     SkAutoTDelete<SkStream>     fStream;
     bool                        fNeedsRewind;
@@ skipping 56 matching lines @@
      */
     void fillIncompleteImage(const SkImageInfo& dstInfo, void* dst, size_t rowBytes,
             ZeroInitialized zeroInit, int linesRequested, int linesDecoded);
 
     /**
      *  Return an object which will allow forcing scanline decodes to sample in X.
      *
      *  May create a sampler, if one is not currently being used. Otherwise, does
      *  not affect ownership.
      *
-     *  Only valid during scanline decoding.
+     *  Only valid during scanline decoding or incremental decoding.
      */
     virtual SkSampler* getSampler(bool /*createIfNecessary*/) { return nullptr; }
 
     // For testing with qcms
     // FIXME: Remove these when we are done comparing with qcms.
     friend class DM::ColorCodecSrc;
     friend class ColorCodecBench;
 
     friend class DM::CodecSrc;  // for fillIncompleteImage
     friend class SkSampledCodec;
     friend class SkIcoCodec;
 };
 #endif // SkCodec_DEFINED