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 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.
      */
     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