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 113 matching lines @@
         /**
          *  The input did not contain a valid image.
          */
         kInvalidInput,
         /**
          *  Fulfilling this request requires rewinding the input, which is not
          *  supported for this input.
          */
         kCouldNotRewind,
         /**
-         *  startScanlineDecode() was not called before calling getScanlines.
-         */
-        kScanlineDecodingNotStarted,
-        /**
          *  This method is not implemented by this codec.
          *  FIXME: Perhaps this should be kUnsupported?
          */
         kUnimplemented,
     };
 
     /**
      *  Whether or not the memory passed to getPixels is zero initialized.
      */
     enum ZeroInitialized {
@@ skipping 125 matching lines @@
     /**
      *  Write the next countLines scanlines into dst.
      *
      *  Not valid to call before calling startScanlineDecode().
      *
      *  @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.
+     *  @return the number of lines successfully decoded.  If this value is
+     *      less than countLines, this will fill the remaining lines with a
+     *      default value.
      */
-    Result getScanlines(void* dst, int countLines, size_t rowBytes);
+    int getScanlines(void* dst, int countLines, size_t rowBytes);

[djsollen, 2015/10/05 12:15:39]

what do you expect the caller to do with this value?  It seems like we could
return something like kIncompleteResult to the same effect.

[scroggo, 2015/10/05 13:12:24]

This is something we discussed and were not very sure about. If we did *not*
fill the remaining lines, the caller could use this to know which lines they
need to fill. Filling those lines in getScanlines makes things easier on the
caller and means we'll initialize the memory, rather than leaving it up to the
caller, who may otherwise not do it.

We use the int return value from onGetScanlines, in the default version of
onSkipScanlines. That could be accomplished with returning kIncompleteInput,
though, and we're planning to get rid of the default version anyway.

We use the int return value from onGetScanlines in getScanlines, but we could
still return kSuccess or kIncompleteInput from the non-virtual function.

SkScaledCodec also uses the return value from getScanlines (number of lines),
but could easily take the enum, except in one place, kNone_ScanlineOrder - not
sure whether that could take the enum.

One idea behind returning the number of lines is that the client can decide
whether that image is complete enough. (i.e. I could imagine a client saying an
image with N-1 lines decoded is fine, but if only 1 line was decoded they may
not want to show it. Not sure where to draw the line though.)

[reed1, 2015/10/06 18:40:02]

What is the default value? Can it be provided by the caller?

[msarett, 2015/10/06 18:47:40]

/**
 * kN32_SkColorType: Transparent or Black
 * kRGB_565_SkColorType: Black
 * kGray_8_SkColorType: Black
 * kIndex_8_SkColorType: First color in color table
 */

Above are the default values depending on the color type.

Some subcodecs will override these defaults.  Specifically gifs may specify a
background color and, when we will convert Index8 style images to N32 etc., we
still fill with the first color in the color table for consistency.

We don't provide a way for the caller to provide a default value, however I am
not opposed to this.

 
     /**
      *  Skip count scanlines.
      *
      *  Not valid to call before calling startScanlineDecode().
      *
      *  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.
+     *
+     *  @return true if the scanlines were successfully skipped
+     *          false on failure, possible reasons for failure include:
+     *              An incomplete input image stream.
+     *              Calling this function before calling startScanlineDecode().
+     *              If countLines is less than zero or so large that it moves
+     *                  the current scanline past the end of the image.
      */
-    Result skipScanlines(int countLines);
+    bool skipScanlines(int countLines);
 
     /**
      *  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
@@ skipping 50 matching lines @@
     };
 
     /**
      *  An enum representing the order in which scanlines will be returned by
      *  the scanline decoder.
      */
     SkScanlineOrder getScanlineOrder() const { return this->onGetScanlineOrder(); }
 
     /**
      *  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.
+     *  decoder.
+     *
+     *  This will equal fCurrScanline, except in the case of strangely
+     *  encoded image types (bottom-up bmps, interlaced gifs).
      *
      *  Results are undefined when not in scanline decoding mode.
      */
-    int nextScanline() const {
-        return this->onNextScanline();
-    }
+    int nextScanline() const { return this->outputScanline(fCurrScanline); }
+
+    /**
+     * Returns the output y-coordinate of the row that corresponds to an input
+     * y-coordinate.  The input y-coordinate represents where the scanline
+     * is located in the encoded data.
+     *
+     *  This will equal inputScanline, except in the case of strangely
+     *  encoded image types (bottom-up bmps, interlaced gifs).
+     */
+    int outputScanline(int inputScanline) const;
 
 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 rowsDecoded When the encoded image stream is incomplete, this function
+     *                    will return kIncompleteInput and rowsDecoded will be set to
+     *                    the number of scanlines that were successfully decoded.
+     *                    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* rowsDecoded) = 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 10 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;
     }
 
     /**
+     * On an incomplete input, getPixels() and getScanlines() will fill any uninitialized
+     * scanlines.  This allows the subclass to indicate what value to fill with.
+     *
+     * @param colorType Destination color type.
+     * @param alphaType Destination alpha type.
+     * @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(SkColorType colorType, SkAlphaType alphaType) const {
+        return this->onGetFillValue(colorType, alphaType);
+    }
+
+    /**
+     * 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(SkColorType colorType, SkAlphaType alphaType) const {
+        return kOpaque_SkAlphaType == alphaType ? SK_ColorBLACK : SK_ColorTRANSPARENT;
+    }
+
+    /**
      * Get method for the input stream
      */
     SkStream* stream() {
         return fStream.get();
     }
 
     /**
      *  The remaining functions revolve around decoding scanlines.
      */
 
     /**
      *  Most images types will be kTopDown and will not need to override this function.
      */
     virtual SkScanlineOrder onGetScanlineOrder() const { return kTopDown_SkScanlineOrder; }
 
     /**
-     *  Most images will be kTopDown and will not need to override this function.
-     */
-    virtual int onNextScanline() const { return fCurrScanline; }
-
-    /**
      *  Update the next scanline. Used by interlaced png.
      */
     void updateNextScanline(int newY) { fCurrScanline = newY; }
 
     const SkImageInfo& dstInfo() const { return fDstInfo; }
 
     const SkCodec::Options& options() const { return fOptions; }
 
 private:
     const SkImageInfo       fSrcInfo;
     SkAutoTDelete<SkStream> fStream;
     bool                    fNeedsRewind;
     // These fields are only meaningful during scanline decodes.
     SkImageInfo             fDstInfo;
     SkCodec::Options        fOptions;
     int                     fCurrScanline;
 
     // Methods for scanline decoding.
     virtual SkCodec::Result onStartScanlineDecode(const SkImageInfo& dstInfo,
             const SkCodec::Options& options, SkPMColor ctable[], int* ctableCount) {
         return kUnimplemented;
     }
 
     // Naive default version just calls onGetScanlines on temp memory.
