diff options
| -rw-r--r-- | core/java/android/view/SurfaceControlViewHost.java | 16 | ||||
| -rw-r--r-- | core/java/android/view/SurfaceView.java | 19 |
2 files changed, 32 insertions, 3 deletions
diff --git a/core/java/android/view/SurfaceControlViewHost.java b/core/java/android/view/SurfaceControlViewHost.java index 174165c5ba59..cfceb031539f 100644 --- a/core/java/android/view/SurfaceControlViewHost.java +++ b/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; diff --git a/core/java/android/view/SurfaceView.java b/core/java/android/view/SurfaceView.java index b677ccd9a618..9880ea096cf2 100644 --- a/core/java/android/view/SurfaceView.java +++ b/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. */ |