From f723db7f9db2f96aaf02cae39b524b16e823fe85 Mon Sep 17 00:00:00 2001 From: Chien-Yu Chen Date: Thu, 30 Apr 2015 13:06:09 -0700 Subject: [PATCH] Camera2: stream configs for reprocessible session Add the guaranteed stream configurations for creating reprocessible capture sessions to the docs. Bug: 20263562 Change-Id: Id46d6ec8ebe7a5fe7edcb7c15325c6b53f1bc589 --- .../camera2/CameraCaptureSession.java | 35 +++--- .../hardware/camera2/CameraDevice.java | 110 ++++++++++++++++-- 2 files changed, 118 insertions(+), 27 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCaptureSession.java b/core/java/android/hardware/camera2/CameraCaptureSession.java index ef71c42a9ba53..f70e075483204 100644 --- a/core/java/android/hardware/camera2/CameraCaptureSession.java +++ b/core/java/android/hardware/camera2/CameraCaptureSession.java @@ -177,13 +177,16 @@ public abstract class CameraCaptureSession implements AutoCloseable { * was explicitly closed, a new session has been created * or the camera device has been closed. * @throws IllegalArgumentException if the request targets no Surfaces or Surfaces that are not - * configured as outputs for this session; or a reprocess - * capture request is submitted in a non-reprocessible capture - * session; or the reprocess capture request was created with - * a {@link TotalCaptureResult} from a different session; or - * the capture targets a Surface in the middle of being - * {@link #prepare prepared}; or the handler is null, the - * listener is not null, and the calling thread has no looper. + * configured as outputs for this session; or the request + * targets a set of Surfaces that cannot be submitted + * simultaneously in a reprocessible capture session; or a + * reprocess capture request is submitted in a + * non-reprocessible capture session; or the reprocess capture + * request was created with a {@link TotalCaptureResult} from + * a different session; or the capture targets a Surface in + * the middle of being {@link #prepare prepared}; or the + * handler is null, the listener is not null, and the calling + * thread has no looper. * * @see #captureBurst * @see #setRepeatingRequest @@ -233,14 +236,16 @@ public abstract class CameraCaptureSession implements AutoCloseable { * was explicitly closed, a new session has been created * or the camera device has been closed. * @throws IllegalArgumentException If the requests target no Surfaces, or the requests target - * Surfaces not currently configured as outputs; or a reprocess - * capture request is submitted in a non-reprocessible capture - * session; or one of the reprocess capture requests was - * created with a {@link TotalCaptureResult} from a different - * session; or one of the captures targets a Surface in the - * middle of being {@link #prepare prepared}; or if the handler - * is null, the listener is not null, and the calling thread - * has no looper. + * Surfaces not currently configured as outputs; or one of the + * requests targets a set of Surfaces that cannot be submitted + * simultaneously in a reprocessible capture session; or a + * reprocess capture request is submitted in a + * non-reprocessible capture session; or one of the reprocess + * capture requests was created with a + * {@link TotalCaptureResult} from a different session; or one + * of the captures targets a Surface in the middle of being + * {@link #prepare prepared}; or if the handler is null, the + * listener is not null, and the calling thread has no looper. * * @see #capture * @see #setRepeatingRequest diff --git a/core/java/android/hardware/camera2/CameraDevice.java b/core/java/android/hardware/camera2/CameraDevice.java index e9564b3fd59f8..4af7daff20576 100644 --- a/core/java/android/hardware/camera2/CameraDevice.java +++ b/core/java/android/hardware/camera2/CameraDevice.java @@ -416,24 +416,27 @@ public abstract class CameraDevice implements AutoCloseable { * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING}) or OPAQUE * reprocessing * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_OPAQUE_REPROCESSING}), besides - * the capture session created via {@link #createCaptureSession}, the application can also - * create a reprocessible capture session to submit reprocess capture requests in addition to - * regular capture requests. A reprocess capture request takes the next available buffer from - * the session's input Surface, and sends it through the camera device's processing pipeline - * again, to produce buffers for the request's target output Surfaces. No new image data is - * captured for a reprocess request. However the input buffer provided by + * the capture session created via {@link #createCaptureSession createCaptureSession}, the + * application can also create a reprocessible capture session to submit reprocess capture + * requests in addition to regular capture requests. A reprocess capture request takes the next + * available buffer from the session's input Surface, and sends it through the camera device's + * processing pipeline again, to produce buffers for the request's target output Surfaces. No + * new image data is captured for a reprocess request. However the input buffer provided by * the application must be captured previously by the same camera device in the same session * directly (e.g. for Zero-Shutter-Lag use case) or indirectly (e.g. combining multiple output * images).

* *

The active reprocessible capture session determines an input {@link Surface} and the set * of potential output Surfaces for the camera devices for each capture request. The application - * can use {@link #createCaptureRequest} to create regular capture requests to capture new - * images from the camera device, and use {@link #createReprocessCaptureRequest} to create - * reprocess capture requests to process buffers from the input {@link Surface}. A request may - * use all or only some of the outputs. All the output Surfaces in one capture request will come - * from the same source, either from a new capture by the camera device, or from the input - * Surface depending on if the request is a reprocess capture request.

+ * can use {@link #createCaptureRequest createCaptureRequest} to create regular capture requests + * to capture new images from the camera device, and use {@link #createReprocessCaptureRequest + * createReprocessCaptureRequest} to create reprocess capture requests to process buffers from + * the input {@link Surface}. Some combinations of output Surfaces in a session may not be used + * in a request simultaneously. The guaranteed combinations of output Surfaces that can be used + * in a request simultaneously are listed in the tables under {@link #createCaptureSession + * createCaptureSession}. All the output Surfaces in one capture request will come from the + * same source, either from a new capture by the camera device, or from the input Surface + * depending on if the request is a reprocess capture request.

* *

Input formats and sizes supported by the camera device can be queried via * {@link StreamConfigurationMap#getInputFormats} and @@ -451,6 +454,88 @@ public abstract class CameraDevice implements AutoCloseable { * {@link android.graphics.ImageFormat#PRIVATE} format. Otherwise, creating a reprocessible * capture session will fail.

* + *

The guaranteed stream configurations listed in + * {@link #createCaptureSession createCaptureSession} are also guaranteed to work for + * {@link #createReprocessibleCaptureSession createReprocessibleCaptureSession}. In addition, + * the configurations in the tables below are also guaranteed for creating a reprocessible + * capture session if the camera device supports YUV reprocessing or OPAQUE reprocessing. + * However, not all output targets used to create a reprocessible session may be used in a + * {@link CaptureRequest} simultaneously. The guaranteed output targets that can be included + * in a {@link CaptureRequest} simultaneously are listed in the tables under + * {@link #createCaptureSession createCaptureSession}. For example, with a FULL-capability + * ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} {@code == } + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) device that supports OPAQUE + * reprocessing, an application can create a reprocessible capture session with 1 input, + * ({@code PRIV}, {@code MAXIMUM}), and 3 outputs, ({@code PRIV}, {@code MAXIMUM}), + * ({@code PRIV}, {@code PREVIEW}), and ({@code YUV}, {@code MAXIMUM}). However, it's not + * guaranteed that an application can submit a regular or reprocess capture with ({@code PRIV}, + * {@code MAXIMUM}) and ({@code YUV}, {@code MAXIMUM}) outputs based on the table listed under + * {@link #createCaptureSession createCaptureSession}. In other words, use the tables below to + * determine the guaranteed stream configurations for creating a reprocessible capture session, + * and use the tables under {@link #createCaptureSession createCaptureSession} to determine the + * guaranteed output targets that can be submitted in a regular or reprocess + * {@link CaptureRequest} simultaneously.

+ * + * + * + *

Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices + * support at least the following stream combinations for creating a reprocessible capture + * session in addition to those listed in {@link #createCaptureSession createCaptureSession} for + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: + * + * + * + * + * + * + * + * + * + *
LIMITED-level additional guaranteed configurations for creating a reprocessible capture session
({@code PRIV} input is guaranteed only if OPAQUE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)
InputTarget 1Target 2Target 3Target 4Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code JPEG}{@code MAXIMUM} No-viewfinder still image reprocessing.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} ZSL(Zero-Shutter-Lag) still imaging.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} ZSL still and in-app processing imaging.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code YUV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} ZSL in-app processing with still capture.

+ *

+ * + *

FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices + * support at least the following stream combinations for creating a reprocessible capture + * session in addition to those for + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: + * + * + * + * + * + * + * + * + * + * + * + * + * + *
FULL-capability additional guaranteed configurations for creating a reprocessible capture session
({@code PRIV} input is guaranteed only if OPAQUE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)
InputTarget 1Target 2Target 3Target 4Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax sizeTypeMax sizeTypeMax size
{@code YUV}{@code MAXIMUM} {@code YUV}{@code MAXIMUM} {@code PRIV}{@code PREVIEW} Maximum-resolution multi-frame image fusion in-app processing with regular preview.
{@code YUV}{@code MAXIMUM} {@code YUV}{@code MAXIMUM} {@code YUV}{@code PREVIEW} Maximum-resolution multi-frame image fusion two-input in-app processing.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code YUV}{@code RECORD} High-resolution ZSL in-app video processing with regular preview.
{@code PRIV}{@code MAXIMUM} {@code PRIV}{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code YUV}{@code MAXIMUM} Maximum-resolution ZSL in-app processing with regular preview.
{@code PRIV}{@code MAXIMUM} {@code PRIV}{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code YUV}{@code MAXIMUM} Maximum-resolution two-input ZSL in-app processing.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code YUV}{@code RECORD} {@code JPEG}{@code RECORD} High-resolution ZSL in-app video processing and video snapshot with regular preview.
{@code PRIV}{@code MAXIMUM} {@code PRIV}{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code PRIV}{@code PREVIEW} {@code YUV}{@code MAXIMUM} Maximum-resolution two-input ZSL in-app processing with regular preview.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code YUV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} ZSL still capture and in-app processing.

