RenderNode

Kotlin |Java

class RenderNode

kotlin.Any
↳	android.graphics.RenderNode

RenderNode is used to build hardware accelerated rendering hierarchies. Each RenderNode contains both a display list as well as a set of properties that affect the rendering of the display list. RenderNodes are used internally for all Views by default and are not typically used directly.

RenderNodes are used to divide up the rendering content of a complex scene into smaller pieces that can then be updated individually more cheaply. Updating part of the scene only needs to update the display list or properties of a small number of RenderNode instead of redrawing everything from scratch. A RenderNode only needs its display list re-recorded when its content alone should be changed. RenderNodes can also be transformed without re-recording the display list through the transform properties.

A text editor might for instance store each paragraph into its own RenderNode. Thus when the user inserts or removes characters, only the display list of the affected paragraph needs to be recorded again.

Hardware acceleration

RenderNodes can be drawn using a RecordingCanvas. They are not supported in software. Always make sure that the android.graphics.Canvas you are using to render a display list is hardware accelerated using android.graphics.Canvas#isHardwareAccelerated().

Creating a RenderNode

RenderNode renderNode = new RenderNode("myRenderNode");
      renderNode.setPosition(0, 0, 50, 50); // Set the size to 50x50
      RecordingCanvas canvas = renderNode.beginRecording();
      try {
          // Draw with the canvas
          canvas.drawRect(...);
      } finally {
          renderNode.endRecording();
      }

Drawing a RenderNode in a View

protected void onDraw(Canvas canvas) {
          if (canvas.isHardwareAccelerated()) {
              // Check that the RenderNode has a display list, re-recording it if it does not.
              if (!myRenderNode.hasDisplayList()) {
                  updateDisplayList(myRenderNode);
              }
              // Draw the RenderNode into this canvas.
              canvas.drawRenderNode(myRenderNode);
          }
      }

Releasing resources

This step is not mandatory but recommended if you want to release resources held by a display list as soon as possible. Most significantly any bitmaps it may contain.

// Discards the display list content allowing for any held resources to be released.
      // After calling this
      renderNode.discardDisplayList();

Properties

In addition, a RenderNode offers several properties, such as setScaleX(float) or setTranslationX(float), 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 canvas.drawBitmap() calls.

private void createDisplayList() {
          mRenderNode = new RenderNode("MyRenderNode");
          mRenderNode.setPosition(0, 0, width, height);
          RecordingCanvas canvas = mRenderNode.beginRecording();
          try {
              for (Bitmap b : mBitmaps) {
                  canvas.drawBitmap(b, 0.0f, 0.0f, null);
                  canvas.translate(0.0f, b.getHeight());
              }
          } finally {
              mRenderNode.endRecording();
          }
      }
 
      protected void onDraw(Canvas canvas) {
          if (canvas.isHardwareAccelerated())
              canvas.drawRenderNode(mRenderNode);
          }
      }
 
      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
           mRenderNode.offsetLeftAndRight(x);
           invalidate();
      }

A few of the properties may at first appear redundant, such as setElevation(float) and setTranslationZ(float). The reason for these duplicates are to allow for a separation between static & transient usages. For example consider a button that raises from 2dp to 8dp when pressed. To achieve that an application may decide to setElevation(2dip), and then on press to animate setTranslationZ to 6dip. Combined this achieves the final desired 8dip value, but the animation need only concern itself with animating the lift from press without needing to know the initial starting value. setTranslationX(float) and setTranslationY(float) are similarly provided for animation uses despite the functional overlap with setPosition(android.graphics.Rect).

The RenderNode's transform matrix is computed at render time as follows:

Matrix transform = new Matrix();
      transform.setTranslate(renderNode.getTranslationX(), renderNode.getTranslationY());
      transform.preRotate(renderNode.getRotationZ(),
              renderNode.getPivotX(), renderNode.getPivotY());
      transform.preScale(renderNode.getScaleX(), renderNode.getScaleY(),
              renderNode.getPivotX(), renderNode.getPivotY());

The current canvas transform matrix, which is translated to the RenderNode's position, is then multiplied by the RenderNode's transform matrix. Therefore the ordering of calling property setters does not affect the result. That is to say that:

renderNode.setTranslationX(100);
      renderNode.setScaleX(100);

is equivalent to:

renderNode.setScaleX(100);
      renderNode.setTranslationX(100);

Threading

RenderNode may be created and used on any thread but they are not thread-safe. Only a single thread may interact with a RenderNode at any given time. It is critical that the RenderNode is only used on the same thread it is drawn with. For example when using RenderNode with a custom View, then that RenderNode must only be used from the UI thread.

When to re-render

