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 "SkImageGenerator.h"
 #include "SkImageInfo.h"
 #include "SkSize.h"
 #include "SkTemplates.h"
 #include "SkTypes.h"
 
 class SkData;
+class SkScanlineDecoder;
 class SkStream;
 
 /**
  *  Abstraction layer directly on top of an image codec.
  */
 class SkCodec : public SkImageGenerator {
 public:
     /**
      *  If this stream represents an encoded image that we know how to decode,
      *  return an SkCodec that can decode it. Otherwise return NULL.
@@ skipping 13 matching lines @@
 
     /**
      *  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.
      *
      *  FIXME: Move to SkImageGenerator?
      */
     SkISize getScaledDimensions(float desiredScale) const;
 
+    /**
+     *  Create a new scanline decoder.
+     *
+     *  Create a new object which can be used to decode individual scanlines.
+     *
+     *  @param dstInfo Info of the destination. If the dimensions do not match
+     *      those of getInfo (or origSubset, if provided), this implies a scale.
+     *  @param origSubset If non null, represents a subset of the original
+     *      unscaled image for the scanline decoder to decode.
+     *  @return New SkScanlineDecoder, or NULL on failure.
+     *
+     *  NOTE: If any rows were previously decoded, this requires rewinding the
+     *  SkStream.
+     *
+     *  NOTE: The lifetime of the scanline decoder is tied to the lifetime of
+     *  the SkCodec. Do not attempt to use after the SkCodec has been deleted.
+     *  Further, the SkScanlineDecoder should be deleted *before* the SkCodec,
+     *  in case the implementation depends on the ordering.
+     */
+    SkScanlineDecoder* getScanlineDecoder(const SkImageInfo& dstInfo,
+                                          const SkIRect* origSubset = NULL);

[scroggo, 2015/03/18 20:19:06]

I haven't yet handled the subset case, but I wanted to bounce my thoughts of you
all before I start to do it.

We discussed passing the subset in here, but I'm wondering if it's necessary. If
I was going to implement a subset decode, I would probably do something like the
following:

scanlineDecoder->skipLines(origSubset->top());
void* tmpDest = malloc(getInfo()->minRowBytes());
for (int y = origSubset->top(); y < origSubset->bottom(); y++) {
  scanlineDecoder->getNextScanline(tmpDest);
  memcpy(dest, tmpDest + (origSubset->left() * bpp),
         origSubset->width() * bpp);
}
scanlineDecoder->skipLines(getInfo()->height() - origSubset->bottom());

(The scanline implementation looks a bit different, since we don't do it in a
loop, but this is the general idea.)

This reads some extra pixels (maybe a lot, if the caller wanted a narrow
subset), but at least for PNG/JPEG, I think we can only read a row at a time
anyway. I'm guessing BMP could do something smarter, but I imagine it would
greatly complicate the code (WDYT, Matt?).

Should we just leave this to the caller? The only obvious downside is that it
makes things a little bit trickier, but not impossible, to use getScanlines(int
count).

+
+    /**
+     *  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.
+     */
+    bool reallyHasAlpha() const {

[scroggo, 2015/03/18 20:19:06]

This maybe should have been a separate change, but it came up as I was
rearranging the PngCodec

+        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.
      */
     bool onGetInfo(SkImageInfo* info) SK_OVERRIDE {
         *info = fInfo;
         return true;
     }
 
     // Helper for subclasses.
     const SkImageInfo& getOriginalInfo() { return fInfo; }
 
     virtual SkISize onGetScaledDimensions(float /* desiredScale */) const {
         // By default, scaling is not supported.
         return fInfo.dimensions();
     }
 
     /**
+     *  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 (or origSubset, if different), this implies a
+     *      scale.
+     *  @param origSubset Subset of the original info to decode. The base class
+     *      will have already intersected with getInfo (or set to match if the
+     *      caller supplied NULL).
+     *  @return New SkScanlineDecoder on success, NULL otherwise.
+     */
+    virtual SkScanlineDecoder* onGetScanlineDecoder(const SkImageInfo& dstInfo,
+                                                    const SkIRect& origSubset) {
+        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();
 
 private:
     const SkImageInfo fInfo;
     SkAutoTDelete<SkStream> fStream;
     bool fNeedsRewind;
 };
 #endif // SkCodec_DEFINED