+ *

+ * + *

RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes + * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support + * at least the following stream combinations for creating a reprocessible capture session + * on both {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices + * + * + * + * + * + * + * + * + * + * + *
RAW-capability additional guaranteed configurations for creating a reprocessible capture session
({@code PRIV} input is guaranteed only if OPAQUE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)
InputTarget 1Target 2Target 3Target 4Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code RAW}{@code MAXIMUM} Mutually exclusive ZSL in-app processing and DNG capture.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code YUV}{@code PREVIEW} {@code RAW}{@code MAXIMUM} Mutually exclusive ZSL in-app processing and preview with DNG capture.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code YUV}{@code PREVIEW} {@code RAW}{@code MAXIMUM} Mutually exclusive ZSL two-input in-app processing and DNG capture.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} {@code RAW}{@code MAXIMUM} Mutually exclusive ZSL still capture and preview with DNG capture.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code YUV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} {@code RAW}{@code MAXIMUM} Mutually exclusive ZSL in-app processing with still capture and DNG capture.

+ *

+ * * @param inputConfig The configuration for the input {@link Surface} * @param outputs The new set of Surfaces that should be made available as * targets for captured image data. @@ -466,6 +551,7 @@ public abstract class CameraDevice implements AutoCloseable { * encountered a fatal error * @throws IllegalStateException if the camera device has been closed * + * @see #createCaptureSession * @see CameraCaptureSession * @see StreamConfigurationMap#getInputFormats * @see StreamConfigurationMap#getInputSizes