am f62fb8f9: Merge "Camera2: Document supported target combinations for a session." into lmp-dev
* commit 'f62fb8f94ac595d31da73fd791a2738737a13efa': Camera2: Document supported target combinations for a session.
This commit is contained in:
Eino-Ville Talvala
@@ -216,6 +216,128 @@ public abstract class CameraDevice implements AutoCloseable {
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <p>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}.</p>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <style scoped>
|
||||
* #rb { border-right-width: thick; }
|
||||
* </style>
|
||||
* <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
|
||||
* {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at
|
||||
* least the following stream combinations:
|
||||
*
|
||||
* <table>
|
||||
* <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr>
|
||||
* <tr> <th colspan="2" id="rb">Target 1</th> <th colspan="2" id="rb">Target 2</th> <th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr>
|
||||
* <tr> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th></tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>Simple preview, GPU video processing, or no-preview video recording.</td> </tr>
|
||||
* <tr> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-viewfinder still image capture.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>In-application video/image processing.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Standard still imaging.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>In-app processing plus still capture.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td colspan="2" id="rb"></td> <td>Standard recording.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td colspan="2" id="rb"></td> <td>Preview plus in-app processing.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Still capture plus in-app processing.</td> </tr>
|
||||
* </table><br>
|
||||
* </p>
|
||||
*
|
||||
* <p>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:
|
||||
*
|
||||
* <table>
|
||||
* <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr>
|
||||
* <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr>
|
||||
* <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>High-resolution video recording with preview.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>High-resolution in-app video processing with preview.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>Two-input in-app video processing.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD }</td> <td>High-resolution recording with video snapshot.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD }</td> <td>High-resolution in-app processing with video snapshot.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Two-input in-app processing with still capture.</td> </tr>
|
||||
* </table><br>
|
||||
* </p>
|
||||
*
|
||||
* <p>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:
|
||||
*
|
||||
* <table>
|
||||
* <tr><th colspan="7">FULL-capability additional guaranteed configurations</th></tr>
|
||||
* <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr>
|
||||
* <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution GPU processing with preview.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution in-app processing with preview.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution two-input in-app processsing.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Video recording with maximum-size video snapshot</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code 640x480}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Standard video recording plus maximum-resolution in-app processing.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code 640x480}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Preview plus two-input maximum-resolution in-app processing.</td> </tr>
|
||||
* </table><br>
|
||||
* </p>
|
||||
*
|
||||
* <p>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:
|
||||
*
|
||||
* <table>
|
||||
* <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr>
|
||||
* <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr>
|
||||
* <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr>
|
||||
* <tr> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-preview DNG capture.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Standard DNG capture.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>In-app processing plus DNG capture.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Video recording with DNG capture.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Preview with in-app processing and DNG capture.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Two-input in-app processing plus DNG capture.</td> </tr>
|
||||
* <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Still capture with simultaneous JPEG and DNG.</td> </tr>
|
||||
* <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>In-app processing with simultaneous JPEG and DNG.</td> </tr>
|
||||
* </table><br>
|
||||
* </p>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* @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.
|
||||
|
||||
@@ -142,7 +142,7 @@ public final class StreamConfigurationMap {
|
||||
* or in {@link PixelFormat} (and there is no possibility of collision).</p>
|
||||
*
|
||||
* <p>Formats listed in this array are guaranteed to return true if queried with
|
||||
* {@link #isOutputSupportedFor(int).</p>
|
||||
* {@link #isOutputSupportedFor(int)}.</p>
|
||||
*
|
||||
* @return an array of integer format
|
||||
*
|
||||
|
||||
Reference in New Issue
Block a user