1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef SkDrawLooper_DEFINED
18#define SkDrawLooper_DEFINED
19
20#include "SkFlattenable.h"
21
22class SkCanvas;
23class SkPaint;
24
25/** \class SkDrawLooper
26    Subclasses of SkDrawLooper can be attached to a SkPaint. Where they are,
27    and something is drawn to a canvas with that paint, the looper subclass will
28    be called, allowing it to modify the canvas and/or paint for that draw call.
29    More than that, via the next() method, the looper can modify the draw to be
30    invoked multiple times (hence the name loop-er), allow it to perform effects
31    like shadows or frame/fills, that require more than one pass.
32*/
33class SK_API SkDrawLooper : public SkFlattenable {
34public:
35    /**
36     *  Called right before something is being drawn. This will be followed by
37     *  calls to next() until next() returns false.
38     */
39    virtual void init(SkCanvas*) = 0;
40
41    /**
42     *  Called in a loop (after init()). Each time true is returned, the object
43     *  is drawn (possibly with a modified canvas and/or paint). When false is
44     *  finally returned, drawing for the object stops.
45     *
46     *  On each call, the paint will be in its original state, but the canvas
47     *  will be as it was following the previous call to next() or init().
48     *
49     *  The implementation must ensure that, when next() finally returns false,
50     *  that the canvas has been restored to the state it was initially, before
51     *  init() was first called.
52     */
53    virtual bool next(SkCanvas*, SkPaint* paint) = 0;
54
55    /**
56     * The fast bounds functions are used to enable the paint to be culled early
57     * in the drawing pipeline. If a subclass can support this feature it must
58     * return true for the canComputeFastBounds() function.  If that function
59     * returns false then computeFastBounds behavior is undefined otherwise it
60     * is expected to have the following behavior. Given the parent paint and
61     * the parent's bounding rect the subclass must fill in and return the
62     * storage rect, where the storage rect is with the union of the src rect
63     * and the looper's bounding rect.
64     */
65    virtual bool canComputeFastBounds(const SkPaint& paint);
66    virtual void computeFastBounds(const SkPaint& paint,
67                                   const SkRect& src, SkRect* dst);
68
69protected:
70    SkDrawLooper() {}
71    SkDrawLooper(SkFlattenableReadBuffer& buffer) : INHERITED(buffer) {}
72
73private:
74    typedef SkFlattenable INHERITED;
75};
76
77#endif
78