Home | History | Annotate | Download | only in utils
      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 
     13 class SkCanvasState;
     14 
     15 /**
     16  * A set of functions that are useful for copying an SkCanvas across a library
     17  * boundary where the Skia libraries on either side of the boundary may not be
     18  * version identical.  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 namespace SkCanvasStateUtils {
     31     /**
     32      * Captures the current state of the canvas into an opaque ptr that is safe
     33      * to pass between different instances of Skia (which may or may not be the
     34      * same version). 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 canvas The canvas you wish to capture the current state of.
     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.
     70      *
     71      * @param state The captured state you wish to dispose of.
     72      */
     73     SK_API void ReleaseCanvasState(SkCanvasState* state);
     74 };
     75 
     76 #endif
     77