DisplayList.java revision 3dd4b51fc37c1f05b1b583f5706e3a12216b9822 
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     * Starts recording the display list. All operations performed on the
66     * returned canvas are recorded and stored in this display list.
67     *
68     * @return A canvas to record drawing operations.
69     */
70    public abstract HardwareCanvas start();
71
72    /**
73     * Ends the recording for this display list. A display list cannot be
74     * replayed if recording is not finished.
75     */
76    public abstract void end();
77
78    /**
79     * Invalidates the display list, indicating that it should be repopulated
80     * with new drawing commands prior to being used again. Calling this method
81     * causes calls to {@link #isValid()} to return <code>false</code>.
82     */
83    public abstract void invalidate();
84
85    /**
86     * Returns whether the display list is currently usable. If this returns false,
87     * the display list should be re-recorded prior to replaying it.
88     *
89     * @return boolean true if the display list is able to be replayed, false otherwise.
90     */
91    public abstract boolean isValid();
92
93    /**
94     * Return the amount of memory used by this display list.
95     *
96     * @return The size of this display list in bytes
97     */
98    public abstract int getSize();
99
100    ///////////////////////////////////////////////////////////////////////////
101    // DisplayList Property Setters
102    ///////////////////////////////////////////////////////////////////////////
103
104    /**
105     * Set the caching property on the DisplayList, which indicates whether the DisplayList
106     * holds a layer. Layer DisplayLists should avoid creating an alpha layer, since alpha is
107     * handled in the drawLayer operation directly (and more efficiently).
108     *
109     * @param caching true if the DisplayList represents a hardware layer, false otherwise.
110     */
111    public abstract void setCaching(boolean caching);
112
113    /**
114     * Set whether the DisplayList should clip itself to its bounds. This property is controlled by
115     * the view's parent.
116     *
117     * @param clipChildren true if the DisplayList should clip to its bounds
118     */
119    public abstract void setClipChildren(boolean clipChildren);
120
121    /**
122     * Set the static matrix on the DisplayList. This matrix exists if a custom ViewGroup
123     * overrides
124     * {@link ViewGroup#getChildStaticTransformation(View, android.view.animation.Transformation)}
125     * and also has {@link ViewGroup#setStaticTransformationsEnabled(boolean)} set to true.
126     * This matrix will be concatenated with any other matrices in the DisplayList to position
127     * the view appropriately.
128     *
129     * @param matrix The matrix
130     */
131    public abstract void setStaticMatrix(Matrix matrix);
132
133    /**
134     * Set the Animation matrix on the DisplayList. This matrix exists if an Animation is
135     * currently playing on a View, and is set on the DisplayList during at draw() time. When
136     * the Animation finishes, the matrix should be cleared by sending <code>null</code>
137     * for the matrix parameter.
138     *
139     * @param matrix The matrix, null indicates that the matrix should be cleared.
140     */
141    public abstract void setAnimationMatrix(Matrix matrix);
142
143    /**
144     * Sets the alpha value for the DisplayList
145     *
146     * @param alpha The translucency of the DisplayList
147     * @see View#setAlpha(float)
148     */
149    public abstract void setAlpha(float alpha);
150
151    /**
152     * Sets whether the DisplayList renders content which overlaps. Non-overlapping rendering
153     * can use a fast path for alpha that avoids rendering to an offscreen buffer.
154     *
155     * @param hasOverlappingRendering
156     * @see android.view.View#hasOverlappingRendering()
157     */
158    public abstract void setHasOverlappingRendering(boolean hasOverlappingRendering);
159
160    /**
161     * Sets the translationX value for the DisplayList
162     *
163     * @param translationX The translationX value of the DisplayList
164     * @see View#setTranslationX(float)
165     */
166    public abstract void setTranslationX(float translationX);
167
168    /**
169     * Sets the translationY value for the DisplayList
170     *
171     * @param translationY The translationY value of the DisplayList
172     * @see View#setTranslationY(float)
173     */
174    public abstract void setTranslationY(float translationY);
175
176    /**
177     * Sets the rotation value for the DisplayList
178     *
179     * @param rotation The rotation value of the DisplayList
180     * @see View#setRotation(float)
181     */
182    public abstract void setRotation(float rotation);
183
184    /**
185     * Sets the rotationX value for the DisplayList
186     *
187     * @param rotationX The rotationX value of the DisplayList
188     * @see View#setRotationX(float)
189     */
190    public abstract void setRotationX(float rotationX);
191
192    /**
193     * Sets the rotationY value for the DisplayList
194     *
195     * @param rotationY The rotationY value of the DisplayList
196     * @see View#setRotationY(float)
197     */
198    public abstract void setRotationY(float rotationY);
199
200    /**
201     * Sets the scaleX value for the DisplayList
202     *
203     * @param scaleX The scaleX value of the DisplayList
204     * @see View#setScaleX(float)
205     */
206    public abstract void setScaleX(float scaleX);
207
208    /**
209     * Sets the scaleY value for the DisplayList
210     *
211     * @param scaleY The scaleY value of the DisplayList
212     * @see View#setScaleY(float)
213     */
214    public abstract void setScaleY(float scaleY);
215
216    /**
217     * Sets all of the transform-related values of the View onto the DisplayList
218     *
219     * @param alpha The alpha value of the DisplayList
220     * @param translationX The translationX value of the DisplayList
221     * @param translationY The translationY value of the DisplayList
222     * @param rotation The rotation value of the DisplayList
223     * @param rotationX The rotationX value of the DisplayList
224     * @param rotationY The rotationY value of the DisplayList
225     * @param scaleX The scaleX value of the DisplayList
226     * @param scaleY The scaleY value of the DisplayList
227     */
228    public abstract void setTransformationInfo(float alpha, float translationX, float translationY,
229            float rotation, float rotationX, float rotationY, float scaleX, float scaleY);
230
231    /**
232     * Sets the pivotX value for the DisplayList
233     *
234     * @param pivotX The pivotX value of the DisplayList
235     * @see View#setPivotX(float)
236     */
237    public abstract void setPivotX(float pivotX);
238
239    /**
240     * Sets the pivotY value for the DisplayList
241     *
242     * @param pivotY The pivotY value of the DisplayList
243     * @see View#setPivotY(float)
244     */
245    public abstract void setPivotY(float pivotY);
246
247    /**
248     * Sets the camera distance for the DisplayList
249     *
250     * @param distance The distance in z of the camera of the DisplayList
251     * @see View#setCameraDistance(float)
252     */
253    public abstract void setCameraDistance(float distance);
254
255    /**
256     * Sets the left value for the DisplayList
257     *
258     * @param left The left value of the DisplayList
259     * @see View#setLeft(int)
260     */
261    public abstract void setLeft(int left);
262
263    /**
264     * Sets the top value for the DisplayList
265     *
266     * @param top The top value of the DisplayList
267     * @see View#setTop(int)
268     */
269    public abstract void setTop(int top);
270
271    /**
272     * Sets the right value for the DisplayList
273     *
274     * @param right The right value of the DisplayList
275     * @see View#setRight(int)
276     */
277    public abstract void setRight(int right);
278
279    /**
280     * Sets the bottom value for the DisplayList
281     *
282     * @param bottom The bottom value of the DisplayList
283     * @see View#setBottom(int)
284     */
285    public abstract void setBottom(int bottom);
286
287    /**
288     * Sets the left and top values for the DisplayList
289     *
290     * @param left The left value of the DisplayList
291     * @param top The top value of the DisplayList
292     * @see View#setLeft(int)
293     * @see View#setTop(int)
294     */
295    public abstract void setLeftTop(int left, int top);
296
297    /**
298     * Sets the left and top values for the DisplayList
299     *
300     * @param left The left value of the DisplayList
301     * @param top The top value of the DisplayList
302     * @see View#setLeft(int)
303     * @see View#setTop(int)
304     */
305    public abstract void setLeftTopRightBottom(int left, int top, int right, int bottom);
306
307    /**
308     * Offsets the left and right values for the DisplayList
309     *
310     * @param offset The amount that the left and right values of the DisplayList are offset
311     * @see View#offsetLeftAndRight(int)
312     */
313    public abstract void offsetLeftRight(int offset);
314
315    /**
316     * Offsets the top and bottom values for the DisplayList
317     *
318     * @param offset The amount that the top and bottom values of the DisplayList are offset
319     * @see View#offsetTopAndBottom(int)
320     */
321    public abstract void offsetTopBottom(int offset);
322}
323