Many of the RenderNode mutation methods, such as setTranslationX(float), return a boolean indicating if the value actually changed or not. This is useful in detecting if a new frame should be rendered or not. A typical usage would look like:

public void translateTo(int x, int y) {
          boolean needsUpdate = myRenderNode.setTranslationX(x);
          needsUpdate |= myRenderNode.setTranslationY(y);
          if (needsUpdate) {
              myOwningView.invalidate();
          }
      }

This is marginally faster than doing a more explicit up-front check if the value changed by comparing the desired value against getTranslationX() as it minimizes JNI transitions. The actual mechanism of requesting a new frame to be rendered will depend on how this RenderNode is being drawn. If it's drawn to a containing View, as in the above snippet, then simply invalidating that View works. If instead the RenderNode is being drawn to a Canvas directly such as with Surface#lockHardwareCanvas() then a new frame needs to be drawn by calling Surface#lockHardwareCanvas(), re-drawing the root RenderNode or whatever top-level content is desired, and finally calling Surface#unlockCanvasAndPost(Canvas).

Summary

Public constructors
`RenderNode(name: String?)` Creates a new RenderNode that can be used to record batches of drawing operations, and store / apply render properties when drawn.

Public methods
RecordingCanvas	`beginRecording(width: Int, height: Int)` Starts recording a display list for the render node.
RecordingCanvas	`beginRecording()` Same as `beginRecording(int,int)` with the width & height set to the RenderNode's own width & height.
Long	`computeApproximateMemoryUsage()` Gets the approximate memory usage of the RenderNode for debug purposes.
Unit	`discardDisplayList()` Reset native resources.
Unit	`endRecording()` ` Ends the recording for this display list.
Float	`getAlpha()` Returns the translucency level of this display list.
Int	`getAmbientShadowColor()`
Int	`getBottom()` Gets the bottom position for the RenderNode.
Float	`getCameraDistance()` Returns the distance in Z of the camera for this RenderNode
Boolean	`getClipToBounds()` Returns whether or not the RenderNode is clipping to its bounds.
Boolean	`getClipToOutline()` See `setClipToOutline(boolean)`
Float	`getElevation()` See `setElevation(float)`
Int	`getHeight()` Gets the height of the RenderNode, which is the bottom - top.
Unit	`getInverseMatrix(outMatrix: Matrix)` Gets the current transform inverted.
Int	`getLeft()` Gets the left position for the RenderNode.
Unit	`getMatrix(outMatrix: Matrix)` Gets the current transform matrix
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.
Int	`getRight()` Gets the right position for the RenderNode.
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	`getRotationZ()` Returns the rotation value for this display list around the Z 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.
Int	`getSpotShadowColor()`
Int	`getTop()` Gets the top position for the RenderNode.
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.
Long	`getUniqueId()` Returns the unique ID that identifies this RenderNode.
Boolean	`getUseCompositingLayer()` Gets whether or not a compositing layer is forced to be used.
Int	`getWidth()` Gets the width of the RenderNode, which is the right - left.
Boolean	`hasDisplayList()` Returns whether the RenderNode has a display list.
Boolean	`hasIdentityMatrix()` Whether or not the RenderNode has an identity transform.
Boolean	`hasOverlappingRendering()` Indicates whether the content of this display list overlaps.
Boolean	`hasShadow()` Checks if the RenderNode has a shadow.
Boolean	`isForceDarkAllowed()` See `setForceDarkAllowed(boolean)`
Boolean	`isPivotExplicitlySet()`
Boolean	`offsetLeftAndRight(offset: Int)` Offsets the left and right positions for the RenderNode
Boolean	`offsetTopAndBottom(offset: Int)` Offsets the top and bottom values for the RenderNode
Boolean	`resetPivot()` Clears any pivot previously set by a call to `setPivotX(float)` or `setPivotY(float)`.
Boolean	`setAlpha(alpha: Float)` Sets the translucency level for the display list.
Boolean	`setAmbientShadowColor(color: Int)` Sets the color of the ambient shadow that is drawn when the RenderNode has a positive Z or elevation value and is drawn inside of a `Canvas#enableZ()` section.
Boolean	`setCameraDistance(distance: Float)` Sets the distance along the Z axis (orthogonal to the X/Y plane on which RenderNodes are drawn) from the camera to this RenderNode.
Boolean	`setClipRect(rect: Rect?)` Sets an additional clip on the RenderNode.
Boolean	`setClipToBounds(clipToBounds: Boolean)` Set whether the Render node should clip itself to its bounds.
Boolean	`setClipToOutline(clipToOutline: Boolean)` Enables or disables clipping to the outline.
Boolean	`setElevation(lift: Float)` Sets the base elevation of this RenderNode in pixels
Boolean	`setForceDarkAllowed(allow: Boolean)` Sets whether or not to allow force dark to apply to this RenderNode.
Boolean	`setHasOverlappingRendering(hasOverlappingRendering: Boolean)` Sets whether the display list renders content which overlaps.
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(pivotX: Float)` Sets the pivot value for the display list on the X axis
Boolean	`setPivotY(pivotY: Float)` Sets the pivot value for the display list on the Y axis
Boolean	`setPosition(left: Int, top: Int, right: Int, bottom: Int)` Sets the position of the RenderNode.
Boolean	`setPosition(position: Rect)` Sets the position of the RenderNode.
Boolean	`setProjectBackwards(shouldProject: Boolean)` Sets whether the RenderNode should be drawn immediately after the closest ancestor RenderNode containing a projection receiver.
Boolean	`setProjectionReceiver(shouldReceive: Boolean)` Sets whether the RenderNode is a projection receiver.
Boolean	`setRenderEffect(renderEffect: RenderEffect?)` Configure the `android.graphics.RenderEffect` to apply to this RenderNode.
Boolean	`setRotationX(rotationX: Float)` Sets the rotation value for the display list around the X axis.
Boolean	`setRotationY(rotationY: Float)` Sets the rotation value for the display list around the Y axis.
Boolean	`setRotationZ(rotation: Float)` Sets the rotation value for the display list around the Z axis.
Boolean	`setScaleX(scaleX: Float)` Sets the scale value for the display list on the X axis.
Boolean	`setScaleY(scaleY: Float)` Sets the scale value for the display list on the Y axis.
Boolean	`setSpotShadowColor(color: Int)` Sets the color of the spot shadow that is drawn when the RenderNode has a positive Z or elevation value and is drawn inside of a `Canvas#enableZ()` section.
Boolean	`setTranslationX(translationX: Float)` Sets the translation value for the display list on the X axis.
Boolean	`setTranslationY(translationY: Float)` Sets the translation value for the display list on the Y axis.
Boolean	`setTranslationZ(translationZ: Float)` Sets the translation value for the display list on the Z axis.
Boolean	`setUseCompositingLayer(forceToLayer: Boolean, paint: Paint?)` Controls whether or not to force this RenderNode to render to an intermediate buffer.

