Camera2: Add timestampCalibration tag
Also update the video/optical stabilization docs.
Change-Id: I444cc8d46c0a460bc4311e58bf6166b5c6dbfd14
diff --git a/api/current.txt b/api/current.txt
index 25c6ce8..370b098 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -12171,6 +12171,7 @@
field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_INFO_PHYSICAL_SIZE;
field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_INFO_PIXEL_ARRAY_SIZE;
field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_INFO_SENSITIVITY_RANGE;
+ field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_INFO_TIMESTAMP_CALIBRATION;
field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_INFO_WHITE_LEVEL;
field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_MAX_ANALOG_SENSITIVITY;
field public static final android.hardware.camera2.CameraCharacteristics.Key SENSOR_ORIENTATION;
@@ -12379,6 +12380,8 @@
field public static final int SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG = 1; // 0x1
field public static final int SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB = 4; // 0x4
field public static final int SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB = 0; // 0x0
+ field public static final int SENSOR_INFO_TIMESTAMP_CALIBRATION_CALIBRATED = 1; // 0x1
+ field public static final int SENSOR_INFO_TIMESTAMP_CALIBRATION_UNCALIBRATED = 0; // 0x0
field public static final int SENSOR_REFERENCE_ILLUMINANT1_CLOUDY_WEATHER = 10; // 0xa
field public static final int SENSOR_REFERENCE_ILLUMINANT1_COOL_WHITE_FLUORESCENT = 14; // 0xe
field public static final int SENSOR_REFERENCE_ILLUMINANT1_D50 = 23; // 0x17
diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 9eea545..4a87680 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -1423,6 +1423,18 @@
new Key<Integer>("android.sensor.info.whiteLevel", int.class);
/**
+ * <p>The sensor timestamp calibration quality.</p>
+ * <p>The sensor timestamp calibration quality determines the reliability of
+ * {@link CaptureResult#SENSOR_TIMESTAMP android.sensor.timestamp} provided by the camera device.</p>
+ *
+ * @see CaptureResult#SENSOR_TIMESTAMP
+ * @see #SENSOR_INFO_TIMESTAMP_CALIBRATION_UNCALIBRATED
+ * @see #SENSOR_INFO_TIMESTAMP_CALIBRATION_CALIBRATED
+ */
+ public static final Key<Integer> SENSOR_INFO_TIMESTAMP_CALIBRATION =
+ new Key<Integer>("android.sensor.info.timestampCalibration", int.class);
+
+ /**
* <p>The standard reference illuminant used as the scene light source when
* calculating the {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 android.sensor.calibrationTransform1}, and
diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index 33e1915..5a02435 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -419,6 +419,33 @@
public static final int SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB = 4;
//
+ // Enumeration values for CameraCharacteristics#SENSOR_INFO_TIMESTAMP_CALIBRATION
+ //
+
+ /**
+ * <p>Timestamps from {@link CaptureResult#SENSOR_TIMESTAMP android.sensor.timestamp} are in nanoseconds and monotonic,
+ * but can not be compared to timestamps from other subsystems
+ * (e.g. accelerometer, gyro etc.), or other instances of the same or different
+ * camera devices in the same system. Timestamps between streams and results for
+ * a single camera instance are comparable, and the timestamps for all buffers
+ * and the result metadata generated by a single capture are identical.</p>
+ *
+ * @see CaptureResult#SENSOR_TIMESTAMP
+ * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_CALIBRATION
+ */
+ public static final int SENSOR_INFO_TIMESTAMP_CALIBRATION_UNCALIBRATED = 0;
+
+ /**
+ * <p>Timestamps from {@link CaptureResult#SENSOR_TIMESTAMP android.sensor.timestamp} are in the same timebase as
+ * android.os.SystemClock#elapsedRealtimeNanos(),
+ * and they can be compared to other timestamps using that base.</p>
+ *
+ * @see CaptureResult#SENSOR_TIMESTAMP
+ * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_CALIBRATION
+ */
+ public static final int SENSOR_INFO_TIMESTAMP_CALIBRATION_CALIBRATED = 1;
+
+ //
// Enumeration values for CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1
//
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index bf7bd37..2cfb611 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -1020,9 +1020,17 @@
* <p>Video stabilization automatically translates and scales images from the camera
* in order to stabilize motion between consecutive frames.</p>
* <p>If enabled, video stabilization can modify the
- * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
- * stabilized</p>
+ * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream stabilized.</p>
+ * <p>Switching between different video stabilization modes may take several frames
+ * to initialize, the camera device will report the current mode in capture result
+ * metadata. For example, When "ON" mode is requested, the video stabilization modes
+ * in the first several capture results may still be "OFF", and it will become "ON"
+ * when the initialization is done.</p>
+ * <p>If a camera device supports both this mode and OIS ({@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}),
+ * turning both modes on may produce undesirable interaction, so it is recommended not to
+ * enable both at the same time.</p>
*
+ * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
* @see CaptureRequest#SCALER_CROP_REGION
* @see #CONTROL_VIDEO_STABILIZATION_MODE_OFF
* @see #CONTROL_VIDEO_STABILIZATION_MODE_ON
@@ -1258,6 +1266,14 @@
* makes use of mechanical elements to stabilize the camera
* sensor, and thus allows for longer exposure times before
* camera shake becomes apparent.</p>
+ * <p>Switching between different optical stabilization modes may take several
+ * frames to initialize, the camera device will report the current mode in
+ * capture result metadata. For example, When "ON" mode is requested, the
+ * optical stabilization modes in the first several capture results may still
+ * be "OFF", and it will become "ON" when the initialization is done.</p>
+ * <p>If a camera device supports both OIS and EIS ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}),
+ * turning both modes on may produce undesirable interaction, so it is recommended not
+ * to enable both at the same time.</p>
* <p>Not all devices will support OIS; see
* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for
* available controls.</p>
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index 3d17ed3..65b6627 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -1591,9 +1591,17 @@
* <p>Video stabilization automatically translates and scales images from the camera
* in order to stabilize motion between consecutive frames.</p>
* <p>If enabled, video stabilization can modify the
- * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
- * stabilized</p>
+ * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream stabilized.</p>
+ * <p>Switching between different video stabilization modes may take several frames
+ * to initialize, the camera device will report the current mode in capture result
+ * metadata. For example, When "ON" mode is requested, the video stabilization modes
+ * in the first several capture results may still be "OFF", and it will become "ON"
+ * when the initialization is done.</p>
+ * <p>If a camera device supports both this mode and OIS ({@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}),
+ * turning both modes on may produce undesirable interaction, so it is recommended not to
+ * enable both at the same time.</p>
*
+ * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
* @see CaptureRequest#SCALER_CROP_REGION
* @see #CONTROL_VIDEO_STABILIZATION_MODE_OFF
* @see #CONTROL_VIDEO_STABILIZATION_MODE_ON
@@ -1846,6 +1854,14 @@
* makes use of mechanical elements to stabilize the camera
* sensor, and thus allows for longer exposure times before
* camera shake becomes apparent.</p>
+ * <p>Switching between different optical stabilization modes may take several
+ * frames to initialize, the camera device will report the current mode in
+ * capture result metadata. For example, When "ON" mode is requested, the
+ * optical stabilization modes in the first several capture results may still
+ * be "OFF", and it will become "ON" when the initialization is done.</p>
+ * <p>If a camera device supports both OIS and EIS ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}),
+ * turning both modes on may produce undesirable interaction, so it is recommended not
+ * to enable both at the same time.</p>
* <p>Not all devices will support OIS; see
* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for
* available controls.</p>
@@ -2117,12 +2133,19 @@
* row of the image sensor, in nanoseconds.</p>
* <p>The timestamps are also included in all image
* buffers produced for the same capture, and will be identical
- * on all the outputs. The timestamps measure time since an
- * unspecified starting point, and are monotonically
- * increasing.</p>
- * <p>They can be compared with the timestamps for other captures
- * from the same camera device, but are not guaranteed to be
- * comparable to any other time source.</p>
+ * on all the outputs.</p>
+ * <p>When {@link CameraCharacteristics#SENSOR_INFO_TIMESTAMP_CALIBRATION android.sensor.info.timestampCalibration} <code>==</code> UNCALIBRATED,
+ * the timestamps measure time since an unspecified starting point,
+ * and are monotonically increasing. They can be compared with the
+ * timestamps for other captures from the same camera device, but are
+ * not guaranteed to be comparable to any other time source.</p>
+ * <p>When {@link CameraCharacteristics#SENSOR_INFO_TIMESTAMP_CALIBRATION android.sensor.info.timestampCalibration} <code>==</code> CALIBRATED,
+ * the timestamps measure time in the same timebase as
+ * android.os.SystemClock#elapsedRealtimeNanos(), and they can be
+ * compared to other timestamps from other subsystems that are using
+ * that base.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_CALIBRATION
*/
public static final Key<Long> SENSOR_TIMESTAMP =
new Key<Long>("android.sensor.timestamp", long.class);