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
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 */
30class SK_API SkCanvasStateUtils {
31public:
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