From 28a1f9428ecf6430abb5038f9251b7f2b67f17f2 Mon Sep 17 00:00:00 2001
From: John Reck <jreck@google.com>
Date: Wed, 6 Mar 2019 17:27:15 -0800
Subject: Address API council feedback

Fixes: 127532446
Test: build & checked docs
Change-Id: Ibf14ad52040694ccd503aaa187b99c19338b727a
---
 .../java/android/graphics/HardwareRenderer.java    | 34 +++++++++++++++++++---
 1 file changed, 30 insertions(+), 4 deletions(-)

(limited to 'graphics/java/android')

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,11 +457,36 @@ 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
@@ -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);
-- 
cgit v1.2.3-59-g8ed1b