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 */ 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
