Merge "camera2: Add capture sequences and capture failures" into klp-dev (ca833c38) · Commits · e / os / android_frameworks_base

api/current.txt

+19 −5

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

+47 −8

Original line number	Original line	Diff line number	Diff line
	@@ -305,6 +305,9 @@ public interface CameraDevice extends AutoCloseable {
	* {@code null} to use the current thread's {@link android.os.Looper		* {@code null} to use the current thread's {@link android.os.Looper
	* looper}.		* looper}.
	*		*
			* @return int A unique capture sequence ID used by
			* {@link CaptureListener#onCaptureSequenceCompleted}.
			*
	* @throws CameraAccessException if the camera device is no longer connected or has		* @throws CameraAccessException if the camera device is no longer connected or has
	* encountered a fatal error		* encountered a fatal error
	* @throws IllegalStateException if the camera is currently busy or unconfigured,		* @throws IllegalStateException if the camera is currently busy or unconfigured,
	@@ -317,7 +320,7 @@ public interface CameraDevice extends AutoCloseable {
	* @see #setRepeatingRequest		* @see #setRepeatingRequest
	* @see #setRepeatingBurst		* @see #setRepeatingBurst
	*/		*/
	public void capture(CaptureRequest request, CaptureListener listener, Handler handler)		public int capture(CaptureRequest request, CaptureListener listener, Handler handler)
	throws CameraAccessException;		throws CameraAccessException;

	/**		/**
	@@ -346,6 +349,9 @@ public interface CameraDevice extends AutoCloseable {
	* {@code null} to use the current thread's {@link android.os.Looper		* {@code null} to use the current thread's {@link android.os.Looper
	* looper}.		* looper}.
	*		*
			* @return int A unique capture sequence ID used by
			* {@link CaptureListener#onCaptureSequenceCompleted}.
			*
	* @throws CameraAccessException if the camera device is no longer connected or has		* @throws CameraAccessException if the camera device is no longer connected or has
	* encountered a fatal error		* encountered a fatal error
	* @throws IllegalStateException if the camera is currently busy or unconfigured,		* @throws IllegalStateException if the camera is currently busy or unconfigured,
	@@ -358,7 +364,7 @@ public interface CameraDevice extends AutoCloseable {
	* @see #setRepeatingRequest		* @see #setRepeatingRequest
	* @see #setRepeatingBurst		* @see #setRepeatingBurst
	*/		*/
	public void captureBurst(List<CaptureRequest> requests, CaptureListener listener,		public int captureBurst(List<CaptureRequest> requests, CaptureListener listener,
	Handler handler) throws CameraAccessException;		Handler handler) throws CameraAccessException;

	/**		/**
	@@ -399,6 +405,9 @@ public interface CameraDevice extends AutoCloseable {
	* {@code null} to use the current thread's {@link android.os.Looper		* {@code null} to use the current thread's {@link android.os.Looper
	* looper}.		* looper}.
	*		*
			* @return int A unique capture sequence ID used by
			* {@link CaptureListener#onCaptureSequenceCompleted}.
			*
	* @throws CameraAccessException if the camera device is no longer connected or has		* @throws CameraAccessException if the camera device is no longer connected or has
	* encountered a fatal error		* encountered a fatal error
	* @throws IllegalStateException if the camera is currently busy or unconfigured,		* @throws IllegalStateException if the camera is currently busy or unconfigured,
	@@ -413,7 +422,7 @@ public interface CameraDevice extends AutoCloseable {
	* @see #stopRepeating		* @see #stopRepeating
	* @see #flush		* @see #flush
	*/		*/
	public void setRepeatingRequest(CaptureRequest request, CaptureListener listener,		public int setRepeatingRequest(CaptureRequest request, CaptureListener listener,
	Handler handler) throws CameraAccessException;		Handler handler) throws CameraAccessException;

	/**		/**
	@@ -454,6 +463,9 @@ public interface CameraDevice extends AutoCloseable {
	* {@code null} to use the current thread's {@link android.os.Looper		* {@code null} to use the current thread's {@link android.os.Looper
	* looper}.		* looper}.
	*		*
			* @return int A unique capture sequence ID used by
			* {@link CaptureListener#onCaptureSequenceCompleted}.
			*
	* @throws CameraAccessException if the camera device is no longer connected or has		* @throws CameraAccessException if the camera device is no longer connected or has
	* encountered a fatal error		* encountered a fatal error
	* @throws IllegalStateException if the camera is currently busy or unconfigured,		* @throws IllegalStateException if the camera is currently busy or unconfigured,
	@@ -468,7 +480,7 @@ public interface CameraDevice extends AutoCloseable {
	* @see #stopRepeating		* @see #stopRepeating
	* @see #flush		* @see #flush
	*/		*/
	public void setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener,		public int setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener,
	Handler handler) throws CameraAccessException;		Handler handler) throws CameraAccessException;

	/**		/**
	@@ -601,7 +613,6 @@ public interface CameraDevice extends AutoCloseable {
	* @see #captureBurst		* @see #captureBurst
	* @see #setRepeatingRequest		* @see #setRepeatingRequest
	* @see #setRepeatingBurst		* @see #setRepeatingBurst
	*
	*/		*/
	public static abstract class CaptureListener {		public static abstract class CaptureListener {

	@@ -672,8 +683,13 @@ public interface CameraDevice extends AutoCloseable {
	*		*
	* <p>The default implementation of this method does nothing.</p>		* <p>The default implementation of this method does nothing.</p>
	*		*
	* @param camera The CameraDevice sending the callback.		* @param camera
	* @param request The request that was given to the CameraDevice		* The CameraDevice sending the callback.
			* @param request
			* The request that was given to the CameraDevice
			* @param failure
			* The output failure from the capture, including the failure reason
			* and the frame number.
	*		*
	* @see #capture		* @see #capture
	* @see #captureBurst		* @see #captureBurst
	@@ -681,7 +697,30 @@ public interface CameraDevice extends AutoCloseable {
	* @see #setRepeatingBurst		* @see #setRepeatingBurst
	*/		*/
	public void onCaptureFailed(CameraDevice camera,		public void onCaptureFailed(CameraDevice camera,
	CaptureRequest request) {		CaptureRequest request, CaptureFailure failure) {
			// default empty implementation
			}

			/**
			* This method is called independently of the others in CaptureListener,
			* when a capture sequence finishes and all {@link CaptureResult}
			* or {@link CaptureFailure} for it have been returned via this listener.
			*
			* @param camera
			* The CameraDevice sending the callback.
			* @param sequenceId
			* A sequence ID returned by the {@link #capture} family of functions.
			* @param frameNumber
			* The last frame number (returned by {@link CaptureResult#getFrameNumber}
			* or {@link CaptureFailure#getFrameNumber}) in the capture sequence.
			*
			* @see CaptureResult#getFrameNumber()
			* @see CaptureFailure#getFrameNumber()
			* @see CaptureResult#getSequenceId()
			* @see CaptureFailure#getSequenceId()
			*/
			public void onCaptureSequenceCompleted(CameraDevice camera,
			int sequenceId, int frameNumber) {
	// default empty implementation		// default empty implementation
	}		}
	}		}

core/java/android/hardware/camera2/CaptureFailure.java

0 → 100644

+144 −0

Original line number	Original line	Diff line number	Diff line
			/*
			* Copyright (C) 2013 The Android Open Source Project
			*
			* Licensed under the Apache License, Version 2.0 (the "License");
			* you may not use this file except in compliance with the License.
			* You may obtain a copy of the License at
			*
			* http://www.apache.org/licenses/LICENSE-2.0
			*
			* Unless required by applicable law or agreed to in writing, software
			* distributed under the License is distributed on an "AS IS" BASIS,
			* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
			* See the License for the specific language governing permissions and
			* limitations under the License.
			*/
			package android.hardware.camera2;

			import android.hardware.camera2.CameraDevice.CaptureListener;

			/**
			* A report of failed capture for a single image capture from the image sensor.
			*
			* <p>CaptureFailures are produced by a {@link CameraDevice} if processing a
			* {@link CaptureRequest} fails, either partially or fully. Use {@link #getReason}
			* to determine the specific nature of the failed capture.</p>
			*
			* <p>Receiving a CaptureFailure means that the metadata associated with that frame number
			* has been dropped -- no {@link CaptureResult} with the same frame number will be
			* produced.</p>
			*/
			public class CaptureFailure {
			/**
			* The {@link CaptureResult} has been dropped this frame only due to an error
			* in the framework.
			*
			* @see #getReason()
			*/
			public static final int REASON_ERROR = 0;

			/**
			* The capture has failed due to a {@link CameraDevice#flush} call from the application.
			*
			* @see #getReason()
			*/
			public static final int REASON_FLUSHED = 1;

			private final CaptureRequest mRequest;
			private final int mReason;
			private final boolean mDropped;
			private final int mSequenceId;
			private final int mFrameNumber;

			/**
			* @hide
			*/
			public CaptureFailure(CaptureRequest request, int reason, boolean dropped, int sequenceId,
			int frameNumber) {
			mRequest = request;
			mReason = reason;
			mDropped = dropped;
			mSequenceId = sequenceId;
			mFrameNumber = frameNumber;
			}

			/**
			* Get the request associated with this failed capture.
			*
			* <p>Whenever a request is unsuccessfully captured, with
			* {@link CameraDevice.CaptureListener#onCaptureFailed},
			* the {@code failed capture}'s {@code getRequest()} will return that {@code request}.
			* </p>
			*
			* <p>In particular,
			* <code><pre>cameraDevice.capture(someRequest, new CaptureListener() {
			* {@literal @}Override
			* void onCaptureFailed(CaptureRequest myRequest, CaptureFailure myFailure) {
			* assert(myFailure.getRequest.equals(myRequest) == true);
			* }
			* };
			* </code></pre>
			* </p>
			*
			* @return The request associated with this failed capture. Never {@code null}.
			*/
			public CaptureRequest getRequest() {
			return mRequest;
			}

			/**
			* Get the frame number associated with this failed capture.
			*
			* <p>Whenever a request has been processed, regardless of failed capture or success,
			* it gets a unique frame number assigned to its future result/failed capture.</p>
			*
			* <p>This value monotonically increments, starting with 0,
			* for every new result or failure; and the scope is the lifetime of the
			* {@link CameraDevice}.</p>
			*
			* @return int frame number
			*/
			public int getFrameNumber() {
			return mFrameNumber;
			}

			/**
			* Determine why the request was dropped, whether due to an error or to a user
			* action.
			*
			* @return int One of {@code REASON_*} integer constants.
			*
			* @see #REASON_ERROR
			* @see #REASON_FLUSHED
			*/
			public int getReason() {
			return mReason;
			}

			/**
			* Determine if the image was captured from the camera.
			*
			* <p>If the image was not captured, no image buffers will be available.
			* If the image was captured, then image buffers may be available.</p>
			*
			* @return boolean True if the image was captured, false otherwise.
			*/
			public boolean wasImageCaptured() {
			return !mDropped;
			}

			/**
			* The sequence ID for this failed capture that was returned by the
			* {@link CameraDevice#capture} family of functions.
			*
			* <p>The sequence ID is a unique monotonically increasing value starting from 0,
			* incremented every time a new group of requests is submitted to the CameraDevice.</p>
			*
			* @return int The ID for the sequence of requests that this capture failure is the result of
			*
			* @see CameraDevice.CaptureListener#onCaptureSequenceCompleted
			*/
			public int getSequenceId() {
			return mSequenceId;
			}
			}

core/java/android/hardware/camera2/CaptureRequest.java

+42 −5

Original line number	Original line	Diff line number	Diff line
	@@ -17,11 +17,13 @@
	package android.hardware.camera2;		package android.hardware.camera2;

	import android.hardware.camera2.impl.CameraMetadataNative;		import android.hardware.camera2.impl.CameraMetadataNative;
			import android.hardware.camera2.CameraDevice.CaptureListener;
	import android.os.Parcel;		import android.os.Parcel;
	import android.os.Parcelable;		import android.os.Parcelable;
	import android.view.Surface;		import android.view.Surface;

	import java.util.HashSet;		import java.util.HashSet;
			import java.util.Objects;


	/**		/**
	@@ -62,30 +64,37 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
	private Object mUserTag;		private Object mUserTag;

	/**		/**
	* Construct empty request		* Construct empty request.
	* @hide		*
			* Used by Binder to unparcel this object only.
	*/		*/
	public CaptureRequest() {		private CaptureRequest() {
	mSettings = new CameraMetadataNative();		mSettings = new CameraMetadataNative();
	mSurfaceSet = new HashSet<Surface>();		mSurfaceSet = new HashSet<Surface>();
	}		}

	/**		/**
	* Clone from source capture request		* Clone from source capture request.
			*
			* Used by the Builder to create an immutable copy.
	*/		*/
			@SuppressWarnings("unchecked")
	private CaptureRequest(CaptureRequest source) {		private CaptureRequest(CaptureRequest source) {
	mSettings = new CameraMetadataNative(source.mSettings);		mSettings = new CameraMetadataNative(source.mSettings);
	mSurfaceSet = (HashSet<Surface>) source.mSurfaceSet.clone();		mSurfaceSet = (HashSet<Surface>) source.mSurfaceSet.clone();
	}		}

	/**		/**
	* Take ownership of passed-in settings		* Take ownership of passed-in settings.
			*
			* Used by the Builder to create a mutable CaptureRequest.
	*/		*/
	private CaptureRequest(CameraMetadataNative settings) {		private CaptureRequest(CameraMetadataNative settings) {
	mSettings = settings;		mSettings = settings;
	mSurfaceSet = new HashSet<Surface>();		mSurfaceSet = new HashSet<Surface>();
	}		}

			@SuppressWarnings("unchecked")
	@Override		@Override
	public <T> T get(Key<T> key) {		public <T> T get(Key<T> key) {
	return mSettings.get(key);		return mSettings.get(key);
	@@ -108,6 +117,34 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
	return mUserTag;		return mUserTag;
	}		}

			/**
			* Determine whether this CaptureRequest is equal to another CaptureRequest.
			*
			* <p>A request is considered equal to another is if it's set of key/values is equal, it's
			* list of output surfaces is equal, and the user tag is equal.</p>
			*
			* @param other Another instance of CaptureRequest.
			*
			* @return True if the requests are the same, false otherwise.
			*/
			@Override
			public boolean equals(Object other) {
			return other instanceof CaptureRequest
			&& equals((CaptureRequest)other);
			}

			private boolean equals(CaptureRequest other) {
			return other != null
			&& Objects.equals(mUserTag, other.mUserTag)
			&& mSurfaceSet.equals(other.mSurfaceSet)
			&& mSettings.equals(other.mSettings);
			}

			@Override
			public int hashCode() {
			return mSettings.hashCode();
			}

	public static final Parcelable.Creator<CaptureRequest> CREATOR =		public static final Parcelable.Creator<CaptureRequest> CREATOR =
	new Parcelable.Creator<CaptureRequest>() {		new Parcelable.Creator<CaptureRequest>() {
	@Override		@Override

core/java/android/hardware/camera2/CaptureResult.java

+71 −3

Original line number	Original line	Diff line number	Diff line
	@@ -37,13 +37,25 @@ import android.hardware.camera2.impl.CameraMetadataNative;
	public final class CaptureResult extends CameraMetadata {		public final class CaptureResult extends CameraMetadata {

	private final CameraMetadataNative mResults;		private final CameraMetadataNative mResults;
			private final CaptureRequest mRequest;
			private final int mSequenceId;

	/**		/**
	* Takes ownership of the passed-in properties object		* Takes ownership of the passed-in properties object
	* @hide		* @hide
	*/		*/
	public CaptureResult(CameraMetadataNative results) {		public CaptureResult(CameraMetadataNative results, CaptureRequest parent, int sequenceId) {
			if (results == null) {
			throw new IllegalArgumentException("results was null");
			}

			if (parent == null) {
			throw new IllegalArgumentException("parent was null");
			}

	mResults = results;		mResults = results;
			mRequest = parent;
			mSequenceId = sequenceId;
	}		}

	@Override		@Override
	@@ -51,6 +63,61 @@ public final class CaptureResult extends CameraMetadata {
	return mResults.get(key);		return mResults.get(key);
	}		}

			/**
			* Get the request associated with this result.
			*
			* <p>Whenever a request is successfully captured, with
			* {@link CameraDevice.CaptureListener#onCaptureCompleted},
			* the {@code result}'s {@code getRequest()} will return that {@code request}.
			* </p>
			*
			* <p>In particular,
			* <code><pre>cameraDevice.capture(someRequest, new CaptureListener() {
			* {@literal @}Override
			* void onCaptureCompleted(CaptureRequest myRequest, CaptureResult myResult) {
			* assert(myResult.getRequest.equals(myRequest) == true);
			* }
			* };
			* </code></pre>
			* </p>
			*
			* @return The request associated with this result. Never {@code null}.
			*/
			public CaptureRequest getRequest() {
			return mRequest;
			}

			/**
			* Get the frame number associated with this result.
			*
			* <p>Whenever a request has been processed, regardless of failure or success,
			* it gets a unique frame number assigned to its future result/failure.</p>
			*
			* <p>This value monotonically increments, starting with 0,
			* for every new result or failure; and the scope is the lifetime of the
			* {@link CameraDevice}.</p>
			*
			* @return int frame number
			*/
			public int getFrameNumber() {
			return get(REQUEST_FRAME_COUNT);
			}

			/**
			* The sequence ID for this failure that was returned by the
			* {@link CameraDevice#capture} family of functions.
			*
			* <p>The sequence ID is a unique monotonically increasing value starting from 0,
			* incremented every time a new group of requests is submitted to the CameraDevice.</p>
			*
			* @return int The ID for the sequence of requests that this capture result is a part of
			*
			* @see CameraDevice.CaptureListener#onCaptureSequenceCompleted
			*/
			public int getSequenceId() {
			return mSequenceId;
			}

	/*@O~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~		/*@O~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
	* The key entries below this point are generated from metadata		* The key entries below this point are generated from metadata
	* definitions in /system/media/camera/docs. Do not modify by hand or		* definitions in /system/media/camera/docs. Do not modify by hand or
	@@ -523,8 +590,9 @@ public final class CaptureResult extends CameraMetadata {

	/**		/**
	* <p>		* <p>
	* Number of frames captured since		* A frame counter set by the framework. This value monotonically
	* open()		* increases with every new result (that is, each new result has a unique
			* frameCount value).
	* </p>		* </p>
	* <p>		* <p>
	* Reset on release()		* Reset on release()