Create a semi-stable API for capturing the state of an SkCanvas and reconstructing that state across different versions of Skia.

R=joth@chromium.org, mtklein@google.com, reed@google.com, scroggo@google.com

Review URL: https://codereview.chromium.org/23545017

git-svn-id: http://skia.googlecode.com/svn/trunk@11010 2bbb7eff-a529-9590-31e7-b0007b416f81

gm/canvasstate.cpp

@@ -112,9 +112,6 @@ private:
 class CanvasLayerStateGM : public GM {
 public:
     CanvasLayerStateGM() {
-        fRedPaint.setColor(SK_ColorRED);
-        fRedPaint.setStyle(SkPaint::kFill_Style);
-
         fBluePaint.setColor(SK_ColorBLUE);
         fBluePaint.setStyle(SkPaint::kFill_Style);
 
@@ -167,7 +164,6 @@ private:
         SPACER = 10,
     };
 
-    SkPaint fRedPaint;
     SkPaint fBluePaint;
     SkRect fRect;
 

gyp/tests.gyp

@@ -34,6 +34,7 @@
         '../tests/BlitRowTest.cpp',
         '../tests/BlurTest.cpp',
         '../tests/CanvasTest.cpp',
+        '../tests/CanvasStateTest.cpp',
         '../tests/ChecksumTest.cpp',
         '../tests/ClampRangeTest.cpp',
         '../tests/ClipCacheTest.cpp',

gyp/utils.gyp

@@ -35,6 +35,7 @@
 
         '../include/utils/SkBoundaryPatch.h',
         '../include/utils/SkCamera.h',
+        '../include/utils/SkCanvasStateUtils.h',
         '../include/utils/SkCubicInterval.h',
         '../include/utils/SkCullPoints.h',
         '../include/utils/SkDebugUtils.h',
@@ -65,6 +66,7 @@
         '../src/utils/SkBitSet.h',
         '../src/utils/SkBoundaryPatch.cpp',
         '../src/utils/SkCamera.cpp',
+        '../src/utils/SkCanvasStateUtils.cpp',
         '../src/utils/SkCubicInterval.cpp',
         '../src/utils/SkCullPoints.cpp',
         '../src/utils/SkDeferredCanvas.cpp',

include/core/SkWriter32.h

@@ -114,6 +114,10 @@ public:
         *(SkRect*)this->reserve(sizeof(rect)) = rect;
     }
 
+    void writeIRect(const SkIRect& rect) {
+        *(SkIRect*)this->reserve(sizeof(rect)) = rect;
+    }
+
     void writeRRect(const SkRRect& rrect) {
         rrect.writeToMemory(this->reserve(SkRRect::kSizeInMemory));
     }

include/utils/SkCanvasStateUtils.h

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

src/utils/SkCanvasStateUtils.cpp

