add src-rect-constraint to drawImageRect

include/core/SkCanvas.h

 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkCanvas_DEFINED
 #define SkCanvas_DEFINED
 
@@ skipping 19 matching lines @@
 class SkRRect;
 struct SkRSXform;
 class SkSurface;
 class SkSurface_Base;
 class SkTextBlob;
 class GrContext;
 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).
     This includes a reference to the device itself, and a stack of matrix/clip
     values. For any given draw call (e.g. drawRect), the geometry of the object
     being drawn is transformed by the concatenation of all the matrices in the
     stack. The transformed geometry is clipped by the intersection of all of
     the clips in the stack.
 
     While the Canvas holds the state of the drawing device, the state (style)
@@ skipping 721 matching lines @@
 
     /** Draw the specified image, with its top/left corner at (x,y), using the
         specified paint, transformed by the current matrix.
 
         @param image    The image to be drawn
         @param left     The position of the left side of the image being drawn
         @param top      The position of the top side of the image being drawn
         @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.
      *  center is a rect within the image, and logically divides the image
      *  into 9 sections (3x3). For example, if the middle pixel of a [5x5]
      *  image is the "center", then the center-rect should be [2, 2, 3, 3].
      *
      *  If the dst is >= the image size, then...
      *  - The 4 corners are not stretched at all.
      *  - The sides are stretched in only one axis.
@@ skipping 17 matching lines @@
         generated by the shader.
 
         @param bitmap   The bitmap to be drawn
         @param left     The position of the left side of the bitmap being drawn
         @param top      The position of the top side of the bitmap being drawn
         @param paint    The paint used to draw the bitmap, or NULL
     */
     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,
         /**
          *  When filtering is enabled, allow the color samples outside of
          *  the src rect (but still in the src bitmap) to bleed into the
          *  drawn portion
          */
         kBleed_DrawBitmapRectFlag           = 0x1,
     };
 
     /** Draw the specified bitmap, with the specified matrix applied (before the
         canvas' matrix is applied).
         @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
                         image will be drawn
         @param paint    The paint used to draw the bitmap, or NULL
     */
     void drawBitmapRectToRect(const SkBitmap& bitmap, const SkRect* src, const SkRect& dst,
                               const SkPaint* paint = NULL,
                               DrawBitmapRectFlags flags = kNone_DrawBitmapRectFlag);

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

Are we going to switch this to the new enum at some point?  Or just deprecate
this variant?

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

Plan to switch, as I now expose a version of drawBitmapRect that takes the
constraint. However, removing flags is complicated due to blink/chrome, so I
will do that in a follow-on CL.

Note: SkDevice has already been converted over to SrcRectConstraint

 
     void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst,
                         const SkPaint* paint = NULL) {
         this->drawBitmapRectToRect(bitmap, NULL, dst, paint, kNone_DrawBitmapRectFlag);
     }
 
     void drawBitmapRect(const SkBitmap& bitmap, const SkIRect* isrc,
                         const SkRect& dst, const SkPaint* paint = NULL,
                         DrawBitmapRectFlags flags = kNone_DrawBitmapRectFlag) {
         SkRect realSrcStorage;
@@ skipping 378 matching lines @@
     virtual void onDrawRRect(const SkRRect&, const SkPaint&);
     virtual void onDrawPoints(PointMode, size_t count, const SkPoint pts[], const SkPaint&);
     virtual void onDrawVertices(VertexMode, int vertexCount, const SkPoint vertices[],
                                 const SkPoint texs[], const SkColor colors[], SkXfermode*,
                                 const uint16_t indices[], int indexCount, const SkPaint&);
 
     virtual void onDrawAtlas(const SkImage*, const SkRSXform[], const SkRect[], const SkColor[],
                              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*);
 
     virtual void onDrawBitmap(const SkBitmap&, SkScalar dx, SkScalar dy, const SkPaint*);
     virtual void onDrawBitmapRect(const SkBitmap&, const SkRect*, const SkRect&, const SkPaint*,
                                   DrawBitmapRectFlags);
     virtual void onDrawBitmapNine(const SkBitmap&, const SkIRect& center, const SkRect& dst,
                                   const SkPaint*);
     virtual void onDrawSprite(const SkBitmap&, int left, int top, const SkPaint*);
 
@@ skipping 99 matching lines @@
      * to be public because it exposes decisions about layer sizes that are internal to the canvas.
      */
     SkISize getTopLayerSize() const;
     SkIPoint getTopLayerOrigin() const;
 
     // internal methods are not virtual, so they can safely be called by other
     // canvas apis, without confusing subclasses (like SkPictureRecording)
     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);
 
     // shared by save() and saveLayer()
     void internalSave();
     void internalRestore();
     static void DrawRect(const SkDraw& draw, const SkPaint& paint,
                          const SkRect& r, SkScalar textSize);
     static void DrawTextDecorations(const SkDraw& draw, const SkPaint& paint,
@@ skipping 135 matching lines @@
 
 class SkCanvasClipVisitor {
 public:
     virtual ~SkCanvasClipVisitor();
     virtual void clipRect(const SkRect&, SkRegion::Op, bool antialias) = 0;
     virtual void clipRRect(const SkRRect&, SkRegion::Op, bool antialias) = 0;
     virtual void clipPath(const SkPath&, SkRegion::Op, bool antialias) = 0;
 };
 
 #endif