From 3c1ff68d699be7157af0ea43adac27ad46bb6e56 Mon Sep 17 00:00:00 2001 From: Zhijun He Date: Tue, 23 Jun 2015 09:21:43 -0700 Subject: [PATCH] Camera2: update high speed recording API java doc Bug: 21442271 Change-Id: Iff5889394f7723eb0fd7319b9513cd0dca04b927 --- .../camera2/CameraCharacteristics.java | 3 +- .../params/StreamConfigurationMap.java | 152 +++++++++--------- 2 files changed, 82 insertions(+), 73 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index 261ce72bac349..a88b71c07a9dd 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -628,7 +628,7 @@ public final class CameraCharacteristics extends CameraMetadataList of available high speed video size, fps range and max batch size configurations * supported by the camera device, in the format of (width, height, fps_min, fps_max, batch_size_max).

- *

When CONSTRAINED_HIGH_SPEED_VIDEO is supported in android.control.availableCapabilities, + *

When CONSTRAINED_HIGH_SPEED_VIDEO is supported in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}, * this metadata will list the supported high speed video size, fps range and max batch size * configurations. All the sizes listed in this configuration will be a subset of the sizes * reported by {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes } @@ -675,6 +675,7 @@ public final class CameraCharacteristics extends CameraMetadata * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @hide */ public static final Key CONTROL_AVAILABLE_HIGH_SPEED_VIDEO_CONFIGURATIONS = diff --git a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java index 0935564913c89..639ad6054a325 100644 --- a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java +++ b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java @@ -20,6 +20,7 @@ import android.graphics.ImageFormat; import android.graphics.PixelFormat; import android.hardware.camera2.CameraCharacteristics; import android.hardware.camera2.CameraDevice; +import android.hardware.camera2.CameraMetadata; import android.hardware.camera2.CaptureRequest; import android.hardware.camera2.utils.HashCodeHelpers; import android.hardware.camera2.utils.SurfaceUtils; @@ -484,31 +485,35 @@ public final class StreamConfigurationMap { /** * Get a list of supported high speed video recording sizes. - * - *

When HIGH_SPEED_VIDEO is supported in - * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES available scene modes}, this - * method will list the supported high speed video size configurations. All the sizes listed - * will be a subset of the sizes reported by {@link #getOutputSizes} for processed non-stalling - * formats (typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12)

- * - *

To enable high speed video recording, application must set - * {@link CaptureRequest#CONTROL_SCENE_MODE} to - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture - * requests and select the video size from this method and + *

+ * When {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO} is + * supported in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES}, this method will + * list the supported high speed video size configurations. All the sizes listed will be a + * subset of the sizes reported by {@link #getOutputSizes} for processed non-stalling formats + * (typically {@link ImageFormat#PRIVATE} {@link ImageFormat#YUV_420_888}, etc.) + *

+ *

+ * To enable high speed video recording, application must create a constrained create high speed + * capture session via {@link CameraDevice#createConstrainedHighSpeedCaptureSession}, and submit + * a CaptureRequest list created by {@link CameraDevice#createConstrainedHighSpeedRequestList} + * to this session. The application must select the video size from this method and * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS range} from - * {@link #getHighSpeedVideoFpsRangesFor} to configure the recording and preview streams and - * setup the recording requests. For example, if the application intends to do high speed - * recording, it can select the maximum size reported by this method to configure output - * streams. Note that for the use case of multiple output streams, application must select one - * unique size from this method to use. Otherwise a request error might occur. Once the size is + * {@link #getHighSpeedVideoFpsRangesFor} to configure the constrained high speed session and + * generate the high speed request list. For example, if the application intends to do high + * speed recording, it can select the maximum size reported by this method to create high speed + * capture session. Note that for the use case of multiple output streams, application must + * select one unique size from this method to use (e.g., preview and recording streams must have + * the same size). Otherwise, the high speed session creation will fail. Once the size is * selected, application can get the supported FPS ranges by * {@link #getHighSpeedVideoFpsRangesFor}, and use these FPS ranges to setup the recording - * requests.

- * - * @return - * an array of supported high speed video recording sizes + * request lists via {@link CameraDevice#createConstrainedHighSpeedRequestList}. + *

* + * @return an array of supported high speed video recording sizes * @see #getHighSpeedVideoFpsRangesFor(Size) + * @see CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO + * @see CameraDevice#createConstrainedHighSpeedCaptureSession + * @see CameraDevice#createConstrainedHighSpeedRequestList */ public Size[] getHighSpeedVideoSizes() { Set keySet = mHighSpeedVideoSizeMap.keySet(); @@ -517,26 +522,25 @@ public final class StreamConfigurationMap { /** * Get the frame per second ranges (fpsMin, fpsMax) for input high speed video size. - * - *

See {@link #getHighSpeedVideoSizes} for how to enable high speed recording.

- * - *

For normal video recording use case, where some application will NOT set - * {@link CaptureRequest#CONTROL_SCENE_MODE} to - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture - * requests, the {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS ranges} reported in - * this method must not be used to setup capture requests, or it will cause request error.

+ *

+ * See {@link #getHighSpeedVideoFpsRanges} for how to enable high speed recording. + *

+ *

+ * The {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS ranges} reported in this method + * must not be used to setup capture requests that are submitted to unconstrained capture + * sessions, or it will result in {@link IllegalArgumentException IllegalArgumentExceptions}. + *

+ *

+ * See {@link #getHighSpeedVideoFpsRanges} for the characteristics of the returned FPS ranges. + *

* * @param size one of the sizes returned by {@link #getHighSpeedVideoSizes()} - * @return - * An array of FPS range to use with - * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE TARGET_FPS_RANGE} when using - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} scene - * mode. - * The upper bound of returned ranges is guaranteed to be larger or equal to 60. - * + * @return an array of supported high speed video recording FPS ranges The upper bound of + * returned ranges is guaranteed to be greater than or equal to 120. * @throws IllegalArgumentException if input size does not exist in the return value of - * getHighSpeedVideoSizes + * getHighSpeedVideoSizes * @see #getHighSpeedVideoSizes() + * @see #getHighSpeedVideoFpsRanges() */ public Range[] getHighSpeedVideoFpsRangesFor(Size size) { Integer fpsRangeCount = mHighSpeedVideoSizeMap.get(size); @@ -558,34 +562,46 @@ public final class StreamConfigurationMap { /** * Get a list of supported high speed video recording FPS ranges. - * - *

When HIGH_SPEED_VIDEO is supported in - * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES available scene modes}, this - * method will list the supported high speed video FPS range configurations. Application can - * then use {@link #getHighSpeedVideoSizesFor} to query available sizes for one of returned - * FPS range.

- * - *

To enable high speed video recording, application must set - * {@link CaptureRequest#CONTROL_SCENE_MODE} to - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture - * requests and select the video size from {@link #getHighSpeedVideoSizesFor} and + *

+ * When {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO} is + * supported in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES}, this method will + * list the supported high speed video FPS range configurations. Application can then use + * {@link #getHighSpeedVideoSizesFor} to query available sizes for one of returned FPS range. + *

+ *

+ * To enable high speed video recording, application must create a constrained create high speed + * capture session via {@link CameraDevice#createConstrainedHighSpeedCaptureSession}, and submit + * a CaptureRequest list created by {@link CameraDevice#createConstrainedHighSpeedRequestList} + * to this session. The application must select the video size from this method and * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS range} from - * this method to configure the recording and preview streams and setup the recording requests. - * For example, if the application intends to do high speed recording, it can select one FPS - * range reported by this method, query the video sizes corresponding to this FPS range by - * {@link #getHighSpeedVideoSizesFor} and select one of reported sizes to configure output - * streams. Note that for the use case of multiple output streams, application must select one - * unique size from {@link #getHighSpeedVideoSizesFor}, and use it for all output streams. - * Otherwise a request error might occur when attempting to enable - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}. - * Once the stream is configured, application can set the FPS range in the recording requests. + * {@link #getHighSpeedVideoFpsRangesFor} to configure the constrained high speed session and + * generate the high speed request list. For example, if the application intends to do high + * speed recording, it can select one FPS range reported by this method, query the video sizes + * corresponding to this FPS range by {@link #getHighSpeedVideoSizesFor} and use one of reported + * sizes to create a high speed capture session. Note that for the use case of multiple output + * streams, application must select one unique size from this method to use (e.g., preview and + * recording streams must have the same size). Otherwise, the high speed session creation will + * fail. Once the high speed capture session is created, the application can set the FPS range + * in the recording request lists via + * {@link CameraDevice#createConstrainedHighSpeedRequestList}. + *

+ *

+ * The FPS ranges reported by this method will have below characteristics: + *

  • The fpsMin and fpsMax will be a multiple 30fps.
    • + *
  • The fpsMin will be no less than 30fps, the fpsMax will be no less than 120fps.
    • + *
  • At least one range will be a fixed FPS range where fpsMin == fpsMax.
    • + *
  • For each fixed FPS range, there will be one corresponding variable FPS range [30, + * fps_max]. These kinds of FPS ranges are suitable for preview-only use cases where the + * application doesn't want the camera device always produce higher frame rate than the display + * refresh rate.
    • *

    * - * @return - * an array of supported high speed video recording FPS ranges - * The upper bound of returned ranges is guaranteed to be larger or equal to 60. - * + * @return an array of supported high speed video recording FPS ranges The upper bound of + * returned ranges is guaranteed to be larger or equal to 120. * @see #getHighSpeedVideoSizesFor + * @see CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO + * @see CameraDevice#createConstrainedHighSpeedCaptureSession + * @see CameraDevice#createConstrainedHighSpeedRequestList */ @SuppressWarnings("unchecked") public Range[] getHighSpeedVideoFpsRanges() { @@ -594,21 +610,13 @@ public final class StreamConfigurationMap { } /** - * Get the supported video sizes for input FPS range. + * Get the supported video sizes for an input high speed FPS range. * - *

    See {@link #getHighSpeedVideoFpsRanges} for how to enable high speed recording.

    - * - *

    For normal video recording use case, where the application will NOT set - * {@link CaptureRequest#CONTROL_SCENE_MODE} to - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture - * requests, the {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS ranges} reported in - * this method must not be used to setup capture requests, or it will cause request error.

    + *

    See {@link #getHighSpeedVideoSizes} for how to enable high speed recording.

    * * @param fpsRange one of the FPS range returned by {@link #getHighSpeedVideoFpsRanges()} - * @return - * An array of video sizes to configure output stream when using - * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} scene - * mode. + * @return An array of video sizes to create high speed capture sessions for high speed streaming + * use cases. * * @throws IllegalArgumentException if input FPS range does not exist in the return value of * getHighSpeedVideoFpsRanges