Add scanline decoding to 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 "SkEncodedFormat.h"
 #include "SkImageGenerator.h"
 #include "SkImageInfo.h"
+#include "SkScanlineDecoder.h"
 #include "SkSize.h"
 #include "SkStream.h"
 #include "SkTemplates.h"
 #include "SkTypes.h"
 
 class SkData;
 
 /**
  *  Abstraction layer directly on top of an image codec.
  */
@@ skipping 25 matching lines @@
      */
     SkISize getScaledDimensions(float desiredScale) const {
         return this->onGetScaledDimensions(desiredScale);
     }
 
     /**
      *  Format of the encoded data.
      */
     SkEncodedFormat getEncodedFormat() const { return this->onGetEncodedFormat(); }
 
+    /**
+     *  Return an object which can be used to decode individual scanlines.
+     *
+     *  This object is owned by the SkCodec, which will handle its lifetime. The
+     *  returned object is only valid until the SkCodec is deleted or the next
+     *  call to getScanlineDecoder, whichever comes first.
+     *
+     *  Calling a second time will rewind and replace the existing one with a

[djsollen, 2015/03/25 13:08:42]

What if the stream cannot be rewound?

[scroggo, 2015/03/25 13:49:15]

I've added a comment that we will return NULL.

For our methods that return objects, instead of SkImageGenerator::Result, I've
been thinking about using an out parameter Result so we can let the caller know
*why* we didn't create an object. I think Android would appreciate that since it
allows us to throw a Java exception describing the failure better. Thoughts?

+     *  new one.
+     *
+     *  @param dstInfo Info of the destination. If the dimensions do not match
+     *      those of getInfo, this implies a scale.
+     *  @return New SkScanlineDecoder, or NULL on failure.
+     *
+     *  NOTE: If any rows were previously decoded, this requires rewinding the
+     *  SkStream.
+     *
+     *  NOTE: The scanline decoder is owned by the SkCodec and will delete it
+     *  when the SkCodec is deleted.
+     */
+    SkScanlineDecoder* getScanlineDecoder(const SkImageInfo& dstInfo);
+
+    /**
+     *  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();
+    }
+
 protected:
     SkCodec(const SkImageInfo&, SkStream*);
 
     /**
      *  The SkAlphaType is a conservative answer. i.e. it is possible that it
      *  initially returns a non-opaque answer, but completing the decode
      *  reveals that the image is actually opaque.
      */
 #ifdef SK_SUPPORT_LEGACY_BOOL_ONGETINFO
     bool onGetInfo(SkImageInfo* info) SK_OVERRIDE {
         *info = fInfo;
         return true;
     }
 #endif
 
-    // Helper for subclasses.
-    const SkImageInfo& getOriginalInfo() { return fInfo; }
-
     virtual SkISize onGetScaledDimensions(float /* desiredScale */) const {
         // By default, scaling is not supported.
         return fInfo.dimensions();
     }
 
     virtual SkEncodedFormat onGetEncodedFormat() const = 0;
 
     /**
+     *  Override if your codec supports scanline decoding.
+     *
+     *  No need to call rewindIfNeeded(), which will have already been called
+     *  by the base class.
+     *
+     *  @param dstInfo Info of the destination. If the dimensions do not match
+     *      those of getInfo, this implies a scale.
+     *  @return New SkScanlineDecoder on success, NULL otherwise. The SkCodec
+     *      will take ownership of the returned scanline decoder.
+     */
+    virtual SkScanlineDecoder* onGetScanlineDecoder(const SkImageInfo& dstInfo) {
+        return NULL;
+    }
+
+    virtual bool onReallyHasAlpha() const { return false; }
+
+    /**
      *  If the stream was previously read, attempt to rewind.
      *  @returns:
      *      true
      *       - if the stream needed to be rewound, and the rewind
      *         succeeded.
      *       - if the stream did not need to be rewound.
      *      false
      *       - if the stream needed to be rewound, and rewind failed.
      *  Subclasses MUST call this function before reading the stream (e.g. in
      *  onGetPixels). If it returns false, onGetPixels should return
      *  kCouldNotRewind.
      */
     bool SK_WARN_UNUSED_RESULT rewindIfNeeded();
 
     /*
      *
      * Get method for the input stream
      *
      */
     SkStream* stream() {
         return fStream.get();
     }
 
 private:
-    const SkImageInfo       fInfo;
-    SkAutoTDelete<SkStream> fStream;
-    bool                    fNeedsRewind;
+    const SkImageInfo                   fInfo;
+    SkAutoTDelete<SkStream>             fStream;
+    bool                                fNeedsRewind;
+    SkAutoTDelete<SkScanlineDecoder>    fScanlineDecoder;
 
     typedef SkImageGenerator INHERITED;
 };
 #endif // SkCodec_DEFINED