1 /*
2  * Copyright 2013 Google Inc.
3  *
4  * Use of this source code is governed by a BSD-style license that can be
5  * found in the LICENSE file.
6  */
7 
8 #ifndef SkCanvasStateUtils_DEFINED
9 #define SkCanvasStateUtils_DEFINED
10 
11 #include "include/core/SkCanvas.h"
12 
13 class SkCanvasState;
14 
15 /**
16  * A set of functions that are useful for copying the state of an SkCanvas
17  * across a library boundary where the Skia library on the other side of the
18  * boundary may be newer. The expected usage is outline below...
19  *
20  *                          Lib Boundary
21  * CaptureCanvasState(...)      |||
22  *   SkCanvas --> SkCanvasState |||
23  *                              ||| CreateFromCanvasState(...)
24  *                              |||   SkCanvasState --> SkCanvas`
25  *                              ||| Draw into SkCanvas`
26  *                              ||| Unref SkCanvas`
27  * ReleaseCanvasState(...)      |||
28  *
29  */
30 class SK_API SkCanvasStateUtils {
31 public:
32     /**
33      * Captures the current state of the canvas into an opaque ptr that is safe
34      * to pass to a different instance of Skia (which may be the same version,
35      * or may be newer). The function will return NULL in the event that one of the
36      * following conditions are true.
37      *  1) the canvas device type is not supported (currently only raster is supported)
38      *  2) the canvas clip type is not supported (currently only non-AA clips are supported)
39      *
40      * It is recommended that the original canvas also not be used until all
41      * canvases that have been created using its captured state have been dereferenced.
42      *
43      * Finally, it is important to note that any draw filters attached to the
44      * canvas are NOT currently captured.
45      *
46      * @param canvas The canvas you wish to capture the current state of.
47      * @return NULL or an opaque ptr that can be passed to CreateFromCanvasState
48      *         to reconstruct the canvas. The caller is responsible for calling
49      *         ReleaseCanvasState to free the memory associated with this state.
50      */
51     static SkCanvasState* CaptureCanvasState(SkCanvas* canvas);
52 
53     /**
54      * Create a new SkCanvas from the captured state of another SkCanvas. The
55      * function will return NULL in the event that one of the
56      * following conditions are true.
57      *  1) the captured state is in an unrecognized format
58      *  2) the captured canvas device type is not supported
59      *
60      * @param state Opaque object created by CaptureCanvasState.
61      * @return NULL or an SkCanvas* whose devices and matrix/clip state are
62      *         identical to the captured canvas. The caller is responsible for
63      *         calling unref on the SkCanvas.
64      */
65     static std::unique_ptr<SkCanvas> MakeFromCanvasState(const SkCanvasState* state);
66 
67     /**
68      * Free the memory associated with the captured canvas state.  The state
69      * should not be released until all SkCanvas objects created using that
70      * state have been dereferenced. Must be called from the same library
71      * instance that created the state via CaptureCanvasState.
72      *
73      * @param state The captured state you wish to dispose of.
74      */
75     static void ReleaseCanvasState(SkCanvasState* state);
76 };
77 
78 #endif
79