Refactor SkBitmapRegionDecoderInterface for Android

tools/SkBitmapRegionDecoderInterface.h

Index: tools/SkBitmapRegionDecoderInterface.h
diff --git a/tools/SkBitmapRegionDecoderInterface.h b/tools/SkBitmapRegionDecoderInterface.h
index e1f79bccb66b263d7fcf1f5e8d7e4d2e26a06e56..f05b6b1f4da51e3a302c3f122bc0ee8b9d92d330 100644
--- a/tools/SkBitmapRegionDecoderInterface.h
+++ b/tools/SkBitmapRegionDecoderInterface.h
@@ -25,6 +25,15 @@ public:
     };
 
     /*
+     * Defines the relationship of the requested subset to the original image.
+     */
+    enum SubsetType {
+        kFullyInside_SubsetType,
+        kPartiallyInside_SubsetType,
+        kOutside_SubsetType,
+    };
+
+    /*
      * @param data     Refs the data while this object exists, unrefs on destruction
      * @param strategy Strategy used for scaling and subsetting
      * @return         Tries to create an SkBitmapRegionDecoder, returns NULL on failure
@@ -33,33 +42,50 @@ public:
             SkData* data, Strategy strategy);
 
     /*
-     * Decode a scaled region of the encoded image stream
+     * Must be called before decodeRegion().  Processes the subset, sample size,
+     * color type, and alpha type for the decode.  Reports the output image info.
+     *
+     * CAVEAT:
+     * kOriginal_Strategy performs the initial set-up, pixel allocation, and
+     * subset decode all in one step.  For kOriginal_Strategy, this function
+     * will not set outInfo, since it will allocate its own pixels later
+     * in decodeRegion().
      *
-     * @param start_x    X-coordinate of upper-left corner of region.
-     *                   This coordinate is unscaled, relative to the original dimensions.
-     * @param start_y    Y-coordinate of upper-left corner of region.
-     *                   This coordinate is unscaled, relative to the original dimensions.
-     * @param width      Width of the region to decode.
-     *                   This distance is unscaled, relative to the original dimensions.
-     * @param height     Height of the region to decode.
-     *                   This distance is unscaled, relative to the original dimensions.
-     * @param sampleSize An integer downscaling factor for the decode.
-     * @param colorType  Preferred output colorType.
-     *                   New implementations should return NULL if they do not support
-     *                   decoding to this color type.
-     *                   The old kOriginal_Strategy will decode to a default color type
-     *                   if this color type is unsupported.
-     * @return           Pointer to a bitmap of the decoded region on success, NULL on
-     *                   failure.
+     * @param desiredSubset   Subset of the original image to decode.
+     * @param sampleSize      Downscale factor.
+     * @param colorType       Color type to decode to.
+     * @param requireUnpremul If the image is not opaque, we will use this to
+     *                        determine the alpha type to use.
+     * @param outInfo         Output parameter used to indicate the properties
+     *                        of the output.
+     *
+     * @return true if the desiredSubset intersects at least part of the image

[scroggo, 2015/10/27 15:00:51]

Should this return a SubsetType?

+     *              and we support the conversion to the requested color type.
+     *         false otherwise.
      */
-    virtual SkBitmap* decodeRegion(int start_x, int start_y, int width,
-                                   int height, int sampleSize,
-                                   SkColorType colorType) = 0;
+    virtual bool prepareRegion(const SkIRect& desiredSubset, int sampleSize,
+            SkColorType colorType, bool requireUnpremul, SkImageInfo* outInfo) = 0;
+
     /*
-     * @param  Requested destination color type
-     * @return true if we support the requested color type and false otherwise
+     * Must be called after prepareRegion(), decodes the subset requested in
+     * prepareRegion() into the provided bitmap.
+     *
+     * CAVEAT:
+     * kOriginal_Strategy performs the initial set-up, pixel allocation, and
+     * subset decode all in one step.  This means that decodeRegion() may
+     * fail due to invalid parameters passed to prepareRegion() (ex: invalid
+     * subset, invalid color type, etc).
+     * Also, kOriginal_Strategy will allocate its own pixels on the input
+     * bitmap, while the other strategies expect that the pixels will already
+     * be allocated.
+     *
+     * @param bitmap Must be large enough to contain the requested subset.

[scroggo, 2015/10/27 15:00:51]

I find this comment confusing. I guess you're saying that you expect the caller
has called setInfo no matter what, and allocPixels except for kOriginal.

+     *               Unless we are using kOriginal_Strategy, the pixels
+     *               must already be allocated.
+     *
+     * @return true on success, false on failure.
      */
-    virtual bool conversionSupported(SkColorType colorType) = 0;
+    virtual bool decodeRegion(SkBitmap& bitmap) = 0;

[scroggo, 2015/10/27 15:00:50]

Typically we use a pointer if we are going to modify it.

 
     int width() const { return fWidth; }
     int height() const { return fHeight; }