Merge "Address API council feedback"

2 files changed, 32 insertions, 5 deletions

diff --git a/api/current.txt b/api/current.txt
index fd342964ec8a..7007e3c428a8 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -14127,8 +14127,9 @@ package android.graphics {
     method public void setLightSourceGeometry(float, float, float, float);
     method public void setName(@NonNull String);
     method public void setOpaque(boolean);
-    method public void setStopped(boolean);
     method public void setSurface(@Nullable android.view.Surface);
+    method public void start();
+    method public void stop();
     field public static final int SYNC_CONTEXT_IS_STOPPED = 4; // 0x4
     field public static final int SYNC_FRAME_DROPPED = 8; // 0x8
     field public static final int SYNC_LOST_SURFACE_REWARD_IF_FOUND = 2; // 0x2
diff --git a/graphics/java/android/graphics/HardwareRenderer.java b/graphics/java/android/graphics/HardwareRenderer.java
index 7345ea4db43d..bc744cc7af3d 100644
--- a/graphics/java/android/graphics/HardwareRenderer.java
+++ b/graphics/java/android/graphics/HardwareRenderer.java
@@ -170,13 +170,14 @@ public class HardwareRenderer {
 
     /**
      * Destroys the rendering context of this HardwareRenderer. This destroys the resources
-     * associated with this renderer and releases the currently set {@link Surface}.
+     * associated with this renderer and releases the currently set {@link Surface}. This must
+     * be called when this HardwareRenderer is no longer needed.
      *
      * <p>The renderer may be restored from this state by setting a new {@link Surface}, setting
      * new rendering content with {@link #setContentRoot(RenderNode)}, and resuming
      * rendering by issuing a new {@link FrameRenderRequest}.
      *
-     * <p>It is suggested to call this in response to callbacks such as
+     * <p>It is recommended to call this in response to callbacks such as
      * {@link android.view.SurfaceHolder.Callback#surfaceDestroyed(SurfaceHolder)}.
      *
      * <p>Note that if there are any outstanding frame commit callbacks they may never being
@@ -383,7 +384,7 @@ public class HardwareRenderer {
          * The system internally may reuse instances of {@link FrameRenderRequest} to reduce
          * allocation churn.
          *
-         * @return The result of the sync operation. See {@link SyncAndDrawResult}.
+         * @return The result of the sync operation.
          */
         @SyncAndDrawResult
         public int syncAndDraw() {
@@ -456,12 +457,37 @@ public class HardwareRenderer {
      * and {@link Activity#onStart()}.
      *
      * @param stopped true to stop all rendering, false to resume
+     * @hide
      */
     public void setStopped(boolean stopped) {
         nSetStopped(mNativeProxy, stopped);
     }
 
     /**
+     * Hard stops rendering into the surface. If the renderer is stopped it will
+     * block any attempt to render. Calls to {@link FrameRenderRequest#syncAndDraw()} will
+     * still sync over the latest rendering content, however they will not render and instead
+     * {@link #SYNC_CONTEXT_IS_STOPPED} will be returned.
+     *
+     * <p>This is useful in combination with lifecycle events such as {@link Activity#onStop()}.
+     * See {@link #start()} for resuming rendering.
+     */
+    public void stop() {
+        nSetStopped(mNativeProxy, true);
+    }
+
+    /**
+     * Resumes rendering into the surface. Any pending rendering requests
+     * will produce a new frame at the next vsync signal.
+     *
+     * <p>This is useful in combination with lifecycle events such as {@link Activity#onStart()}.
+     * See {@link #stop()} for stopping rendering.
+     */
+    public void start() {
+        nSetStopped(mNativeProxy, false);
+    }
+
+    /**
      * Destroys all the display lists associated with the current rendering content.
      * This includes releasing a reference to the current content root RenderNode. It will
      * therefore be necessary to call {@link #setContentRoot(RenderNode)} in order to resume
@@ -473,7 +499,7 @@ public class HardwareRenderer {
      * {@link android.content.ComponentCallbacks2#onTrimMemory(int)} signals such as
      * {@link android.content.ComponentCallbacks2#TRIM_MEMORY_UI_HIDDEN}
      *
-     * See also {@link #setStopped(boolean)}
+     * See also {@link #stop()}.
      */
     public void clearContent() {
         nDestroyHardwareResources(mNativeProxy);