@@ -0,0 +1,339 @@
+/*
+ * Copyright 2013 Google Inc.
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#include "SkCanvasStateUtils.h"
+#include "SkCanvas.h"
+#include "SkDevice.h"
+#include "SkNWayCanvas.h"
+#include "SkWriter32.h"
+
+#define CANVAS_STATE_VERSION 1
+/*
+ * WARNING: The structs below are part of a stable ABI and as such we explicitly
+ * use unambigious primitives (e.g. int32_t instead of an enum).
+ *
+ * ANY CHANGES TO THE STRUCTS BELOW THAT IMPACT THE ABI SHOULD RESULT IN AN
+ * UPDATE OF THE CANVAS_STATE_VERSION. SUCH CHANGES SHOULD ONLY BE MADE IF
+ * ABSOLUTELY NECESSARY!
+ */
+enum RasterConfigs {
+  kUnknown_RasterConfig   = 0,
+  kRGB_565_RasterConfig   = 1,
+  kARGB_8888_RasterConfig = 2
+};
+typedef int32_t RasterConfig;
+
+enum CanvasBackends {
+    kUnknown_CanvasBackend = 0,
+    kRaster_CanvasBackend  = 1,
+    kGPU_CanvasBackend     = 2,
+    kPDF_CanvasBackend     = 3
+};
+typedef int32_t CanvasBackend;
+
+struct ClipRect {
+    int32_t left, top, right, bottom;
+};
+
+struct SkMCState {
+    float matrix[9];
+    // NOTE: this only works for non-antialiased clips
+    int32_t clipRectCount;
+    ClipRect* clipRects;
+};
+
+// NOTE: If you add more members, bump CanvasState::version.
+struct SkCanvasLayerState {
+    CanvasBackend type;
+    int32_t x, y;
+    int32_t width;
+    int32_t height;
+
+    SkMCState mcState;
+
+    union {
+        struct {
+            RasterConfig config; // pixel format: a value from RasterConfigs.
+            uint32_t rowBytes;   // Number of bytes from start of one line to next.
+            void* pixels;        // The pixels, all (height * rowBytes) of them.
+        } raster;
+        struct {
+            int32_t textureID;
+        } gpu;
+    };
+};
+
+class SkCanvasState {
+public:
+    SkCanvasState(SkCanvas* canvas) {
+        SkASSERT(canvas);
+        version = CANVAS_STATE_VERSION;
+        width = canvas->getDeviceSize().width();
+        height = canvas->getDeviceSize().height();
+        layerCount = 0;
+        layers = NULL;
+        originalCanvas = SkRef(canvas);
+
+        mcState.clipRectCount = 0;
+        mcState.clipRects = NULL;
+    }
+
+    ~SkCanvasState() {
+        // loop through the layers and free the data allocated to the clipRects
+        for (int i = 0; i < layerCount; ++i) {
+            sk_free(layers[i].mcState.clipRects);
+        }
+
+        sk_free(mcState.clipRects);
+        sk_free(layers);
+
+        // it is now safe to free the canvas since there should be no remaining
+        // references to the content that is referenced by this canvas (e.g. pixels)
+        originalCanvas->unref();
+    }
+
+    /**
+     * The version this struct was built with.  This field must always appear
+     * first in the struct so that when the versions don't match (and the
+     * remaining contents and size are potentially different) we can still
+     * compare the version numbers.
+     */
+    int32_t version;
+
+    int32_t width;
+    int32_t height;
+
+    SkMCState mcState;
+
+    int32_t layerCount;
+    SkCanvasLayerState* layers;
+
+private:
+    SkCanvas* originalCanvas;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+class ClipValidator : public SkCanvas::ClipVisitor {
+public:
+    ClipValidator() : fFailed(false) {}
+    bool failed() { return fFailed; }
+
+    // ClipVisitor
+    virtual void clipRect(const SkRect& rect, SkRegion::Op op, bool antialias) SK_OVERRIDE {
+        fFailed |= antialias;
+    }
+
+    virtual void clipPath(const SkPath&, SkRegion::Op, bool antialias) SK_OVERRIDE {
+        fFailed |= antialias;
+    }
+
+private:
+    bool fFailed;
+};
+
+static void setup_MC_state(SkMCState* state, const SkMatrix& matrix, const SkRegion& clip) {
+    // initialize the struct
+    state->clipRectCount = 0;
+
+    // capture the matrix
+    for (int i = 0; i < 9; i++) {
+        state->matrix[i] = matrix.get(i);
+    }
+
+    /*
+     * capture the clip
+     *
+     * storage is allocated on the stack for the first 4 rects. This value was
+     * chosen somewhat arbitrarily, but does allow us to represent simple clips
+     * and some more common complex clips (e.g. a clipRect with a sub-rect
+     * clipped out of its interior) without needing to malloc any additional memory.
+     */
+    const int clipBufferSize = 4 * sizeof(ClipRect);
+    char clipBuffer[clipBufferSize];
+    SkWriter32 clipWriter(sizeof(ClipRect), clipBuffer, clipBufferSize);
+
+    if (!clip.isEmpty()) {
+        // only returns the b/w clip so aa clips fail
+        SkRegion::Iterator clip_iterator(clip);
+        for (; !clip_iterator.done(); clip_iterator.next()) {
+            // this assumes the SkIRect is stored in l,t,r,b ordering which
+            // matches the ordering of our ClipRect struct
+            clipWriter.writeIRect(clip_iterator.rect());
+            state->clipRectCount++;
+        }
+    }
+
+    // allocate memory for the clip then and copy them to the struct
+    state->clipRects = (ClipRect*) sk_malloc_throw(clipWriter.size());
+    clipWriter.flatten(state->clipRects);
+}
+
+
+
+SkCanvasState* SkCanvasStateUtils::CaptureCanvasState(SkCanvas* canvas) {
+    SkASSERT(canvas);
+
+    // Check the clip can be decomposed into rectangles (i.e. no soft clips).
+    ClipValidator validator;
+    canvas->replayClips(&validator);
+    if (validator.failed()) {
+        SkDEBUGF(("CaptureCanvasState does not support canvases with antialiased clips.\n"));
+        return NULL;
+    }
+
+    SkAutoTDelete<SkCanvasState> canvasState(SkNEW_ARGS(SkCanvasState, (canvas)));
+
+    // decompose the total matrix and clip
+    setup_MC_state(&canvasState->mcState, canvas->getTotalMatrix(), canvas->getTotalClip());
+
+    /*
+     * decompose the layers
+     *
+     * storage is allocated on the stack for the first 3 layers. It is common in
+     * some view systems (e.g. Android) that a few non-clipped layers are present
+     * and we will not need to malloc any additional memory in those cases.
+     */
+    const int layerBufferSize = 3 * sizeof(SkCanvasLayerState);
+    char layerBuffer[layerBufferSize];
+    SkWriter32 layerWriter(sizeof(SkCanvasLayerState), layerBuffer, layerBufferSize);
+    int layerCount = 0;
+    for (SkCanvas::LayerIter layer(canvas, true/*skipEmptyClips*/); !layer.done(); layer.next()) {
+
+        // we currently only work for bitmap backed devices
+        const SkBitmap& bitmap = layer.device()->accessBitmap(true/*changePixels*/);
+        if (bitmap.empty() || bitmap.isNull() || !bitmap.lockPixelsAreWritable()) {
+            return NULL;
+        }
+
+        SkCanvasLayerState* layerState =
+                (SkCanvasLayerState*) layerWriter.reserve(sizeof(SkCanvasLayerState));
+        layerState->type = kRaster_CanvasBackend;
+        layerState->x = layer.x();
+        layerState->y = layer.y();
+        layerState->width = bitmap.width();
+        layerState->height = bitmap.height();
+
+        switch (bitmap.config()) {
+            case SkBitmap::kARGB_8888_Config:
+                layerState->raster.config = kARGB_8888_RasterConfig;
+                break;
+            case SkBitmap::kRGB_565_Config:
+                layerState->raster.config = kRGB_565_RasterConfig;
+                break;
+            default:
+                return NULL;
+        }
+        layerState->raster.rowBytes = bitmap.rowBytes();
+        layerState->raster.pixels = bitmap.getPixels();
+
+        setup_MC_state(&layerState->mcState, layer.matrix(), layer.clip());
+        layerCount++;
+    }
+
+    // allocate memory for the layers and then and copy them to the struct
+    SkASSERT(layerWriter.size() == layerCount * sizeof(SkCanvasLayerState));
+    canvasState->layerCount = layerCount;
+    canvasState->layers = (SkCanvasLayerState*) sk_malloc_throw(layerWriter.size());
+    layerWriter.flatten(canvasState->layers);
+
+    // for now, just ignore any client supplied DrawFilter.
+    if (canvas->getDrawFilter()) {
+        SkDEBUGF(("CaptureCanvasState will ignore the canvases draw filter.\n"));
+    }
+
+    return canvasState.detach();
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+static void setup_canvas_from_MC_state(const SkMCState& state, SkCanvas* canvas) {
+    // reconstruct the matrix
+    SkMatrix matrix;
+    for (int i = 0; i < 9; i++) {
+        matrix.set(i, state.matrix[i]);
+    }
+
+    // reconstruct the clip
+    SkRegion clip;
+    for (int i = 0; i < state.clipRectCount; ++i) {
+        clip.op(SkIRect::MakeLTRB(state.clipRects[i].left,
+                                  state.clipRects[i].top,
+                                  state.clipRects[i].right,
+                                  state.clipRects[i].bottom),
+                SkRegion::kUnion_Op);
+    }
+
+    canvas->setMatrix(matrix);
+    canvas->setClipRegion(clip);
+}
+
+static SkCanvas* create_canvas_from_canvas_layer(const SkCanvasLayerState& layerState) {
+    SkASSERT(kRaster_CanvasBackend == layerState.type);
+
+    SkBitmap bitmap;
+    SkBitmap::Config config =
+        layerState.raster.config == kARGB_8888_RasterConfig ? SkBitmap::kARGB_8888_Config :
+        layerState.raster.config == kRGB_565_RasterConfig ? SkBitmap::kRGB_565_Config :
+        SkBitmap::kNo_Config;
+
+    if (config == SkBitmap::kNo_Config) {
+        return NULL;
+    }
+
+    bitmap.setConfig(config, layerState.width, layerState.height,
+                     layerState.raster.rowBytes);
+    bitmap.setPixels(layerState.raster.pixels);
+
+    SkASSERT(!bitmap.empty());
+    SkASSERT(!bitmap.isNull());
+
+    // create a device & canvas
+    SkAutoTUnref<SkDevice> device(SkNEW_ARGS(SkDevice, (bitmap)));
+    SkAutoTUnref<SkCanvas> canvas(SkNEW_ARGS(SkCanvas, (device.get())));
+
+    // setup the matrix and clip
+    setup_canvas_from_MC_state(layerState.mcState, canvas.get());
+
+    return canvas.detach();
+}
+
+SkCanvas* SkCanvasStateUtils::CreateFromCanvasState(const SkCanvasState* state) {
+    SkASSERT(state);
+
+    // check that the versions match
+    if (CANVAS_STATE_VERSION != state->version) {
+        SkDebugf("CreateFromCanvasState version does not match the one use to create the input");
+        return NULL;
+    }
+
+    if (state->layerCount < 1) {
+        return NULL;
+    }
+
+    SkAutoTUnref<SkNWayCanvas> canvas(SkNEW_ARGS(SkNWayCanvas, (state->width, state->height)));
+
+    // setup the matrix and clip on the n-way canvas
+    setup_canvas_from_MC_state(state->mcState, canvas);
+
+    // Iterate over the layers and add them to the n-way canvas
+    for (int i = 0; i < state->layerCount; ++i) {
+        SkAutoTUnref<SkCanvas> canvasLayer(create_canvas_from_canvas_layer(state->layers[i]));
+        if (!canvasLayer.get()) {
+            return NULL;
+        }
+        canvas->addCanvas(canvasLayer.get());
+    }
+
+    return canvas.detach();
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+void SkCanvasStateUtils::ReleaseCanvasState(SkCanvasState* state) {
+    SkDELETE(state);
+}

tests/CanvasStateTest.cpp

@@ -0,0 +1,140 @@
+
+/*
+ * Copyright 2013 Google Inc.
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#include "Test.h"
+#include "SkCanvas.h"
+#include "SkCanvasStateUtils.h"
+#include "SkDevice.h"
+#include "SkDrawFilter.h"
+#include "SkPaint.h"
+#include "SkRect.h"
+#include "SkRRect.h"
+
+static void test_complex_layers(skiatest::Reporter* reporter) {
+
+    const int WIDTH = 400;
+    const int HEIGHT = 400;
+    const int SPACER = 10;
+
+    SkRect rect = SkRect::MakeXYWH(SPACER, SPACER, WIDTH-(2*SPACER), (HEIGHT-(2*SPACER)) / 7);
+
+    const SkBitmap::Config configs[] = { SkBitmap::kRGB_565_Config,
+                                         SkBitmap::kARGB_8888_Config
+    };
+    const int configCount = sizeof(configs) / sizeof(SkBitmap::Config);
+
+    const int layerAlpha[] = { 255, 255, 0 };
+    const SkCanvas::SaveFlags flags[] = { SkCanvas::kARGB_NoClipLayer_SaveFlag,
+                                          SkCanvas::kARGB_ClipLayer_SaveFlag,
+                                          SkCanvas::kARGB_NoClipLayer_SaveFlag
+    };
+    REPORTER_ASSERT(reporter, sizeof(layerAlpha) == sizeof(flags));
+    const int layerCombinations = sizeof(layerAlpha) / sizeof(int);
+
+    for (int i = 0; i < configCount; ++i) {
+        SkBitmap bitmaps[2];
+        for (int j = 0; j < 2; ++j) {
+            bitmaps[j].setConfig(configs[i], WIDTH, HEIGHT);
+            bitmaps[j].allocPixels();
+
+            SkCanvas canvas(bitmaps[j]);
+
+            canvas.drawColor(SK_ColorRED);
+
+            for (int k = 0; k < layerCombinations; ++k) {
+                // draw a rect within the layer's bounds and again outside the layer's bounds
+                canvas.saveLayerAlpha(&rect, layerAlpha[k], flags[k]);
+
+                SkCanvasState* state = NULL;
+                SkCanvas* tmpCanvas = NULL;
+                if (j) {
+                    state = SkCanvasStateUtils::CaptureCanvasState(&canvas);
+                    REPORTER_ASSERT(reporter, state);
+                    tmpCanvas = SkCanvasStateUtils::CreateFromCanvasState(state);
+                    REPORTER_ASSERT(reporter, tmpCanvas);
+                } else {
+                    tmpCanvas = SkRef(&canvas);
+                }
+
+                SkPaint bluePaint;
+                bluePaint.setColor(SK_ColorBLUE);
+                bluePaint.setStyle(SkPaint::kFill_Style);
+
+                tmpCanvas->drawRect(rect, bluePaint);
+                tmpCanvas->translate(0, rect.height() + SPACER);
+                tmpCanvas->drawRect(rect, bluePaint);
+
+                tmpCanvas->unref();
+                SkCanvasStateUtils::ReleaseCanvasState(state);
+
+                canvas.restore();
+
+                // translate the canvas for the next iteration
+                canvas.translate(0, 2*(rect.height() + SPACER));
+            }
+        }
+
+        // now we memcmp the two bitmaps
+        REPORTER_ASSERT(reporter, bitmaps[0].getSize() == bitmaps[1].getSize());
+        REPORTER_ASSERT(reporter, !memcmp(bitmaps[0].getPixels(),
+                                          bitmaps[1].getPixels(),
+                                          bitmaps[0].getSize()));
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+class TestDrawFilter : public SkDrawFilter {
+public:
+    virtual bool filter(SkPaint*, Type) SK_OVERRIDE { return true; }
+};
+
+static void test_draw_filters(skiatest::Reporter* reporter) {
+    TestDrawFilter drawFilter;
+    SkDevice device(SkBitmap::kARGB_8888_Config, 10, 10);
+    SkCanvas canvas(&device);
+
+    canvas.setDrawFilter(&drawFilter);
+
+    SkCanvasState* state = SkCanvasStateUtils::CaptureCanvasState(&canvas);
+    REPORTER_ASSERT(reporter, state);
+    SkCanvas* tmpCanvas = SkCanvasStateUtils::CreateFromCanvasState(state);
+    REPORTER_ASSERT(reporter, tmpCanvas);
+
+    REPORTER_ASSERT(reporter, NULL != canvas.getDrawFilter());
+    REPORTER_ASSERT(reporter, NULL == tmpCanvas->getDrawFilter());
+
+    tmpCanvas->unref();
+    SkCanvasStateUtils::ReleaseCanvasState(state);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+static void test_soft_clips(skiatest::Reporter* reporter) {
+    SkDevice device(SkBitmap::kARGB_8888_Config, 10, 10);
+    SkCanvas canvas(&device);
+
+    SkRRect roundRect;
+    roundRect.setOval(SkRect::MakeWH(5, 5));
+
+    canvas.clipRRect(roundRect, SkRegion::kIntersect_Op, true);
+
+    SkCanvasState* state = SkCanvasStateUtils::CaptureCanvasState(&canvas);
+    REPORTER_ASSERT(reporter, !state);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+static void test_canvas_state_utils(skiatest::Reporter* reporter) {
+    test_complex_layers(reporter);
+    test_draw_filters(reporter);
+    test_soft_clips(reporter);
+}
+
+#include "TestClassDef.h"
+DEFINE_TESTCLASS("CanvasState", TestCanvasStateClass, test_canvas_state_utils)