-    virtual SkCodec::Result onSkipScanlines(int countLines) {
+    virtual bool onSkipScanlines(int countLines) {
+        // FIXME (msarett): Make this a pure virtual and always override this.
         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);
+        return countLines == this->onGetScanlines(storage.get(), countLines, 0);
     }
 
-    virtual SkCodec::Result onGetScanlines(void* dst, int countLines,
-                                                    size_t rowBytes) {
-        return kUnimplemented;
-    }
+    virtual int onGetScanlines(void* dst, int countLines, size_t rowBytes) { return 0; }
 
+    /**
+     * On an incomplete decode, getPixels() and getScanlines() will call this function
+     * to fill any uinitialized memory.
+     *
+     * @param info           Destination image info
+     * @param dst            Pointer to the start of destination pixel memory
+     * @param rowBytes       Stride length in destination pixel memory
+     * @param zeroInit       Indicates if memory is zero initialized
+     * @param linesRequested Number of lines that the client requested
+     * @param linesDecoded   Number of lines that were successfully decoded
+     */
+    void fillIncompleteImage(const SkImageInfo& info, void* dst, size_t rowBytes,
+            ZeroInitialized zeroInit, int linesRequested, int linesDecoded);
+
+    // Needed to call getFillColor()
+    friend class SkScaledCodec;
 };
 #endif // SkCodec_DEFINED