From f3621f3a5c5fd16ebedd3ce1ae1b0100d0f64152 Mon Sep 17 00:00:00 2001 From: Eino-Ville Talvala Date: Tue, 26 Aug 2014 14:53:39 -0700 Subject: [PATCH] Camera2: Document supported target combinations for a session. Since most camera devices cannot support all combinations of target sizes given the maximum stream counts, enumerate a set of guaranteed configurations that can be used to create a session. Also fix minor docs formatting in StreamConfigurationMap Bug: 16899526 Change-Id: Ic7c94051dd47964f2be98343163ebd242b19bd24 --- .../hardware/camera2/CameraDevice.java | 122 ++++++++++++++++++ .../params/StreamConfigurationMap.java | 2 +- 2 files changed, 123 insertions(+), 1 deletion(-) diff --git a/core/java/android/hardware/camera2/CameraDevice.java b/core/java/android/hardware/camera2/CameraDevice.java index 6a9d56544184e..097b430e3d997 100644 --- a/core/java/android/hardware/camera2/CameraDevice.java +++ b/core/java/android/hardware/camera2/CameraDevice.java @@ -216,6 +216,128 @@ public abstract class CameraDevice implements AutoCloseable { *

Configuring a session with an empty or null list will close the current session, if * any. This can be used to release the current session's target surfaces for another use.

* + *

While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when + * a single output stream is configured, a given camera device may not be able to support all + * combination of sizes, formats, and targets when multiple outputs are configured at once. The + * tables below list the maximum guaranteed resolutions for combinations of streams and targets, + * given the capabilities of the camera device.

+ * + *

If an application tries to create a session using a set of targets that exceed the limits + * described in the below tables, one of three possibilities may occur. First, the session may + * be successfully created and work normally. Second, the session may be successfully created, + * but the camera device won't meet the frame rate guarantees as described in + * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set + * cannot be used at all, session creation will fail entirely, with + * {@link CameraCaptureSession.StateListener#onConfigureFailed} being invoked.

+ * + *

For the type column, {@code PRIV} refers to any target whose available sizes are found + * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible + * format, {@code YUV} refers to a target Surface using the + * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the + * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the + * {@link android.graphics.ImageFormat#RAW_SENSOR} format.

+ * + *

For the maximum size column, {@code PREVIEW} refers to the best size match to the + * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is + * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution, + * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the + * camera device's maximum output resolution for that format or target from + * {@link StreamConfigurationMap#getOutputSizes}.

+ * + *

To use these tables, determine the number and the formats/targets of outputs needed, and + * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes + * that can be used; it is guaranteed that for those targets, the listed sizes and anything + * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be + * successfully used to create a session. For example, if a row indicates that a 8 megapixel + * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session + * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP + * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4 + * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless + * some other row of the table lists such a combination.

+ * + * + *

Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at + * least the following stream combinations: + * + * + * + * + * + * + * + * + * + * + * + * + * + *
LEGACY-level guaranteed configurations
Target 1 Target 2 Target 3 Sample use case(s)
TypeMax size TypeMax size TypeMax size
{@code PRIV}{@code MAXIMUM} Simple preview, GPU video processing, or no-preview video recording.
{@code JPEG}{@code MAXIMUM} No-viewfinder still image capture.
{@code YUV }{@code MAXIMUM} In-application video/image processing.
{@code PRIV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} Standard still imaging.
{@code YUV }{@code PREVIEW} {@code JPEG}{@code MAXIMUM} In-app processing plus still capture.
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code PREVIEW} Standard recording.
{@code PRIV}{@code PREVIEW} {@code YUV }{@code PREVIEW} Preview plus in-app processing.
{@code PRIV}{@code PREVIEW} {@code YUV }{@code PREVIEW} {@code JPEG}{@code MAXIMUM} Still capture plus in-app processing.

+ *

+ * + *

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 in addition to those for + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: + * + * + * + * + * + * + * + * + * + * + * + *
LIMITED-level additional guaranteed configurations
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code RECORD } High-resolution video recording with preview.
{@code PRIV}{@code PREVIEW} {@code YUV }{@code RECORD } High-resolution in-app video processing with preview.
{@code YUV }{@code PREVIEW} {@code YUV }{@code RECORD } Two-input in-app video processing.
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code RECORD } {@code JPEG}{@code RECORD } High-resolution recording with video snapshot.
{@code PRIV}{@code PREVIEW} {@code YUV }{@code RECORD } {@code JPEG}{@code RECORD } High-resolution in-app processing with video snapshot.
{@code YUV }{@code PREVIEW} {@code YUV }{@code PREVIEW} {@code JPEG}{@code MAXIMUM} Two-input 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 in addition to those for + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: + * + * + * + * + * + * + * + * + * + * + * + *
FULL-capability additional guaranteed configurations
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code MAXIMUM} Maximum-resolution GPU processing with preview.
{@code PRIV}{@code PREVIEW} {@code YUV }{@code MAXIMUM} Maximum-resolution in-app processing with preview.
{@code YUV }{@code PREVIEW} {@code YUV }{@code MAXIMUM} Maximum-resolution two-input in-app processsing.
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} Video recording with maximum-size video snapshot
{@code YUV }{@code 640x480} {@code PRIV}{@code PREVIEW} {@code YUV }{@code MAXIMUM} Standard video recording plus maximum-resolution in-app processing.
{@code YUV }{@code 640x480} {@code YUV }{@code PREVIEW} {@code YUV }{@code MAXIMUM} Preview plus two-input maximum-resolution 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 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
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
{@code RAW }{@code MAXIMUM} No-preview DNG capture.
{@code PRIV}{@code PREVIEW} {@code RAW }{@code MAXIMUM} Standard DNG capture.
{@code YUV }{@code PREVIEW} {@code RAW }{@code MAXIMUM} In-app processing plus DNG capture.
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code PREVIEW} {@code RAW }{@code MAXIMUM} Video recording with DNG capture.
{@code PRIV}{@code PREVIEW} {@code YUV }{@code PREVIEW} {@code RAW }{@code MAXIMUM} Preview with in-app processing and DNG capture.
{@code YUV }{@code PREVIEW} {@code YUV }{@code PREVIEW} {@code RAW }{@code MAXIMUM} Two-input in-app processing plus DNG capture.
{@code PRIV}{@code PREVIEW} {@code JPEG}{@code MAXIMUM} {@code RAW }{@code MAXIMUM} Still capture with simultaneous JPEG and DNG.
{@code YUV }{@code PREVIEW} {@code JPEG}{@code MAXIMUM} {@code RAW }{@code MAXIMUM} In-app processing with simultaneous JPEG and DNG.

+ *

+ * + *

Since the capabilities of camera devices vary greatly, a given camera device may support + * target combinations with sizes outside of these guarantees, but this can only be tested for + * by attempting to create a session with such targets.

+ * * @param outputs The new set of Surfaces that should be made available as * targets for captured image data. * @param listener The listener to notify about the status of the new capture session. diff --git a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java index c0b79678c63c3..5d226e393f9f2 100644 --- a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java +++ b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java @@ -142,7 +142,7 @@ public final class StreamConfigurationMap { * or in {@link PixelFormat} (and there is no possibility of collision).

* *

Formats listed in this array are guaranteed to return true if queried with - * {@link #isOutputSupportedFor(int).

+ * {@link #isOutputSupportedFor(int)}.

* * @return an array of integer format *