[WIP] Add Context to SkDrawLooper.

include/core/SkDrawLooper.h

Index: include/core/SkDrawLooper.h
diff --git a/include/core/SkDrawLooper.h b/include/core/SkDrawLooper.h
index 4609c1dcf90ddb67a4708909ea209b5063fcfe18..7bef31871bbaefc19c20f939333e503ed5576af9 100644
--- a/include/core/SkDrawLooper.h
+++ b/include/core/SkDrawLooper.h
@@ -30,24 +30,55 @@ public:
     SK_DECLARE_INST_COUNT(SkDrawLooper)
 
     /**
-     *  Called right before something is being drawn. This will be followed by
-     *  calls to next() until next() returns false.
+     *  Holds state during a draw. Users call next() until it returns false. The
+     *  final call to next() will also delete the context.

[scroggo, 2014/02/11 15:51:29]

nit: The word delete is no longer necessarily accurate here.

[Dominik Grewe, 2014/02/11 16:04:31]

Good point. Actually the last call to next() doesn't do anything any more. We
ask the user to explicitly call cleanup(), because we don't always finish the
entire loop.
I'll update the comment accordingly.

+     *
+     *  Subclasses of SkDrawLooper should create a subclass of this object to
+     *  hold state specific to their subclass.
      */
-    virtual void init(SkCanvas*) = 0;
+    class SK_API DrawContext {
+    public:
+        DrawContext() {}
+        virtual ~DrawContext() {}
+
+        /**
+         *  Called in a loop (after init()). Each time true is returned, the
+         *  object is drawn (possibly with a modified canvas and/or paint). When
+         *  false is finally returned, drawing for the object stops. When the
+         *  context is no longer in use, call cleanup().
+         *
+         *  On each call, the paint will be in its original state, but the
+         *  canvas will be as it was following the previous call to next() or
+         *  init().
+         *
+         *  The implementation must ensure that, when next() finally returns
+         *  false, that the canvas has been restored to the state it was
+         *  initially, before init() was first called.
+         */
+        virtual bool next(SkCanvas* canvas, SkPaint* paint) = 0;
+
+        /**
+         *  Destroys the object and frees memory if the object was dynamically
+         *  allocated. To work correctly, pass in the same pointer that was
+         *  passed to SkDrawLooper::init() for creating this object.
+         *
+         *  Call this method instead of 'delete' (or similar) to ensure the
+         *  object is destroyed correctly.
+         */
+        void cleanup(void* storage);
+    };
 
     /**
-     *  Called in a loop (after init()). Each time true is returned, the object
-     *  is drawn (possibly with a modified canvas and/or paint). When false is
-     *  finally returned, drawing for the object stops.
+     *  Called right before something is being drawn. Returns a DrawContext
+     *  whose next() method should be called until it returns false.
      *
-     *  On each call, the paint will be in its original state, but the canvas
-     *  will be as it was following the previous call to next() or init().
-     *
-     *  The implementation must ensure that, when next() finally returns false,
-     *  that the canvas has been restored to the state it was initially, before
-     *  init() was first called.
+     *  Pass a pointer to pre-allocated memory to avoid dynamic memory
+     *  allocation. If the storage size is too small, the object will be
+     *  dynamically allocated.
      */
-    virtual bool next(SkCanvas*, SkPaint* paint) = 0;
+    virtual DrawContext* init(SkCanvas*, void* storage, size_t storageSize)
+        const = 0;
+
 
     /**
      * The fast bounds functions are used to enable the paint to be culled early