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) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Input | Target 1 | Target 2 | Target 3 | Target 4 | Sample use case(s) | |||||
| Type | Max size | Type | Max size | Type | Max size | Type | Max size | Type | Max 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) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Input | Target 1 | Target 2 | Target 3 | Target 4 | Sample use case(s) | |||||
| Type | Max size | Type | Max size | Type | Max size | Type | Max size | Type | Max 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) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Input | Target 1 | Target 2 | Target 3 | Target 4 | Sample use case(s) | |||||
| Type | Max size | Type | Max size | Type | Max size | Type | Max size | Type | Max 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. |