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

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

Camera2: Add SDK annotations 

- Annotate everything with @NonNull, @Nullable
- Annotate a few @IntRange
- Annotate a few @IntDef
  - Most metadata enums probably canont be annotated usefully,
    since get/set() are generic and the annotation system
    can't yet manage that.
  - Plus metadata annotations need to be auto-generated anyway
- Also add explicit null check to prepare's surface argument
- Also update docs of getCameraCharacteristics to match reality

Bug: 21029463
Change-Id: Ifd81b2a782e29ad069fe25c7db4a1fda73dabcd7
parent 9939961d

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

        }

    }