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.Matrix;
20
21/**
22 * A display lists records a series of graphics related operation and can replay
23 * them later. Display lists are usually built by recording operations on a
24 * {@link android.graphics.Canvas}. Replaying the operations from a display list
25 * avoids executing views drawing code on every frame, and is thus much more
26 * efficient.
27 *
28 * @hide
29 */
30public abstract class DisplayList {
31    /**
32     * Flag used when calling
33     * {@link HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int)}
34     * When this flag is set, draw operations lying outside of the bounds of the
35     * display list will be culled early. It is recommeneded to always set this
36     * flag.
37     */
38    public static final int FLAG_CLIP_CHILDREN = 0x1;
39
40    // NOTE: The STATUS_* values *must* match the enum in DrawGlInfo.h
41
42    /**
43     * Indicates that the display list is done drawing.
44     *
45     * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int)
46     */
47    public static final int STATUS_DONE = 0x0;
48
49    /**
50     * Indicates that the display list needs another drawing pass.
51     *
52     * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int)
53     */
54    public static final int STATUS_DRAW = 0x1;
55
56    /**
57     * Indicates that the display list needs to re-execute its GL functors.
58     *
59     * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int)
60     * @see HardwareCanvas#callDrawGLFunction(int)
61     */
62    public static final int STATUS_INVOKE = 0x2;
63
64    /**
65     * Indicates that the display list performed GL drawing operations.
66     *
67     * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int)
68     */
69    public static final int STATUS_DREW = 0x4;
70
71    /**
72     * Starts recording the display list. All operations performed on the
73     * returned canvas are recorded and stored in this display list.
74     *
75     * @return A canvas to record drawing operations.
76     */
77    public abstract HardwareCanvas start();
78
79    /**
80     * Ends the recording for this display list. A display list cannot be
81     * replayed if recording is not finished.
82     */
83    public abstract void end();
84
85    /**
86     * Invalidates the display list, indicating that it should be repopulated
87     * with new drawing commands prior to being used again. Calling this method
88     * causes calls to {@link #isValid()} to return <code>false</code>.
89     */
90    public abstract void invalidate();
91
92    /**
93     * Clears additional resources held onto by this display list. You should
94     * only invoke this method after {@link #invalidate()}.
95     */
96    public abstract void clear();
97
98    /**
99     * Returns whether the display list is currently usable. If this returns false,
100     * the display list should be re-recorded prior to replaying it.
101     *
102     * @return boolean true if the display list is able to be replayed, false otherwise.
103     */
104    public abstract boolean isValid();
105
106    /**
107     * Return the amount of memory used by this display list.
108     *
109     * @return The size of this display list in bytes
110     */
111    public abstract int getSize();
112
113    ///////////////////////////////////////////////////////////////////////////
114    // DisplayList Property Setters
115    ///////////////////////////////////////////////////////////////////////////
116
117    /**
118     * Set the caching property on the DisplayList, which indicates whether the DisplayList
119     * holds a layer. Layer DisplayLists should avoid creating an alpha layer, since alpha is
120     * handled in the drawLayer operation directly (and more efficiently).
121     *
122     * @param caching true if the DisplayList represents a hardware layer, false otherwise.
123     */
124    public abstract void setCaching(boolean caching);
125
126    /**
127     * Set whether the DisplayList should clip itself to its bounds. This property is controlled by
128     * the view's parent.
129     *
130     * @param clipChildren true if the DisplayList should clip to its bounds
131     */
132    public abstract void setClipChildren(boolean clipChildren);
133
134    /**
135     * Set the static matrix on the DisplayList. This matrix exists if a custom ViewGroup
136     * overrides
137     * {@link ViewGroup#getChildStaticTransformation(View, android.view.animation.Transformation)}
138     * and also has {@link ViewGroup#setStaticTransformationsEnabled(boolean)} set to true.
139     * This matrix will be concatenated with any other matrices in the DisplayList to position
140     * the view appropriately.
141     *
142     * @param matrix The matrix
143     */
144    public abstract void setStaticMatrix(Matrix matrix);
145
146    /**
147     * Set the Animation matrix on the DisplayList. This matrix exists if an Animation is
148     * currently playing on a View, and is set on the DisplayList during at draw() time. When
149     * the Animation finishes, the matrix should be cleared by sending <code>null</code>
150     * for the matrix parameter.
151     *
152     * @param matrix The matrix, null indicates that the matrix should be cleared.
153     */
154    public abstract void setAnimationMatrix(Matrix matrix);
155
156    /**
157     * Sets the alpha value for the DisplayList
158     *
159     * @param alpha The translucency of the DisplayList
160     * @see View#setAlpha(float)
161     */
162    public abstract void setAlpha(float alpha);
163
164    /**
165     * Sets whether the DisplayList renders content which overlaps. Non-overlapping rendering
166     * can use a fast path for alpha that avoids rendering to an offscreen buffer.
167     *
168     * @param hasOverlappingRendering
169     * @see android.view.View#hasOverlappingRendering()
170     */
171    public abstract void setHasOverlappingRendering(boolean hasOverlappingRendering);
172
173    /**
174     * Sets the translationX value for the DisplayList
175     *
176     * @param translationX The translationX value of the DisplayList
177     * @see View#setTranslationX(float)
178     */
179    public abstract void setTranslationX(float translationX);
180
181    /**
182     * Sets the translationY value for the DisplayList
183     *
184     * @param translationY The translationY value of the DisplayList
185     * @see View#setTranslationY(float)
186     */
187    public abstract void setTranslationY(float translationY);
188
189    /**
190     * Sets the rotation value for the DisplayList
191     *
192     * @param rotation The rotation value of the DisplayList
193     * @see View#setRotation(float)
194     */
195    public abstract void setRotation(float rotation);
196
197    /**
198     * Sets the rotationX value for the DisplayList
199     *
200     * @param rotationX The rotationX value of the DisplayList
201     * @see View#setRotationX(float)
202     */
203    public abstract void setRotationX(float rotationX);
204
205    /**
206     * Sets the rotationY value for the DisplayList
207     *
208     * @param rotationY The rotationY value of the DisplayList
209     * @see View#setRotationY(float)
210     */
211    public abstract void setRotationY(float rotationY);
212
213    /**
214     * Sets the scaleX value for the DisplayList
215     *
216     * @param scaleX The scaleX value of the DisplayList
217     * @see View#setScaleX(float)
218     */
219    public abstract void setScaleX(float scaleX);
220
221    /**
222     * Sets the scaleY value for the DisplayList
223     *
224     * @param scaleY The scaleY value of the DisplayList
225     * @see View#setScaleY(float)
226     */
227    public abstract void setScaleY(float scaleY);
228
229    /**
230     * Sets all of the transform-related values of the View onto the DisplayList
231     *
232     * @param alpha The alpha value of the DisplayList
233     * @param translationX The translationX value of the DisplayList
234     * @param translationY The translationY value of the DisplayList
235     * @param rotation The rotation value of the DisplayList
236     * @param rotationX The rotationX value of the DisplayList
237     * @param rotationY The rotationY value of the DisplayList
238     * @param scaleX The scaleX value of the DisplayList
239     * @param scaleY The scaleY value of the DisplayList
240     */
241    public abstract void setTransformationInfo(float alpha, float translationX, float translationY,
242            float rotation, float rotationX, float rotationY, float scaleX, float scaleY);
243
244    /**
245     * Sets the pivotX value for the DisplayList
246     *
247     * @param pivotX The pivotX value of the DisplayList
248     * @see View#setPivotX(float)
249     */
250    public abstract void setPivotX(float pivotX);
251
252    /**
253     * Sets the pivotY value for the DisplayList
254     *
255     * @param pivotY The pivotY value of the DisplayList
256     * @see View#setPivotY(float)
257     */
258    public abstract void setPivotY(float pivotY);
259
260    /**
261     * Sets the camera distance for the DisplayList
262     *
263     * @param distance The distance in z of the camera of the DisplayList
264     * @see View#setCameraDistance(float)
265     */
266    public abstract void setCameraDistance(float distance);
267
268    /**
269     * Sets the left value for the DisplayList
270     *
271     * @param left The left value of the DisplayList
272     * @see View#setLeft(int)
273     */
274    public abstract void setLeft(int left);
275
276    /**
277     * Sets the top value for the DisplayList
278     *
279     * @param top The top value of the DisplayList
280     * @see View#setTop(int)
281     */
282    public abstract void setTop(int top);
283
284    /**
285     * Sets the right value for the DisplayList
286     *
287     * @param right The right value of the DisplayList
288     * @see View#setRight(int)
289     */
290    public abstract void setRight(int right);
291
292    /**
293     * Sets the bottom value for the DisplayList
294     *
295     * @param bottom The bottom value of the DisplayList
296     * @see View#setBottom(int)
297     */
298    public abstract void setBottom(int bottom);
299
300    /**
301     * Sets the left and top values for the DisplayList
302     *
303     * @param left The left value of the DisplayList
304     * @param top The top value of the DisplayList
305     * @see View#setLeft(int)
306     * @see View#setTop(int)
307     */
308    public abstract void setLeftTop(int left, int top);
309
310    /**
311     * Sets the left and top values for the DisplayList
312     *
313     * @param left The left value of the DisplayList
314     * @param top The top value of the DisplayList
315     * @see View#setLeft(int)
316     * @see View#setTop(int)
317     */
318    public abstract void setLeftTopRightBottom(int left, int top, int right, int bottom);
319
320    /**
321     * Offsets the left and right values for the DisplayList
322     *
323     * @param offset The amount that the left and right values of the DisplayList are offset
324     * @see View#offsetLeftAndRight(int)
325     */
326    public abstract void offsetLeftRight(int offset);
327
328    /**
329     * Offsets the top and bottom values for the DisplayList
330     *
331     * @param offset The amount that the top and bottom values of the DisplayList are offset
332     * @see View#offsetTopAndBottom(int)
333     */
334    public abstract void offsetTopBottom(int offset);
335
336    /**
337     * Reset native resources. This is called when cleaning up the state of DisplayLists
338     * during destruction of hardware resources, to ensure that we do not hold onto
339     * obsolete resources after related resources are gone.
340     */
341    public abstract void reset();
342}
343