From edeab40338a047655f6af60e9e950dbad262279b Mon Sep 17 00:00:00 2001 From: Sol Boucher Date: Wed, 9 Jul 2014 18:36:28 -0700 Subject: [PATCH] camera2: Document CameraCaptureSession behavior given 0 Surfaces Clarify that this will cause an IllegalArgumentException to be thrown Change-Id: Ifabfed6d8d46492c4ca45bbbed599ded5260b099 --- .../camera2/CameraCaptureSession.java | 29 ++++++++++--------- .../hardware/camera2/CaptureRequest.java | 6 ++++ 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCaptureSession.java b/core/java/android/hardware/camera2/CameraCaptureSession.java index c6f98dc213305..fc2141f0c90da 100644 --- a/core/java/android/hardware/camera2/CameraCaptureSession.java +++ b/core/java/android/hardware/camera2/CameraCaptureSession.java @@ -93,9 +93,10 @@ public abstract class CameraCaptureSession implements AutoCloseable { * @throws IllegalStateException if this session is no longer active, either because the session * was explicitly closed, a new session has been created * or the camera device has been closed. - * @throws IllegalArgumentException if the request targets Surfaces that are not configured as - * outputs for this session. Or if the handler is null, the - * listener is not null, and the calling thread has no looper. + * @throws IllegalArgumentException if the request targets no Surfaces or Surfaces that are not + * configured as outputs for this session. Or if the handler is + * null, the listener is not null, and the calling thread has + * no looper. * * @see #captureBurst * @see #setRepeatingRequest @@ -137,9 +138,9 @@ public abstract class CameraCaptureSession implements AutoCloseable { * @throws IllegalStateException if this session is no longer active, either because the session * was explicitly closed, a new session has been created * or the camera device has been closed. - * @throws IllegalArgumentException If the requests target Surfaces not currently configured as - * outputs. Or if the handler is null, the listener is not - * null, and the calling thread has no looper. + * @throws IllegalArgumentException If the requests target no Surfaces or Surfaces not currently + * configured as outputs. Or if the handler is null, the + * listener is not null, and the calling thread has no looper. * * @see #capture * @see #setRepeatingRequest @@ -191,10 +192,10 @@ public abstract class CameraCaptureSession implements AutoCloseable { * @throws IllegalStateException if this session is no longer active, either because the session * was explicitly closed, a new session has been created * or the camera device has been closed. - * @throws IllegalArgumentException If the requests reference Surfaces that are not currently - * configured as outputs. Or if the handler is null, the - * listener is not null, and the calling thread has no looper. - * Or if no requests were passed in. + * @throws IllegalArgumentException If the requests reference no Surfaces or Surfaces that are + * not currently configured as outputs. Or if the handler is + * null, the listener is not null, and the calling thread has + * no looper. Or if no requests were passed in. * * @see #capture * @see #captureBurst @@ -251,10 +252,10 @@ public abstract class CameraCaptureSession implements AutoCloseable { * @throws IllegalStateException if this session is no longer active, either because the session * was explicitly closed, a new session has been created * or the camera device has been closed. - * @throws IllegalArgumentException If the requests reference Surfaces not currently configured - * as outputs. Or if the handler is null, the listener is not - * null, and the calling thread has no looper. Or if no - * requests were passed in. + * @throws IllegalArgumentException If the requests reference no Surfaces or Surfaces not + * currently configured as outputs. Or if the handler is null, + * the listener is not null, and the calling thread has no + * looper. Or if no requests were passed in. * * @see #capture * @see #captureBurst diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index e8014b0123649..964f4f3c171c9 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -446,6 +446,12 @@ public final class CaptureRequest extends CameraMetadata> /** * Build a request using the current target Surfaces and settings. + *

Note that, although it is possible to create a {@code CaptureRequest} with no target + * {@link Surface}s, passing such a request into {@link CameraCaptureSession#capture}, + * {@link CameraCaptureSession#captureBurst}, + * {@link CameraCaptureSession#setRepeatingBurst}, or + * {@link CameraCaptureSession#setRepeatingRequest} will cause that method to throw an + * {@link IllegalArgumentException}.

* * @return A new capture request instance, ready for submission to the * camera device.