Merge "camera2: Add partial results to the capture listener (API change)" into lmp-preview-dev (79458826) · Commits · e / os / android_frameworks_base

api/current.txt

+13 −5

Original line number	Diff line number	Diff line
		@@ -12138,9 +12138,11 @@ package android.hardware.camera2 {

		public static abstract class CameraCaptureSession.CaptureListener {
		ctor public CameraCaptureSession.CaptureListener();
		method public void onCaptureCompleted(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureResult);
		method public void onCaptureCompleted(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.TotalCaptureResult);
		method public void onCaptureFailed(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureFailure);
		method public void onCaptureSequenceCompleted(android.hardware.camera2.CameraDevice, int, int);
		method public void onCaptureProgressed(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureResult);
		method public void onCaptureSequenceAborted(android.hardware.camera2.CameraDevice, int);
		method public void onCaptureSequenceCompleted(android.hardware.camera2.CameraDevice, int, long);
		method public void onCaptureStarted(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, long);
		}

		@@ -12247,9 +12249,11 @@ package android.hardware.camera2 {

		public static abstract deprecated class CameraDevice.CaptureListener {
		ctor public CameraDevice.CaptureListener();
		method public void onCaptureCompleted(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureResult);
		method public void onCaptureCompleted(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.TotalCaptureResult);
		method public void onCaptureFailed(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureFailure);
		method public void onCaptureSequenceCompleted(android.hardware.camera2.CameraDevice, int, int);
		method public void onCaptureProgressed(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureResult);
		method public void onCaptureSequenceAborted(android.hardware.camera2.CameraDevice, int);
		method public void onCaptureSequenceCompleted(android.hardware.camera2.CameraDevice, int, long);
		method public void onCaptureStarted(android.hardware.camera2.CameraDevice, android.hardware.camera2.CaptureRequest, long);
		}

		@@ -12540,7 +12544,7 @@ package android.hardware.camera2 {
		method public final int hashCode();
		}

		public final class CaptureResult extends android.hardware.camera2.CameraMetadata {
		public class CaptureResult extends android.hardware.camera2.CameraMetadata {
		method public T get(android.hardware.camera2.CaptureResult.Key<T>);
		method public int getFrameNumber();
		method public android.hardware.camera2.CaptureRequest getRequest();
		@@ -12633,6 +12637,10 @@ package android.hardware.camera2 {
		method public void writeInputStream(java.io.OutputStream, android.util.Size, java.io.InputStream, long) throws java.io.IOException;
		}

		public final class TotalCaptureResult extends android.hardware.camera2.CaptureResult {
		method public java.util.List<android.hardware.camera2.CaptureResult> getPartialResults();
		}

		}

		package android.hardware.camera2.params {

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

+89 −8

Original line number	Diff line number	Diff line
		@@ -508,14 +508,62 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		}

		/**
		* This method is called when an image capture has completed and the
		* This method is called when an image capture makes partial forward progress; some
		* (but not all) results from an image capture are available.
		*
		* <p>The result provided here will contain some subset of the fields of
		* a full result. Multiple {@link #onCaptureProgressed} calls may happen per
		* capture; a given result field will only be present in one partial
		* capture at most. The final {@link #onCaptureCompleted} call will always
		* contain all the fields (in particular, the union of all the fields of all
		* the partial results composing the total result).</p>
		*
		* <p>For each request, some result data might be available earlier than others. The typical
		* delay between each partial result (per request) is a single frame interval.
		* For performance-oriented use-cases, applications should query the metadata they need
		* to make forward progress from the partial results and avoid waiting for the completed
		* result.</p>
		*
		* <p>Each request will generate at least {@code 1} partial results, and at most
		* {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT} partial results.</p>
		*
		* <p>Depending on the request settings, the number of partial results per request
		* will vary, although typically the partial count could be the same as long as the
		* camera device subsystems enabled stay the same.</p>
		*
		* <p>The default implementation of this method does nothing.</p>
		*
		* @param camera The CameraDevice sending the callback.
		* @param request The request that was given to the CameraDevice
		* @param partialResult The partial output metadata from the capture, which
		* includes a subset of the {@link TotalCaptureResult} fields.
		*
		* @see #capture
		* @see #captureBurst
		* @see #setRepeatingRequest
		* @see #setRepeatingBurst
		*/
		public void onCaptureProgressed(CameraDevice camera,
		CaptureRequest request, CaptureResult partialResult) {
		// default empty implementation
		}

		/**
		* This method is called when an image capture has fully completed and all the
		* result metadata is available.
		*
		* <p>This callback will always fire after the last {@link #onCaptureProgressed};
		* in other words, no more partial results will be delivered once the completed result
		* is available.</p>
		*
		* <p>For performance-intensive use-cases where latency is a factor, consider
		* using {@link #onCaptureProgressed} instead.</p>
		*
		* <p>The default implementation of this method does nothing.</p>
		*
		* @param camera The CameraDevice sending the callback.
		* @param request The request that was given to the CameraDevice
		* @param result The output metadata from the capture, including the
		* @param result The total output metadata from the capture, including the
		* final capture parameters and the state of the camera system during
		* capture.
		*
		@@ -525,7 +573,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* @see #setRepeatingBurst
		*/
		public void onCaptureCompleted(CameraDevice camera,
		CaptureRequest request, CaptureResult result) {
		CaptureRequest request, TotalCaptureResult result) {
		// default empty implementation
		}

		@@ -563,24 +611,57 @@ public abstract class CameraCaptureSession implements AutoCloseable {
		* when a capture sequence finishes and all {@link CaptureResult}
		* or {@link CaptureFailure} for it have been returned via this listener.
		*
		* <p>In total, there will be at least one result/failure returned by this listener
		* before this callback is invoked. If the capture sequence is aborted before any
		* requests have been processed, {@link #onCaptureSequenceAborted} is invoked instead.</p>
		*
		* <p>The default implementation does nothing.</p>
		*
		* @param camera
		* The CameraDevice sending the callback.
		* @param sequenceId
		* A sequence ID returned by the {@link #capture} family of functions.
		* @param lastFrameNumber
		* @param frameNumber
		* The last frame number (returned by {@link CaptureResult#getFrameNumber}
		* or {@link CaptureFailure#getFrameNumber}) in the capture sequence.
		* The last frame number may be equal to NO_FRAMES_CAPTURED if no images
		* were captured for this sequence. This can happen, for example, when a
		* repeating request or burst is cleared right after being set.
		*
		* @see CaptureResult#getFrameNumber()
		* @see CaptureFailure#getFrameNumber()
		* @see CaptureResult#getSequenceId()
		* @see CaptureFailure#getSequenceId()
		* @see #onCaptureSequenceAborted
		*/
		public void onCaptureSequenceCompleted(CameraDevice camera,
		int sequenceId, int lastFrameNumber) {
		int sequenceId, long frameNumber) {
		// default empty implementation
		}

		/**
		* This method is called independently of the others in CaptureListener,
		* when a capture sequence aborts before any {@link CaptureResult}
		* or {@link CaptureFailure} for it have been returned via this listener.
		*
		* <p>Due to the asynchronous nature of the camera device, not all submitted captures
		* are immediately processed. It is possible to clear out the pending requests
		* by a variety of operations such as {@link CameraDevice#stopRepeating} or
		* {@link CameraDevice#flush}. When such an event happens,
		* {@link #onCaptureSequenceCompleted} will not be called.</p>
		*
		* <p>The default implementation does nothing.</p>
		*
		* @param camera
		* The CameraDevice sending the callback.
		* @param sequenceId
		* A sequence ID returned by the {@link #capture} family of functions.
		*
		* @see CaptureResult#getFrameNumber()
		* @see CaptureFailure#getFrameNumber()
		* @see CaptureResult#getSequenceId()
		* @see CaptureFailure#getSequenceId()
		* @see #onCaptureSequenceCompleted
		*/
		public void onCaptureSequenceAborted(CameraDevice camera,
		int sequenceId) {
		// default empty implementation
		}
		}

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

+93 −8

Original line number	Diff line number	Diff line
		@@ -766,14 +766,62 @@ public interface CameraDevice extends AutoCloseable {
		}

		/**
		* This method is called when an image capture has completed and the
		* This method is called when an image capture makes partial forward progress; some
		* (but not all) results from an image capture are available.
		*
		* <p>The result provided here will contain some subset of the fields of
		* a full result. Multiple {@link #onCaptureProgressed} calls may happen per
		* capture; a given result field will only be present in one partial
		* capture at most. The final {@link #onCaptureCompleted} call will always
		* contain all the fields (in particular, the union of all the fields of all
		* the partial results composing the total result).</p>
		*
		* <p>For each request, some result data might be available earlier than others. The typical
		* delay between each partial result (per request) is a single frame interval.
		* For performance-oriented use-cases, applications should query the metadata they need
		* to make forward progress from the partial results and avoid waiting for the completed
		* result.</p>
		*
		* <p>Each request will generate at least {@code 1} partial results, and at most
		* {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT} partial results.</p>
		*
		* <p>Depending on the request settings, the number of partial results per request
		* will vary, although typically the partial count could be the same as long as the
		* camera device subsystems enabled stay the same.</p>
		*
		* <p>The default implementation of this method does nothing.</p>
		*
		* @param camera The CameraDevice sending the callback.
		* @param request The request that was given to the CameraDevice
		* @param partialResult The partial output metadata from the capture, which
		* includes a subset of the {@link TotalCaptureResult} fields.
		*
		* @see #capture
		* @see #captureBurst
		* @see #setRepeatingRequest
		* @see #setRepeatingBurst
		*/
		public void onCaptureProgressed(CameraDevice camera,
		CaptureRequest request, CaptureResult partialResult) {
		// default empty implementation
		}

		/**
		* This method is called when an image capture has fully completed and all the
		* result metadata is available.
		*
		* <p>This callback will always fire after the last {@link #onCaptureProgressed};
		* in other words, no more partial results will be delivered once the completed result
		* is available.</p>
		*
		* <p>For performance-intensive use-cases where latency is a factor, consider
		* using {@link #onCaptureProgressed} instead.</p>
		*
		* <p>The default implementation of this method does nothing.</p>
		*
		* @param camera The CameraDevice sending the callback.
		* @param request The request that was given to the CameraDevice
		* @param result The output metadata from the capture, including the
		* @param result The total output metadata from the capture, including the
		* final capture parameters and the state of the camera system during
		* capture.
		*
		@@ -783,7 +831,7 @@ public interface CameraDevice extends AutoCloseable {
		* @see #setRepeatingBurst
		*/
		public void onCaptureCompleted(CameraDevice camera,
		CaptureRequest request, CaptureResult result) {
		CaptureRequest request, TotalCaptureResult result) {
		// default empty implementation
		}

		@@ -796,6 +844,10 @@ public interface CameraDevice extends AutoCloseable {
		* the capture may have been pushed to their respective output
		* streams.</p>
		*
		* <p>Some partial results may have been delivered before the capture fails;
		* however after this callback fires, no more partial results will be delivered by
		* {@link #onCaptureProgressed}.</p>
		*
		* <p>The default implementation of this method does nothing.</p>
		*
		* @param camera
		@@ -821,24 +873,57 @@ public interface CameraDevice extends AutoCloseable {
		* when a capture sequence finishes and all {@link CaptureResult}
		* or {@link CaptureFailure} for it have been returned via this listener.
		*
		* <p>In total, there will be at least one result/failure returned by this listener
		* before this callback is invoked. If the capture sequence is aborted before any
		* requests have been processed, {@link #onCaptureSequenceAborted} is invoked instead.</p>
		*
		* <p>The default implementation does nothing.</p>
		*
		* @param camera
		* The CameraDevice sending the callback.
		* @param sequenceId
		* A sequence ID returned by the {@link #capture} family of functions.
		* @param lastFrameNumber
		* @param frameNumber
		* The last frame number (returned by {@link CaptureResult#getFrameNumber}
		* or {@link CaptureFailure#getFrameNumber}) in the capture sequence.
		* The last frame number may be equal to NO_FRAMES_CAPTURED if no images
		* were captured for this sequence. This can happen, for example, when a
		* repeating request or burst is cleared right after being set.
		*
		* @see CaptureResult#getFrameNumber()
		* @see CaptureFailure#getFrameNumber()
		* @see CaptureResult#getSequenceId()
		* @see CaptureFailure#getSequenceId()
		* @see #onCaptureSequenceAborted
		*/
		public void onCaptureSequenceCompleted(CameraDevice camera,
		int sequenceId, int lastFrameNumber) {
		int sequenceId, long frameNumber) {
		// default empty implementation
		}

		/**
		* This method is called independently of the others in CaptureListener,
		* when a capture sequence aborts before any {@link CaptureResult}
		* or {@link CaptureFailure} for it have been returned via this listener.
		*
		* <p>Due to the asynchronous nature of the camera device, not all submitted captures
		* are immediately processed. It is possible to clear out the pending requests
		* by a variety of operations such as {@link CameraDevice#stopRepeating} or
		* {@link CameraDevice#flush}. When such an event happens,
		* {@link #onCaptureSequenceCompleted} will not be called.</p>
		*
		* <p>The default implementation does nothing.</p>
		*
		* @param camera
		* The CameraDevice sending the callback.
		* @param sequenceId
		* A sequence ID returned by the {@link #capture} family of functions.
		*
		* @see CaptureResult#getFrameNumber()
		* @see CaptureFailure#getFrameNumber()
		* @see CaptureResult#getSequenceId()
		* @see CaptureFailure#getSequenceId()
		* @see #onCaptureSequenceCompleted
		*/
		public void onCaptureSequenceAborted(CameraDevice camera,
		int sequenceId) {
		// default empty implementation
		}
		}

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

+16 −9

Original line number	Diff line number	Diff line
		@@ -24,9 +24,9 @@ import android.util.Rational;
		import java.util.List;

		/**
		* <p>The results of a single image capture from the image sensor.</p>
		* <p>The subset of the results of a single image capture from the image sensor.</p>
		*
		* <p>Contains the final configuration for the capture hardware (sensor, lens,
		* <p>Contains a subset of the final configuration for the capture hardware (sensor, lens,
		* flash), the processing pipeline, the control algorithms, and the output
		* buffers.</p>
		*
		@@ -36,10 +36,15 @@ import java.util.List;
		* capture. The result also includes additional metadata about the state of the
		* camera device during the capture.</p>
		*
		* <p>{@link CameraCharacteristics} objects are immutable.</p>
		* <p>Not all properties returned by {@link CameraCharacteristics#getAvailableCaptureResultKeys()}
		* are necessarily available. Some results are {@link CaptureResult partial} and will
		* not have every key set. Only {@link TotalCaptureResult total} results are guaranteed to have
		* every key available that was enabled by the request.</p>
		*
		* <p>{@link CaptureResult} objects are immutable.</p>
		*
		*/
		public final class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
		public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {

		private static final String TAG = "CaptureResult";
		private static final boolean VERBOSE = false;
		@@ -249,18 +254,19 @@ public final class CaptureResult extends CameraMetadata<CaptureResult.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>Whenever a request has been fully or partially captured, with
		* {@link CameraDevice.CaptureListener#onCaptureCompleted} or
		* {@link CameraDevice.CaptureListener#onCaptureProgressed}, the {@code result}'s
		* {@code getRequest()} will return that {@code request}.
		* </p>
		*
		* <p>In particular,
		* <p>For example,
		* <code><pre>cameraDevice.capture(someRequest, new CaptureListener() {
		* {@literal @}Override
		* void onCaptureCompleted(CaptureRequest myRequest, CaptureResult myResult) {
		* assert(myResult.getRequest.equals(myRequest) == true);
		* }
		* };
		* }, null);
		* </code></pre>
		* </p>
		*
		@@ -297,6 +303,7 @@ public final class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
		* @return int The ID for the sequence of requests that this capture result is a part of
		*
		* @see CameraDevice.CaptureListener#onCaptureSequenceCompleted
		* @see CameraDevice.CaptureListener#onCaptureSequenceAborted
		*/
		public int getSequenceId() {
		return mSequenceId;

core/java/android/hardware/camera2/TotalCaptureResult.java

0 → 100644

+84 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2014 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.impl.CameraMetadataNative;

		import java.util.Collections;
		import java.util.List;

		/**
		* <p>The total assembled results of a single image capture from the image sensor.</p>
		*
		* <p>Contains the final configuration for the capture hardware (sensor, lens,
		* flash), the processing pipeline, the control algorithms, and the output
		* buffers.</p>
		*
		* <p>A {@code TotalCaptureResult} is produced by a {@link CameraDevice} after processing a
		* {@link CaptureRequest}. All properties listed for capture requests can also
		* be queried on the capture result, to determine the final values used for
		* capture. The result also includes additional metadata about the state of the
		* camera device during the capture.</p>
		*
		* <p>All properties returned by {@link CameraCharacteristics#getAvailableCaptureResultKeys()}
		* are available (that is {@link CaptureResult#get} will return non-{@code null}, if and only if
		* that key that was enabled by the request. A few keys such as
		* {@link CaptureResult#STATISTICS_FACES} are disabled by default unless enabled with a switch (such
		* as {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE}). Refer to each key documentation on
		* a case-by-case basis.</p>
		*
		* <p>{@link TotalCaptureResult} objects are immutable.</p>
		*
		* @see CameraDevice.CaptureListener#onCaptureCompleted
		*/
		public final class TotalCaptureResult extends CaptureResult {

		/**
		* Takes ownership of the passed-in properties object
		* @hide
		*/
		public TotalCaptureResult(CameraMetadataNative results, CaptureRequest parent, int sequenceId) {
		super(results, parent, sequenceId);
		}

		/**
		* Creates a request-less result.
		*
		* <p><strong>For testing only.</strong></p>
		* @hide
		*/
		public TotalCaptureResult(CameraMetadataNative results, int sequenceId) {
		super(results, sequenceId);
		}

		/**
		* Get the read-only list of partial results that compose this total result.
		*
		* <p>The list is returned is unmodifiable; attempting to modify it will result in a
		* {@code UnsupportedOperationException} being thrown.</p>
		*
		* <p>The list size will be inclusive between {@code 1} and
		* {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT}, in ascending order
		* of when {@link CameraDevice.CaptureListener#onCaptureProgressed} was invoked.</p>
		*
		* @return unmodifiable list of partial results
		*/
		public List<CaptureResult> getPartialResults() {
		// TODO
		return Collections.unmodifiableList(null);
		}
		}