Merge SkCodec with SkScanlineDecoder

Benefits:
- This mimics other decoding APIs (including the ones SkCodec relies
on, e.g. a png_struct, which can be used to decode an entire image or
one line at a time).

- It allows a client to ask us to do what we can do efficiently - i.e.
start from encoded data and either decode the whole thing or scanlines.

- It removes the duplicate methods which appeared in both SkCodec and
SkScanlineDecoder (some of which, e.g. in SkJpegScanlineDecoder, just
call fCodec->sameMethod()).

- It simplifies moving more checks into the base class (e.g. the
examples in skbug.com/4284).

BUG=skia:4175
BUG=skia:4284

=====================================================================

SkScanlineDecoder.h/.cpp:
Removed.

SkCodec.h/.cpp:
Add methods, enums, and variables which were previously in
SkScanlineDecoder.
Default fCurrScanline to -1, as a sentinel that start has not been
called.

General changes:
Convert SkScanlineDecoders to SkCodecs.

General changes in SkCodec subclasses:
Merge SkScanlineDecoder implementation into SkCodec. Most (all?) owned
an SkCodec, so they now call this-> instead of fCodec->.

SkBmpCodec.h/.cpp:
Replace the unused rowOrder method with an override for
onGetScanlineOrder.
Make getDstRow const, since it is called by onGetY, which is const.

SkCodec_libpng.h/.cpp:
Make SkPngCodec an abstract class, with two subclasses which handle
scanline decoding separately (they share code for decoding the entire
image). Reimplement onReallyHasAlpha so that it can return the most
recent result (e.g. after a scanline decode which only decoded part
of the image) or a better answer (e.g. if the whole image is known to
be opaque).
Compute fNumberPasses early, so we know which subclass to instantiate.
Make SkPngInterlaceScanlineDecoder use the base class' fCurrScanline
rather than a separate variable.

CodexTest.cpp:
Add tests for the state changes in SkCodec (need to call start before
decoding scanlines; calling getPixels means that start will need to
be called again before decoding more scanlines).
Add a test which decodes in stripes, currently only used for an
interlaced PNG.

TODO: Add tests for onReallyHasAlpha.

Review URL: https://codereview.chromium.org/1365313002

3 files changed, 206 insertions, 297 deletions

diff --git a/include/codec/SkCodec.h b/include/codec/SkCodec.h
index bdfa2326fb..01fd4fa62a 100644
--- a/include/codec/SkCodec.h
+++ b/include/codec/SkCodec.h
@@ -45,7 +45,7 @@ public:
     /**
      *  Return the ImageInfo associated with this codec.
      */
-    const SkImageInfo& getInfo() const { return fInfo; }
+    const SkImageInfo& getInfo() const { return fSrcInfo; }
 
     /**
      *  Return a size that approximately supports the desired scale factor.
@@ -131,7 +131,12 @@ public:
          */
         kCouldNotRewind,
         /**
-         *  This method is not implemented by this generator.
+         *  startScanlineDecode() was not called before calling getScanlines.
+         */
+        kScanlineDecodingNotStarted,
+        /**
+         *  This method is not implemented by this codec.
+         *  FIXME: Perhaps this should be kUnsupported?
          */
         kUnimplemented,
     };
@@ -202,6 +207,9 @@ public:
      *  If info is not kIndex8_SkColorType, then the last two parameters may be NULL. If ctableCount
      *  is not null, it will be set to 0.
      *
+     *  If a scanline decode is in progress, scanline mode will end, requiring the client to call
+     *  startScanlineDecode() in order to return to decoding scanlines.
+     *
      *  @return Result kSuccess, or another value explaining the type of failure.
      */
     Result getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes, const Options*,
@@ -225,6 +233,147 @@ public:
         return this->onReallyHasAlpha();
     }
 
