A display list records a series of graphics related operations and can replay * them later. Display lists are usually built by recording operations on a * {@link HardwareCanvas}. Replaying the operations from a display list avoids * executing application code on every frame, and is thus much more efficient.
* *Display lists are used internally for all views by default, and are not * typically used directly. One reason to consider using a display is a custom * {@link View} implementation that needs to issue a large number of drawing commands. * When the view invalidates, all the drawing commands must be reissued, even if * large portions of the drawing command stream stay the same frame to frame, which * can become a performance bottleneck. To solve this issue, a custom View might split * its content into several display lists. A display list is updated only when its * content, and only its content, needs to be updated.
* *A text editor might for instance store each paragraph into its own display list. * Thus when the user inserts or removes characters, only the display list of the * affected paragraph needs to be recorded again.
* *Display lists can only be replayed using a {@link HardwareCanvas}. They are not * supported in software. Always make sure that the {@link android.graphics.Canvas} * you are using to render a display list is hardware accelerated using * {@link android.graphics.Canvas#isHardwareAccelerated()}.
* *
* HardwareRenderer renderer = myView.getHardwareRenderer();
* if (renderer != null) {
* DisplayList displayList = renderer.createDisplayList();
* HardwareCanvas canvas = displayList.start(width, height);
* try {
* // Draw onto the canvas
* // For instance: canvas.drawBitmap(...);
* } finally {
* displayList.end();
* }
* }
*
*
*
* protected void onDraw(Canvas canvas) {
* if (canvas.isHardwareAccelerated()) {
* HardwareCanvas hardwareCanvas = (HardwareCanvas) canvas;
* hardwareCanvas.drawDisplayList(mDisplayList);
* }
* }
*
*
* This step is not mandatory but recommended if you want to release resources * held by a display list as soon as possible.
** // Mark this display list invalid, it cannot be used for drawing anymore, * // and release resources held by this display list * displayList.clear(); ** *
In addition, a display list offers several properties, such as
* {@link #setScaleX(float)} or {@link #setLeft(int)}, that can be used to affect all
* the drawing commands recorded within. For instance, these properties can be used
* to move around a large number of images without re-issuing all the individual
* drawBitmap() calls.
* private void createDisplayList() {
* HardwareRenderer renderer = getHardwareRenderer();
* if (renderer != null) {
* mDisplayList = renderer.createDisplayList();
* HardwareCanvas canvas = mDisplayList.start(width, height);
* try {
* for (Bitmap b : mBitmaps) {
* canvas.drawBitmap(b, 0.0f, 0.0f, null);
* canvas.translate(0.0f, b.getHeight());
* }
* } finally {
* displayList.end();
* }
* }
* }
*
* protected void onDraw(Canvas canvas) {
* if (canvas.isHardwareAccelerated()) {
* HardwareCanvas hardwareCanvas = (HardwareCanvas) canvas;
* hardwareCanvas.drawDisplayList(mDisplayList);
* }
* }
*
* private void moveContentBy(int x) {
* // This will move all the bitmaps recorded inside the display list
* // by x pixels to the right and redraw this view. All the commands
* // recorded in createDisplayList() won't be re-issued, only onDraw()
* // will be invoked and will execute very quickly
* mDisplayList.offsetLeftAndRight(x);
* invalidate();
* }
*
*
* Display lists must be created on and manipulated from the UI thread only.
* * @hide */ public abstract class DisplayList { private boolean mDirty; /** * Flag used when calling * {@link HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int)} * When this flag is set, draw operations lying outside of the bounds of the * display list will be culled early. It is recommeneded to always set this * flag. * * @hide */ public static final int FLAG_CLIP_CHILDREN = 0x1; // NOTE: The STATUS_* values *must* match the enum in DrawGlInfo.h /** * Indicates that the display list is done drawing. * * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int) * * @hide */ public static final int STATUS_DONE = 0x0; /** * Indicates that the display list needs another drawing pass. * * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int) * * @hide */ public static final int STATUS_DRAW = 0x1; /** * Indicates that the display list needs to re-execute its GL functors. * * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int) * @see HardwareCanvas#callDrawGLFunction(int) * * @hide */ public static final int STATUS_INVOKE = 0x2; /** * Indicates that the display list performed GL drawing operations. * * @see HardwareCanvas#drawDisplayList(DisplayList, android.graphics.Rect, int) * * @hide */ public static final int STATUS_DREW = 0x4; /** * Starts recording the display list. All operations performed on the * returned canvas are recorded and stored in this display list. * * Calling this method will mark the display list invalid until * {@link #end()} is called. Only valid display lists can be replayed. * * @param width The width of the display list's viewport * @param height The height of the display list's viewport * * @return A canvas to record drawing operations. * * @see #end() * @see #isValid() */ public abstract HardwareCanvas start(int width, int height); /** * Ends the recording for this display list. A display list cannot be * replayed if recording is not finished. Calling this method marks * the display list valid and {@link #isValid()} will return true. * * @see #start(int, int) * @see #isValid() */ public abstract void end(); /** * Clears resources held onto by this display list. After calling this method * {@link #isValid()} will return false. * * @see #isValid() * @see #reset() */ public abstract void clear(); /** * Reset native resources. This is called when cleaning up the state of display lists * during destruction of hardware resources, to ensure that we do not hold onto * obsolete resources after related resources are gone. * * @see #clear() * * @hide */ public abstract void reset(); /** * Sets the dirty flag. When a display list is dirty, {@link #clear()} should * be invoked whenever possible. * * @see #isDirty() * @see #clear() * * @hide */ public void markDirty() { mDirty = true; } /** * Removes the dirty flag. This method can be used to cancel a cleanup * previously scheduled by setting the dirty flag. * * @see #isDirty() * @see #clear() * * @hide */ protected void clearDirty() { mDirty = false; } /** * Indicates whether the display list is dirty. * * @see #markDirty() * @see #clear() * * @hide */ public boolean isDirty() { return mDirty; } /** * Returns whether the display list is currently usable. If this returns false, * the display list should be re-recorded prior to replaying it. * * @return boolean true if the display list is able to be replayed, false otherwise. */ public abstract boolean isValid(); /** * Return the amount of memory used by this display list. * * @return The size of this display list in bytes * * @hide */ public abstract int getSize(); /////////////////////////////////////////////////////////////////////////// // DisplayList Property Setters /////////////////////////////////////////////////////////////////////////// /** * Set the caching property on the display list, which indicates whether the display list * holds a layer. Layer display lists should avoid creating an alpha layer, since alpha is * handled in the drawLayer operation directly (and more efficiently). * * @param caching true if the display list represents a hardware layer, false otherwise. * * @hide */ public abstract void setCaching(boolean caching); /** * Set whether the display list should clip itself to its bounds. This property is controlled by * the view's parent. * * @param clipToBounds true if the display list should clip to its bounds */ public abstract void setClipToBounds(boolean clipToBounds); /** * Set the static matrix on the display list. The specified matrix is combined with other * transforms (such as {@link #setScaleX(float)}, {@link #setRotation(float)}, etc.) * * @param matrix A transform matrix to apply to this display list * * @see #getMatrix(android.graphics.Matrix) * @see #getMatrix() */ public abstract void setMatrix(Matrix matrix); /** * Returns the static matrix set on this display list. * * @return A new {@link Matrix} instance populated with this display list's static * matrix * * @see #getMatrix(android.graphics.Matrix) * @see #setMatrix(android.graphics.Matrix) */ public Matrix getMatrix() { return getMatrix(new Matrix()); } /** * Copies this display list's static matrix into the specified matrix. * * @param matrix The {@link Matrix} instance in which to copy this display * list's static matrix. Cannot be null * * @return Thematrix parameter, for convenience
*
* @see #getMatrix()
* @see #setMatrix(android.graphics.Matrix)
*/
public abstract Matrix getMatrix(Matrix matrix);
/**
* Set the Animation matrix on the display list. This matrix exists if an Animation is
* currently playing on a View, and is set on the display list during at draw() time. When
* the Animation finishes, the matrix should be cleared by sending null
* for the matrix parameter.
*
* @param matrix The matrix, null indicates that the matrix should be cleared.
*
* @hide
*/
public abstract void setAnimationMatrix(Matrix matrix);
/**
* Sets the translucency level for the display list.
*
* @param alpha The translucency of the display list, must be a value between 0.0f and 1.0f
*
* @see View#setAlpha(float)
* @see #getAlpha()
*/
public abstract void setAlpha(float alpha);
/**
* Returns the translucency level of this display list.
*
* @return A value between 0.0f and 1.0f
*
* @see #setAlpha(float)
*/
public abstract float getAlpha();
/**
* Sets whether the display list renders content which overlaps. Non-overlapping rendering
* can use a fast path for alpha that avoids rendering to an offscreen buffer. By default
* display lists consider they do not have overlapping content.
*
* @param hasOverlappingRendering False if the content is guaranteed to be non-overlapping,
* true otherwise.
*
* @see android.view.View#hasOverlappingRendering()
* @see #hasOverlappingRendering()
*/
public abstract void setHasOverlappingRendering(boolean hasOverlappingRendering);
/**
* Indicates whether the content of this display list overlaps.
*
* @return True if this display list renders content which overlaps, false otherwise.
*
* @see #setHasOverlappingRendering(boolean)
*/
public abstract boolean hasOverlappingRendering();
/**
* Sets the translation value for the display list on the X axis
*
* @param translationX The X axis translation value of the display list, in pixels
*
* @see View#setTranslationX(float)
* @see #getTranslationX()
*/
public abstract void setTranslationX(float translationX);
/**
* Returns the translation value for this display list on the X axis, in pixels.
*
* @see #setTranslationX(float)
*/
public abstract float getTranslationX();
/**
* Sets the translation value for the display list on the Y axis
*
* @param translationY The Y axis translation value of the display list, in pixels
*
* @see View#setTranslationY(float)
* @see #getTranslationY()
*/
public abstract void setTranslationY(float translationY);
/**
* Returns the translation value for this display list on the Y axis, in pixels.
*
* @see #setTranslationY(float)
*/
public abstract float getTranslationY();
/**
* Sets the rotation value for the display list around the Z axis
*
* @param rotation The rotation value of the display list, in degrees
*
* @see View#setRotation(float)
* @see #getRotation()
*/
public abstract void setRotation(float rotation);
/**
* Returns the rotation value for this display list around the Z axis, in degrees.
*
* @see #setRotation(float)
*/
public abstract float getRotation();
/**
* Sets the rotation value for the display list around the X axis
*
* @param rotationX The rotation value of the display list, in degrees
*
* @see View#setRotationX(float)
* @see #getRotationX()
*/
public abstract void setRotationX(float rotationX);
/**
* Returns the rotation value for this display list around the X axis, in degrees.
*
* @see #setRotationX(float)
*/
public abstract float getRotationX();
/**
* Sets the rotation value for the display list around the Y axis
*
* @param rotationY The rotation value of the display list, in degrees
*
* @see View#setRotationY(float)
* @see #getRotationY()
*/
public abstract void setRotationY(float rotationY);
/**
* Returns the rotation value for this display list around the Y axis, in degrees.
*
* @see #setRotationY(float)
*/
public abstract float getRotationY();
/**
* Sets the scale value for the display list on the X axis
*
* @param scaleX The scale value of the display list
*
* @see View#setScaleX(float)
* @see #getScaleX()
*/
public abstract void setScaleX(float scaleX);
/**
* Returns the scale value for this display list on the X axis.
*
* @see #setScaleX(float)
*/
public abstract float getScaleX();
/**
* Sets the scale value for the display list on the Y axis
*
* @param scaleY The scale value of the display list
*
* @see View#setScaleY(float)
* @see #getScaleY()
*/
public abstract void setScaleY(float scaleY);
/**
* Returns the scale value for this display list on the Y axis.
*
* @see #setScaleY(float)
*/
public abstract float getScaleY();
/**
* Sets all of the transform-related values of the display list
*
* @param alpha The alpha value of the display list
* @param translationX The translationX value of the display list
* @param translationY The translationY value of the display list
* @param rotation The rotation value of the display list
* @param rotationX The rotationX value of the display list
* @param rotationY The rotationY value of the display list
* @param scaleX The scaleX value of the display list
* @param scaleY The scaleY value of the display list
*
* @hide
*/
public abstract void setTransformationInfo(float alpha, float translationX, float translationY,
float rotation, float rotationX, float rotationY, float scaleX, float scaleY);
/**
* Sets the pivot value for the display list on the X axis
*
* @param pivotX The pivot value of the display list on the X axis, in pixels
*
* @see View#setPivotX(float)
* @see #getPivotX()
*/
public abstract void setPivotX(float pivotX);
/**
* Returns the pivot value for this display list on the X axis, in pixels.
*
* @see #setPivotX(float)
*/
public abstract float getPivotX();
/**
* Sets the pivot value for the display list on the Y axis
*
* @param pivotY The pivot value of the display list on the Y axis, in pixels
*
* @see View#setPivotY(float)
* @see #getPivotY()
*/
public abstract void setPivotY(float pivotY);
/**
* Returns the pivot value for this display list on the Y axis, in pixels.
*
* @see #setPivotY(float)
*/
public abstract float getPivotY();
/**
* Sets the camera distance for the display list. Refer to
* {@link View#setCameraDistance(float)} for more information on how to
* use this property.
*
* @param distance The distance in Z of the camera of the display list
*
* @see View#setCameraDistance(float)
* @see #getCameraDistance()
*/
public abstract void setCameraDistance(float distance);
/**
* Returns the distance in Z of the camera of the display list.
*
* @see #setCameraDistance(float)
*/
public abstract float getCameraDistance();
/**
* Sets the left position for the display list.
*
* @param left The left position, in pixels, of the display list
*
* @see View#setLeft(int)
* @see #getLeft()
*/
public abstract void setLeft(int left);
/**
* Returns the left position for the display list in pixels.
*
* @see #setLeft(int)
*/
public abstract float getLeft();
/**
* Sets the top position for the display list.
*
* @param top The top position, in pixels, of the display list
*
* @see View#setTop(int)
* @see #getTop()
*/
public abstract void setTop(int top);
/**
* Returns the top position for the display list in pixels.
*
* @see #setTop(int)
*/
public abstract float getTop();
/**
* Sets the right position for the display list.
*
* @param right The right position, in pixels, of the display list
*
* @see View#setRight(int)
* @see #getRight()
*/
public abstract void setRight(int right);
/**
* Returns the right position for the display list in pixels.
*
* @see #setRight(int)
*/
public abstract float getRight();
/**
* Sets the bottom position for the display list.
*
* @param bottom The bottom position, in pixels, of the display list
*
* @see View#setBottom(int)
* @see #getBottom()
*/
public abstract void setBottom(int bottom);
/**
* Returns the bottom position for the display list in pixels.
*
* @see #setBottom(int)
*/
public abstract float getBottom();
/**
* Sets the left and top positions for the display list
*
* @param left The left position of the display list, in pixels
* @param top The top position of the display list, in pixels
* @param right The right position of the display list, in pixels
* @param bottom The bottom position of the display list, in pixels
*
* @see View#setLeft(int)
* @see View#setTop(int)
* @see View#setRight(int)
* @see View#setBottom(int)
*/
public abstract void setLeftTopRightBottom(int left, int top, int right, int bottom);
/**
* Offsets the left and right positions for the display list
*
* @param offset The amount that the left and right positions of the display
* list are offset, in pixels
*
* @see View#offsetLeftAndRight(int)
*/
public abstract void offsetLeftAndRight(float offset);
/**
* Offsets the top and bottom values for the display list
*
* @param offset The amount that the top and bottom positions of the display
* list are offset, in pixels
*
* @see View#offsetTopAndBottom(int)
*/
public abstract void offsetTopAndBottom(float offset);
}