Merge "Tweak RenderNode's docs"

 *         canvas.drawRect(...);

 *     } finally {

 *         renderNode.endRecording();

 *     }

 * </pre>

 *     }</pre>

 *

 * <h3>Drawing a RenderNode in a View</h3>

 * <pre class="prettyprint">

 *             // Draw the RenderNode into this canvas.

 *             canvas.drawRenderNode(myRenderNode);

 *         }

 *     }

 * </pre>

 *     }</pre>

 *

 * <h3>Releasing resources</h3>

 * <p>This step is not mandatory but recommended if you want to release resources

 * <pre class="prettyprint">

 *     // Discards the display list content allowing for any held resources to be released.

 *     // After calling this

 *     renderNode.discardDisplayList();

 * </pre>

 *     renderNode.discardDisplayList();</pre>

 *

 *

 * <h3>Properties</h3>

 *          // will be invoked and will execute very quickly

 *          mRenderNode.offsetLeftAndRight(x);

 *          invalidate();

 *     }

 * </pre>

 *     }</pre>

 *

 * <p>A few of the properties may at first appear redundant, such as {@link #setElevation(float)}

 * and {@link #setTranslationZ(float)}. The reason for these duplicates are to allow for a

 * overlap with {@link #setPosition(Rect)}.

 *

 * <p>The RenderNode's transform matrix is computed at render time as follows:

 * First a setTranslate(getTranslationX(), getTranslationY()) is applied to a {@link Matrix}.

 * Second a preRotate(getRotationZ(), getPivotX(), getPivotY()) is applied to the matrix. And

 * finally a preScale(getScaleX(), getScaleY(), getPivotX(), getPivotY()) is applied. The current

 * canvas transform matrix, which is translated to the RenderNode's position,

 * is then multiplied by the RenderNode's transform matrix. Therefore there is no implicit

 * ordering in setting various RenderNode properties. That is to say that:

 * <pre class="prettyprint">

 *     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());</pre>

 * 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:

 *

 * <pre class="prettyprint">

 *     renderNode.setTranslationX(100);

 *     renderNode.setScaleX(100);

 * </pre>

 *     renderNode.setScaleX(100);</pre>

 *

 * is equivalent to

 * is equivalent to:

 *

 * <pre class="prettyprint">

 *     renderNode.setScaleX(100);

 *     renderNode.setTranslationX(100);

 * </pre>

 *     renderNode.setTranslationX(100);</pre>

 *

 * <h3>Threading</h3>

 * <p>RenderNode may be created and used on any thread but they are not thread-safe. Only

 *         if (needsUpdate) {

 *             myOwningView.invalidate();

 *         }

 *     }

 * </pre>

 *     }</pre>

 * This is marginally faster than doing a more explicit up-front check if the value changed by

 * comparing the desired value against {@link #getTranslationX()} as it minimizes JNI transitions.

 * The actual mechanism of requesting a new frame to be rendered will depend on how this