+    /**
+     * 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.
+     *
+     *  This may require rewinding the stream.
+     *
+     *  Not all SkCodecs support this.
+     *
+     *  @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.
+     *  @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 startScanlineDecode(const SkImageInfo& dstInfo, const SkCodec::Options* options,
+                 SkPMColor ctable[], int* ctableCount);
+
+    /**
+     *  Simplified version of startScanlineDecode() that asserts that info is NOT
+     *  kIndex8_SkColorType and uses the default Options.
+     */
+    Result startScanlineDecode(const SkImageInfo& dstInfo);
+
+    /**
+     *  Write the next countLines scanlines into dst.
+     *
+     *  Not valid to call before calling startScanlineDecode().
+     *
+     *  @param dst Must be non-null, and large enough to hold countLines
+     *      scanlines of size rowBytes.
+     *  @param countLines Number of lines to write.
+     *  @param rowBytes Number of bytes per row. Must be large enough to hold
+     *      a scanline based on the SkImageInfo used to create this object.
+     */
+    Result getScanlines(void* dst, int countLines, size_t rowBytes);
+
+    /**
+     *  Skip count scanlines.
+     *
+     *  Not valid to call before calling startScanlineDecode().
+     *
+     *  The default version just calls onGetScanlines and discards the dst.
+     *  NOTE: If skipped lines are the only lines with alpha, this default
+     *  will make reallyHasAlpha return true, when it could have returned
+     *  false.
+     */
+    Result skipScanlines(int countLines);
+
+    /**
+     *  The order in which rows are output from the scanline decoder is not the
+     *  same for all variations of all image types.  This explains the possible
+     *  output row orderings.
+     */
+    enum SkScanlineOrder {
+        /*
+         * By far the most common, this indicates that the image can be decoded
+         * reliably using the scanline decoder, and that rows will be output in
+         * the logical order.
+         */
+        kTopDown_SkScanlineOrder,
+
+        /*
+         * This indicates that the scanline decoder reliably outputs rows, but
+         * they will be returned in reverse order.  If the scanline format is
+         * kBottomUp, the nextScanline() API can be used to determine the actual
+         * y-coordinate of the next output row, but the client is not forced
+         * to take advantage of this, given that it's not too tough to keep
+         * track independently.
+         *
+         * For full image decodes, it is safe to get all of the scanlines at
+         * once, since the decoder will handle inverting the rows as it
+         * decodes.
+         *
+         * 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,
+
+        /*
+         * 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.
+     */
+    SkScanlineOrder getScanlineOrder() const { return this->onGetScanlineOrder(); }
+
+    /**
+     *  Returns the y-coordinate of the next row to be returned by the scanline
+     *  decoder.  This will be overridden in the case of
+     *  kOutOfOrder_SkScanlineOrder and should be unnecessary in the case of
+     *  kNone_SkScanlineOrder.
+     *
+     *  Results are undefined when not in scanline decoding mode.
+     */
+    int nextScanline() const {
+        return this->onNextScanline();
+    }
+
 protected:
     SkCodec(const SkImageInfo&, SkStream*);
 
@@ -275,9 +424,59 @@ protected:
         return fStream.get();
     }
 
+    /**
+     *  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; }
+
+    /**
+     *  Most images will be kTopDown and will not need to override this function.
+     */
+    virtual int onNextScanline() const { return fCurrScanline; }
+
+    /**
+     *  Update the next scanline. Used by interlaced png.
+     */
+    void updateNextScanline(int newY) { fCurrScanline = newY; }
+
+    const SkImageInfo& dstInfo() const { return fDstInfo; }
+
+    const SkCodec::Options& options() const { return fOptions; }
+
 private:
-    const SkImageInfo       fInfo;
+    const SkImageInfo       fSrcInfo;
     SkAutoTDelete<SkStream> fStream;
     bool                    fNeedsRewind;
