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