FileDocCategorySizeDatePackage
RenderNode.javaAPI DocAndroid 5.1 API33478Thu Mar 12 22:22:10 GMT 2015android.view

RenderNode

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 {@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.

Hardware acceleration

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()}.

Creating a display list

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();
}
}

Rendering a display list on a View

protected void onDraw(Canvas canvas) {
if (canvas.isHardwareAccelerated()) {
HardwareCanvas hardwareCanvas = (HardwareCanvas) canvas;
hardwareCanvas.drawDisplayList(mDisplayList);
}
}

Releasing resources

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();

Properties

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() {
mDisplayList = DisplayList.create("MyDisplayList");
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();
}

Threading

Display lists must be created on and manipulated from the UI thread only.

hide

Fields Summary
public static final int
FLAG_CLIP_CHILDREN
Flag used when calling {@link HardwareCanvas#drawRenderNode(RenderNode, 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.
public static final int
STATUS_DONE
Indicates that the display list is done drawing.
public static final int
STATUS_DRAW
Indicates that the display list needs another drawing pass.
public static final int
STATUS_INVOKE
Indicates that the display list needs to re-execute its GL functors.
public static final int
STATUS_DREW
Indicates that the display list performed GL drawing operations.
private boolean
mValid
final long
mNativeRenderNode
private final View
mOwningView
Constructors Summary
private RenderNode(String name, View owningView)


         
        mNativeRenderNode = nCreate(name);
        mOwningView = owningView;
    
private RenderNode(long nativePtr)

see
RenderNode#adopt(long)

        mNativeRenderNode = nativePtr;
        mOwningView = null;
    
Methods Summary
public voidaddAnimator(RenderNodeAnimator animator)

        if (mOwningView == null || mOwningView.mAttachInfo == null) {
            throw new IllegalStateException("Cannot start this animator on a detached view!");
        }
        nAddAnimator(mNativeRenderNode, animator.getNativeAnimator());
        mOwningView.mAttachInfo.mViewRootImpl.registerAnimatingRenderNode(this);
    
public static android.view.RenderNodeadopt(long nativePtr)
Adopts an existing native render node. Note: This will *NOT* incRef() on the native object, however it will decRef() when it is destroyed. The caller should have already incRef'd it

        return new RenderNode(nativePtr);
    
public static android.view.RenderNodecreate(java.lang.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.

param
name The name of the RenderNode, used for debugging purpose. May be null.
return
A new RenderNode.

        return new RenderNode(name, owningView);
    
public voiddestroyDisplayListData()
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.

        if (!mValid) return;

        nSetDisplayListData(mNativeRenderNode, 0);
        mValid = false;
    
public voidend(HardwareCanvas endCanvas)
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()

        if (!(endCanvas instanceof GLES20RecordingCanvas)) {
            throw new IllegalArgumentException("Passed an invalid canvas to end!");
        }

        GLES20RecordingCanvas canvas = (GLES20RecordingCanvas) endCanvas;
        canvas.onPostDraw();
        long renderNodeData = canvas.finishRecording();
        nSetDisplayListData(mNativeRenderNode, renderNodeData);
        canvas.recycle();
        mValid = true;
    
public voidendAllAnimators()

        nEndAllAnimators(mNativeRenderNode);
    
protected voidfinalize()

        try {
            nDestroyRenderNode(mNativeRenderNode);
        } finally {
            super.finalize();
        }
    
public floatgetAlpha()
Returns the translucency level of this display list.

return
A value between 0.0f and 1.0f
see
#setAlpha(float)

        return nGetAlpha(mNativeRenderNode);
    
public floatgetCameraDistance()
Returns the distance in Z of the camera of the display list.

see
#setCameraDistance(float)

        return nGetCameraDistance(mNativeRenderNode);
    
public booleangetClipToOutline()

        return nGetClipToOutline(mNativeRenderNode);
    
public intgetDebugSize()
Gets the size of the DisplayList for debug purposes.

        return nGetDebugSize(mNativeRenderNode);
    
public floatgetElevation()

        return nGetElevation(mNativeRenderNode);
    
public voidgetInverseMatrix(android.graphics.Matrix outMatrix)

        nGetInverseTransformMatrix(mNativeRenderNode, outMatrix.native_instance);
    
public voidgetMatrix(android.graphics.Matrix outMatrix)

        nGetTransformMatrix(mNativeRenderNode, outMatrix.native_instance);
    
longgetNativeDisplayList()

        if (!mValid) {
            throw new IllegalStateException("The display list is not valid.");
        }
        return mNativeRenderNode;
    
public floatgetPivotX()
Returns the pivot value for this display list on the X axis, in pixels.

see
#setPivotX(float)

        return nGetPivotX(mNativeRenderNode);
    
public floatgetPivotY()
Returns the pivot value for this display list on the Y axis, in pixels.

see
#setPivotY(float)

        return nGetPivotY(mNativeRenderNode);
    
public floatgetRotation()
Returns the rotation value for this display list around the Z axis, in degrees.

see
#setRotation(float)

        return nGetRotation(mNativeRenderNode);
    
public floatgetRotationX()
Returns the rotation value for this display list around the X axis, in degrees.

see
#setRotationX(float)

        return nGetRotationX(mNativeRenderNode);
    
public floatgetRotationY()
Returns the rotation value for this display list around the Y axis, in degrees.

see
#setRotationY(float)

        return nGetRotationY(mNativeRenderNode);
    
public floatgetScaleX()
Returns the scale value for this display list on the X axis.

see
#setScaleX(float)

        return nGetScaleX(mNativeRenderNode);
    
public floatgetScaleY()
Returns the scale value for this display list on the Y axis.

see
#setScaleY(float)

        return nGetScaleY(mNativeRenderNode);
    
public floatgetTranslationX()
Returns the translation value for this display list on the X axis, in pixels.

see
#setTranslationX(float)

        return nGetTranslationX(mNativeRenderNode);
    
public floatgetTranslationY()
Returns the translation value for this display list on the Y axis, in pixels.

see
#setTranslationY(float)

        return nGetTranslationY(mNativeRenderNode);
    
public floatgetTranslationZ()
Returns the translation value for this display list on the Z axis.

see
#setTranslationZ(float)

        return nGetTranslationZ(mNativeRenderNode);
    
public booleanhasIdentityMatrix()

        return nHasIdentityMatrix(mNativeRenderNode);
    
public booleanhasOverlappingRendering()
Indicates whether the content of this display list overlaps.

return
True if this display list renders content which overlaps, false otherwise.
see
#setHasOverlappingRendering(boolean)

        //noinspection SimplifiableIfStatement
        return nHasOverlappingRendering(mNativeRenderNode);
    
public booleanhasShadow()

        return nHasShadow(mNativeRenderNode);
    
public booleanisPivotExplicitlySet()

        return nIsPivotExplicitlySet(mNativeRenderNode);
    
public booleanisValid()
Returns whether the RenderNode's display list content 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.

 return mValid; 
private static native voidnAddAnimator(long renderNode, long animatorPtr)

private static native longnCreate(java.lang.String name)

private static native voidnDestroyRenderNode(long renderNode)

private static native voidnEndAllAnimators(long renderNode)

private static native floatnGetAlpha(long renderNode)

private static native floatnGetCameraDistance(long renderNode)

private static native booleannGetClipToOutline(long renderNode)

private static native intnGetDebugSize(long renderNode)

private static native floatnGetElevation(long renderNode)

private static native voidnGetInverseTransformMatrix(long renderNode, long nativeMatrix)

private static native floatnGetPivotX(long renderNode)

private static native floatnGetPivotY(long renderNode)

private static native floatnGetRotation(long renderNode)

private static native floatnGetRotationX(long renderNode)

private static native floatnGetRotationY(long renderNode)

private static native floatnGetScaleX(long renderNode)

private static native floatnGetScaleY(long renderNode)

private static native voidnGetTransformMatrix(long renderNode, long nativeMatrix)

private static native floatnGetTranslationX(long renderNode)

private static native floatnGetTranslationY(long renderNode)

private static native floatnGetTranslationZ(long renderNode)

private static native booleannHasIdentityMatrix(long renderNode)

private static native booleannHasOverlappingRendering(long renderNode)

private static native booleannHasShadow(long renderNode)

private static native booleannIsPivotExplicitlySet(long renderNode)

private static native booleannOffsetLeftAndRight(long renderNode, int offset)

private static native booleannOffsetTopAndBottom(long renderNode, int offset)

private static native voidnOutput(long renderNode)

private static native booleannSetAlpha(long renderNode, float alpha)

private static native booleannSetAnimationMatrix(long renderNode, long animationMatrix)

private static native booleannSetBottom(long renderNode, int bottom)

private static native booleannSetCameraDistance(long renderNode, float distance)

private static native booleannSetClipBounds(long renderNode, int left, int top, int right, int bottom)

private static native booleannSetClipBoundsEmpty(long renderNode)

private static native booleannSetClipToBounds(long renderNode, boolean clipToBounds)

private static native booleannSetClipToOutline(long renderNode, boolean clipToOutline)

private static native voidnSetDisplayListData(long renderNode, long newData)

private static native booleannSetElevation(long renderNode, float lift)

private static native booleannSetHasOverlappingRendering(long renderNode, boolean hasOverlappingRendering)

private static native booleannSetLayerPaint(long renderNode, long paint)

private static native booleannSetLayerType(long renderNode, int layerType)

private static native booleannSetLeft(long renderNode, int left)

private static native booleannSetLeftTopRightBottom(long renderNode, int left, int top, int right, int bottom)

private static native booleannSetOutlineConvexPath(long renderNode, long nativePath, float alpha)

private static native booleannSetOutlineEmpty(long renderNode)

private static native booleannSetOutlineNone(long renderNode)

private static native booleannSetOutlineRoundRect(long renderNode, int left, int top, int right, int bottom, float radius, float alpha)

private static native booleannSetPivotX(long renderNode, float pivotX)

private static native booleannSetPivotY(long renderNode, float pivotY)

private static native booleannSetProjectBackwards(long renderNode, boolean shouldProject)

private static native booleannSetProjectionReceiver(long renderNode, boolean shouldRecieve)

private static native booleannSetRevealClip(long renderNode, boolean shouldClip, float x, float y, float radius)

private static native booleannSetRight(long renderNode, int right)

private static native booleannSetRotation(long renderNode, float rotation)

private static native booleannSetRotationX(long renderNode, float rotationX)

private static native booleannSetRotationY(long renderNode, float rotationY)

private static native booleannSetScaleX(long renderNode, float scaleX)

private static native booleannSetScaleY(long renderNode, float scaleY)

private static native booleannSetStaticMatrix(long renderNode, long nativeMatrix)

private static native booleannSetTop(long renderNode, int top)

private static native booleannSetTranslationX(long renderNode, float translationX)

private static native booleannSetTranslationY(long renderNode, float translationY)

private static native booleannSetTranslationZ(long renderNode, float translationZ)

public booleanoffsetLeftAndRight(int offset)
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)

        return nOffsetLeftAndRight(mNativeRenderNode, offset);
    
public booleanoffsetTopAndBottom(int 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)

        return nOffsetTopAndBottom(mNativeRenderNode, offset);
    
public voidoutput()
Outputs the display list to the log. This method exists for use by tools to output display lists for selected nodes to the log.

        nOutput(mNativeRenderNode);
    
public booleansetAlpha(float alpha)
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()

        return nSetAlpha(mNativeRenderNode, alpha);
    
public booleansetAnimationMatrix(android.graphics.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.

        return nSetAnimationMatrix(mNativeRenderNode,
                (matrix != null) ? matrix.native_instance : 0);
    
public booleansetBottom(int bottom)
Sets the bottom position for the display list.

param
bottom The bottom position, in pixels, of the display list
see
View#setBottom(int)

        return nSetBottom(mNativeRenderNode, bottom);
    
public booleansetCameraDistance(float distance)
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()

        return nSetCameraDistance(mNativeRenderNode, distance);
    
public booleansetClipBounds(android.graphics.Rect rect)

        if (rect == null) {
            return nSetClipBoundsEmpty(mNativeRenderNode);
        } else {
            return nSetClipBounds(mNativeRenderNode, rect.left, rect.top, rect.right, rect.bottom);
        }
    
public booleansetClipToBounds(boolean clipToBounds)
Set whether the Render node 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

        return nSetClipToBounds(mNativeRenderNode, clipToBounds);
    
public booleansetClipToOutline(boolean clipToOutline)
Enables or disables clipping to the outline.

param
clipToOutline true if clipping to the outline.

        return nSetClipToOutline(mNativeRenderNode, clipToOutline);
    
public booleansetElevation(float lift)

        return nSetElevation(mNativeRenderNode, lift);
    
public booleansetHasOverlappingRendering(boolean hasOverlappingRendering)
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()

        return nSetHasOverlappingRendering(mNativeRenderNode, hasOverlappingRendering);
    
public booleansetLayerPaint(android.graphics.Paint paint)

        return nSetLayerPaint(mNativeRenderNode, paint != null ? paint.mNativePaint : 0);
    
public booleansetLayerType(int layerType)

        return nSetLayerType(mNativeRenderNode, layerType);
    
public booleansetLeft(int left)
Sets the left position for the display list.

param
left The left position, in pixels, of the display list
see
View#setLeft(int)

        return nSetLeft(mNativeRenderNode, left);
    
public booleansetLeftTopRightBottom(int left, int top, int right, int bottom)
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)

        return nSetLeftTopRightBottom(mNativeRenderNode, left, top, right, bottom);
    
public booleansetOutline(android.graphics.Outline outline)
Sets the outline, defining the shape that casts a shadow, and the path to be clipped if setClipToOutline is set. Deep copies the data into native to simplify reference ownership.

        if (outline == null) {
            return nSetOutlineNone(mNativeRenderNode);
        } else if (outline.isEmpty()) {
            return nSetOutlineEmpty(mNativeRenderNode);
        } else if (outline.mRect != null) {
            return nSetOutlineRoundRect(mNativeRenderNode, outline.mRect.left, outline.mRect.top,
                    outline.mRect.right, outline.mRect.bottom, outline.mRadius, outline.mAlpha);
        } else if (outline.mPath != null) {
            return nSetOutlineConvexPath(mNativeRenderNode, outline.mPath.mNativePath,
                    outline.mAlpha);
        }
        throw new IllegalArgumentException("Unrecognized outline?");
    
public booleansetPivotX(float pivotX)
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()

        return nSetPivotX(mNativeRenderNode, pivotX);
    
public booleansetPivotY(float pivotY)
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()

        return nSetPivotY(mNativeRenderNode, pivotY);
    
public booleansetProjectBackwards(boolean shouldProject)
Sets whether the display list should be drawn immediately after the closest ancestor display list containing a projection receiver.

param
shouldProject true if the display list should be projected onto a containing volume.

        return nSetProjectBackwards(mNativeRenderNode, shouldProject);
    
public booleansetProjectionReceiver(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. Default value is false.

        return nSetProjectionReceiver(mNativeRenderNode, shouldRecieve);
    
public booleansetRevealClip(boolean shouldClip, float x, float y, float radius)
Controls the RenderNode's circular reveal clip.

        return nSetRevealClip(mNativeRenderNode, shouldClip, x, y, radius);
    
public booleansetRight(int right)
Sets the right position for the display list.

param
right The right position, in pixels, of the display list
see
View#setRight(int)

        return nSetRight(mNativeRenderNode, right);
    
public booleansetRotation(float rotation)
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()

        return nSetRotation(mNativeRenderNode, rotation);
    
public booleansetRotationX(float rotationX)
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()

        return nSetRotationX(mNativeRenderNode, rotationX);
    
public booleansetRotationY(float rotationY)
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()

        return nSetRotationY(mNativeRenderNode, rotationY);
    
public booleansetScaleX(float scaleX)
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()

        return nSetScaleX(mNativeRenderNode, scaleX);
    
public booleansetScaleY(float scaleY)
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()

        return nSetScaleY(mNativeRenderNode, scaleY);
    
public booleansetStaticMatrix(android.graphics.Matrix matrix)
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

        return nSetStaticMatrix(mNativeRenderNode, matrix.native_instance);
    
public booleansetTop(int top)
Sets the top position for the display list.

param
top The top position, in pixels, of the display list
see
View#setTop(int)

        return nSetTop(mNativeRenderNode, top);
    
public booleansetTranslationX(float translationX)
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()

        return nSetTranslationX(mNativeRenderNode, translationX);
    
public booleansetTranslationY(float translationY)
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()

        return nSetTranslationY(mNativeRenderNode, translationY);
    
public booleansetTranslationZ(float translationZ)
Sets the translation value for the display list on the Z axis.

see
View#setTranslationZ(float)
see
#getTranslationZ()

        return nSetTranslationZ(mNativeRenderNode, translationZ);
    
public HardwareCanvasstart(int width, int height)
Starts recording a display list for the render node. All operations performed on the returned canvas are recorded and stored in this display list. Calling this method will mark the render node invalid until {@link #end(HardwareCanvas)} is called. Only valid render nodes can be replayed.

param
width The width of the recording viewport
param
height The height of the recording viewport
return
A canvas to record drawing operations.
see
#end(HardwareCanvas)
see
#isValid()

        HardwareCanvas canvas = GLES20RecordingCanvas.obtain(this);
        canvas.setViewport(width, height);
        // The dirty rect should always be null for a display list
        canvas.onPreDraw(null);
        return canvas;