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 17 package android.view; 18 19 import 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 */ 30 public 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 */ start()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 */ end()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 */ invalidate()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 */ clear()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 */ isValid()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 */ getSize()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 */ setCaching(boolean caching)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 */ setClipChildren(boolean clipChildren)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 */ setStaticMatrix(Matrix matrix)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 */ setAnimationMatrix(Matrix matrix)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 */ setAlpha(float alpha)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 */ setHasOverlappingRendering(boolean hasOverlappingRendering)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 */ setTranslationX(float translationX)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 */ setTranslationY(float translationY)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 */ setRotation(float rotation)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 */ setRotationX(float rotationX)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 */ setRotationY(float rotationY)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 */ setScaleX(float scaleX)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 */ setScaleY(float scaleY)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 */ setTransformationInfo(float alpha, float translationX, float translationY, float rotation, float rotationX, float rotationY, float scaleX, float scaleY)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 */ setPivotX(float pivotX)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 */ setPivotY(float pivotY)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 */ setCameraDistance(float distance)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 */ setLeft(int left)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 */ setTop(int top)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 */ setRight(int right)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 */ setBottom(int bottom)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 */ setLeftTop(int left, int top)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 */ setLeftTopRightBottom(int left, int top, int right, int bottom)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 */ offsetLeftRight(int offset)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 */ offsetTopBottom(int offset)334 public abstract void offsetTopBottom(int offset); 335 } 336