+    // These fields are only meaningful during scanline decodes.
+    SkImageInfo             fDstInfo;
+    SkCodec::Options        fOptions;
+    int                     fCurrScanline;
+
+    // Methods for scanline decoding.
+    virtual SkCodec::Result onStartScanlineDecode(const SkImageInfo& dstInfo,
+            const SkCodec::Options& options, SkPMColor ctable[], int* ctableCount) {
+        return kUnimplemented;
+    }
+
+    // Naive default version just calls onGetScanlines on temp memory.
+    virtual SkCodec::Result onSkipScanlines(int countLines) {
+        SkAutoMalloc storage(fDstInfo.minRowBytes());
+        // Note that we pass 0 to rowBytes so we continue to use the same memory.
+        // Also note that while getScanlines checks that rowBytes is big enough,
+        // onGetScanlines bypasses that check.
+        // Calling the virtual method also means we do not double count
+        // countLines.
+        return this->onGetScanlines(storage.get(), countLines, 0);
+    }
+
+    virtual SkCodec::Result onGetScanlines(void* dst, int countLines,
+                                                    size_t rowBytes) {
+        return kUnimplemented;
+    }
+
 };
 #endif // SkCodec_DEFINED
diff --git a/include/codec/SkScaledCodec.h b/include/codec/SkScaledCodec.h
index 1bcdf085b2..20428d8d73 100644
--- a/include/codec/SkScaledCodec.h
+++ b/include/codec/SkScaledCodec.h
@@ -8,9 +8,7 @@
 #define SkScaledCodec_DEFINED
 
 #include "SkCodec.h"
-#include "SkScanlineDecoder.h"
 
