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 <functional>
+
 #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;
+}
+
 /**
  *  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 309 matching lines @@
             return kCouldNotRewind;
         }
 
         return this->onGetYUV8Planes(sizeInfo, planes);
     }
 
     /**
      * The remaining functions revolve around decoding scanlines.
      */
 
+
+    /**
+     *  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 options Contains decoding options, including if memory is zero
+     *      initialized.
+     *      The callback will only be called for rows in the subset specified
+     *      by fSubset.
+     *  @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, const SkCodec::Options* = nullptr,
+            SkPMColor* ctable = nullptr, int* ctableCount = 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 callback This will be called each time a row has been decoded.
+     *      The int parameter will be the number of the row (in the Options.fSubset's
+     *      [fTop, fBottom), provided in startIncrementalDecode).
+     *      The callback should return either a block of memory to write the row or
+     *      null to skip writing this row.
+     *      On consecutive calls, this should always write to the same memory.
+     *  @param rowsDecoded Optional output variable returning the total number of
+     *      lines decoded. This includes all lines decoded from the image, whether

[msarett, 2016/05/20 15:04:40]

nit: "whether" -> "whether or not" ?

[scroggo_chromium, 2016/05/20 16:51:59]

Done.

+     *      the client (via the callback) included it in the output, since the
+     *      last call to startIncrementalDecode.
+     *  @return kSuccess if all lines requested in startIncrementalDecode have
+     *      been completely decoded. kIncompleteInput otherwise.
+     */
+    Result incrementalDecode(std::function<void*(int)> callback,
+            int* rowsDecoded = nullptr) {
+        if (!fStartedIncrementalDecode) {
+            return kInvalidParameters;
+        }
+        return this->onIncrementalDecode(callback, rowsDecoded);
+    }
+
     /**
      *  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.
      *
      *  This may require rewinding the stream.
      *
      *  Not all SkCodecs support this.
@@ skipping 96 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 159 matching lines @@
     const SkImageInfo           fSrcInfo;
     SkAutoTDelete<SkStream>     fStream;
     bool                        fNeedsRewind;
     sk_sp<SkColorSpace>         fColorSpace;
     const Origin                fOrigin;
 
     // These fields are only meaningful during scanline decodes.
     SkImageInfo                 fDstInfo;
     SkCodec::Options            fOptions;
     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*/,
+            const SkCodec::Options&, SkPMColor*, int*) {
+        return kUnimplemented;
+    }
+
+    virtual Result onIncrementalDecode(std::function<void*(int)>, 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 11 matching lines @@
     /**
      *  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.
      */
     virtual SkSampler* getSampler(bool /*createIfNecessary*/) { return nullptr; }
 
+    friend class DM::CodecSrc;  // for fillIncompleteImage

[msarett, 2016/05/20 15:04:40]

Is this what our clients will do?  If not, can we fill a different way in DM?

I'm guessing it's tricky because the "fill value" isn't public?  Is there
anything else make this difficult for the client (possibly sampling/subsetting)?

Maybe we should have a public API to fill(), where the client optionally
provides the fill value.  I think this could be a follow-up though.

UPDATE:  The scanline ordering also makes filling hard.  I do think we should
add a public API that offers to fill for the client...

[msarett, 2016/05/20 15:06:59]

Might be changing my mind on this again.  If we are the client that will handle
filling, I think we can get away with it not being public.

[scroggo_chromium, 2016/05/20 16:51:59]

If Chrome continues to behave the way it currently does, it will fill prior to
doing any decoding. If they decide to fill afterwards (without using
SkAndroidCodec), we'll need to make this public, but I figured we could decide
that once it becomes an issue.

[msarett, 2016/05/20 18:21:37]

sgtm

     friend class SkSampledCodec;
     friend class SkIcoCodec;
 };
 #endif // SkCodec_DEFINED