Merge "Address API council feedback"
diff --git a/api/current.txt b/api/current.txt
index fd34296..7007e3c 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -14127,8 +14127,9 @@
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 7345ea4..bc744cc 100644
--- a/graphics/java/android/graphics/HardwareRenderer.java
+++ b/graphics/java/android/graphics/HardwareRenderer.java
@@ -170,13 +170,14 @@
/**
* 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 @@
* 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 @@
* 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 @@
* {@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);