-class SkScanlineDecoder;
 class SkStream;
 
 /**
@@ -52,18 +50,18 @@ protected:
     Result onGetPixels(const SkImageInfo&, void*, size_t, const Options&, SkPMColor*, int*)
             override;
     SkEncodedFormat onGetEncodedFormat() const override {
-        return fScanlineDecoder->getEncodedFormat();
+        return fCodec->getEncodedFormat();
     }
 
     bool onReallyHasAlpha() const override {
-        return fScanlineDecoder->reallyHasAlpha();
+        return fCodec->reallyHasAlpha();
     }
 
 private:
 
-    SkAutoTDelete<SkScanlineDecoder> fScanlineDecoder;
+    SkAutoTDelete<SkCodec> fCodec;
 
-    explicit SkScaledCodec(SkScanlineDecoder*);
+    explicit SkScaledCodec(SkCodec*);
 
     typedef SkCodec INHERITED;
 };
diff --git a/include/codec/SkScanlineDecoder.h b/include/codec/SkScanlineDecoder.h
deleted file mode 100644
index 61184d644a..0000000000
--- a/include/codec/SkScanlineDecoder.h
+++ /dev/null
@@ -1,288 +0,0 @@
-/*
- * 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 SkScanlineDecoder_DEFINED
-#define SkScanlineDecoder_DEFINED
-
-#include "../private/SkTemplates.h"
-#include "SkCodec.h"
-#include "SkImageInfo.h"
-#include "SkTypes.h"
-
-class SkScanlineDecoder : public SkNoncopyable {
-public:
-    /**
-     *  If this stream represents an encoded image that we know how to decode
-     *  in scanlines, return an SkScanlineDecoder that can decode it. Otherwise
-     *  return NULL.
-     *
-     *  start() must be called in order to decode any scanlines.
-     *
-     *  If NULL is returned, the stream is deleted immediately. Otherwise, the
-     *  SkScanlineDecoder takes ownership of it, and will delete it when done
-     *  with it.
-     */
-    static SkScanlineDecoder* NewFromStream(SkStream*);
-
-    /**
-     *  Similar to NewFromStream, but reads from an SkData.
-     *
-     *  Will take a ref if it returns a scanline decoder, else will not affect
-     *  the data.
-     */
-    static SkScanlineDecoder* NewFromData(SkData*);
-
-    /**
-     *  Clean up after reading/skipping scanlines.
-     *
-     *  It is possible that not all scanlines will have been read/skipped.  In
-     *  fact, in the case of subset decodes, it is likely that there will be
-     *  scanlines at the bottom of the image that have been ignored.
-     */
-    virtual ~SkScanlineDecoder() {}
-
-    /**
-     *  Return a size that approximately supports the desired scale factor.
-     *  The codec may not be able to scale efficiently to the exact scale
-     *  factor requested, so return a size that approximates that scale.
-     *  The returned value is the codec's suggestion for the closest valid
-     *  scale that it can natively support
-     *  FIXME: share this with SkCodec
-     */
-    SkISize getScaledDimensions(float desiredScale) {
-        return this->onGetScaledDimensions(desiredScale);
-    }
-
-    /**
-     *  Returns the default info, corresponding to the encoded data.
-     */
-    const SkImageInfo& getInfo() { return fSrcInfo; }
-
-    /**
-     *  Initialize on the first scanline, with the specified options.
-     *
-     *  This must be called in order to call getScanlnies or skipScanlines. If
-     *  it has been called before, this will require rewinding the stream.
-     *
-     *  @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.
-     *  @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.
-     */
-    SkCodec::Result start(const SkImageInfo& dstInfo, const SkCodec::Options* options,
-                          SkPMColor ctable[], int* ctableCount);
-
-    /**
-     *  Simplified version of start() that asserts that info is NOT
-     *  kIndex8_SkColorType and uses the default Options.
-     */
-    SkCodec::Result start(const SkImageInfo& dstInfo);
-
-    /**
-     *  Write the next countLines scanlines into dst.
-     *
-     *  Not valid to call before calling start().
-     *
-     *  @param dst Must be non-null, and large enough to hold countLines
-     *      scanlines of size rowBytes.
-     *  @param countLines Number of lines to write.
-     *  @param rowBytes Number of bytes per row. Must be large enough to hold
-     *      a scanline based on the SkImageInfo used to create this object.
-     */
-    SkCodec::Result getScanlines(void* dst, int countLines, size_t rowBytes) {
-        SkASSERT(!fDstInfo.isEmpty());
-        if ((rowBytes < fDstInfo.minRowBytes() && countLines > 1 ) || countLines <= 0
-                || fCurrScanline + countLines > fDstInfo.height()) {
-            return SkCodec::kInvalidParameters;
-        }
-        const SkCodec::Result result = this->onGetScanlines(dst, countLines, rowBytes);
-        fCurrScanline += countLines;
-        return result;
-    }
-
-    /**
-     *  Skip count scanlines.
-     *
-     *  Not valid to call before calling start().
-     *
-     *  The default version just calls onGetScanlines and discards the dst.
-     *  NOTE: If skipped lines are the only lines with alpha, this default
-     *  will make reallyHasAlpha return true, when it could have returned
-     *  false.
-     */
-    SkCodec::Result skipScanlines(int countLines) {
-        SkASSERT(!fDstInfo.isEmpty());
-        if (fCurrScanline + countLines > fDstInfo.height()) {
-            // Arguably, we could just skip the scanlines which are remaining,
-            // and return kSuccess. We choose to return invalid so the client
-            // can catch their bug.
-            return SkCodec::kInvalidParameters;
-        }
-        const SkCodec::Result result = this->onSkipScanlines(countLines);
-        fCurrScanline += countLines;
-        return result;
-    }
-
-    /**
-     *  Some images may initially report that they have alpha due to the format
-     *  of the encoded data, but then never use any colors which have alpha
-     *  less than 100%. This function can be called *after* decoding to
-     *  determine if such an image truly had alpha. Calling it before decoding
-     *  is undefined.
-     *  FIXME: see skbug.com/3582.
-     */
-    bool reallyHasAlpha() const {
-        return this->onReallyHasAlpha();
-    }
-
-    /**
-     *  Format of the encoded data.
-     */
-    SkEncodedFormat getEncodedFormat() const { return this->onGetEncodedFormat(); }
-
-    /**
-     *  The order in which rows are output from the scanline decoder is not the
-     *  same for all variations of all image types.  This explains the possible
-     *  output row orderings.
-     */
-    enum SkScanlineOrder {
-        /*
-         * By far the most common, this indicates that the image can be decoded
-         * reliably using the scanline decoder, and that rows will be output in
-         * the logical order.
-         */
-        kTopDown_SkScanlineOrder,
-
-        /*
-         * This indicates that the scanline decoder reliably outputs rows, but
-         * they will be returned in reverse order.  If the scanline format is
-         * kBottomUp, the getY() API can be used to determine the actual
-         * y-coordinate of the next output row, but the client is not forced
-         * to take advantage of this, given that it's not too tough to keep
-         * track independently.
-         *
-         * For full image decodes, it is safe to get all of the scanlines at
-         * once, since the decoder will handle inverting the rows as it
-         * decodes.
-         *
-         * For subset decodes and sampling, it is simplest to get and skip
-         * scanlines one at a time, using the getY() 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 getY() 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.
-     */
-    SkScanlineOrder getScanlineOrder() const { return this->onGetScanlineOrder(); }
-
-    /**
-     *  Returns the y-coordinate of the next row to be returned by the scanline
-     *  decoder.  This will be overridden in the case of
-     *  kOutOfOrder_SkScanlineOrder and should be unnecessary in the case of
-     *  kNone_SkScanlineOrder.
-     */
-    int getY() const {
-        SkASSERT(kNone_SkScanlineOrder != this->getScanlineOrder());
-        return this->onGetY();
-    }
-
-protected:
-    SkScanlineDecoder(const SkImageInfo& srcInfo)
-        : fSrcInfo(srcInfo)
-        , fDstInfo()
-        , fOptions()
-        , fCurrScanline(0) {}
-
-    virtual SkISize onGetScaledDimensions(float /* desiredScale */) {
-        // By default, scaling is not supported.
-        return this->getInfo().dimensions();
-    }
-
-    virtual SkEncodedFormat onGetEncodedFormat() const = 0;
-
-    virtual bool onReallyHasAlpha() const { return false; }
-
-    /**
-     *  Most images types will be kTopDown and will not need to override this function.
-     */
-    virtual SkScanlineOrder onGetScanlineOrder() const { return kTopDown_SkScanlineOrder; }
-
-    /**
-     *  Most images will be kTopDown and will not need to override this function.
-     */
-    virtual int onGetY() const { return fCurrScanline; }
-
-    const SkImageInfo& dstInfo() const { return fDstInfo; }
-
-    const SkCodec::Options& options() const { return fOptions; }
-
-private:
-    const SkImageInfo   fSrcInfo;
-    SkImageInfo         fDstInfo;
-    SkCodec::Options    fOptions;
-    int                 fCurrScanline;
-
-    virtual SkCodec::Result onStart(const SkImageInfo& dstInfo,
-                                    const SkCodec::Options& options,
-                                    SkPMColor ctable[], int* ctableCount) = 0;
-
-    // Naive default version just calls onGetScanlines on temp memory.
-    virtual SkCodec::Result onSkipScanlines(int countLines) {
-        SkAutoMalloc storage(fDstInfo.minRowBytes());
-        // Note that we pass 0 to rowBytes so we continue to use the same memory.
-        // Also note that while getScanlines checks that rowBytes is big enough,
-        // onGetScanlines bypasses that check.
-        // Calling the virtual method also means we do not double count
-        // countLines.
-        return this->onGetScanlines(storage.get(), countLines, 0);
-    }
-
-    virtual SkCodec::Result onGetScanlines(void* dst, int countLines,
-                                                    size_t rowBytes) = 0;
-
-};
-#endif // SkScanlineDecoder_DEFINED