Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 20c23963 authored by Robert Carr's avatar Robert Carr
Browse files

SurfaceControlViewHost: Improve documentation 

Capturing the answers to some questions I received today in-to
source-code comments.

Bug: 153756455
Test: Comments only
Change-Id: I208ca0370267803bf546d654f5a8d4e0c25b6f11
parent 4d7fb0b4

core/java/android/view/SurfaceControlViewHost.java

+16 −0
Original line number Diff line number Diff line
@@ -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

+16 −3
Original line number Diff line number Diff line
@@ -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.

     */