add src-rect-constraint to drawImageRect

include/core/SkCanvas.h

Index: include/core/SkCanvas.h
diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h
index 9a46801a98bb3fe638f9ef5cd5eacb33ad30d982..44050296a92dd648c5467aaba8508d15116631cd 100644
--- a/include/core/SkCanvas.h
+++ b/include/core/SkCanvas.h
@@ -37,6 +37,16 @@ class GrRenderTarget;
 
 class SkCanvasState;
 
+#ifdef SK_SUPPORT_LEGACY_ONDRAWIMAGERECT
+    #define SRC_RECT_CONSTRAINT_PARAM(param)
+    #define SRC_RECT_CONSTRAINT_ARG(arg)
+    #define SRC_RECT_CONSTRAINT_LOCAL_DEFAULT(var)  SkCanvas::SrcRectConstraint var = SkCanvas::kStrict_SrcRectConstraint;
+#else
+    #define SRC_RECT_CONSTRAINT_PARAM(param)    , SrcRectConstraint param
+    #define SRC_RECT_CONSTRAINT_ARG(arg)        , arg

[f(malita), 2015/07/09 21:28:36]

For some reason I recall trying this same approach a while back (saveFlags?),
and finding that commas are not valid define substitutions.  Does this work on
all platforms?  I guess we'll find out soon enough :)

+    #define SRC_RECT_CONSTRAINT_LOCAL_DEFAULT(var)
+#endif
+
 /** \class SkCanvas
 
     A Canvas encapsulates all of the state about drawing into a device (bitmap).
@@ -778,17 +788,50 @@ public:
         @param paint    The paint used to draw the image, or NULL
      */
     void drawImage(const SkImage* image, SkScalar left, SkScalar top, const SkPaint* paint = NULL);
-    /** Draw the specified image, with the specified matrix applied (before the
-        canvas' matrix is applied).
 
-        @param image   The image to be drawn
-        @param src      Optional: specify the subset of the image to be drawn
-        @param dst      The destination rectangle where the scaled/translated
-                        image will be drawn
-        @param paint    The paint used to draw the image, or NULL
-    */
+    /**
+     *  Controls the behavior at the edge of the src-rect, when specified in drawImageRect,
+     *  trading off speed for exactness.
+     *
+     *  When filtering is enabled (in the Paint), skia may need to sample in a neighborhood around
+     *  the pixels in the image. If there is a src-rect specified, it is intended to restrict the
+     *  pixels that will be read. However, for performance reasons, some implementations may slow
+     *  down if they cannot read 1-pixel past the src-rect boundary at times.
+     *
+     *  This enum allows the caller to specify if such a 1-pixel "slop" will be visually acceptable.
+     *  If it is, the caller should pass kFast, and it may result in a faster draw. If the src-rect
+     *  must be strictly respected, the caller should pass kStrict.
+     */
+    enum SrcRectConstraint {
+        /**
+         *  If kStrict is specified, the implementation must respect the src-rect
+         *  (if specified) strictly, and will never sample outside of those bounds during sampling
+         *  even when filtering. This may be slower than kFast.
+         */
+        kStrict_SrcRectConstraint,
+
+        /**
+         *  If kFast is specified, the implementation may sample outside of the src-rect
+         *  (if specified) by at most 1 pixel when filtering. This allows greater flexibility
+         *  to the implementation and can make the draw much faster.
+         */
+        kFast_SrcRectConstraint,
+    };

[f(malita), 2015/07/09 21:28:36]

Awesome documentation!

+
+    /** Draw the specified image, scaling and translating so that it fills the specified
+     *  dst rect. If the src rect is non-null, only that subset of the image is transformed
+     *  and drawn.
+     *
+     *  @param image      The image to be drawn
+     *  @param src        Optional: specify the subset of the image to be drawn
+     *  @param dst        The destination rectangle where the scaled/translated
+     *                    image will be drawn
+     *  @param paint      The paint used to draw the image, or NULL
+     *  @param constraint Control the tradeoff between speed and exactness w.r.t. the src-rect.
+     */
     void drawImageRect(const SkImage* image, const SkRect* src, const SkRect& dst,
-                       const SkPaint* paint = NULL);
+                       const SkPaint* paint = NULL,
+                       SrcRectConstraint constraint = kStrict_SrcRectConstraint);

[f(malita), 2015/07/09 21:28:36]

I don't feel strongly, but aren't multiple default param values discouraged?

[reed1, 2015/07/10 15:07:50]

Good point. Fixed.

 
     /**
      *  Draw the image stretched differentially to fit into dst.
@@ -826,6 +869,20 @@ public:
     void drawBitmap(const SkBitmap& bitmap, SkScalar left, SkScalar top,
                     const SkPaint* paint = NULL);
 
+    /** Draw the specified bitmap, scaling and translating so that it fills the specified
+     *  dst rect. If the src rect is non-null, only that subset of the bitmap is transformed
+     *  and drawn.
+     *
+     *  @param bitmap     The bitmap to be drawn
+     *  @param src        Optional: specify the subset of the bitmap to be drawn
+     *  @param dst        The destination rectangle where the scaled/translated
+     *                    bitmap will be drawn
+     *  @param paint      The paint used to draw the bitmap, or NULL
+     *  @param constraint Control the tradeoff between speed and exactness w.r.t. the src-rect.
+     */
+    void drawBitmapRect(const SkBitmap& bitmap, const SkRect* src, const SkRect& dst,
+                        const SkPaint* paint, SrcRectConstraint constraint);
+
     enum DrawBitmapRectFlags {
         kNone_DrawBitmapRectFlag            = 0x0,
         /**
@@ -1245,7 +1302,8 @@ protected:
                              int count, SkXfermode::Mode, const SkRect* cull, const SkPaint*);
     virtual void onDrawPath(const SkPath&, const SkPaint&);
     virtual void onDrawImage(const SkImage*, SkScalar dx, SkScalar dy, const SkPaint*);
-    virtual void onDrawImageRect(const SkImage*, const SkRect*, const SkRect&, const SkPaint*);
+    virtual void onDrawImageRect(const SkImage*, const SkRect*, const SkRect&, const SkPaint*
+                                 SRC_RECT_CONSTRAINT_PARAM(constraint));
     virtual void onDrawImageNine(const SkImage*, const SkIRect& center, const SkRect& dst,
                                  const SkPaint*);
 
@@ -1365,7 +1423,7 @@ private:
     void internalDrawBitmap(const SkBitmap&, const SkMatrix& m, const SkPaint* paint);
     void internalDrawBitmapRect(const SkBitmap& bitmap, const SkRect* src,
                                 const SkRect& dst, const SkPaint* paint,
-                                DrawBitmapRectFlags flags);
+                                SrcRectConstraint);
     void internalDrawPaint(const SkPaint& paint);
     void internalSaveLayer(const SkRect* bounds, const SkPaint*, SaveFlags, SaveLayerStrategy);
     void internalDrawDevice(SkBaseDevice*, int x, int y, const SkPaint*, bool isBitmapDevice);