Scanline decoding for bmp

include/codec/SkScanlineDecoder.h

Index: include/codec/SkScanlineDecoder.h
diff --git a/include/codec/SkScanlineDecoder.h b/include/codec/SkScanlineDecoder.h
index c547f6701f667d2ecfd61f7dca2154f164c19242..4b4646b0dbc183a31908d7887d274e769a75849d 100644
--- a/include/codec/SkScanlineDecoder.h
+++ b/include/codec/SkScanlineDecoder.h
@@ -152,22 +152,68 @@ public:
      */
     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 scanline decoder can reliably output 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-coordinates of the output rows.
+         *
+         * For this scanline ordering, it is advisable to get and skip
+         * scanlines one at a time.
+         *
+         * Upside down bmps and interlaced gifs are examples.

[scroggo, 2015/08/26 22:40:09]

Should upside down be its own ordering? It seems like that is a special case
where they're still in a simple order, it's just the opposite order.

+         */
+        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,

[scroggo, 2015/08/26 22:40:09]

I'm not a huge fan of this name, but do not have a suggestion for a better one.

+    };
+
+    /**
+     *  An enum representing the order in which scanlines will be returned by
+     *  the scanline decoder.
+     */
+    SkScanlineOrder getScanlineOrder() const { return this->onGetScanlineOrder(); }
+
     /**
-     * returns true if the image must be scaled, in the y direction, after reading, not during.
-     * To scale afterwards, we first decode every line and then sample the lines we want afterwards.
-     * An example is interlaced pngs, where calling getScanlines once (regardless of the count
-     * used) needs to read the entire image, therefore it is inefficient to call
-     * getScanlines more than once. Instead, it should only ever be called with all the
-     * rows needed.
+     *  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.
      */
-    bool requiresPostYSampling() {
-        return this->onRequiresPostYSampling();
+    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 */) {
@@ -180,16 +226,23 @@ protected:
     virtual bool onReallyHasAlpha() const { return false; }
 
     /**
-     * returns true if the image type is hard to sample and must be scaled after reading, not during
-     * An example is interlaced pngs, where the entire image must be read for each decode
+     *  Most images types will be kTopDown and will not need to override this function.
      */
-    virtual bool onRequiresPostYSampling() { return false; }
+    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,