Create a semi-stable API for capturing the state of an SkCanvas and reconstructing that state acros…

include/utils/SkCanvasUtils.h

Index: include/utils/SkCanvasUtils.h
diff --git a/include/utils/SkCanvasUtils.h b/include/utils/SkCanvasUtils.h
new file mode 100644
index 0000000000000000000000000000000000000000..9bd55cdb6f60fee3d7746e3928ee4e8b17c3d533
--- /dev/null
+++ b/include/utils/SkCanvasUtils.h
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2013 Google Inc.
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef SkCanvasUtils_DEFINED
+#define SkCanvasUtils_DEFINED
+
+#include "SkCanvas.h"
+
+struct SkCanvasState;
+
+class SK_API SkCanvasUtils {

[scroggo, 2013/08/28 17:22:01]

This seems to be a rather generic name, considering that all of the current
functions are more specifically about recording/reusing a canvas state. If we
ever have more canvas utils, Wouldn't we want them to be separate from these
(namespace-wise)?

Also, should this be a namespace instead of a class? It seems we rarely use
named namespaces in Skia; is this our preferred way of doing things?

[djsollen, 2013/08/29 15:09:19]

Done.

+public:
+    /**
+     * Captures the current state of the canvas into an opaque ptr that is safe
+     * to pass between different instances of Skia (which may or may not be the
+     * same version). The function will return NULL in the event that one of the
+     * following conditions are true.
+     *  1) the canvas device type is not supported (currently only raster is supported)
+     *  2) the canvas clip type is not supported (currently only non-AA clips are supported)
+     *
+     * It is required that the original SkCanvas remain valid until all canvases

[mtklein, 2013/08/28 18:20:46]

Can we have the SkCanvasState grab a ref on the SkCanvas to make this automatic?

[djsollen, 2013/08/29 15:09:19]

Done.

+     * that have been created using its captured state have been dereferenced. It
+     * is also recommended that the original canvas also to be used during this

[scroggo, 2013/08/28 17:22:01]

I'm not sure what this sentence means.

[joth, 2013/08/28 21:04:59]

recommended that the original canvas NOT be used... ?

[djsollen, 2013/08/29 15:09:19]

Done.

+     * time.
+     *
+     * Finally, it is important to note that any draw filters attached to the
+     * canvas are NOT currently captured.

[mtklein, 2013/08/28 18:20:46]

A unit test for this will make sure we don't get this doc out of date with
reality.

[djsollen, 2013/08/29 15:09:19]

Done.

+     *
+     * @param canvas The canvas you wish to capture the current state of.
+     * @return NULL or an opaque ptr that can be passed to CreateFromCanvasState
+     *         to reconstruct the canvas. The caller is responsible for calling
+     *         ReleaseCanvasState to free the memory associated with this state.
+     */
+    static SkCanvasState* CaptureCanvasState(SkCanvas* canvas);

[mtklein, 2013/08/28 18:20:46]

Given that this is opaque, maybe we can use typedef to hide that it's a pointer
too?    Is there value in that?  Or maybe negative value?  Am I going too C
here?

+
+    /**
+     * Create a new SkCanvas from the captured state of another SkCanvas. The
+     * function will return NULL in the event that one of the
+     * following conditions are true.
+     *  1) the captured state is in an unrecognized format
+     *  2) the captured canvas device type is not supported
+     *
+     * @param canvas The canvas you wish to capture the current state of.
+     * @return NULL or an SkCanvas* whose devices and matrix/clip state are
+     *         identical to the captured canvas. The caller is responsible for
+     *         calling unref on the SkCanvas.
+     */
+    static SkCanvas* CreateFromCanvasState(SkCanvasState* state);

[mtklein, 2013/08/28 18:20:46]

Can this be a const* or const&?  (Or if * is typedef'd away, just const?)  If we
always pass a const SkCanvasState over the line, we can't possibly get confused
and release it there.

+
+    /**
+     * Free the memory associated with the captured canvas state.  This function
+     * can be called as soon as the caller is finished using the state (e.g. calling
+     * CreateFromCanvasState) and does not need to be retained for the lifecycle
+     * of any SkCanvas objects that it was used to create.

[mtklein, 2013/08/28 18:20:46]

This is what needs update after what we all just talked about, right?  Simpler
to maintain stack order?

[djsollen, 2013/08/29 15:09:19]

Done.

+     *
+     * @param state The captured state you wish to dispose of.
+     */
+    static void ReleaseCanvasState(SkCanvasState* state);

[scroggo, 2013/08/28 17:22:01]

I think it would be useful to be explicit in the comments about which side of
the boundary each call is made on and when.

[joth, 2013/08/28 21:04:59]

Yes.

I'd group CaptureCanvasState &  ReleaseCanvasState together, and sketch a quick
example flow at top of the file:-

// canvas provider code, compiled against skia version N.
SkCanvasState* state = CaptureCanvasState(my_canvas);
if (state) {
  consumer_render(state)
  ReleaseCanvasState(state)
}

// canvas consumer code, compiled against skia version >= N

void consumer_render(SkCanvasState* state) {
  SkCanvas* canvas = CreateFromCanvasState(state);
  if (canvas) {
    canvas->draw...()
    delete canvas;  // or unref or?
  }
}

[djsollen, 2013/08/29 15:09:19]

Done.

+};
+
+#endif