Deprecate SaveFlags use in the public SkCanvas API.

Because we still have internal users for now (to support the deprecated
mode), this CL introduces an external-only variant of deprecation.

Chromium is no longer using the deprecated methods, but Android may need
to suppress SK_ATTR_EXTERNALLY_DEPRECATED warnings.

R=reed@google.com, robertphillips@google.com, scroggo@google.com, bungeman@google.com, mtklein@google.com

Author: fmalita@chromium.org

Review URL: https://codereview.chromium.org/246023008

git-svn-id: http://skia.googlecode.com/svn/trunk@14367 2bbb7eff-a529-9590-31e7-b0007b416f81

diff --git a/gyp/common.gypi b/gyp/common.gypi
index 2a5bbd493e216bdd6009e8c58857076c3265a8d7..0846fef7b3af98327344c8a581e38b6fc8bf6c89 100644 (file)
--- a/gyp/common.gypi
+++ b/gyp/common.gypi
@@ -12,6 +12,7 @@
 
   'target_defaults': {
     'defines': [
+      'SK_INTERNAL',
       'SK_GAMMA_SRGB',
       'SK_GAMMA_APPLY_TO_A8',
       'SK_SCALAR_TO_FLOAT_EXCLUDED',  # temporary to allow Chrome to call SkFloatToScalar

diff --git a/gyp/common_conditions.gypi b/gyp/common_conditions.gypi
index 175b8b09edc41bbf9030e9517a17fac302c12a99..ed302450e7ffc228b1c7eb624819229f6c19750e 100644 (file)
--- a/gyp/common_conditions.gypi
+++ b/gyp/common_conditions.gypi
@@ -309,6 +309,8 @@
         'SK_SUPPORT_LEGACY_BLURDRAWLOOPERCONSTRUCTORS',
         # Needed until we fix skbug.com/2440.
         'SK_SUPPORT_LEGACY_CLIPTOLAYERFLAG',
+        # Transitional, for deprecated SkCanvas::SaveFlags methods.
+        'SK_ATTR_DEPRECATED=SK_NOTHING_ARG1',
       ],
     }],
 

diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h
index 562999da4729b7840ccab7e6694a26db6b6bf73a..70cfe287b85bb9226803dbdaf045db185eeb96a8 100644 (file)
--- a/include/core/SkCanvas.h
+++ b/include/core/SkCanvas.h
@@ -330,6 +330,16 @@ public:
         operate on this copy.
         When the balancing call to restore() is made, the previous matrix, clip,
         and drawFilter are restored.
+
+        @return The value to pass to restoreToCount() to balance this save()
+    */
+    int save();
+
+    /** DEPRECATED - use save() instead.
+
+        This behaves the same as save(), but it allows fine-grained control of
+        which state bits to be saved (and subsequently restored).
+
         @param flags The flags govern what portion of the Matrix/Clip/drawFilter
                      state the save (and matching restore) effect. For example,
                      if only kMatrix is specified, then only the matrix state
@@ -338,12 +348,29 @@ public:
                      by calls to save/restore.
         @return The value to pass to restoreToCount() to balance this save()
     */
-    int save(SaveFlags flags = kMatrixClip_SaveFlag);
+    SK_ATTR_EXTERNALLY_DEPRECATED("SaveFlags use is deprecated")
+    int save(SaveFlags flags);
 
     /** This behaves the same as save(), but in addition it allocates an
         offscreen bitmap. All drawing calls are directed there, and only when
         the balancing call to restore() is made is that offscreen transfered to
         the canvas (or the previous layer).
+        @param bounds (may be null) This rect, if non-null, is used as a hint to
+                      limit the size of the offscreen, and thus drawing may be
+                      clipped to it, though that clipping is not guaranteed to
+                      happen. If exact clipping is desired, use clipRect().
+        @param paint (may be null) This is copied, and is applied to the
+                     offscreen when restore() is called
+        @return The value to pass to restoreToCount() to balance this save()
+    */
+    int saveLayer(const SkRect* bounds, const SkPaint* paint);
+
+    /** DEPRECATED - use saveLayer(const SkRect*, const SkPaint*) instead.
+
+        This behaves the same as saveLayer(const SkRect*, const SkPaint*),
+        but it allows fine-grained control of which state bits to be saved
+        (and subsequently restored).
+
         @param bounds (may be null) This rect, if non-null, is used as a hint to
                       limit the size of the offscreen, and thus drawing may be
                       clipped to it, though that clipping is not guaranteed to
@@ -353,13 +380,28 @@ public:
         @param flags  LayerFlags
         @return The value to pass to restoreToCount() to balance this save()
     */
