Refactor SkBitmapRegionDecoderInterface for Android

tools/SkBitmapRegionDecoderInterface.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 SkBitmapRegionDecoder_DEFINED
 #define SkBitmapRegionDecoder_DEFINED
 
 #include "SkBitmap.h"
 #include "SkStream.h"
 
 /*
  * This class aims to provide an interface to test multiple implementations of
  * SkBitmapRegionDecoder.
  */
 class SkBitmapRegionDecoderInterface {
 public:
 
     enum Strategy {
         kCanvas_Strategy,       // Draw to the canvas, uses SkCodec
         kOriginal_Strategy,     // Sampling, uses SkImageDecoder
         kAndroidCodec_Strategy, // Uses SkAndroidCodec for scaling and subsetting
     };
 
     /*
+     * 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
      */
     static SkBitmapRegionDecoderInterface* CreateBitmapRegionDecoder(
             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.
      *
-     * @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.
+     * 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 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; }
 
     virtual ~SkBitmapRegionDecoderInterface() {}
 
 protected:
 
     SkBitmapRegionDecoderInterface(int width, int height)
         : fWidth(width)
         , fHeight(height)
     {}
 
 private:
     const int fWidth;
     const int fHeight;
 };
 
 #endif