michael@0: /*
michael@0:  * Copyright 2013 Google Inc.
michael@0:  *
michael@0:  * Use of this source code is governed by a BSD-style license that can be
michael@0:  * found in the LICENSE file.
michael@0:  */
michael@0: 
michael@0: #ifndef SkCanvasStateUtils_DEFINED
michael@0: #define SkCanvasStateUtils_DEFINED
michael@0: 
michael@0: #include "SkCanvas.h"
michael@0: 
michael@0: class SkCanvasState;
michael@0: 
michael@0: /**
michael@0:  * A set of functions that are useful for copying an SkCanvas across a library
michael@0:  * boundary where the Skia libraries on either side of the boundary may not be
michael@0:  * version identical.  The expected usage is outline below...
michael@0:  *
michael@0:  *                          Lib Boundary
michael@0:  * CaptureCanvasState(...)      |||
michael@0:  *   SkCanvas --> SkCanvasState |||
michael@0:  *                              ||| CreateFromCanvasState(...)
michael@0:  *                              |||   SkCanvasState --> SkCanvas`
michael@0:  *                              ||| Draw into SkCanvas`
michael@0:  *                              ||| Unref SkCanvas`
michael@0:  * ReleaseCanvasState(...)      |||
michael@0:  *
michael@0:  */
michael@0: namespace SkCanvasStateUtils {
michael@0:     /**
michael@0:      * Captures the current state of the canvas into an opaque ptr that is safe
michael@0:      * to pass between different instances of Skia (which may or may not be the
michael@0:      * same version). The function will return NULL in the event that one of the
michael@0:      * following conditions are true.
michael@0:      *  1) the canvas device type is not supported (currently only raster is supported)
michael@0:      *  2) the canvas clip type is not supported (currently only non-AA clips are supported)
michael@0:      *
michael@0:      * It is recommended that the original canvas also not be used until all
michael@0:      * canvases that have been created using its captured state have been dereferenced.
michael@0:      *
michael@0:      * Finally, it is important to note that any draw filters attached to the
michael@0:      * canvas are NOT currently captured.
michael@0:      *
michael@0:      * @param canvas The canvas you wish to capture the current state of.
michael@0:      * @return NULL or an opaque ptr that can be passed to CreateFromCanvasState
michael@0:      *         to reconstruct the canvas. The caller is responsible for calling
michael@0:      *         ReleaseCanvasState to free the memory associated with this state.
michael@0:      */
michael@0:     SK_API SkCanvasState* CaptureCanvasState(SkCanvas* canvas);
michael@0: 
michael@0:     /**
michael@0:      * Create a new SkCanvas from the captured state of another SkCanvas. The
michael@0:      * function will return NULL in the event that one of the
michael@0:      * following conditions are true.
michael@0:      *  1) the captured state is in an unrecognized format
michael@0:      *  2) the captured canvas device type is not supported
michael@0:      *
michael@0:      * @param canvas The canvas you wish to capture the current state of.
michael@0:      * @return NULL or an SkCanvas* whose devices and matrix/clip state are
michael@0:      *         identical to the captured canvas. The caller is responsible for
michael@0:      *         calling unref on the SkCanvas.
michael@0:      */
michael@0:     SK_API SkCanvas* CreateFromCanvasState(const SkCanvasState* state);
michael@0: 
michael@0:     /**
michael@0:      * Free the memory associated with the captured canvas state.  The state
michael@0:      * should not be released until all SkCanvas objects created using that
michael@0:      * state have been dereferenced.
michael@0:      *
michael@0:      * @param state The captured state you wish to dispose of.
michael@0:      */
michael@0:     SK_API void ReleaseCanvasState(SkCanvasState* state);
michael@0: };
michael@0: 
michael@0: #endif