public class RenderNode extends Object
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
DisplayListCanvas
. 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
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 DisplayListCanvas
. They are not
supported in software. Always make sure that the Canvas
you are using to render a display list is hardware accelerated using
Canvas.isHardwareAccelerated()
.
HardwareRenderer renderer = myView.getHardwareRenderer(); if (renderer != null) { DisplayList displayList = renderer.createDisplayList(); DisplayListCanvas 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()) { DisplayListCanvas displayListCanvas = (DisplayListCanvas) canvas; displayListCanvas.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
setScaleX(float)
or 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() { mDisplayList = DisplayList.create("MyDisplayList"); DisplayListCanvas 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()) { DisplayListCanvas displayListCanvas = (DisplayListCanvas) canvas; displayListCanvas.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.
Modifier and Type | Method and Description |
---|---|
void |
addAnimator(RenderNodeAnimator animator) |
static RenderNode |
adopt(long nativePtr)
Adopts an existing native render node.
|
static RenderNode |
create(String name,
View owningView)
Creates a new RenderNode that can be used to record batches of
drawing operations, and store / apply render properties when drawn.
|
void |
discardDisplayList()
Reset native resources.
|
void |
end(DisplayListCanvas canvas)
Ends the recording for this display list.
|
void |
endAllAnimators() |
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
float |
getAlpha()
Returns the translucency level of this display list.
|
float |
getCameraDistance()
Returns the distance in Z of the camera of the display list.
|
boolean |
getClipToOutline() |
int |
getDebugSize()
Gets the size of the DisplayList for debug purposes.
|
float |
getElevation() |
void |
getInverseMatrix(Matrix outMatrix) |
void |
getMatrix(Matrix outMatrix) |
float |
getPivotX()
Returns the pivot value for this display list on the X axis, in pixels.
|
float |
getPivotY()
Returns the pivot value for this display list on the Y axis, in pixels.
|
float |
getRotation()
Returns the rotation value for this display list around the Z axis, in degrees.
|
float |
getRotationX()
Returns the rotation value for this display list around the X axis, in degrees.
|
float |
getRotationY()
Returns the rotation value for this display list around the Y axis, in degrees.
|
float |
getScaleX()
Returns the scale value for this display list on the X axis.
|
float |
getScaleY()
Returns the scale value for this display list on the Y axis.
|
float |
getTranslationX()
Returns the translation value for this display list on the X axis, in pixels.
|
float |
getTranslationY()
Returns the translation value for this display list on the Y axis, in pixels.
|
float |
getTranslationZ()
Returns the translation value for this display list on the Z axis.
|
boolean |
hasIdentityMatrix() |
boolean |
hasOverlappingRendering()
Indicates whether the content of this display list overlaps.
|
boolean |
hasShadow() |
boolean |
isAttached() |
boolean |
isPivotExplicitlySet() |
boolean |
isValid()
Returns whether the RenderNode's display list content is currently usable.
|
boolean |
offsetLeftAndRight(int offset)
Offsets the left and right positions for the display list
|
boolean |
offsetTopAndBottom(int offset)
Offsets the top and bottom values for the display list
|
void |
output()
Outputs the display list to the log.
|
void |
registerVectorDrawableAnimator(AnimatedVectorDrawable.VectorDrawableAnimatorRT animatorSet) |
boolean |
setAlpha(float alpha)
Sets the translucency level for the display list.
|
boolean |
setAnimationMatrix(Matrix matrix)
Set the Animation matrix on the display list.
|
boolean |
setBottom(int bottom)
Sets the bottom position for the display list.
|
boolean |
setCameraDistance(float distance)
Sets the camera distance for the display list.
|
boolean |
setClipBounds(Rect rect) |
boolean |
setClipToBounds(boolean clipToBounds)
Set whether the Render node should clip itself to its bounds.
|
boolean |
setClipToOutline(boolean clipToOutline)
Enables or disables clipping to the outline.
|
boolean |
setElevation(float lift) |
boolean |
setHasOverlappingRendering(boolean hasOverlappingRendering)
Sets whether the display list renders content which overlaps.
|
boolean |
setLayerPaint(Paint paint) |
boolean |
setLayerType(int layerType) |
boolean |
setLeft(int left)
Sets the left position for the display list.
|
boolean |
setLeftTopRightBottom(int left,
int top,
int right,
int bottom)
Sets the left and top positions for the display list
|
boolean |
setOutline(Outline outline)
Sets the outline, defining the shape that casts a shadow, and the path to
be clipped if setClipToOutline is set.
|
boolean |
setPivotX(float pivotX)
Sets the pivot value for the display list on the X axis
|
boolean |
setPivotY(float pivotY)
Sets the pivot value for the display list on the Y axis
|
boolean |
setProjectBackwards(boolean shouldProject)
Sets whether the display list should be drawn immediately after the
closest ancestor display list containing a projection receiver.
|
boolean |
setProjectionReceiver(boolean shouldRecieve)
Sets whether the display list is a projection receiver - that its parent
DisplayList should draw any descendent DisplayLists with
ProjectBackwards=true directly on top of it.
|
boolean |
setRevealClip(boolean shouldClip,
float x,
float y,
float radius)
Controls the RenderNode's circular reveal clip.
|
boolean |
setRight(int right)
Sets the right position for the display list.
|
boolean |
setRotation(float rotation)
Sets the rotation value for the display list around the Z axis.
|
boolean |
setRotationX(float rotationX)
Sets the rotation value for the display list around the X axis.
|
boolean |
setRotationY(float rotationY)
Sets the rotation value for the display list around the Y axis.
|
boolean |
setScaleX(float scaleX)
Sets the scale value for the display list on the X axis.
|
boolean |
setScaleY(float scaleY)
Sets the scale value for the display list on the Y axis.
|
boolean |
setStaticMatrix(Matrix matrix)
Set the static matrix on the display list.
|
boolean |
setTop(int top)
Sets the top position for the display list.
|
boolean |
setTranslationX(float translationX)
Sets the translation value for the display list on the X axis.
|
boolean |
setTranslationY(float translationY)
Sets the translation value for the display list on the Y axis.
|
boolean |
setTranslationZ(float translationZ)
Sets the translation value for the display list on the Z axis.
|
DisplayListCanvas |
start(int width,
int height)
Starts recording a display list for the render node.
|
public static RenderNode create(String name, View owningView)
name
- The name of the RenderNode, used for debugging purpose. May be null.public static RenderNode adopt(long nativePtr)
public DisplayListCanvas start(int width, int height)
end(DisplayListCanvas)
is called.
Only valid render nodes can be replayed.width
- The width of the recording viewportheight
- The height of the recording viewportend(DisplayListCanvas)
,
isValid()
public void end(DisplayListCanvas canvas)
isValid()
will return true.start(int, int)
,
isValid()
public void discardDisplayList()
public boolean isValid()
public boolean hasIdentityMatrix()
public void getMatrix(Matrix outMatrix)
public void getInverseMatrix(Matrix outMatrix)
public boolean setLayerType(int layerType)
public boolean setLayerPaint(Paint paint)
public boolean setClipBounds(Rect rect)
public boolean setClipToBounds(boolean clipToBounds)
clipToBounds
- true if the display list should clip to its boundspublic boolean setProjectBackwards(boolean shouldProject)
shouldProject
- true if the display list should be projected onto a
containing volume.public boolean setProjectionReceiver(boolean shouldRecieve)
public boolean setOutline(Outline outline)
public boolean hasShadow()
public boolean setClipToOutline(boolean clipToOutline)
clipToOutline
- true if clipping to the outline.public boolean getClipToOutline()
public boolean setRevealClip(boolean shouldClip, float x, float y, float radius)
public boolean setStaticMatrix(Matrix matrix)
setScaleX(float)
, setRotation(float)
, etc.)matrix
- A transform matrix to apply to this display listpublic boolean setAnimationMatrix(Matrix matrix)
null
for the matrix parameter.matrix
- The matrix, null indicates that the matrix should be cleared.public boolean setAlpha(float alpha)
alpha
- The translucency of the display list, must be a value between 0.0f and 1.0fView.setAlpha(float)
,
getAlpha()
public float getAlpha()
setAlpha(float)
public boolean setHasOverlappingRendering(boolean hasOverlappingRendering)
hasOverlappingRendering
- False if the content is guaranteed to be non-overlapping,
true otherwise.View.hasOverlappingRendering()
,
hasOverlappingRendering()
public boolean hasOverlappingRendering()
setHasOverlappingRendering(boolean)
public boolean setElevation(float lift)
public float getElevation()
public boolean setTranslationX(float translationX)
translationX
- The X axis translation value of the display list, in pixelsView.setTranslationX(float)
,
getTranslationX()
public float getTranslationX()
setTranslationX(float)
public boolean setTranslationY(float translationY)
translationY
- The Y axis translation value of the display list, in pixelsView.setTranslationY(float)
,
getTranslationY()
public float getTranslationY()
setTranslationY(float)
public boolean setTranslationZ(float translationZ)
View.setTranslationZ(float)
,
getTranslationZ()
public float getTranslationZ()
setTranslationZ(float)
public boolean setRotation(float rotation)
rotation
- The rotation value of the display list, in degreesView.setRotation(float)
,
getRotation()
public float getRotation()
setRotation(float)
public boolean setRotationX(float rotationX)
rotationX
- The rotation value of the display list, in degreesView.setRotationX(float)
,
getRotationX()
public float getRotationX()
setRotationX(float)
public boolean setRotationY(float rotationY)
rotationY
- The rotation value of the display list, in degreesView.setRotationY(float)
,
getRotationY()
public float getRotationY()
setRotationY(float)
public boolean setScaleX(float scaleX)
scaleX
- The scale value of the display listView.setScaleX(float)
,
getScaleX()
public float getScaleX()
setScaleX(float)
public boolean setScaleY(float scaleY)
scaleY
- The scale value of the display listView.setScaleY(float)
,
getScaleY()
public float getScaleY()
setScaleY(float)
public boolean setPivotX(float pivotX)
pivotX
- The pivot value of the display list on the X axis, in pixelsView.setPivotX(float)
,
getPivotX()
public float getPivotX()
setPivotX(float)
public boolean setPivotY(float pivotY)
pivotY
- The pivot value of the display list on the Y axis, in pixelsView.setPivotY(float)
,
getPivotY()
public float getPivotY()
setPivotY(float)
public boolean isPivotExplicitlySet()
public boolean setCameraDistance(float distance)
View.setCameraDistance(float)
for more information on how to
use this property.distance
- The distance in Z of the camera of the display listView.setCameraDistance(float)
,
getCameraDistance()
public float getCameraDistance()
setCameraDistance(float)
public boolean setLeft(int left)
left
- The left position, in pixels, of the display listView.setLeft(int)
public boolean setTop(int top)
top
- The top position, in pixels, of the display listView.setTop(int)
public boolean setRight(int right)
right
- The right position, in pixels, of the display listView.setRight(int)
public boolean setBottom(int bottom)
bottom
- The bottom position, in pixels, of the display listView.setBottom(int)
public boolean setLeftTopRightBottom(int left, int top, int right, int bottom)
left
- The left position of the display list, in pixelstop
- The top position of the display list, in pixelsright
- The right position of the display list, in pixelsbottom
- The bottom position of the display list, in pixelsView.setLeft(int)
,
View.setTop(int)
,
View.setRight(int)
,
View.setBottom(int)
public boolean offsetLeftAndRight(int offset)
offset
- The amount that the left and right positions of the display
list are offset, in pixelsView.offsetLeftAndRight(int)
public boolean offsetTopAndBottom(int offset)
offset
- The amount that the top and bottom positions of the display
list are offset, in pixelsView.offsetTopAndBottom(int)
public void output()
public int getDebugSize()
public void addAnimator(RenderNodeAnimator animator)
public boolean isAttached()
public void registerVectorDrawableAnimator(AnimatedVectorDrawable.VectorDrawableAnimatorRT animatorSet)
public void endAllAnimators()
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.