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..375057ce330a105800835d96acf5d5f6cd2b7518 100644
--- a/include/core/SkImageGenerator.h
+++ b/include/core/SkImageGenerator.h
@@ -153,6 +153,73 @@ 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 sukpportedSizes[1]

[msarett, 2015/10/29 19:50:24]

nit: *supported

[reed1, 2015/11/02 20:52:59]

Done.

+     *  - 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].
+     *
+     *  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]);

[msarett, 2015/10/29 19:50:24]

I prefer these comments.

[reed1, 2015/11/02 20:52:59]

Done.

+
+    /**
+     *  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.
+     *
+     *      requestedWidth = originalWidth * scale
+     *      requestedHeight = originalHeight * scale
+     *
+     *  The calculated requested dimensions may be fractional, or the generator may not natively
+     *  support scaling to those values (e.g. JPEG typically can only scale by powers of 2).

[msarett, 2015/10/29 19:50:24]

JPEG gives us all the eighths.  Ex: 1/8, 1/4, 3/8, 1/2, 5/8, 3/4, 7/8.

But powers of 2 tend to be a bit more efficient.
https://docs.google.com/spreadsheets/d/1V_-6seZXa0h2flox1bfOO3WQQtplrk5F7I26d...

[reed1, 2015/11/02 20:52:59]

Gone

+     *
+     *  This API allows the generator to report back 2 "suggested" scaled dimensions, that would
+     *  be natively supported. The generator will try to return one that is <= the requested
+     *  dimensions, and one that is >= the requested dimension. This allows the caller
+     *  to make the choice of which approximate size to pass to generateScaledPixels().
+     */
+    bool computeScaledDimensions(SkScalar scale, SkISize supportedSizes[2]);
+
+    /**
+     *  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,

[msarett, 2015/10/29 19:50:24]

I'm indifferent on this, but I lean towards this API.

[aleksandar.stojiljkovic, 2015/10/29 20:39:35]

if SkImageInfo can be supplied here, i.e. 565 or Index8, could there also be a
query for getting supported colorTypes?

[reed1, 2015/11/02 20:52:59]

Done.

[reed1, 2015/11/02 20:52:59]

1. 565

Decoding (generating) into 565 is pretty harsh, since there is (typically) a
loss of quality, and questions about dithering (unless we're not going to dither
either). What is your interest in getting scaled output into 565?

2. Index8

Supporting Index8 (it seems to me) is binary -- either the original colortype is
Index8, in which case we can subset or scale (sans any filtering/dithering) into
it as well. If the original is *not* Index8, then I propose that we never expect
the generator to convert into Index8.

+                              const SkIRect* scaledClip);
+
+    /**
+     *  Request a scaled version (specified by scaledDimension) of the pixels.
+     *  If the caller wants only a subset of the scaled result, it will put the top/left coordiante
+     *  of the desired subset in offset.
+     *  info.width and info.height are the dimensions of the desired subset.
+     */
+    bool generateScaledPixels(const SkISize& scaledDimensions, const SkIPoint& offset,
+                              const SkImageInfo& info, void* pixels, size_t rowBytes);
+
+    /**
      *  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 +266,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: