API to support native scaling by image-generator

include/core/SkImageGenerator.h

 /*
  * Copyright 2013 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkImageGenerator_DEFINED
 #define SkImageGenerator_DEFINED
 
@@ skipping 135 matching lines @@
      *  Regarding the GrTextureParams parameter:
      *
      *  If the context (the provided one or the generator's intrinsic one) determines that to
      *  support the specified usage, it must return a different sized texture it may,
      *  so the caller must inspect the texture's width/height and compare them to the generator's
      *  getInfo() width/height. For readback usage use GrTextureParams::ClampNoFilter()
      */
     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.
      */
     static SkImageGenerator* NewFromEncoded(SkData*);
 
     /** Return a new image generator backed by the specified picture.  If the size is empty or
      *  the picture is NULL, this returns NULL.
      *  The optional matrix and paint arguments are passed to drawPicture() at rasterization
      *  time.
@@ skipping 26 matching lines @@
     virtual bool onGetPixels(const SkImageInfo& info, void* pixels, size_t rowBytes,
                              SkPMColor ctable[], int* ctableCount);
     virtual bool onGetYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3]);
     virtual bool onGetYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3],
                                  SkYUVColorSpace* colorSpace);
 
     virtual GrTexture* onGenerateTexture(GrContext*, const SkIRect*) {
         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:
     const SkImageInfo fInfo;
     const uint32_t fUniqueID;
 
     // This is our default impl, which may be different on different platforms.
     // It is called from NewFromEncoded() after it has checked for any runtime factory.
     // The SkData will never be NULL, as that will have been checked by NewFromEncoded.
     static SkImageGenerator* NewFromEncodedImpl(SkData*);
 };
 
 #endif  // SkImageGenerator_DEFINED