Address API council feedback

Bug: 125027187
Bug: 125026102
Bug: 125026678
Bug: 125026234
Bug: 125027586
Bug: 125026476
Bug: 125026103
Bug: 125026237
Bug: 125027248
Bug: 125026475
Bug: 125027487
Test: RenderNodeTests
Change-Id: Ic63ea7a3cfe359a7dff0c1b46e534e499f7e928b

4 files changed, 179 insertions, 84 deletions

diff --git a/graphics/java/android/graphics/Bitmap.java b/graphics/java/android/graphics/Bitmap.java
index 81356710cce6..7ad949db310c 100644
--- a/graphics/java/android/graphics/Bitmap.java
+++ b/graphics/java/android/graphics/Bitmap.java
@@ -1267,7 +1267,7 @@ public final class Bitmap implements Parcelable {
             node.setLeftTopRightBottom(0, 0, width, height);
             node.setClipToBounds(false);
             node.setForceDarkAllowed(false);
-            final RecordingCanvas canvas = node.startRecording(width, height);
+            final RecordingCanvas canvas = node.beginRecording(width, height);
             if (source.getWidth() != width || source.getHeight() != height) {
                 canvas.scale(width / (float) source.getWidth(),
                         height / (float) source.getHeight());
diff --git a/graphics/java/android/graphics/HardwareRenderer.java b/graphics/java/android/graphics/HardwareRenderer.java
index b020556cd15f..e6233548651e 100644
--- a/graphics/java/android/graphics/HardwareRenderer.java
+++ b/graphics/java/android/graphics/HardwareRenderer.java
@@ -258,7 +258,7 @@ public class HardwareRenderer {
      *                and the renderer will draw nothing.
      */
     public void setContentRoot(@Nullable RenderNode content) {
-        RecordingCanvas canvas = mRootNode.startRecording();
+        RecordingCanvas canvas = mRootNode.beginRecording();
         if (content != null) {
             canvas.drawRenderNode(content);
         }
diff --git a/graphics/java/android/graphics/RecordingCanvas.java b/graphics/java/android/graphics/RecordingCanvas.java
index 515532ffda52..30466e1f6b1f 100644
--- a/graphics/java/android/graphics/RecordingCanvas.java
+++ b/graphics/java/android/graphics/RecordingCanvas.java
@@ -31,7 +31,7 @@ import dalvik.annotation.optimization.FastNative;
  * Bitmap objects that it draws, preventing the backing memory of Bitmaps from being released while
  * the RecordingCanvas is still holding a native reference to the memory.
  *
- * This is obtained by calling {@link RenderNode#startRecording()} and is valid until the matching
+ * This is obtained by calling {@link RenderNode#beginRecording()} and is valid until the matching
  * {@link RenderNode#endRecording()} is called. It must not be retained beyond that as it is
  * internally reused.
  */
diff --git a/graphics/java/android/graphics/RenderNode.java b/graphics/java/android/graphics/RenderNode.java
index 09b18b771250..e98879d0c5bd 100644
--- a/graphics/java/android/graphics/RenderNode.java
+++ b/graphics/java/android/graphics/RenderNode.java
@@ -16,6 +16,9 @@
 
 package android.graphics;
 
+import android.annotation.BytesLong;
+import android.annotation.ColorInt;
+import android.annotation.FloatRange;
 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
@@ -59,7 +62,7 @@ import java.lang.annotation.RetentionPolicy;
  * <pre class="prettyprint">
  *     RenderNode renderNode = RenderNode.create("myRenderNode");
  *     renderNode.setLeftTopRightBottom(0, 0, 50, 50); // Set the size to 50x50
- *     RecordingCanvas canvas = renderNode.startRecording();
+ *     RecordingCanvas canvas = renderNode.beginRecording();
  *     try {
  *         // Draw with the canvas
  *         canvas.drawRect(...);
@@ -71,14 +74,13 @@ import java.lang.annotation.RetentionPolicy;
  * <h3>Drawing a RenderNode in a View</h3>
  * <pre class="prettyprint">
  *     protected void onDraw(Canvas canvas) {
- *         if (canvas instanceof RecordingCanvas) {
- *             RecordingCanvas recordingCanvas = (RecordingCanvas) 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.
- *             recordingCanvas.drawRenderNode(myRenderNode);
+ *             canvas.drawRenderNode(myRenderNode);
  *         }
  *     }
  * </pre>
@@ -95,7 +97,7 @@ import java.lang.annotation.RetentionPolicy;
  *
  * <h3>Properties</h3>
  * <p>In addition, a RenderNode offers several properties, such as
- * {@link #setScaleX(float)} or {@link #setLeft(int)}, that can be used to affect all
+ * {@link #setScaleX(float)} or {@link #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
  * <code>canvas.drawBitmap()</code> calls.</p>
@@ -104,7 +106,7 @@ import java.lang.annotation.RetentionPolicy;
  *     private void createDisplayList() {
  *         mRenderNode = RenderNode.create("MyRenderNode");
  *         mRenderNode.setLeftTopRightBottom(0, 0, width, height);
- *         RecordingCanvas canvas = mRenderNode.startRecording();
+ *         RecordingCanvas canvas = mRenderNode.beginRecording();
  *         try {
  *             for (Bitmap b : mBitmaps) {
  *                 canvas.drawBitmap(b, 0.0f, 0.0f, null);
@@ -116,9 +118,8 @@ import java.lang.annotation.RetentionPolicy;
  *     }
  *
  *     protected void onDraw(Canvas canvas) {
- *         if (canvas instanceof RecordingCanvas) {
- *             RecordingCanvas recordingCanvas = (RecordingCanvas) canvas;
- *             recordingCanvas.drawRenderNode(mRenderNode);
+ *         if (canvas.isHardwareAccelerated())
+ *             canvas.drawRenderNode(mRenderNode);
  *         }
  *     }
  *
@@ -263,19 +264,20 @@ public final class RenderNode {
      * stored in this display list.
      *
      * {@link #endRecording()} must be called when the recording is finished in order to apply
-     * the updated display list.
+     * the updated display list. Failing to call {@link #endRecording()} will result in an
+     * {@link IllegalStateException} if {@link #beginRecording(int, int)} is called again.
      *
      * @param width  The width of the recording viewport. This will not alter the width of the
-     *               RenderNode itself, that must be set with {@link #setLeft(int)} and
-     *               {@link #setRight(int)}
+     *               RenderNode itself, that must be set with {@link #setPosition(Rect)}.
      * @param height The height of the recording viewport. This will not alter the height of the
-     *               RenderNode itself, that must be set with {@link #setTop(int)} and
-     *               {@link #setBottom(int)}.
+     *               RenderNode itself, that must be set with {@link #setPosition(Rect)}.
      * @return A canvas to record drawing operations.
+     * @throws IllegalStateException If a recording is already in progress. That is, the previous
+     * call to {@link #beginRecording(int, int)} did not call {@link #endRecording()}.
      * @see #endRecording()
      * @see #hasDisplayList()
      */
-    public RecordingCanvas startRecording(int width, int height) {
+    public RecordingCanvas beginRecording(int width, int height) {
         if (mCurrentRecordingCanvas != null) {
             throw new IllegalStateException(
                     "Recording currently in progress - missing #endRecording() call?");
@@ -285,21 +287,18 @@ public final class RenderNode {
     }
 
     /**
-     * Same as {@link #startRecording(int, int)} with the width & height set
+     * Same as {@link #beginRecording(int, int)} with the width & height set
      * to the RenderNode's own width & height. The RenderNode's width & height may be set
-     * with {@link #setLeftTopRightBottom(int, int, int, int)}.
-     */
-    public RecordingCanvas startRecording() {
-        return startRecording(nGetWidth(mNativeRenderNode), nGetHeight(mNativeRenderNode));
-    }
-
-    /**
-     * @hide
-     * @deprecated use {@link #startRecording(int, int)} instead
+     * with {@link #setPosition(int, int, int, int)}.
+     *
+     * @return A canvas to record drawing operations.
+     * @throws IllegalStateException If a recording is already in progress. That is, the previous
+     * call to {@link #beginRecording(int, int)} did not call {@link #endRecording()}.
+     * @see #endRecording()
+     * @see #hasDisplayList()
      */
-    @Deprecated
-    public RecordingCanvas start(int width, int height) {
-        return startRecording(width, height);
+    public RecordingCanvas beginRecording() {
+        return beginRecording(nGetWidth(mNativeRenderNode), nGetHeight(mNativeRenderNode));
     }
 
     /**
@@ -307,13 +306,13 @@ public final class RenderNode {
      * Ends the recording for this display list. Calling this method marks
      * the display list valid and {@link #hasDisplayList()} will return true.
      *
-     * @see #startRecording(int, int)
+     * @see #beginRecording(int, int)
      * @see #hasDisplayList()
      */
     public void endRecording() {
         if (mCurrentRecordingCanvas == null) {
             throw new IllegalStateException(
-                    "No recording in progress, forgot to call #startRecording()?");
+                    "No recording in progress, forgot to call #beginRecording()?");
         }
         RecordingCanvas canvas = mCurrentRecordingCanvas;
         mCurrentRecordingCanvas = null;
@@ -324,13 +323,21 @@ public final class RenderNode {
 
     /**
      * @hide
+     * @deprecated use {@link #beginRecording(int, int)} instead
+     */
+    @Deprecated
+    public RecordingCanvas start(int width, int height) {
+        return beginRecording(width, height);
+    }
+
+    /**
+     * @hide
      * @deprecated use {@link #endRecording()} instead
      */
     @Deprecated
     public void end(RecordingCanvas canvas) {
-        if (mCurrentRecordingCanvas != canvas) {
-            throw new IllegalArgumentException(
-                    "Canvas given isn't the one that was returned from #startRecording");
+        if (canvas != mCurrentRecordingCanvas) {
+            throw new IllegalArgumentException("Wrong canvas");
         }
         endRecording();
     }
@@ -346,7 +353,7 @@ public final class RenderNode {
 
     /**
      * Returns whether the RenderNode has a display list. If this returns false, the RenderNode
-     * should be re-recorded with {@link #startRecording()} and {@link #endRecording()}.
+     * should be re-recorded with {@link #beginRecording()} and {@link #endRecording()}.
      *
      * A RenderNode without a display list may still be drawn, however it will have no impact
      * on the rendering content until its display list is updated.
@@ -425,18 +432,21 @@ public final class RenderNode {
      * for performance or required for the current combination of {@link #setAlpha(float)} and
      * {@link #setHasOverlappingRendering(boolean)}.
      *
-     * The usage of this is instead to allow for either overriding of the internal behavior
+     * <p>The usage of this is instead to allow for either overriding of the internal behavior
      * if it's measured to be necessary for the particular rendering content in question or, more
      * usefully, to add a composition effect to the RenderNode via the optional paint parameter.
      *
-     * Note: When a RenderNode is using a compositing layer it will also result in
+     * <p>Note: When a RenderNode is using a compositing layer it will also result in
      * clipToBounds=true behavior.
      *
      * @param forceToLayer if true this forces the RenderNode to use an intermediate buffer.
      *                     Default & generally recommended value is false.
      * @param paint        The blend mode, alpha, and ColorFilter to apply to the compositing layer.
-     *                     Only applies if forceToLayer is true.
-     * @return true if anything changed, false otherwise
+     *                     Only applies if forceToLayer is true. The paint's alpha is multiplied
+     *                     with {@link #getAlpha()} to resolve the final alpha of the RenderNode.
+     *                     If null then no additional composition effects are applied on top of the
+     *                     composition layer.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setUseCompositingLayer(boolean forceToLayer, @Nullable Paint paint) {
         boolean didChange = nSetLayerType(mNativeRenderNode, forceToLayer ? 2 : 0);
@@ -457,15 +467,22 @@ public final class RenderNode {
     }
 
     /**
-     * Sets the clip bounds of the RenderNode. If null, the clip bounds is removed from the
-     * RenderNode. If non-null, the RenderNode will be clipped to this rect. If
+     * Sets an additional clip on the RenderNode. If null, the extra clip is removed from the
+     * RenderNode. If non-null, the RenderNode will be clipped to this rect. In addition  if
      * {@link #setClipToBounds(boolean)} is true, then the RenderNode will be clipped to the
-     * intersection of this rectangle and the bounds of the render node.
+     * intersection of this rectangle and the bounds of the render node, which is set with
+     * {@link #setPosition(Rect)}.
+     *
+     * <p>This is equivalent to do a {@link Canvas#clipRect(Rect)} at the start of this
+     * RenderNode's display list. However, as this is a property of the RenderNode instead
+     * of part of the display list it can be more easily animated for transient additional
+     * clipping. An example usage of this would be the {@link android.transition.ChangeBounds}
+     * transition animation with the resizeClip=true option.
      *
-     * @param rect the bounds to clip to. If null, the clip bounds are reset
-     * @return True if the clip bounds changed, false otherwise
+     * @param rect the bounds to clip to. If null, the additional clip is removed.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
-    public boolean setClipBounds(@Nullable Rect rect) {
+    public boolean setClipRect(@Nullable Rect rect) {
         if (rect == null) {
             return nSetClipBoundsEmpty(mNativeRenderNode);
         } else {
@@ -477,11 +494,12 @@ public final class RenderNode {
      * Set whether the Render node should clip itself to its bounds. This defaults to true,
      * and is useful to the renderer in enable quick-rejection of chunks of the tree as well as
      * better partial invalidation support. Clipping can be further restricted or controlled
-     * through the combination of this property as well as {@link #setClipBounds(Rect)}, which
+     * through the combination of this property as well as {@link #setClipRect(Rect)}, which
      * allows for a different clipping rectangle to be used in addition to or instead of the
-     * {@link #setLeftTopRightBottom(int, int, int, int)} or the RenderNode.
+     * {@link #setPosition(int, int, int, int)} or the RenderNode.
      *
      * @param clipToBounds true if the display list should clip to its bounds, false otherwise.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setClipToBounds(boolean clipToBounds) {
         return nSetClipToBounds(mNativeRenderNode, clipToBounds);
@@ -489,7 +507,7 @@ public final class RenderNode {
 
     /**
      * Returns whether or not the RenderNode is clipping to its bounds. See
-     * {@link #setClipToBounds(boolean)} and {@link #setLeftTopRightBottom(int, int, int, int)}
+     * {@link #setClipToBounds(boolean)} and {@link #setPosition(int, int, int, int)}
      *
      * @return true if the render node clips to its bounds, false otherwise.
      */
@@ -498,20 +516,58 @@ public final class RenderNode {
     }
 
     /**
-     * Sets whether the RenderNode should be drawn immediately after the
+     * <p>Sets whether the RenderNode should be drawn immediately after the
      * closest ancestor RenderNode containing a projection receiver.
      *
+     * <p>The default is false, and the rendering of this node happens in the typical draw order.
+     *
+     * <p>If true, then at rendering time this rendernode will not be drawn in order with the
+     * {@link Canvas#drawRenderNode(RenderNode)} command that drew this RenderNode, but instead
+     * it will be re-positioned in the RenderNode tree to be drawn on the closet ancestor with a
+     * child rendernode that has {@link #setProjectionReceiver(boolean)} as true.
+     *
+     * <p>The typical usage of this is to allow a child RenderNode to draw on a parent's background,
+     * such as the platform's usage with {@link android.graphics.drawable.RippleDrawable}. Consider
+     * the following structure, built out of which RenderNode called drawRenderNode on a different
+     * RenderNode:
+     *
+     * <pre>
+     *        +-------------+
+     *        |RenderNode: P|
+     *        +-+----------++
+     *          |          |
+     *          v          v
+     *  +-------+-----+  +-+--------------+
+     *  |RenderNode: C|  |RenderNode: P'BG|
+     *  +-------+-----+  +----------------+
+     *          |
+     *          |
+     * +--------+-------+
+     * |RenderNode: C'BG|
+     * +----------------+
+     * </pre>
+     *
+     * If P'BG is a projection receiver, and C'BG is set to project backwards then C'BG will
+     * behave as if it was drawn directly by P'BG instead of by C. This includes inheriting P'BG's
+     * clip instead of C's clip.
+     *
      * @param shouldProject true if the display list should be projected onto a
-     *                      containing volume.
+     *                      containing volume. Default is false.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setProjectBackwards(boolean shouldProject) {
         return nSetProjectBackwards(mNativeRenderNode, shouldProject);
     }
 
     /**
-     * Sets whether the RenderNode is a projection receiver - that its parent
-     * RenderNode should draw any descendent RenderNodes with
-     * ProjectBackwards=true directly on top of it. Default value is false.
+     * Sets whether the RenderNode is a projection receiver. If true then this RenderNode's parent
+     * should draw any descendant RenderNodes with ProjectBackwards=true directly on top of it.
+     * Default value is false. See
+     * {@link #setProjectBackwards(boolean)} for a description of what this entails.
+     *
+     * @param shouldRecieve True if this RenderNode is a projection receiver, false otherwise.
+     *                      Default is false.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setProjectionReceiver(boolean shouldRecieve) {
         return nSetProjectionReceiver(mNativeRenderNode, shouldRecieve);
@@ -526,6 +582,7 @@ public final class RenderNode {
      * outline for those changes to be applied.
      *
      * @param outline The outline to use for this RenderNode.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setOutline(@Nullable Outline outline) {
         if (outline == null) {
@@ -572,8 +629,9 @@ public final class RenderNode {
      * {@link android.R.attr#spotShadowAlpha} theme attribute
      *
      * @param color The color this RenderNode will cast for its elevation spot shadow.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
-    public boolean setSpotShadowColor(int color) {
+    public boolean setSpotShadowColor(@ColorInt int color) {
         return nSetSpotShadowColor(mNativeRenderNode, color);
     }
 
@@ -581,7 +639,7 @@ public final class RenderNode {
      * @return The shadow color set by {@link #setSpotShadowColor(int)}, or black if nothing
      * was set
      */
-    public int getSpotShadowColor() {
+    public @ColorInt int getSpotShadowColor() {
         return nGetSpotShadowColor(mNativeRenderNode);
     }
 
@@ -597,8 +655,9 @@ public final class RenderNode {
      * {@link android.R.attr#ambientShadowAlpha} theme attribute.
      *
      * @param color The color this RenderNode will cast for its elevation shadow.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
-    public boolean setAmbientShadowColor(int color) {
+    public boolean setAmbientShadowColor(@ColorInt int color) {
         return nSetAmbientShadowColor(mNativeRenderNode, color);
     }
 
@@ -606,7 +665,7 @@ public final class RenderNode {
      * @return The shadow color set by {@link #setAmbientShadowColor(int)}, or black if
      * nothing was set
      */
-    public int getAmbientShadowColor() {
+    public @ColorInt int getAmbientShadowColor() {
         return nGetAmbientShadowColor(mNativeRenderNode);
     }
 
@@ -614,6 +673,8 @@ public final class RenderNode {
      * Enables or disables clipping to the outline.
      *
      * @param clipToOutline true if clipping to the outline.
+     * @return True if the clipToOutline value changed, false if previous value matched the new
+     *         value.
      */
     public boolean setClipToOutline(boolean clipToOutline) {
         return nSetClipToOutline(mNativeRenderNode, clipToOutline);
@@ -640,7 +701,7 @@ public final class RenderNode {
 
     /**
      * 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.)
+     * transforms (such as {@link #setScaleX(float)}, {@link #setRotationZ(float)}, etc.)
      *
      * @param matrix A transform matrix to apply to this display list
      * @hide TODO Do we want this?
@@ -669,6 +730,7 @@ public final class RenderNode {
      * @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 True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setAlpha(float alpha) {
         return nSetAlpha(mNativeRenderNode, alpha);
@@ -742,7 +804,7 @@ public final class RenderNode {
      * Sets the base elevation of this RenderNode in pixels
      *
      * @param lift the elevation in pixels
-     * @return true if the elevation changed, false if it was the same
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setElevation(float lift) {
         return nSetElevation(mNativeRenderNode, lift);
@@ -763,6 +825,7 @@ public final class RenderNode {
      * @param translationX The X axis translation value of the display list, in pixels
      * @see View#setTranslationX(float)
      * @see #getTranslationX()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setTranslationX(float translationX) {
         return nSetTranslationX(mNativeRenderNode, translationX);
@@ -783,6 +846,7 @@ public final class RenderNode {
      * @param translationY The Y axis translation value of the display list, in pixels
      * @see View#setTranslationY(float)
      * @see #getTranslationY()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setTranslationY(float translationY) {
         return nSetTranslationY(mNativeRenderNode, translationY);
@@ -802,6 +866,7 @@ public final class RenderNode {
      *
      * @see View#setTranslationZ(float)
      * @see #getTranslationZ()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setTranslationZ(float translationZ) {
         return nSetTranslationZ(mNativeRenderNode, translationZ);
@@ -820,19 +885,20 @@ public final class RenderNode {
      * 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()
+     * @see View#setRotationZ(float)
+     * @see #getRotationZ()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
-    public boolean setRotation(float rotation) {
+    public boolean setRotationZ(float rotation) {
         return nSetRotation(mNativeRenderNode, rotation);
     }
 
     /**
      * Returns the rotation value for this display list around the Z axis, in degrees.
      *
-     * @see #setRotation(float)
+     * @see #setRotationZ(float)
      */
-    public float getRotation() {
+    public float getRotationZ() {
         return nGetRotation(mNativeRenderNode);
     }
 
@@ -842,6 +908,7 @@ public final class RenderNode {
      * @param rotationX The rotation value of the display list, in degrees
      * @see View#setRotationX(float)
      * @see #getRotationX()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setRotationX(float rotationX) {
         return nSetRotationX(mNativeRenderNode, rotationX);
@@ -862,6 +929,7 @@ public final class RenderNode {
      * @param rotationY The rotation value of the display list, in degrees
      * @see View#setRotationY(float)
      * @see #getRotationY()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setRotationY(float rotationY) {
         return nSetRotationY(mNativeRenderNode, rotationY);
@@ -882,6 +950,7 @@ public final class RenderNode {
      * @param scaleX The scale value of the display list
      * @see View#setScaleX(float)
      * @see #getScaleX()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setScaleX(float scaleX) {
         return nSetScaleX(mNativeRenderNode, scaleX);
@@ -902,6 +971,7 @@ public final class RenderNode {
      * @param scaleY The scale value of the display list
      * @see View#setScaleY(float)
      * @see #getScaleY()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setScaleY(float scaleY) {
         return nSetScaleY(mNativeRenderNode, scaleY);
@@ -922,6 +992,7 @@ public final class RenderNode {
      * @param pivotX The pivot value of the display list on the X axis, in pixels
      * @see View#setPivotX(float)
      * @see #getPivotX()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setPivotX(float pivotX) {
         return nSetPivotX(mNativeRenderNode, pivotX);
@@ -942,6 +1013,7 @@ public final class RenderNode {
      * @param pivotY The pivot value of the display list on the Y axis, in pixels
      * @see View#setPivotY(float)
      * @see #getPivotY()
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setPivotY(float pivotY) {
         return nSetPivotY(mNativeRenderNode, pivotY);
@@ -969,6 +1041,8 @@ public final class RenderNode {
      * Clears any pivot previously set by a call to  {@link #setPivotX(float)} or
      * {@link #setPivotY(float)}. After calling this {@link #isPivotExplicitlySet()} will be false
      * and the pivot used for rotation will return to default of being centered on the view.
+     *
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean resetPivot() {
         return nResetPivot(mNativeRenderNode);
@@ -997,8 +1071,10 @@ public final class RenderNode {
      * @param distance The distance in pixels, must always be positive
      * @see #setRotationX(float)
      * @see #setRotationY(float)
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
-    public boolean setCameraDistance(float distance) {
+    public boolean setCameraDistance(
+            @FloatRange(from = 0.0f, to = Float.MAX_VALUE) float distance) {
         if (!Float.isFinite(distance) || distance < 0.0f) {
             throw new IllegalArgumentException("distance must be finite & positive, given="
                     + distance);
@@ -1013,7 +1089,7 @@ public final class RenderNode {
      * @return the distance along the Z axis in pixels.
      * @see #setCameraDistance(float)
      */
-    public float getCameraDistance() {
+    public @FloatRange(from = 0.0f, to = Float.MAX_VALUE) float getCameraDistance() {
         return -nGetCameraDistance(mNativeRenderNode);
     }
 
@@ -1022,6 +1098,7 @@ public final class RenderNode {
      *
      * @param left The left position, in pixels, of the RenderNode
      * @return true if the value changed, false otherwise
+     * @hide
      */
     public boolean setLeft(int left) {
         return nSetLeft(mNativeRenderNode, left);
@@ -1032,6 +1109,7 @@ public final class RenderNode {
      *
      * @param top The top position, in pixels, of the RenderNode
      * @return true if the value changed, false otherwise.
+     * @hide
      */
     public boolean setTop(int top) {
         return nSetTop(mNativeRenderNode, top);
@@ -1042,6 +1120,7 @@ public final class RenderNode {
      *
      * @param right The right position, in pixels, of the RenderNode
      * @return true if the value changed, false otherwise.
+     * @hide
      */
     public boolean setRight(int right) {
         return nSetRight(mNativeRenderNode, right);
@@ -1052,6 +1131,7 @@ public final class RenderNode {
      *
      * @param bottom The bottom position, in pixels, of the RenderNode
      * @return true if the value changed, false otherwise.
+     * @hide
      */
     public boolean setBottom(int bottom) {
         return nSetBottom(mNativeRenderNode, bottom);
@@ -1060,8 +1140,6 @@ public final class RenderNode {
     /**
      * Gets the left position for the RenderNode.
      *
-     * See {@link #setLeft(int)}
-     *
      * @return the left position in pixels
      */
     public int getLeft() {
@@ -1071,8 +1149,6 @@ public final class RenderNode {
     /**
      * Gets the top position for the RenderNode.
      *
-     * See {@link #setTop(int)}
-     *
      * @return the top position in pixels
      */
     public int getTop() {
@@ -1082,8 +1158,6 @@ public final class RenderNode {
     /**
      * Gets the right position for the RenderNode.
      *
-     * See {@link #setRight(int)}
-     *
      * @return the right position in pixels
      */
     public int getRight() {
@@ -1093,8 +1167,6 @@ public final class RenderNode {
     /**
      * Gets the bottom position for the RenderNode.
      *
-     * See {@link #setBottom(int)}
-     *
      * @return the bottom position in pixels
      */
     public int getBottom() {
@@ -1127,20 +1199,41 @@ public final class RenderNode {
      * @param right  The right position of the RenderNode, in pixels
      * @param bottom The bottom position of the RenderNode, in pixels
      * @return true if any values changed, false otherwise.
-     * @see #setLeft(int)
-     * @see #setTop(int)
-     * @see #setRight(int)
-     * @see #setBottom(int)
+     * @hide
      */
     public boolean setLeftTopRightBottom(int left, int top, int right, int bottom) {
         return nSetLeftTopRightBottom(mNativeRenderNode, left, top, right, bottom);
     }
 
     /**
+     * Sets the position of the RenderNode.
+     *
+     * @param left   The left position of the RenderNode, in pixels
+     * @param top    The top position of the RenderNode, in pixels
+     * @param right  The right position of the RenderNode, in pixels
+     * @param bottom The bottom position of the RenderNode, in pixels
+     * @return True if the value changed, false if the new value was the same as the previous value.
+     */
+    public boolean setPosition(int left, int top, int right, int bottom) {
+        return nSetLeftTopRightBottom(mNativeRenderNode, left, top, right, bottom);
+    }
+
+    /**
+     * Sets the position of the RenderNode.
+     *
+     * @param position The position rectangle in pixels
+     * @return True if the value changed, false if the new value was the same as the previous value.
+     */
+    public boolean setPosition(Rect position) {
+        return nSetLeftTopRightBottom(mNativeRenderNode,
+                position.left, position.top, position.right, position.bottom);
+    }
+
+    /**
      * Offsets the left and right positions for the RenderNode
      *
      * @param offset The amount that the left and right positions are offset in pixels
-     * @return true if any values changed, false otherwise.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean offsetLeftAndRight(int offset) {
         return nOffsetLeftAndRight(mNativeRenderNode, offset);
@@ -1150,7 +1243,7 @@ public final class RenderNode {
      * Offsets the top and bottom values for the RenderNode
      *
      * @param offset The amount that the left and right positions are offset in pixels
-     * @return true if any values changed, false otherwise.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean offsetTopAndBottom(int offset) {
         return nOffsetTopAndBottom(mNativeRenderNode, offset);
@@ -1170,8 +1263,10 @@ public final class RenderNode {
      * Gets the approximate memory usage of the RenderNode for debug purposes. Does not include
      * the memory usage of any child RenderNodes nor any bitmaps, only the memory usage of
      * this RenderNode and any data it owns.
+     *
+     * @return Approximate memory usage in bytes.
      */
-    public int computeApproximateMemoryUsage() {
+    public @BytesLong long computeApproximateMemoryUsage() {
         return nGetDebugSize(mNativeRenderNode);
     }
 
@@ -1186,7 +1281,7 @@ public final class RenderNode {
      * it prevent any 'false' in any of its children.
      *
      * @param allow Whether or not to allow force dark.
-     * @return true If the value has changed, false otherwise.
+     * @return True if the value changed, false if the new value was the same as the previous value.
      */
     public boolean setForceDarkAllowed(boolean allow) {
         return nSetAllowForceDark(mNativeRenderNode, allow);