Fill incomplete images in SkCodec parent class

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
 
@@ skipping 207 matching lines @@
      *  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();
     }
 
+    /**
+     * Before returning kIncompleteInput, onGetPixels() indicates how many uninitialized
+     * scanlines need to be filled.  In order to fill these scanlines, we use this function
+     * to determine what value to fill with.
+     *
+     * @param dstInfo Contains the destination colorType and alphaType, which may be
+     *                used to choose the fill value.
+     * @return        The value with which to fill uninitialized pixels.
+     *
+     * Note that we can interpret the return value as an SkPMColor, a 16-bit 565 color,
+     * an 8-bit gray color, or an 8-bit index into a color table, depending on the color
+     * type specified in dstInfo.
+     */
+    uint32_t getFillValue(const SkImageInfo& dstInfo) const {
+        return this->onGetFillValue(dstInfo);
+    }
+
+    /**
+     * Before returning kIncompleteInput, onGetPixels() indicates how many uninitialized
+     * scanlines need to be filled.  In order to fill these scanlines, we use this function
+     * to determine where these pixels are located in destination memory.
+     *
+     * When encoded scanlines are arranged top-down, we fill the bottom of destination
+     * memory.  When encoded scanlines are arranged bottom-up, we fill the top of
+     * destination memory.  When encoded scanlines are arranged out of order, it is the
+     * responsibility of the subclass to fill uninitialized memory.

[scroggo, 2015/09/25 15:55:05]

FWIW, it seems like getY could be used to make the base class do it (not sure
whether that is worth the trouble, if it's only for GIF though).

[msarett, 2015/10/01 12:44:52]

We will be able to do this (and I intend to do this) once we combine
SkScanlineDecoder and SkCodec.

+     *
+     * @param dstStart         Pointer to the start of destination memory
+     * @param dstRowBytes      Stride length in destination memory
+     * @param decodedScanlines Number of scanlines decoded successfully
+     * @return                 Pointer to the destination memory that we need to fill
+     */
+    void* getFillDst(void* dstStart, size_t rowBytes, uint32_t decodedScanlines) const {
+        return this->onGetFillDst(dstStart, rowBytes, decodedScanlines);
+    }
+
 protected:
     SkCodec(const SkImageInfo&, SkStream*);
 
     virtual SkISize onGetScaledDimensions(float /* desiredScale */) const {
         // By default, scaling is not supported.
         return this->getInfo().dimensions();
     }
 
     virtual SkEncodedFormat onGetEncodedFormat() const = 0;
 
+    /**
+     * @param incompleteScanlines When the encoded image stream is incomplete, this function

[scroggo, 2015/09/25 15:55:05]

As I keep thinking about skbug.com/4284, I wonder if we can get to a point where
all the possible Results returned from getPixels will be returned before calling
onGetPixels, allowing onGetPixels to return a number of lines like
onGetScanlines.

[msarett, 2015/10/01 12:44:52]

That would be great if we could do that!  For now, we need this :|.

+     *                            will return kIncompleteInput and incompleteScanlines will
+     *                            be set to the number of scanlines that remain uninitialized.
+     *                            This will allow getPixels() to fill the uninitialized memory.
+     */
     virtual Result onGetPixels(const SkImageInfo& info,
                                void* pixels, size_t rowBytes, const Options&,
-                               SkPMColor ctable[], int* ctableCount) = 0;
+                               SkPMColor ctable[], int* ctableCount,
+                               int* incompleteScanlines) = 0;
 
     virtual bool onGetValidSubset(SkIRect* /* desiredSubset */) const {
         // By default, subsets are not supported.
         return false;
     }
 
     virtual bool onReallyHasAlpha() const { return false; }
 
     /**
      *  If the stream was previously read, attempt to rewind.
@@ skipping 11 matching lines @@
     /**
      *  Called by rewindIfNeeded, if the stream needed to be rewound.
      *
      *  Subclasses should do any set up needed after a rewind.
      */
     virtual bool onRewind() {
         return true;
     }
 
     /**
+     * Some subclasses will override this function, but this is a useful default for the color
+     * types that we support.  Note that for color types that do not use the full 32-bits,
+     * we will simply take the low bits of the fill value.
+     *
+     * kN32_SkColorType: Transparent or Black
+     * kRGB_565_SkColorType: Black
+     * kGray_8_SkColorType: Black
+     * kIndex_8_SkColorType: First color in color table
+     */
+    virtual uint32_t onGetFillValue(const SkImageInfo& dstInfo) const {
+        return kOpaque_SkAlphaType == dstInfo.alphaType() ? SK_ColorBLACK : SK_ColorTRANSPARENT;
+    }
+
+    /**
+     * This will only need to be overridden for images where the rows are not
+     * decoded in top-down order.
+     */
+    virtual void* onGetFillDst(void* dstStart, size_t rowBytes, uint32_t decodedScanlines) const {
+        return SkTAddOffset<void>(dstStart, rowBytes * decodedScanlines);
+    }
+
+    /**
      * Get method for the input stream
      */
     SkStream* stream() {
         return fStream.get();
     }
 
 private:
     const SkImageInfo       fInfo;
     SkAutoTDelete<SkStream> fStream;
     bool                    fNeedsRewind;
+    uint32_t                fIncompleteScanlines;

[scroggo, 2015/09/25 15:55:05]

I think this no longer needs to be a member variable.

[msarett, 2015/10/01 12:44:52]

Done.

 };
 #endif // SkCodec_DEFINED