-    int saveLayer(const SkRect* bounds, const SkPaint* paint,
-                  SaveFlags flags = kARGB_ClipLayer_SaveFlag);
+    SK_ATTR_EXTERNALLY_DEPRECATED("SaveFlags use is deprecated")
+    int saveLayer(const SkRect* bounds, const SkPaint* paint, SaveFlags flags);
 
     /** This behaves the same as save(), but in addition it allocates an
         offscreen bitmap. All drawing calls are directed there, and only when
         the balancing call to restore() is made is that offscreen transfered to
         the canvas (or the previous layer).
+        @param bounds (may be null) This rect, if non-null, is used as a hint to
+                      limit the size of the offscreen, and thus drawing may be
+                      clipped to it, though that clipping is not guaranteed to
+                      happen. If exact clipping is desired, use clipRect().
+        @param alpha  This is applied to the offscreen when restore() is called.
+        @return The value to pass to restoreToCount() to balance this save()
+    */
+    int saveLayerAlpha(const SkRect* bounds, U8CPU alpha);
+
+    /** DEPRECATED - use saveLayerAlpha(const SkRect*, U8CPU) instead.
+
+        This behaves the same as saveLayerAlpha(const SkRect*, U8CPU),
+        but it allows fine-grained control of which state bits to be saved
+        (and subsequently restored).
+
         @param bounds (may be null) This rect, if non-null, is used as a hint to
                       limit the size of the offscreen, and thus drawing may be
                       clipped to it, though that clipping is not guaranteed to
@@ -368,8 +410,8 @@ public:
         @param flags  LayerFlags
         @return The value to pass to restoreToCount() to balance this save()
     */
-    int saveLayerAlpha(const SkRect* bounds, U8CPU alpha,
-                       SaveFlags flags = kARGB_ClipLayer_SaveFlag);
+    SK_ATTR_EXTERNALLY_DEPRECATED("SaveFlags use is deprecated")
+    int saveLayerAlpha(const SkRect* bounds, U8CPU alpha, SaveFlags flags);
 
     /** This call balances a previous call to save(), and is used to remove all
         modifications to the matrix/clip/drawFilter state since the last save

diff --git a/include/core/SkPostConfig.h b/include/core/SkPostConfig.h
index 53b4adfaa5833c6b732a1891ae13e4c18c9db5f2..bee87e621245d63a4f3d479dff9fd3ced7038823 100644 (file)
--- a/include/core/SkPostConfig.h
+++ b/include/core/SkPostConfig.h
@@ -323,6 +323,14 @@
 #  define SK_ATTR_DEPRECATED(msg) SK_ATTRIBUTE(deprecated)
 #endif
 
+#if !defined(SK_ATTR_EXTERNALLY_DEPRECATED)
+#  if !defined(SK_INTERNAL)
+#    define SK_ATTR_EXTERNALLY_DEPRECATED(msg) SK_ATTR_DEPRECATED(msg)
+#  else
+#    define SK_ATTR_EXTERNALLY_DEPRECATED(msg)
+#  endif
+#endif
+
 /**
  * If your judgment is better than the compiler's (i.e. you've profiled it),
  * you can use SK_ALWAYS_INLINE to force inlining. E.g.

diff --git a/src/core/SkCanvas.cpp b/src/core/SkCanvas.cpp
index 0598528ba2c5805f8f2c9f339f3ae002d303f991..6c0fc884e1a53472f3a3681df8537c69dc283c6a 100644 (file)
--- a/src/core/SkCanvas.cpp
+++ b/src/core/SkCanvas.cpp
@@ -834,6 +834,11 @@ void SkCanvas::willSave(SaveFlags) {
     // Do nothing. Subclasses may do something.
 }
 
+int SkCanvas::save() {
+    this->willSave(kMatrixClip_SaveFlag);
+    return this->internalSave(kMatrixClip_SaveFlag);
+}
+
 int SkCanvas::save(SaveFlags flags) {
     this->willSave(flags);
     // call shared impl
@@ -898,9 +903,13 @@ SkCanvas::SaveLayerStrategy SkCanvas::willSaveLayer(const SkRect*, const SkPaint
     return kFullLayer_SaveLayerStrategy;
 }
 
+int SkCanvas::saveLayer(const SkRect* bounds, const SkPaint* paint) {
+    SaveLayerStrategy strategy = this->willSaveLayer(bounds, paint, kARGB_ClipLayer_SaveFlag);
+    return this->internalSaveLayer(bounds, paint, kARGB_ClipLayer_SaveFlag, false, strategy);
+}
+
 int SkCanvas::saveLayer(const SkRect* bounds, const SkPaint* paint,
                         SaveFlags flags) {
-    // Overriding classes may return false to signal that we don't need to create a layer.
     SaveLayerStrategy strategy = this->willSaveLayer(bounds, paint, flags);
     return this->internalSaveLayer(bounds, paint, flags, false, strategy);
 }
@@ -975,6 +984,10 @@ int SkCanvas::internalSaveLayer(const SkRect* bounds, const SkPaint* paint, Save
     return count;
 }
 
+int SkCanvas::saveLayerAlpha(const SkRect* bounds, U8CPU alpha) {
+    return this->saveLayerAlpha(bounds, alpha, kARGB_ClipLayer_SaveFlag);
+}
+
 int SkCanvas::saveLayerAlpha(const SkRect* bounds, U8CPU alpha,
                              SaveFlags flags) {
     if (0xFF == alpha) {