Parameters
`width`	Int: The width of the recording viewport. This will not alter the width of the RenderNode itself, that must be set with `setPosition(android.graphics.Rect)`.
`height`	Int: The height of the recording viewport. This will not alter the height of the RenderNode itself, that must be set with `setPosition(android.graphics.Rect)`.

Parameters
`left`	Int: The left position of the RenderNode, in pixels
`top`	Int: The top position of the RenderNode, in pixels
`right`	Int: The right position of the RenderNode, in pixels
`bottom`	Int: The bottom position of the RenderNode, in pixels

Parameters
`forceToLayer`	Boolean: if true this forces the RenderNode to use an intermediate buffer. Default & generally recommended value is false.
`paint`	Paint?: The blend mode, alpha, and ColorFilter to apply to the compositing layer. Only applies if forceToLayer is true. The paint's alpha is multiplied with `getAlpha()` to resolve the final alpha of the RenderNode. If null then no additional composition effects are applied on top of the composition layer.

RenderNode

Hardware acceleration

Creating a RenderNode

Drawing a RenderNode in a View

Releasing resources

Properties

Threading

When to re-render

Summary

Public constructors

RenderNode

Public methods

beginRecording

beginRecording

computeApproximateMemoryUsage

discardDisplayList

endRecording

getAlpha

getAmbientShadowColor

getBottom

getCameraDistance

getClipToBounds

getClipToOutline

getElevation

getHeight

getInverseMatrix

getLeft

getMatrix

getPivotX

getPivotY

getRight

getRotationX

getRotationY

getRotationZ

getScaleX

getScaleY

getSpotShadowColor

getTop

getTranslationX

getTranslationY

getTranslationZ

getUniqueId

getUseCompositingLayer

getWidth

hasDisplayList

hasIdentityMatrix

hasOverlappingRendering

hasShadow

isForceDarkAllowed

isPivotExplicitlySet

offsetLeftAndRight

offsetTopAndBottom

resetPivot

setAlpha

setAmbientShadowColor

setCameraDistance

setClipRect

setClipToBounds

setClipToOutline

setElevation

setForceDarkAllowed

setHasOverlappingRendering

setOutline

setPivotX

setPivotY

setPosition

setPosition

setProjectBackwards

setProjectionReceiver

setRenderEffect

setRotationX

setRotationY

setRotationZ

setScaleX

setScaleY

setSpotShadowColor

setTranslationX

setTranslationY

setTranslationZ

setUseCompositingLayer