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

Commit fd887436 authored by Eino-Ville Talvala's avatar Eino-Ville Talvala
Browse files

Camera2: Final API revisions 

- Rename listeners to callbacks. Listeners are single-method and are interfaces,
  while callbacks are abstract may get more methods in the future.
- Use register/unregister for registering callbacks, not add/remove.

Bug: 17389922
Change-Id: Ic6b46ad79cb43a43a85e2a4b63f059d3af99798b
parent 9f30ce3b

api/current.txt

+16 −16
Original line number Diff line number Diff line
@@ -12651,17 +12651,17 @@ package android.hardware.camera2 { 
  public abstract class CameraCaptureSession implements java.lang.AutoCloseable {

    ctor public CameraCaptureSession();

    method public abstract void abortCaptures() throws android.hardware.camera2.CameraAccessException;

    method public abstract int capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureListener, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureListener, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract void close();

    method public abstract android.hardware.camera2.CameraDevice getDevice();

    method public abstract int setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureListener, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureListener, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract void stopRepeating() throws android.hardware.camera2.CameraAccessException;

  }













  public static abstract class CameraCaptureSession.CaptureListener {













    ctor public CameraCaptureSession.CaptureListener();













  public static abstract class CameraCaptureSession.CaptureCallback {













    ctor public CameraCaptureSession.CaptureCallback();















    method public void onCaptureCompleted(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.TotalCaptureResult);















    method public void onCaptureFailed(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureFailure);















    method public void onCaptureProgressed(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureResult);









@@ -12670,8 +12670,8 @@ package android.hardware.camera2 {













    method public void onCaptureStarted(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, long);















  }



























  public static abstract class CameraCaptureSession.StateListener {













    ctor public CameraCaptureSession.StateListener();













  public static abstract class CameraCaptureSession.StateCallback {













    ctor public CameraCaptureSession.StateCallback();















    method public void onActive(android.hardware.camera2.CameraCaptureSession);















    method public void onClosed(android.hardware.camera2.CameraCaptureSession);















    method public abstract void onConfigureFailed(android.hardware.camera2.CameraCaptureSession);










@@ -12758,7 +12758,7 @@ package android.hardware.camera2 {













  public abstract class CameraDevice implements java.lang.AutoCloseable {















    method public abstract void close();















    method public abstract android.hardware.camera2.CaptureRequest.Builder createCaptureRequest(int) throws android.hardware.camera2.CameraAccessException;













    method public abstract void createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateListener, android.os.Handler) throws android.hardware.camera2.CameraAccessException;













    method public abstract void createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;















    method public abstract java.lang.String getId();















    field public static final int TEMPLATE_MANUAL = 6; // 0x6















    field public static final int TEMPLATE_PREVIEW = 1; // 0x1









@@ -12768,8 +12768,8 @@ package android.hardware.camera2 {













    field public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; // 0x5















  }



























  public static abstract class CameraDevice.StateListener {













    ctor public CameraDevice.StateListener();













  public static abstract class CameraDevice.StateCallback {













    ctor public CameraDevice.StateCallback();















    method public void onClosed(android.hardware.camera2.CameraDevice);















    method public abstract void onDisconnected(android.hardware.camera2.CameraDevice);















    method public abstract void onError(android.hardware.camera2.CameraDevice, int);









@@ -12782,15 +12782,15 @@ package android.hardware.camera2 {













  }





























  public final class CameraManager {













    method public void addAvailabilityListener(android.hardware.camera2.CameraManager.AvailabilityListener, android.os.Handler);















    method public android.hardware.camera2.CameraCharacteristics getCameraCharacteristics(java.lang.String) throws android.hardware.camera2.CameraAccessException;















    method public java.lang.String[] getCameraIdList() throws android.hardware.camera2.CameraAccessException;













    method public void openCamera(java.lang.String, android.hardware.camera2.CameraDevice.StateListener, android.os.Handler) throws android.hardware.camera2.CameraAccessException;













    method public void removeAvailabilityListener(android.hardware.camera2.CameraManager.AvailabilityListener);













    method public void openCamera(java.lang.String, android.hardware.camera2.CameraDevice.StateCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;













    method public void registerAvailabilityCallback(android.hardware.camera2.CameraManager.AvailabilityCallback, android.os.Handler);













    method public void unregisterAvailabilityCallback(android.hardware.camera2.CameraManager.AvailabilityCallback);















  }



























  public static abstract class CameraManager.AvailabilityListener {













    ctor public CameraManager.AvailabilityListener();













  public static abstract class CameraManager.AvailabilityCallback {













    ctor public CameraManager.AvailabilityCallback();















    method public void onCameraAvailable(java.lang.String);















    method public void onCameraUnavailable(java.lang.String);















  }

























core/java/android/hardware/camera2/CameraAccessException.java



+1
−1




























Original line number
Diff line number
Diff line








@@ -61,7 +61,7 @@ public class CameraAccessException extends AndroidException {













     *















     * <p>The camera has failed to open or has failed at a later time















     * as a result of some non-user interaction. Refer to













     * {@link CameraDevice.StateListener#onError} for the exact













     * {@link CameraDevice.StateCallback#onError} for the exact















     * nature of the error.</p>















     *















     * <p>No further calls to the camera will succeed. Clean up

































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



+42
−28




























Original line number
Diff line number
Diff line








@@ -32,18 +32,18 @@ import java.util.List;













 * sending images to the desired targets. Therefore the setup is done asynchronously, and















 * {@link CameraDevice#createCaptureSession createCaptureSession} will send the ready-to-use















 * CameraCaptureSession to the provided listener's













 * {@link CameraCaptureSession.StateListener#onConfigured onConfigured} callback. If configuration













 * {@link CameraCaptureSession.StateCallback#onConfigured onConfigured} callback. If configuration















 * cannot be completed, then the













 * {@link CameraCaptureSession.StateListener#onConfigureFailed onConfigureFailed} is called, and the













 * {@link CameraCaptureSession.StateCallback#onConfigureFailed onConfigureFailed} is called, and the















 * session will not become active.</p>















 *<!--















 * <p>Any capture requests (repeating or non-repeating) submitted before the session is ready will















 * be queued up and will begin capture once the session becomes ready. In case the session cannot be













 * configured and {@link StateListener#onConfigureFailed onConfigureFailed} is called, all queued













 * configured and {@link StateCallback#onConfigureFailed onConfigureFailed} is called, all queued















 * capture requests are discarded.</p>















 *-->















 * <p>If a new session is created by the camera device, then the previous session is closed, and its













 * associated {@link StateListener#onClosed onClosed} callback will be invoked.  All













 * associated {@link StateCallback#onClosed onClosed} callback will be invoked.  All















 * of the session methods will throw an IllegalStateException if called once the session is















 * closed.</p>















 *










@@ -86,7 +86,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * looper}.















     *















     * @return int A unique capture sequence ID used by













     *             {@link CaptureListener#onCaptureSequenceCompleted}.













     *             {@link CaptureCallback#onCaptureSequenceCompleted}.















     *















     * @throws CameraAccessException if the camera device is no longer connected or has















     *                               encountered a fatal error









@@ -103,7 +103,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * @see #setRepeatingBurst















     * @see #abortCaptures















     */













    public abstract int capture(CaptureRequest request, CaptureListener listener, Handler handler)













    public abstract int capture(CaptureRequest request, CaptureCallback listener, Handler handler)















            throws CameraAccessException;































    /**










@@ -131,7 +131,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * looper}.















     *















     * @return int A unique capture sequence ID used by













     *             {@link CaptureListener#onCaptureSequenceCompleted}.













     *             {@link CaptureCallback#onCaptureSequenceCompleted}.















     *















     * @throws CameraAccessException if the camera device is no longer connected or has















     *                               encountered a fatal error









@@ -147,7 +147,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * @see #setRepeatingBurst















     * @see #abortCaptures















     */













    public abstract int captureBurst(List<CaptureRequest> requests, CaptureListener listener,













    public abstract int captureBurst(List<CaptureRequest> requests, CaptureCallback listener,















            Handler handler) throws CameraAccessException;































    /**










@@ -185,7 +185,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * looper}.















     *















     * @return int A unique capture sequence ID used by













     *             {@link CaptureListener#onCaptureSequenceCompleted}.













     *             {@link CaptureCallback#onCaptureSequenceCompleted}.















     *















     * @throws CameraAccessException if the camera device is no longer connected or has















     *                               encountered a fatal error









@@ -203,7 +203,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * @see #stopRepeating















     * @see #abortCaptures















     */













    public abstract int setRepeatingRequest(CaptureRequest request, CaptureListener listener,













    public abstract int setRepeatingRequest(CaptureRequest request, CaptureCallback listener,















            Handler handler) throws CameraAccessException;































    /**










@@ -245,7 +245,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * looper}.















     *















     * @return int A unique capture sequence ID used by













     *             {@link CaptureListener#onCaptureSequenceCompleted}.













     *             {@link CaptureCallback#onCaptureSequenceCompleted}.















     *















     * @throws CameraAccessException if the camera device is no longer connected or has















     *                               encountered a fatal error









@@ -263,7 +263,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * @see #stopRepeating















     * @see #abortCaptures















     */













    public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener,













    public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureCallback listener,















            Handler handler) throws CameraAccessException;































    /**









@@ -274,7 +274,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     *















     * <p>Any currently in-flight captures will still complete, as will any burst that is















     * mid-capture. To ensure that the device has finished processing all of its capture requests













     * and is in ready state, wait for the {@link StateListener#onReady} callback after













     * and is in ready state, wait for the {@link StateCallback#onReady} callback after















     * calling this method.</p>















     *















     * @throws CameraAccessException if the camera device is no longer connected or has









@@ -285,7 +285,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     *















     * @see #setRepeatingRequest















     * @see #setRepeatingBurst













     * @see StateListener#onIdle













     * @see StateCallback#onIdle















     */















    public abstract void stopRepeating() throws CameraAccessException;

























@@ -293,15 +293,15 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * Discard all captures currently pending and in-progress as fast as possible.















     *















     * <p>The camera device will discard all of its current work as fast as possible. Some in-flight













     * captures may complete successfully and call {@link CaptureListener#onCaptureCompleted}, while













     * others will trigger their {@link CaptureListener#onCaptureFailed} callbacks. If a repeating













     * captures may complete successfully and call {@link CaptureCallback#onCaptureCompleted}, while













     * others will trigger their {@link CaptureCallback#onCaptureFailed} callbacks. If a repeating















     * request or a repeating burst is set, it will be cleared.</p>















     *















     * <p>This method is the fastest way to switch the camera device to a new session with















     * {@link CameraDevice#createCaptureSession}, at the cost of discarding in-progress work. It















     * must be called before the new session is created. Once all pending requests are either













     * completed or thrown away, the {@link StateListener#onReady} callback will be called,













     * if the session has not been closed. Otherwise, the {@link StateListener#onClosed}













     * completed or thrown away, the {@link StateCallback#onReady} callback will be called,













     * if the session has not been closed. Otherwise, the {@link StateCallback#onClosed}















     * callback will be fired when a new session is created by the camera device.</p>















     *















     * <p>Cancelling will introduce at least a brief pause in the stream of data from the camera










@@ -332,7 +332,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     *















     * <p>Note that creating a new capture session with {@link CameraDevice#createCaptureSession}















     * will close any existing capture session automatically, and call the older session listener's













     * {@link StateListener#onClosed} callback. Using {@link CameraDevice#createCaptureSession}













     * {@link StateCallback#onClosed} callback. Using {@link CameraDevice#createCaptureSession}















     * directly without closing is the recommended approach for quickly switching to a new session,















     * since unchanged target outputs can be reused more efficiently.</p>















     *









@@ -340,7 +340,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * repeating requests or bursts are stopped (as if {@link #stopRepeating()} was called).















     * However, any in-progress capture requests submitted to the session will be completed as















     * normal; once all captures have completed and the session has been torn down,













     * {@link StateListener#onClosed} will be called.</p>













     * {@link StateCallback#onClosed} will be called.</p>















     *















     * <p>Closing a session is idempotent; closing more than once has no effect.</p>















     */









@@ -348,10 +348,10 @@ public abstract class CameraCaptureSession implements AutoCloseable {













    public abstract void close();































    /**













     * A listener for tracking the state of a camera capture session.













     * A callback object for receiving updates about the state of a camera capture session.















     *















     */













    public static abstract class StateListener {













    public static abstract class StateCallback {































        /**















         * This method is called when the camera device has finished configuring itself, and the










@@ -439,10 +439,17 @@ public abstract class CameraCaptureSession implements AutoCloseable {













    }































    /**













     * <p>A listener for tracking the progress of a {@link CaptureRequest}













     * submitted to the camera device.</p>













     * Temporary for migrating to Callback naming













     * @hide













     */













    public static abstract class StateListener extends StateCallback {













    }



























    /**













     * <p>A callback object for tracking the progress of a {@link CaptureRequest} submitted to the













     * camera device.</p>















     *













     * <p>This listener is called when a request triggers a capture to start,













     * <p>This callback is invoked when a request triggers a capture to start,















     * and when the capture is complete. In case on an error capturing an image,















     * the error method is triggered instead of the completion method.</p>















     *









@@ -451,7 +458,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













     * @see #setRepeatingRequest















     * @see #setRepeatingBurst















     */













    public static abstract class CaptureListener {













    public static abstract class CaptureCallback {































        /**















         * This constant is used to indicate that no images were captured for










@@ -625,7 +632,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













        }































        /**













         * This method is called independently of the others in CaptureListener,













         * This method is called independently of the others in CaptureCallback,















         * when a capture sequence finishes and all {@link CaptureResult}















         * or {@link CaptureFailure} for it have been returned via this listener.















         *










@@ -655,7 +662,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {













        }































        /**













         * This method is called independently of the others in CaptureListener,













         * This method is called independently of the others in CaptureCallback,















         * when a capture sequence aborts before any {@link CaptureResult}















         * or {@link CaptureFailure} for it have been returned via this listener.















         *










@@ -684,4 +691,11 @@ public abstract class CameraCaptureSession implements AutoCloseable {













        }















    }





























    /**













     * Temporary for migrating to Callback naming













     * @hide













     */













    public static abstract class CaptureListener extends CaptureCallback {













    }





























}
























core/java/android/hardware/camera2/CameraDevice.java



+27
−20




























Original line number
Diff line number
Diff line








@@ -199,8 +199,8 @@ public abstract class CameraDevice implements AutoCloseable {













     * <p>It can take several hundred milliseconds for the session's configuration to complete,















     * since camera hardware may need to be powered on or reconfigured. Once the configuration is















     * complete and the session is ready to actually capture data, the provided













     * {@link CameraCaptureSession.StateListener}'s













     * {@link CameraCaptureSession.StateListener#onConfigured} callback will be called.</p>













     * {@link CameraCaptureSession.StateCallback}'s













     * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p>















     *















     * <p>If a prior CameraCaptureSession already exists when a new one is created, the previous















     * session is closed. Any in-progress capture requests made on the prior session will be









@@ -218,12 +218,12 @@ public abstract class CameraDevice implements AutoCloseable {













     *















     * @param outputs The new set of Surfaces that should be made available as















     *                targets for captured image data.













     * @param listener The listener to notify about the status of the new capture session.













     * @param handler The handler on which the listener should be invoked, or {@code null} to use













     * @param callback The callback to notify about the status of the new capture session.













     * @param handler The handler on which the callback should be invoked, or {@code null} to use















     *                the current thread's {@link android.os.Looper looper}.















     *















     * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements,













     *                                  the listener is null, or the handler is null but the current













     *                                  the callback is null, or the handler is null but the current















     *                                  thread has no looper.















     * @throws CameraAccessException if the camera device is no longer connected or has















     *                               encountered a fatal error









@@ -235,7 +235,7 @@ public abstract class CameraDevice implements AutoCloseable {













     * @see StreamConfigurationMap#getOutputSizes(Class)















     */















    public abstract void createCaptureSession(List<Surface> outputs,













            CameraCaptureSession.StateListener listener, Handler handler)













            CameraCaptureSession.StateCallback callback, Handler handler)















            throws CameraAccessException;































    /**










@@ -271,10 +271,10 @@ public abstract class CameraDevice implements AutoCloseable {













     *















     * <p>Immediately after this call, all calls to the camera device or active session interface















     * will throw a {@link IllegalStateException}, except for calls to close(). Once the device has













     * fully shut down, the {@link StateListener#onClosed} callback will be called, and the camera













     * fully shut down, the {@link StateCallback#onClosed} callback will be called, and the camera















     * is free to be re-opened.</p>















     *













     * <p>Immediately after this call, besides the final {@link StateListener#onClosed} calls, no













     * <p>Immediately after this call, besides the final {@link StateCallback#onClosed} calls, no















     * further callbacks from the device or the active session will occur, and any remaining















     * submitted capture requests will be discarded, as if















     * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure









@@ -285,24 +285,24 @@ public abstract class CameraDevice implements AutoCloseable {













    public abstract void close();































    /**













     * A listener for notifications about the state of a camera













     * device.













     * A callback objects for receiving updates about the state of a camera device.















     *













     * <p>A listener must be provided to the {@link CameraManager#openCamera}













     * method to open a camera device.</p>













     * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to













     * open a camera device.</p>















     *













     * <p>These events include notifications about the device completing startup (













     * <p>These state updates include notifications about the device completing startup (















     * allowing for {@link #createCaptureSession} to be called), about device















     * disconnection or closure, and about unexpected device errors.</p>















     *















     * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided













     * through a {@link CameraCaptureSession.CaptureListener} given to the













     * through a {@link CameraCaptureSession.CaptureCallback} given to the















     * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst},













     * {@link CameraCaptureSession#setRepeatingRequest}, or {@link CameraCaptureSession#setRepeatingBurst} methods.













     * {@link CameraCaptureSession#setRepeatingRequest}, or













     * {@link CameraCaptureSession#setRepeatingBurst} methods.















     *















     * @see CameraManager#openCamera















     */













    public static abstract class StateListener {













    public static abstract class StateCallback {















       /**















         * An error code that can be reported by {@link #onError}















         * indicating that the camera device is in use already.










@@ -408,7 +408,7 @@ public abstract class CameraDevice implements AutoCloseable {













         * of a removable camera device; or the camera being needed for a















         * higher-priority use case.</p>















         *













         * <p>There may still be capture listener callbacks that are called













         * <p>There may still be capture callbacks that are invoked















         * after this method is called, or new image buffers that are delivered















         * to active outputs.</p>















         *









@@ -417,7 +417,7 @@ public abstract class CameraDevice implements AutoCloseable {













         *















         * <p>You should clean up the camera with {@link CameraDevice#close} after















         * this happens, as it is not recoverable until opening the camera again













         * after it becomes {@link CameraManager.AvailabilityListener#onCameraAvailable available}.













         * after it becomes {@link CameraManager.AvailabilityCallback#onCameraAvailable available}.















         * </p>















         *















         * @param camera the device that has been disconnected









@@ -436,7 +436,7 @@ public abstract class CameraDevice implements AutoCloseable {













         * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason.















         * </p>















         *













         * <p>There may still be capture completion or camera stream listeners













         * <p>There may still be capture completion or camera stream callbacks















         * that will be called after this error is received.</p>















         *















         * <p>You should clean up the camera with {@link CameraDevice#close} after









@@ -444,7 +444,7 @@ public abstract class CameraDevice implements AutoCloseable {













         *















         * @param camera The device reporting the error















         * @param error The error code, one of the













         *     {@code StateListener.ERROR_*} values.













         *     {@code StateCallback.ERROR_*} values.















         *















         * @see #ERROR_CAMERA_DEVICE















         * @see #ERROR_CAMERA_SERVICE









@@ -454,6 +454,13 @@ public abstract class CameraDevice implements AutoCloseable {













        public abstract void onError(CameraDevice camera, int error); // Must implement















    }





























    /**













     * Temporary for migrating to Callback naming













     * @hide













     */













    public static abstract class StateListener extends StateCallback {













    }





























    /**















     * To be inherited by android.hardware.camera2.* code only.















     * @hide

































core/java/android/hardware/camera2/CameraManager.java



+60
−53


























File changed.
Preview size limit exceeded, changes collapsed.