1/*
2 * Copyright (C) 2010 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
17package android.view;
18
19import android.graphics.Bitmap;
20import android.graphics.Canvas;
21import android.graphics.Paint;
22import android.graphics.Rect;
23
24/**
25 * Hardware accelerated canvas.
26 *
27 * @hide
28 */
29public abstract class HardwareCanvas extends Canvas {
30    private String mName;
31
32    @Override
33    public boolean isHardwareAccelerated() {
34        return true;
35    }
36
37    @Override
38    public void setBitmap(Bitmap bitmap) {
39        throw new UnsupportedOperationException();
40    }
41
42    /**
43     * Specifies the name of this canvas. Naming the canvas is entirely
44     * optional but can be useful for debugging purposes.
45     *
46     * @param name The name of the canvas, can be null
47     *
48     * @see #getName()
49     *
50     * @hide
51     */
52    public void setName(String name) {
53        mName = name;
54    }
55
56    /**
57     * Returns the name of this canvas.
58     *
59     * @return The name of the canvas or null
60     *
61     * @see #setName(String)
62     *
63     * @hide
64     */
65    public String getName() {
66        return mName;
67    }
68
69    /**
70     * Invoked before any drawing operation is performed in this canvas.
71     *
72     * @param dirty The dirty rectangle to update, can be null.
73     * @return {@link DisplayList#STATUS_DREW} if anything was drawn (such as a call to clear
74     *         the canvas).
75     *
76     * @hide
77     */
78    public abstract int onPreDraw(Rect dirty);
79
80    /**
81     * Invoked after all drawing operation have been performed.
82     *
83     * @hide
84     */
85    public abstract void onPostDraw();
86
87    /**
88     * Draws the specified display list onto this canvas. The display list can only
89     * be drawn if {@link android.view.DisplayList#isValid()} returns true.
90     *
91     * @param displayList The display list to replay.
92     */
93    public void drawDisplayList(DisplayList displayList) {
94        drawDisplayList(displayList, null, DisplayList.FLAG_CLIP_CHILDREN);
95    }
96
97    /**
98     * Draws the specified display list onto this canvas.
99     *
100     * @param displayList The display list to replay.
101     * @param dirty The dirty region to redraw in the next pass, matters only
102     *        if this method returns {@link DisplayList#STATUS_DRAW}, can be null.
103     * @param flags Optional flags about drawing, see {@link DisplayList} for
104     *              the possible flags.
105     *
106     * @return One of {@link DisplayList#STATUS_DONE}, {@link DisplayList#STATUS_DRAW}, or
107     *         {@link DisplayList#STATUS_INVOKE}, or'd with {@link DisplayList#STATUS_DREW}
108     *         if anything was drawn.
109     *
110     * @hide
111     */
112    public abstract int drawDisplayList(DisplayList displayList, Rect dirty, int flags);
113
114    /**
115     * Outputs the specified display list to the log. This method exists for use by
116     * tools to output display lists for selected nodes to the log.
117     *
118     * @param displayList The display list to be logged.
119     *
120     * @hide
121     */
122    abstract void outputDisplayList(DisplayList displayList);
123
124    /**
125     * Draws the specified layer onto this canvas.
126     *
127     * @param layer The layer to composite on this canvas
128     * @param x The left coordinate of the layer
129     * @param y The top coordinate of the layer
130     * @param paint The paint used to draw the layer
131     *
132     * @hide
133     */
134    abstract void drawHardwareLayer(HardwareLayer layer, float x, float y, Paint paint);
135
136    /**
137     * Calls the function specified with the drawGLFunction function pointer. This is
138     * functionality used by webkit for calling into their renderer from our display lists.
139     * This function may return true if an invalidation is needed after the call.
140     *
141     * @param drawGLFunction A native function pointer
142     *
143     * @return One of {@link DisplayList#STATUS_DONE}, {@link DisplayList#STATUS_DRAW} or
144     *         {@link DisplayList#STATUS_INVOKE}
145     *
146     * @hide
147     */
148    public int callDrawGLFunction(int drawGLFunction) {
149        // Noop - this is done in the display list recorder subclass
150        return DisplayList.STATUS_DONE;
151    }
152
153    /**
154     * Invoke all the functors who requested to be invoked during the previous frame.
155     *
156     * @param dirty The region to redraw when the functors return {@link DisplayList#STATUS_DRAW}
157     *
158     * @return One of {@link DisplayList#STATUS_DONE}, {@link DisplayList#STATUS_DRAW} or
159     *         {@link DisplayList#STATUS_INVOKE}
160     *
161     * @hide
162     */
163    public int invokeFunctors(Rect dirty) {
164        return DisplayList.STATUS_DONE;
165    }
166
167    /**
168     * Detaches the specified functor from the current functor execution queue.
169     *
170     * @param functor The native functor to remove from the execution queue.
171     *
172     * @see #invokeFunctors(android.graphics.Rect)
173     * @see #callDrawGLFunction(int)
174     * @see #detachFunctor(int)
175     *
176     * @hide
177     */
178    abstract void detachFunctor(int functor);
179
180    /**
181     * Attaches the specified functor to the current functor execution queue.
182     *
183     * @param functor The native functor to add to the execution queue.
184     *
185     * @see #invokeFunctors(android.graphics.Rect)
186     * @see #callDrawGLFunction(int)
187     * @see #detachFunctor(int)
188     *
189     * @hide
190     */
191    abstract void attachFunctor(int functor);
192
193    /**
194     * Indicates that the specified layer must be updated as soon as possible.
195     *
196     * @param layer The layer to update
197     *
198     * @see #clearLayerUpdates()
199     *
200     * @hide
201     */
202    abstract void pushLayerUpdate(HardwareLayer layer);
203
204    /**
205     * Cancels a queued layer update. If the specified layer was not
206     * queued for update, this method has no effect.
207     *
208     * @param layer The layer whose update to cancel
209     *
210     * @see #pushLayerUpdate(HardwareLayer)
211     * @see #clearLayerUpdates()
212     *
213     * @hide
214     */
215    abstract void cancelLayerUpdate(HardwareLayer layer);
216
217    /**
218     * Immediately executes all enqueued layer updates.
219     *
220     * @see #pushLayerUpdate(HardwareLayer)
221     *
222     * @hide
223     */
224    abstract void flushLayerUpdates();
225
226    /**
227     * Removes all enqueued layer updates.
228     *
229     * @see #pushLayerUpdate(HardwareLayer)
230     *
231     * @hide
232     */
233    abstract void clearLayerUpdates();
234}
235