Merge "Camera2: Add SDK annotations" into mnc-dev (77545f6a) · Commits · e / os / android_frameworks_base

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

+21 −5

Original line number	Diff line number	Diff line
		@@ -16,8 +16,13 @@

		package android.hardware.camera2;

		import android.annotation.NonNull;
		import android.annotation.IntDef;
		import android.util.AndroidException;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* <p><code>CameraAccessException</code> is thrown if a camera device could not
		* be queried or opened by the {@link CameraManager}, or if the connection to an
		@@ -76,6 +81,16 @@ public class CameraAccessException extends AndroidException {
		*/
		public static final int CAMERA_DEPRECATED_HAL = 1000;

		/** @hide */
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(
		{CAMERA_IN_USE,
		MAX_CAMERAS_IN_USE,
		CAMERA_DISABLED,
		CAMERA_DISCONNECTED,
		CAMERA_ERROR})
		public @interface AccessError {};

		// Make the eclipse warning about serializable exceptions go away
		private static final long serialVersionUID = 5630338637471475675L; // randomly generated

		@@ -88,26 +103,27 @@ public class CameraAccessException extends AndroidException {
		* @see #CAMERA_DISCONNECTED
		* @see #CAMERA_ERROR
		*/
		@AccessError
		public final int getReason() {
		return mReason;
		}

		public CameraAccessException(int problem) {
		public CameraAccessException(@AccessError int problem) {
		super(getDefaultMessage(problem));
		mReason = problem;
		}

		public CameraAccessException(int problem, String message) {
		public CameraAccessException(@AccessError int problem, String message) {
		super(message);
		mReason = problem;
		}

		public CameraAccessException(int problem, String message, Throwable cause) {
		public CameraAccessException(@AccessError int problem, String message, Throwable cause) {
		super(message, cause);
		mReason = problem;
		}

		public CameraAccessException(int problem, Throwable cause) {
		public CameraAccessException(@AccessError int problem, Throwable cause) {
		super(getDefaultMessage(problem), cause);
		mReason = problem;
		}
		@@ -115,7 +131,7 @@ public class CameraAccessException extends AndroidException {
		/**
		* @hide
		*/
		public static String getDefaultMessage(int problem) {
		public static String getDefaultMessage(@AccessError int problem) {
		switch (problem) {
		case CAMERA_IN_USE:
		return "The camera device is in use already";

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

+33 −24

Original line number	Diff line number	Diff line
		@@ -16,6 +16,8 @@

		package android.hardware.camera2;

		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.os.Handler;
		import android.view.Surface;

		@@ -73,6 +75,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		/**
		* Get the camera device that this session is created for.
		*/
		@NonNull
		public abstract CameraDevice getDevice();

		/**
		@@ -133,7 +136,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		*
		* @see StateCallback#onSurfacePrepared
		*/
		public abstract void prepare(Surface surface) throws CameraAccessException;
		public abstract void prepare(@NonNull Surface surface) throws CameraAccessException;

		/**
		* <p>Submit a request for an image to be captured by the camera device.</p>
		@@ -194,7 +197,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #abortCaptures
		* @see CameraDevice#createReprocessableCaptureSession
		*/
		public abstract int capture(CaptureRequest request, CaptureCallback listener, Handler handler)
		public abstract int capture(@NonNull CaptureRequest request,
		@Nullable CaptureCallback listener, @Nullable Handler handler)
		throws CameraAccessException;

		/**
		@@ -252,8 +256,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #setRepeatingBurst
		* @see #abortCaptures
		*/
		public abstract int captureBurst(List<CaptureRequest> requests, CaptureCallback listener,
		Handler handler) throws CameraAccessException;
		public abstract int captureBurst(@NonNull List<CaptureRequest> requests,
		@Nullable CaptureCallback listener, @Nullable Handler handler)
		throws CameraAccessException;

		/**
		* Request endlessly repeating capture of images by this capture session.
		@@ -318,8 +323,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #stopRepeating
		* @see #abortCaptures
		*/
		public abstract int setRepeatingRequest(CaptureRequest request, CaptureCallback listener,
		Handler handler) throws CameraAccessException;
		public abstract int setRepeatingRequest(@NonNull CaptureRequest request,
		@Nullable CaptureCallback listener, @Nullable Handler handler)
		throws CameraAccessException;

		/**
		* <p>Request endlessly repeating capture of a sequence of images by this
		@@ -389,8 +395,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #stopRepeating
		* @see #abortCaptures
		*/
		public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureCallback listener,
		Handler handler) throws CameraAccessException;
		public abstract int setRepeatingBurst(@NonNull List<CaptureRequest> requests,
		@Nullable CaptureCallback listener, @Nullable Handler handler)
		throws CameraAccessException;

		/**
		* <p>Cancel any ongoing repeating capture set by either
		@@ -478,6 +485,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see android.media.ImageWriter
		* @see android.media.ImageReader
		*/
		@Nullable
		public abstract Surface getInputSurface();

		/**
		@@ -525,7 +533,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		*
		* @param session the session returned by {@link CameraDevice#createCaptureSession}
		*/
		public abstract void onConfigured(CameraCaptureSession session);
		public abstract void onConfigured(@NonNull CameraCaptureSession session);

		/**
		* This method is called if the session cannot be configured as requested.
		@@ -540,7 +548,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		*
		* @param session the session returned by {@link CameraDevice#createCaptureSession}
		*/
		public abstract void onConfigureFailed(CameraCaptureSession session);
		public abstract void onConfigureFailed(@NonNull CameraCaptureSession session);

		/**
		* This method is called every time the session has no more capture requests to process.
		@@ -555,7 +563,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @param session the session returned by {@link CameraDevice#createCaptureSession}
		*
		*/
		public void onReady(CameraCaptureSession session) {
		public void onReady(@NonNull CameraCaptureSession session) {
		// default empty implementation
		}

		@@ -571,7 +579,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		*
		* @param session the session returned by {@link CameraDevice#createCaptureSession}
		*/
		public void onActive(CameraCaptureSession session) {
		public void onActive(@NonNull CameraCaptureSession session) {
		// default empty implementation
		}

		@@ -589,7 +597,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		*
		* @param session the session returned by {@link CameraDevice#createCaptureSession}
		*/
		public void onClosed(CameraCaptureSession session) {
		public void onClosed(@NonNull CameraCaptureSession session) {
		// default empty implementation
		}

		@@ -608,7 +616,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @param session the session returned by {@link CameraDevice#createCaptureSession}
		* @param surface the Surface that was used with the {@link #prepare} call.
		*/
		public void onSurfacePrepared(CameraCaptureSession session, Surface surface) {
		public void onSurfacePrepared(@NonNull CameraCaptureSession session,
		@NonNull Surface surface) {
		// default empty implementation
		}
		}
		@@ -675,8 +684,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		*
		* @see android.media.MediaActionSound
		*/
		public void onCaptureStarted(CameraCaptureSession session,
		CaptureRequest request, long timestamp, long frameNumber) {
		public void onCaptureStarted(@NonNull CameraCaptureSession session,
		@NonNull CaptureRequest request, long timestamp, long frameNumber) {
		// Temporary trampoline for API change transition
		onCaptureStarted(session, request, timestamp);
		}
		@@ -756,8 +765,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #setRepeatingRequest
		* @see #setRepeatingBurst
		*/
		public void onCaptureProgressed(CameraCaptureSession session,
		CaptureRequest request, CaptureResult partialResult) {
		public void onCaptureProgressed(@NonNull CameraCaptureSession session,
		@NonNull CaptureRequest request, @NonNull CaptureResult partialResult) {
		// default empty implementation
		}

		@@ -785,8 +794,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #setRepeatingRequest
		* @see #setRepeatingBurst
		*/
		public void onCaptureCompleted(CameraCaptureSession session,
		CaptureRequest request, TotalCaptureResult result) {
		public void onCaptureCompleted(@NonNull CameraCaptureSession session,
		@NonNull CaptureRequest request, @NonNull TotalCaptureResult result) {
		// default empty implementation
		}

		@@ -814,8 +823,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #setRepeatingRequest
		* @see #setRepeatingBurst
		*/
		public void onCaptureFailed(CameraCaptureSession session,
		CaptureRequest request, CaptureFailure failure) {
		public void onCaptureFailed(@NonNull CameraCaptureSession session,
		@NonNull CaptureRequest request, @NonNull CaptureFailure failure) {
		// default empty implementation
		}

		@@ -844,7 +853,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see CaptureFailure#getSequenceId()
		* @see #onCaptureSequenceAborted
		*/
		public void onCaptureSequenceCompleted(CameraCaptureSession session,
		public void onCaptureSequenceCompleted(@NonNull CameraCaptureSession session,
		int sequenceId, long frameNumber) {
		// default empty implementation
		}
		@@ -873,7 +882,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see CaptureFailure#getSequenceId()
		* @see #onCaptureSequenceCompleted
		*/
		public void onCaptureSequenceAborted(CameraCaptureSession session,
		public void onCaptureSequenceAborted(@NonNull CameraCaptureSession session,
		int sequenceId) {
		// default empty implementation
		}

core/java/android/hardware/camera2/CameraCharacteristics.java

+7 −0

Original line number	Diff line number	Diff line
		@@ -16,6 +16,8 @@

		package android.hardware.camera2;

		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.hardware.camera2.impl.CameraMetadataNative;
		import android.hardware.camera2.impl.PublicKey;
		import android.hardware.camera2.impl.SyntheticKey;
		@@ -91,6 +93,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
		*
		* @return String representation of the key name
		*/
		@NonNull
		public String getName() {
		return mKey.getName();
		}
		@@ -166,6 +169,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
		* @param key The characteristics field to read.
		* @return The value of that key, or {@code null} if the field is not set.
		*/
		@Nullable
		public <T> T get(Key<T> key) {
		return mProperties.get(key);
		}
		@@ -194,6 +198,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
		/**
		* {@inheritDoc}
		*/
		@NonNull
		@Override
		public List<Key<?>> getKeys() {
		// List of keys is immutable; cache the results after we calculate them
		@@ -227,6 +232,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
		* @return List of keys supported by this CameraDevice for CaptureRequests.
		*/
		@SuppressWarnings({"unchecked"})
		@NonNull
		public List<CaptureRequest.Key<?>> getAvailableCaptureRequestKeys() {
		if (mAvailableRequestKeys == null) {
		Object crKey = CaptureRequest.Key.class;
		@@ -258,6 +264,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
		* @return List of keys supported by this CameraDevice for CaptureResults.
		*/
		@SuppressWarnings({"unchecked"})
		@NonNull
		public List<CaptureResult.Key<?>> getAvailableCaptureResultKeys() {
		if (mAvailableResultKeys == null) {
		Object crKey = CaptureResult.Key.class;

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

+44 −12

Original line number	Diff line number	Diff line
		@@ -16,6 +16,9 @@

		package android.hardware.camera2;

		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.annotation.IntDef;
		import android.hardware.camera2.params.InputConfiguration;
		import android.hardware.camera2.params.StreamConfigurationMap;
		import android.hardware.camera2.params.OutputConfiguration;
		@@ -23,6 +26,8 @@ import android.os.Handler;
		import android.view.Surface;

		import java.util.List;
		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* <p>The CameraDevice class is a representation of a single camera connected to an
		@@ -124,6 +129,17 @@ public abstract class CameraDevice implements AutoCloseable {
		*/
		public static final int TEMPLATE_MANUAL = 6;

		/** @hide */
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(
		{TEMPLATE_PREVIEW,
		TEMPLATE_STILL_CAPTURE,
		TEMPLATE_RECORD,
		TEMPLATE_VIDEO_SNAPSHOT,
		TEMPLATE_ZERO_SHUTTER_LAG,
		TEMPLATE_MANUAL })
		public @interface RequestTemplate {};

		/**
		* Get the ID of this camera device.
		*
		@@ -142,6 +158,7 @@ public abstract class CameraDevice implements AutoCloseable {
		* @see CameraManager#getCameraCharacteristics
		* @see CameraManager#getCameraIdList
		*/
		@NonNull
		public abstract String getId();

		/**
		@@ -391,8 +408,8 @@ public abstract class CameraDevice implements AutoCloseable {
		* @see StreamConfigurationMap#getOutputSizes(int)
		* @see StreamConfigurationMap#getOutputSizes(Class)
		*/
		public abstract void createCaptureSession(List<Surface> outputs,
		CameraCaptureSession.StateCallback callback, Handler handler)
		public abstract void createCaptureSession(@NonNull List<Surface> outputs,
		@NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)
		throws CameraAccessException;

		/**
		@@ -560,8 +577,9 @@ public abstract class CameraDevice implements AutoCloseable {
		* @see android.media.ImageWriter
		* @see android.media.ImageReader
		*/
		public abstract void createReprocessableCaptureSession(InputConfiguration inputConfig,
		List<Surface> outputs, CameraCaptureSession.StateCallback callback, Handler handler)
		public abstract void createReprocessableCaptureSession(@NonNull InputConfiguration inputConfig,
		@NonNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback,
		@Nullable Handler handler)
		throws CameraAccessException;

		/**
		@@ -591,7 +609,8 @@ public abstract class CameraDevice implements AutoCloseable {
		* @see #TEMPLATE_VIDEO_SNAPSHOT
		* @see #TEMPLATE_MANUAL
		*/
		public abstract CaptureRequest.Builder createCaptureRequest(int templateType)
		@NonNull
		public abstract CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType)
		throws CameraAccessException;

		/**
		@@ -620,8 +639,9 @@ public abstract class CameraDevice implements AutoCloseable {
		* @see CameraDevice#createReprocessableCaptureSession
		* @see android.media.ImageWriter
		*/
		@NonNull
		public abstract CaptureRequest.Builder createReprocessCaptureRequest(
		TotalCaptureResult inputResult) throws CameraAccessException;
		@NonNull TotalCaptureResult inputResult) throws CameraAccessException;

		/**
		* Close the connection to this camera device as quickly as possible.
		@@ -727,6 +747,16 @@ public abstract class CameraDevice implements AutoCloseable {
		*/
		public static final int ERROR_CAMERA_SERVICE = 5;

		/** @hide */
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(
		{ERROR_CAMERA_IN_USE,
		ERROR_MAX_CAMERAS_IN_USE,
		ERROR_CAMERA_DISABLED,
		ERROR_CAMERA_DEVICE,
		ERROR_CAMERA_SERVICE })
		public @interface ErrorCode {};

		/**
		* The method called when a camera device has finished opening.
		*
		@@ -736,7 +766,7 @@ public abstract class CameraDevice implements AutoCloseable {
		*
		* @param camera the camera device that has become opened
		*/
		public abstract void onOpened(CameraDevice camera); // Must implement
		public abstract void onOpened(@NonNull CameraDevice camera); // Must implement

		/**
		* The method called when a camera device has been closed with
		@@ -749,7 +779,7 @@ public abstract class CameraDevice implements AutoCloseable {
		*
		* @param camera the camera device that has become closed
		*/
		public void onClosed(CameraDevice camera) {
		public void onClosed(@NonNull CameraDevice camera) {
		// Default empty implementation
		}

		@@ -781,7 +811,7 @@ public abstract class CameraDevice implements AutoCloseable {
		*
		* @param camera the device that has been disconnected
		*/
		public abstract void onDisconnected(CameraDevice camera); // Must implement
		public abstract void onDisconnected(@NonNull CameraDevice camera); // Must implement

		/**
		* The method called when a camera device has encountered a serious error.
		@@ -805,12 +835,14 @@ public abstract class CameraDevice implements AutoCloseable {
		* @param error The error code, one of the
		* {@code StateCallback.ERROR_*} values.
		*
		* @see #ERROR_CAMERA_IN_USE
		* @see #ERROR_MAX_CAMERAS_IN_USE
		* @see #ERROR_CAMERA_DISABLED
		* @see #ERROR_CAMERA_DEVICE
		* @see #ERROR_CAMERA_SERVICE
		* @see #ERROR_CAMERA_DISABLED
		* @see #ERROR_CAMERA_IN_USE
		*/
		public abstract void onError(CameraDevice camera, int error); // Must implement
		public abstract void onError(@NonNull CameraDevice camera,
		@ErrorCode int error); // Must implement
		}

		/**

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

+22 −17

Original line number	Diff line number	Diff line
		@@ -16,6 +16,9 @@

		package android.hardware.camera2;

		import android.annotation.RequiresPermission;
		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.content.Context;
		import android.hardware.ICameraService;
		import android.hardware.ICameraServiceListener;
		@@ -86,6 +89,7 @@ public final class CameraManager {
		*
		* @return The list of currently connected camera devices.
		*/
		@NonNull
		public String[] getCameraIdList() throws CameraAccessException {
		synchronized (mLock) {
		// ID list creation handles various known failures in device enumeration, so only
		@@ -121,7 +125,8 @@ public final class CameraManager {
		* @throws IllegalArgumentException if the handler is {@code null} but the current thread has
		* no looper.
		*/
		public void registerAvailabilityCallback(AvailabilityCallback callback, Handler handler) {
		public void registerAvailabilityCallback(@NonNull AvailabilityCallback callback,
		@Nullable Handler handler) {
		if (handler == null) {
		Looper looper = Looper.myLooper();
		if (looper == null) {
		@@ -142,7 +147,7 @@ public final class CameraManager {
		*
		* @param callback The callback to remove from the notification list
		*/
		public void unregisterAvailabilityCallback(AvailabilityCallback callback) {
		public void unregisterAvailabilityCallback(@NonNull AvailabilityCallback callback) {
		CameraManagerGlobal.get().unregisterAvailabilityCallback(callback);
		}

		@@ -168,7 +173,7 @@ public final class CameraManager {
		* @throws IllegalArgumentException if the handler is {@code null} but the current thread has
		* no looper.
		*/
		public void registerTorchCallback(TorchCallback callback, Handler handler) {
		public void registerTorchCallback(@NonNull TorchCallback callback, @Nullable Handler handler) {
		if (handler == null) {
		Looper looper = Looper.myLooper();
		if (looper == null) {
		@@ -188,7 +193,7 @@ public final class CameraManager {
		*
		* @param callback The callback to remove from the notification list
		*/
		public void unregisterTorchCallback(TorchCallback callback) {
		public void unregisterTorchCallback(@NonNull TorchCallback callback) {
		CameraManagerGlobal.get().unregisterTorchCallback(callback);
		}

		@@ -201,15 +206,13 @@ public final class CameraManager {
		*
		* @throws IllegalArgumentException if the cameraId does not match any
		* known camera device.
		* @throws CameraAccessException if the camera is disabled by device policy, or
		* the camera device has been disconnected.
		* @throws SecurityException if the application does not have permission to
		* access the camera
		* @throws CameraAccessException if the camera device has been disconnected.
		*
		* @see #getCameraIdList
		* @see android.app.admin.DevicePolicyManager#setCameraDisabled
		*/
		public CameraCharacteristics getCameraCharacteristics(String cameraId)
		@NonNull
		public CameraCharacteristics getCameraCharacteristics(@NonNull String cameraId)
		throws CameraAccessException {
		CameraCharacteristics characteristics = null;

		@@ -431,8 +434,9 @@ public final class CameraManager {
		* @see #getCameraIdList
		* @see android.app.admin.DevicePolicyManager#setCameraDisabled
		*/
		public void openCamera(String cameraId, final CameraDevice.StateCallback callback,
		Handler handler)
		@RequiresPermission(android.Manifest.permission.CAMERA)
		public void openCamera(@NonNull String cameraId,
		@NonNull final CameraDevice.StateCallback callback, @Nullable Handler handler)
		throws CameraAccessException {

		if (cameraId == null) {
		@@ -444,7 +448,7 @@ public final class CameraManager {
		handler = new Handler();
		} else {
		throw new IllegalArgumentException(
		"Looper doesn't exist in the calling thread");
		"Handler argument is null, but no looper exists in the calling thread");
		}
		}

		@@ -490,7 +494,8 @@ public final class CameraManager {
		* or previously available camera device, or the camera device doesn't have a
		* flash unit.
		*/
		public void setTorchMode(String cameraId, boolean enabled) throws CameraAccessException {
		public void setTorchMode(@NonNull String cameraId, boolean enabled)
		throws CameraAccessException {
		CameraManagerGlobal.get().setTorchMode(cameraId, enabled);
		}

		@@ -517,7 +522,7 @@ public final class CameraManager {
		*
		* @param cameraId The unique identifier of the new camera.
		*/
		public void onCameraAvailable(String cameraId) {
		public void onCameraAvailable(@NonNull String cameraId) {
		// default empty implementation
		}

		@@ -532,7 +537,7 @@ public final class CameraManager {
		*
		* @param cameraId The unique identifier of the disconnected camera.
		*/
		public void onCameraUnavailable(String cameraId) {
		public void onCameraUnavailable(@NonNull String cameraId) {
		// default empty implementation
		}
		}
		@@ -572,7 +577,7 @@ public final class CameraManager {
		* @param cameraId The unique identifier of the camera whose torch mode has become
		* unavailable.
		*/
		public void onTorchModeUnavailable(String cameraId) {
		public void onTorchModeUnavailable(@NonNull String cameraId) {
		// default empty implementation
		}

		@@ -589,7 +594,7 @@ public final class CameraManager {
		* off. {@code false} when the torch mode has becomes off and available to
		* be turned on.
		*/
		public void onTorchModeChanged(String cameraId, boolean enabled) {
		public void onTorchModeChanged(@NonNull String cameraId, boolean enabled) {
		// default empty implementation
		}
		}