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 "SkCanvas.h"
12
13class 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 */
30namespace SkCanvasStateUtils {
31    /**
32     * Captures the current state of the canvas into an opaque ptr that is safe
33     * to pass to a different instance of Skia (which may be the same version,
34     * or may be newer). The function will return NULL in the event that one of the
35     * following conditions are true.
36     *  1) the canvas device type is not supported (currently only raster is supported)
37     *  2) the canvas clip type is not supported (currently only non-AA clips are supported)
38     *
39     * It is recommended that the original canvas also not be used until all
40     * canvases that have been created using its captured state have been dereferenced.
41     *
42     * Finally, it is important to note that any draw filters attached to the
43     * canvas are NOT currently captured.
44     *
45     * @param canvas The canvas you wish to capture the current state of.
46     * @return NULL or an opaque ptr that can be passed to CreateFromCanvasState
47     *         to reconstruct the canvas. The caller is responsible for calling
48     *         ReleaseCanvasState to free the memory associated with this state.
49     */
50    SK_API SkCanvasState* CaptureCanvasState(SkCanvas* canvas);
51
52    /**
53     * Create a new SkCanvas from the captured state of another SkCanvas. The
54     * function will return NULL in the event that one of the
55     * following conditions are true.
56     *  1) the captured state is in an unrecognized format
57     *  2) the captured canvas device type is not supported
58     *
59     * @param state Opaque object created by CaptureCanvasState.
60     * @return NULL or an SkCanvas* whose devices and matrix/clip state are
61     *         identical to the captured canvas. The caller is responsible for
62     *         calling unref on the SkCanvas.
63     */
64    SK_API SkCanvas* CreateFromCanvasState(const SkCanvasState* state);
65
66    /**
67     * Free the memory associated with the captured canvas state.  The state
68     * should not be released until all SkCanvas objects created using that
69     * state have been dereferenced. Must be called from the same library
70     * instance that created the state via CaptureCanvasState.
71     *
72     * @param state The captured state you wish to dispose of.
73     */
74    SK_API void ReleaseCanvasState(SkCanvasState* state);
75};
76
77#endif
78