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