Merge "SurfaceControlViewHost: Improve documentation" into rvc-dev am: 4413b0edba am: 96d7fdc315

Change-Id: I839f2be3e869f2bcbd1637dc18f850aa8fa5acdb

core/java/android/view/SurfaceControlViewHost.java

@@ -50,6 +50,22 @@ public class SurfaceControlViewHost {
      * elements. It's expected to get this object from
      * {@link SurfaceControlViewHost#getSurfacePackage} afterwards it can be embedded within
      * a SurfaceView by calling {@link SurfaceView#setChildSurfacePackage}.
+     *
+     * Note that each {@link SurfacePackage} must be released by calling
+     * {@link SurfacePackage#release}. However, if you use the recommended flow,
+     *  the framework will automatically handle the lifetime for you.
+     *
+     * 1. When sending the package to the remote process, return it from an AIDL method
+     * or manually use FLAG_WRITE_RETURN_VALUE in writeToParcel. This will automatically
+     * release the package in the local process.
+     * 2. In the remote process, consume the package using SurfaceView. This way the
+     * SurfaceView will take over the lifetime and call {@link SurfacePackage#release}
+     * for the user.
+     *
+     * One final note: The {@link SurfacePackage} lifetime is totally de-coupled
+     * from the lifetime of the underlying {@link SurfaceControlViewHost}. Regardless
+     * of the lifetime of the package the user should still call
+     * {@link SurfaceControlViewHost#release} when finished.
      */
     public static final class SurfacePackage implements Parcelable {
         private SurfaceControl mSurfaceControl;

core/java/android/view/SurfaceView.java

@@ -1650,11 +1650,24 @@ public class SurfaceView extends View implements ViewRootImpl.SurfaceChangedCall
 
     /**
      * Display the view-hierarchy embedded within a {@link SurfaceControlViewHost.SurfacePackage}
-     * within this SurfaceView. If this SurfaceView is above it's host Surface (see
+     * within this SurfaceView.
+     *
+     * This can be called independently of the SurfaceView lifetime callbacks. SurfaceView
+     * will internally manage reparenting the package to our Surface as it is created
+     * and destroyed.
+     *
+     * If this SurfaceView is above its host Surface (see
      * {@link #setZOrderOnTop} then the embedded Surface hierarchy will be able to receive
-     * input. This will take ownership of the SurfaceControl contained inside the SurfacePackage
+     * input.
+     *
+     * This will take ownership of the SurfaceControl contained inside the SurfacePackage
      * and free the caller of the obligation to call
-     * {@link SurfaceControlViewHost.SurfacePackage#release}.
+     * {@link SurfaceControlViewHost.SurfacePackage#release}. However, note that
+     * {@link SurfaceControlViewHost.SurfacePackage#release} and
+     * {@link SurfaceControlViewHost#release} are not the same. While the ownership
+     * of this particular {@link SurfaceControlViewHost.SurfacePackage} will be taken by the
+     * SurfaceView the underlying {@link SurfaceControlViewHost} remains managed by it's original
+     * remote-owner.
      *
      * @param p The SurfacePackage to embed.
      */