Camera2: Add hidden experimental tearDown method

Bug: 18949148
Change-Id: I6264d95a26ebf51cce6114c9a86b9561f7c60ab5

Author: Eino-Ville Talvala

core/java/android/hardware/camera2/CameraCaptureSession.java

@@ -138,6 +138,45 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      */
     public abstract void prepare(@NonNull Surface surface) throws CameraAccessException;
 
+
+    /**
+     * <p>Free all buffers allocated for an output Surface.</p>
+     *
+     * <p>Normally, once allocated, the image buffers for a given output Surface remain allocated
+     * for the lifetime of the capture session, to minimize latency of captures and to reduce
+     * memory allocation overhead.</p>
+     *
+     * <p>However, in some cases, it may be desirable for allocated buffers to be freed to reduce
+     * the application's memory consumption, if the particular output Surface will not be used by
+     * the application for some time.</p>
+     *
+     * <p>The tearDown() method can be used to perform this operation. After the call finishes, all
+     * unfilled image buffers will have been freed. Any future use of the target Surface may require
+     * allocation of additional buffers, as if the session had just been created.  Buffers being
+     * held by the application (either explicitly as Image objects from ImageReader, or implicitly
+     * as the current texture in a SurfaceTexture or the current contents of a RS Allocation, will
+     * remain valid and allocated even when tearDown is invoked.</p>
+     *
+     * <p>A Surface that has had tearDown() called on it is eligible to have prepare() invoked on it
+     * again even if it was used as a request target before the tearDown() call, as long as it
+     * doesn't get used as a target of a request between the tearDown() and prepare() calls.</p>
+     *
+     * @param surface the output Surface for which buffers should be freed. Must be one of the
+     * the output Surfaces used to create this session.
+     *
+     * @throws CameraAccessException if the camera device is no longer connected or has
+     *                               encountered a fatal error.
+     * @throws IllegalStateException if this session is no longer active, either because the session
+     *                               was explicitly closed, a new session has been created
+     *                               or the camera device has been closed.
+     * @throws IllegalArgumentException if the Surface is invalid, not part of this Session, or has
+     *                                  already been used as a target of a CaptureRequest in this
+     *                                  session or immediately prior sessions.
+     *
+     * @hide
+     */
+    public abstract void tearDown(@NonNull Surface surface) throws CameraAccessException;
+
     /**
      * <p>Submit a request for an image to be captured by the camera device.</p>
      *

core/java/android/hardware/camera2/ICameraDeviceUser.aidl

@@ -100,4 +100,6 @@ interface ICameraDeviceUser
     int flush(out LongParcelable lastFrameNumber);
 
     int prepare(int streamId);
+
+    int tearDown(int streamId);
 }

core/java/android/hardware/camera2/impl/CameraCaptureSessionImpl.java

@@ -145,6 +145,11 @@ public void prepare(Surface surface) throws CameraAccessException {
         mDeviceImpl.prepare(surface);
     }
 
+    @Override
+    public void tearDown(Surface surface) throws CameraAccessException {
+        mDeviceImpl.tearDown(surface);
+    }
+
     @Override
     public synchronized int capture(CaptureRequest request, CaptureCallback callback,
             Handler handler) throws CameraAccessException {

core/java/android/hardware/camera2/impl/CameraConstrainedHighSpeedCaptureSessionImpl.java

@@ -168,6 +168,11 @@ public void prepare(Surface surface) throws CameraAccessException {
         mSessionImpl.prepare(surface);
     }
 
+    @Override
+    public void tearDown(Surface surface) throws CameraAccessException {
+        mSessionImpl.tearDown(surface);
+    }
+
     @Override
     public int capture(CaptureRequest request, CaptureCallback listener, Handler handler)
             throws CameraAccessException {

core/java/android/hardware/camera2/impl/CameraDeviceImpl.java

@@ -679,6 +679,31 @@ public void prepare(Surface surface) throws CameraAccessException {
         }
     }
 
+    public void tearDown(Surface surface) throws CameraAccessException {
+        if (surface == null) throw new IllegalArgumentException("Surface is null");
+
+        synchronized(mInterfaceLock) {
+            int streamId = -1;
+            for (int i = 0; i < mConfiguredOutputs.size(); i++) {
+                if (surface == mConfiguredOutputs.valueAt(i).getSurface()) {
+                    streamId = mConfiguredOutputs.keyAt(i);
+                    break;
+                }
+            }
+            if (streamId == -1) {
+                throw new IllegalArgumentException("Surface is not part of this session");
+            }
+            try {
+                mRemoteDevice.tearDown(streamId);
+            } catch (CameraRuntimeException e) {
+                throw e.asChecked();
+            } catch (RemoteException e) {
+                // impossible
+                return;
+            }
+        }
+    }
+
     public int capture(CaptureRequest request, CaptureCallback callback, Handler handler)
             throws CameraAccessException {
         if (DEBUG) {

core/java/android/hardware/camera2/legacy/CameraDeviceUserShim.java

@@ -636,6 +636,20 @@ public int prepare(int streamId) {
         return CameraBinderDecorator.NO_ERROR;
     }
 
+    public int tearDown(int streamId) {
+        if (DEBUG) {
+            Log.d(TAG, "tearDown called.");
+        }
+        if (mLegacyDevice.isClosed()) {
+            Log.e(TAG, "Cannot tear down stream, device has been closed.");
+            return CameraBinderDecorator.ENODEV;
+        }
+
+        // LEGACY doesn't support actual teardown, so just a no-op
+
+        return CameraBinderDecorator.NO_ERROR;
+    }
+
     @Override
     public IBinder asBinder() {
         // This is solely intended to be used for in-process binding.