Make SkPngCodec decode progressively.

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"
 
 class SkColorSpace;
 class SkData;
 class SkPngChunkReader;
 class SkSampler;
 
 namespace DM {
+class CodecSrc;
 class ColorCodecSrc;
 }
 class ColorCodecBench;
 
-
 /**
  *  Abstraction layer directly on top of an image codec.
  */
 class SkCodec : SkNoncopyable {
 public:
     /**
      *  Minimum number of bytes that must be buffered in SkStream input.
      *
      *  An SkStream passed to NewFromStream must be able to use this many
      *  bytes to determine the image type. Then the same SkStream must be
@@ skipping 204 matching lines @@
             , fSubset(NULL)
         {}
 
         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, we will attempt to decode the exact rectangular
-         *  subset specified by fSubset.
+         *  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;
@@ skipping 80 matching lines @@
         }
 
         if (!this->rewindIfNeeded()) {
             return kCouldNotRewind;
         }
 
         return this->onGetYUV8Planes(sizeInfo, planes);
     }
 
     /**
+     *  Prepare for an incremental decode with the specified options.
+     *
+     *  This may require a rewind.
+     *
+     *  @param dstInfo Info of the destination. If the dimensions do not match
+     *      those of getInfo, this implies a scale.
+     *  @param dst Memory to write to. Needs to be large enough to hold the subset,
+     *      if present, or the full image as described in dstInfo.
+     *  @param options Contains decoding options, including if memory is zero
+     *      initialized and whether to decode a subset.
+     *  @param ctable A pointer to a color table.  When dstInfo.colorType() is
+     *      kIndex8, this should be non-NULL and have enough storage for 256
+     *      colors.  The color table will be populated after decoding the palette.
+     *  @param ctableCount A pointer to the size of the color table.  When
+     *      dstInfo.colorType() is kIndex8, this should be non-NULL.  It will
+     *      be modified to the true size of the color table (<= 256) after
+     *      decoding the palette.
+     *  @return Enum representing success or reason for failure.
+     */
+    Result startIncrementalDecode(const SkImageInfo& dstInfo, void* dst, size_t rowBytes,
+            const SkCodec::Options*, SkPMColor* ctable, int* ctableCount);
+
+    Result startIncrementalDecode(const SkImageInfo& dstInfo, void* dst, size_t rowBytes,
+            const SkCodec::Options* options) {
+        return this->startIncrementalDecode(dstInfo, dst, rowBytes, options, nullptr, nullptr);
+    }
+
+    Result startIncrementalDecode(const SkImageInfo& dstInfo, void* dst, size_t rowBytes) {
+        return this->startIncrementalDecode(dstInfo, dst, rowBytes, nullptr, nullptr, nullptr);
+    }
+
+    /**
+     *  Start/continue the incremental decode.
+     *
+     *  Not valid to call before calling startIncrementalDecode().
+     *
+     *  After the first call, should only be called again if more data has been
+     *  provided to the source SkStream.
+     *
+     *  Unlike getPixels and getScanlines, this does not do any filling. This is
+     *  left up to the caller, since they may be skipping lines or continuing the
+     *  decode later. In the latter case, they may choose to initialize all lines
+     *  first, or only initialize the remaining lines after the first call.
+     *
+     *  @param rowsDecoded Optional output variable returning the total number of
+     *      lines initialized. Only meaningful if this method returns kIncompleteInput.
+     *      Otherwise the implementation may not set it.
+     *      Note that some implementations may have initialized this many rows, but
+     *      not necessarily finished those rows (e.g. interlaced PNG). This may be
+     *      useful for determining what rows the client needs to initialize.
+     *  @return kSuccess if all lines requested in startIncrementalDecode have
+     *      been completely decoded. kIncompleteInput otherwise.
+     */
+    Result incrementalDecode(int* rowsDecoded = nullptr) {
+        if (!fStartedIncrementalDecode) {
+            return kInvalidParameters;
+        }
+        return this->onIncrementalDecode(rowsDecoded);
+    }
+
+    /**
      * The remaining functions revolve around decoding scanlines.
      */
 
     /**
      *  Prepare for a scanline decode with the specified options.
      *
      *  After this call, this class will be ready to decode the first scanline.
      *
      *  This must be called in order to call getScanlines or skipScanlines.
      *
@@ skipping 99 matching lines @@
          * 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,
-
-        /*
-         * Indicates that the entire image must be decoded in order to output
-         * any amount of scanlines.  In this case, it is a REALLY BAD IDEA to
-         * request scanlines 1-by-1 or in small chunks.  The client should
-         * determine which scanlines are needed and ask for all of them in
-         * a single call to getScanlines().
-         *
-         * Interlaced pngs are an example.
-         */
-        kNone_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(); }
 
@@ skipping 137 matching lines @@
 
     /**
      *  The remaining functions revolve around decoding scanlines.
      */
 
     /**
      *  Most images types will be kTopDown and will not need to override this function.
      */
     virtual SkScanlineOrder onGetScanlineOrder() const { return kTopDown_SkScanlineOrder; }
 
-    /**
-     *  Update the current scanline. Used by interlaced png.
-     */
-    void updateCurrScanline(int newY) { fCurrScanline = newY; }
-
     const SkImageInfo& dstInfo() const { return fDstInfo; }
 
     const SkCodec::Options& options() const { return fOptions; }
 
     /**
      *  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;
 
     /**
      *  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;
     const Origin                fOrigin;
 
-    // These fields are only meaningful during scanline decodes.
     SkImageInfo                 fDstInfo;
     SkCodec::Options            fOptions;
+
+    // Only meaningful during scanline decodes.
     int                         fCurrScanline;
 
+    bool                        fStartedIncrementalDecode;
+
     /**
      *  Return whether these dimensions are supported as a scale.
      *
      *  The codec may choose to cache the information about scale and subset.
      *  Either way, the same information will be passed to onGetPixels/onStart
      *  on success.
      *
      *  This must return true for a size returned from getScaledDimensions.
      */
     bool dimensionsSupported(const SkISize& dim) {
         return dim == fSrcInfo.dimensions() || this->onDimensionsSupported(dim);
     }
 
     // Methods for scanline decoding.
     virtual SkCodec::Result onStartScanlineDecode(const SkImageInfo& /*dstInfo*/,
             const SkCodec::Options& /*options*/, SkPMColor* /*ctable*/, int* /*ctableCount*/) {
         return kUnimplemented;
     }
 
+    virtual Result onStartIncrementalDecode(const SkImageInfo& /*dstInfo*/, void*, size_t,
+            const SkCodec::Options&, SkPMColor*, int*) {
+        return kUnimplemented;
+    }
+
+    virtual Result onIncrementalDecode(int*) {
+        return kUnimplemented;
+    }
+
+
     virtual bool onSkipScanlines(int /*countLines*/) { return false; }
 
     virtual int onGetScanlines(void* /*dst*/, int /*countLines*/, size_t /*rowBytes*/) { return 0; }
 
     /**
      * On an incomplete decode, getPixels() and getScanlines() will call this function
      * to fill any uinitialized memory.
      *
      * @param dstInfo        Contains the destination color type
      *                       Contains the destination alpha type
@@ skipping 16 matching lines @@
      *
      *  Only valid during scanline 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