Merge "Fix child view ordering for accessibility." into lmp-dev
diff --git a/Android.mk b/Android.mk
index b323650..7fa0e87 100644
--- a/Android.mk
+++ b/Android.mk
@@ -631,6 +631,7 @@
-since $(SRC_API_DIR)/18.txt 18 \
-since $(SRC_API_DIR)/19.txt 19 \
-since $(SRC_API_DIR)/20.txt 20 \
+ -since $(SRC_API_DIR)/21.txt 21 \
-werror -hide 111 -hide 113 \
-overview $(LOCAL_PATH)/core/java/overview.html
diff --git a/api/current.txt b/api/current.txt
index 1b07af9..09497a5 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -5587,7 +5587,6 @@
method public int describeContents();
method public boolean getNextEvent(android.app.usage.UsageEvents.Event);
method public boolean hasNextEvent();
- method public void resetToStart();
method public void writeToParcel(android.os.Parcel, int);
field public static final android.os.Parcelable.Creator CREATOR;
}
diff --git a/cmds/bootanimation/AudioPlayer.cpp b/cmds/bootanimation/AudioPlayer.cpp
index a2ee7ea..471b77f 100644
--- a/cmds/bootanimation/AudioPlayer.cpp
+++ b/cmds/bootanimation/AudioPlayer.cpp
@@ -272,6 +272,9 @@
config.rate = chunkFmt->sample_rate;
config.period_size = mPeriodSize;
config.period_count = mPeriodCount;
+ config.start_threshold = mPeriodSize / 4;
+ config.stop_threshold = INT_MAX;
+ config.avail_min = config.start_threshold;
if (chunkFmt->bits_per_sample != 16) {
ALOGE("only 16 bit WAV files are supported");
goto exit;
diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index 9f683e3..0e98175 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -3498,14 +3498,24 @@
* <p>You can override this function to force global search, e.g. in response to a dedicated
* search key, or to block search entirely (by simply returning false).
*
- * @return Returns {@code true} if search launched, and {@code false} if activity blocks it.
- * The default implementation always returns {@code true}.
+ * <p>Note: when running in a {@link Configuration#UI_MODE_TYPE_TELEVISION}, the default
+ * implementation changes to simply return false and you must supply your own custom
+ * implementation if you want to support search.</p>
+ *
+ * @return Returns {@code true} if search launched, and {@code false} if the activity does
+ * not respond to search. The default implementation always returns {@code true}, except
+ * when in {@link Configuration#UI_MODE_TYPE_TELEVISION} mode where it returns false.
*
* @see android.app.SearchManager
*/
public boolean onSearchRequested() {
- startSearch(null, false, null, false);
- return true;
+ if ((getResources().getConfiguration().uiMode&Configuration.UI_MODE_TYPE_MASK)
+ != Configuration.UI_MODE_TYPE_TELEVISION) {
+ startSearch(null, false, null, false);
+ return true;
+ } else {
+ return false;
+ }
}
/**
diff --git a/core/java/android/app/ActivityManagerNative.java b/core/java/android/app/ActivityManagerNative.java
index 11470e3..6c67c09 100644
--- a/core/java/android/app/ActivityManagerNative.java
+++ b/core/java/android/app/ActivityManagerNative.java
@@ -1929,7 +1929,7 @@
case IS_INTENT_SENDER_TARGETED_TO_PACKAGE_TRANSACTION: {
data.enforceInterface(IActivityManager.descriptor);
IIntentSender r = IIntentSender.Stub.asInterface(
- data.readStrongBinder());
+ data.readStrongBinder());
boolean res = isIntentSenderTargetedToPackage(r);
reply.writeNoException();
reply.writeInt(res ? 1 : 0);
@@ -2102,6 +2102,18 @@
return true;
}
+ case LAUNCH_ASSIST_INTENT_TRANSACTION: {
+ data.enforceInterface(IActivityManager.descriptor);
+ Intent intent = Intent.CREATOR.createFromParcel(data);
+ int requestType = data.readInt();
+ String hint = data.readString();
+ int userHandle = data.readInt();
+ boolean res = launchAssistIntent(intent, requestType, hint, userHandle);
+ reply.writeNoException();
+ reply.writeInt(res ? 1 : 0);
+ return true;
+ }
+
case KILL_UID_TRANSACTION: {
data.enforceInterface(IActivityManager.descriptor);
int uid = data.readInt();
@@ -5039,6 +5051,23 @@
reply.recycle();
}
+ public boolean launchAssistIntent(Intent intent, int requestType, String hint, int userHandle)
+ throws RemoteException {
+ Parcel data = Parcel.obtain();
+ Parcel reply = Parcel.obtain();
+ data.writeInterfaceToken(IActivityManager.descriptor);
+ intent.writeToParcel(data, 0);
+ data.writeInt(requestType);
+ data.writeString(hint);
+ data.writeInt(userHandle);
+ mRemote.transact(LAUNCH_ASSIST_INTENT_TRANSACTION, data, reply, 0);
+ reply.readException();
+ boolean res = reply.readInt() != 0;
+ data.recycle();
+ reply.recycle();
+ return res;
+ }
+
public void killUid(int uid, String reason) throws RemoteException {
Parcel data = Parcel.obtain();
Parcel reply = Parcel.obtain();
diff --git a/core/java/android/app/IActivityManager.java b/core/java/android/app/IActivityManager.java
index aa5fea0..b72addf 100644
--- a/core/java/android/app/IActivityManager.java
+++ b/core/java/android/app/IActivityManager.java
@@ -417,6 +417,9 @@
public void reportAssistContextExtras(IBinder token, Bundle extras) throws RemoteException;
+ public boolean launchAssistIntent(Intent intent, int requestType, String hint, int userHandle)
+ throws RemoteException;
+
public void killUid(int uid, String reason) throws RemoteException;
public void hang(IBinder who, boolean allowRestart) throws RemoteException;
@@ -777,4 +780,5 @@
int RELEASE_SOME_ACTIVITIES_TRANSACTION = IBinder.FIRST_CALL_TRANSACTION+236;
int BOOT_ANIMATION_COMPLETE_TRANSACTION = IBinder.FIRST_CALL_TRANSACTION+237;
int GET_TASK_DESCRIPTION_ICON_TRANSACTION = IBinder.FIRST_CALL_TRANSACTION+238;
+ int LAUNCH_ASSIST_INTENT_TRANSACTION = IBinder.FIRST_CALL_TRANSACTION+239;
}
diff --git a/core/java/android/app/ISearchManager.aidl b/core/java/android/app/ISearchManager.aidl
index 074d343..03e7ff4 100644
--- a/core/java/android/app/ISearchManager.aidl
+++ b/core/java/android/app/ISearchManager.aidl
@@ -31,4 +31,5 @@
ComponentName getGlobalSearchActivity();
ComponentName getWebSearchActivity();
ComponentName getAssistIntent(int userHandle);
+ boolean launchAssistAction(int requestType, String hint, int userHandle);
}
diff --git a/core/java/android/app/SearchManager.java b/core/java/android/app/SearchManager.java
index 261b15d..a40b29a 100644
--- a/core/java/android/app/SearchManager.java
+++ b/core/java/android/app/SearchManager.java
@@ -23,6 +23,7 @@
import android.content.DialogInterface;
import android.content.Intent;
import android.content.pm.ResolveInfo;
+import android.content.res.Configuration;
import android.database.Cursor;
import android.graphics.Rect;
import android.net.Uri;
@@ -624,9 +625,13 @@
return;
}
- ensureSearchDialog();
+ UiModeManager uiModeManager = new UiModeManager();
+ // Don't show search dialog on televisions.
+ if (uiModeManager.getCurrentModeType() != Configuration.UI_MODE_TYPE_TELEVISION) {
+ ensureSearchDialog();
- mSearchDialog.show(initialQuery, selectInitialQuery, launchActivity, appSearchData);
+ mSearchDialog.show(initialQuery, selectInitialQuery, launchActivity, appSearchData);
+ }
}
private void ensureSearchDialog() {
@@ -984,4 +989,20 @@
return null;
}
}
+
+ /**
+ * Launch an assist action for the current top activity.
+ * @hide
+ */
+ public boolean launchAssistAction(int requestType, String hint, int userHandle) {
+ try {
+ if (mService == null) {
+ return false;
+ }
+ return mService.launchAssistAction(requestType, hint, userHandle);
+ } catch (RemoteException re) {
+ Log.e(TAG, "launchAssistAction() failed: " + re);
+ return false;
+ }
+ }
}
diff --git a/core/java/android/app/backup/WallpaperBackupHelper.java b/core/java/android/app/backup/WallpaperBackupHelper.java
index 68ea9e9..75a5237 100644
--- a/core/java/android/app/backup/WallpaperBackupHelper.java
+++ b/core/java/android/app/backup/WallpaperBackupHelper.java
@@ -42,7 +42,7 @@
// If 'true', then apply an acceptable-size heuristic at restore time, dropping back
// to the factory default wallpaper if the restored one differs "too much" from the
// device's preferred wallpaper image dimensions.
- private static final boolean REJECT_OUTSIZED_RESTORE = false;
+ private static final boolean REJECT_OUTSIZED_RESTORE = true;
// This path must match what the WallpaperManagerService uses
// TODO: Will need to change if backing up non-primary user's wallpaper
diff --git a/core/java/android/app/usage/UsageEvents.java b/core/java/android/app/usage/UsageEvents.java
index 1a947ec..3cf3c95 100644
--- a/core/java/android/app/usage/UsageEvents.java
+++ b/core/java/android/app/usage/UsageEvents.java
@@ -15,7 +15,6 @@
*/
package android.app.usage;
-import android.content.ComponentName;
import android.content.res.Configuration;
import android.os.Parcel;
import android.os.Parcelable;
@@ -95,14 +94,6 @@
public Configuration mConfiguration;
/**
- * TODO(adamlesinski): Removed before release.
- * {@hide}
- */
- public ComponentName getComponent() {
- return new ComponentName(mPackage, mClass);
- }
-
- /**
* The package name of the source of this event.
*/
public String getPackageName() {
@@ -233,6 +224,9 @@
/**
* Resets the collection so that it can be iterated over from the beginning.
+ *
+ * @hide When this object is iterated to completion, the parcel is destroyed and
+ * so resetToStart doesn't work.
*/
public void resetToStart() {
mIndex = 0;
diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 55ca486..fb3eaff 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -310,14 +310,18 @@
* modify the comment blocks at the start or end.
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
-
/**
- * <p>The set of aberration correction modes supported by this camera device.</p>
- * <p>This metadata lists the valid modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}.
- * If no aberration correction modes are available for a device, this list will solely include
+ * <p>List of aberration correction modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode} that are
+ * supported by this camera device.</p>
+ * <p>This key lists the valid modes for {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}. If no
+ * aberration correction modes are available for a device, this list will solely include
* OFF mode.</p>
- * <p>For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL), OFF must be
- * included.</p>
+ * <p>For FULL capability device ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL), OFF is
+ * always included.</p>
+ * <p>LEGACY devices will always only support FAST mode.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE android.colorCorrection.aberrationMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
@@ -327,30 +331,42 @@
new Key<int[]>("android.colorCorrection.availableAberrationModes", int[].class);
/**
- * <p>The set of auto-exposure antibanding modes that are
+ * <p>List of auto-exposure antibanding modes for {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} that are
* supported by this camera device.</p>
* <p>Not all of the auto-exposure anti-banding modes may be
* supported by a given camera device. This field lists the
* valid anti-banding modes that the application may request
- * for this camera device; they must include AUTO.</p>
+ * for this camera device with the
+ * {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} control. This list
+ * always includes AUTO.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE
*/
@PublicKey
public static final Key<int[]> CONTROL_AE_AVAILABLE_ANTIBANDING_MODES =
new Key<int[]>("android.control.aeAvailableAntibandingModes", int[].class);
/**
- * <p>The set of auto-exposure modes that are supported by this
- * camera device.</p>
+ * <p>List of auto-exposure modes for {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} that are supported by this camera
+ * device.</p>
* <p>Not all the auto-exposure modes may be supported by a
* given camera device, especially if no flash unit is
* available. This entry lists the valid modes for
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} for this camera device.</p>
- * <p>All camera devices support ON, and all camera devices with
- * flash units support ON_AUTO_FLASH and
- * ON_ALWAYS_FLASH.</p>
+ * <p>All camera devices support ON, and all camera devices with flash
+ * units support ON_AUTO_FLASH and ON_ALWAYS_FLASH.</p>
* <p>FULL mode camera devices always support OFF mode,
* which enables application control of camera exposure time,
* sensitivity, and frame duration.</p>
+ * <p>LEGACY mode camera devices never support OFF mode.
+ * LIMITED mode devices support OFF if they support the MANUAL_SENSOR
+ * capability.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
*/
@@ -359,43 +375,70 @@
new Key<int[]>("android.control.aeAvailableModes", int[].class);
/**
- * <p>List of frame rate ranges supported by the
- * auto-exposure (AE) algorithm/hardware</p>
+ * <p>List of frame rate ranges for {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE android.control.aeTargetFpsRange} supported by
+ * this camera device.</p>
+ * <p>For devices at the LIMITED level or above, this list will include at least (30, 30) for
+ * constant-framerate recording.</p>
+ * <p><b>Units</b>: Frames per second (FPS)</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE
*/
@PublicKey
public static final Key<android.util.Range<Integer>[]> CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES =
new Key<android.util.Range<Integer>[]>("android.control.aeAvailableTargetFpsRanges", new TypeReference<android.util.Range<Integer>[]>() {{ }});
/**
- * <p>Maximum and minimum exposure compensation
- * setting, in counts of
- * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep}.</p>
+ * <p>Maximum and minimum exposure compensation values for
+ * {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation}, in counts of {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep},
+ * that are supported by this camera device.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p><code>Min.exposure compensation * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} <= -2 EV</code></p>
+ * <p><code>Max.exposure compensation * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} >= 2 EV</code></p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
+ * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
*/
@PublicKey
public static final Key<android.util.Range<Integer>> CONTROL_AE_COMPENSATION_RANGE =
new Key<android.util.Range<Integer>>("android.control.aeCompensationRange", new TypeReference<android.util.Range<Integer>>() {{ }});
/**
- * <p>Smallest step by which exposure compensation
- * can be changed</p>
+ * <p>Smallest step by which the exposure compensation
+ * can be changed.</p>
+ * <p>This is the unit for {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation}. For example, if this key has
+ * a value of <code>1/2</code>, then a setting of <code>-2</code> for {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} means
+ * that the target EV offset for the auto-exposure routine is -1 EV.</p>
+ * <p>One unit of EV compensation changes the brightness of the captured image by a factor
+ * of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness.</p>
+ * <p><b>Units</b>: Exposure Value (EV)</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
*/
@PublicKey
public static final Key<Rational> CONTROL_AE_COMPENSATION_STEP =
new Key<Rational>("android.control.aeCompensationStep", Rational.class);
/**
- * <p>List of auto-focus (AF) modes that can be
- * selected with {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p>
+ * <p>List of auto-focus (AF) modes for {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} that are
+ * supported by this camera device.</p>
* <p>Not all the auto-focus modes may be supported by a
* given camera device. This entry lists the valid modes for
* {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} for this camera device.</p>
* <p>All LIMITED and FULL mode camera devices will support OFF mode, and all
* camera devices with adjustable focuser units
* (<code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0</code>) will support AUTO mode.</p>
+ * <p>LEGACY devices will support OFF mode only if they support
+ * focusing to infinity (by also setting {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} to
+ * <code>0.0f</code>).</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
+ * @see CaptureRequest#LENS_FOCUS_DISTANCE
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
*/
@PublicKey
@@ -403,17 +446,20 @@
new Key<int[]>("android.control.afAvailableModes", int[].class);
/**
- * <p>List containing the subset of color effects
- * specified in {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode} that is supported by
- * this device.</p>
+ * <p>List of color effects for {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode} that are supported by this camera
+ * device.</p>
* <p>This list contains the color effect modes that can be applied to
- * images produced by the camera device. Only modes that have
- * been fully implemented for the current device may be included here.
+ * images produced by the camera device.
* Implementations are not expected to be consistent across all devices.
- * If no color effect modes are available for a device, this should
- * simply be set to OFF.</p>
+ * If no color effect modes are available for a device, this will only list
+ * OFF.</p>
* <p>A color effect will only be applied if
- * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
+ * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF. OFF is always included in this list.</p>
+ * <p>This control has no effect on the operation of other control routines such
+ * as auto-exposure, white balance, or focus.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_EFFECT_MODE android.control.effectMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_EFFECT_MODE
* @see CaptureRequest#CONTROL_MODE
@@ -423,38 +469,56 @@
new Key<int[]>("android.control.availableEffects", int[].class);
/**
- * <p>List containing a subset of scene modes
- * specified in {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode}.</p>
+ * <p>List of scene modes for {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} that are supported by this camera
+ * device.</p>
* <p>This list contains scene modes that can be set for the camera device.
* Only scene modes that have been fully implemented for the
* camera device may be included here. Implementations are not expected
- * to be consistent across all devices. If no scene modes are supported
- * by the camera device, this will be set to <code>[DISABLED]</code>.</p>
+ * to be consistent across all devices.</p>
+ * <p>If no scene modes are supported by the camera device, this
+ * will be set to DISABLED. Otherwise DISABLED will not be listed.</p>
+ * <p>FACE_PRIORITY is always listed if face detection is
+ * supported (i.e.<code>{@link CameraCharacteristics#STATISTICS_INFO_MAX_FACE_COUNT android.statistics.info.maxFaceCount} >
+ * 0</code>).</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#STATISTICS_INFO_MAX_FACE_COUNT
*/
@PublicKey
public static final Key<int[]> CONTROL_AVAILABLE_SCENE_MODES =
new Key<int[]>("android.control.availableSceneModes", int[].class);
/**
- * <p>List of video stabilization modes that can
- * be supported</p>
+ * <p>List of video stabilization modes for {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}
+ * that are supported by this camera device.</p>
+ * <p>OFF will always be listed.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE
*/
@PublicKey
public static final Key<int[]> CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES =
new Key<int[]>("android.control.availableVideoStabilizationModes", int[].class);
/**
- * <p>The set of auto-white-balance modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode})
- * that are supported by this camera device.</p>
+ * <p>List of auto-white-balance modes for {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} that are supported by this
+ * camera device.</p>
* <p>Not all the auto-white-balance modes may be supported by a
* given camera device. This entry lists the valid modes for
* {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} for this camera device.</p>
* <p>All camera devices will support ON mode.</p>
- * <p>FULL mode camera devices will always support OFF mode,
- * which enables application control of white balance, by using
- * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}({@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} must be set to TRANSFORM_MATRIX).</p>
+ * <p>Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF
+ * mode, which enables application control of white balance, by using
+ * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}({@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} must be set to TRANSFORM_MATRIX). This includes all FULL
+ * mode camera devices.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_MODE
@@ -471,6 +535,11 @@
* this corresponds to the the maximum number of elements in
* {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}, {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions},
* and {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>Value must be >= 0 for each element. For full-capability devices
+ * this value must be >= 1 for AE and AF. The order of the elements is:
+ * <code>(AE, AWB, AF)</code>.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_REGIONS
* @see CaptureRequest#CONTROL_AF_REGIONS
@@ -481,10 +550,14 @@
new Key<int[]>("android.control.maxRegions", int[].class);
/**
- * <p>List of the maximum number of regions that can be used for metering in
- * auto-exposure (AE);
- * this corresponds to the the maximum number of elements in
+ * <p>The maximum number of metering regions that can be used by the auto-exposure (AE)
+ * routine.</p>
+ * <p>This corresponds to the the maximum allowed number of elements in
* {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions}.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Value will be >= 0. For FULL-capability devices, this
+ * value will be >= 1.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_REGIONS
*/
@@ -494,10 +567,13 @@
new Key<Integer>("android.control.maxRegionsAe", int.class);
/**
- * <p>List of the maximum number of regions that can be used for metering in
- * auto-white balance (AWB);
- * this corresponds to the the maximum number of elements in
+ * <p>The maximum number of metering regions that can be used by the auto-white balance (AWB)
+ * routine.</p>
+ * <p>This corresponds to the the maximum allowed number of elements in
* {@link CaptureRequest#CONTROL_AWB_REGIONS android.control.awbRegions}.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Value will be >= 0.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AWB_REGIONS
*/
@@ -507,10 +583,13 @@
new Key<Integer>("android.control.maxRegionsAwb", int.class);
/**
- * <p>List of the maximum number of regions that can be used for metering in
- * auto-focus (AF);
- * this corresponds to the the maximum number of elements in
+ * <p>The maximum number of metering regions that can be used by the auto-focus (AF) routine.</p>
+ * <p>This corresponds to the the maximum allowed number of elements in
* {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Value will be >= 0. For FULL-capability devices, this
+ * value will be >= 1.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_REGIONS
*/
@@ -541,20 +620,34 @@
* {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} to HIGH_SPEED_VIDEO in capture requests, the fps ranges
* reported in this metadata must not be used to setup capture requests, or it will cause
* request error.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>For each configuration, the fps_max >= 60fps.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<android.hardware.camera2.params.HighSpeedVideoConfiguration[]> CONTROL_AVAILABLE_HIGH_SPEED_VIDEO_CONFIGURATIONS =
new Key<android.hardware.camera2.params.HighSpeedVideoConfiguration[]>("android.control.availableHighSpeedVideoConfigurations", android.hardware.camera2.params.HighSpeedVideoConfiguration[].class);
/**
- * <p>The set of edge enhancement modes supported by this camera device.</p>
- * <p>This tag lists the valid modes for {@link CaptureRequest#EDGE_MODE android.edge.mode}.</p>
- * <p>Full-capability camera devices must always support OFF and FAST.</p>
+ * <p>List of edge enhancement modes for {@link CaptureRequest#EDGE_MODE android.edge.mode} that are supported by this camera
+ * device.</p>
+ * <p>Full-capability camera devices must always support OFF; all devices will list FAST.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#EDGE_MODE android.edge.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#EDGE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<int[]> EDGE_AVAILABLE_EDGE_MODES =
@@ -562,19 +655,23 @@
/**
* <p>Whether this camera device has a
- * flash.</p>
- * <p>If no flash, none of the flash controls do
- * anything. All other metadata should return 0.</p>
+ * flash unit.</p>
+ * <p>Will be <code>false</code> if no flash is available.</p>
+ * <p>If there is no flash unit, none of the flash controls do
+ * anything.
+ * This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Boolean> FLASH_INFO_AVAILABLE =
new Key<Boolean>("android.flash.info.available", boolean.class);
/**
- * <p>The set of hot pixel correction modes that are supported by this
+ * <p>List of hot pixel correction modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode} that are supported by this
* camera device.</p>
- * <p>This tag lists valid modes for {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}.</p>
* <p>FULL mode camera devices will always support FAST.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#HOT_PIXEL_MODE android.hotPixel.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureRequest#HOT_PIXEL_MODE
*/
@@ -583,7 +680,10 @@
new Key<int[]>("android.hotPixel.availableHotPixelModes", int[].class);
/**
- * <p>Supported resolutions for the JPEG thumbnail.</p>
+ * <p>List of JPEG thumbnail sizes for {@link CaptureRequest#JPEG_THUMBNAIL_SIZE android.jpeg.thumbnailSize} supported by this
+ * camera device.</p>
+ * <p>This list will include at least one non-zero resolution, plus <code>(0,0)</code> for indicating no
+ * thumbnail should be generated.</p>
* <p>Below condiditions will be satisfied for this size list:</p>
* <ul>
* <li>The sizes will be sorted by increasing pixel area (width x height).
@@ -595,33 +695,51 @@
* <li>Each output JPEG size in android.scaler.availableStreamConfigurations will have at least
* one corresponding size that has the same aspect ratio in availableThumbnailSizes,
* and vice versa.</li>
- * <li>All non (0, 0) sizes will have non-zero widths and heights.</li>
+ * <li>All non-<code>(0, 0)</code> sizes will have non-zero widths and heights.
+ * This key is available on all devices.</li>
* </ul>
+ *
+ * @see CaptureRequest#JPEG_THUMBNAIL_SIZE
*/
@PublicKey
public static final Key<android.util.Size[]> JPEG_AVAILABLE_THUMBNAIL_SIZES =
new Key<android.util.Size[]>("android.jpeg.availableThumbnailSizes", android.util.Size[].class);
/**
- * <p>List of supported aperture
- * values.</p>
- * <p>If the camera device doesn't support variable apertures,
- * listed value will be the fixed aperture.</p>
- * <p>If the camera device supports variable apertures, the aperture value
+ * <p>List of aperture size values for {@link CaptureRequest#LENS_APERTURE android.lens.aperture} that are
+ * supported by this camera device.</p>
+ * <p>If the camera device doesn't support a variable lens aperture,
+ * this list will contain only one value, which is the fixed aperture size.</p>
+ * <p>If the camera device supports a variable aperture, the aperture values
* in this list will be sorted in ascending order.</p>
+ * <p><b>Units</b>: The aperture f-number</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CaptureRequest#LENS_APERTURE
*/
@PublicKey
public static final Key<float[]> LENS_INFO_AVAILABLE_APERTURES =
new Key<float[]>("android.lens.info.availableApertures", float[].class);
/**
- * <p>List of supported neutral density filter values for
- * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity}.</p>
- * <p>If changing {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} is not supported,
- * availableFilterDensities must contain only 0. Otherwise, this
- * list contains only the exact filter density values available on
- * this camera device.</p>
+ * <p>List of neutral density filter values for
+ * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} that are supported by this camera device.</p>
+ * <p>If a neutral density filter is not supported by this camera device,
+ * this list will contain only 0. Otherwise, this list will include every
+ * filter density supported by the camera device, in ascending order.</p>
+ * <p><b>Units</b>: Exposure value (EV)</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>Values are >= 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_FILTER_DENSITY
*/
@PublicKey
@@ -629,12 +747,16 @@
new Key<float[]>("android.lens.info.availableFilterDensities", float[].class);
/**
- * <p>The available focal lengths for this device for use with
- * {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}.</p>
- * <p>If optical zoom is not supported, this will only report
- * a single value corresponding to the static focal length of the
- * device. Otherwise, this will report every focal length supported
- * by the device.</p>
+ * <p>List of focal lengths for {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength} that are supported by this camera
+ * device.</p>
+ * <p>If optical zoom is not supported, this list will only contain
+ * a single value corresponding to the fixed focal length of the
+ * device. Otherwise, this list will include every focal length supported
+ * by the camera device, in ascending order.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>Values are > 0</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_FOCAL_LENGTH
*/
@@ -643,12 +765,18 @@
new Key<float[]>("android.lens.info.availableFocalLengths", float[].class);
/**
- * <p>List containing a subset of the optical image
- * stabilization (OIS) modes specified in
- * {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}.</p>
- * <p>If OIS is not implemented for a given camera device, this will
+ * <p>List of optical image stabilization (OIS) modes for
+ * {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode} that are supported by this camera device.</p>
+ * <p>If OIS is not supported by a given camera device, this list will
* contain only OFF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE android.lens.opticalStabilizationMode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
*/
@PublicKey
@@ -656,12 +784,21 @@
new Key<int[]>("android.lens.info.availableOpticalStabilization", int[].class);
/**
- * <p>Optional. Hyperfocal distance for this lens.</p>
+ * <p>Hyperfocal distance for this lens.</p>
* <p>If the lens is not fixed focus, the camera device will report this
* field when {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} is APPROXIMATE or CALIBRATED.</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * If lens is fixed focus, >= 0. If lens has focuser unit, the value is
+ * within <code>(0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}]</code></p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
+ * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
*/
@PublicKey
public static final Key<Float> LENS_INFO_HYPERFOCAL_DISTANCE =
@@ -669,10 +806,19 @@
/**
* <p>Shortest distance from frontmost surface
- * of the lens that can be focused correctly.</p>
- * <p>If the lens is fixed-focus, this should be
+ * of the lens that can be brought into sharp focus.</p>
+ * <p>If the lens is fixed-focus, this will be
* 0.</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
*/
@PublicKey
public static final Key<Float> LENS_INFO_MINIMUM_FOCUS_DISTANCE =
@@ -682,6 +828,14 @@
* <p>Dimensions of lens shading map.</p>
* <p>The map should be on the order of 30-40 rows and columns, and
* must be smaller than 64x64.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Both values >= 1</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<android.util.Size> LENS_INFO_SHADING_MAP_SIZE =
@@ -693,7 +847,27 @@
* focus related metadata entries, i.e. {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance},
* {@link CaptureResult#LENS_FOCUS_RANGE android.lens.focusRange}, {@link CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE android.lens.info.hyperfocalDistance}, and
* {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}.</p>
+ * <p>APPROXIMATE and CALIBRATED devices report the focus metadata in
+ * units of diopters (1/meter), so <code>0.0f</code> represents focusing at infinity,
+ * and increasing positive numbers represent focusing closer and closer
+ * to the camera device. The focus distance control also uses diopters
+ * on these devices.</p>
+ * <p>UNCALIBRATED devices do not use units that are directly comparable
+ * to any real physical measurement, but <code>0.0f</code> still represents farthest
+ * focus, and {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} represents the
+ * nearest focus the device can achieve.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED UNCALIBRATED}</li>
+ * <li>{@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE APPROXIMATE}</li>
+ * <li>{@link #LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED CALIBRATED}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_FOCUS_DISTANCE
* @see CaptureResult#LENS_FOCUS_RANGE
* @see CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE
@@ -709,6 +883,12 @@
/**
* <p>Direction the camera faces relative to
* device screen.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_FACING_FRONT FRONT}</li>
+ * <li>{@link #LENS_FACING_BACK BACK}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
* @see #LENS_FACING_FRONT
* @see #LENS_FACING_BACK
*/
@@ -717,10 +897,18 @@
new Key<Integer>("android.lens.facing", int.class);
/**
- * <p>The set of noise reduction modes supported by this camera device.</p>
- * <p>This tag lists the valid modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}.</p>
- * <p>Full-capability camera devices must always support OFF and FAST.</p>
+ * <p>List of noise reduction modes for {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode} that are supported
+ * by this camera device.</p>
+ * <p>Full-capability camera devices will always support OFF and FAST.</p>
+ * <p>Legacy-capability camera devices will only support FAST mode.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#NOISE_REDUCTION_MODE android.noiseReduction.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#NOISE_REDUCTION_MODE
*/
@PublicKey
@@ -765,6 +953,15 @@
* <li>Processed (but not-stalling): any non-RAW format without a stall duration.
* Typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12.</li>
* </ul>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>For processed (and stalling) format streams, >= 1.</p>
+ * <p>For Raw format (either stalling or non-stalling) streams, >= 0.</p>
+ * <p>For processed (but not stalling) format streams, >= 3
+ * for FULL mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL</code>);
+ * >= 2 for LIMITED mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LIMITED</code>).</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<int[]> REQUEST_MAX_NUM_OUTPUT_STREAMS =
@@ -786,7 +983,13 @@
* <li>ImageFormat#RAW10</li>
* <li>Opaque <code>RAW</code></li>
* </ul>
+ * <p>LEGACY mode devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> LEGACY)
+ * never support raw streams.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 0</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
*/
@PublicKey
@@ -814,7 +1017,14 @@
* </ul>
* <p>For full guarantees, query StreamConfigurationMap#getOutputStallDuration with
* a processed format -- it will return 0 for a non-stalling stream.</p>
+ * <p>LEGACY devices will support at least 2 processing/non-stalling streams.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 3
+ * for FULL mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL</code>);
+ * >= 2 for LIMITED mode devices (<code>{@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == LIMITED</code>).</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
*/
@PublicKey
@@ -833,9 +1043,13 @@
* CPU resources that will consume more power. The image format for this kind of an output stream can
* be any non-<code>RAW</code> and supported format provided by {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}.</p>
* <p>A processed and stalling format is defined as any non-RAW format with a stallDurations > 0.
- * Typically only the <code>JPEG</code> format (ImageFormat#JPEG)</p>
+ * Typically only the <code>JPEG</code> format (ImageFormat#JPEG) is a stalling format.</p>
* <p>For full guarantees, query StreamConfigurationMap#getOutputStallDuration with
* a processed format -- it will return a non-0 value for a stalling stream.</p>
+ * <p>LEGACY devices will support up to 1 processing/stalling stream.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 1</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
*/
@@ -856,6 +1070,14 @@
* <p>For example, for Zero Shutter Lag (ZSL) still capture use case, the input
* stream image format will be RAW_OPAQUE, the associated output stream image format
* should be JPEG.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>0 or 1.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<Integer> REQUEST_MAX_NUM_INPUT_STREAMS =
@@ -876,6 +1098,7 @@
* <p>A pipeline depth of X stages is equivalent to a pipeline latency of
* X frame intervals.</p>
* <p>This value will be 8 or less.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureResult#REQUEST_PIPELINE_DEPTH
*/
@@ -898,6 +1121,8 @@
* then immediately dispatch this state via a partial result to
* the application, and the rest of the metadata via later
* partial results.</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 1</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*/
@PublicKey
@@ -905,7 +1130,7 @@
new Key<Integer>("android.request.partialResultCount", int.class);
/**
- * <p>List of capabilities that the camera device
+ * <p>List of capabilities that this camera device
* advertises as fully supporting.</p>
* <p>A capability is a contract that the camera device makes in order
* to be able to satisfy one or more use cases.</p>
@@ -923,7 +1148,15 @@
* <li>MANUAL_POST_PROCESSING</li>
* </ul>
* <p>Other capabilities may be available on either FULL or LIMITED
- * devices, but the application should query this field to be sure.</p>
+ * devices, but the application should query this key to be sure.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE BACKWARD_COMPATIBLE}</li>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR MANUAL_SENSOR}</li>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING MANUAL_POST_PROCESSING}</li>
+ * <li>{@link #REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE
@@ -945,6 +1178,7 @@
* at a more granular level than capabilities. This is especially
* important for optional keys that are not listed under any capability
* in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @hide
@@ -957,18 +1191,19 @@
* to use with CaptureResult.</p>
* <p>Attempting to get a key from a CaptureResult that is not
* listed here will always return a <code>null</code> value. Getting a key from
- * a CaptureResult that is listed here must never return a <code>null</code>
+ * a CaptureResult that is listed here will generally never return a <code>null</code>
* value.</p>
* <p>The following keys may return <code>null</code> unless they are enabled:</p>
* <ul>
* <li>android.statistics.lensShadingMap (non-null iff {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON)</li>
* </ul>
- * <p>(Those sometimes-null keys should nevertheless be listed here
+ * <p>(Those sometimes-null keys will nevertheless be listed here
* if they are available.)</p>
* <p>This field can be used to query the feature set of a camera device
* at a more granular level than capabilities. This is especially
* important for optional keys that are not listed under any capability
* in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
@@ -984,6 +1219,7 @@
* android.request.availableResultKeys (except that it applies for
* CameraCharacteristics instead of CaptureResult). See above for more
* details.</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<int[]> REQUEST_AVAILABLE_CHARACTERISTICS_KEYS =
@@ -994,6 +1230,7 @@
* camera device for output streams.</p>
* <p>All camera devices will support JPEG and YUV_420_888 formats.</p>
* <p>When set to YUV_420_888, application can access the YUV420 data directly.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1010,6 +1247,10 @@
* <p>When multiple streams are configured, the minimum
* frame duration will be >= max(individual stream min
* durations)</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * TODO: Remove property.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1021,6 +1262,9 @@
* <p>The JPEG resolutions that are supported by this camera device.</p>
* <p>The resolutions are listed as <code>(width, height)</code> pairs. All camera devices will support
* sensor maximum resolution (defined by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}).</p>
+ * <p><b>Range of valid values:</b><br>
+ * TODO: Remove property.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @deprecated
@@ -1033,13 +1277,19 @@
/**
* <p>The maximum ratio between both active area width
* and crop region width, and active area height and
- * crop region height.</p>
+ * crop region height, for {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.</p>
* <p>This represents the maximum amount of zooming possible by
* the camera device, or equivalently, the minimum cropping
* window size.</p>
* <p>Crop regions that have a width or height that is smaller
* than this ratio allows will be rounded up to the minimum
* allowed size by the camera device.</p>
+ * <p><b>Units</b>: Zoom scale factor</p>
+ * <p><b>Range of valid values:</b><br>
+ * >=1</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#SCALER_CROP_REGION
*/
@PublicKey
public static final Key<Float> SCALER_AVAILABLE_MAX_DIGITAL_ZOOM =
@@ -1054,6 +1304,8 @@
* set to FAST.</p>
* <p>When multiple streams are configured, the minimum frame duration will
* be >= max(individual stream min durations).</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1075,6 +1327,7 @@
* can provide.</p>
* <p>Please reference the documentation for the image data destination to
* check if it limits the maximum size for image data.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -1133,6 +1386,12 @@
* <p>Attempting to configure an input stream with output streams not
* listed as available in this map is not valid.</p>
* <p>TODO: typedef to ReprocessFormatMap</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<int[]> SCALER_AVAILABLE_INPUT_OUTPUT_FORMATS_MAP =
@@ -1220,6 +1479,7 @@
* </table>
* <p>Refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} for additional
* mandatory stream configurations on a per-capability basis.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -1244,6 +1504,8 @@
* calculating the max frame rate.</p>
* <p>(Keep in sync with
* StreamConfigurationMap#getOutputMinFrameDuration)</p>
+ * <p><b>Units</b>: (format, width, height, ns) x n</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#SENSOR_FRAME_DURATION
* @hide
@@ -1309,6 +1571,8 @@
* calculating the max frame rate (absent stalls).</p>
* <p>(Keep up to date with
* StreamConfigurationMap#getOutputStallDuration(int, Size) )</p>
+ * <p><b>Units</b>: (format, width, height, ns) x n</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @see CaptureRequest#SENSOR_FRAME_DURATION
@@ -1396,6 +1660,7 @@
* </table>
* <p>Refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} for additional
* mandatory stream configurations on a per-capability basis.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -1417,7 +1682,13 @@
* is inside of the active array. The camera device will apply the same crop region and
* return the final used crop region in capture result metadata {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.</p>
* <p>FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL) will support
- * FREEFORM cropping.</p>
+ * FREEFORM cropping. LEGACY capability devices will only support CENTER_ONLY cropping.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SCALER_CROPPING_TYPE_CENTER_ONLY CENTER_ONLY}</li>
+ * <li>{@link #SCALER_CROPPING_TYPE_FREEFORM FREEFORM}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SCALER_CROP_REGION
@@ -1430,22 +1701,41 @@
new Key<Integer>("android.scaler.croppingType", int.class);
/**
- * <p>Area of raw data which corresponds to only
+ * <p>The area of the image sensor which corresponds to
* active pixels.</p>
- * <p>It is smaller or equal to
- * sensor full pixel array, which could include the black calibration pixels.</p>
+ * <p>This is the region of the sensor that actually receives light from the scene.
+ * Therefore, the size of this region determines the maximum field of view and the maximum
+ * number of pixels that an image from this sensor can contain.</p>
+ * <p>The rectangle is defined in terms of the full pixel array; (0,0) is the top-left of the
+ * full pixel array, and the size of the full pixel array is given by
+ * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+ * <p>Most other keys listing pixel coordinates have their coordinate systems based on the
+ * active array, with <code>(0, 0)</code> being the top-left of the active array rectangle.</p>
+ * <p>The active array may be smaller than the full pixel array, since the full array may
+ * include black calibration pixels or other inactive regions.</p>
+ * <p><b>Units</b>: Pixel coordinates on the image sensor</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
*/
@PublicKey
public static final Key<android.graphics.Rect> SENSOR_INFO_ACTIVE_ARRAY_SIZE =
new Key<android.graphics.Rect>("android.sensor.info.activeArraySize", android.graphics.Rect.class);
/**
- * <p>Range of valid sensitivities.</p>
- * <p>The minimum and maximum valid values for the
- * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} control.</p>
+ * <p>Range of sensitivities for {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} supported by this
+ * camera device.</p>
* <p>The values are the standard ISO sensitivity values,
* as defined in ISO 12232:2006.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Min <= 100, Max >= 800</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SENSOR_SENSITIVITY
*/
@PublicKey
@@ -1456,6 +1746,20 @@
* <p>The arrangement of color filters on sensor;
* represents the colors in the top-left 2x2 section of
* the sensor, in reading order.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB RGGB}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG GRBG}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG GBRG}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_BGGR BGGR}</li>
+ * <li>{@link #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB RGB}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB
* @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG
* @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG
@@ -1467,11 +1771,17 @@
new Key<Integer>("android.sensor.info.colorFilterArrangement", int.class);
/**
- * <p>Range of valid exposure
- * times used by {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}.</p>
- * <p>The min value will be <= 100e3 (100 us). For FULL
+ * <p>The range of image exposure times for {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} supported
+ * by this camera device.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * The minimum exposure time will be less than 100 us. For FULL
* capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL),
- * max will be >= 100e6 (100ms)</p>
+ * the maximum exposure time will be greater than 100ms.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
@@ -1481,18 +1791,21 @@
new Key<android.util.Range<Long>>("android.sensor.info.exposureTimeRange", new TypeReference<android.util.Range<Long>>() {{ }});
/**
- * <p>Maximum possible frame duration (minimum frame
- * rate).</p>
- * <p>The largest possible {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
- * that will be accepted by the camera device. Attempting to use
- * frame durations beyond the maximum will result in the frame duration
- * being clipped to the maximum. See that control
- * for a full definition of frame durations.</p>
- * <p>Refer to
- * StreamConfigurationMap#getOutputMinFrameDuration(int,Size)
- * for the minimum frame duration values.</p>
- * <p>For FULL capability devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL),
- * max will be >= 100e6 (100ms).</p>
+ * <p>The maximum possible frame duration (minimum frame rate) for
+ * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} that is supported this camera device.</p>
+ * <p>Attempting to use frame durations beyond the maximum will result in the frame
+ * duration being clipped to the maximum. See that control for a full definition of frame
+ * durations.</p>
+ * <p>Refer to StreamConfigurationMap#getOutputMinFrameDuration(int,Size) for the minimum
+ * frame duration values.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * For FULL capability devices
+ * ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} == FULL), at least 100ms.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#SENSOR_FRAME_DURATION
@@ -1506,6 +1819,8 @@
* array.</p>
* <p>This is the physical size of the sensor pixel
* array defined by {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
*/
@@ -1514,7 +1829,7 @@
new Key<android.util.SizeF>("android.sensor.info.physicalSize", android.util.SizeF.class);
/**
- * <p>Dimensions of full pixel array, possibly
+ * <p>Dimensions of the full pixel array, possibly
* including black calibration pixels.</p>
* <p>The pixel count of the full pixel array,
* which covers {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area.</p>
@@ -1523,6 +1838,11 @@
* raw size listed in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}.
* If a size corresponding to pixelArraySize is listed, the resulting
* raw sensor image will include black pixels.</p>
+ * <p>Some parts of the full pixel array may not receive light from the scene,
+ * or are otherwise inactive. The {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} key
+ * defines the rectangle of active pixels that actually forms an image.</p>
+ * <p><b>Units</b>: Pixels</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -1538,11 +1858,14 @@
* sample values from the sensor. This is typically caused by the
* sensor becoming highly non-linear or clipping. The minimum for
* each channel is specified by the offset in the
- * {@link CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN android.sensor.blackLevelPattern} tag.</p>
+ * {@link CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN android.sensor.blackLevelPattern} key.</p>
* <p>The white level is typically determined either by sensor bit depth
* (8-14 bits is expected), or by the point where the sensor response
* becomes too non-linear to be useful. The default value for this is
* maximum representable value for a 16-bit raw sample (2^16 - 1).</p>
+ * <p><b>Range of valid values:</b><br>
+ * > 255 (8-bit output)</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN
*/
@@ -1556,6 +1879,12 @@
* may not based on a time source that can be compared to other system time sources.</p>
* <p>This characteristic defines the source for the timestamps, and therefore whether they
* can be compared against other system time sources/timestamps.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN UNKNOWN}</li>
+ * <li>{@link #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME REALTIME}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
* @see #SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN
* @see #SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME
*/
@@ -1568,15 +1897,38 @@
* calculating the {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 android.sensor.calibrationTransform1}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX1 android.sensor.forwardMatrix1} matrices.</p>
- * <p>The values in this tag correspond to the values defined for the
+ * <p>The values in this key correspond to the values defined for the
* EXIF LightSource tag. These illuminants are standard light sources
* that are often used calibrating camera devices.</p>
- * <p>If this tag is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
+ * <p>If this key is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 android.sensor.calibrationTransform1}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX1 android.sensor.forwardMatrix1} will also be present.</p>
* <p>Some devices may choose to provide a second set of calibration
* information for improved quality, including
* {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT2 android.sensor.referenceIlluminant2} and its corresponding matrices.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT DAYLIGHT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_FLUORESCENT FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_TUNGSTEN TUNGSTEN}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_FLASH FLASH}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_FINE_WEATHER FINE_WEATHER}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_CLOUDY_WEATHER CLOUDY_WEATHER}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_SHADE SHADE}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT_FLUORESCENT DAYLIGHT_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_DAY_WHITE_FLUORESCENT DAY_WHITE_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_COOL_WHITE_FLUORESCENT COOL_WHITE_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_WHITE_FLUORESCENT WHITE_FLUORESCENT}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_A STANDARD_A}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_B STANDARD_B}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_STANDARD_C STANDARD_C}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D55 D55}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D65 D65}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D75 D75}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_D50 D50}</li>
+ * <li>{@link #SENSOR_REFERENCE_ILLUMINANT1_ISO_STUDIO_TUNGSTEN ISO_STUDIO_TUNGSTEN}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1
* @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM1
@@ -1611,12 +1963,13 @@
* calculating the {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 android.sensor.calibrationTransform2}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX2 android.sensor.forwardMatrix2} matrices.</p>
- * <p>See {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1} for more details.
- * Valid values for this are the same as those given for the first
- * reference illuminant.</p>
- * <p>If this tag is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2},
+ * <p>See {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1} for more details.</p>
+ * <p>If this key is present, then {@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2},
* {@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 android.sensor.calibrationTransform2}, and
* {@link CameraCharacteristics#SENSOR_FORWARD_MATRIX2 android.sensor.forwardMatrix2} will also be present.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2
* @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM2
@@ -1763,13 +2116,15 @@
/**
* <p>A fixed black level offset for each of the color filter arrangement
* (CFA) mosaic channels.</p>
- * <p>This tag specifies the zero light value for each of the CFA mosaic
+ * <p>This key specifies the zero light value for each of the CFA mosaic
* channels in the camera sensor. The maximal value output by the
* sensor is represented by the value in {@link CameraCharacteristics#SENSOR_INFO_WHITE_LEVEL android.sensor.info.whiteLevel}.</p>
* <p>The values are given in the same order as channels listed for the CFA
- * layout tag (see {@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}), i.e. the
+ * layout key (see {@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}), i.e. the
* nth value given corresponds to the black level offset for the nth
* color channel listed in the CFA.</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0 for each.</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
@@ -1799,19 +2154,26 @@
new Key<Integer>("android.sensor.maxAnalogSensitivity", int.class);
/**
- * <p>Clockwise angle through which the output
- * image needs to be rotated to be upright on the device
- * screen in its native orientation. Also defines the
- * direction of rolling shutter readout, which is from top
- * to bottom in the sensor's coordinate system</p>
+ * <p>Clockwise angle through which the output image needs to be rotated to be
+ * upright on the device screen in its native orientation.</p>
+ * <p>Also defines the direction of rolling shutter readout, which is from top to bottom in
+ * the sensor's coordinate system.</p>
+ * <p><b>Units</b>: Degrees of clockwise rotation; always a multiple of
+ * 90</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0, 90, 180, 270</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Integer> SENSOR_ORIENTATION =
new Key<Integer>("android.sensor.orientation", int.class);
/**
- * <p>Lists the supported sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.</p>
- * <p>Optional. Defaults to [OFF].</p>
+ * <p>List of sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}
+ * supported by this camera device.</p>
+ * <p>Defaults to OFF, and always includes OFF if defined.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureRequest#SENSOR_TEST_PATTERN_MODE
@@ -1821,15 +2183,14 @@
new Key<int[]>("android.sensor.availableTestPatternModes", int[].class);
/**
- * <p>The face detection modes that are available
- * for this camera device.</p>
+ * <p>List of face detection modes for {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} that are
+ * supported by this camera device.</p>
* <p>OFF is always supported.</p>
- * <p>SIMPLE means the device supports the
- * android.statistics.faceRectangles and
- * android.statistics.faceScores outputs.</p>
- * <p>FULL means the device additionally supports the
- * android.statistics.faceIds and
- * android.statistics.faceLandmarks outputs.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
@PublicKey
public static final Key<int[]> STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES =
@@ -1838,17 +2199,25 @@
/**
* <p>The maximum number of simultaneously detectable
* faces.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0 for cameras without available face detection; otherwise:
+ * <code>>=4</code> for LIMITED or FULL hwlevel devices or
+ * <code>>0</code> for LEGACY devices.</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Integer> STATISTICS_INFO_MAX_FACE_COUNT =
new Key<Integer>("android.statistics.info.maxFaceCount", int.class);
/**
- * <p>The set of hot pixel map output modes supported by this camera device.</p>
- * <p>This tag lists valid output modes for {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode}.</p>
- * <p>If no hotpixel map is available for this camera device, this will contain
- * only OFF. If the hotpixel map is available, this will include both
- * the ON and OFF options.</p>
+ * <p>List of hot pixel map output modes for {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode} that are
+ * supported by this camera device.</p>
+ * <p>If no hotpixel map output is available for this camera device, this will contain only
+ * <code>false</code>.</p>
+ * <p>ON is always supported on devices with the RAW capability.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE android.statistics.hotPixelMapMode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE
*/
@@ -1859,14 +2228,18 @@
/**
* <p>Maximum number of supported points in the
* tonemap curve that can be used for {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.</p>
- * <p>If the actual number of points provided by the application (in
- * {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}*) is less than max, the camera device will
- * resample the curve to its internal representation, using linear
- * interpolation.</p>
+ * <p>If the actual number of points provided by the application (in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}*) is
+ * less than this maximum, the camera device will resample the curve to its internal
+ * representation, using linear interpolation.</p>
* <p>The output curves in the result metadata may have a different number
* of points than the input curves, and will represent the actual
* hardware curves used as closely as possible when linearly interpolated.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_CURVE
*/
@PublicKey
@@ -1874,11 +2247,18 @@
new Key<Integer>("android.tonemap.maxCurvePoints", int.class);
/**
- * <p>The set of tonemapping modes supported by this camera device.</p>
- * <p>This tag lists the valid modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}.</p>
- * <p>Full-capability camera devices must always support CONTRAST_CURVE and
- * FAST.</p>
+ * <p>List of tonemapping modes for {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} that are supported by this camera
+ * device.</p>
+ * <p>Camera devices that support the MANUAL_POST_PROCESSING capability will always list
+ * CONTRAST_CURVE and FAST. This includes all FULL level devices.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any value listed in {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
*/
@PublicKey
@@ -1887,6 +2267,11 @@
/**
* <p>A list of camera LEDs that are available on this system.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LED_AVAILABLE_LEDS_TRANSMIT TRANSMIT}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @see #LED_AVAILABLE_LEDS_TRANSMIT
* @hide
*/
@@ -1895,8 +2280,8 @@
/**
* <p>Generally classifies the overall set of the camera device functionality.</p>
- * <p>Camera devices will come in two flavors: LIMITED and FULL.</p>
- * <p>A FULL device has the most support possible and will support below capabilities:</p>
+ * <p>Camera devices will come in three flavors: LEGACY, LIMITED and FULL.</p>
+ * <p>A FULL device will support below capabilities:</p>
* <ul>
* <li>30fps at maximum resolution (== sensor resolution) is preferred, more than 20fps is required.</li>
* <li>Per frame control ({@link CameraCharacteristics#SYNC_MAX_LATENCY android.sync.maxLatency} <code>==</code> PER_FRAME_CONTROL)</li>
@@ -1910,14 +2295,38 @@
* </ul>
* <p>A LIMITED device may have some or none of the above characteristics.
* To find out more refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.</p>
+ * <p>Some features are not part of any particular hardware level or capability and must be
+ * queried separately. These include:</p>
+ * <ul>
+ * <li>Calibrated timestamps ({@link CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE android.sensor.info.timestampSource} <code>==</code> REALTIME)</li>
+ * <li>Precision lens control ({@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} <code>==</code> CALIBRATED)</li>
+ * <li>Face detection ({@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes})</li>
+ * <li>Optical or electrical image stabilization
+ * ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization},
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES android.control.availableVideoStabilizationModes})</li>
+ * </ul>
* <p>A LEGACY device does not support per-frame control, manual sensor control, manual
* post-processing, arbitrary cropping regions, and has relaxed performance constraints.</p>
+ * <p>Each higher level supports everything the lower level supports
+ * in this order: FULL <code>></code> LIMITED <code>></code> LEGACY.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}</li>
+ * <li>{@link #INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}</li>
+ * <li>{@link #INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES
+ * @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @see CameraCharacteristics#REQUEST_MAX_NUM_OUTPUT_PROC
* @see CameraCharacteristics#SCALER_CROPPING_TYPE
* @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE
* @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION
+ * @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE
+ * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
* @see CameraCharacteristics#SYNC_MAX_LATENCY
* @see #INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED
* @see #INFO_SUPPORTED_HARDWARE_LEVEL_FULL
@@ -1959,6 +2368,15 @@
* <p>Since <code>result4</code> has a <code>frameNumber == 4</code> and
* <code>android.sync.frameNumber == 2</code>, the distance is clearly
* <code>4 - 2 = 2</code>.</p>
+ * <p><b>Units</b>: Frame counts</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SYNC_MAX_LATENCY_PER_FRAME_CONTROL PER_FRAME_CONTROL}</li>
+ * <li>{@link #SYNC_MAX_LATENCY_UNKNOWN UNKNOWN}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * A positive value, PER_FRAME_CONTROL, or UNKNOWN.</p>
+ * <p>This key is available on all devices.</p>
* @see #SYNC_MAX_LATENCY_PER_FRAME_CONTROL
* @see #SYNC_MAX_LATENCY_UNKNOWN
*/
@@ -1970,4 +2388,6 @@
* End generated code
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
+
+
}
diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index a57b361..16df844 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -418,11 +418,11 @@
* <ul>
* <li>RAW_SENSOR is supported as an output format.</li>
* <li>The maximum available resolution for RAW_SENSOR streams
- * will match either the value in
- * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize} or
- * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</li>
+ * will match either the value in
+ * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize} or
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</li>
* <li>All DNG-related optional metadata entries are provided
- * by the camera device.</li>
+ * by the camera device.</li>
* </ul>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -437,13 +437,13 @@
* <li>At least one input stream can be used.</li>
* <li>RAW_OPAQUE is supported as an output/input format</li>
* <li>Using RAW_OPAQUE does not cause a frame rate drop
- * relative to the sensor's maximum capture rate (at that
- * resolution).</li>
+ * relative to the sensor's maximum capture rate (at that
+ * resolution).</li>
* <li>RAW_OPAQUE will be reprocessable into both YUV_420_888
- * and JPEG formats.</li>
+ * and JPEG formats.</li>
* <li>The maximum available resolution for RAW_OPAQUE streams
- * (both input/output) will match the maximum available
- * resolution of JPEG streams.</li>
+ * (both input/output) will match the maximum available
+ * resolution of JPEG streams.</li>
* </ul>
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
* @hide
@@ -807,6 +807,8 @@
* {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} are used by the camera
* device, along with android.flash.* fields, if there's
* a flash unit for this camera device.</p>
+ * <p>LEGACY devices do not support the OFF mode and will
+ * override attempts to use this value to ON.</p>
*
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
* @see CaptureRequest#SENSOR_FRAME_DURATION
@@ -1213,8 +1215,7 @@
* image while recording video) use case.</p>
* <p>The camera device should take the highest-quality image
* possible (given the other settings) without disrupting the
- * frame rate of video recording.<br />
- * </p>
+ * frame rate of video recording. </p>
* @see CaptureRequest#CONTROL_CAPTURE_INTENT
*/
public static final int CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT = 4;
@@ -1577,6 +1578,8 @@
/**
* <p>Turn on custom high dynamic range (HDR) mode.</p>
+ * <p>This is intended for LEGACY mode devices only;
+ * HAL3+ camera devices should not implement this mode.</p>
* @see CaptureRequest#CONTROL_SCENE_MODE
* @hide
*/
@@ -1862,8 +1865,6 @@
/**
* <p>Return face rectangle and confidence values only.</p>
- * <p>In this mode, only android.statistics.faceRectangles and
- * android.statistics.faceScores outputs are valid.</p>
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
public static final int STATISTICS_FACE_DETECT_MODE_SIMPLE = 1;
@@ -1871,11 +1872,7 @@
/**
* <p>Return all face
* metadata.</p>
- * <p>In this mode,
- * android.statistics.faceRectangles,
- * android.statistics.faceScores,
- * android.statistics.faceIds, and
- * android.statistics.faceLandmarks outputs are valid.</p>
+ * <p>In this mode, face rectangles, scores, landmarks, and face IDs are all valid.</p>
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
public static final int STATISTICS_FACE_DETECT_MODE_FULL = 2;
@@ -2064,6 +2061,8 @@
* and may restart scanning at any time.</p>
* <p>Only used by CONTINUOUS_* AF modes. This is a transient state, the camera
* device may skip reporting this state in capture result.</p>
+ * <p>LEGACY camera devices do not support this state. When a passive
+ * scan has finished, it will always go to PASSIVE_FOCUSED.</p>
* @see CaptureResult#CONTROL_AF_STATE
*/
public static final int CONTROL_AF_STATE_PASSIVE_UNFOCUSED = 6;
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index 93eb3de..6aec72a 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -476,7 +476,6 @@
* modify the comment blocks at the start or end.
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
-
/**
* <p>The mode control selects how the image data is converted from the
* sensor's native color into linear sRGB color.</p>
@@ -518,10 +517,21 @@
* </code></pre>
* <p>Both the input and output value ranges must match. Overflow/underflow
* values are clipped to fit within the range.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX TRANSFORM_MATRIX}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX
* @see #COLOR_CORRECTION_MODE_FAST
* @see #COLOR_CORRECTION_MODE_HIGH_QUALITY
@@ -542,8 +552,14 @@
* in this matrix result metadata. The transform should keep the magnitude
* of the output color values within <code>[0, 1.0]</code> (assuming input color
* values is within the normalized range <code>[0, 1.0]</code>), or clipping may occur.</p>
+ * <p><b>Units</b>: Unitless scale factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.ColorSpaceTransform> COLOR_CORRECTION_TRANSFORM =
@@ -559,8 +575,14 @@
* TRANSFORM_MATRIX.</p>
* <p>The gains in the result metadata are the gains actually
* applied by the camera device to the current frame.</p>
+ * <p><b>Units</b>: Unitless gain factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.RggbChannelVector> COLOR_CORRECTION_GAINS =
@@ -568,8 +590,6 @@
/**
* <p>Mode of operation for the chromatic aberration correction algorithm.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}.</p>
* <p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
* can not focus on the same point after exiting from the lens. This metadata defines
* the high level control of chromatic aberration correction algorithm, which aims to
@@ -580,6 +600,16 @@
* use the highest-quality aberration correction algorithms, even if it slows down
* capture rate. FAST means the camera device will not slow down capture rate when
* applying aberration correction.</p>
+ * <p>LEGACY devices will always be in FAST mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_OFF OFF}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES
* @see #COLOR_CORRECTION_ABERRATION_MODE_OFF
@@ -612,7 +642,7 @@
* options for the antibanding mode. The
* {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes} key contains
* the available modes for a given camera device.</p>
- * <p>The default mode is AUTO, which must be supported by all
+ * <p>The default mode is AUTO, which is supported by all
* camera devices.</p>
* <p>If manual exposure control is enabled (by setting
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} to OFF),
@@ -620,6 +650,16 @@
* ensure it selects exposure times that do not cause banding
* issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
* the application in this.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_50HZ 50HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_60HZ 60HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_AUTO AUTO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br></p>
+ * <p>{@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
* @see CaptureRequest#CONTROL_AE_MODE
@@ -652,6 +692,10 @@
* state. Once the new exposure target is reached, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} will
* change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
* FLASH_REQUIRED (if the scene is too dark for still capture).</p>
+ * <p><b>Units</b>: Compensation steps</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
@@ -666,9 +710,11 @@
/**
* <p>Whether auto-exposure (AE) is currently locked to its latest
* calculated values.</p>
- * <p>Note that even when AE is locked, the flash may be
- * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
- * ON_AUTO_FLASH_REDEYE.</p>
+ * <p>When set to <code>true</code> (ON), the AE algorithm is locked to its latest parameters,
+ * and will not change exposure settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Note that even when AE is locked, the flash may be fired if
+ * the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH /
+ * ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE.</p>
* <p>When {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} is changed, even if the AE lock
* is ON, the camera device will still adjust its exposure value.</p>
* <p>If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger})
@@ -677,7 +723,21 @@
* parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}
* is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AE updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AE mode:</li>
+ * <li>Lock AE</li>
+ * <li>Wait for the first result to be output that has the AE locked</li>
+ * <li>Copy exposure settings from that result into a request, set the request to manual AE</li>
+ * <li>Submit the capture request, proceed to run manual AE as desired.</li>
+ * </ol>
* <p>See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
* @see CaptureRequest#CONTROL_AE_MODE
@@ -711,7 +771,19 @@
* camera device auto-exposure routine for the overridden
* fields for a given capture will be available in its
* CaptureResult.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON ON}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH ON_AUTO_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES android.control.aeAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#FLASH_INFO_AVAILABLE
* @see CaptureRequest#FLASH_MODE
@@ -729,25 +801,35 @@
new Key<Integer>("android.control.aeMode", int.class);
/**
- * <p>List of areas to use for
- * metering.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
+ * <p>List of metering areas to use for auto-exposure adjustment.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other exposure metering regions, so if only one
+ * region is used, all non-zero weights will have the same effect. A region with 0
+ * weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE
@@ -759,12 +841,20 @@
new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class);
/**
- * <p>Range over which fps can be adjusted to
- * maintain exposure.</p>
+ * <p>Range over which the auto-exposure routine can
+ * adjust the capture frame rate to maintain good
+ * exposure.</p>
* <p>Only constrains auto-exposure (AE) algorithm, not
- * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
+ * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} and
+ * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}.</p>
+ * <p><b>Units</b>: Frames per second (FPS)</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any of the entries in {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES android.control.aeAvailableTargetFpsRanges}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
+ * @see CaptureRequest#SENSOR_FRAME_DURATION
*/
@PublicKey
public static final Key<android.util.Range<Integer>> CONTROL_AE_TARGET_FPS_RANGE =
@@ -789,8 +879,22 @@
* depends on the current AE mode and state; see
* {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
* details.</p>
+ * <p>On LEGACY-level devices, the precapture trigger is not supported;
+ * capturing a high-resolution JPEG image will automatically trigger a
+ * precapture sequence before the high-resolution capture, including
+ * potentially firing a pre-capture flash.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureResult#CONTROL_AE_STATE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_START
*/
@@ -806,7 +910,20 @@
* <p>If the lens is controlled by the camera device auto-focus algorithm,
* the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
* in result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AF_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AF_MODE_MACRO MACRO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_VIDEO CONTINUOUS_VIDEO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_PICTURE CONTINUOUS_PICTURE}</li>
+ * <li>{@link #CONTROL_AF_MODE_EDOF EDOF}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES android.control.afAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES
* @see CaptureResult#CONTROL_AF_STATE
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
@@ -822,25 +939,35 @@
new Key<Integer>("android.control.afMode", int.class);
/**
- * <p>List of areas to use for focus
- * estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
+ * <p>List of metering areas to use for auto-focus.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of focus areas supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other metering regions, so if only one region
+ * is used, all non-zero weights will have the same effect. A region with 0 weight is
+ * ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF
@@ -864,6 +991,13 @@
* START for multiple captures in a row means restarting the AF operation over
* and over again.</p>
* <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_START START}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_CANCEL CANCEL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureResult#CONTROL_AF_STATE
* @see #CONTROL_AF_TRIGGER_IDLE
@@ -877,9 +1011,26 @@
/**
* <p>Whether auto-white balance (AWB) is currently locked to its
* latest calculated values.</p>
+ * <p>When set to <code>true</code> (ON), the AWB algorithm is locked to its latest parameters,
+ * and will not change color balance settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AWB updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AWB mode:</li>
+ * <li>Lock AWB</li>
+ * <li>Wait for the first result to be output that has the AWB locked</li>
+ * <li>Copy AWB settings from that result into a request, set the request to manual AWB</li>
+ * <li>Submit the capture request, proceed to run manual AWB as desired.</li>
+ * </ol>
* <p>Note that AWB lock is only meaningful when
* {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is in the AUTO mode; in other modes,
* AWB is already fixed to a specific setting.</p>
+ * <p>Some LEGACY devices may not support ON; the value is then overridden to OFF.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AWB_MODE
*/
@@ -907,10 +1058,26 @@
* {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform},
* {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
* {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} are ignored.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AWB_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AWB_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AWB_MODE_INCANDESCENT INCANDESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_FLUORESCENT FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_WARM_FLUORESCENT WARM_FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_DAYLIGHT DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT CLOUDY_DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_TWILIGHT TWILIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_SHADE SHADE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES android.control.awbAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_MODE
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+ * @see CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see #CONTROL_AWB_MODE_OFF
* @see #CONTROL_AWB_MODE_AUTO
@@ -927,10 +1094,12 @@
new Key<Integer>("android.control.awbMode", int.class);
/**
- * <p>List of areas to use for illuminant
+ * <p>List of metering areas to use for auto-white-balance illuminant
* estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
@@ -941,11 +1110,20 @@
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other white balance metering regions, so if
+ * only one region is used, all non-zero weights will have the same effect. A region with
+ * 0 weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB
@@ -965,7 +1143,18 @@
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p>
* <p>ZERO_SHUTTER_LAG will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
* contains ZSL. MANUAL will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
- * contains MANUAL_SENSOR.</p>
+ * contains MANUAL_SENSOR. Other intent values are always supported.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_CUSTOM CUSTOM}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_PREVIEW PREVIEW}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_STILL_CAPTURE STILL_CAPTURE}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_RECORD VIDEO_RECORD}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT VIDEO_SNAPSHOT}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ZERO_SHUTTER_LAG}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_MANUAL MANUAL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -989,10 +1178,23 @@
* implementor of the camera device, and should not be
* depended on to be consistent (or present) across all
* devices.</p>
- * <p>A color effect will only be applied if
- * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_EFFECT_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_MONO MONO}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_NEGATIVE NEGATIVE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SOLARIZE SOLARIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SEPIA SEPIA}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_POSTERIZE POSTERIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_WHITEBOARD WHITEBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_BLACKBOARD BLACKBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_AQUA AQUA}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS android.control.availableEffects}</p>
+ * <p>This key is available on all devices.</p>
*
- * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS
* @see #CONTROL_EFFECT_MODE_OFF
* @see #CONTROL_EFFECT_MODE_MONO
* @see #CONTROL_EFFECT_MODE_NEGATIVE
@@ -1008,9 +1210,9 @@
new Key<Integer>("android.control.effectMode", int.class);
/**
- * <p>Overall mode of 3A control
+ * <p>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control
* routines.</p>
- * <p>High-level 3A control. When set to OFF, all 3A control
+ * <p>This is a top-level 3A control switch. When set to OFF, all 3A control
* by the camera device is disabled. The application must set the fields for
* capture parameters itself.</p>
* <p>When set to AUTO, the individual algorithm controls in
@@ -1025,6 +1227,18 @@
* update, as if this frame is never captured. This mode can be used in the scenario
* where the application doesn't want a 3A manual control capture to affect
* the subsequent auto 3A capture results.</p>
+ * <p>LEGACY mode devices will only support AUTO and USE_SCENE_MODE modes.
+ * LIMITED mode devices will only support OFF and OFF_KEEP_STATE if they
+ * support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities.
+ * FULL mode devices will always support OFF and OFF_KEEP_STATE.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_MODE_USE_SCENE_MODE USE_SCENE_MODE}</li>
+ * <li>{@link #CONTROL_MODE_OFF_KEEP_STATE OFF_KEEP_STATE}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
* @see #CONTROL_MODE_OFF
@@ -1037,18 +1251,41 @@
new Key<Integer>("android.control.mode", int.class);
/**
- * <p>A camera mode optimized for conditions typical in a particular
- * capture setting.</p>
+ * <p>Control for which scene mode is currently active.</p>
+ * <p>Scene modes are custom camera modes optimized for a certain set of conditions and
+ * capture settings.</p>
* <p>This is the mode that that is active when
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code>. Aside from FACE_PRIORITY,
* these modes will disable {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
- * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.
- * The scene modes available for a given camera device are listed in
- * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}.</p>
+ * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.</p>
* <p>The interpretation and implementation of these scene modes is left
* to the implementor of the camera device. Their behavior will not be
* consistent across all devices, and any given device may only implement
* a subset of these modes.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_SCENE_MODE_DISABLED DISABLED}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FACE_PRIORITY FACE_PRIORITY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_ACTION ACTION}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PORTRAIT PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_LANDSCAPE LANDSCAPE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT NIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT_PORTRAIT NIGHT_PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_THEATRE THEATRE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BEACH BEACH}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SNOW SNOW}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SUNSET SUNSET}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_STEADYPHOTO STEADYPHOTO}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FIREWORKS FIREWORKS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SPORTS SPORTS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PARTY PARTY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_CANDLELIGHT CANDLELIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BARCODE BARCODE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AF_MODE
@@ -1081,18 +1318,26 @@
/**
* <p>Whether video stabilization is
* active.</p>
- * <p>Video stabilization automatically translates and scales images from the camera
- * in order to stabilize motion between consecutive frames.</p>
+ * <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>
- * <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>
+ * <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>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
* @see CaptureRequest#SCALER_CROP_REGION
@@ -1106,16 +1351,28 @@
/**
* <p>Operation mode for edge
* enhancement.</p>
- * <p>Edge/sharpness/detail enhancement. OFF means no
- * enhancement will be applied by the camera device.</p>
- * <p>This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.</p>
+ * <p>Edge enhancement improves sharpness and details in the captured image. OFF means
+ * no enhancement will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
* will be applied. HIGH_QUALITY mode indicates that the
* camera device will use the highest-quality enhancement algorithms,
* even if it slows down capture rate. FAST means the camera device will
* not slow down capture rate when applying edge enhancement.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #EDGE_MODE_OFF OFF}</li>
+ * <li>{@link #EDGE_MODE_FAST FAST}</li>
+ * <li>{@link #EDGE_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #EDGE_MODE_OFF
* @see #EDGE_MODE_FAST
* @see #EDGE_MODE_HIGH_QUALITY
@@ -1139,6 +1396,13 @@
* <p>When set to TORCH, the flash will be on continuously. This mode can be used
* for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
* <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #FLASH_MODE_OFF OFF}</li>
+ * <li>{@link #FLASH_MODE_SINGLE SINGLE}</li>
+ * <li>{@link #FLASH_MODE_TORCH TORCH}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
@@ -1153,12 +1417,19 @@
new Key<Integer>("android.flash.mode", int.class);
/**
- * <p>Set operational mode for hot pixel correction.</p>
- * <p>Valid modes for this camera device are listed in
- * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
+ * <p>Operational mode for hot pixel correction.</p>
* <p>Hotpixel correction interpolates out, or otherwise removes, pixels
- * that do not accurately encode the incoming light (i.e. pixels that
- * are stuck at an arbitrary value).</p>
+ * that do not accurately measure the incoming light (i.e. pixels that
+ * are stuck at an arbitrary value or are oversensitive).</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #HOT_PIXEL_MODE_OFF OFF}</li>
+ * <li>{@link #HOT_PIXEL_MODE_FAST FAST}</li>
+ * <li>{@link #HOT_PIXEL_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
* @see #HOT_PIXEL_MODE_OFF
@@ -1171,6 +1442,10 @@
/**
* <p>A location object to use when generating image GPS metadata.</p>
+ * <p>Setting a location object in a request will include the GPS coordinates of the location
+ * into any JPEG images captured based on the request. These coordinates can then be
+ * viewed by anyone who receives the JPEG image.</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
@SyntheticKey
@@ -1179,7 +1454,10 @@
/**
* <p>GPS coordinates to include in output JPEG
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * (-180 - 180], [-90,90], [-inf, inf]</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<double[]> JPEG_GPS_COORDINATES =
@@ -1187,7 +1465,9 @@
/**
* <p>32 characters describing GPS algorithm to
- * include in EXIF</p>
+ * include in EXIF.</p>
+ * <p><b>Units</b>: UTF-8 null-terminated string</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
@@ -1195,15 +1475,49 @@
/**
* <p>Time GPS fix was made to include in
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Units</b>: UTC in seconds since January 1, 1970</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<Long> JPEG_GPS_TIMESTAMP =
new Key<Long>("android.jpeg.gpsTimestamp", long.class);
/**
- * <p>Orientation of JPEG image to
- * write</p>
+ * <p>The orientation for a JPEG image.</p>
+ * <p>The clockwise rotation angle in degrees, relative to the orientation
+ * to the camera, that the JPEG picture needs to be rotated by, to be viewed
+ * upright.</p>
+ * <p>Camera devices may either encode this value into the JPEG EXIF header, or
+ * rotate the image data to match this orientation.</p>
+ * <p>Note that this orientation is relative to the orientation of the camera sensor, given
+ * by {@link CameraCharacteristics#SENSOR_ORIENTATION android.sensor.orientation}.</p>
+ * <p>To translate from the device orientation given by the Android sensor APIs, the following
+ * sample code may be used:</p>
+ * <pre><code>private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) {
+ * if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0;
+ * int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION);
+ *
+ * // Round device orientation to a multiple of 90
+ * deviceOrientation = (deviceOrientation + 45) / 90 * 90;
+ *
+ * // Reverse device orientation for front-facing cameras
+ * boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT;
+ * if (facingFront) deviceOrientation = -deviceOrientation;
+ *
+ * // Calculate desired JPEG orientation relative to camera orientation to make
+ * // the image upright relative to the device orientation
+ * int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+ *
+ * return jpegOrientation;
+ * }
+ * </code></pre>
+ * <p><b>Units</b>: Degrees in multiples of 90</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0, 90, 180, 270</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_ORIENTATION
*/
@PublicKey
public static final Key<Integer> JPEG_ORIENTATION =
@@ -1213,6 +1527,9 @@
* <p>Compression quality of the final JPEG
* image.</p>
* <p>85-95 is typical usage range.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_QUALITY =
@@ -1221,6 +1538,9 @@
/**
* <p>Compression quality of JPEG
* thumbnail.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
@@ -1230,25 +1550,29 @@
* <p>Resolution of embedded JPEG thumbnail.</p>
* <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
* but the captured JPEG will still be a valid image.</p>
- * <p>When a jpeg image capture is issued, the thumbnail size selected should have
- * the same aspect ratio as the jpeg image.</p>
+ * <p>For best results, when issuing a request for a JPEG image, the thumbnail size selected
+ * should have the same aspect ratio as the main JPEG output.</p>
* <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
* ratio, the camera device creates the thumbnail by cropping it from the primary image.
* For example, if the primary image has 4:3 aspect ratio, the thumbnail image has
* 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to
* generate the thumbnail image. The thumbnail image will always have a smaller Field
* Of View (FOV) than the primary image when aspect ratios differ.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES android.jpeg.availableThumbnailSizes}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES
*/
@PublicKey
public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
new Key<android.util.Size>("android.jpeg.thumbnailSize", android.util.Size.class);
/**
- * <p>The ratio of lens focal length to the effective
- * aperture diameter.</p>
- * <p>This will only be supported on the camera devices that
- * have variable aperture lens. The aperture value can only be
- * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
+ * <p>The desired lens aperture size, as a ratio of lens focal length to the
+ * effective aperture diameter.</p>
+ * <p>Setting this value is only supported on the camera devices that have a variable
+ * aperture lens.</p>
* <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
* this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
* {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
@@ -1261,8 +1585,16 @@
* the ON modes, this will be overridden by the camera device
* auto-exposure algorithm, the overridden values are then provided
* back to the user in the corresponding result.</p>
+ * <p><b>Units</b>: The f-number (f/N)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
* @see CaptureResult#LENS_STATE
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
@@ -1274,10 +1606,8 @@
new Key<Float>("android.lens.aperture", float.class);
/**
- * <p>State of lens neutral density filter(s).</p>
- * <p>This will not be supported on most camera devices. On devices
- * where this is supported, this may only be set to one of the
- * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
+ * <p>The desired setting for the lens neutral density filter(s).</p>
+ * <p>This control will not be supported on most camera devices.</p>
* <p>Lens filters are typically used to lower the amount of light the
* sensor is exposed to (measured in steps of EV). As used here, an EV
* step is the standard logarithmic representation, which are
@@ -1289,7 +1619,15 @@
* <p>It may take several frames before the lens filter density changes
* to the requested value. While the filter density is still changing,
* {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
+ * <p><b>Units</b>: Exposure Value (EV)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
* @see CaptureResult#LENS_STATE
*/
@@ -1298,7 +1636,7 @@
new Key<Float>("android.lens.filterDensity", float.class);
/**
- * <p>The current lens focal length; used for optical zoom.</p>
+ * <p>The desired lens focal length; used for optical zoom.</p>
* <p>This setting controls the physical focal length of the camera
* device's lens. Changing the focal length changes the field of
* view of the camera device, and is usually used for optical zoom.</p>
@@ -1307,10 +1645,15 @@
* frames before the lens can change to the requested focal length.
* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
* be set to MOVING.</p>
- * <p>This is expected not to be supported on most devices.</p>
+ * <p>Optical zoom will not be supported on most devices.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_APERTURE
* @see CaptureRequest#LENS_FOCUS_DISTANCE
+ * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS
* @see CaptureResult#LENS_STATE
*/
@PublicKey
@@ -1318,16 +1661,30 @@
new Key<Float>("android.lens.focalLength", float.class);
/**
- * <p>Distance to plane of sharpest focus,
+ * <p>Desired distance to plane of sharpest focus,
* measured from frontmost surface of the lens.</p>
- * <p>0 means infinity focus. Used value will be clamped
- * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].</p>
+ * <p>This control can be used for setting manual focus, on devices that support
+ * the MANUAL_SENSOR capability and have a variable-focus lens (see
+ * {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}).</p>
+ * <p>A value of <code>0.0f</code> means infinity focus. The value set will be clamped to
+ * <code>[0.0f, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}]</code>.</p>
* <p>Like {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, this setting won't be applied
* instantaneously, and it may take several frames before the lens
* can move to the requested focus distance. While the lens is still moving,
* {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
+ * <p>LEGACY devices support at most setting this to <code>0.0f</code>
+ * for infinity focus.</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_FOCAL_LENGTH
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
* @see CaptureResult#LENS_STATE
*/
@@ -1349,14 +1706,26 @@
* 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>If a camera device supports both OIS and digital image stabilization
+ * ({@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>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION
* @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
* @see #LENS_OPTICAL_STABILIZATION_MODE_ON
@@ -1367,16 +1736,28 @@
/**
* <p>Mode of operation for the noise reduction algorithm.</p>
- * <p>Noise filtering control. OFF means no noise reduction
- * will be applied by the camera device.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</p>
+ * <p>The noise reduction algorithm attempts to improve image quality by removing
+ * excessive noise added by the capture process, especially in dark conditions.
+ * OFF means no noise reduction will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
* will be applied. HIGH_QUALITY mode indicates that the camera device
* will use the highest-quality noise filtering algorithms,
* even if it slows down capture rate. FAST means the camera device will not
* slow down capture rate when applying noise filtering.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #NOISE_REDUCTION_MODE_OFF OFF}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_FAST FAST}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
* @see #NOISE_REDUCTION_MODE_OFF
* @see #NOISE_REDUCTION_MODE_FAST
@@ -1390,13 +1771,18 @@
* <p>An application-specified ID for the current
* request. Must be maintained unchanged in output
* frame</p>
+ * <p><b>Units</b>: arbitrary integer assigned by application</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any int</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Integer> REQUEST_ID =
new Key<Integer>("android.request.id", int.class);
/**
- * <p>The region of the sensor to read out for this capture.</p>
+ * <p>The desired region of the sensor to read out for this capture.</p>
+ * <p>This control can be used to implement digital zoom.</p>
* <p>The crop region coordinate system is based off
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the
* top-left corner of the sensor active array.</p>
@@ -1426,6 +1812,9 @@
* for rounding and other hardware requirements; the final
* crop region used will be included in the output capture
* result.</p>
+ * <p><b>Units</b>: Pixel coordinates relative to
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -1437,8 +1826,23 @@
/**
* <p>Duration each pixel is exposed to
* light.</p>
- * <p>If the sensor can't expose this exact duration, it should shorten the
- * duration exposed to the nearest possible value (rather than expose longer).</p>
+ * <p>If the sensor can't expose this exact duration, it will shorten the
+ * duration exposed to the nearest possible value (rather than expose longer).
+ * The final exposure time used will be available in the output capture result.</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE
*/
@PublicKey
public static final Key<Long> SENSOR_EXPOSURE_TIME =
@@ -1516,8 +1920,23 @@
* delivered.</p>
* <p>For more details about stalling, see
* StreamConfigurationMap#getOutputStallDuration(int,Size).</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * See {@link CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION android.sensor.info.maxFrameDuration},
+ * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}. The duration
+ * is capped to <code>max(duration, exposureTime + overhead)</code>.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
+ * @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION
*/
@PublicKey
public static final Key<Long> SENSOR_FRAME_DURATION =
@@ -1535,7 +1954,15 @@
* requested, it will reduce the gain to the nearest supported
* value. The final sensitivity used will be available in the
* output capture result.</p>
+ * <p><b>Units</b>: ISO arithmetic units</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE
* @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY
*/
@@ -1569,7 +1996,21 @@
* <p>For example, if manual flash is enabled, flash firing should still
* occur (and that the test pattern remain unmodified, since the flash
* would not actually affect it).</p>
+ * <p>Defaults to OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_OFF OFF}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR SOLID_COLOR}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS COLOR_BARS}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY COLOR_BARS_FADE_TO_GRAY}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_PN9 PN9}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_CUSTOM1 CUSTOM1}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES
* @see #SENSOR_TEST_PATTERN_MODE_OFF
* @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
* @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
@@ -1587,30 +2028,41 @@
* <p>When set to OFF mode, no lens shading correction will be applied by the
* camera device, and an identity lens shading map data will be provided
* if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
- * shading map with size specified as <code>android.lens.info.shadingMapSize = [ 4, 3 ]</code>,
- * the output android.statistics.lensShadingMap for this case will be an identity map
- * shown below:</p>
+ * shading map with size of <code>[ 4, 3 ]</code>,
+ * the output {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap} for this case will be an identity
+ * map shown below:</p>
* <pre><code>[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
* </code></pre>
- * <p>When set to other modes, lens shading correction will be applied by the
- * camera device. Applications can request lens shading map data by setting
- * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
- * lens shading map data in android.statistics.lensShadingMap, with size specified
- * by android.lens.info.shadingMapSize; the returned shading map data will be the one
- * applied by the camera device for this capture request.</p>
- * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
- * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
- * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF),
- * to get best results, it is recommended that the applications wait for the AE and AWB to
- * be converged before using the returned shading map data.</p>
+ * <p>When set to other modes, lens shading correction will be applied by the camera
+ * device. Applications can request lens shading map data by setting
+ * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide lens
+ * shading map data in {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap}; the returned shading map
+ * data will be the one applied by the camera device for this capture request.</p>
+ * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore
+ * the reliability of the map data may be affected by the AE and AWB algorithms. When AE and
+ * AWB are in AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code>
+ * OFF), to get best results, it is recommended that the applications wait for the AE and AWB
+ * to be converged before using the returned shading map data.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SHADING_MODE_OFF OFF}</li>
+ * <li>{@link #SHADING_MODE_FAST FAST}</li>
+ * <li>{@link #SHADING_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP
* @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
* @see #SHADING_MODE_OFF
* @see #SHADING_MODE_FAST
@@ -1621,12 +2073,20 @@
new Key<Integer>("android.shading.mode", int.class);
/**
- * <p>Control for the face detector
+ * <p>Operating mode for the face detector
* unit.</p>
* <p>Whether face detection is enabled, and whether it
* should output just the basic fields or the full set of
- * fields. Value must be one of the
- * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
+ * fields.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_SIMPLE SIMPLE}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_FULL FULL}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
* @see #STATISTICS_FACE_DETECT_MODE_OFF
@@ -1638,10 +2098,12 @@
new Key<Integer>("android.statistics.faceDetectMode", int.class);
/**
- * <p>Operating mode for hotpixel map generation.</p>
- * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
- * If set to OFF, no hotpixel map will be returned.</p>
- * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
+ * <p>Operating mode for hot pixel map generation.</p>
+ * <p>If set to <code>true</code>, a hot pixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
+ * If set to <code>false</code>, no hot pixel map will be returned.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
@@ -1656,6 +2118,18 @@
* <p>When set to ON,
* android.statistics.lensShadingMap will be provided in
* the output result metadata.</p>
+ * <p>ON is always supported on devices with the RAW capability.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF
* @see #STATISTICS_LENS_SHADING_MAP_MODE_ON
*/
@@ -1668,7 +2142,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -1680,7 +2159,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -1693,10 +2177,10 @@
* CONTRAST_CURVE.</p>
* <p>Each channel's curve is defined by an array of control points:</p>
* <pre><code>android.tonemap.curveRed =
- * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
+ * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
- * <p>These are sorted in order of increasing <code>Pin</code>; it is always
- * guaranteed that input values 0.0 and 1.0 are included in the list to
+ * <p>These are sorted in order of increasing <code>Pin</code>; it is
+ * required that input values 0.0 and 1.0 are included in the list to
* define a complete mapping. For input values between control points,
* the camera device must linearly interpolate between the control
* points.</p>
@@ -1717,21 +2201,29 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
- * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
- * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
- * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
+ * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
+ * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
+ * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
- * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
- * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
- * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
+ * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
+ * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
+ * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * 0-1 on both input and output coordinates, normalized
+ * as a floating-point value such that 0 == black and 1 == white.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
* @hide
@@ -1747,7 +2239,7 @@
* example. The same logic applies to green and blue channel.
* Each channel's curve is defined by an array of control points:</p>
* <pre><code>curveRed =
- * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
+ * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
* <p>These are sorted in order of increasing <code>Pin</code>; it is always
* guaranteed that input values 0.0 and 1.0 are included in the list to
@@ -1771,21 +2263,26 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
- * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
- * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
- * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
+ * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
+ * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
+ * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
- * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
- * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
- * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
+ * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
+ * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
+ * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
*/
@@ -1807,8 +2304,6 @@
* tables, selective chroma enhancement, or other non-linear color
* transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
- * <p>This must be set to a valid mode in
- * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.</p>
* <p>When using either FAST or HIGH_QUALITY, the camera device will
* emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.
* These values are always available, and as close as possible to the
@@ -1816,7 +2311,20 @@
* <p>If a request is sent with CONTRAST_CURVE with the camera device's
* provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
* roughly the same.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #TONEMAP_MODE_CONTRAST_CURVE CONTRAST_CURVE}</li>
+ * <li>{@link #TONEMAP_MODE_FAST FAST}</li>
+ * <li>{@link #TONEMAP_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES
* @see CaptureRequest#TONEMAP_CURVE
* @see CaptureRequest#TONEMAP_MODE
@@ -1839,6 +2347,7 @@
* data is stored locally on the device.</p>
* <p>The LED <em>may</em> be off if a trusted application is using the data that
* doesn't violate the above rules.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Boolean> LED_TRANSMIT =
@@ -1847,9 +2356,9 @@
/**
* <p>Whether black-level compensation is locked
* to its current values, or is free to vary.</p>
- * <p>When set to ON, the values used for black-level
+ * <p>When set to <code>true</code> (ON), the values used for black-level
* compensation will not change until the lock is set to
- * OFF.</p>
+ * <code>false</code> (OFF).</p>
* <p>Since changes to certain capture parameters (such as
* exposure time) may require resetting of black level
* compensation, the camera device must report whether setting
@@ -1882,6 +2391,12 @@
* possible, only overriding the lock to OFF when changes to
* other request parameters require a black level recalculation
* or reset.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<Boolean> BLACK_LEVEL_LOCK =
@@ -1891,4 +2406,6 @@
* End generated code
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
+
+
}
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index 01276a2..d208649 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -327,7 +327,6 @@
* modify the comment blocks at the start or end.
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
-
/**
* <p>The mode control selects how the image data is converted from the
* sensor's native color into linear sRGB color.</p>
@@ -369,10 +368,21 @@
* </code></pre>
* <p>Both the input and output value ranges must match. Overflow/underflow
* values are clipped to fit within the range.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX TRANSFORM_MATRIX}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX
* @see #COLOR_CORRECTION_MODE_FAST
* @see #COLOR_CORRECTION_MODE_HIGH_QUALITY
@@ -393,8 +403,14 @@
* in this matrix result metadata. The transform should keep the magnitude
* of the output color values within <code>[0, 1.0]</code> (assuming input color
* values is within the normalized range <code>[0, 1.0]</code>), or clipping may occur.</p>
+ * <p><b>Units</b>: Unitless scale factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.ColorSpaceTransform> COLOR_CORRECTION_TRANSFORM =
@@ -410,8 +426,14 @@
* TRANSFORM_MATRIX.</p>
* <p>The gains in the result metadata are the gains actually
* applied by the camera device to the current frame.</p>
+ * <p><b>Units</b>: Unitless gain factors</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.RggbChannelVector> COLOR_CORRECTION_GAINS =
@@ -419,8 +441,6 @@
/**
* <p>Mode of operation for the chromatic aberration correction algorithm.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}.</p>
* <p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
* can not focus on the same point after exiting from the lens. This metadata defines
* the high level control of chromatic aberration correction algorithm, which aims to
@@ -431,6 +451,16 @@
* use the highest-quality aberration correction algorithms, even if it slows down
* capture rate. FAST means the camera device will not slow down capture rate when
* applying aberration correction.</p>
+ * <p>LEGACY devices will always be in FAST mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_OFF OFF}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_FAST FAST}</li>
+ * <li>{@link #COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES android.colorCorrection.availableAberrationModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES
* @see #COLOR_CORRECTION_ABERRATION_MODE_OFF
@@ -463,7 +493,7 @@
* options for the antibanding mode. The
* {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes} key contains
* the available modes for a given camera device.</p>
- * <p>The default mode is AUTO, which must be supported by all
+ * <p>The default mode is AUTO, which is supported by all
* camera devices.</p>
* <p>If manual exposure control is enabled (by setting
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} to OFF),
@@ -471,6 +501,16 @@
* ensure it selects exposure times that do not cause banding
* issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
* the application in this.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_50HZ 50HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_60HZ 60HZ}</li>
+ * <li>{@link #CONTROL_AE_ANTIBANDING_MODE_AUTO AUTO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br></p>
+ * <p>{@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
* @see CaptureRequest#CONTROL_AE_MODE
@@ -503,6 +543,10 @@
* state. Once the new exposure target is reached, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} will
* change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
* FLASH_REQUIRED (if the scene is too dark for still capture).</p>
+ * <p><b>Units</b>: Compensation steps</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE
* @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
@@ -517,9 +561,11 @@
/**
* <p>Whether auto-exposure (AE) is currently locked to its latest
* calculated values.</p>
- * <p>Note that even when AE is locked, the flash may be
- * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
- * ON_AUTO_FLASH_REDEYE.</p>
+ * <p>When set to <code>true</code> (ON), the AE algorithm is locked to its latest parameters,
+ * and will not change exposure settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Note that even when AE is locked, the flash may be fired if
+ * the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH /
+ * ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE.</p>
* <p>When {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} is changed, even if the AE lock
* is ON, the camera device will still adjust its exposure value.</p>
* <p>If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger})
@@ -528,7 +574,21 @@
* parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}
* is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
* {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AE updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AE mode:</li>
+ * <li>Lock AE</li>
+ * <li>Wait for the first result to be output that has the AE locked</li>
+ * <li>Copy exposure settings from that result into a request, set the request to manual AE</li>
+ * <li>Submit the capture request, proceed to run manual AE as desired.</li>
+ * </ol>
* <p>See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
* @see CaptureRequest#CONTROL_AE_MODE
@@ -562,7 +622,19 @@
* camera device auto-exposure routine for the overridden
* fields for a given capture will be available in its
* CaptureResult.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON ON}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH ON_AUTO_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}</li>
+ * <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES android.control.aeAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#FLASH_INFO_AVAILABLE
* @see CaptureRequest#FLASH_MODE
@@ -580,25 +652,35 @@
new Key<Integer>("android.control.aeMode", int.class);
/**
- * <p>List of areas to use for
- * metering.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
+ * <p>List of metering areas to use for auto-exposure adjustment.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other exposure metering regions, so if only one
+ * region is used, all non-zero weights will have the same effect. A region with 0
+ * weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE
@@ -610,12 +692,20 @@
new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class);
/**
- * <p>Range over which fps can be adjusted to
- * maintain exposure.</p>
+ * <p>Range over which the auto-exposure routine can
+ * adjust the capture frame rate to maintain good
+ * exposure.</p>
* <p>Only constrains auto-exposure (AE) algorithm, not
- * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
+ * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime} and
+ * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}.</p>
+ * <p><b>Units</b>: Frames per second (FPS)</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any of the entries in {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES android.control.aeAvailableTargetFpsRanges}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
+ * @see CaptureRequest#SENSOR_FRAME_DURATION
*/
@PublicKey
public static final Key<android.util.Range<Integer>> CONTROL_AE_TARGET_FPS_RANGE =
@@ -640,8 +730,22 @@
* depends on the current AE mode and state; see
* {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
* details.</p>
+ * <p>On LEGACY-level devices, the precapture trigger is not supported;
+ * capturing a high-resolution JPEG image will automatically trigger a
+ * precapture sequence before the high-resolution capture, including
+ * potentially firing a pre-capture flash.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureResult#CONTROL_AE_STATE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
* @see #CONTROL_AE_PRECAPTURE_TRIGGER_START
*/
@@ -831,12 +935,26 @@
* </tr>
* </tbody>
* </table>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AE_STATE_INACTIVE INACTIVE}</li>
+ * <li>{@link #CONTROL_AE_STATE_SEARCHING SEARCHING}</li>
+ * <li>{@link #CONTROL_AE_STATE_CONVERGED CONVERGED}</li>
+ * <li>{@link #CONTROL_AE_STATE_LOCKED LOCKED}</li>
+ * <li>{@link #CONTROL_AE_STATE_FLASH_REQUIRED FLASH_REQUIRED}</li>
+ * <li>{@link #CONTROL_AE_STATE_PRECAPTURE PRECAPTURE}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_LOCK
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
* @see CaptureRequest#CONTROL_MODE
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AE_STATE_INACTIVE
* @see #CONTROL_AE_STATE_SEARCHING
* @see #CONTROL_AE_STATE_CONVERGED
@@ -856,7 +974,20 @@
* <p>If the lens is controlled by the camera device auto-focus algorithm,
* the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
* in result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AF_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AF_MODE_MACRO MACRO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_VIDEO CONTINUOUS_VIDEO}</li>
+ * <li>{@link #CONTROL_AF_MODE_CONTINUOUS_PICTURE CONTINUOUS_PICTURE}</li>
+ * <li>{@link #CONTROL_AF_MODE_EDOF EDOF}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES android.control.afAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
+ * @see CameraCharacteristics#CONTROL_AF_AVAILABLE_MODES
* @see CaptureResult#CONTROL_AF_STATE
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
@@ -872,25 +1003,35 @@
new Key<Integer>("android.control.afMode", int.class);
/**
- * <p>List of areas to use for focus
- * estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
+ * <p>List of metering areas to use for auto-focus.</p>
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of focus areas supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
* bottom-right pixel in the active pixel array.</p>
- * <p>The weight must range from 0 to 1000, and represents a weight
+ * <p>The weight must be within <code>[0, 1000]</code>, and represents a weight
* for every pixel in the area. This means that a large metering area
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other metering regions, so if only one region
+ * is used, all non-zero weights will have the same effect. A region with 0 weight is
+ * ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF
@@ -914,6 +1055,13 @@
* START for multiple captures in a row means restarting the AF operation over
* and over again.</p>
* <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what the trigger means for each AF mode.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_TRIGGER_IDLE IDLE}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_START START}</li>
+ * <li>{@link #CONTROL_AF_TRIGGER_CANCEL CANCEL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureResult#CONTROL_AF_STATE
* @see #CONTROL_AF_TRIGGER_IDLE
@@ -1306,6 +1454,17 @@
* </tr>
* </tbody>
* </table>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AF_STATE_INACTIVE INACTIVE}</li>
+ * <li>{@link #CONTROL_AF_STATE_PASSIVE_SCAN PASSIVE_SCAN}</li>
+ * <li>{@link #CONTROL_AF_STATE_PASSIVE_FOCUSED PASSIVE_FOCUSED}</li>
+ * <li>{@link #CONTROL_AF_STATE_ACTIVE_SCAN ACTIVE_SCAN}</li>
+ * <li>{@link #CONTROL_AF_STATE_FOCUSED_LOCKED FOCUSED_LOCKED}</li>
+ * <li>{@link #CONTROL_AF_STATE_NOT_FOCUSED_LOCKED NOT_FOCUSED_LOCKED}</li>
+ * <li>{@link #CONTROL_AF_STATE_PASSIVE_UNFOCUSED PASSIVE_UNFOCUSED}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
* @see CaptureRequest#CONTROL_MODE
@@ -1325,9 +1484,26 @@
/**
* <p>Whether auto-white balance (AWB) is currently locked to its
* latest calculated values.</p>
+ * <p>When set to <code>true</code> (ON), the AWB algorithm is locked to its latest parameters,
+ * and will not change color balance settings until the lock is set to <code>false</code> (OFF).</p>
+ * <p>Since the camera device has a pipeline of in-flight requests, the settings that
+ * get locked do not necessarily correspond to the settings that were present in the
+ * latest capture result received from the camera device, since additional captures
+ * and AWB updates may have occurred even before the result was sent out. If an
+ * application is switching between automatic and manual control and wishes to eliminate
+ * any flicker during the switch, the following procedure is recommended:</p>
+ * <ol>
+ * <li>Starting in auto-AWB mode:</li>
+ * <li>Lock AWB</li>
+ * <li>Wait for the first result to be output that has the AWB locked</li>
+ * <li>Copy AWB settings from that result into a request, set the request to manual AWB</li>
+ * <li>Submit the capture request, proceed to run manual AWB as desired.</li>
+ * </ol>
* <p>Note that AWB lock is only meaningful when
* {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is in the AUTO mode; in other modes,
* AWB is already fixed to a specific setting.</p>
+ * <p>Some LEGACY devices may not support ON; the value is then overridden to OFF.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AWB_MODE
*/
@@ -1355,10 +1531,26 @@
* {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform},
* {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
* {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} are ignored.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AWB_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_AWB_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_AWB_MODE_INCANDESCENT INCANDESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_FLUORESCENT FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_WARM_FLUORESCENT WARM_FLUORESCENT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_DAYLIGHT DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT CLOUDY_DAYLIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_TWILIGHT TWILIGHT}</li>
+ * <li>{@link #CONTROL_AWB_MODE_SHADE SHADE}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES android.control.awbAvailableModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#COLOR_CORRECTION_GAINS
* @see CaptureRequest#COLOR_CORRECTION_MODE
* @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
+ * @see CameraCharacteristics#CONTROL_AWB_AVAILABLE_MODES
* @see CaptureRequest#CONTROL_MODE
* @see #CONTROL_AWB_MODE_OFF
* @see #CONTROL_AWB_MODE_AUTO
@@ -1375,10 +1567,12 @@
new Key<Integer>("android.control.awbMode", int.class);
/**
- * <p>List of areas to use for illuminant
+ * <p>List of metering areas to use for auto-white-balance illuminant
* estimation.</p>
- * <p>Optional. Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
+ * <p>Not available if {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb} is 0.
* Otherwise will always be present.</p>
+ * <p>The maximum number of regions supported by the device is determined by the value
+ * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.</p>
* <p>The coordinate system is based on the active pixel array,
* with (0,0) being the top-left pixel in the active pixel array, and
* ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
@@ -1389,11 +1583,20 @@
* with the same weight as a smaller area will have more effect in
* the metering result. Metering areas can partially overlap and the
* camera device will add the weights in the overlap region.</p>
- * <p>If all regions have 0 weight, then no specific metering area
- * needs to be used by the camera device. If the metering region is
- * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
- * the camera device will ignore the sections outside the region and output the
- * used sections in the result metadata.</p>
+ * <p>The weights are relative to weights of other white balance metering regions, so if
+ * only one region is used, all non-zero weights will have the same effect. A region with
+ * 0 weight is ignored.</p>
+ * <p>If all regions have 0 weight, then no specific metering area needs to be used by the
+ * camera device.</p>
+ * <p>If the metering region is outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in
+ * capture result metadata, the camera device will ignore the sections outside the crop
+ * region and output only the intersection rectangle as the metering region in the result
+ * metadata. If the region is entirely outside the crop region, it will be ignored and
+ * not reported in the result metadata.</p>
+ * <p><b>Units</b>: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p><b>Range of valid values:</b><br>
+ * Coordinates must be between <code>[(0,0), (width, height))</code> of
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB
@@ -1413,7 +1616,18 @@
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p>
* <p>ZERO_SHUTTER_LAG will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
* contains ZSL. MANUAL will be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
- * contains MANUAL_SENSOR.</p>
+ * contains MANUAL_SENSOR. Other intent values are always supported.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_CUSTOM CUSTOM}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_PREVIEW PREVIEW}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_STILL_CAPTURE STILL_CAPTURE}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_RECORD VIDEO_RECORD}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT VIDEO_SNAPSHOT}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ZERO_SHUTTER_LAG}</li>
+ * <li>{@link #CONTROL_CAPTURE_INTENT_MANUAL MANUAL}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_MODE
* @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
@@ -1546,11 +1760,23 @@
* </tr>
* </tbody>
* </table>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_AWB_STATE_INACTIVE INACTIVE}</li>
+ * <li>{@link #CONTROL_AWB_STATE_SEARCHING SEARCHING}</li>
+ * <li>{@link #CONTROL_AWB_STATE_CONVERGED CONVERGED}</li>
+ * <li>{@link #CONTROL_AWB_STATE_LOCKED LOCKED}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AWB_LOCK
* @see CaptureRequest#CONTROL_AWB_MODE
* @see CaptureRequest#CONTROL_MODE
* @see CaptureRequest#CONTROL_SCENE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #CONTROL_AWB_STATE_INACTIVE
* @see #CONTROL_AWB_STATE_SEARCHING
* @see #CONTROL_AWB_STATE_CONVERGED
@@ -1568,10 +1794,23 @@
* implementor of the camera device, and should not be
* depended on to be consistent (or present) across all
* devices.</p>
- * <p>A color effect will only be applied if
- * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_EFFECT_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_MONO MONO}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_NEGATIVE NEGATIVE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SOLARIZE SOLARIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_SEPIA SEPIA}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_POSTERIZE POSTERIZE}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_WHITEBOARD WHITEBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_BLACKBOARD BLACKBOARD}</li>
+ * <li>{@link #CONTROL_EFFECT_MODE_AQUA AQUA}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS android.control.availableEffects}</p>
+ * <p>This key is available on all devices.</p>
*
- * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#CONTROL_AVAILABLE_EFFECTS
* @see #CONTROL_EFFECT_MODE_OFF
* @see #CONTROL_EFFECT_MODE_MONO
* @see #CONTROL_EFFECT_MODE_NEGATIVE
@@ -1587,9 +1826,9 @@
new Key<Integer>("android.control.effectMode", int.class);
/**
- * <p>Overall mode of 3A control
+ * <p>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control
* routines.</p>
- * <p>High-level 3A control. When set to OFF, all 3A control
+ * <p>This is a top-level 3A control switch. When set to OFF, all 3A control
* by the camera device is disabled. The application must set the fields for
* capture parameters itself.</p>
* <p>When set to AUTO, the individual algorithm controls in
@@ -1604,6 +1843,18 @@
* update, as if this frame is never captured. This mode can be used in the scenario
* where the application doesn't want a 3A manual control capture to affect
* the subsequent auto 3A capture results.</p>
+ * <p>LEGACY mode devices will only support AUTO and USE_SCENE_MODE modes.
+ * LIMITED mode devices will only support OFF and OFF_KEEP_STATE if they
+ * support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities.
+ * FULL mode devices will always support OFF and OFF_KEEP_STATE.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_MODE_AUTO AUTO}</li>
+ * <li>{@link #CONTROL_MODE_USE_SCENE_MODE USE_SCENE_MODE}</li>
+ * <li>{@link #CONTROL_MODE_OFF_KEEP_STATE OFF_KEEP_STATE}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AF_MODE
* @see #CONTROL_MODE_OFF
@@ -1616,18 +1867,41 @@
new Key<Integer>("android.control.mode", int.class);
/**
- * <p>A camera mode optimized for conditions typical in a particular
- * capture setting.</p>
+ * <p>Control for which scene mode is currently active.</p>
+ * <p>Scene modes are custom camera modes optimized for a certain set of conditions and
+ * capture settings.</p>
* <p>This is the mode that that is active when
* <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code>. Aside from FACE_PRIORITY,
* these modes will disable {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
- * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.
- * The scene modes available for a given camera device are listed in
- * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}.</p>
+ * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.</p>
* <p>The interpretation and implementation of these scene modes is left
* to the implementor of the camera device. Their behavior will not be
* consistent across all devices, and any given device may only implement
* a subset of these modes.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_SCENE_MODE_DISABLED DISABLED}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FACE_PRIORITY FACE_PRIORITY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_ACTION ACTION}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PORTRAIT PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_LANDSCAPE LANDSCAPE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT NIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_NIGHT_PORTRAIT NIGHT_PORTRAIT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_THEATRE THEATRE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BEACH BEACH}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SNOW SNOW}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SUNSET SUNSET}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_STEADYPHOTO STEADYPHOTO}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_FIREWORKS FIREWORKS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_SPORTS SPORTS}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_PARTY PARTY}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_CANDLELIGHT CANDLELIGHT}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_BARCODE BARCODE}</li>
+ * <li>{@link #CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AF_MODE
@@ -1660,18 +1934,26 @@
/**
* <p>Whether video stabilization is
* active.</p>
- * <p>Video stabilization automatically translates and scales images from the camera
- * in order to stabilize motion between consecutive frames.</p>
+ * <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>
- * <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>
+ * <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>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #CONTROL_VIDEO_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE
* @see CaptureRequest#SCALER_CROP_REGION
@@ -1685,16 +1967,28 @@
/**
* <p>Operation mode for edge
* enhancement.</p>
- * <p>Edge/sharpness/detail enhancement. OFF means no
- * enhancement will be applied by the camera device.</p>
- * <p>This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.</p>
+ * <p>Edge enhancement improves sharpness and details in the captured image. OFF means
+ * no enhancement will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
* will be applied. HIGH_QUALITY mode indicates that the
* camera device will use the highest-quality enhancement algorithms,
* even if it slows down capture rate. FAST means the camera device will
* not slow down capture rate when applying edge enhancement.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #EDGE_MODE_OFF OFF}</li>
+ * <li>{@link #EDGE_MODE_FAST FAST}</li>
+ * <li>{@link #EDGE_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #EDGE_MODE_OFF
* @see #EDGE_MODE_FAST
* @see #EDGE_MODE_HIGH_QUALITY
@@ -1718,6 +2012,13 @@
* <p>When set to TORCH, the flash will be on continuously. This mode can be used
* for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
* <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #FLASH_MODE_OFF OFF}</li>
+ * <li>{@link #FLASH_MODE_SINGLE SINGLE}</li>
+ * <li>{@link #FLASH_MODE_TORCH TORCH}</li>
+ * </ul></p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
@@ -1737,8 +2038,33 @@
* <p>When the camera device doesn't have flash unit
* (i.e. <code>{@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == false</code>), this state will always be UNAVAILABLE.
* Other states indicate the current flash status.</p>
+ * <p>In certain conditions, this will be available on LEGACY devices:</p>
+ * <ul>
+ * <li>Flash-less cameras always return UNAVAILABLE.</li>
+ * <li>Using {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>==</code> ON_ALWAYS_FLASH
+ * will always return FIRED.</li>
+ * <li>Using {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> TORCH
+ * will always return FIRED.</li>
+ * </ul>
+ * <p>In all other conditions the state will not be available on
+ * LEGACY devices (i.e. it will be <code>null</code>).</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #FLASH_STATE_UNAVAILABLE UNAVAILABLE}</li>
+ * <li>{@link #FLASH_STATE_CHARGING CHARGING}</li>
+ * <li>{@link #FLASH_STATE_READY READY}</li>
+ * <li>{@link #FLASH_STATE_FIRED FIRED}</li>
+ * <li>{@link #FLASH_STATE_PARTIAL PARTIAL}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CaptureRequest#CONTROL_AE_MODE
* @see CameraCharacteristics#FLASH_INFO_AVAILABLE
+ * @see CaptureRequest#FLASH_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #FLASH_STATE_UNAVAILABLE
* @see #FLASH_STATE_CHARGING
* @see #FLASH_STATE_READY
@@ -1750,12 +2076,19 @@
new Key<Integer>("android.flash.state", int.class);
/**
- * <p>Set operational mode for hot pixel correction.</p>
- * <p>Valid modes for this camera device are listed in
- * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
+ * <p>Operational mode for hot pixel correction.</p>
* <p>Hotpixel correction interpolates out, or otherwise removes, pixels
- * that do not accurately encode the incoming light (i.e. pixels that
- * are stuck at an arbitrary value).</p>
+ * that do not accurately measure the incoming light (i.e. pixels that
+ * are stuck at an arbitrary value or are oversensitive).</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #HOT_PIXEL_MODE_OFF OFF}</li>
+ * <li>{@link #HOT_PIXEL_MODE_FAST FAST}</li>
+ * <li>{@link #HOT_PIXEL_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
* @see #HOT_PIXEL_MODE_OFF
@@ -1768,6 +2101,10 @@
/**
* <p>A location object to use when generating image GPS metadata.</p>
+ * <p>Setting a location object in a request will include the GPS coordinates of the location
+ * into any JPEG images captured based on the request. These coordinates can then be
+ * viewed by anyone who receives the JPEG image.</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
@SyntheticKey
@@ -1776,7 +2113,10 @@
/**
* <p>GPS coordinates to include in output JPEG
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * (-180 - 180], [-90,90], [-inf, inf]</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<double[]> JPEG_GPS_COORDINATES =
@@ -1784,7 +2124,9 @@
/**
* <p>32 characters describing GPS algorithm to
- * include in EXIF</p>
+ * include in EXIF.</p>
+ * <p><b>Units</b>: UTF-8 null-terminated string</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
@@ -1792,15 +2134,49 @@
/**
* <p>Time GPS fix was made to include in
- * EXIF</p>
+ * EXIF.</p>
+ * <p><b>Units</b>: UTC in seconds since January 1, 1970</p>
+ * <p>This key is available on all devices.</p>
* @hide
*/
public static final Key<Long> JPEG_GPS_TIMESTAMP =
new Key<Long>("android.jpeg.gpsTimestamp", long.class);
/**
- * <p>Orientation of JPEG image to
- * write</p>
+ * <p>The orientation for a JPEG image.</p>
+ * <p>The clockwise rotation angle in degrees, relative to the orientation
+ * to the camera, that the JPEG picture needs to be rotated by, to be viewed
+ * upright.</p>
+ * <p>Camera devices may either encode this value into the JPEG EXIF header, or
+ * rotate the image data to match this orientation.</p>
+ * <p>Note that this orientation is relative to the orientation of the camera sensor, given
+ * by {@link CameraCharacteristics#SENSOR_ORIENTATION android.sensor.orientation}.</p>
+ * <p>To translate from the device orientation given by the Android sensor APIs, the following
+ * sample code may be used:</p>
+ * <pre><code>private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) {
+ * if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0;
+ * int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION);
+ *
+ * // Round device orientation to a multiple of 90
+ * deviceOrientation = (deviceOrientation + 45) / 90 * 90;
+ *
+ * // Reverse device orientation for front-facing cameras
+ * boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT;
+ * if (facingFront) deviceOrientation = -deviceOrientation;
+ *
+ * // Calculate desired JPEG orientation relative to camera orientation to make
+ * // the image upright relative to the device orientation
+ * int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+ *
+ * return jpegOrientation;
+ * }
+ * </code></pre>
+ * <p><b>Units</b>: Degrees in multiples of 90</p>
+ * <p><b>Range of valid values:</b><br>
+ * 0, 90, 180, 270</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_ORIENTATION
*/
@PublicKey
public static final Key<Integer> JPEG_ORIENTATION =
@@ -1810,6 +2186,9 @@
* <p>Compression quality of the final JPEG
* image.</p>
* <p>85-95 is typical usage range.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_QUALITY =
@@ -1818,6 +2197,9 @@
/**
* <p>Compression quality of JPEG
* thumbnail.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100; larger is higher quality</p>
+ * <p>This key is available on all devices.</p>
*/
@PublicKey
public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
@@ -1827,25 +2209,29 @@
* <p>Resolution of embedded JPEG thumbnail.</p>
* <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
* but the captured JPEG will still be a valid image.</p>
- * <p>When a jpeg image capture is issued, the thumbnail size selected should have
- * the same aspect ratio as the jpeg image.</p>
+ * <p>For best results, when issuing a request for a JPEG image, the thumbnail size selected
+ * should have the same aspect ratio as the main JPEG output.</p>
* <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
* ratio, the camera device creates the thumbnail by cropping it from the primary image.
* For example, if the primary image has 4:3 aspect ratio, the thumbnail image has
* 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to
* generate the thumbnail image. The thumbnail image will always have a smaller Field
* Of View (FOV) than the primary image when aspect ratios differ.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES android.jpeg.availableThumbnailSizes}</p>
+ * <p>This key is available on all devices.</p>
+ *
+ * @see CameraCharacteristics#JPEG_AVAILABLE_THUMBNAIL_SIZES
*/
@PublicKey
public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
new Key<android.util.Size>("android.jpeg.thumbnailSize", android.util.Size.class);
/**
- * <p>The ratio of lens focal length to the effective
- * aperture diameter.</p>
- * <p>This will only be supported on the camera devices that
- * have variable aperture lens. The aperture value can only be
- * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
+ * <p>The desired lens aperture size, as a ratio of lens focal length to the
+ * effective aperture diameter.</p>
+ * <p>Setting this value is only supported on the camera devices that have a variable
+ * aperture lens.</p>
* <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
* this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
* {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
@@ -1858,8 +2244,16 @@
* the ON modes, this will be overridden by the camera device
* auto-exposure algorithm, the overridden values are then provided
* back to the user in the corresponding result.</p>
+ * <p><b>Units</b>: The f-number (f/N)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
* @see CaptureResult#LENS_STATE
* @see CaptureRequest#SENSOR_EXPOSURE_TIME
@@ -1871,10 +2265,8 @@
new Key<Float>("android.lens.aperture", float.class);
/**
- * <p>State of lens neutral density filter(s).</p>
- * <p>This will not be supported on most camera devices. On devices
- * where this is supported, this may only be set to one of the
- * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
+ * <p>The desired setting for the lens neutral density filter(s).</p>
+ * <p>This control will not be supported on most camera devices.</p>
* <p>Lens filters are typically used to lower the amount of light the
* sensor is exposed to (measured in steps of EV). As used here, an EV
* step is the standard logarithmic representation, which are
@@ -1886,7 +2278,15 @@
* <p>It may take several frames before the lens filter density changes
* to the requested value. While the filter density is still changing,
* {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
+ * <p><b>Units</b>: Exposure Value (EV)</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
* @see CaptureResult#LENS_STATE
*/
@@ -1895,7 +2295,7 @@
new Key<Float>("android.lens.filterDensity", float.class);
/**
- * <p>The current lens focal length; used for optical zoom.</p>
+ * <p>The desired lens focal length; used for optical zoom.</p>
* <p>This setting controls the physical focal length of the camera
* device's lens. Changing the focal length changes the field of
* view of the camera device, and is usually used for optical zoom.</p>
@@ -1904,10 +2304,15 @@
* frames before the lens can change to the requested focal length.
* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
* be set to MOVING.</p>
- * <p>This is expected not to be supported on most devices.</p>
+ * <p>Optical zoom will not be supported on most devices.</p>
+ * <p><b>Units</b>: Millimeters</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#LENS_APERTURE
* @see CaptureRequest#LENS_FOCUS_DISTANCE
+ * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS
* @see CaptureResult#LENS_STATE
*/
@PublicKey
@@ -1915,9 +2320,19 @@
new Key<Float>("android.lens.focalLength", float.class);
/**
- * <p>Distance to plane of sharpest focus,
+ * <p>Desired distance to plane of sharpest focus,
* measured from frontmost surface of the lens.</p>
* <p>Should be zero for fixed-focus cameras</p>
+ * <p><b>Units</b>: See {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
*/
@PublicKey
public static final Key<Float> LENS_FOCUS_DISTANCE =
@@ -1928,6 +2343,17 @@
* sharp focus (depth of field).</p>
* <p>If variable focus not supported, can still report
* fixed depth of field range</p>
+ * <p><b>Units</b>: A pair of focus distances in diopters: (near,
+ * far); see {@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration} for details.</p>
+ * <p><b>Range of valid values:</b><br>
+ * >=0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION
*/
@PublicKey
public static final Key<android.util.Pair<Float,Float>> LENS_FOCUS_RANGE =
@@ -1947,14 +2373,26 @@
* 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>If a camera device supports both OIS and digital image stabilization
+ * ({@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>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_OFF OFF}</li>
+ * <li>{@link #LENS_OPTICAL_STABILIZATION_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION
* @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
* @see #LENS_OPTICAL_STABILIZATION_MODE_ON
@@ -1984,7 +2422,17 @@
* <p>Then this state will always be STATIONARY.</p>
* <p>When the state is MOVING, it indicates that at least one of the lens parameters
* is changing.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #LENS_STATE_STATIONARY STATIONARY}</li>
+ * <li>{@link #LENS_STATE_MOVING MOVING}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#LENS_APERTURE
* @see CaptureRequest#LENS_FILTER_DENSITY
* @see CaptureRequest#LENS_FOCAL_LENGTH
@@ -2002,16 +2450,28 @@
/**
* <p>Mode of operation for the noise reduction algorithm.</p>
- * <p>Noise filtering control. OFF means no noise reduction
- * will be applied by the camera device.</p>
- * <p>This must be set to a valid mode from
- * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</p>
+ * <p>The noise reduction algorithm attempts to improve image quality by removing
+ * excessive noise added by the capture process, especially in dark conditions.
+ * OFF means no noise reduction will be applied by the camera device.</p>
* <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
* will be applied. HIGH_QUALITY mode indicates that the camera device
* will use the highest-quality noise filtering algorithms,
* even if it slows down capture rate. FAST means the camera device will not
* slow down capture rate when applying noise filtering.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #NOISE_REDUCTION_MODE_OFF OFF}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_FAST FAST}</li>
+ * <li>{@link #NOISE_REDUCTION_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
* @see #NOISE_REDUCTION_MODE_OFF
* @see #NOISE_REDUCTION_MODE_FAST
@@ -2035,6 +2495,8 @@
* in any order relative to other frames, but all PARTIAL buffers for a given
* capture must arrive before the FINAL buffer for that capture. This entry may
* only be used by the camera device if quirks.usePartialResult is set to 1.</p>
+ * <p><b>Range of valid values:</b><br>
+ * Optional. Default value is FINAL.</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
@@ -2048,6 +2510,10 @@
* increases with every new result (that is, each new result has a unique
* frameCount value).</p>
* <p>Reset on release()</p>
+ * <p><b>Units</b>: count of frames</p>
+ * <p><b>Range of valid values:</b><br>
+ * > 0</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @deprecated
* @hide
*/
@@ -2059,6 +2525,10 @@
* <p>An application-specified ID for the current
* request. Must be maintained unchanged in output
* frame</p>
+ * <p><b>Units</b>: arbitrary integer assigned by application</p>
+ * <p><b>Range of valid values:</b><br>
+ * Any int</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Integer> REQUEST_ID =
@@ -2072,6 +2542,9 @@
* what streams are configured, the data may undergo less processing,
* and some pipeline stages skipped.</p>
* <p>See {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} for more details.</p>
+ * <p><b>Range of valid values:</b><br>
+ * <= {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH
*/
@@ -2080,7 +2553,8 @@
new Key<Byte>("android.request.pipelineDepth", byte.class);
/**
- * <p>The region of the sensor to read out for this capture.</p>
+ * <p>The desired region of the sensor to read out for this capture.</p>
+ * <p>This control can be used to implement digital zoom.</p>
* <p>The crop region coordinate system is based off
* {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the
* top-left corner of the sensor active array.</p>
@@ -2110,6 +2584,9 @@
* for rounding and other hardware requirements; the final
* crop region used will be included in the output capture
* result.</p>
+ * <p><b>Units</b>: Pixel coordinates relative to
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
@@ -2121,8 +2598,23 @@
/**
* <p>Duration each pixel is exposed to
* light.</p>
- * <p>If the sensor can't expose this exact duration, it should shorten the
- * duration exposed to the nearest possible value (rather than expose longer).</p>
+ * <p>If the sensor can't expose this exact duration, it will shorten the
+ * duration exposed to the nearest possible value (rather than expose longer).
+ * The final exposure time used will be available in the output capture result.</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE
*/
@PublicKey
public static final Key<Long> SENSOR_EXPOSURE_TIME =
@@ -2200,8 +2692,23 @@
* delivered.</p>
* <p>For more details about stalling, see
* StreamConfigurationMap#getOutputStallDuration(int,Size).</p>
+ * <p>This control is only effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} is set to
+ * OFF; otherwise the auto-exposure algorithm will override this value.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * See {@link CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION android.sensor.info.maxFrameDuration},
+ * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}. The duration
+ * is capped to <code>max(duration, exposureTime + overhead)</code>.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CaptureRequest#CONTROL_AE_MODE
+ * @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
+ * @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION
*/
@PublicKey
public static final Key<Long> SENSOR_FRAME_DURATION =
@@ -2219,7 +2726,15 @@
* requested, it will reduce the gain to the nearest supported
* value. The final sensitivity used will be available in the
* output capture result.</p>
+ * <p><b>Units</b>: ISO arithmetic units</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE
* @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY
*/
@@ -2243,6 +2758,10 @@
* android.os.SystemClock#elapsedRealtimeNanos(), and they can be
* compared to other timestamps from other subsystems that are using
* that base.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * > 0</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE
*/
@@ -2267,10 +2786,10 @@
/**
* <p>Noise model coefficients for each CFA mosaic channel.</p>
- * <p>This tag contains two noise model coefficients for each CFA channel
+ * <p>This key contains two noise model coefficients for each CFA channel
* corresponding to the sensor amplification (S) and sensor readout
* noise (O). These are given as pairs of coefficients for each channel
- * in the same order as channels listed for the CFA layout tag
+ * in the same order as channels listed for the CFA layout key
* (see {@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}). This is
* represented as an array of Pair<Double, Double>, where
* the first member of the Pair at index n is the S coefficient and the
@@ -2324,6 +2843,8 @@
* <li>R > 1.20 will require strong software correction to produce
* a usuable image (>20% divergence).</li>
* </ul>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>>= 0</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*/
@PublicKey
@@ -2356,7 +2877,21 @@
* <p>For example, if manual flash is enabled, flash firing should still
* occur (and that the test pattern remain unmodified, since the flash
* would not actually affect it).</p>
+ * <p>Defaults to OFF.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_OFF OFF}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR SOLID_COLOR}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS COLOR_BARS}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY COLOR_BARS_FADE_TO_GRAY}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_PN9 PN9}</li>
+ * <li>{@link #SENSOR_TEST_PATTERN_MODE_CUSTOM1 CUSTOM1}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}</p>
* <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ *
+ * @see CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES
* @see #SENSOR_TEST_PATTERN_MODE_OFF
* @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
* @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
@@ -2371,12 +2906,22 @@
/**
* <p>Duration between the start of first row exposure
* and the start of last row exposure.</p>
- * <p>This is the exposure time skew (in the unit of nanosecond) between the first and
- * last row exposure start times. The first row and the last row are the first
- * and last rows inside of the {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
+ * <p>This is the exposure time skew between the first and last
+ * row exposure start times. The first row and the last row are
+ * the first and last rows inside of the
+ * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
* <p>For typical camera sensors that use rolling shutters, this is also equivalent
* to the frame readout time.</p>
+ * <p><b>Units</b>: Nanoseconds</p>
+ * <p><b>Range of valid values:</b><br>
+ * >= 0 and <
+ * StreamConfigurationMap#getOutputMinFrameDuration(int, Size).</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Limited capability</b> -
+ * Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
*/
@PublicKey
@@ -2389,30 +2934,41 @@
* <p>When set to OFF mode, no lens shading correction will be applied by the
* camera device, and an identity lens shading map data will be provided
* if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
- * shading map with size specified as <code>android.lens.info.shadingMapSize = [ 4, 3 ]</code>,
- * the output android.statistics.lensShadingMap for this case will be an identity map
- * shown below:</p>
+ * shading map with size of <code>[ 4, 3 ]</code>,
+ * the output {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap} for this case will be an identity
+ * map shown below:</p>
* <pre><code>[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
* </code></pre>
- * <p>When set to other modes, lens shading correction will be applied by the
- * camera device. Applications can request lens shading map data by setting
- * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
- * lens shading map data in android.statistics.lensShadingMap, with size specified
- * by android.lens.info.shadingMapSize; the returned shading map data will be the one
- * applied by the camera device for this capture request.</p>
- * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
- * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
- * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF),
- * to get best results, it is recommended that the applications wait for the AE and AWB to
- * be converged before using the returned shading map data.</p>
+ * <p>When set to other modes, lens shading correction will be applied by the camera
+ * device. Applications can request lens shading map data by setting
+ * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide lens
+ * shading map data in {@link CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP android.statistics.lensShadingCorrectionMap}; the returned shading map
+ * data will be the one applied by the camera device for this capture request.</p>
+ * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore
+ * the reliability of the map data may be affected by the AE and AWB algorithms. When AE and
+ * AWB are in AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code>
+ * OFF), to get best results, it is recommended that the applications wait for the AE and AWB
+ * to be converged before using the returned shading map data.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SHADING_MODE_OFF OFF}</li>
+ * <li>{@link #SHADING_MODE_FAST FAST}</li>
+ * <li>{@link #SHADING_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_AWB_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
+ * @see CaptureResult#STATISTICS_LENS_SHADING_CORRECTION_MAP
* @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
* @see #SHADING_MODE_OFF
* @see #SHADING_MODE_FAST
@@ -2423,12 +2979,20 @@
new Key<Integer>("android.shading.mode", int.class);
/**
- * <p>Control for the face detector
+ * <p>Operating mode for the face detector
* unit.</p>
* <p>Whether face detection is enabled, and whether it
* should output just the basic fields or the full set of
- * fields. Value must be one of the
- * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
+ * fields.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_SIMPLE SIMPLE}</li>
+ * <li>{@link #STATISTICS_FACE_DETECT_MODE_FULL FULL}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
* @see #STATISTICS_FACE_DETECT_MODE_OFF
@@ -2444,7 +3008,8 @@
* <p>Each detected face is given a unique ID that is valid for as long as the face is visible
* to the camera device. A face that leaves the field of view and later returns may be
* assigned a new ID.</p>
- * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL</p>
+ * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL
+ * This key is available on all devices.</p>
*
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
* @hide
@@ -2457,7 +3022,8 @@
* faces.</p>
* <p>The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with
* <code>(0, 0)</code> being the top-left pixel of the active array.</p>
- * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL</p>
+ * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL
+ * This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
@@ -2471,7 +3037,8 @@
* faces.</p>
* <p>The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with
* <code>(0, 0)</code> being the top-left pixel of the active array.</p>
- * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF</p>
+ * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF
+ * This key is available on all devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
@@ -2484,6 +3051,9 @@
* <p>List of the face confidence scores for
* detected faces</p>
* <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.</p>
+ * <p><b>Range of valid values:</b><br>
+ * 1-100</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
* @hide
@@ -2493,8 +3063,9 @@
/**
* <p>List of the faces detected through camera face detection
- * in this result.</p>
+ * in this capture.</p>
* <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} <code>!=</code> OFF.</p>
+ * <p>This key is available on all devices.</p>
*
* @see CaptureRequest#STATISTICS_FACE_DETECT_MODE
*/
@@ -2528,11 +3099,11 @@
* <pre><code>width,height = [ 4, 3 ]
* values =
* [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2,
- * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
- * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
- * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
- * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
+ * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
+ * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
+ * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
+ * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
* </code></pre>
* <p>The low-resolution scaling map images for each channel are
* (displayed using nearest-neighbor interpolation):</p>
@@ -2543,8 +3114,15 @@
* <p>As a visualization only, inverting the full-color map to recover an
* image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives:</p>
* <p><img alt="Image of a uniform white wall (inverse shading map)" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/inv_shading.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * Each gain factor is >= 1</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<android.hardware.camera2.params.LensShadingMap> STATISTICS_LENS_SHADING_CORRECTION_MAP =
@@ -2576,11 +3154,11 @@
* <pre><code>android.lens.info.shadingMapSize = [ 4, 3 ]
* android.statistics.lensShadingMap =
* [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2,
- * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
- * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
- * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
- * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
- * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
+ * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
+ * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
+ * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
+ * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
+ * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
* </code></pre>
* <p>The low-resolution scaling map images for each channel are
* (displayed using nearest-neighbor interpolation):</p>
@@ -2591,8 +3169,15 @@
* <p>As a visualization only, inverting the full-color map to recover an
* image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives:</p>
* <p><img alt="Image of a uniform white wall (inverse shading map)" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/inv_shading.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * Each gain factor is >= 1</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#COLOR_CORRECTION_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @hide
*/
public static final Key<float[]> STATISTICS_LENS_SHADING_MAP =
@@ -2659,10 +3244,21 @@
* into this metadata field. See
* {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} for more details.</p>
* <p>Reports NONE if there doesn't appear to be flickering illumination.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_SCENE_FLICKER_NONE NONE}</li>
+ * <li>{@link #STATISTICS_SCENE_FLICKER_50HZ 50HZ}</li>
+ * <li>{@link #STATISTICS_SCENE_FLICKER_60HZ 60HZ}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE
* @see CaptureRequest#CONTROL_AE_MODE
* @see CaptureRequest#CONTROL_MODE
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #STATISTICS_SCENE_FLICKER_NONE
* @see #STATISTICS_SCENE_FLICKER_50HZ
* @see #STATISTICS_SCENE_FLICKER_60HZ
@@ -2672,10 +3268,12 @@
new Key<Integer>("android.statistics.sceneFlicker", int.class);
/**
- * <p>Operating mode for hotpixel map generation.</p>
- * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
- * If set to OFF, no hotpixel map will be returned.</p>
- * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
+ * <p>Operating mode for hot pixel map generation.</p>
+ * <p>If set to <code>true</code>, a hot pixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
+ * If set to <code>false</code>, no hot pixel map will be returned.</p>
+ * <p><b>Range of valid values:</b><br>
+ * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
* @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
@@ -2692,6 +3290,11 @@
* height dimensions are given in {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.
* This may include hot pixels that lie outside of the active array
* bounds given by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
+ * <p><b>Range of valid values:</b><br></p>
+ * <p>n <= number of pixels on the sensor.
+ * The <code>(x, y)</code> coordinates must be bounded by
+ * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
*
* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
* @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
@@ -2706,6 +3309,18 @@
* <p>When set to ON,
* android.statistics.lensShadingMap will be provided in
* the output result metadata.</p>
+ * <p>ON is always supported on devices with the RAW capability.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_OFF OFF}</li>
+ * <li>{@link #STATISTICS_LENS_SHADING_MAP_MODE_ON ON}</li>
+ * </ul></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
+ *
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF
* @see #STATISTICS_LENS_SHADING_MAP_MODE_ON
*/
@@ -2718,7 +3333,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -2730,7 +3350,12 @@
* channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
* <p>See android.tonemap.curveRed for more details.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CaptureRequest#TONEMAP_MODE
* @hide
*/
@@ -2743,10 +3368,10 @@
* CONTRAST_CURVE.</p>
* <p>Each channel's curve is defined by an array of control points:</p>
* <pre><code>android.tonemap.curveRed =
- * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
+ * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
- * <p>These are sorted in order of increasing <code>Pin</code>; it is always
- * guaranteed that input values 0.0 and 1.0 are included in the list to
+ * <p>These are sorted in order of increasing <code>Pin</code>; it is
+ * required that input values 0.0 and 1.0 are included in the list to
* define a complete mapping. For input values between control points,
* the camera device must linearly interpolate between the control
* points.</p>
@@ -2767,21 +3392,29 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
- * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
- * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
- * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
+ * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
+ * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
+ * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>android.tonemap.curveRed = [
- * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
- * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
- * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
- * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
+ * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
+ * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
+ * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
+ * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Range of valid values:</b><br>
+ * 0-1 on both input and output coordinates, normalized
+ * as a floating-point value such that 0 == black and 1 == white.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
* @hide
@@ -2797,7 +3430,7 @@
* example. The same logic applies to green and blue channel.
* Each channel's curve is defined by an array of control points:</p>
* <pre><code>curveRed =
- * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
+ * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
* 2 <= N <= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
* <p>These are sorted in order of increasing <code>Pin</code>; it is always
* guaranteed that input values 0.0 and 1.0 are included in the list to
@@ -2821,21 +3454,26 @@
* <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
* <p>Gamma 1/2.2 mapping, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
- * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
- * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
- * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
+ * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
+ * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
+ * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
* <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
* <pre><code>curveRed = [
- * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
- * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
- * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
- * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
+ * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
+ * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
+ * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
+ * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
* </code></pre>
* <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
* @see CaptureRequest#TONEMAP_MODE
*/
@@ -2857,8 +3495,6 @@
* tables, selective chroma enhancement, or other non-linear color
* transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
* CONTRAST_CURVE.</p>
- * <p>This must be set to a valid mode in
- * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.</p>
* <p>When using either FAST or HIGH_QUALITY, the camera device will
* emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.
* These values are always available, and as close as possible to the
@@ -2866,7 +3502,20 @@
* <p>If a request is sent with CONTRAST_CURVE with the camera device's
* provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
* roughly the same.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #TONEMAP_MODE_CONTRAST_CURVE CONTRAST_CURVE}</li>
+ * <li>{@link #TONEMAP_MODE_FAST FAST}</li>
+ * <li>{@link #TONEMAP_MODE_HIGH_QUALITY HIGH_QUALITY}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
* @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES
* @see CaptureRequest#TONEMAP_CURVE
* @see CaptureRequest#TONEMAP_MODE
@@ -2889,6 +3538,7 @@
* data is stored locally on the device.</p>
* <p>The LED <em>may</em> be off if a trusted application is using the data that
* doesn't violate the above rules.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
* @hide
*/
public static final Key<Boolean> LED_TRANSMIT =
@@ -2901,8 +3551,13 @@
* ON if {@link CaptureRequest#BLACK_LEVEL_LOCK android.blackLevel.lock} was ON in the capture request, unless
* a change in other capture settings forced the camera device to
* perform a black level reset.</p>
+ * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
+ * <p><b>Full capability</b> -
+ * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
+ * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
*
* @see CaptureRequest#BLACK_LEVEL_LOCK
+ * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
*/
@PublicKey
public static final Key<Boolean> BLACK_LEVEL_LOCK =
@@ -2960,6 +3615,15 @@
* <p>In other words, results for this current request and up to
* {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} prior requests may have their
* android.sync.frameNumber change to CONVERGING.</p>
+ * <p><b>Possible values:</b>
+ * <ul>
+ * <li>{@link #SYNC_FRAME_NUMBER_CONVERGING CONVERGING}</li>
+ * <li>{@link #SYNC_FRAME_NUMBER_UNKNOWN UNKNOWN}</li>
+ * </ul></p>
+ * <p><b>Available values for this device:</b><br>
+ * Either a non-negative value corresponding to a
+ * <code>frame_number</code>, or one of the two enums (CONVERGING / UNKNOWN).</p>
+ * <p>This key is available on all devices.</p>
*
* @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH
* @see #SYNC_FRAME_NUMBER_CONVERGING
@@ -2973,4 +3637,6 @@
* End generated code
*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
+
+
}
diff --git a/docs/html/google/play-services/index.jd b/docs/html/google/play-services/index.jd
index e5479bb..9f6962d 100644
--- a/docs/html/google/play-services/index.jd
+++ b/docs/html/google/play-services/index.jd
@@ -65,7 +65,7 @@
<p><a href="#" onclick="return toggleContent(this)">
<img src="{@docRoot}assets/images/triangle-opened.png"
class="toggle-content-img"
- alt=""/>Google Play services, Version 6.1</a> <em>(September 2014)</em>
+ alt=""/>Google Play services, Version 6.1</a> <em>(October 2014)</em>
</p>
<div class="toggle-content-toggleme">
diff --git a/docs/html/preview/license.jd b/docs/html/preview/license.jd
new file mode 100644
index 0000000..5ff52ba
--- /dev/null
+++ b/docs/html/preview/license.jd
@@ -0,0 +1,143 @@
+page.title=License Agreement
+
+@jd:body
+
+<p>
+To get started with the Android SDK Preview, you must agree to the following terms and conditions.
+As described below, please note that this is a preview version of the Android SDK, subject to change, that you use at your own risk. The Android SDK Preview is not a stable release, and may contain errors and defects that can result in serious damage to your computer systems, devices and data.
+</p>
+
+<p>
+This is the Android SDK Preview License Agreement (the “License Agreement”).
+</p>
+<div class="sdk-terms" style="height:auto;border:0;padding:0;width:700px">
+1. Introduction
+
+1.1 The Android SDK Preview (referred to in the License Agreement as the “Preview” and specifically including the Android system files, packaged APIs, and Preview library files, if and when they are made available) is licensed to you subject to the terms of the License Agreement. The License Agreement forms a legally binding contract between you and Google in relation to your use of the Preview.
+
+1.2 "Android" means the Android software stack for devices, as made available under the Android Open Source Project, which is located at the following URL: http://source.android.com/, as updated from time to time.
+
+1.3 "Google" means Google Inc., a Delaware corporation with principal place of business at 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States.
+
+2. Accepting the License Agreement
+
+2.1 In order to use the Preview, you must first agree to the License Agreement. You may not use the Preview if you do not accept the License Agreement.
+
+2.2 By clicking to accept and/or using the Preview, you hereby agree to the terms of the License Agreement.
+
+2.3 You may not use the Preview and may not accept the License Agreement if you are a person barred from receiving the Preview under the laws of the United States or other countries including the country in which you are resident or from which you use the Preview.
+
+2.4 If you will use the Preview internally within your company or organization you agree to be bound by the License Agreement on behalf of your employer or other entity, and you represent and warrant that you have full legal authority to bind your employer or such entity to the License Agreement. If you do not have the requisite authority, you may not accept the License Agreement or use the Preview on behalf of your employer or other entity.
+
+3. Preview License from Google
+
+3.1 Subject to the terms of the License Agreement, Google grants you a royalty-free, non-assignable, non-exclusive, non-sublicensable, limited, revocable license to use the Preview, personally or internally within your company or organization, solely to develop applications to run on the Android platform.
+
+3.2 You agree that Google or third parties owns all legal right, title and interest in and to the Preview, including any Intellectual Property Rights that subsist in the Preview. "Intellectual Property Rights" means any and all rights under patent law, copyright law, trade secret law, trademark law, and any and all other proprietary rights. Google reserves all rights not expressly granted to you.
+
+3.3 You may not use the Preview for any purpose not expressly permitted by the License Agreement. Except to the extent required by applicable third party licenses, you may not: (a) copy (except for backup purposes), modify, adapt, redistribute, decompile, reverse engineer, disassemble, or create derivative works of the Preview or any part of the Preview; or (b) load any part of the Preview onto a mobile handset or any other hardware device except a personal computer, combine any part of the Preview with other software, or distribute any software or device incorporating a part of the Preview.
+
+3.4 You agree that you will not take any actions that may cause or result in the fragmentation of Android, including but not limited to distributing, participating in the creation of, or promoting in any way a software development kit derived from the Preview.
+
+3.5 Use, reproduction and distribution of components of the Preview licensed under an open source software license are governed solely by the terms of that open source software license and not the License Agreement. You agree to remain a licensee in good standing in regard to such open source software licenses under all the rights granted and to refrain from any actions that may terminate, suspend, or breach such rights.
+
+3.6 You agree that the form and nature of the Preview that Google provides may change without prior notice to you and that future versions of the Preview may be incompatible with applications developed on previous versions of the Preview. You agree that Google may stop (permanently or temporarily) providing the Preview (or any features within the Preview) to you or to users generally at Google's sole discretion, without prior notice to you.
+
+3.7 Nothing in the License Agreement gives you a right to use any of Google's trade names, trademarks, service marks, logos, domain names, or other distinctive brand features.
+
+3.8 You agree that you will not remove, obscure, or alter any proprietary rights notices (including copyright and trademark notices) that may be affixed to or contained within the Preview.
+
+4. Use of the Preview by You
+
+4.1 Google agrees that nothing in the License Agreement gives Google any right, title or interest from you (or your licensors) under the License Agreement in or to any software applications that you develop using the Preview, including any intellectual property rights that subsist in those applications.
+
+4.2 You agree to use the Preview and write applications only for purposes that are permitted by (a) the License Agreement, and (b) any applicable law, regulation or generally accepted practices or guidelines in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries).
+
+4.3 You agree that if you use the Preview to develop applications, you will protect the privacy and legal rights of users. If users provide you with user names, passwords, or other login information or personal information, you must make the users aware that the information will be available to your application, and you must provide legally adequate privacy notice and protection for those users. If your application stores personal or sensitive information provided by users, it must do so securely. If users provide you with Google Account information, your application may only use that information to access the user's Google Account when, and for the limited purposes for which, each user has given you permission to do so.
+
+4.4 You agree that you will not engage in any activity with the Preview, including the development or distribution of an application, that interferes with, disrupts, damages, or accesses in an unauthorized manner the servers, networks, or other properties or services of Google or any third party.
+
+4.5 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any data, content, or resources that you create, transmit or display through Android and/or applications for Android, and for the consequences of your actions (including any loss or damage which Google may suffer) by doing so.
+
+4.6 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any breach of your obligations under the License Agreement, any applicable third party contract or Terms of Service, or any applicable law or regulation, and for the consequences (including any loss or damage which Google or any third party may suffer) of any such breach.
+
+4.7 The Preview is in development, and your testing and feedback are an important part of the development process. By using the Preview, you acknowledge that implementation of some features are still under development and that you should not rely on the Preview having the full functionality of a stable release. You agree not to publicly distribute or ship any application using this Preview as this Preview will no longer be supported after the official Android SDK is released.
+
+5. Your Developer Credentials
+
+5.1 You agree that you are responsible for maintaining the confidentiality of any developer credentials that may be issued to you by Google or which you may choose yourself and that you will be solely responsible for all applications that are developed under your developer credentials.
+
+6. Privacy and Information
+
+6.1 In order to continually innovate and improve the Preview, Google may collect certain usage statistics from the software including but not limited to a unique identifier, associated IP address, version number of the software, and information on which tools and/or services in the Preview are being used and how they are being used. Before any of this information is collected, the Preview will notify you and seek your consent. If you withhold consent, the information will not be collected.
+
+6.2 The data collected is examined in the aggregate to improve the Preview and is maintained in accordance with Google's Privacy Policy located at http://www.google.com/policies/privacy/.
+
+7. Third Party Applications
+
+7.1 If you use the Preview to run applications developed by a third party or that access data, content or resources provided by a third party, you agree that Google is not responsible for those applications, data, content, or resources. You understand that all data, content or resources which you may access through such third party applications are the sole responsibility of the person from which they originated and that Google is not liable for any loss or damage that you may experience as a result of the use or access of any of those third party applications, data, content, or resources.
+
+7.2 You should be aware the data, content, and resources presented to you through such a third party application may be protected by intellectual property rights which are owned by the providers (or by other persons or companies on their behalf). You may not modify, rent, lease, loan, sell, distribute or create derivative works based on these data, content, or resources (either in whole or in part) unless you have been specifically given permission to do so by the relevant owners.
+
+7.3 You acknowledge that your use of such third party applications, data, content, or resources may be subject to separate terms between you and the relevant third party.
+
+8. Using Google APIs
+
+8.1 Google APIs
+
+8.1.1 If you use any API to retrieve data from Google, you acknowledge that the data may be protected by intellectual property rights which are owned by Google or those parties that provide the data (or by other persons or companies on their behalf). Your use of any such API may be subject to additional Terms of Service. You may not modify, rent, lease, loan, sell, distribute or create derivative works based on this data (either in whole or in part) unless allowed by the relevant Terms of Service.
+
+8.1.2 If you use any API to retrieve a user's data from Google, you acknowledge and agree that you shall retrieve data only with the user's explicit consent and only when, and for the limited purposes for which, the user has given you permission to do so.
+
+9. Terminating the License Agreement
+
+9.1 the License Agreement will continue to apply until terminated by either you or Google as set out below.
+
+9.2 If you want to terminate the License Agreement, you may do so by ceasing your use of the Preview and any relevant developer credentials.
+
+9.3 Google may at any time, terminate the License Agreement, with or without cause, upon notice to you.
+
+9.4 The License Agreement will automatically terminate without notice or other action upon the earlier of:
+(A) when Google ceases to provide the Preview or certain parts of the Preview to users in the country in which you are resident or from which you use the service; and
+(B) Google issues a final release version of the Android SDK.
+
+9.5 When the License Agreement is terminated, the license granted to you in the License Agreement will terminate, you will immediately cease all use of the Preview, and the provisions of paragraphs 10, 11, 12 and 14 shall survive indefinitely.
+
+10. DISCLAIMERS
+
+10.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT YOUR USE OF THE PREVIEW IS AT YOUR SOLE RISK AND THAT THE PREVIEW IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY KIND FROM GOOGLE.
+
+10.2 YOUR USE OF THE PREVIEW AND ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE USE OF THE PREVIEW IS AT YOUR OWN DISCRETION AND RISK AND YOU ARE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM SUCH USE. WITHOUT LIMITING THE FOREGOING, YOU UNDERSTAND THAT THE PREVIEW IS NOT A STABLE RELEASE AND MAY CONTAIN ERRORS, DEFECTS AND SECURITY VULNERABILITIES THAT CAN RESULT IN SIGNIFICANT DAMAGE, INCLUDING THE COMPLETE, IRRECOVERABLE LOSS OF USE OF YOUR COMPUTER SYSTEM OR OTHER DEVICE.
+
+10.3 GOOGLE FURTHER EXPRESSLY DISCLAIMS ALL WARRANTIES AND CONDITIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+11. LIMITATION OF LIABILITY
+
+11.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT GOOGLE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS SHALL NOT BE LIABLE TO YOU UNDER ANY THEORY OF LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES THAT MAY BE INCURRED BY YOU, INCLUDING ANY LOSS OF DATA, WHETHER OR NOT GOOGLE OR ITS REPRESENTATIVES HAVE BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES ARISING.
+
+12. Indemnification
+
+12.1 To the maximum extent permitted by law, you agree to defend, indemnify and hold harmless Google, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any and all losses, liabilities, damages, costs and expenses (including reasonable attorneys’ fees) arising out of or accruing from (a) your use of the Preview, (b) any application you develop on the Preview that infringes any Intellectual Property Rights of any person or defames any person or violates their rights of publicity or privacy, and (c) any non-compliance by you of the License Agreement.
+
+13. Changes to the License Agreement
+
+13.1 Google may make changes to the License Agreement as it distributes new versions of the Preview. When these changes are made, Google will make a new version of the License Agreement available on the website where the Preview is made available.
+
+14. General Legal Terms
+
+14.1 the License Agreement constitutes the whole legal agreement between you and Google and governs your use of the Preview (excluding any services which Google may provide to you under a separate written agreement), and completely replaces any prior agreements between you and Google in relation to the Preview.
+
+14.2 You agree that if Google does not exercise or enforce any legal right or remedy which is contained in the License Agreement (or which Google has the benefit of under any applicable law), this will not be taken to be a formal waiver of Google's rights and that those rights or remedies will still be available to Google.
+
+14.3 If any court of law, having the jurisdiction to decide on this matter, rules that any provision of the License Agreement is invalid, then that provision will be removed from the License Agreement without affecting the rest of the License Agreement. The remaining provisions of the License Agreement will continue to be valid and enforceable.
+
+14.4 You acknowledge and agree that each member of the group of companies of which Google is the parent shall be third party beneficiaries to the License Agreement and that such other companies shall be entitled to directly enforce, and rely upon, any provision of the License Agreement that confers a benefit on (or rights in favor of) them. Other than this, no other person or company shall be third party beneficiaries to the License Agreement.
+
+14.5 EXPORT RESTRICTIONS. THE PREVIEW IS SUBJECT TO UNITED STATES EXPORT LAWS AND REGULATIONS. YOU MUST COMPLY WITH ALL DOMESTIC AND INTERNATIONAL EXPORT LAWS AND REGULATIONS THAT APPLY TO THE PREVIEW. THESE LAWS INCLUDE RESTRICTIONS ON DESTINATIONS, END USERS AND END USE.
+
+14.6 The License Agreement may not be assigned or transferred by you without the prior written approval of Google, and any attempted assignment without such approval will be void. You shall not delegate your responsibilities or obligations under the License Agreement without the prior written approval of Google.
+
+14.7 The License Agreement, and your relationship with Google under the License Agreement, shall be governed by the laws of the State of California without regard to its conflict of laws provisions. You and Google agree to submit to the exclusive jurisdiction of the courts located within the county of Santa Clara, California to resolve any legal matter arising from the License Agreement. Notwithstanding this, you agree that Google shall still be allowed to apply for injunctive remedies (or an equivalent type of urgent legal relief) in any jurisdiction.
+
+
+</div>
\ No newline at end of file
diff --git a/docs/html/preview/preview_toc.cs b/docs/html/preview/preview_toc.cs
index 04f966a..3564b16 100644
--- a/docs/html/preview/preview_toc.cs
+++ b/docs/html/preview/preview_toc.cs
@@ -76,6 +76,8 @@
Hardware Features</a></li>
<li><a href="<?cs var:toroot ?>preview/tv/adt-1/index.html">
ADT-1</a></li>
+ <li><a href="<?cs var:toroot ?>preview/tv/publish/index.html">
+ Publishing TV Apps</a></li>
</ul>
</li>
@@ -96,6 +98,11 @@
<a href="<?cs var:toroot ?>preview/support.html">Support</a>
</div>
</li>
+ <li class="nav-section">
+ <div class="nav-section-header empty">
+ <a href="<?cs var:toroot ?>preview/license.html">License Agreement</a>
+ </div>
+ </li>
<li class="nav-section" style="margin: 20px 0 0 -10px;">
<div class="nav-section-header empty">
<a href="<?cs var:toroot ?>index.html" class="back-link">Developer Home</a>
diff --git a/docs/html/preview/tv/design/index.jd b/docs/html/preview/tv/design/index.jd
index b924a5c..58bfd5e 100644
--- a/docs/html/preview/tv/design/index.jd
+++ b/docs/html/preview/tv/design/index.jd
@@ -8,6 +8,11 @@
experience. It's important to understand how your app is presented in the main user interface and
how your app can help users get to the content they want quickly.</p>
+<p class="note">
+ <strong>Important:</strong> There are specific requirements your app must meet in order to
+ qualify as an Android TV app on Google Play. For more information, see the requirements listed
+ in <a href="{@docRoot}preview/tv/publish/index.html">Publishing TV Apps</a>.
+</p>
<h2>Home Screen</h2>
diff --git a/docs/html/preview/tv/games/index.jd b/docs/html/preview/tv/games/index.jd
index 61a26d2c..68d2d8b 100644
--- a/docs/html/preview/tv/games/index.jd
+++ b/docs/html/preview/tv/games/index.jd
@@ -21,7 +21,7 @@
players are viewing it simultaneously.</p>
-<h2 id=display>Display</h2>
+<h2 id="display">Display</h2>
<p>The two main things to keep in mind when developing games for the TV screen are its nature as a
shared display and the need to design your game for a landscape orientation.</p>
<h3>Shared display</h3>
@@ -105,14 +105,48 @@
href="http://developer.android.com/guide/topics/connectivity/bluetooth.html">Bluetooth</a>.</p>
<h2 id="manifest">Manifest</h2>
-<p>Games are displayed in a separate row from regular apps in the launcher. Android TV uses the
-<code>android:isGame</code> flag to differentiate games from non-game apps. You can assign it a
-value of either <code>true</code> or <code>false</code>. For example:</p>
-<pre class="fragment"><application>
- ...
-< android:isGame=["true" | "false"] >
- ...
-</application></pre>
+
+<p>
+ Games are displayed in a separate row from regular apps in the launcher. Android TV uses the
+ <code>android:isGame</code> attribute to differentiate games from non-game apps. Set this value
+ to <code>true</code> in your game's app manifest, as shown in the following code example:
+</p>
+
+<pre class="fragment">
+<application>
+ ...
+ < meta-data android:name="isGame" android:value="true" >
+ ...
+</application>
+</pre>
+
+
+<h3 id="gamepad">Game Controllers</h3>
+
+<p>
+ Games controllers may not be available or active for users of a TV device. In order to properly
+ inform users that your game requires (or just supports) a game controller, you must include
+ entries in the app manifest. If your game requires a game controller, you must include the
+ following entry in your app manifest:
+</p>
+
+<pre>
+ <uses-feature android:name="android.hardware.gamepad"/>
+</pre>
+
+<p>
+ If your game uses, but does not require, a game controller, include the following feature
+ entry in your app manifest:
+</p>
+
+<pre>
+ <uses-feature android:name="android.hardware.gamepad" android:required="false"/>
+</pre>
+
+<p>For more information about manifest entries, see
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">App Manifest</a>.
+</p>
+
<h2 id="gpgs">Google Play Game Services</h2>
<p>If your game integrates Google Play Game Services, you should keep in mind a number of
diff --git a/docs/html/preview/tv/publish/index.jd b/docs/html/preview/tv/publish/index.jd
new file mode 100644
index 0000000..f834493
--- /dev/null
+++ b/docs/html/preview/tv/publish/index.jd
@@ -0,0 +1,205 @@
+page.title=Publishing TV Apps
+page.tags="requirements","usability"
+
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#requirements">Publishing Requirements for TV Apps</a>
+ <ol>
+ <li><a href="#requirements-manifest">Manifest Requirements</a></li>
+ <li><a href="#requirements-usability">Usability Requirements</a></li>
+ </ol>
+ </li>
+ <li><a href="#faq">Frequently Asked Questions</a></li>
+ </ol>
+</div>
+</div>
+
+<p>
+ Apps for TV devices can be published like other Android apps. You must prepare your app for
+ release and then you can publish it through <a href=
+ "{@docRoot}distribute/googleplay/index.html">Google Play</a>. In order for your app to be
+ accepted as a TV app in Google Play, it must meet some additional requirements, which are covered
+ in this document.
+</p>
+
+<p class="note">
+ <strong>Note:</strong> You will not be able to publish apps to TV devices through <a href=
+ "{@docRoot}distribute/googleplay/index.html">Google Play</a> until Android L SDK is released.
+</p>
+
+
+<h2 id="requirements">Publishing Requirements for TV Apps</h2>
+
+<p>
+ Your app must provide specific manifest declarations and meet some minimum usability requirements
+ before it can qualify as TV app on Google Play. Make sure your app meets these requirements to
+ get your app ready for TV devices.
+</p>
+
+<p class="caution">
+ <strong>Caution:</strong> Your app must meet all of the requirements described in this section in
+ order to qualify as a TV app on Google Play. If your app does not meet the usability requirements
+ described below, the Google Play team will contact you through the email address specified in main
+ <a href="https://play.google.com/apps/publish/">Google Play Developer Console</a> account
+ associated with the app.
+</p>
+
+<h3 id="requirements-manifest">Manifest Requirements</h3>
+
+<p>
+ Developers who want their apps to be considered for publishing on TV devices <em>must</em>
+ include a manifest entry that declares an activity which handles the {@code
+ android.intent.category.LEANBACK_LAUNCHER} intent filter. For more information about including
+ the required manifest entries, see <a href=
+ "{@docRoot}preview/tv/start/index.html#tv-activity">Get Started with TV Apps</a>.
+</p>
+
+<p class="caution">
+ <strong>Caution:</strong> If you do not include the <a href=
+ "{@docRoot}preview/tv/start/index.html#tv-activity">required manifest entries</a> for TV devices,
+ your app is not considered as a TV app. The app will not be reviewed for the TV app usability
+ requirements and will not be able to qualify as a TV app on Google Play.
+</p>
+
+
+<h3 id="requirements-usability">Usability Requirements</h3>
+
+<p>
+ Users bring a different set of expectations when watching TV. Apps for Android TV devices have a
+ different interaction, look and feel from Android apps on the phone or tablet. How users interact
+ with TVs (with a remote control device) and how they view them (sitting about 10 feet away),
+ significantly changes the requirements for what makes a good user experience in an app.
+</p>
+
+<p>
+ The first step toward creating a great experience for users on TV is to review and follow the
+ <a href="{@docRoot}preview/tv/design/index.html">Design for TV</a> guidelines. These guidelines
+ provide general directions for designing a TV app as well as some specific implementation
+ instructions.
+</p>
+
+<p>
+ Apps for TV devices must meet some specific requirements for usability. Only apps that meet the
+ following usability criteria will qualify as an TV app on Google Play:
+</p>
+
+<ul>
+ <li>App functionality must be navigable using 5-way D-pad controls, unless the app requires a
+ game controller.
+ (<a href="{@docRoot}preview/tv/ui/navigation.html#d-pad-navigation">details</a>)
+ <ul>
+ <li>If the app requires a game controller, all functionality must be navigable using
+ standard Android game controller keys.
+ (<a href="{@docRoot}training/game-controllers/controller-input.html#button">details</a>)
+ </li>
+ </ul>
+ </li>
+
+ <li>Layouts used on TV devices must be designed for landscape orientation.
+ (<a href="{@docRoot}preview/tv/ui/layouts.html#structure">details</a>)</li>
+
+ <li>Core text used in TV layouts must be at least 16sp in size and all text must be at least
+ 12sp.</li>
+
+ <li>Text and functionality should be placed inside an overscan margin of at least 27dp from the
+ top and bottom edges and 48dp from the left and right edges of the TV screen.
+ (<a href="{@docRoot}preview/tv/ui/layouts.html#overscan">details</a>)</li>
+
+ <li>Apps that uses full-screen, non-video ads, must ensure that the ads are immediately
+ dismissible by the user with D-pad controls.</li>
+
+ <li>Apps must not depend on having a web browser app on TV devices. Apps can use <a href=
+ "http://developer.android.com/reference/android/webkit/WebView.html">WebView components</a> to
+ show web content where needed.</li>
+
+ <li>Apps that uses clickable, non-full screen, non-video ads must ensure that the ads do not link
+ to a web URL. These ads must also not link to an app or game that is not available on TV devices
+ and, therefore, not available in the Google Play store for TV.</li>
+
+ <li>Apps must display correctly on the Android TV launcher by doing the following:
+ <ul>
+ <li>Include in the app manifest an intent filter of type {@code ACTION_MAIN} with an intent
+ category {@code CATEGORY_LEANBACK_LAUNCHER}.
+ (<a href="{@docRoot}preview/tv/start/index.html#tv-activity">details</a>)
+ </li>
+
+ <li>Provide a 320x180px banner image resource and declare it in the manifest.</li>
+
+ <li>If the app is a game, it must set the {@code isGame} property to {@code true} in the
+ manifest. (<a href="{@docRoot}preview/tv/games/index.html#manifest">details</a>)
+ </li>
+ </ul>
+ </li>
+
+ <li>App must not partially obscure other apps. Apps must fill the entire screen and have a
+ non-transparent background.
+ </li>
+
+ <li>Music and audio apps that continue to play sound after a user has left the app must provide
+ a <strong>Now Playing</strong> card on the home screen recommendation row so users can easily
+ control playback. Developers should use the {@code android.media.session.MediaSession} API
+ to enable this card and link playback to a specific activity.
+ </li>
+
+ <li>Media apps that play video or music content must toggle between play and pause of media
+ playback when a <a href="{@docRoot}reference/android/view/KeyEvent.html#KEYCODE_MEDIA_PLAY_PAUSE">
+ play or pause key event</a> is sent during playback.
+ </li>
+
+ <li>Games that use a gamepad in order to play must define gamepad use in the app manifest.
+ (<a href="{@docRoot}preview/tv/games/index.html#gamepad">details</a>)
+ </li>
+
+ <li>Games that provide in-game instructions for game controllers must show a generic controller
+ layout that does not include any branding. You can download generic controller artwork from
+ here: <a href="http://storage.googleapis.com/androiddevelopers/design/android_tv_gamepad_template-2014-10.zip">
+ android_tv_gamepad_template_2014-10.zip</a>.
+ </li>
+</ul>
+
+
+<h2 id="faq">Frequently Asked Questions</h2>
+
+<p>
+ <strong>After I submit my app, how will find out if my app does not meet all the requirements for
+ TV devices?</strong>
+</p>
+<p>
+ If your app does not meet the usability requirements described on this page, the Play Store team
+ will contact you through the email address specified in main <a href=
+ "https://play.google.com/apps/publish/">Google Play Developer Console</a> account associated with
+ the app.
+</p>
+<p class="caution">
+ <strong>Caution:</strong> Make sure your app includes the <a href=
+ "{@docRoot}preview/tv/start/index.html#tv-activity">required manifest entries</a> for TV devices,
+ otherwise your app will not be considered a TV app and will not be reviewed for TV usability
+ requirements.
+</p>
+
+
+<p>
+ <strong>My app targets more than just TV devices. If my app does not meet the TV device
+ requirements, will my new or updated app still appear on Google Play for phones and
+ tablets?</strong>
+</p>
+<p>
+ Yes. The requirements described above only restrict distribution to the Google Play Store on TV
+ devices. Distribution to other device types, such as phones, tablets and other devices, is not
+ affected.
+</p>
+
+
+<p>
+ <strong>If my app meets the publishing requirements, when will it be available in the Google
+ Play Store on TV devices?</strong>
+</p>
+
+<p>
+ Apps that meet the requirements for TV will appear in the Google Play Store on TV devices
+ <em>after</em> the official release of Android L.
+</p>
\ No newline at end of file
diff --git a/docs/html/preview/tv/start/index.jd b/docs/html/preview/tv/start/index.jd
index 5af28a6..8081995 100644
--- a/docs/html/preview/tv/start/index.jd
+++ b/docs/html/preview/tv/start/index.jd
@@ -24,6 +24,12 @@
<p>This guide describes how to prepare your development environment and projects for building
TV apps, including updating your existing app to run on TV devices.</p>
+<p class="note">
+ <strong>Important:</strong> There are specific requirements your app must meet in order to
+ qualify as an Android TV app on Google Play. For more information, see the requirements listed
+ in <a href="{@docRoot}preview/tv/publish/index.html">Publishing TV Apps</a>.
+</p>
+
<h2 id="prerequisites">Prerequisites</h2>
diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd
index 9ed70ed..d91e7e8 100644
--- a/docs/html/sdk/index.jd
+++ b/docs/html/sdk/index.jd
@@ -308,7 +308,7 @@
If you're a new Android developer, you should consider starting with Android Studio, because the
ADT plugin for Eclipse is no longer in active development.</p>
<p style="margin: 0;">
- <a href="/sdk/installing/studio.html">Learn more about Android Studio</a></p>
+ <a href="/sdk/installing/studio.html" style="position:relative;z-index:99">Learn more about Android Studio</a></p>
</div>
diff --git a/libs/androidfw/ResourceTypes.cpp b/libs/androidfw/ResourceTypes.cpp
index 8cef137..b5d2885 100644
--- a/libs/androidfw/ResourceTypes.cpp
+++ b/libs/androidfw/ResourceTypes.cpp
@@ -4175,57 +4175,61 @@
continue;
}
- const ssize_t ti = group->findType16(type, typeLen);
- if (ti < 0) {
- TABLE_NOISY(printf("Type not found in package %s\n", String8(group->name).string()));
- continue;
- }
-
- const TypeList& typeList = group->types[ti];
- if (typeList.isEmpty()) {
- TABLE_NOISY(printf("Expected type structure not found in package %s for index %d\n",
- String8(group->name).string(), ti));
- continue;
- }
-
- const size_t typeCount = typeList.size();
- for (size_t i = 0; i < typeCount; i++) {
- const Type* t = typeList[i];
- const ssize_t ei = t->package->keyStrings.indexOfString(name, nameLen);
- if (ei < 0) {
+ const size_t packageCount = group->packages.size();
+ for (size_t pi = 0; pi < packageCount; pi++) {
+ ssize_t ti = group->packages[pi]->typeStrings.indexOfString(type, typeLen);
+ if (ti < 0) {
continue;
}
- const size_t configCount = t->configs.size();
- for (size_t j = 0; j < configCount; j++) {
- const TypeVariant tv(t->configs[j]);
- for (TypeVariant::iterator iter = tv.beginEntries();
- iter != tv.endEntries();
- iter++) {
- const ResTable_entry* entry = *iter;
- if (entry == NULL) {
- continue;
- }
+ ti += group->packages[pi]->typeIdOffset;
- if (dtohl(entry->key.index) == (size_t) ei) {
- uint32_t resId = Res_MAKEID(group->id - 1, ti, iter.index());
- if (outTypeSpecFlags) {
- Entry result;
- if (getEntry(group, ti, iter.index(), NULL, &result) != NO_ERROR) {
- ALOGW("Failed to find spec flags for %s:%s/%s (0x%08x)",
- String8(group->name).string(),
- String8(String16(type, typeLen)).string(),
- String8(String16(name, nameLen)).string(),
- resId);
- return 0;
- }
- *outTypeSpecFlags = result.specFlags;
+ const TypeList& typeList = group->types[ti];
+ if (typeList.isEmpty()) {
+ TABLE_NOISY(printf("Expected type structure not found in package %s for index %d\n",
+ String8(group->name).string(), ti));
+ continue;
+ }
- if (fakePublic) {
- *outTypeSpecFlags |= ResTable_typeSpec::SPEC_PUBLIC;
- }
+ const size_t typeCount = typeList.size();
+ for (size_t i = 0; i < typeCount; i++) {
+ const Type* t = typeList[i];
+ const ssize_t ei = t->package->keyStrings.indexOfString(name, nameLen);
+ if (ei < 0) {
+ continue;
+ }
+
+ const size_t configCount = t->configs.size();
+ for (size_t j = 0; j < configCount; j++) {
+ const TypeVariant tv(t->configs[j]);
+ for (TypeVariant::iterator iter = tv.beginEntries();
+ iter != tv.endEntries();
+ iter++) {
+ const ResTable_entry* entry = *iter;
+ if (entry == NULL) {
+ continue;
}
- return resId;
+
+ if (dtohl(entry->key.index) == (size_t) ei) {
+ uint32_t resId = Res_MAKEID(group->id - 1, ti, iter.index());
+ if (outTypeSpecFlags) {
+ Entry result;
+ if (getEntry(group, ti, iter.index(), NULL, &result) != NO_ERROR) {
+ ALOGW("Failed to find spec flags for %s:%s/%s (0x%08x)",
+ String8(group->name).string(),
+ String8(String16(type, typeLen)).string(),
+ String8(String16(name, nameLen)).string(),
+ resId);
+ return 0;
+ }
+ *outTypeSpecFlags = result.specFlags;
+
+ if (fakePublic) {
+ *outTypeSpecFlags |= ResTable_typeSpec::SPEC_PUBLIC;
+ }
+ }
+ return resId;
+ }
}
}
}
diff --git a/libs/androidfw/tests/Split_test.cpp b/libs/androidfw/tests/Split_test.cpp
index 82703f9..f63f566 100644
--- a/libs/androidfw/tests/Split_test.cpp
+++ b/libs/androidfw/tests/Split_test.cpp
@@ -179,7 +179,7 @@
EXPECT_EQ(Res_value::TYPE_STRING, val.dataType);
}
-TEST(SplitFeatureTest, TestNewResourceIsAccessibleByName) {
+TEST(SplitFeatureTest, TestNewResourceNameHasCorrectName) {
ResTable table;
ASSERT_EQ(NO_ERROR, table.add(basic_arsc, basic_arsc_len));
@@ -200,4 +200,17 @@
String16(name.name, name.nameLen));
}
+TEST(SplitFeatureTest, TestNewResourceIsAccessibleByName) {
+ ResTable table;
+ ASSERT_EQ(NO_ERROR, table.add(basic_arsc, basic_arsc_len));
+ ASSERT_EQ(NO_ERROR, table.add(feature_arsc, feature_arsc_len));
+
+ const String16 name("test3");
+ const String16 type("string");
+ const String16 package("com.android.test.basic");
+ ASSERT_EQ(base::R::string::test3, table.identifierForName(name.string(), name.size(),
+ type.string(), type.size(),
+ package.string(), package.size()));
+}
+
} // namespace
diff --git a/media/java/android/media/MediaHTTPConnection.java b/media/java/android/media/MediaHTTPConnection.java
index 05acf90..d0f3334 100644
--- a/media/java/android/media/MediaHTTPConnection.java
+++ b/media/java/android/media/MediaHTTPConnection.java
@@ -16,6 +16,7 @@
package android.media;
+import android.net.NetworkUtils;
import android.os.IBinder;
import android.os.StrictMode;
import android.util.Log;
@@ -25,6 +26,7 @@
import java.io.IOException;
import java.net.CookieHandler;
import java.net.CookieManager;
+import java.net.Proxy;
import java.net.URL;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
@@ -137,6 +139,29 @@
}
}
+ private static final boolean isLocalHost(URL url) {
+ if (url == null) {
+ return false;
+ }
+
+ String host = url.getHost();
+
+ if (host == null) {
+ return false;
+ }
+
+ try {
+ if (host.equalsIgnoreCase("localhost")) {
+ return true;
+ }
+ if (NetworkUtils.numericToInetAddress(host).isLoopbackAddress()) {
+ return true;
+ }
+ } catch (IllegalArgumentException iex) {
+ }
+ return false;
+ }
+
private void seekTo(long offset) throws IOException {
teardownConnection();
@@ -145,8 +170,17 @@
int redirectCount = 0;
URL url = mURL;
+
+ // do not use any proxy for localhost (127.0.0.1)
+ boolean noProxy = isLocalHost(url);
+
while (true) {
- mConnection = (HttpURLConnection)url.openConnection();
+ if (noProxy) {
+ mConnection = (HttpURLConnection)url.openConnection(Proxy.NO_PROXY);
+ } else {
+ mConnection = (HttpURLConnection)url.openConnection();
+ }
+
// handle redirects ourselves if we do not allow cross-domain redirect
mConnection.setInstanceFollowRedirects(mAllowCrossDomainRedirect);
diff --git a/packages/SystemUI/res/values-lt/strings.xml b/packages/SystemUI/res/values-lt/strings.xml
index 7439b97..b30b80c 100644
--- a/packages/SystemUI/res/values-lt/strings.xml
+++ b/packages/SystemUI/res/values-lt/strings.xml
@@ -31,7 +31,7 @@
</plurals>
<string name="status_bar_no_notifications_title" msgid="4755261167193833213">"Nėra įspėjimų"</string>
<string name="status_bar_ongoing_events_title" msgid="1682504513316879202">"Vykstantys"</string>
- <string name="status_bar_latest_events_title" msgid="6594767438577593172">"Įspėjimai"</string>
+ <string name="status_bar_latest_events_title" msgid="6594767438577593172">"Pranešimai"</string>
<string name="battery_low_title" msgid="6456385927409742437">"Akumuliatorius senka"</string>
<string name="battery_low_percent_format" msgid="1077244949318261761">"Liko <xliff:g id="NUMBER">%d%%</xliff:g>"</string>
<string name="battery_low_percent_format_saver_started" msgid="6534746636002666456">"Liko <xliff:g id="NUMBER">%d%%</xliff:g>. Akumuliatoriaus tausojimo priemonė įjungta."</string>
diff --git a/packages/SystemUI/res/values-sw/strings.xml b/packages/SystemUI/res/values-sw/strings.xml
index e66522f..9ab3d91 100644
--- a/packages/SystemUI/res/values-sw/strings.xml
+++ b/packages/SystemUI/res/values-sw/strings.xml
@@ -181,7 +181,7 @@
<string name="accessibility_quick_settings_bluetooth_changed_off" msgid="2730003763480934529">"Bluetooth imezimwa."</string>
<string name="accessibility_quick_settings_bluetooth_changed_on" msgid="8722351798763206577">"Bluetooth imewashwa."</string>
<string name="accessibility_quick_settings_location_off" msgid="5119080556976115520">"Programu ya Kuonyesha mahali ulipo imezimwa."</string>
- <string name="accessibility_quick_settings_location_on" msgid="5809937096590102036">"Programu ya Kuonyesha mahali ulipo inawaka."</string>
+ <string name="accessibility_quick_settings_location_on" msgid="5809937096590102036">"Programu ya kuonyesha mahali ulipo imewashwa."</string>
<string name="accessibility_quick_settings_location_changed_off" msgid="8526845571503387376">"Programu ya Kuonyesha mahali ulipo imezimwa."</string>
<string name="accessibility_quick_settings_location_changed_on" msgid="339403053079338468">"Programu ya Kuonyesha mahali ulipo imewashwa."</string>
<string name="accessibility_quick_settings_alarm" msgid="3959908972897295660">"Kengele imewekwa <xliff:g id="TIME">%s</xliff:g>."</string>
@@ -251,7 +251,7 @@
<string name="quick_settings_wifi_detail_empty_text" msgid="2831702993995222755">"Hakuna mitandao iliyohifadhiwa inayopatikana"</string>
<string name="quick_settings_cast_title" msgid="1893629685050355115">"Tuma skrini"</string>
<string name="quick_settings_casting" msgid="6601710681033353316">"Inatuma"</string>
- <string name="quick_settings_cast_device_default_name" msgid="5367253104742382945">"Kifaa kisichokuwa na jina"</string>
+ <string name="quick_settings_cast_device_default_name" msgid="5367253104742382945">"Kifaa hakina jina"</string>
<string name="quick_settings_cast_device_default_description" msgid="2484573682378634413">"Tayari kutuma"</string>
<string name="quick_settings_cast_detail_empty_text" msgid="311785821261640623">"Hakuna vifaa vilivyopatikana"</string>
<string name="quick_settings_brightness_dialog_title" msgid="8599674057673605368">"Ung\'avu"</string>
diff --git a/packages/SystemUI/src/com/android/systemui/statusbar/ActivatableNotificationView.java b/packages/SystemUI/src/com/android/systemui/statusbar/ActivatableNotificationView.java
index 0d5ebe7..e4faa6a 100644
--- a/packages/SystemUI/src/com/android/systemui/statusbar/ActivatableNotificationView.java
+++ b/packages/SystemUI/src/com/android/systemui/statusbar/ActivatableNotificationView.java
@@ -403,6 +403,7 @@
}
private void fadeBackground() {
+ mBackgroundNormal.animate().cancel();
if (mDimmed) {
mBackgroundDimmed.setVisibility(View.VISIBLE);
} else {
@@ -446,6 +447,7 @@
mBackgroundDimmed.setVisibility(View.VISIBLE);
mBackgroundNormal.setVisibility(View.INVISIBLE);
} else {
+ cancelFadeAnimations();
mBackgroundDimmed.setVisibility(View.INVISIBLE);
mBackgroundNormal.setVisibility(View.VISIBLE);
mBackgroundNormal.setAlpha(1f);
@@ -453,6 +455,13 @@
}
}
+ private void cancelFadeAnimations() {
+ if (mBackgroundAnimator != null) {
+ mBackgroundAnimator.cancel();
+ }
+ mBackgroundNormal.animate().cancel();
+ }
+
@Override
protected void onLayout(boolean changed, int left, int top, int right, int bottom) {
super.onLayout(changed, left, top, right, bottom);
diff --git a/packages/SystemUI/src/com/android/systemui/statusbar/phone/PhoneStatusBarPolicy.java b/packages/SystemUI/src/com/android/systemui/statusbar/phone/PhoneStatusBarPolicy.java
index 6006217..47e1ab5 100644
--- a/packages/SystemUI/src/com/android/systemui/statusbar/phone/PhoneStatusBarPolicy.java
+++ b/packages/SystemUI/src/com/android/systemui/statusbar/phone/PhoneStatusBarPolicy.java
@@ -85,7 +85,7 @@
}
else if (action.equals(BluetoothAdapter.ACTION_STATE_CHANGED) ||
action.equals(BluetoothAdapter.ACTION_CONNECTION_STATE_CHANGED)) {
- updateBluetooth(intent);
+ updateBluetooth();
}
else if (action.equals(AudioManager.RINGER_MODE_CHANGED_ACTION)) {
updateVolumeZen();
@@ -128,16 +128,7 @@
mService.setIconVisibility(SLOT_CDMA_ERI, false);
// bluetooth status
- BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter();
- int bluetoothIcon = R.drawable.stat_sys_data_bluetooth;
- if (adapter != null) {
- mBluetoothEnabled = (adapter.getState() == BluetoothAdapter.STATE_ON);
- if (adapter.getConnectionState() == BluetoothAdapter.STATE_CONNECTED) {
- bluetoothIcon = R.drawable.stat_sys_data_bluetooth_connected;
- }
- }
- mService.setIcon(SLOT_BLUETOOTH, bluetoothIcon, 0, null);
- mService.setIconVisibility(SLOT_BLUETOOTH, mBluetoothEnabled);
+ updateBluetooth();
// Alarm clock
mService.setIcon(SLOT_ALARM_CLOCK, R.drawable.stat_sys_alarm, 0, null);
@@ -253,25 +244,19 @@
}
}
- private final void updateBluetooth(Intent intent) {
+ private final void updateBluetooth() {
+ BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter();
int iconId = R.drawable.stat_sys_data_bluetooth;
- String contentDescription = null;
- String action = intent.getAction();
- if (action.equals(BluetoothAdapter.ACTION_STATE_CHANGED)) {
- int state = intent.getIntExtra(BluetoothAdapter.EXTRA_STATE, BluetoothAdapter.ERROR);
- mBluetoothEnabled = state == BluetoothAdapter.STATE_ON;
- } else if (action.equals(BluetoothAdapter.ACTION_CONNECTION_STATE_CHANGED)) {
- int state = intent.getIntExtra(BluetoothAdapter.EXTRA_CONNECTION_STATE,
- BluetoothAdapter.STATE_DISCONNECTED);
- if (state == BluetoothAdapter.STATE_CONNECTED) {
+ String contentDescription =
+ mContext.getString(R.string.accessibility_bluetooth_disconnected);
+ if (adapter != null) {
+ mBluetoothEnabled = (adapter.getState() == BluetoothAdapter.STATE_ON);
+ if (adapter.getConnectionState() == BluetoothAdapter.STATE_CONNECTED) {
iconId = R.drawable.stat_sys_data_bluetooth_connected;
contentDescription = mContext.getString(R.string.accessibility_bluetooth_connected);
- } else {
- contentDescription = mContext.getString(
- R.string.accessibility_bluetooth_disconnected);
}
} else {
- return;
+ mBluetoothEnabled = false;
}
mService.setIcon(SLOT_BLUETOOTH, iconId, 0, contentDescription);
diff --git a/packages/WallpaperCropper/res/layout/actionbar_set_wallpaper.xml b/packages/WallpaperCropper/res/layout/actionbar_set_wallpaper.xml
index 2a0188a..54f8ff3 100644
--- a/packages/WallpaperCropper/res/layout/actionbar_set_wallpaper.xml
+++ b/packages/WallpaperCropper/res/layout/actionbar_set_wallpaper.xml
@@ -31,5 +31,6 @@
android:drawableLeft="@drawable/ic_actionbar_accept"
android:drawablePadding="8dp"
android:gravity="center_vertical"
- android:text="@string/wallpaper_instructions" />
+ android:text="@string/wallpaper_instructions"
+ android:textColor="@android:color/white" />
</FrameLayout>
diff --git a/policy/src/com/android/internal/policy/impl/PhoneWindow.java b/policy/src/com/android/internal/policy/impl/PhoneWindow.java
index e9a114a..9c81f0a 100644
--- a/policy/src/com/android/internal/policy/impl/PhoneWindow.java
+++ b/policy/src/com/android/internal/policy/impl/PhoneWindow.java
@@ -22,6 +22,8 @@
import static android.view.ViewGroup.LayoutParams.WRAP_CONTENT;
import static android.view.WindowManager.LayoutParams.*;
+import android.app.SearchManager;
+import android.os.UserHandle;
import com.android.internal.R;
import com.android.internal.view.RootViewSurfaceTaker;
import com.android.internal.view.StandaloneActionMode;
@@ -4004,13 +4006,21 @@
* @return true if search window opened
*/
private boolean launchDefaultSearch() {
+ boolean result;
final Callback cb = getCallback();
if (cb == null || isDestroyed()) {
- return false;
+ result = false;
} else {
sendCloseSystemWindows("search");
- return cb.onSearchRequested();
+ result = cb.onSearchRequested();
}
+ if (!result && (getContext().getResources().getConfiguration().uiMode
+ & Configuration.UI_MODE_TYPE_MASK) == Configuration.UI_MODE_TYPE_TELEVISION) {
+ // On TVs, if the app doesn't implement search, we want to launch assist.
+ return ((SearchManager)getContext().getSystemService(Context.SEARCH_SERVICE))
+ .launchAssistAction(0, null, UserHandle.myUserId());
+ }
+ return result;
}
@Override
diff --git a/services/appwidget/java/com/android/server/appwidget/AppWidgetServiceImpl.java b/services/appwidget/java/com/android/server/appwidget/AppWidgetServiceImpl.java
index fca13f8..7623514 100644
--- a/services/appwidget/java/com/android/server/appwidget/AppWidgetServiceImpl.java
+++ b/services/appwidget/java/com/android/server/appwidget/AppWidgetServiceImpl.java
@@ -1839,13 +1839,14 @@
// If the provider was not found it may be because it was restored and
// we did not know its UID so let us find if there is such one.
if (existing == null) {
- providerId = new ProviderId(UNKNOWN_UID, componentName);
- existing = lookupProviderLocked(providerId);
+ ProviderId restoredProviderId = new ProviderId(UNKNOWN_UID, componentName);
+ existing = lookupProviderLocked(restoredProviderId);
}
if (existing != null) {
if (existing.zombie && !mSafeMode) {
// it's a placeholder that was set up during an app restore
+ existing.id = providerId;
existing.zombie = false;
existing.info = provider.info; // the real one filled out from the ResolveInfo
if (DEBUG) {
diff --git a/services/backup/java/com/android/server/backup/BackupManagerService.java b/services/backup/java/com/android/server/backup/BackupManagerService.java
index 9a5ffbd..3694d61 100644
--- a/services/backup/java/com/android/server/backup/BackupManagerService.java
+++ b/services/backup/java/com/android/server/backup/BackupManagerService.java
@@ -2415,6 +2415,11 @@
mStatus = invokeAgentForBackup(PACKAGE_MANAGER_SENTINEL,
IBackupAgent.Stub.asInterface(pmAgent.onBind()), mTransport);
addBackupTrace("PMBA invoke: " + mStatus);
+
+ // Because the PMBA is a local instance, it has already executed its
+ // backup callback and returned. Blow away the lingering (spurious)
+ // pending timeout message for it.
+ mBackupHandler.removeMessages(MSG_TIMEOUT);
}
if (mStatus == BackupTransport.TRANSPORT_NOT_INITIALIZED) {
@@ -7048,6 +7053,11 @@
private void startRestore() {
sendStartRestore(mAcceptSet.size());
+ // If we're starting a full-system restore, set up to begin widget ID remapping
+ if (mIsSystemRestore) {
+ AppWidgetBackupBridge.restoreStarting(UserHandle.USER_OWNER);
+ }
+
try {
String transportDir = mTransport.transportDirName();
mStateDir = new File(mBaseStateDir, transportDir);
diff --git a/services/core/java/com/android/server/MmsServiceBroker.java b/services/core/java/com/android/server/MmsServiceBroker.java
index 0fb80c9..926235f 100644
--- a/services/core/java/com/android/server/MmsServiceBroker.java
+++ b/services/core/java/com/android/server/MmsServiceBroker.java
@@ -34,7 +34,7 @@
import android.os.IBinder;
import android.os.Message;
import android.os.RemoteException;
-import android.os.ServiceManager;
+import android.os.SystemClock;
import android.telephony.TelephonyManager;
import android.util.Slog;
@@ -56,10 +56,12 @@
private static final Uri FAKE_SMS_DRAFT_URI = Uri.parse("content://sms/draft/0");
private static final Uri FAKE_MMS_DRAFT_URI = Uri.parse("content://mms/draft/0");
+ private static final long SERVICE_CONNECTION_WAIT_TIME_MS = 4 * 1000L; // 4 seconds
+ private static final long RETRY_DELAY_ON_DISCONNECTION_MS = 3 * 1000L; // 3 seconds
+
private Context mContext;
// The actual MMS service instance to invoke
private volatile IMms mService;
- private boolean mIsConnecting;
// Cached system service instances
private volatile AppOpsManager mAppOpsManager = null;
@@ -85,7 +87,7 @@
Slog.i(TAG, "MmsService connected");
synchronized (MmsServiceBroker.this) {
mService = IMms.Stub.asInterface(service);
- mIsConnecting = false;
+ MmsServiceBroker.this.notifyAll();
}
}
@@ -94,8 +96,13 @@
Slog.i(TAG, "MmsService unexpectedly disconnected");
synchronized (MmsServiceBroker.this) {
mService = null;
- mIsConnecting = false;
+ MmsServiceBroker.this.notifyAll();
}
+ // Retry connecting, but not too eager (with a delay)
+ // since it may come back by itself.
+ mConnectionHandler.sendMessageDelayed(
+ mConnectionHandler.obtainMessage(MSG_TRY_CONNECTING),
+ RETRY_DELAY_ON_DISCONNECTION_MS);
}
};
@@ -103,7 +110,6 @@
super(context);
mContext = context;
mService = null;
- mIsConnecting = false;
}
@Override
@@ -118,29 +124,50 @@
private void tryConnecting() {
Slog.i(TAG, "Connecting to MmsService");
synchronized (this) {
- if (mIsConnecting) {
- Slog.d(TAG, "Already connecting");
+ if (mService != null) {
+ Slog.d(TAG, "Already connected");
return;
}
final Intent intent = new Intent();
intent.setComponent(MMS_SERVICE_COMPONENT);
try {
- if (mContext.bindService(intent, mConnection, Context.BIND_AUTO_CREATE)) {
- mIsConnecting = true;
- } else {
- Slog.e(TAG, "Failed to connect to MmsService");
+ if (!mContext.bindService(intent, mConnection, Context.BIND_AUTO_CREATE)) {
+ Slog.e(TAG, "Failed to bind to MmsService");
}
} catch (SecurityException e) {
- Slog.e(TAG, "Forbidden to connect to MmsService", e);
+ Slog.e(TAG, "Forbidden to bind to MmsService", e);
}
}
}
private void ensureService() {
- if (mService == null) {
- // Service instance lost, kicking off the connection again
- mConnectionHandler.sendMessage(mConnectionHandler.obtainMessage(MSG_TRY_CONNECTING));
- throw new RuntimeException("MMS service is not connected");
+ synchronized (this) {
+ if (mService == null) {
+ // Service is not connected. Try blocking connecting.
+ Slog.w(TAG, "MmsService not connected. Try connecting...");
+ mConnectionHandler.sendMessage(
+ mConnectionHandler.obtainMessage(MSG_TRY_CONNECTING));
+ final long shouldEnd =
+ SystemClock.elapsedRealtime() + SERVICE_CONNECTION_WAIT_TIME_MS;
+ long waitTime = SERVICE_CONNECTION_WAIT_TIME_MS;
+ while (waitTime > 0) {
+ try {
+ // TODO: consider using Java concurrent construct instead of raw object wait
+ this.wait(waitTime);
+ } catch (InterruptedException e) {
+ Slog.w(TAG, "Connection wait interrupted", e);
+ }
+ if (mService != null) {
+ // Success
+ return;
+ }
+ // Calculate remaining waiting time to make sure we wait the full timeout period
+ waitTime = shouldEnd - SystemClock.elapsedRealtime();
+ }
+ // Timed out. Something's really wrong.
+ Slog.e(TAG, "Can not connect to MmsService (timed out)");
+ throw new RuntimeException("Timed out in connecting to MmsService");
+ }
}
}
diff --git a/services/core/java/com/android/server/am/ActivityManagerService.java b/services/core/java/com/android/server/am/ActivityManagerService.java
index 9e0483d..bb4db90 100755
--- a/services/core/java/com/android/server/am/ActivityManagerService.java
+++ b/services/core/java/com/android/server/am/ActivityManagerService.java
@@ -434,10 +434,19 @@
public class PendingAssistExtras extends Binder implements Runnable {
public final ActivityRecord activity;
+ public final Bundle extras;
+ public final Intent intent;
+ public final String hint;
+ public final int userHandle;
public boolean haveResult = false;
public Bundle result = null;
- public PendingAssistExtras(ActivityRecord _activity) {
+ public PendingAssistExtras(ActivityRecord _activity, Bundle _extras, Intent _intent,
+ String _hint, int _userHandle) {
activity = _activity;
+ extras = _extras;
+ intent = _intent;
+ hint = _hint;
+ userHandle = _userHandle;
}
@Override
public void run() {
@@ -10449,6 +10458,31 @@
}
public Bundle getAssistContextExtras(int requestType) {
+ PendingAssistExtras pae = enqueueAssistContext(requestType, null, null,
+ UserHandle.getCallingUserId());
+ if (pae == null) {
+ return null;
+ }
+ synchronized (pae) {
+ while (!pae.haveResult) {
+ try {
+ pae.wait();
+ } catch (InterruptedException e) {
+ }
+ }
+ if (pae.result != null) {
+ pae.extras.putBundle(Intent.EXTRA_ASSIST_CONTEXT, pae.result);
+ }
+ }
+ synchronized (this) {
+ mPendingAssistExtras.remove(pae);
+ mHandler.removeCallbacks(pae);
+ }
+ return pae.extras;
+ }
+
+ private PendingAssistExtras enqueueAssistContext(int requestType, Intent intent, String hint,
+ int userHandle) {
enforceCallingPermission(android.Manifest.permission.GET_TOP_ACTIVITY_INFO,
"getAssistContextExtras()");
PendingAssistExtras pae;
@@ -10462,13 +10496,13 @@
extras.putString(Intent.EXTRA_ASSIST_PACKAGE, activity.packageName);
if (activity.app == null || activity.app.thread == null) {
Slog.w(TAG, "getAssistContextExtras failed: no process for " + activity);
- return extras;
+ return null;
}
if (activity.app.pid == Binder.getCallingPid()) {
Slog.w(TAG, "getAssistContextExtras failed: request process same as " + activity);
- return extras;
+ return null;
}
- pae = new PendingAssistExtras(activity);
+ pae = new PendingAssistExtras(activity, extras, intent, hint, userHandle);
try {
activity.app.thread.requestAssistContextExtras(activity.appToken, pae,
requestType);
@@ -10476,25 +10510,10 @@
mHandler.postDelayed(pae, PENDING_ASSIST_EXTRAS_TIMEOUT);
} catch (RemoteException e) {
Slog.w(TAG, "getAssistContextExtras failed: crash calling " + activity);
- return extras;
+ return null;
}
+ return pae;
}
- synchronized (pae) {
- while (!pae.haveResult) {
- try {
- pae.wait();
- } catch (InterruptedException e) {
- }
- }
- if (pae.result != null) {
- extras.putBundle(Intent.EXTRA_ASSIST_CONTEXT, pae.result);
- }
- }
- synchronized (this) {
- mPendingAssistExtras.remove(pae);
- mHandler.removeCallbacks(pae);
- }
- return extras;
}
public void reportAssistContextExtras(IBinder token, Bundle extras) {
@@ -10503,7 +10522,38 @@
pae.result = extras;
pae.haveResult = true;
pae.notifyAll();
+ if (pae.intent == null) {
+ // Caller is just waiting for the result.
+ return;
+ }
}
+
+ // We are now ready to launch the assist activity.
+ synchronized (this) {
+ boolean exists = mPendingAssistExtras.remove(pae);
+ mHandler.removeCallbacks(pae);
+ if (!exists) {
+ // Timed out.
+ return;
+ }
+ }
+ pae.intent.replaceExtras(extras);
+ if (pae.hint != null) {
+ pae.intent.putExtra(pae.hint, true);
+ }
+ pae.intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK
+ | Intent.FLAG_ACTIVITY_SINGLE_TOP
+ | Intent.FLAG_ACTIVITY_CLEAR_TOP);
+ closeSystemDialogs("assist");
+ try {
+ mContext.startActivityAsUser(pae.intent, new UserHandle(pae.userHandle));
+ } catch (ActivityNotFoundException e) {
+ Slog.w(TAG, "No activity to handle assist action.", e);
+ }
+ }
+
+ public boolean launchAssistIntent(Intent intent, int requestType, String hint, int userHandle) {
+ return enqueueAssistContext(requestType, intent, hint, userHandle) != null;
}
public void registerProcessObserver(IProcessObserver observer) {
diff --git a/services/core/java/com/android/server/display/DisplayManagerService.java b/services/core/java/com/android/server/display/DisplayManagerService.java
index 97748e8..09dc477 100644
--- a/services/core/java/com/android/server/display/DisplayManagerService.java
+++ b/services/core/java/com/android/server/display/DisplayManagerService.java
@@ -651,7 +651,10 @@
mDisplayDevices.add(device);
addLogicalDisplayLocked(device);
- updateDisplayStateLocked(device);
+ Runnable work = updateDisplayStateLocked(device);
+ if (work != null) {
+ work.run();
+ }
scheduleTraversalLocked(false);
}
diff --git a/services/core/java/com/android/server/job/JobSchedulerService.java b/services/core/java/com/android/server/job/JobSchedulerService.java
index f456bcd..c6d2db2 100644
--- a/services/core/java/com/android/server/job/JobSchedulerService.java
+++ b/services/core/java/com/android/server/job/JobSchedulerService.java
@@ -70,8 +70,7 @@
*/
public class JobSchedulerService extends com.android.server.SystemService
implements StateChangedListener, JobCompletedListener {
- // TODO: Switch this off for final version.
- static final boolean DEBUG = true;
+ static final boolean DEBUG = false;
/** The number of concurrent jobs we run at one time. */
private static final int MAX_JOB_CONTEXTS_COUNT = 3;
static final String TAG = "JobSchedulerService";
diff --git a/services/core/java/com/android/server/job/JobServiceContext.java b/services/core/java/com/android/server/job/JobServiceContext.java
index 9df21a2..63c8d92 100644
--- a/services/core/java/com/android/server/job/JobServiceContext.java
+++ b/services/core/java/com/android/server/job/JobServiceContext.java
@@ -62,7 +62,7 @@
*
*/
public class JobServiceContext extends IJobCallback.Stub implements ServiceConnection {
- private static final boolean DEBUG = true;
+ private static final boolean DEBUG = false;
private static final String TAG = "JobServiceContext";
/** Define the maximum # of jobs allowed to run on a service at once. */
private static final int defaultMaxActiveJobsPerService =
diff --git a/services/core/java/com/android/server/job/controllers/StateController.java b/services/core/java/com/android/server/job/controllers/StateController.java
index 81658bf..ca56886 100644
--- a/services/core/java/com/android/server/job/controllers/StateController.java
+++ b/services/core/java/com/android/server/job/controllers/StateController.java
@@ -29,7 +29,7 @@
* are ready to run, or whether they must be stopped.
*/
public abstract class StateController {
- protected static final boolean DEBUG = true;
+ protected static final boolean DEBUG = false;
protected Context mContext;
protected StateChangedListener mStateChangedListener;
diff --git a/services/core/java/com/android/server/media/MediaSessionRecord.java b/services/core/java/com/android/server/media/MediaSessionRecord.java
index a0ec1d5..ebce3ad 100644
--- a/services/core/java/com/android/server/media/MediaSessionRecord.java
+++ b/services/core/java/com/android/server/media/MediaSessionRecord.java
@@ -625,12 +625,12 @@
private PlaybackState getStateWithUpdatedPosition() {
PlaybackState state;
+ long duration = -1;
synchronized (mLock) {
state = mPlaybackState;
- }
- long duration = -1;
- if (mMetadata != null && mMetadata.containsKey(MediaMetadata.METADATA_KEY_DURATION)) {
- duration = mMetadata.getLong(MediaMetadata.METADATA_KEY_DURATION);
+ if (mMetadata != null && mMetadata.containsKey(MediaMetadata.METADATA_KEY_DURATION)) {
+ duration = mMetadata.getLong(MediaMetadata.METADATA_KEY_DURATION);
+ }
}
PlaybackState result = null;
if (state != null) {
@@ -725,10 +725,14 @@
@Override
public void setMetadata(MediaMetadata metadata) {
- // Make a copy of the metadata as the underlying bundle may be
- // modified on this thread.
synchronized (mLock) {
- mMetadata = metadata == null ? null : new MediaMetadata.Builder(metadata).build();
+ MediaMetadata temp = metadata == null ? null : new MediaMetadata.Builder(metadata)
+ .build();
+ // This is to guarantee that the underlying bundle is unparceled
+ // before we set it to prevent concurrent reads from throwing an
+ // exception
+ temp.size();
+ mMetadata = temp;
}
mHandler.post(MessageHandler.MSG_UPDATE_METADATA);
}
diff --git a/services/core/java/com/android/server/search/SearchManagerService.java b/services/core/java/com/android/server/search/SearchManagerService.java
index 5deb2b8..ddf02e9 100644
--- a/services/core/java/com/android/server/search/SearchManagerService.java
+++ b/services/core/java/com/android/server/search/SearchManagerService.java
@@ -17,7 +17,9 @@
package com.android.server.search;
import android.app.ActivityManager;
+import android.app.ActivityManagerNative;
import android.app.AppGlobals;
+import android.app.IActivityManager;
import android.app.ISearchManager;
import android.app.SearchManager;
import android.app.SearchableInfo;
@@ -32,6 +34,7 @@
import android.content.pm.ResolveInfo;
import android.database.ContentObserver;
import android.os.Binder;
+import android.os.Bundle;
import android.os.Process;
import android.os.RemoteException;
import android.os.UserHandle;
@@ -262,6 +265,25 @@
}
@Override
+ public boolean launchAssistAction(int requestType, String hint, int userHandle) {
+ ComponentName comp = getAssistIntent(userHandle);
+ if (comp == null) {
+ return false;
+ }
+ long ident = Binder.clearCallingIdentity();
+ try {
+ Intent intent = new Intent(Intent.ACTION_ASSIST);
+ intent.setComponent(comp);
+ IActivityManager am = ActivityManagerNative.getDefault();
+ return am.launchAssistIntent(intent, requestType, hint, userHandle);
+ } catch (RemoteException e) {
+ } finally {
+ Binder.restoreCallingIdentity(ident);
+ }
+ return true;
+ }
+
+ @Override
public void dump(FileDescriptor fd, PrintWriter pw, String[] args) {
mContext.enforceCallingOrSelfPermission(android.Manifest.permission.DUMP, TAG);
diff --git a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
index a8245e7..8a36335 100644
--- a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
+++ b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java
@@ -116,7 +116,7 @@
public WallpaperObserver(WallpaperData wallpaper) {
super(getWallpaperDir(wallpaper.userId).getAbsolutePath(),
- CLOSE_WRITE | DELETE | DELETE_SELF);
+ CLOSE_WRITE | MOVED_TO | DELETE | DELETE_SELF);
mWallpaperDir = getWallpaperDir(wallpaper.userId);
mWallpaper = wallpaper;
mWallpaperFile = new File(mWallpaperDir, WALLPAPER);
@@ -137,9 +137,11 @@
File changedFile = new File(mWallpaperDir, path);
if (mWallpaperFile.equals(changedFile)) {
notifyCallbacksLocked(mWallpaper);
- if (mWallpaper.wallpaperComponent == null || event != CLOSE_WRITE
+ final boolean written = (event == CLOSE_WRITE || event == MOVED_TO);
+ if (mWallpaper.wallpaperComponent == null
+ || event != CLOSE_WRITE // includes the MOVED_TO case
|| mWallpaper.imageWallpaperPending) {
- if (event == CLOSE_WRITE) {
+ if (written) {
mWallpaper.imageWallpaperPending = false;
}
bindWallpaperComponentLocked(mImageWallpaper, true,
diff --git a/services/devicepolicy/java/com/android/server/devicepolicy/DevicePolicyManagerService.java b/services/devicepolicy/java/com/android/server/devicepolicy/DevicePolicyManagerService.java
index d1aba3c..f8f20dc 100644
--- a/services/devicepolicy/java/com/android/server/devicepolicy/DevicePolicyManagerService.java
+++ b/services/devicepolicy/java/com/android/server/devicepolicy/DevicePolicyManagerService.java
@@ -53,6 +53,7 @@
import android.net.ConnectivityManager;
import android.net.ProxyInfo;
import android.net.Uri;
+import android.os.AsyncTask;
import android.os.Binder;
import android.os.Bundle;
import android.os.Environment;
@@ -288,7 +289,7 @@
}
if (Intent.ACTION_BOOT_COMPLETED.equals(action)
|| KeyChain.ACTION_STORAGE_CHANGED.equals(action)) {
- manageMonitoringCertificateNotification(intent);
+ new MonitoringCertNotificationTask().execute(intent);
}
if (Intent.ACTION_USER_REMOVED.equals(action)) {
removeUserData(userHandle);
@@ -1610,60 +1611,91 @@
}
}
- private void manageMonitoringCertificateNotification(Intent intent) {
- final NotificationManager notificationManager = getNotificationManager();
+ private class MonitoringCertNotificationTask extends AsyncTask<Intent, Void, Void> {
+ @Override
+ protected Void doInBackground(Intent... params) {
+ int userHandle = params[0].getIntExtra(Intent.EXTRA_USER_HANDLE, UserHandle.USER_ALL);
- final boolean hasCert = !(new TrustedCertificateStore().userAliases().isEmpty());
- if (! hasCert) {
- if (intent.getAction().equals(KeyChain.ACTION_STORAGE_CHANGED)) {
- for (UserInfo user : mUserManager.getUsers()) {
- notificationManager.cancelAsUser(
- null, MONITORING_CERT_NOTIFICATION_ID, user.getUserHandle());
+ if (userHandle == UserHandle.USER_ALL) {
+ for (UserInfo userInfo : mUserManager.getUsers()) {
+ manageNotification(userInfo.getUserHandle());
}
+ } else {
+ manageNotification(new UserHandle(userHandle));
}
- return;
- }
- final boolean isManaged = getDeviceOwner() != null;
- int smallIconId;
- String contentText;
- if (isManaged) {
- contentText = mContext.getString(R.string.ssl_ca_cert_noti_managed,
- getDeviceOwnerName());
- smallIconId = R.drawable.stat_sys_certificate_info;
- } else {
- contentText = mContext.getString(R.string.ssl_ca_cert_noti_by_unknown);
- smallIconId = android.R.drawable.stat_sys_warning;
+ return null;
}
- Intent dialogIntent = new Intent(Settings.ACTION_MONITORING_CERT_INFO);
- dialogIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
- dialogIntent.setPackage("com.android.settings");
- // Notification will be sent individually to all users. The activity should start as
- // whichever user is current when it starts.
- PendingIntent notifyIntent = PendingIntent.getActivityAsUser(mContext, 0, dialogIntent,
- PendingIntent.FLAG_UPDATE_CURRENT, null, UserHandle.CURRENT);
-
- Notification noti = new Notification.Builder(mContext)
- .setSmallIcon(smallIconId)
- .setContentTitle(mContext.getString(R.string.ssl_ca_cert_warning))
- .setContentText(contentText)
- .setContentIntent(notifyIntent)
- .setPriority(Notification.PRIORITY_HIGH)
- .setShowWhen(false)
- .setColor(mContext.getResources().getColor(
- com.android.internal.R.color.system_notification_accent_color))
- .build();
-
- // If this is a boot intent, this will fire for each user. But if this is a storage changed
- // intent, it will fire once, so we need to notify all users.
- if (intent.getAction().equals(KeyChain.ACTION_STORAGE_CHANGED)) {
- for (UserInfo user : mUserManager.getUsers()) {
- notificationManager.notifyAsUser(
- null, MONITORING_CERT_NOTIFICATION_ID, noti, user.getUserHandle());
+ private void manageNotification(UserHandle userHandle) {
+ if (!mUserManager.isUserRunning(userHandle)) {
+ return;
}
- } else {
- notificationManager.notifyAsUser(
- null, MONITORING_CERT_NOTIFICATION_ID, noti, UserHandle.CURRENT);
+
+ boolean hasCert = false;
+ final long id = Binder.clearCallingIdentity();
+ try {
+ KeyChainConnection kcs = KeyChain.bindAsUser(mContext, userHandle);
+ try {
+ if (!kcs.getService().getUserCaAliases().getList().isEmpty()) {
+ hasCert = true;
+ }
+ } catch (RemoteException e) {
+ Log.e(LOG_TAG, "Could not connect to KeyChain service", e);
+ } finally {
+ kcs.close();
+ }
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ } catch (RuntimeException e) {
+ Log.e(LOG_TAG, "Could not connect to KeyChain service", e);
+ } finally {
+ Binder.restoreCallingIdentity(id);
+ }
+ if (!hasCert) {
+ getNotificationManager().cancelAsUser(
+ null, MONITORING_CERT_NOTIFICATION_ID, userHandle);
+ return;
+ }
+
+ int smallIconId;
+ String contentText;
+ final String ownerName = getDeviceOwnerName();
+ if (ownerName != null) {
+ contentText = mContext.getString(R.string.ssl_ca_cert_noti_managed, ownerName);
+ smallIconId = R.drawable.stat_sys_certificate_info;
+ } else {
+ contentText = mContext.getString(R.string.ssl_ca_cert_noti_by_unknown);
+ smallIconId = android.R.drawable.stat_sys_warning;
+ }
+
+ Intent dialogIntent = new Intent(Settings.ACTION_MONITORING_CERT_INFO);
+ dialogIntent.setFlags(
+ Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
+ dialogIntent.setPackage("com.android.settings");
+ PendingIntent notifyIntent = PendingIntent.getActivityAsUser(mContext, 0,
+ dialogIntent, PendingIntent.FLAG_UPDATE_CURRENT, null, userHandle);
+
+ final Context userContext;
+ try {
+ userContext = mContext.createPackageContextAsUser("android", 0, userHandle);
+ } catch (PackageManager.NameNotFoundException e) {
+ Log.e(LOG_TAG, "Create context as " + userHandle + " failed", e);
+ return;
+ }
+ final Notification noti = new Notification.Builder(userContext)
+ .setSmallIcon(smallIconId)
+ .setContentTitle(mContext.getString(R.string.ssl_ca_cert_warning))
+ .setContentText(contentText)
+ .setContentIntent(notifyIntent)
+ .setOngoing(true)
+ .setPriority(Notification.PRIORITY_HIGH)
+ .setShowWhen(false)
+ .setColor(mContext.getResources().getColor(
+ com.android.internal.R.color.system_notification_accent_color))
+ .build();
+
+ getNotificationManager().notifyAsUser(
+ null, MONITORING_CERT_NOTIFICATION_ID, noti, userHandle);
}
}
diff --git a/telecomm/java/android/telecom/RemoteConnectionService.java b/telecomm/java/android/telecom/RemoteConnectionService.java
index de1dc17..af4ee22 100644
--- a/telecomm/java/android/telecom/RemoteConnectionService.java
+++ b/telecomm/java/android/telecom/RemoteConnectionService.java
@@ -365,7 +365,7 @@
}
private boolean hasConnection(String callId) {
- return mConferenceById.containsKey(callId);
+ return mConnectionById.containsKey(callId);
}
private RemoteConnection findConnectionForAction(
diff --git a/telephony/java/android/telephony/ServiceState.java b/telephony/java/android/telephony/ServiceState.java
index 8e43772..52d0516 100644
--- a/telephony/java/android/telephony/ServiceState.java
+++ b/telephony/java/android/telephony/ServiceState.java
@@ -850,7 +850,8 @@
|| radioTechnology == RIL_RADIO_TECHNOLOGY_HSPA
|| radioTechnology == RIL_RADIO_TECHNOLOGY_LTE
|| radioTechnology == RIL_RADIO_TECHNOLOGY_HSPAP
- || radioTechnology == RIL_RADIO_TECHNOLOGY_GSM;
+ || radioTechnology == RIL_RADIO_TECHNOLOGY_GSM
+ || radioTechnology == RIL_RADIO_TECHNOLOGY_TD_SCDMA;
}
/** @hide */
@@ -861,7 +862,6 @@
|| radioTechnology == RIL_RADIO_TECHNOLOGY_EVDO_0
|| radioTechnology == RIL_RADIO_TECHNOLOGY_EVDO_A
|| radioTechnology == RIL_RADIO_TECHNOLOGY_EVDO_B
- || radioTechnology == RIL_RADIO_TECHNOLOGY_EHRPD
- || radioTechnology == RIL_RADIO_TECHNOLOGY_TD_SCDMA;
+ || radioTechnology == RIL_RADIO_TECHNOLOGY_EHRPD;
}
}
diff --git a/tests/VoiceEnrollment/AndroidManifest.xml b/tests/VoiceEnrollment/AndroidManifest.xml
index 6321222..46f6ff5 100644
--- a/tests/VoiceEnrollment/AndroidManifest.xml
+++ b/tests/VoiceEnrollment/AndroidManifest.xml
@@ -1,16 +1,20 @@
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.android.test.voiceenrollment">
+ <uses-permission android:name="android.permission.MANAGE_VOICE_KEYPHRASES" />
<application
android:permission="android.permission.MANAGE_VOICE_KEYPHRASES">
- <activity android:name="TestEnrollmentActivity" android:label="Voice Enrollment Application"
- android:theme="@android:style/Theme.Material.Light.Voice">
+ <activity
+ android:name="TestEnrollmentActivity"
+ android:label="Voice Enrollment Application"
+ android:theme="@android:style/Theme.Material.Light.Voice">
<intent-filter>
<action android:name="com.android.intent.action.MANAGE_VOICE_KEYPHRASES" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
- <meta-data android:name="android.voice_enrollment"
+ <meta-data
+ android:name="android.voice_enrollment"
android:resource="@xml/enrollment_application"/>
</application>
</manifest>
diff --git a/tests/VoiceEnrollment/res/layout/main.xml b/tests/VoiceEnrollment/res/layout/main.xml
new file mode 100644
index 0000000..9d2b9d9
--- /dev/null
+++ b/tests/VoiceEnrollment/res/layout/main.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2014 Google Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent"
+ >
+
+ <Button
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/enroll"
+ android:onClick="onEnrollButtonClicked"
+ android:padding="20dp" />
+
+ <Button
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/reenroll"
+ android:onClick="onReEnrollButtonClicked"
+ android:padding="20dp" />
+
+ <Button
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/unenroll"
+ android:onClick="onUnEnrollButtonClicked"
+ android:padding="20dp" />
+</LinearLayout>
\ No newline at end of file
diff --git a/tests/VoiceEnrollment/res/values/strings.xml b/tests/VoiceEnrollment/res/values/strings.xml
new file mode 100644
index 0000000..07bac2a
--- /dev/null
+++ b/tests/VoiceEnrollment/res/values/strings.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2014 Google Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
+
+ <string name="enroll">Enroll</string>
+ <string name="reenroll">Re-enroll</string>
+ <string name="unenroll">Un-enroll</string>
+</resources>
\ No newline at end of file
diff --git a/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/EnrollmentUtil.java b/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/EnrollmentUtil.java
new file mode 100644
index 0000000..9e544a5
--- /dev/null
+++ b/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/EnrollmentUtil.java
@@ -0,0 +1,198 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.test.voiceenrollment;
+
+import android.annotation.Nullable;
+import android.content.Context;
+import android.hardware.soundtrigger.KeyphraseEnrollmentInfo;
+import android.hardware.soundtrigger.SoundTrigger;
+import android.hardware.soundtrigger.SoundTrigger.Keyphrase;
+import android.hardware.soundtrigger.SoundTrigger.KeyphraseSoundModel;
+import android.os.RemoteException;
+import android.os.ServiceManager;
+import android.service.voice.AlwaysOnHotwordDetector;
+import android.util.Log;
+
+import com.android.internal.app.IVoiceInteractionManagerService;
+
+/**
+ * Utility class for the enrollment operations like enroll;re-enroll & un-enroll.
+ */
+public class EnrollmentUtil {
+ private static final String TAG = "TestEnrollmentUtil";
+
+ /**
+ * Activity Action: Show activity for managing the keyphrases for hotword detection.
+ * This needs to be defined by an activity that supports enrolling users for hotword/keyphrase
+ * detection.
+ */
+ public static final String ACTION_MANAGE_VOICE_KEYPHRASES =
+ KeyphraseEnrollmentInfo.ACTION_MANAGE_VOICE_KEYPHRASES;
+
+ /**
+ * Intent extra: The intent extra for the specific manage action that needs to be performed.
+ * Possible values are {@link AlwaysOnHotwordDetector#MANAGE_ACTION_ENROLL},
+ * {@link AlwaysOnHotwordDetector#MANAGE_ACTION_RE_ENROLL}
+ * or {@link AlwaysOnHotwordDetector#MANAGE_ACTION_UN_ENROLL}.
+ */
+ public static final String EXTRA_VOICE_KEYPHRASE_ACTION =
+ KeyphraseEnrollmentInfo.EXTRA_VOICE_KEYPHRASE_ACTION;
+
+ /**
+ * Intent extra: The hint text to be shown on the voice keyphrase management UI.
+ */
+ public static final String EXTRA_VOICE_KEYPHRASE_HINT_TEXT =
+ KeyphraseEnrollmentInfo.EXTRA_VOICE_KEYPHRASE_HINT_TEXT;
+ /**
+ * Intent extra: The voice locale to use while managing the keyphrase.
+ */
+ public static final String EXTRA_VOICE_KEYPHRASE_LOCALE =
+ KeyphraseEnrollmentInfo.EXTRA_VOICE_KEYPHRASE_LOCALE;
+
+ /** Simple recognition of the key phrase */
+ public static final int RECOGNITION_MODE_VOICE_TRIGGER =
+ SoundTrigger.RECOGNITION_MODE_VOICE_TRIGGER;
+ /** Trigger only if one user is identified */
+ public static final int RECOGNITION_MODE_USER_IDENTIFICATION =
+ SoundTrigger.RECOGNITION_MODE_USER_IDENTIFICATION;
+
+ private final IVoiceInteractionManagerService mModelManagementService;
+
+ public EnrollmentUtil() {
+ mModelManagementService = IVoiceInteractionManagerService.Stub.asInterface(
+ ServiceManager.getService(Context.VOICE_INTERACTION_MANAGER_SERVICE));
+ }
+
+ /**
+ * Adds/Updates a sound model.
+ * The sound model must contain a valid UUID,
+ * exactly 1 keyphrase,
+ * and users for which the keyphrase is valid - typically the current user.
+ *
+ * @param soundModel The sound model to add/update.
+ * @return {@code true} if the call succeeds, {@code false} otherwise.
+ */
+ public boolean addOrUpdateSoundModel(KeyphraseSoundModel soundModel) {
+ if (!verifyKeyphraseSoundModel(soundModel)) {
+ return false;
+ }
+
+ int status = SoundTrigger.STATUS_ERROR;
+ try {
+ status = mModelManagementService.updateKeyphraseSoundModel(soundModel);
+ } catch (RemoteException e) {
+ Log.e(TAG, "RemoteException in updateKeyphraseSoundModel", e);
+ }
+ return status == SoundTrigger.STATUS_OK;
+ }
+
+ /**
+ * Gets the sound model for the given keyphrase, null if none exists.
+ * This should be used for re-enrollment purposes.
+ * If a sound model for a given keyphrase exists, and it needs to be updated,
+ * it should be obtained using this method, updated and then passed in to
+ * {@link #addOrUpdateSoundModel(KeyphraseSoundModel)} without changing the IDs.
+ *
+ * @param keyphraseId The keyphrase ID to look-up the sound model for.
+ * @param bcp47Locale The locale for with to look up the sound model for.
+ * @return The sound model if one was found, null otherwise.
+ */
+ @Nullable
+ public KeyphraseSoundModel getSoundModel(int keyphraseId, String bcp47Locale) {
+ if (keyphraseId <= 0) {
+ Log.e(TAG, "Keyphrase must have a valid ID");
+ return null;
+ }
+
+ KeyphraseSoundModel model = null;
+ try {
+ model = mModelManagementService.getKeyphraseSoundModel(keyphraseId, bcp47Locale);
+ } catch (RemoteException e) {
+ Log.e(TAG, "RemoteException in updateKeyphraseSoundModel");
+ }
+
+ if (model == null) {
+ Log.w(TAG, "No models present for the gien keyphrase ID");
+ return null;
+ } else {
+ return model;
+ }
+ }
+
+ /**
+ * Deletes the sound model for the given keyphrase id.
+ *
+ * @param keyphraseId The keyphrase ID to look-up the sound model for.
+ * @return {@code true} if the call succeeds, {@code false} otherwise.
+ */
+ @Nullable
+ public boolean deleteSoundModel(int keyphraseId, String bcp47Locale) {
+ if (keyphraseId <= 0) {
+ Log.e(TAG, "Keyphrase must have a valid ID");
+ return false;
+ }
+
+ int status = SoundTrigger.STATUS_ERROR;
+ try {
+ status = mModelManagementService.deleteKeyphraseSoundModel(keyphraseId, bcp47Locale);
+ } catch (RemoteException e) {
+ Log.e(TAG, "RemoteException in updateKeyphraseSoundModel");
+ }
+ return status == SoundTrigger.STATUS_OK;
+ }
+
+ private boolean verifyKeyphraseSoundModel(KeyphraseSoundModel soundModel) {
+ if (soundModel == null) {
+ Log.e(TAG, "KeyphraseSoundModel must be non-null");
+ return false;
+ }
+ if (soundModel.uuid == null) {
+ Log.e(TAG, "KeyphraseSoundModel must have a UUID");
+ return false;
+ }
+ if (soundModel.data == null) {
+ Log.e(TAG, "KeyphraseSoundModel must have data");
+ return false;
+ }
+ if (soundModel.keyphrases == null || soundModel.keyphrases.length != 1) {
+ Log.e(TAG, "Keyphrase must be exactly 1");
+ return false;
+ }
+ Keyphrase keyphrase = soundModel.keyphrases[0];
+ if (keyphrase.id <= 0) {
+ Log.e(TAG, "Keyphrase must have a valid ID");
+ return false;
+ }
+ if (keyphrase.recognitionModes < 0) {
+ Log.e(TAG, "Recognition modes must be valid");
+ return false;
+ }
+ if (keyphrase.locale == null) {
+ Log.e(TAG, "Locale must not be null");
+ return false;
+ }
+ if (keyphrase.text == null) {
+ Log.e(TAG, "Text must not be null");
+ return false;
+ }
+ if (keyphrase.users == null || keyphrase.users.length == 0) {
+ Log.e(TAG, "Keyphrase must have valid user(s)");
+ return false;
+ }
+ return true;
+ }
+}
diff --git a/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/TestEnrollmentActivity.java b/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/TestEnrollmentActivity.java
index 7fbd965..2494db7 100644
--- a/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/TestEnrollmentActivity.java
+++ b/tests/VoiceEnrollment/src/com/android/test/voiceenrollment/TestEnrollmentActivity.java
@@ -16,8 +16,106 @@
package com.android.test.voiceenrollment;
+import java.util.Random;
+import java.util.UUID;
+
import android.app.Activity;
+import android.hardware.soundtrigger.SoundTrigger;
+import android.hardware.soundtrigger.SoundTrigger.Keyphrase;
+import android.hardware.soundtrigger.SoundTrigger.KeyphraseSoundModel;
+import android.os.Bundle;
+import android.os.UserManager;
+import android.util.Log;
+import android.view.View;
+import android.widget.Toast;
public class TestEnrollmentActivity extends Activity {
- // TODO(sansid): Add a test enrollment flow here.
+ private static final String TAG = "TestEnrollmentActivity";
+ private static final boolean DBG = true;
+
+ /** Keyphrase related constants, must match those defined in enrollment_application.xml */
+ private static final int KEYPHRASE_ID = 101;
+ private static final int RECOGNITION_MODES = SoundTrigger.RECOGNITION_MODE_VOICE_TRIGGER;
+ private static final String BCP47_LOCALE = "fr-FR";
+ private static final String TEXT = "Hello There";
+
+ private EnrollmentUtil mEnrollmentUtil;
+ private Random mRandom;
+
+ @Override
+ protected void onCreate(Bundle savedInstanceState) {
+ if (DBG) Log.d(TAG, "onCreate");
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+ mEnrollmentUtil = new EnrollmentUtil();
+ mRandom = new Random();
+ }
+
+ /**
+ * Called when the user clicks the enroll button.
+ * Performs a fresh enrollment.
+ */
+ public void onEnrollButtonClicked(View v) {
+ Keyphrase kp = new Keyphrase(KEYPHRASE_ID, RECOGNITION_MODES, BCP47_LOCALE, TEXT,
+ new int[] { UserManager.get(this).getUserHandle() /* current user */});
+ UUID modelUuid = UUID.randomUUID();
+ // Generate a fake model to push.
+ byte[] data = new byte[1024];
+ mRandom.nextBytes(data);
+ KeyphraseSoundModel soundModel = new KeyphraseSoundModel(modelUuid, null, data,
+ new Keyphrase[] { kp });
+ boolean status = mEnrollmentUtil.addOrUpdateSoundModel(soundModel);
+ if (status) {
+ Toast.makeText(
+ this, "Successfully enrolled, model UUID=" + modelUuid, Toast.LENGTH_SHORT)
+ .show();
+ } else {
+ Toast.makeText(this, "Failed to enroll!!!" + modelUuid, Toast.LENGTH_SHORT).show();
+ }
+ }
+
+ /**
+ * Called when the user clicks the un-enroll button.
+ * Clears the enrollment information for the user.
+ */
+ public void onUnEnrollButtonClicked(View v) {
+ KeyphraseSoundModel soundModel = mEnrollmentUtil.getSoundModel(KEYPHRASE_ID, BCP47_LOCALE);
+ if (soundModel == null) {
+ Toast.makeText(this, "Sound model not found!!!", Toast.LENGTH_SHORT).show();
+ return;
+ }
+ boolean status = mEnrollmentUtil.deleteSoundModel(KEYPHRASE_ID, BCP47_LOCALE);
+ if (status) {
+ Toast.makeText(this, "Successfully un-enrolled, model UUID=" + soundModel.uuid,
+ Toast.LENGTH_SHORT)
+ .show();
+ } else {
+ Toast.makeText(this, "Failed to un-enroll!!!", Toast.LENGTH_SHORT).show();
+ }
+ }
+
+ /**
+ * Called when the user clicks the re-enroll button.
+ * Uses the previously enrolled sound model and makes changes to it before pushing it back.
+ */
+ public void onReEnrollButtonClicked(View v) {
+ KeyphraseSoundModel soundModel = mEnrollmentUtil.getSoundModel(KEYPHRASE_ID, BCP47_LOCALE);
+ if (soundModel == null) {
+ Toast.makeText(this, "Sound model not found!!!", Toast.LENGTH_SHORT).show();
+ return;
+ }
+ // Generate a fake model to push.
+ byte[] data = new byte[2048];
+ mRandom.nextBytes(data);
+ KeyphraseSoundModel updated = new KeyphraseSoundModel(soundModel.uuid,
+ soundModel.vendorUuid, data, soundModel.keyphrases);
+ boolean status = mEnrollmentUtil.addOrUpdateSoundModel(updated);
+ if (status) {
+ Toast.makeText(this, "Successfully re-enrolled, model UUID=" + updated.uuid,
+ Toast.LENGTH_SHORT)
+ .show();
+ } else {
+ Toast.makeText(this, "Failed to re-enroll!!!", Toast.LENGTH_SHORT).show();
+ }
+ }
}