1 files changed, 122 insertions, 0 deletions
diff --git a/docs/SkAutoCanvasRestore_Reference.bmh b/docs/SkAutoCanvasRestore_Reference.bmh
new file mode 100644
index 0000000000..a01aa793c7
--- /dev/null
+++ b/docs/SkAutoCanvasRestore_Reference.bmh
@@ -0,0 +1,122 @@
+#Topic Automatic_Canvas_Restore
+
+#Class SkAutoCanvasRestore
+
+Stack helper class calls SkCanvas::restoreToCount() when SkAutoCanvasRestore
+goes out of scope. Use this to guarantee that the canvas is restored to a known
+state.
+
+#Topic Overview
+
+#Subtopic Subtopics
+#ToDo manually add subtopics ##
+#Table
+#Legend
+# name             # description                                   ##
+#Legend ##
+# Constructors     # functions that construct SkAutoCanvasRestore  ##
+# Member_Functions # static functions and member methods           ##
+#Table ##
+#Subtopic ##
+
+#Subtopic Constructors
+#Table
+#Legend
+# name                                               # description                     ##
+#Legend ##
+# SkAutoCanvasRestore(SkCanvas* canvas, bool doSave) # Preserves Canvas save count.    ##
+# ~SkAutoCanvasRestore()                             # Restores Canvas to saved state. ##
+#Table ##
+#Subtopic ##
+
+#Subtopic Member_Functions
+#Table
+#Legend
+# name                             # description                     ##
+#Legend ##
+# restore()                        # Restores Canvas to saved state. ##
+#Table ##
+#Subtopic ##
+
+#Topic Overview ##
+
+#Method SkAutoCanvasRestore(SkCanvas* canvas, bool doSave)
+
+Preserves Canvas save count. Optionally saves Canvas_Clip and Canvas_Matrix.
+
+#Param canvas  Canvas to guard ##
+#Param doSave  call SkCanvas::save() ##
+
+#Return utility to restore Canvas state on destructor ##
+
+#Example
+#Height 128
+    SkPaint p;
+    p.setAntiAlias(true);
+    p.setTextSize(64);
+    for (SkScalar sx : { -1, 1 } ) {
+        for (SkScalar sy : { -1, 1 } ) {
+            SkAutoCanvasRestore autoRestore(canvas, true);
+            SkMatrix m = SkMatrix::MakeAll(sx, 1, 96,    0, sy, 64,   0, 0, 1);
+            canvas->concat(m);
+            canvas->drawString("R", 0, 0, p);
+        }
+    }
+##
+
+#SeeAlso SkCanvas::save SkCanvas::restore
+
+##
+
+#Method ~SkAutoCanvasRestore()
+
+Restores Canvas to saved state. Destructor is called when container goes out of
+scope.
+
+#NoExample
+##
+
+#SeeAlso SkCanvas::save SkCanvas::restore
+
+##
+
+#Method void restore()
+
+Restores Canvas to saved state immediately. Subsequent calls and
+~SkAutoCanvasRestore have no effect.
+
+#Example
+for (bool callRestore : { false, true } ) {
+    for (bool saveCanvas : {false, true} ) {
+        SkAutoCanvasRestore autoRestore(canvas, saveCanvas);
+        if (!saveCanvas) {
+            canvas->save();
+        }
+        SkDebugf("saveCanvas: %s  before restore: %d\n",
+               saveCanvas ? "true" : "false", canvas->getSaveCount());
+        if (callRestore) autoRestore.restore();
+        SkDebugf("saveCanvas: %s  after restore: %d\n",
+               saveCanvas ? "true" : "false", canvas->getSaveCount());
+    }
+}
+SkDebugf("final count: %d\n", canvas->getSaveCount());
+#StdOut
+saveCanvas: false  before restore: 2
+saveCanvas: false  after restore: 2
+saveCanvas: true  before restore: 2
+saveCanvas: true  after restore: 2
+saveCanvas: false  before restore: 2
+saveCanvas: false  after restore: 1
+saveCanvas: true  before restore: 2
+saveCanvas: true  after restore: 1
+final count: 1
+##
+##
+
+#SeeAlso SkCanvas::save SkCanvas::restore
+
+##
+
+#Class SkAutoCanvasRestore ##
+
+#Topic Automatic_Canvas_Restore ##