Allow client to force an SkImage snapshot to be unique (and uniquely own its backing store).

include/core/SkSurface.h

 /*
  * Copyright 2012 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkSurface_DEFINED
 #define SkSurface_DEFINED
 
@@ skipping 210 matching lines @@
      *  SkCanvas* canvasA = surfaceA->newCanvas();
      *  ...
      *  SkSurface* surfaceB = surfaceA->newSurface(...);
      *  SkCanvas* canvasB = surfaceB->newCanvas();
      *  ... // draw using canvasB
      *  canvasA->drawSurface(surfaceB); // <--- this will always be optimal!
      */
     SkSurface* newSurface(const SkImageInfo&);
 
     /**
+     * In rare instances a client may want a unique copy of the SkSurface's contents in an image
+     * snapshot. This enum can be used to enforce that the image snapshot's backing store is not
+     * shared with another image snapshot or the surface's backing store. This is generally more
+     * expensive.
+     */
+    enum ForceUnique {
+        kNo_ForceUnique,
+        kYes_ForceUnique
+    };
+
+    /**
      *  Returns an image of the current state of the surface pixels up to this
      *  point. Subsequent changes to the surface (by drawing into its canvas)
      *  will not be reflected in this image. If a copy must be made the Budgeted
      *  parameter controls whether it counts against the resource budget
      *  (currently for the gpu backend only).
      */
-    SkImage* newImageSnapshot(Budgeted = kYes_Budgeted);
+    SkImage* newImageSnapshot(Budgeted = kYes_Budgeted, ForceUnique = kNo_ForceUnique);

[reed1, 2016/02/15 21:32:13]

Crud. I think its cruddy when we have more than one default arg. I had forgotten
that we had budgeted. I wonder if we should just have a 2nd version that
explicitly requires both enums..?

 
     /**
      *  Though the caller could get a snapshot image explicitly, and draw that,
      *  it seems that directly drawing a surface into another canvas might be
      *  a common pattern, and that we could possibly be more efficient, since
      *  we'd know that the "snapshot" need only live until we've handed it off
      *  to the canvas.
      */
     void draw(SkCanvas*, SkScalar x, SkScalar y, const SkPaint*);
 
@@ skipping 44 matching lines @@
 private:
     const SkSurfaceProps fProps;
     const int            fWidth;
     const int            fHeight;
     uint32_t             fGenerationID;
 
     typedef SkRefCnt INHERITED;
 };
 
 #endif