Create a scanline decoder without creating a codec

include/codec/SkScanlineDecoder.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 SkScanlineDecoder_DEFINED
 #define SkScanlineDecoder_DEFINED
 
 #include "SkTypes.h"
 #include "SkCodec.h"
 #include "SkTemplates.h"
 #include "SkImageInfo.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.
+     *
+     *  reset 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() {}
 
     /**
+     *  Returns the default info, corresponding to the encoded data.
+     *
+     *  If reset has never been called, this is the info that will be used.
+     */
+    const SkImageInfo& getInfo() { return fSrcInfo; }
+
+    /**
+     *  Reset to the first scanline, with the specified options.
+     *
+     *  This may 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 reset(const SkImageInfo& dstInfo, const SkCodec::Options* options,
+                          SkPMColor ctable[], int* ctableCount);
+
+    /**
+     *  Simplified version of reset() that asserts that info is NOT
+     *  kIndex8_SkColorType and uses the default Options.
+     */
+    SkCodec::Result reset(const SkImageInfo& dstInfo);

[msarett, 2015/07/30 12:58:46]

So can we get away with not calling reset() at all if the dstColorType is not
kIndex8 and we don't need to pass any options in?

One comments says:
"reset must be called in order to decode any scanlines"

Another says:
"If reset has never been called, this is the info that will be used."

I think I understand it after reading the comments over this function, but maybe
we can be a little more consistent throughout this file?

[scroggo, 2015/07/30 15:11:35]

Agreed. When I originally wrote the header, I made calling reset unnecessary if
you wanted to use the defaults. I later realized that that would require doing
work that is unnecessary if you did *not* want to use the defaults. I changed
some comments, but did not change them all :(

Thank you for diligently reading over the comments!
Haha, good point - if we stuck with the notion of allowing getting scanlines
without calling reset, kIndex_8 would need to be the exception.

+
+    /**
      *  Write the next countLines scanlines into dst.
      *
      *  @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) {
+        if (fDstInfo.isEmpty()) {

[msarett, 2015/07/30 12:58:46]

Maybe there is a way to make to this check once rather than every time we call
getScanlines()?  I'm guessing the info reported by NewFromStream will never be
empty, since we are responsible for filling it in?  And then if we also check
that the info is not empty in reset(), can we avoid this check?

[scroggo, 2015/07/30 15:11:35]

Actually, what I was trying to check was that you *had* called reset.

Alternatively, we could just say: you better not call this without calling
reset, and assert this (instead of having this check). That would be faster in
release, and catch someone in debug trying to do something invalid.

[msarett, 2015/07/30 15:37:55]

+1 for using SkASSERT.

+            return SkCodec::kInvalidParameters;
+        }
         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.
      *
      *  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) {
+        if (fDstInfo.isEmpty()) {

[msarett, 2015/07/30 12:58:46]

Same question as getScanlines().

[scroggo, 2015/07/30 15:11:35]

Acknowledged.

+            return SkCodec::kInvalidParameters;
+        }
         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();
     }
 
 protected:
-    SkScanlineDecoder(const SkImageInfo& requested)
-        : fDstInfo(requested)
+    SkScanlineDecoder(const SkImageInfo& srcInfo)
+        : fSrcInfo(srcInfo)
+        , fDstInfo()
         , fCurrScanline(0) {}
 
     virtual bool onReallyHasAlpha() const { return false; }
 
     const SkImageInfo& dstInfo() const { return fDstInfo; }
 
 private:
-    const SkImageInfo   fDstInfo;
+    const SkImageInfo   fSrcInfo;
+    SkImageInfo         fDstInfo;
     int                 fCurrScanline;
 
+    virtual SkCodec::Result onReset(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