src/third_party/skia/include/utils/SkCanvasStateUtils.h

   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 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 namespace 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