Merge "SurfaceControlViewHost: Improve documentation" into rvc-dev (4413b0ed) · Commits · e / os / android_frameworks_base

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;

+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.
		*/