Upstream Android modifications to the image encoders/decoders.

include/images/SkImageDecoder.h

 
 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 #ifndef SkImageDecoder_DEFINED
 #define SkImageDecoder_DEFINED
 
 #include "SkBitmap.h"
 #include "SkBitmapFactory.h"
 #include "SkImage.h"
+#include "SkRect.h"
 #include "SkRefCnt.h"
 
 class SkStream;
 
 /** \class SkImageDecoder
 
     Base class for decoding compressed images into a SkBitmap
 */
 class SkImageDecoder {
 public:
     virtual ~SkImageDecoder();
 
+    // Should be consistent with kFormatName
     enum Format {
         kUnknown_Format,
         kBMP_Format,
         kGIF_Format,
         kICO_Format,
         kJPEG_Format,
         kPNG_Format,
         kWBMP_Format,
+        kWEBP_Format,
 
-        kLastKnownFormat = kWBMP_Format
+        kLastKnownFormat = kWEBP_Format
     };
 
+    /** Contains the image format name.
+     *  This should be consistent with Format.
+     *
+     *  The format name gives a more meaningful error message than enum.
+     */

[robertphillips, 2013/03/13 13:41:29]

So you don't think replacing the '8' with "kLastKnownFormat+1" would be
worthwhile?

[djsollen, 2013/03/13 16:02:48]

Done.

+    static const char *kFormatName[8];

[scroggo, 2013/03/13 16:04:14]

Why does this have a 'k' at the front? Isn't that reserved for enums? Also, does
it need to be public?

[djsollen, 2013/03/13 17:35:09]

Done.

+
     /** Return the compressed data's format (see Format enum)
     */
     virtual Format getFormat() const;
 
+    /** Return the compressed data's format name.
+    */
+    const char* getFormatName() const {
+        SkASSERT(SK_ARRAY_COUNT(kFormatName) == kLastKnownFormat);

[robertphillips, 2013/03/13 13:41:29]

this->getFormat()

[djsollen, 2013/03/13 16:02:48]

Done.

+        return kFormatName[getFormat()];
+    }
+
     /** Returns true if the decoder should try to dither the resulting image.
         The default setting is true.
     */
     bool getDitherImage() const { return fDitherImage; }
 
     /** Set to true if the the decoder should try to dither the resulting image.
         The default setting is true.
     */
     void setDitherImage(bool dither) { fDitherImage = dither; }
 
+    /** Returns true if the decoder should try to decode the
+        resulting image to a higher quality even at the expense of
+        the decoding speed.
+    */
+    bool getPreferQualityOverSpeed() const { return fPreferQualityOverSpeed; }
+
+    /** Set to true if the the decoder should try to decode the
+        resulting image to a higher quality even at the expense of
+        the decoding speed.
+    */
+    void setPreferQualityOverSpeed(bool qualityOverSpeed) {
+        fPreferQualityOverSpeed = qualityOverSpeed;
+    }
+
     /** \class Peeker
 
         Base class for optional callbacks to retrieve meta/chunk data out of
         an image as it is being decoded.
     */
     class Peeker : public SkRefCnt {
     public:
         SK_DECLARE_INST_COUNT(Peeker)
 
         /** Return true to continue decoding, or false to indicate an error, which
@@ skipping 104 matching lines @@
         which will allocated a pixelRef. To access the pixel memory, the codec
         needs to call lockPixels/unlockPixels on the
         bitmap. It can then set the pixels with the decompressed image.
     *   If the image cannot be decompressed, return false. After the
     *   decoding, the function converts the decoded config in bitmap
     *   to pref if possible. Whether a conversion is feasible is
     *   tested by Bitmap::canCopyTo(pref).
 
         note: document use of Allocator, Peeker and Chooser
     */
-    bool decode(SkStream*, SkBitmap* bitmap, SkBitmap::Config pref, Mode);
-    bool decode(SkStream* stream, SkBitmap* bitmap, Mode mode) {
-        return this->decode(stream, bitmap, SkBitmap::kNo_Config, mode);
+    bool decode(SkStream*, SkBitmap* bitmap, SkBitmap::Config pref, Mode, bool reuseBitmap = false);

[scroggo, 2013/03/13 16:04:14]

Some thoughts on reuseBitmap:
It appears to be only meaningful if Mode == kDecodePixels, making for an ugly
API.
I dislike that passing true to reuseBitmap can turn into a mysterious failure.
At the very least,  we should document the behavior. Also, it is not clear to me
why some decoders do not allow reuse of a bitmap.
It almost seems like it could be replaced with a custom allocator which just
reuses the existing pixels. I guess the drawback to that approach is that the
subclass cannot deny reuse. I suppose some caller attempts to reuse when it's
not allowed?

[djsollen, 2013/03/13 17:35:09]

The lack of support is not a technical problem, just that the android authors
didn't spend the time to do all codecs.

FWIW, I don't think this is a great API either, but it is what is currently in
use.

+    bool decode(SkStream* stream, SkBitmap* bitmap, Mode mode, bool reuseBitmap = false) {
+        return this->decode(stream, bitmap, SkBitmap::kNo_Config, mode, reuseBitmap);
     }
 
+    /**
+     * Given a stream, build an index for doing tile-based decode.
+     * The built index will be saved in the decoder, and the image size will
+     * be returned in width and height.
+     *
+     * Return true for success or false on failure.
+     */
+    virtual bool buildTileIndex(SkStream*, int *width, int *height);
+
+    /**
+     * Decode a rectangle region in the image specified by rect.
+     * The method can only be called after buildTileIndex().
+     *
+     * Return true for success.
+     * Return false if the index is never built or failing in decoding.
+     */
+    virtual bool decodeRegion(SkBitmap* bitmap, const SkIRect& rect,

[scroggo, 2013/03/13 16:04:14]

decodeRect?

[djsollen, 2013/03/13 17:35:09]

I don't want to change method signatures in this CL.

+                              SkBitmap::Config pref);
+
     /** Given a stream, this will try to find an appropriate decoder object.
         If none is found, the method returns NULL.
     */
     static SkImageDecoder* Factory(SkStream*);
 
     /** Decode the image stored in the specified file, and store the result
         in bitmap. Return true for success or false on failure.
 
         If pref is kNo_Config, then the decoder is free to choose the most natural
         config given the image data. If pref something other than kNo_Config,
@@ skipping 95 matching lines @@
     */
     static void SetDeviceConfig(SkBitmap::Config);
 
   /** @cond UNIT_TEST */
     SkDEBUGCODE(static void UnitTest();)
   /** @endcond */
 
 protected:
     // must be overridden in subclasses. This guy is called by decode(...)
     virtual bool onDecode(SkStream*, SkBitmap* bitmap, Mode) = 0;
 

[robertphillips, 2013/03/13 13:41:29]

Isn't the pattern to have a non-virtual decodeRegion/buildTileIndex and then
virtual on* methods? Do we need virtuals in all four locations?

[djsollen, 2013/03/13 17:35:09]

Done.

+    // If the decoder wants to support tiled based decoding,
+    // this method must be overridden. This guy is called by buildTileIndex(...)
+    virtual bool onBuildTileIndex(SkStream*, int *width, int *height) {
+        return false;
+    }
+
+    // If the decoder wants to support tiled based decoding,
+    // this method must be overridden. This guy is called by decodeRegion(...)
+    virtual bool onDecodeRegion(SkBitmap* bitmap, const SkIRect& rect) {
+        return false;
+    }
+
+    /*
+     * Crop a rectangle from the src Bitmap to the dest Bitmap. src and dst are
+     * both sampled by sampleSize from an original Bitmap.
+     *
+     * @param dst the destination bitmap.
+     * @param src the source bitmap that is sampled by sampleSize from the
+     *            original bitmap.
+     * @param sampleSize the sample size that src is sampled from the original bitmap.

[robertphillips, 2013/03/13 13:41:29]

make order in the comment match the order in the function call? bitimap ->
bitmap

[djsollen, 2013/03/13 17:35:09]

Done.

+     * @param (srcX, srcY) the upper-left point of the src bitimap in terms of
+     *                     the coordinate in the original bitmap.
+     * @param (width, height) the width and height of the unsampled dst.
+     * @param (dstX, dstY) the upper-left point of the dest bitmap in terms of
+     *                     the coordinate in the original bitmap.
+     */
+    void cropBitmap(SkBitmap *dst, SkBitmap *src, int sampleSize,
+                    int dstX, int dstY, int width, int height,
+                    int srcX, int srcY);
+
+
+
     /** Can be queried from within onDecode, to see if the user (possibly in
         a different thread) has requested the decode to cancel. If this returns
         true, your onDecode() should stop and return false.
         Each subclass needs to decide how often it can query this, to balance
         responsiveness with performance.
 
         Calling this outside of onDecode() may return undefined values.
      */
 
 public:
@@ skipping 30 matching lines @@
 private:
     Peeker*                 fPeeker;
     Chooser*                fChooser;
     SkBitmap::Allocator*    fAllocator;
     int                     fSampleSize;
     SkBitmap::Config        fDefaultPref;   // use if fUsePrefTable is false
     SkBitmap::Config        fPrefTable[6];  // use if fUsePrefTable is true
     bool                    fDitherImage;
     bool                    fUsePrefTable;
     mutable bool            fShouldCancelDecode;
+    bool                    fPreferQualityOverSpeed;
 
     // illegal
     SkImageDecoder(const SkImageDecoder&);
     SkImageDecoder& operator=(const SkImageDecoder&);
 };
 
 /** Calling newDecoder with a stream returns a new matching imagedecoder
     instance, or NULL if none can be found. The caller must manage its ownership
     of the stream as usual, calling unref() when it is done, as the returned
     decoder may have called ref() (and if so, the decoder is responsible for
@@ skipping 30 matching lines @@
     }
 
 // All the decoders known by Skia. Note that, depending on the compiler settings,
 // not all of these will be available
 DECLARE_DECODER_CREATOR(BMPImageDecoder);
 DECLARE_DECODER_CREATOR(GIFImageDecoder);
 DECLARE_DECODER_CREATOR(ICOImageDecoder);
 DECLARE_DECODER_CREATOR(JPEGImageDecoder);
 DECLARE_DECODER_CREATOR(PNGImageDecoder);
 DECLARE_DECODER_CREATOR(WBMPImageDecoder);
+DECLARE_DECODER_CREATOR(WEBPImageDecoder);
 
 #endif