API to support native scaling by image-generator

include/core/SkImageGenerator.h

Index: include/core/SkImageGenerator.h
diff --git a/include/core/SkImageGenerator.h b/include/core/SkImageGenerator.h
index 3d508ddfb1c7ec7f1ceb34b9a12d3ce3d50f6060..c3b6bb1885e161035262ef801b5f0ac5ab175e76 100644
--- a/include/core/SkImageGenerator.h
+++ b/include/core/SkImageGenerator.h
@@ -153,6 +153,45 @@ public:
     GrTexture* generateTexture(GrContext*, const SkIRect* subset = nullptr);
 
     /**
+     *  Some generators can efficiently scale their contents. If this is supported, the generator
+     *  may only support certain scaled dimensions. Call this with the desired scale factor,
+     *  and it will return true if scaling is supported, and in supportedSizes[] it will return
+     *  the two nearest supported dimensions...
+     *
+     *  If the requested scale is exactly supported, then both entries
+     *  supporedSizes[0] and supportedSizes[1] will hold the same dimensions.
+     *
+     *  However, often the requested size may result in a fractional resulting width/height,
+     *  and or not be natively supported by the generator. (e.g. the scale is 1/3, but the
+     *  generator only performs native scaling on powers-of-2 fractions). In this case...
+     *  - if the generator can natively scale at a smaller size (e.g. 1/4), that will be returned
+     *      in supportedSizes[0]
+     *  - if the generator can natively scale at a larger size (e.g. 1/2), that will be returned
+     *      in supportedSizes[1]
+     *  - if the generator can only natively scale smaller, or only larger, than the
+     *      requested scale, then that 1 native size will returned in both [0] and [1].

[scroggo, 2015/11/03 16:59:19]

will be* returned

[reed1, 2015/11/30 20:38:01]

Done.

+     *
+     *  If no native scaling is supported, or scale is invalid (e.g. scale <= 0 || scale > 1)
+     *  this will return false, and supportedSizes[] will be undefined.
+     */
+    bool computeScaledDimensions(SkScalar scale, SkISize supportedSizes[2]);

[scroggo, 2015/11/03 16:59:19]

As stated in person, I'd prefer something other than an array here. Something
like one of the following:

bool computeScaledDimensions(SkScalar scale, SkISize* smallerNativeSize,
                             SkISize* largerNativeSize);

or

struct sizes {
  SkISize smaller;
  SkISize larger;
};

bool computeScaledDimensions(SkScalar scale, sizes* supportedSizes);

I find these better for a couple of reasons:
- the variables are named (rather than remembering the difference between
supportedSizes[0] and supportedSizes[1])
- the compiler will enforce that you pass the correct number of things to
computeScaledDimensions

[reed1, 2015/11/30 20:38:01]

Done.

+

[scroggo, 2015/11/03 16:59:19]

Should computeScaledDimensions be const?

[reed1, 2015/11/30 20:38:01]

None of the other methods are, though *all* are meant to always return the same
value, even if called multiple times.

+    /**
+     *  Request that pixels be scaled to fit into the specified scaledInfo dimensions.
+     *  If scaledClip is not null, it specifies the subset of the scaled pixels that should
+     *  be returned. It will be in the scaled coordinate system (not the original), and is only
+     *  valid if it is entirely contained inside the scaled dimensions...
+     *
+     *  SkIRect scaledBounds = SkIRect::MakeWH(0, 0, scaledInfo.width(), scaledInfo.height());
+     *  bool valid = scaledBounds.contains(scaledClip);
+     *
+     *  If the requested scaledInfo is not supported by the generator, or it encounters an error,
+     *  or the scaledClip is invalid, this returns false and the contents of pixels is undefined.
+     */
+    bool generateScaledPixels(const SkImageInfo& scaledInfo, void* pixels, size_t rowBytes,
+                              const SkIRect* scaledClip);
+
+    /**
      *  If the default image decoder system can interpret the specified (encoded) data, then
      *  this returns a new ImageGenerator for it. Otherwise this returns NULL. Either way
      *  the caller is still responsible for managing their ownership of the data.
@@ -199,6 +238,14 @@ protected:
         return nullptr;
     }
 
+    virtual bool onComputeScaledDimensions(SkScalar scale, SkISize supportedSizes[2]) {
+        return false;
+    }
+    virtual bool onGenerateScaledPixels(const SkImageInfo& info, void* pixels, size_t rowBytes,
+                                        const SkIRect* subset) {
+        return false;
+    }
+
     bool tryGenerateBitmap(SkBitmap* bm, const SkImageInfo* optionalInfo, SkBitmap::Allocator*);
 
 private: