diff options
Diffstat (limited to 'core/java')
21 files changed, 911 insertions, 463 deletions
diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java index 946555f..f6883e2 100644 --- a/core/java/android/app/Activity.java +++ b/core/java/android/app/Activity.java @@ -5616,6 +5616,34 @@ public class Activity extends ContextThemeWrapper mExitTransitionListener = listener; } + /** + * Postpone the entering activity transition when Activity was started with + * {@link android.app.ActivityOptions#makeSceneTransitionAnimation(Activity, + * android.util.Pair[])}. + * <p>This method gives the Activity the ability to delay starting the entering and + * shared element transitions until all data is loaded. Until then, the Activity won't + * draw into its window, leaving the window transparent. This may also cause the + * returning animation to be delayed until data is ready. This method should be + * called in {@link #onCreate(android.os.Bundle)} or in + * {@link #onActivityReenter(int, android.content.Intent)}. + * {@link #startPostponedEnterTransition()} must be called to allow the Activity to + * start the transitions. If the Activity did not use + * {@link android.app.ActivityOptions#makeSceneTransitionAnimation(Activity, + * android.util.Pair[])}, then this method does nothing.</p> + */ + public void postponeEnterTransition() { + mActivityTransitionState.postponeEnterTransition(); + } + + /** + * Begin postponed transitions after {@link #postponeEnterTransition()} was called. + * If postponeEnterTransition() was called, you must call startPostponedEnterTransition() + * to have your Activity start drawing. + */ + public void startPostponedEnterTransition() { + mActivityTransitionState.startPostponedEnterTransition(); + } + // ------------------ Internal API ------------------ final void setParent(Activity parent) { diff --git a/core/java/android/app/ActivityTransitionCoordinator.java b/core/java/android/app/ActivityTransitionCoordinator.java index b658597..703df51 100644 --- a/core/java/android/app/ActivityTransitionCoordinator.java +++ b/core/java/android/app/ActivityTransitionCoordinator.java @@ -214,11 +214,21 @@ abstract class ActivityTransitionCoordinator extends ResultReceiver { ArrayList<String> allSharedElementNames, ArrayList<String> accepted, ArrayList<String> localNames, SharedElementListener listener, boolean isReturning) { + this(window, allSharedElementNames, listener, isReturning); + viewsReady(accepted, localNames); + } + + public ActivityTransitionCoordinator(Window window, + ArrayList<String> allSharedElementNames, + SharedElementListener listener, boolean isReturning) { super(new Handler()); mWindow = window; mListener = listener; mAllSharedElementNames = allSharedElementNames; mIsReturning = isReturning; + } + + protected void viewsReady(ArrayList<String> accepted, ArrayList<String> localNames) { setSharedElements(accepted, localNames); if (getViewsTransition() != null) { getDecor().captureTransitioningViews(mTransitioningViews); @@ -274,6 +284,8 @@ abstract class ActivityTransitionCoordinator extends ResultReceiver { return names; } + public ArrayList<String> getAllSharedElementNames() { return mAllSharedElementNames; } + public static void setViewVisibility(Collection<View> views, int visibility) { if (views != null) { for (View view : views) { diff --git a/core/java/android/app/ActivityTransitionState.java b/core/java/android/app/ActivityTransitionState.java index b32e9ad..d94dadd 100644 --- a/core/java/android/app/ActivityTransitionState.java +++ b/core/java/android/app/ActivityTransitionState.java @@ -87,6 +87,11 @@ class ActivityTransitionState { */ private boolean mHasExited; + /** + * Postpone painting and starting the enter transition until this is false. + */ + private boolean mIsEnterPostponed; + public ActivityTransitionState() { } @@ -140,15 +145,38 @@ class ActivityTransitionState { if (mEnterActivityOptions.isReturning()) { restoreExitedViews(); activity.getWindow().getDecorView().setVisibility(View.VISIBLE); - mEnterTransitionCoordinator = new EnterTransitionCoordinator(activity, - resultReceiver, sharedElementNames, mExitingFrom, mExitingTo); + } + mEnterTransitionCoordinator = new EnterTransitionCoordinator(activity, + resultReceiver, sharedElementNames, mEnterActivityOptions.isReturning()); + + if (!mIsEnterPostponed) { + startEnter(); + } + } + + public void postponeEnterTransition() { + mIsEnterPostponed = true; + } + + public void startPostponedEnterTransition() { + if (mIsEnterPostponed) { + mIsEnterPostponed = false; + if (mEnterTransitionCoordinator != null) { + startEnter(); + } + } + } + + private void startEnter() { + if (mEnterActivityOptions.isReturning()) { + mEnterTransitionCoordinator.viewsReady(mExitingFrom, mExitingTo); } else { - mEnterTransitionCoordinator = new EnterTransitionCoordinator(activity, - resultReceiver, sharedElementNames, null, null); - mEnteringNames = sharedElementNames; + mEnterTransitionCoordinator.viewsReady(null, null); + mEnteringNames = mEnterTransitionCoordinator.getAllSharedElementNames(); mEnteringFrom = mEnterTransitionCoordinator.getAcceptedNames(); mEnteringTo = mEnterTransitionCoordinator.getMappedNames(); } + mExitingFrom = null; mExitingTo = null; mEnterActivityOptions = null; diff --git a/core/java/android/app/EnterTransitionCoordinator.java b/core/java/android/app/EnterTransitionCoordinator.java index 4b052e7..779e3de 100644 --- a/core/java/android/app/EnterTransitionCoordinator.java +++ b/core/java/android/app/EnterTransitionCoordinator.java @@ -53,18 +53,37 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { private boolean mIsCanceled; private ObjectAnimator mBackgroundAnimator; private boolean mIsExitTransitionComplete; + private boolean mIsReadyForTransition; + private Bundle mSharedElementsBundle; public EnterTransitionCoordinator(Activity activity, ResultReceiver resultReceiver, - ArrayList<String> sharedElementNames, - ArrayList<String> acceptedNames, ArrayList<String> mappedNames) { - super(activity.getWindow(), sharedElementNames, acceptedNames, mappedNames, - getListener(activity, acceptedNames), acceptedNames != null); + ArrayList<String> sharedElementNames, boolean isReturning) { + super(activity.getWindow(), sharedElementNames, + getListener(activity, isReturning), isReturning); mActivity = activity; setResultReceiver(resultReceiver); prepareEnter(); Bundle resultReceiverBundle = new Bundle(); resultReceiverBundle.putParcelable(KEY_REMOTE_RECEIVER, this); mResultReceiver.send(MSG_SET_REMOTE_RECEIVER, resultReceiverBundle); + getDecor().getViewTreeObserver().addOnPreDrawListener(new ViewTreeObserver.OnPreDrawListener() { + @Override + public boolean onPreDraw() { + if (mIsReadyForTransition) { + getDecor().getViewTreeObserver().removeOnPreDrawListener(this); + } + return mIsReadyForTransition; + } + }); + } + + public void viewsReady(ArrayList<String> accepted, ArrayList<String> localNames) { + if (mIsReadyForTransition) { + return; + } + super.viewsReady(accepted, localNames); + + mIsReadyForTransition = true; if (mIsReturning) { mHandler = new Handler() { @Override @@ -75,6 +94,13 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { mHandler.sendEmptyMessageDelayed(MSG_CANCEL, MAX_WAIT_MS); send(MSG_SEND_SHARED_ELEMENT_DESTINATION, null); } + setViewVisibility(mSharedElements, View.INVISIBLE); + if (getViewsTransition() != null) { + setViewVisibility(mTransitioningViews, View.INVISIBLE); + } + if (mSharedElementsBundle != null) { + onTakeSharedElements(); + } } private void sendSharedElementDestination() { @@ -94,9 +120,7 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { } } - private static SharedElementListener getListener(Activity activity, - ArrayList<String> acceptedNames) { - boolean isReturning = acceptedNames != null; + private static SharedElementListener getListener(Activity activity, boolean isReturning) { return isReturning ? activity.mExitTransitionListener : activity.mEnterTransitionListener; } @@ -108,7 +132,8 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { if (mHandler != null) { mHandler.removeMessages(MSG_CANCEL); } - onTakeSharedElements(resultData); + mSharedElementsBundle = resultData; + onTakeSharedElements(); } break; case MSG_EXIT_TRANSITION_COMPLETE: @@ -139,7 +164,7 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { mSharedElementNames.clear(); mSharedElements.clear(); mAllSharedElementNames.clear(); - onTakeSharedElements(null); + startSharedElementTransition(null); onRemoteExitTransitionComplete(); } } @@ -149,10 +174,6 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { } protected void prepareEnter() { - setViewVisibility(mSharedElements, View.INVISIBLE); - if (getViewsTransition() != null) { - setViewVisibility(mTransitioningViews, View.INVISIBLE); - } mActivity.overridePendingTransition(0, 0); if (!mIsReturning) { mActivity.convertToTranslucent(null, null); @@ -185,7 +206,25 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { } } - protected void onTakeSharedElements(Bundle sharedElementState) { + protected void onTakeSharedElements() { + if (!mIsReadyForTransition || mSharedElementsBundle == null) { + return; + } + final Bundle sharedElementState = mSharedElementsBundle; + mSharedElementsBundle = null; + getDecor().getViewTreeObserver() + .addOnPreDrawListener(new ViewTreeObserver.OnPreDrawListener() { + @Override + public boolean onPreDraw() { + getDecor().getViewTreeObserver().removeOnPreDrawListener(this); + startSharedElementTransition(sharedElementState); + return false; + } + }); + getDecor().invalidate(); + } + + private void startSharedElementTransition(Bundle sharedElementState) { setEpicenter(); // Remove rejected shared elements ArrayList<String> rejectedNames = new ArrayList<String>(mAllSharedElementNames); @@ -299,8 +338,8 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { } public void stop() { + makeOpaque(); mHasStopped = true; - mActivity = null; mIsCanceled = true; mResultReceiver = null; if (mBackgroundAnimator != null) { @@ -310,7 +349,7 @@ class EnterTransitionCoordinator extends ActivityTransitionCoordinator { } private void makeOpaque() { - if (!mHasStopped) { + if (!mHasStopped && mActivity != null) { mActivity.convertFromTranslucent(); mActivity = null; } diff --git a/core/java/android/app/VoiceInteractor.java b/core/java/android/app/VoiceInteractor.java index 85e970c..0d94721 100644 --- a/core/java/android/app/VoiceInteractor.java +++ b/core/java/android/app/VoiceInteractor.java @@ -293,7 +293,7 @@ public class VoiceInteractor { IVoiceInteractorRequest submit(IVoiceInteractor interactor, String packageName, IVoiceInteractorCallback callback) throws RemoteException { - return interactor.startConfirmation(packageName, callback, mCommand, mArgs); + return interactor.startCommand(packageName, callback, mCommand, mArgs); } } diff --git a/core/java/android/app/admin/DeviceAdminReceiver.java b/core/java/android/app/admin/DeviceAdminReceiver.java index ee222a9..1015514 100644 --- a/core/java/android/app/admin/DeviceAdminReceiver.java +++ b/core/java/android/app/admin/DeviceAdminReceiver.java @@ -16,6 +16,7 @@ package android.app.admin; +import android.accounts.AccountManager; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; import android.app.Service; @@ -165,12 +166,14 @@ public class DeviceAdminReceiver extends BroadcastReceiver { = "android.app.action.ACTION_PASSWORD_EXPIRING"; /** - * Broadcast Action: This broadcast is sent to the newly created profile when - * the provisioning of a managed profile has completed successfully. It is used in both the - * Profile Owner and the Device Owner provisioning. + * Broadcast Action: This broadcast is sent to indicate that provisioning of a managed profile + * or managed device has completed successfully. * - * <p>The broadcast is limited to the DeviceAdminReceiver component specified in the message - * that started the provisioning. It is also limited to the managed profile. + * <p>The broadcast is limited to the profile that will be managed by the application that + * requested provisioning. In the device owner case the profile is the primary user. + * The broadcast will also be limited to the {@link DeviceAdminReceiver} component + * specified in the original intent or NFC bump that started the provisioning process + * (@see DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE). * * <p>Input: Nothing.</p> * <p>Output: Nothing</p> @@ -307,18 +310,23 @@ public class DeviceAdminReceiver extends BroadcastReceiver { } /** - * Called on the new profile when managed profile provisioning has completed. - * Managed profile provisioning is the process of setting up the device so that it has a - * separate profile which is managed by the mobile device management(mdm) application that - * triggered the provisioning. + * Called when provisioning of a managed profile or managed device has completed successfully. * - * <p>As part of provisioning a new profile is created, the mdm is moved to the new profile and - * set as the owner of the profile so that it has full control over it. - * This intent is only received by the mdm package that is set as profile owner during - * provisioning. + * <p> As a prerequisit for the execution of this callback the (@link DeviceAdminReceiver} has + * to declare an intent filter for {@link #ACTION_PROFILE_PROVISIONING_COMPLETE}. + * Its component must also be specified in the {@link DevicePolicyManager#EXTRA_DEVICE_ADMIN} + * of the {@link DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE} intent that started the + * managed provisioning. * - * <p>Provisioning can be triggered via an intent with the action - * android.managedprovisioning.ACTION_PROVISION_MANAGED_PROFILE. + * <p>When provisioning is complete, the managed profile is hidden until the profile owner + * calls {DevicePolicyManager#setProfileEnabled(ComponentName admin)}. Typically a profile + * owner will enable the profile when it has finished any additional setup such as adding an + * account by using the {@link AccountManager} and calling apis to bring the profile into the + * desired state. + * + * <p> Note that provisioning completes without waiting for any server interactions, so the + * profile owner needs to wait for data to be available if required (e.g android device ids or + * other data that is set as a result of server interactions). * * @param context The running context as per {@link #onReceive}. * @param intent The received intent as per {@link #onReceive}. diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java index d725873..157b8ec 100644 --- a/core/java/android/app/admin/DevicePolicyManager.java +++ b/core/java/android/app/admin/DevicePolicyManager.java @@ -82,17 +82,25 @@ public class DevicePolicyManager { /** * Activity action: Starts the provisioning flow which sets up a managed profile. - * This intent will typically be sent by a mobile device management application(mdm). - * Managed profile provisioning creates a profile, moves the mdm to the profile, - * sets the mdm as the profile owner and removes all non required applications from the profile. - * As a profile owner the mdm than has full control over the managed profile. * - * <p>The intent must contain the extras {@link #EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME} and - * {@link #EXTRA_PROVISIONING_DEFAULT_MANAGED_PROFILE_NAME}. + * <p>A managed profile allows data separation for example for the usage of a + * device as a personal and corporate device. The user which provisioning is started from and + * the managed profile share a launcher. + * + * <p>This intent will typically be sent by a mobile device management application (mdm). + * Provisioning adds a managed profile and sets the mdm as the profile owner who has full + * control over the profile + * + * <p>This intent must contain the extras {@link #EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME} + * {@link #EXTRA_PROVISIONING_DEFAULT_MANAGED_PROFILE_NAME} and {@link #EXTRA_DEVICE_ADMIN}. * * <p> When managed provisioning has completed, an intent of the type * {@link DeviceAdminReceiver#ACTION_PROFILE_PROVISIONING_COMPLETE} is broadcasted to the - * mdm app on the managed profile. + * managed profile. The intent is sent to the {@link DeviceAdminReceiver} specified in the + * {@link #EXTRA_DEVICE_ADMIN} exclusively. + * + * If provisioning fails, the managedProfile is removed so the device returns to its previous + * state. * * <p>Input: Nothing.</p> * <p>Output: Nothing</p> @@ -107,7 +115,7 @@ public class DevicePolicyManager { * <p>Use with {@link #ACTION_PROVISION_MANAGED_PROFILE}. */ public static final String EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME - = "deviceAdminPackageName"; + = "android.app.extra.deviceAdminPackageName"; /** * A String extra holding the default name of the profile that is created during managed profile @@ -115,7 +123,7 @@ public class DevicePolicyManager { * <p>Use with {@link #ACTION_PROVISION_MANAGED_PROFILE} */ public static final String EXTRA_PROVISIONING_DEFAULT_MANAGED_PROFILE_NAME - = "defaultManagedProfileName"; + = "android.app.extra.defaultManagedProfileName"; /** * Activity action: ask the user to add a new device administrator to the system. @@ -837,6 +845,9 @@ public class DevicePolicyManager { * {@link DeviceAdminInfo#USES_POLICY_EXPIRE_PASSWORD} to be able to call this * method; if it has not, a security exception will be thrown. * + * <p> Note that setting the password will automatically reset the expiration time for all + * active admins. Active admins do not need to explicitly call this method in that case. + * * @param admin Which {@link DeviceAdminReceiver} this request is associated with. * @param timeout The limit (in ms) that a password can remain in effect. A value of 0 * means there is no restriction (unlimited). diff --git a/core/java/android/app/maintenance/package.html b/core/java/android/app/maintenance/package.html new file mode 100644 index 0000000..1c9bf9d --- /dev/null +++ b/core/java/android/app/maintenance/package.html @@ -0,0 +1,5 @@ +<html> +<body> + {@hide} +</body> +</html> diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index ff56720..9eea545 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -30,7 +30,7 @@ import java.util.List; * * <p>These properties are fixed for a given CameraDevice, and can be queried * through the {@link CameraManager CameraManager} - * interface in addition to through the CameraDevice interface.</p> + * interface with {@link CameraManager#getCameraCharacteristics}.</p> * * <p>{@link CameraCharacteristics} objects are immutable.</p> * @@ -555,7 +555,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 should + * <p>If OIS is not implemented for a given camera device, this will * contain only OFF.</p> * * @see CaptureRequest#LENS_OPTICAL_STABILIZATION_MODE @@ -612,7 +612,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <p>Direction the camera faces relative to - * device screen</p> + * device screen.</p> * @see #LENS_FACING_FRONT * @see #LENS_FACING_BACK */ @@ -622,7 +622,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <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 laways support OFF and FAST.</p> + * <p>Full-capability camera devices must always support OFF and FAST.</p> * * @see CaptureRequest#NOISE_REDUCTION_MODE */ @@ -778,18 +778,20 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<Byte>("android.request.pipelineMaxDepth", byte.class); /** - * <p>Optional. Defaults to 1. Defines how many sub-components + * <p>Defines how many sub-components * a result will be composed of.</p> * <p>In order to combat the pipeline latency, partial results * may be delivered to the application layer from the camera device as * soon as they are available.</p> - * <p>A value of 1 means that partial results are not supported.</p> + * <p>Optional; defaults to 1. A value of 1 means that partial + * results are not supported, and only the final TotalCaptureResult will + * be produced by the camera device.</p> * <p>A typical use case for this might be: after requesting an * auto-focus (AF) lock the new AF state might be available 50% * of the way through the pipeline. The camera device could * then immediately dispatch this state via a partial result to - * the framework/application layer, and the rest of the - * metadata via later partial results.</p> + * the application, and the rest of the metadata via later + * partial results.</p> */ public static final Key<Integer> REQUEST_PARTIAL_RESULT_COUNT = new Key<Integer>("android.request.partialResultCount", int.class); @@ -806,8 +808,6 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * to do this query each of android.request.availableRequestKeys, * android.request.availableResultKeys, * android.request.availableCharacteristicsKeys.</p> - * <p>XX: Maybe these should go into {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} - * as a table instead?</p> * <p>The following capabilities are guaranteed to be available on * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} <code>==</code> FULL devices:</p> * <ul> @@ -815,14 +815,11 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <li>MANUAL_POST_PROCESSING</li> * </ul> * <p>Other capabilities may be available on either FULL or LIMITED - * devices, but the app. should query this field to be sure.</p> + * devices, but the application should query this field to be sure.</p> * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL - * @see #REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE - * @see #REQUEST_AVAILABLE_CAPABILITIES_OPTIONAL * @see #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR * @see #REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING - * @see #REQUEST_AVAILABLE_CAPABILITIES_ZSL * @see #REQUEST_AVAILABLE_CAPABILITIES_DNG */ public static final Key<int[]> REQUEST_AVAILABLE_CAPABILITIES = @@ -838,7 +835,6 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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>TODO: This should be used by #getAvailableCaptureRequestKeys.</p> * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @hide @@ -863,7 +859,6 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * 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>TODO: This should be used by #getAvailableCaptureResultKeys.</p> * * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE @@ -879,7 +874,6 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * android.request.availableResultKeys (except that it applies for * CameraCharacteristics instead of CaptureResult). See above for more * details.</p> - * <p>TODO: This should be used by CameraCharacteristics#getKeys.</p> * @hide */ public static final Key<int[]> REQUEST_AVAILABLE_CHARACTERISTICS_KEYS = @@ -927,10 +921,15 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<android.util.Size[]>("android.scaler.availableJpegSizes", android.util.Size[].class); /** - * <p>The maximum ratio between active area width - * and crop region width, or between active area height and - * crop region height, if the crop region height is larger - * than width</p> + * <p>The maximum ratio between both active area width + * and crop region width, and active area height and + * crop region height.</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> */ public static final Key<Float> SCALER_AVAILABLE_MAX_DIGITAL_ZOOM = new Key<Float>("android.scaler.availableMaxDigitalZoom", float.class); @@ -1339,9 +1338,9 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<android.util.Range<Integer>>("android.sensor.info.sensitivityRange", new TypeReference<android.util.Range<Integer>>() {{ }}); /** - * <p>Arrangement of color filters on sensor; + * <p>The arrangement of color filters on sensor; * represents the colors in the top-left 2x2 section of - * the sensor, in reading order</p> + * the sensor, in reading order.</p> * @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB * @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG * @see #SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG @@ -1666,10 +1665,9 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<int[]>("android.sensor.availableTestPatternModes", int[].class); /** - * <p>Which face detection modes are available, - * if any.</p> - * <p>OFF means face detection is disabled, it must - * be included in the list.</p> + * <p>The face detection modes that are available + * for 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> @@ -1681,8 +1679,8 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<int[]>("android.statistics.info.availableFaceDetectModes", int[].class); /** - * <p>Maximum number of simultaneously detectable - * faces</p> + * <p>The maximum number of simultaneously detectable + * faces.</p> */ public static final Key<Integer> STATISTICS_INFO_MAX_FACE_COUNT = new Key<Integer>("android.statistics.info.maxFaceCount", int.class); @@ -1691,7 +1689,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri * <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 should include both + * only OFF. If the hotpixel map is available, this will include both * the ON and OFF options.</p> * * @see CaptureRequest#STATISTICS_HOT_PIXEL_MAP_MODE diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index 90e5e4e..33e1915 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -157,8 +157,8 @@ public abstract class CameraMetadata<TKey> { /** * <p>The lens focus distance is not accurate, and the units used for - * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} do not correspond to any physical units. - * Setting the lens to the same focus distance on separate occasions may + * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} do not correspond to any physical units.</p> + * <p>Setting the lens to the same focus distance on separate occasions may * result in a different real focus distance, depending on factors such * as the orientation of the device, the age of the focusing mechanism, * and the device temperature. The focus distance value will still be @@ -172,20 +172,24 @@ public abstract class CameraMetadata<TKey> { public static final int LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED = 0; /** - * <p>The lens focus distance is measured in diopters. However, setting the lens - * to the same focus distance on separate occasions may result in a - * different real focus distance, depending on factors such as the - * orientation of the device, the age of the focusing mechanism, and - * the device temperature.</p> + * <p>The lens focus distance is measured in diopters.</p> + * <p>However, setting the lens to the same focus distance + * on separate occasions may result in a different real + * focus distance, depending on factors such as the + * orientation of the device, the age of the focusing + * mechanism, and the device temperature.</p> * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION */ public static final int LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE = 1; /** - * <p>The lens focus distance is measured in diopters. The lens mechanism is - * calibrated so that setting the same focus distance is repeatable on - * multiple occasions with good accuracy, and the focus distance corresponds - * to the real physical distance to the plane of best focus.</p> + * <p>The lens focus distance is measured in diopters, and + * is calibrated.</p> + * <p>The lens mechanism is calibrated so that setting the + * same focus distance is repeatable on multiple + * occasions with good accuracy, and the focus distance + * corresponds to the real physical distance to the plane + * of best focus.</p> * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION */ public static final int LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED = 2; @@ -195,11 +199,13 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>The camera device faces the same direction as the device's screen.</p> * @see CameraCharacteristics#LENS_FACING */ public static final int LENS_FACING_FRONT = 0; /** + * <p>The camera device faces the opposite direction as the device's screen.</p> * @see CameraCharacteristics#LENS_FACING */ public static final int LENS_FACING_BACK = 1; @@ -215,11 +221,10 @@ public abstract class CameraMetadata<TKey> { * <p>The full set of features supported by this capability makes * the camera2 api backwards compatible with the camera1 * (android.hardware.Camera) API.</p> - * <p>TODO: @hide this. Doesn't really mean anything except - * act as a catch-all for all the 'base' functionality.</p> * * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @hide */ public static final int REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE = 0; @@ -228,15 +233,14 @@ public abstract class CameraMetadata<TKey> { * tags or functionality not encapsulated by one of the other * capabilities.</p> * <p>A typical example is all tags marked 'optional'.</p> - * <p>TODO: @hide. We may not need this if we @hide all the optional - * tags not belonging to a capability.</p> * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @hide */ public static final int REQUEST_AVAILABLE_CAPABILITIES_OPTIONAL = 1; /** * <p>The camera device can be manually controlled (3A algorithms such - * as auto exposure, and auto focus can be bypassed). + * as auto-exposure, and auto-focus can be bypassed). * The camera device supports basic manual control of the sensor image * acquisition related stages. This means the following controls are * guaranteed to be supported:</p> @@ -257,11 +261,11 @@ public abstract class CameraMetadata<TKey> { * <li>{@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}</li> * </ul> * </li> - * <li>Manual lens control<ul> + * <li>Manual lens control (if the lens is adjustable)<ul> * <li>android.lens.*</li> * </ul> * </li> - * <li>Manual flash control<ul> + * <li>Manual flash control (if a flash unit is present)<ul> * <li>android.flash.*</li> * </ul> * </li> @@ -312,8 +316,6 @@ public abstract class CameraMetadata<TKey> { * </ul> * <p>If auto white balance is enabled, then the camera device * will accurately report the values applied by AWB in the result.</p> - * <p>The camera device will also support everything in MANUAL_SENSOR - * except manual lens control and manual flash control.</p> * <p>A given camera device may also support additional post-processing * controls, but this capability only covers the above list of controls.</p> * @@ -340,8 +342,8 @@ public abstract class CameraMetadata<TKey> { * (both input/output) will match the maximum available * resolution of JPEG streams.</li> * </ul> - * <p>@hide this, TODO: remove it when input related APIs are ready.</p> * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @hide */ public static final int REQUEST_AVAILABLE_CAPABILITIES_ZSL = 4; @@ -355,7 +357,7 @@ public abstract class CameraMetadata<TKey> { * <li>RAW16 is reprocessable into both YUV_420_888 and JPEG * formats.</li> * <li>The maximum available resolution for RAW16 streams (both - * input/output) will match the either value in + * input/output) 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 @@ -373,13 +375,13 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>The camera device will only support centered crop regions.</p> + * <p>The camera device only supports centered crop regions.</p> * @see CameraCharacteristics#SCALER_CROPPING_TYPE */ public static final int SCALER_CROPPING_TYPE_CENTER_ONLY = 0; /** - * <p>The camera device will support arbitrarily chosen crop regions.</p> + * <p>The camera device supports arbitrarily chosen crop regions.</p> * @see CameraCharacteristics#SCALER_CROPPING_TYPE */ public static final int SCALER_CROPPING_TYPE_FREEFORM = 1; @@ -525,7 +527,7 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>android.led.transmit control is used</p> + * <p>android.led.transmit control is used.</p> * @see CameraCharacteristics#LED_AVAILABLE_LEDS * @hide */ @@ -536,11 +538,14 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>This camera device has only limited capabilities.</p> * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED = 0; /** + * <p>This camera device is capable of supporting advanced imaging + * applications.</p> * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_FULL = 1; @@ -550,9 +555,9 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>Every frame has the requests immediately applied. - * (and furthermore for all results, - * <code>android.sync.frameNumber == android.request.frameCount</code>)</p> + * <p>Every frame has the requests immediately applied.</p> + * <p>Furthermore for all results, + * <code>android.sync.frameNumber == android.request.frameCount</code></p> * <p>Changing controls over multiple requests one after another will * produce results that have those controls applied atomically * each frame.</p> @@ -592,8 +597,8 @@ public abstract class CameraMetadata<TKey> { public static final int COLOR_CORRECTION_MODE_TRANSFORM_MATRIX = 0; /** - * <p>Must not slow down capture rate relative to sensor raw - * output.</p> + * <p>Color correction processing must not slow down + * capture rate relative to sensor raw output.</p> * <p>Advanced white balance adjustments above and beyond * the specified white balance pipeline may be applied.</p> * <p>If AWB is enabled with <code>{@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != OFF</code>, then @@ -606,8 +611,9 @@ public abstract class CameraMetadata<TKey> { public static final int COLOR_CORRECTION_MODE_FAST = 1; /** - * <p>Capture rate (relative to sensor raw output) - * may be reduced by high quality.</p> + * <p>Color correction processing operates at improved + * quality but reduced capture rate (relative to sensor raw + * output).</p> * <p>Advanced white balance adjustments above and beyond * the specified white balance pipeline may be applied.</p> * <p>If AWB is enabled with <code>{@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != OFF</code>, then @@ -658,8 +664,8 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>The camera device's autoexposure routine is disabled; - * the application-selected {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, + * <p>The camera device's autoexposure routine is disabled.</p> + * <p>The application-selected {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} and * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} are used by the camera * device, along with android.flash.* fields, if there's @@ -674,7 +680,8 @@ public abstract class CameraMetadata<TKey> { /** * <p>The camera device's autoexposure routine is active, - * with no flash control. The application's values for + * with no flash control.</p> + * <p>The application's values for * {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} are ignored. The @@ -691,10 +698,10 @@ public abstract class CameraMetadata<TKey> { /** * <p>Like ON, except that the camera device also controls * the camera's flash unit, firing it in low-light - * conditions. The flash may be fired during a - * precapture sequence (triggered by - * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and may be fired - * for captures for which the + * conditions.</p> + * <p>The flash may be fired during a precapture sequence + * (triggered by {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and + * may be fired for captures for which the * {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} field is set to * STILL_CAPTURE</p> * @@ -707,10 +714,10 @@ public abstract class CameraMetadata<TKey> { /** * <p>Like ON, except that the camera device also controls * the camera's flash unit, always firing it for still - * captures. The flash may be fired during a precapture - * sequence (triggered by - * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and will always - * be fired for captures for which the + * captures.</p> + * <p>The flash may be fired during a precapture sequence + * (triggered by {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}) and + * will always be fired for captures for which the * {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} field is set to * STILL_CAPTURE</p> * @@ -722,9 +729,10 @@ public abstract class CameraMetadata<TKey> { /** * <p>Like ON_AUTO_FLASH, but with automatic red eye - * reduction. If deemed necessary by the camera device, - * a red eye reduction flash will fire during the - * precapture sequence.</p> + * reduction.</p> + * <p>If deemed necessary by the camera device, a red eye + * reduction flash will fire during the precapture + * sequence.</p> * @see CaptureRequest#CONTROL_AE_MODE */ public static final int CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE = 4; @@ -741,8 +749,9 @@ public abstract class CameraMetadata<TKey> { /** * <p>The precapture metering sequence will be started - * by the camera device. The exact effect of the precapture - * trigger depends on the current AE mode and state.</p> + * by the camera device.</p> + * <p>The exact effect of the precapture trigger depends on + * the current AE mode and state.</p> * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER */ public static final int CONTROL_AE_PRECAPTURE_TRIGGER_START = 1; @@ -754,7 +763,7 @@ public abstract class CameraMetadata<TKey> { /** * <p>The auto-focus routine does not control the lens; * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} is controlled by the - * application</p> + * application.</p> * * @see CaptureRequest#LENS_FOCUS_DISTANCE * @see CaptureRequest#CONTROL_AF_MODE @@ -839,8 +848,11 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_AF_MODE_CONTINUOUS_PICTURE = 4; /** - * <p>Extended depth of field (digital focus). AF - * trigger is ignored, AF state should always be + * <p>Extended depth of field (digital focus) mode.</p> + * <p>The camera device will produce images with an extended + * depth of field automatically; no special focusing + * operations need to be done before taking a picture.</p> + * <p>AF triggers are ignored, and the AF state will always be * INACTIVE.</p> * @see CaptureRequest#CONTROL_AF_MODE */ @@ -874,8 +886,8 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>The camera device's auto white balance routine is disabled; - * the application-selected color transform matrix + * <p>The camera device's auto-white balance routine is disabled.</p> + * <p>The application-selected color transform matrix * ({@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}) and gains * ({@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}) are used by the camera * device for manual white balance control.</p> @@ -887,9 +899,12 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_AWB_MODE_OFF = 0; /** - * <p>The camera device's auto white balance routine is active; - * the application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} - * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored.</p> + * <p>The camera device's auto-white balance routine is active.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> * * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM @@ -898,65 +913,125 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_AWB_MODE_AUTO = 1; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses incandescent light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant A.</p> + * illumination for white balance.</p> + * <p>While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant A.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_INCANDESCENT = 2; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses fluorescent light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant F2.</p> + * illumination for white balance.</p> + * <p>While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant F2.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_FLUORESCENT = 3; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses warm fluorescent light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant F4.</p> + * illumination for white balance.</p> + * <p>While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant F4.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_WARM_FLUORESCENT = 4; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses daylight light as the assumed scene - * illumination for white balance. While the exact white balance - * transforms are up to the camera device, they will approximately - * match the CIE standard illuminant D65.</p> + * illumination for white balance.</p> + * <p>While the exact white balance transforms are up to the + * camera device, they will approximately match the CIE + * standard illuminant D65.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_DAYLIGHT = 5; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses cloudy daylight light as the assumed scene * illumination for white balance.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_CLOUDY_DAYLIGHT = 6; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses twilight light as the assumed scene * illumination for white balance.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_TWILIGHT = 7; /** - * <p>The camera device's auto white balance routine is disabled; + * <p>The camera device's auto-white balance routine is disabled; * the camera device uses shade light as the assumed scene * illumination for white balance.</p> + * <p>The application's values for {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} + * and {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} are ignored. + * For devices that support the MANUAL_POST_PROCESSING capability, the + * values used by the camera device for the transform and gains + * will be available in the capture result for this request.</p> + * + * @see CaptureRequest#COLOR_CORRECTION_GAINS + * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM * @see CaptureRequest#CONTROL_AWB_MODE */ public static final int CONTROL_AWB_MODE_SHADE = 8; @@ -966,38 +1041,43 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>This request doesn't fall into the other - * categories. Default to preview-like + * <p>The goal of this request doesn't fall into the other + * categories. The camera device will default to preview-like * behavior.</p> * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_CUSTOM = 0; /** - * <p>This request is for a preview-like usecase. The - * precapture trigger may be used to start off a metering - * w/flash sequence</p> + * <p>This request is for a preview-like use case.</p> + * <p>The precapture trigger may be used to start off a metering + * w/flash sequence.</p> * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_PREVIEW = 1; /** * <p>This request is for a still capture-type - * usecase.</p> + * use case.</p> + * <p>If the flash unit is under automatic control, it may fire as needed.</p> * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_STILL_CAPTURE = 2; /** * <p>This request is for a video recording - * usecase.</p> + * use case.</p> * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_VIDEO_RECORD = 3; /** * <p>This request is for a video snapshot (still - * image while recording video) usecase</p> + * 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> * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT = 4; @@ -1006,15 +1086,16 @@ public abstract class CameraMetadata<TKey> { * <p>This request is for a ZSL usecase; the * application will stream full-resolution images and * reprocess one or several later for a final - * capture</p> + * capture.</p> * @see CaptureRequest#CONTROL_CAPTURE_INTENT */ public static final int CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG = 5; /** * <p>This request is for manual capture use case where - * the applications want to directly control the capture parameters - * (e.g. {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} etc.).</p> + * the applications want to directly control the capture parameters.</p> + * <p>For example, the application may wish to manually control + * {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}, {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, etc.</p> * * @see CaptureRequest#SENSOR_EXPOSURE_TIME * @see CaptureRequest#SENSOR_SENSITIVITY @@ -1034,7 +1115,8 @@ public abstract class CameraMetadata<TKey> { /** * <p>A "monocolor" effect where the image is mapped into - * a single color. This will typically be grayscale.</p> + * a single color.</p> + * <p>This will typically be grayscale.</p> * @see CaptureRequest#CONTROL_EFFECT_MODE */ public static final int CONTROL_EFFECT_MODE_MONO = 1; @@ -1094,31 +1176,42 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>Full application control of pipeline. All 3A - * routines are disabled, no other settings in - * android.control.* have any effect</p> + * <p>Full application control of pipeline.</p> + * <p>All control by the device's metering and focusing (3A) + * routines is disabled, and no other settings in + * android.control.* have any effect, except that + * {@link CaptureRequest#CONTROL_CAPTURE_INTENT android.control.captureIntent} may be used by the camera + * device to select post-processing values for processing + * blocks that do not allow for manual control, or are not + * exposed by the camera API.</p> + * <p>However, the camera device's 3A routines may continue to + * collect statistics and update their internal state so that + * when control is switched to AUTO mode, good control values + * can be immediately applied.</p> + * + * @see CaptureRequest#CONTROL_CAPTURE_INTENT * @see CaptureRequest#CONTROL_MODE */ public static final int CONTROL_MODE_OFF = 0; /** - * <p>Use settings for each individual 3A routine. - * Manual control of capture parameters is disabled. All + * <p>Use settings for each individual 3A routine.</p> + * <p>Manual control of capture parameters is disabled. All * controls in android.control.* besides sceneMode take - * effect</p> + * effect.</p> * @see CaptureRequest#CONTROL_MODE */ public static final int CONTROL_MODE_AUTO = 1; /** - * <p>Use specific scene mode. Enabling this disables - * control.aeMode, control.awbMode and control.afMode - * controls; the camera device will ignore those settings while - * USE_SCENE_MODE is active (except for FACE_PRIORITY - * scene mode). Other control entries are still active. - * This setting can only be used if scene mode is supported - * (i.e. {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes} contain some modes - * other than DISABLED).</p> + * <p>Use a specific scene mode.</p> + * <p>Enabling this disables control.aeMode, control.awbMode and + * control.afMode controls; the camera device will ignore + * those settings while USE_SCENE_MODE is active (except for + * FACE_PRIORITY scene mode). Other control entries are still + * active. This setting can only be used if scene mode is + * supported (i.e. {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES android.control.availableSceneModes} + * contain some modes other than DISABLED).</p> * * @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES * @see CaptureRequest#CONTROL_MODE @@ -1128,7 +1221,12 @@ public abstract class CameraMetadata<TKey> { /** * <p>Same as OFF mode, except that this capture will not be * used by camera device background auto-exposure, auto-white balance and - * auto-focus algorithms to update their statistics.</p> + * auto-focus algorithms (3A) to update their statistics.</p> + * <p>Specifically, the 3A routines are locked to the last + * values set from a request with AUTO, OFF, or + * USE_SCENE_MODE, and any statistics or state updates + * collected from manual captures with OFF_KEEP_STATE will be + * discarded by the camera device.</p> * @see CaptureRequest#CONTROL_MODE */ public static final int CONTROL_MODE_OFF_KEEP_STATE = 3; @@ -1146,8 +1244,9 @@ public abstract class CameraMetadata<TKey> { /** * <p>If face detection support exists, use face * detection data for auto-focus, auto-white balance, and - * auto-exposure routines. If face detection statistics are - * disabled (i.e. {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} is set to OFF), + * auto-exposure routines.</p> + * <p>If face detection statistics are disabled + * (i.e. {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} is set to OFF), * this should still operate correctly (but will not return * face detection statistics to the framework).</p> * <p>Unlike the other scene modes, {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}, @@ -1163,8 +1262,8 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_SCENE_MODE_FACE_PRIORITY = 1; /** - * <p>Optimized for photos of quickly moving objects. - * Similar to SPORTS.</p> + * <p>Optimized for photos of quickly moving objects.</p> + * <p>Similar to SPORTS.</p> * @see CaptureRequest#CONTROL_SCENE_MODE */ public static final int CONTROL_SCENE_MODE_ACTION = 2; @@ -1233,8 +1332,8 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_SCENE_MODE_FIREWORKS = 12; /** - * <p>Optimized for photos of quickly moving people. - * Similar to ACTION.</p> + * <p>Optimized for photos of quickly moving people.</p> + * <p>Similar to ACTION.</p> * @see CaptureRequest#CONTROL_SCENE_MODE */ public static final int CONTROL_SCENE_MODE_SPORTS = 13; @@ -1266,11 +1365,13 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>Video stabilization is disabled.</p> * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE */ public static final int CONTROL_VIDEO_STABILIZATION_MODE_OFF = 0; /** + * <p>Video stabilization is enabled.</p> * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE */ public static final int CONTROL_VIDEO_STABILIZATION_MODE_ON = 1; @@ -1280,21 +1381,20 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>No edge enhancement is applied</p> + * <p>No edge enhancement is applied.</p> * @see CaptureRequest#EDGE_MODE */ public static final int EDGE_MODE_OFF = 0; /** - * <p>Must not slow down frame rate relative to sensor + * <p>Apply edge enhancement at a quality level that does not slow down frame rate relative to sensor * output</p> * @see CaptureRequest#EDGE_MODE */ public static final int EDGE_MODE_FAST = 1; /** - * <p>Frame rate may be reduced by high - * quality</p> + * <p>Apply high-quality edge enhancement, at a cost of reducing output frame rate.</p> * @see CaptureRequest#EDGE_MODE */ public static final int EDGE_MODE_HIGH_QUALITY = 2; @@ -1327,10 +1427,10 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>No hot pixel correction is applied.</p> * <p>The frame rate must not be reduced relative to sensor raw output * for this option.</p> - * <p>No hot pixel correction is applied. - * The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.</p> + * <p>The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.</p> * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP * @see CaptureRequest#HOT_PIXEL_MODE @@ -1338,10 +1438,9 @@ public abstract class CameraMetadata<TKey> { public static final int HOT_PIXEL_MODE_OFF = 0; /** - * <p>The frame rate must not be reduced relative to sensor raw output - * for this option.</p> - * <p>Hot pixel correction is applied. - * The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.</p> + * <p>Hot pixel correction is applied, without reducing frame + * rate relative to sensor raw output.</p> + * <p>The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.</p> * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP * @see CaptureRequest#HOT_PIXEL_MODE @@ -1349,10 +1448,9 @@ public abstract class CameraMetadata<TKey> { public static final int HOT_PIXEL_MODE_FAST = 1; /** - * <p>The frame rate may be reduced relative to sensor raw output - * for this option.</p> - * <p>A high-quality hot pixel correction is applied. - * The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.</p> + * <p>High-quality hot pixel correction is applied, at a cost + * of reducing frame rate relative to sensor raw output.</p> + * <p>The hotpixel map may be returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.</p> * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP * @see CaptureRequest#HOT_PIXEL_MODE @@ -1380,21 +1478,21 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>No noise reduction is applied</p> + * <p>No noise reduction is applied.</p> * @see CaptureRequest#NOISE_REDUCTION_MODE */ public static final int NOISE_REDUCTION_MODE_OFF = 0; /** - * <p>Must not slow down frame rate relative to sensor - * output</p> + * <p>Noise reduction is applied without reducing frame rate relative to sensor + * output.</p> * @see CaptureRequest#NOISE_REDUCTION_MODE */ public static final int NOISE_REDUCTION_MODE_FAST = 1; /** - * <p>May slow down frame rate to provide highest - * quality</p> + * <p>High-quality noise reduction is applied, at the cost of reducing frame rate + * relative to sensor output.</p> * @see CaptureRequest#NOISE_REDUCTION_MODE */ public static final int NOISE_REDUCTION_MODE_HIGH_QUALITY = 2; @@ -1404,8 +1502,9 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>Default. No test pattern mode is used, and the camera + * <p>No test pattern mode is used, and the camera * device returns captures from the image sensor.</p> + * <p>This is the default if the key is not set.</p> * @see CaptureRequest#SENSOR_TEST_PATTERN_MODE */ public static final int SENSOR_TEST_PATTERN_MODE_OFF = 0; @@ -1509,19 +1608,21 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>No lens shading correction is applied</p> + * <p>No lens shading correction is applied.</p> * @see CaptureRequest#SHADING_MODE */ public static final int SHADING_MODE_OFF = 0; /** - * <p>Must not slow down frame rate relative to sensor raw output</p> + * <p>Apply lens shading corrections, without slowing + * frame rate relative to sensor raw output</p> * @see CaptureRequest#SHADING_MODE */ public static final int SHADING_MODE_FAST = 1; /** - * <p>Frame rate may be reduced by high quality</p> + * <p>Apply high-quality lens shading correction, at the + * cost of reduced frame rate.</p> * @see CaptureRequest#SHADING_MODE */ public static final int SHADING_MODE_HIGH_QUALITY = 2; @@ -1531,20 +1632,28 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>Do not include face detection statistics in capture + * results.</p> * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE */ public static final int STATISTICS_FACE_DETECT_MODE_OFF = 0; /** - * <p>Optional Return rectangle and confidence - * only</p> + * <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; /** - * <p>Optional Return all face - * metadata</p> + * <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> * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE */ public static final int STATISTICS_FACE_DETECT_MODE_FULL = 2; @@ -1554,11 +1663,13 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>Do not include a lens shading map in the capture result.</p> * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE */ public static final int STATISTICS_LENS_SHADING_MAP_MODE_OFF = 0; /** + * <p>Include a lens shading map in the capture result.</p> * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE */ public static final int STATISTICS_LENS_SHADING_MAP_MODE_ON = 1; @@ -1582,15 +1693,15 @@ public abstract class CameraMetadata<TKey> { public static final int TONEMAP_MODE_CONTRAST_CURVE = 0; /** - * <p>Advanced gamma mapping and color enhancement may be applied.</p> - * <p>Should not slow down frame rate relative to raw sensor output.</p> + * <p>Advanced gamma mapping and color enhancement may be applied, without + * reducing frame rate compared to raw sensor output.</p> * @see CaptureRequest#TONEMAP_MODE */ public static final int TONEMAP_MODE_FAST = 1; /** - * <p>Advanced gamma mapping and color enhancement may be applied.</p> - * <p>May slow down frame rate relative to raw sensor output.</p> + * <p>High-quality gamma mapping and color enhancement will be applied, at + * the cost of reduced frame rate compared to raw sensor output.</p> * @see CaptureRequest#TONEMAP_MODE */ public static final int TONEMAP_MODE_HIGH_QUALITY = 2; @@ -1600,7 +1711,8 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>AE is off or recently reset. When a camera device is opened, it starts in + * <p>AE is off or recently reset.</p> + * <p>When a camera device is opened, it starts in * this state. This is a transient state, the camera device may skip reporting * this state in capture result.</p> * @see CaptureResult#CONTROL_AE_STATE @@ -1609,7 +1721,8 @@ public abstract class CameraMetadata<TKey> { /** * <p>AE doesn't yet have a good set of control values - * for the current scene. This is a transient state, the camera device may skip + * for the current scene.</p> + * <p>This is a transient state, the camera device may skip * reporting this state in capture result.</p> * @see CaptureResult#CONTROL_AE_STATE */ @@ -1638,11 +1751,13 @@ public abstract class CameraMetadata<TKey> { /** * <p>AE has been asked to do a precapture sequence - * (through the {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} START), - * and is currently executing it. Once PRECAPTURE - * completes, AE will transition to CONVERGED or - * FLASH_REQUIRED as appropriate. This is a transient state, the - * camera device may skip reporting this state in capture result.</p> + * and is currently executing it.</p> + * <p>Precapture can be triggered through setting + * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} to START.</p> + * <p>Once PRECAPTURE completes, AE will transition to CONVERGED + * or FLASH_REQUIRED as appropriate. This is a transient + * state, the camera device may skip reporting this state in + * capture result.</p> * * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER * @see CaptureResult#CONTROL_AE_STATE @@ -1654,61 +1769,78 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>AF off or has not yet tried to scan/been asked - * to scan. When a camera device is opened, it starts in - * this state. This is a transient state, the camera device may - * skip reporting this state in capture result.</p> + * <p>AF is off or has not yet tried to scan/been asked + * to scan.</p> + * <p>When a camera device is opened, it starts in this + * state. This is a transient state, the camera device may + * skip reporting this state in capture + * result.</p> * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_INACTIVE = 0; /** - * <p>if CONTINUOUS_* modes are supported. AF is - * currently doing an AF scan initiated by a continuous - * autofocus mode. This is a transient state, the camera device may - * skip reporting this state in capture result.</p> + * <p>AF is currently performing an AF scan initiated the + * camera device in a continuous autofocus mode.</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> * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_SCAN = 1; /** - * <p>if CONTINUOUS_* modes are supported. AF currently - * believes it is in focus, but may restart scanning at - * any time. This is a transient state, the camera device may skip - * reporting this state in capture result.</p> + * <p>AF currently believes it is in focus, but 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> * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_PASSIVE_FOCUSED = 2; /** - * <p>if AUTO or MACRO modes are supported. AF is doing - * an AF scan because it was triggered by AF trigger. This is a - * transient state, the camera device may skip reporting - * this state in capture result.</p> + * <p>AF is performing an AF scan because it was + * triggered by AF trigger.</p> + * <p>Only used by AUTO or MACRO AF modes. This is a transient + * state, the camera device may skip reporting this state in + * capture result.</p> * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_ACTIVE_SCAN = 3; /** - * <p>if any AF mode besides OFF is supported. AF - * believes it is focused correctly and is - * locked.</p> + * <p>AF believes it is focused correctly and has locked + * focus.</p> + * <p>This state is reached only after an explicit START AF trigger has been + * sent ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}), when good focus has been obtained.</p> + * <p>The lens will remain stationary until the AF mode ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) is changed or + * a new AF trigger is sent to the camera device ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}).</p> + * + * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#CONTROL_AF_TRIGGER * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_FOCUSED_LOCKED = 4; /** - * <p>if any AF mode besides OFF is supported. AF has - * failed to focus successfully and is - * locked.</p> + * <p>AF has failed to focus successfully and has locked + * focus.</p> + * <p>This state is reached only after an explicit START AF trigger has been + * sent ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}), when good focus cannot be obtained.</p> + * <p>The lens will remain stationary until the AF mode ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) is changed or + * a new AF trigger is sent to the camera device ({@link CaptureRequest#CONTROL_AF_TRIGGER android.control.afTrigger}).</p> + * + * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#CONTROL_AF_TRIGGER * @see CaptureResult#CONTROL_AF_STATE */ public static final int CONTROL_AF_STATE_NOT_FOCUSED_LOCKED = 5; /** - * <p>if CONTINUOUS_* modes are supported. AF finished a - * passive scan without finding focus, and may restart - * scanning at any time. This is a transient state, the camera + * <p>AF finished a passive scan without finding focus, + * 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> * @see CaptureResult#CONTROL_AF_STATE */ @@ -1719,16 +1851,19 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>AWB is not in auto mode. When a camera device is opened, it - * starts in this state. This is a transient state, the camera device may - * skip reporting this state in capture result.</p> + * <p>AWB is not in auto mode, or has not yet started metering.</p> + * <p>When a camera device is opened, it starts in this + * state. This is a transient state, the camera device may + * skip reporting this state in capture + * result.</p> * @see CaptureResult#CONTROL_AWB_STATE */ public static final int CONTROL_AWB_STATE_INACTIVE = 0; /** * <p>AWB doesn't yet have a good set of control - * values for the current scene. This is a transient state, the camera device + * values for the current scene.</p> + * <p>This is a transient state, the camera device * may skip reporting this state in capture result.</p> * @see CaptureResult#CONTROL_AWB_STATE */ @@ -1776,8 +1911,9 @@ public abstract class CameraMetadata<TKey> { public static final int FLASH_STATE_FIRED = 3; /** - * <p>Flash partially illuminated this frame. This is usually due to the next - * or previous frame having the flash fire, and the flash spilling into this capture + * <p>Flash partially illuminated this frame.</p> + * <p>This is usually due to the next or previous frame having + * the flash fire, and the flash spilling into this capture * due to hardware limitations.</p> * @see CaptureResult#FLASH_STATE */ @@ -1800,8 +1936,10 @@ public abstract class CameraMetadata<TKey> { public static final int LENS_STATE_STATIONARY = 0; /** - * <p>Any of the lens parameters ({@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance}, - * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} or {@link CaptureRequest#LENS_APERTURE android.lens.aperture}) is changing.</p> + * <p>One or several of the lens parameters + * ({@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance}, + * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} or {@link CaptureRequest#LENS_APERTURE android.lens.aperture}) is + * currently changing.</p> * * @see CaptureRequest#LENS_APERTURE * @see CaptureRequest#LENS_FILTER_DENSITY @@ -1816,16 +1954,22 @@ public abstract class CameraMetadata<TKey> { // /** + * <p>The camera device does not detect any flickering illumination + * in the current scene.</p> * @see CaptureResult#STATISTICS_SCENE_FLICKER */ public static final int STATISTICS_SCENE_FLICKER_NONE = 0; /** + * <p>The camera device detects illumination flickering at 50Hz + * in the current scene.</p> * @see CaptureResult#STATISTICS_SCENE_FLICKER */ public static final int STATISTICS_SCENE_FLICKER_50HZ = 1; /** + * <p>The camera device detects illumination flickering at 60Hz + * in the current scene.</p> * @see CaptureResult#STATISTICS_SCENE_FLICKER */ public static final int STATISTICS_SCENE_FLICKER_60HZ = 2; @@ -1835,8 +1979,8 @@ public abstract class CameraMetadata<TKey> { // /** - * <p>The current result is not yet fully synchronized to any request. - * Synchronization is in progress, and reading metadata from this + * <p>The current result is not yet fully synchronized to any request.</p> + * <p>Synchronization is in progress, and reading metadata from this * result may include a mix of data that have taken effect since the * last synchronization time.</p> * <p>In some future result, within {@link CameraCharacteristics#SYNC_MAX_LATENCY android.sync.maxLatency} frames, @@ -1851,10 +1995,10 @@ public abstract class CameraMetadata<TKey> { public static final int SYNC_FRAME_NUMBER_CONVERGING = -1; /** - * <p>The current result's synchronization status is unknown. The - * result may have already converged, or it may be in progress. - * Reading from this result may include some mix of settings from - * past requests.</p> + * <p>The current result's synchronization status is unknown.</p> + * <p>The result may have already converged, or it may be in + * progress. Reading from this result may include some mix + * of settings from past requests.</p> * <p>After a settings change, the new settings will eventually all * take effect for the output buffers and results. However, this * value will not change when that happens. Altering settings diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index 0ff8cce..bf7bd37 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -733,8 +733,16 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * included at all in the request settings. When included and * set to START, the camera device will trigger the autoexposure * precapture metering sequence.</p> - * <p>The effect of auto-exposure (AE) precapture trigger depends - * on the current AE mode and state; see + * <p>The precapture sequence should triggered before starting a + * high-quality still capture for final metering decisions to + * be made, and for firing pre-capture flash pulses to estimate + * scene brightness and required final capture flash power, when + * the flash is enabled.</p> + * <p>Normally, this entry should be set to START for only a + * single request, and the application should wait until the + * sequence completes before starting a new one.</p> + * <p>The exact effect of auto-exposure (AE) precapture trigger + * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.</p> * @@ -800,7 +808,11 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * autofocus algorithm. If autofocus is disabled, this trigger has no effect.</p> * <p>When set to CANCEL, the camera device will cancel any active trigger, * and return to its initial AF state.</p> - * <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.</p> + * <p>Generally, applications should set this entry to START or CANCEL for only a + * single capture, and then return it to IDLE (or not set at all). Specifying + * 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> * * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE @@ -813,9 +825,11 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>Whether auto-white balance (AWB) is currently locked to its * latest calculated values.</p> - * <p>Note that AWB lock is only meaningful for AUTO - * mode; in other modes, AWB is already fixed to a specific - * setting.</p> + * <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> + * + * @see CaptureRequest#CONTROL_AWB_MODE */ public static final Key<Boolean> CONTROL_AWB_LOCK = new Key<Boolean>("android.control.awbLock", boolean.class); @@ -825,17 +839,21 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * transform fields, and what its illumination target * is.</p> * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p> - * <p>When set to the ON mode, the camera device's auto white balance + * <p>When set to the ON mode, the camera device's auto-white balance * routine is enabled, overriding the application's selected * {@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}.</p> - * <p>When set to the OFF mode, the camera device's auto white balance + * <p>When set to the OFF mode, the camera device's auto-white balance * routine is disabled. The application manually controls the white * balance by {@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}.</p> - * <p>When set to any other modes, the camera device's auto white balance - * routine is disabled. The camera device uses each particular illumination - * target for white balance adjustment.</p> + * <p>When set to any other modes, the camera device's auto-white + * balance routine is disabled. The camera device uses each + * particular illumination target for white balance + * adjustment. The application's values for + * {@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> * * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -886,8 +904,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * strategy.</p> * <p>This control (except for MANUAL) is only effective if * <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p> - * <p>ZERO_SHUTTER_LAG must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} - * contains ZSL. MANUAL must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} + * <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> * * @see CaptureRequest#CONTROL_MODE @@ -962,7 +980,9 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <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.</p> + * {@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> * <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 @@ -970,6 +990,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AF_MODE + * @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES * @see CaptureRequest#CONTROL_AWB_MODE * @see CaptureRequest#CONTROL_MODE * @see #CONTROL_SCENE_MODE_DISABLED @@ -996,6 +1017,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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>If enabled, video stabilization can modify the * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream * stabilized</p> @@ -1110,14 +1133,14 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>Compression quality of the final JPEG * image.</p> - * <p>85-95 is typical usage range</p> + * <p>85-95 is typical usage range.</p> */ public static final Key<Byte> JPEG_QUALITY = new Key<Byte>("android.jpeg.quality", byte.class); /** * <p>Compression quality of JPEG - * thumbnail</p> + * thumbnail.</p> */ public static final Key<Byte> JPEG_THUMBNAIL_QUALITY = new Key<Byte>("android.jpeg.thumbnailQuality", byte.class); @@ -1229,12 +1252,18 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>Sets whether the camera device uses optical image stabilization (OIS) * when capturing images.</p> - * <p>OIS is used to compensate for motion blur due to small movements of - * the camera during capture. Unlike digital image stabilization, OIS makes - * use of mechanical elements to stabilize the camera sensor, and thus - * allows for longer exposure times before camera shake becomes - * apparent.</p> - * <p>This is not expected to be supported on most devices.</p> + * <p>OIS is used to compensate for motion blur due to small + * movements of the camera during capture. Unlike digital image + * stabilization ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}), OIS + * makes use of mechanical elements to stabilize the camera + * sensor, and thus allows for longer exposure times before + * camera shake becomes apparent.</p> + * <p>Not all devices will support OIS; see + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for + * available controls.</p> + * + * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE + * @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF * @see #LENS_OPTICAL_STABILIZATION_MODE_ON */ @@ -1242,16 +1271,15 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.lens.opticalStabilizationMode", int.class); /** - * <p>Mode of operation for the noise reduction. - * algorithm</p> + * <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 in + * <p>This must be set to a valid mode from * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</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 should not + * even if it slows down capture rate. FAST means the camera device will not * slow down capture rate when applying noise filtering.</p> * * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES @@ -1435,7 +1463,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <p>When enabled, the sensor sends a test pattern instead of * doing a real exposure from the camera.</p> * <p>When a test pattern is enabled, all manual sensor controls specified - * by android.sensor.* should be ignored. All other controls should + * by android.sensor.* will be ignored. All other controls should * work as normal.</p> * <p>For example, if manual flash is enabled, flash firing should still * occur (and that the test pattern remain unmodified, since the flash @@ -1490,7 +1518,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.shading.mode", int.class); /** - * <p>State of the face detector + * <p>Control 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 @@ -1508,7 +1536,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <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 should be returned.</p> + * 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> * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP @@ -1521,7 +1549,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <p>Whether the camera device will output the lens * shading map in output result metadata.</p> * <p>When set to ON, - * android.statistics.lensShadingMap must be provided in + * android.statistics.lensShadingMap will be provided in * the output result metadata.</p> * @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index ce3de1d..3d17ed3 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -579,8 +579,16 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * included at all in the request settings. When included and * set to START, the camera device will trigger the autoexposure * precapture metering sequence.</p> - * <p>The effect of auto-exposure (AE) precapture trigger depends - * on the current AE mode and state; see + * <p>The precapture sequence should triggered before starting a + * high-quality still capture for final metering decisions to + * be made, and for firing pre-capture flash pulses to estimate + * scene brightness and required final capture flash power, when + * the flash is enabled.</p> + * <p>Normally, this entry should be set to START for only a + * single request, and the application should wait until the + * sequence completes before starting a new one.</p> + * <p>The exact effect of auto-exposure (AE) precapture trigger + * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition * details.</p> * @@ -592,7 +600,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.aePrecaptureTrigger", int.class); /** - * <p>Current state of auto-exposure (AE) algorithm.</p> + * <p>Current state of the auto-exposure (AE) algorithm.</p> * <p>Switching between or enabling AE modes ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}) always * resets the AE state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode}, * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all @@ -844,7 +852,11 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * autofocus algorithm. If autofocus is disabled, this trigger has no effect.</p> * <p>When set to CANCEL, the camera device will cancel any active trigger, * and return to its initial AF state.</p> - * <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.</p> + * <p>Generally, applications should set this entry to START or CANCEL for only a + * single capture, and then return it to IDLE (or not set at all). Specifying + * 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> * * @see CaptureResult#CONTROL_AF_STATE * @see #CONTROL_AF_TRIGGER_IDLE @@ -1034,13 +1046,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <td align="center">PASSIVE_SCAN</td> * <td align="center">AF_TRIGGER</td> * <td align="center">FOCUSED_LOCKED</td> - * <td align="center">Immediate trans. If focus is good, Lens now locked</td> + * <td align="center">Immediate transition, if focus is good. Lens now locked</td> * </tr> * <tr> * <td align="center">PASSIVE_SCAN</td> * <td align="center">AF_TRIGGER</td> * <td align="center">NOT_FOCUSED_LOCKED</td> - * <td align="center">Immediate trans. if focus is bad, Lens now locked</td> + * <td align="center">Immediate transition, if focus is bad. Lens now locked</td> * </tr> * <tr> * <td align="center">PASSIVE_SCAN</td> @@ -1064,13 +1076,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <td align="center">PASSIVE_FOCUSED</td> * <td align="center">AF_TRIGGER</td> * <td align="center">FOCUSED_LOCKED</td> - * <td align="center">Immediate trans. Lens now locked</td> + * <td align="center">Immediate transition, lens now locked</td> * </tr> * <tr> * <td align="center">PASSIVE_UNFOCUSED</td> * <td align="center">AF_TRIGGER</td> * <td align="center">NOT_FOCUSED_LOCKED</td> - * <td align="center">Immediate trans. Lens now locked</td> + * <td align="center">Immediate transition, lens now locked</td> * </tr> * <tr> * <td align="center">FOCUSED_LOCKED</td> @@ -1137,13 +1149,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <td align="center">PASSIVE_SCAN</td> * <td align="center">AF_TRIGGER</td> * <td align="center">FOCUSED_LOCKED</td> - * <td align="center">Eventual trans. once focus good, Lens now locked</td> + * <td align="center">Eventual transition once the focus is good. Lens now locked</td> * </tr> * <tr> * <td align="center">PASSIVE_SCAN</td> * <td align="center">AF_TRIGGER</td> * <td align="center">NOT_FOCUSED_LOCKED</td> - * <td align="center">Eventual trans. if cannot focus, Lens now locked</td> + * <td align="center">Eventual transition if cannot find focus. Lens now locked</td> * </tr> * <tr> * <td align="center">PASSIVE_SCAN</td> @@ -1254,9 +1266,11 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Whether auto-white balance (AWB) is currently locked to its * latest calculated values.</p> - * <p>Note that AWB lock is only meaningful for AUTO - * mode; in other modes, AWB is already fixed to a specific - * setting.</p> + * <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> + * + * @see CaptureRequest#CONTROL_AWB_MODE */ public static final Key<Boolean> CONTROL_AWB_LOCK = new Key<Boolean>("android.control.awbLock", boolean.class); @@ -1266,17 +1280,21 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * transform fields, and what its illumination target * is.</p> * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p> - * <p>When set to the ON mode, the camera device's auto white balance + * <p>When set to the ON mode, the camera device's auto-white balance * routine is enabled, overriding the application's selected * {@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}.</p> - * <p>When set to the OFF mode, the camera device's auto white balance + * <p>When set to the OFF mode, the camera device's auto-white balance * routine is disabled. The application manually controls the white * balance by {@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}.</p> - * <p>When set to any other modes, the camera device's auto white balance - * routine is disabled. The camera device uses each particular illumination - * target for white balance adjustment.</p> + * <p>When set to any other modes, the camera device's auto-white + * balance routine is disabled. The camera device uses each + * particular illumination target for white balance + * adjustment. The application's values for + * {@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> * * @see CaptureRequest#COLOR_CORRECTION_GAINS * @see CaptureRequest#COLOR_CORRECTION_MODE @@ -1327,8 +1345,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * strategy.</p> * <p>This control (except for MANUAL) is only effective if * <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p> - * <p>ZERO_SHUTTER_LAG must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} - * contains ZSL. MANUAL must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} + * <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> * * @see CaptureRequest#CONTROL_MODE @@ -1533,7 +1551,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <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.</p> + * {@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> * <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 @@ -1541,6 +1561,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureRequest#CONTROL_AF_MODE + * @see CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES * @see CaptureRequest#CONTROL_AWB_MODE * @see CaptureRequest#CONTROL_MODE * @see #CONTROL_SCENE_MODE_DISABLED @@ -1567,6 +1588,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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>If enabled, video stabilization can modify the * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream * stabilized</p> @@ -1698,14 +1721,14 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Compression quality of the final JPEG * image.</p> - * <p>85-95 is typical usage range</p> + * <p>85-95 is typical usage range.</p> */ public static final Key<Byte> JPEG_QUALITY = new Key<Byte>("android.jpeg.quality", byte.class); /** * <p>Compression quality of JPEG - * thumbnail</p> + * thumbnail.</p> */ public static final Key<Byte> JPEG_THUMBNAIL_QUALITY = new Key<Byte>("android.jpeg.thumbnailQuality", byte.class); @@ -1817,12 +1840,18 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Sets whether the camera device uses optical image stabilization (OIS) * when capturing images.</p> - * <p>OIS is used to compensate for motion blur due to small movements of - * the camera during capture. Unlike digital image stabilization, OIS makes - * use of mechanical elements to stabilize the camera sensor, and thus - * allows for longer exposure times before camera shake becomes - * apparent.</p> - * <p>This is not expected to be supported on most devices.</p> + * <p>OIS is used to compensate for motion blur due to small + * movements of the camera during capture. Unlike digital image + * stabilization ({@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE android.control.videoStabilizationMode}), OIS + * makes use of mechanical elements to stabilize the camera + * sensor, and thus allows for longer exposure times before + * camera shake becomes apparent.</p> + * <p>Not all devices will support OIS; see + * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION android.lens.info.availableOpticalStabilization} for + * available controls.</p> + * + * @see CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE + * @see CameraCharacteristics#LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF * @see #LENS_OPTICAL_STABILIZATION_MODE_ON */ @@ -1866,16 +1895,15 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.lens.state", int.class); /** - * <p>Mode of operation for the noise reduction. - * algorithm</p> + * <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 in + * <p>This must be set to a valid mode from * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</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 should not + * even if it slows down capture rate. FAST means the camera device will not * slow down capture rate when applying noise filtering.</p> * * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES @@ -2170,7 +2198,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <p>When enabled, the sensor sends a test pattern instead of * doing a real exposure from the camera.</p> * <p>When a test pattern is enabled, all manual sensor controls specified - * by android.sensor.* should be ignored. All other controls should + * by android.sensor.* will be ignored. All other controls should * work as normal.</p> * <p>For example, if manual flash is enabled, flash firing should still * occur (and that the test pattern remain unmodified, since the flash @@ -2225,7 +2253,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.shading.mode", int.class); /** - * <p>State of the face detector + * <p>Control 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 @@ -2241,9 +2269,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.statistics.faceDetectMode", int.class); /** - * <p>List of unique IDs for detected - * faces</p> - * <p>Only available if faceDetectMode == FULL</p> + * <p>List of unique IDs for detected faces.</p> + * <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> + * + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ public static final Key<int[]> STATISTICS_FACE_IDS = @@ -2251,8 +2283,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>List of landmarks for detected - * faces</p> - * <p>Only available if faceDetectMode == FULL</p> + * 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> + * + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ public static final Key<int[]> STATISTICS_FACE_LANDMARKS = @@ -2260,8 +2297,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>List of the bounding rectangles for detected - * faces</p> - * <p>Only available if faceDetectMode != OFF</p> + * 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> + * + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ public static final Key<android.graphics.Rect[]> STATISTICS_FACE_RECTANGLES = @@ -2270,8 +2312,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>List of the face confidence scores for * detected faces</p> - * <p>Only available if faceDetectMode != OFF. The value should be - * meaningful (for example, setting 100 at all times is illegal).</p> + * <p>Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF.</p> + * + * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ public static final Key<byte[]> STATISTICS_FACE_SCORES = @@ -2435,12 +2478,13 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * The camera device uses this entry to tell the application what the scene * illuminant frequency is.</p> * <p>When manual exposure control is enabled - * (<code>{@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == OFF</code> or <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == OFF</code>), - * the {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} doesn't do the antibanding, and the - * application can ensure it selects exposure times that do not cause banding - * issues by looking into this metadata field. See {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} - * for more details.</p> - * <p>Report NONE if there doesn't appear to be flickering illumination.</p> + * (<code>{@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == OFF</code> or <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == + * OFF</code>), the {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} doesn't perform + * antibanding, and the application can ensure it selects + * exposure times that do not cause banding issues by looking + * 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> * * @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE * @see CaptureRequest#CONTROL_AE_MODE @@ -2455,7 +2499,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <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 should be returned.</p> + * 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> * * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP @@ -2483,7 +2527,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <p>Whether the camera device will output the lens * shading map in output result metadata.</p> * <p>When set to ON, - * android.statistics.lensShadingMap must be provided in + * android.statistics.lensShadingMap will be provided in * the output result metadata.</p> * @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON diff --git a/core/java/android/hardware/camera2/params/StreamConfiguration.java b/core/java/android/hardware/camera2/params/StreamConfiguration.java index dd862b5..a6fc10f 100644 --- a/core/java/android/hardware/camera2/params/StreamConfiguration.java +++ b/core/java/android/hardware/camera2/params/StreamConfiguration.java @@ -30,7 +30,8 @@ import android.util.Size; * Immutable class to store the available stream * {@link CameraCharacteristics#SCALER_AVAILABLE_STREAM_CONFIGURATIONS configurations} to set up * {@link android.view.Surface Surfaces} for creating a {@link CameraCaptureSession capture session} - * with {@link CameraDevice#createCaptureSession}. <!-- TODO: link to input stream configuration --> + * with {@link CameraDevice#createCaptureSession}. + * <!-- TODO: link to input stream configuration --> * * <p>This is the authoritative list for all input/output formats (and sizes respectively * for that format) that are supported by a camera device.</p> diff --git a/core/java/android/net/DhcpResults.java b/core/java/android/net/DhcpResults.java index 22b26b1..49a307e 100644 --- a/core/java/android/net/DhcpResults.java +++ b/core/java/android/net/DhcpResults.java @@ -74,8 +74,10 @@ public class DhcpResults implements Parcelable { if (linkProperties.getRoutes().size() == 0) { for (RouteInfo r : orig.linkProperties.getRoutes()) linkProperties.addRoute(r); } - if (linkProperties.getDnses().size() == 0) { - for (InetAddress d : orig.linkProperties.getDnses()) linkProperties.addDns(d); + if (linkProperties.getDnsServers().size() == 0) { + for (InetAddress d : orig.linkProperties.getDnsServers()) { + linkProperties.addDnsServer(d); + } } } @@ -211,7 +213,7 @@ public class DhcpResults implements Parcelable { public boolean addDns(String addrString) { if (TextUtils.isEmpty(addrString) == false) { try { - linkProperties.addDns(NetworkUtils.numericToInetAddress(addrString)); + linkProperties.addDnsServer(NetworkUtils.numericToInetAddress(addrString)); } catch (IllegalArgumentException e) { Log.e(TAG, "addDns failed with addrString " + addrString); return true; diff --git a/core/java/android/net/DnsPinger.java b/core/java/android/net/DnsPinger.java index 66f0fd0..7acf3f5 100644 --- a/core/java/android/net/DnsPinger.java +++ b/core/java/android/net/DnsPinger.java @@ -248,7 +248,7 @@ public final class DnsPinger extends Handler { return mDefaultDns; } - Collection<InetAddress> dnses = curLinkProps.getDnses(); + Collection<InetAddress> dnses = curLinkProps.getDnsServers(); if (dnses == null || dnses.size() == 0) { loge("getDns::LinkProps has null dns - returning default"); return mDefaultDns; diff --git a/core/java/android/net/LinkProperties.java b/core/java/android/net/LinkProperties.java index 3c36679..cff9025 100644 --- a/core/java/android/net/LinkProperties.java +++ b/core/java/android/net/LinkProperties.java @@ -30,6 +30,7 @@ import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.Hashtable; +import java.util.List; /** * Describes the properties of a network link. @@ -58,10 +59,12 @@ public class LinkProperties implements Parcelable { private Hashtable<String, LinkProperties> mStackedLinks = new Hashtable<String, LinkProperties>(); - // @hide + /** + * @hide + */ public static class CompareResult<T> { - public Collection<T> removed = new ArrayList<T>(); - public Collection<T> added = new ArrayList<T>(); + public List<T> removed = new ArrayList<T>(); + public List<T> added = new ArrayList<T>(); @Override public String toString() { @@ -81,7 +84,7 @@ public class LinkProperties implements Parcelable { if (source != null) { mIfaceName = source.getInterfaceName(); for (LinkAddress l : source.getLinkAddresses()) mLinkAddresses.add(l); - for (InetAddress i : source.getDnses()) mDnses.add(i); + for (InetAddress i : source.getDnsServers()) mDnses.add(i); mDomains = source.getDomains(); for (RouteInfo r : source.getRoutes()) mRoutes.add(r); mHttpProxy = (source.getHttpProxy() == null) ? @@ -98,6 +101,7 @@ public class LinkProperties implements Parcelable { * will have their interface changed to match this new value. * * @param iface The name of the network interface used for this link. + * @hide */ public void setInterfaceName(String iface) { mIfaceName = iface; @@ -117,9 +121,11 @@ public class LinkProperties implements Parcelable { return mIfaceName; } - // @hide - public Collection<String> getAllInterfaceNames() { - Collection interfaceNames = new ArrayList<String>(mStackedLinks.size() + 1); + /** + * @hide + */ + public List<String> getAllInterfaceNames() { + List<String> interfaceNames = new ArrayList<String>(mStackedLinks.size() + 1); if (mIfaceName != null) interfaceNames.add(new String(mIfaceName)); for (LinkProperties stacked: mStackedLinks.values()) { interfaceNames.addAll(stacked.getAllInterfaceNames()); @@ -134,23 +140,23 @@ public class LinkProperties implements Parcelable { * prefix lengths for each address. This is a simplified utility alternative to * {@link LinkProperties#getLinkAddresses}. * - * @return An umodifiable {@link Collection} of {@link InetAddress} for this link. + * @return An umodifiable {@link List} of {@link InetAddress} for this link. * @hide */ - public Collection<InetAddress> getAddresses() { - Collection<InetAddress> addresses = new ArrayList<InetAddress>(); + public List<InetAddress> getAddresses() { + List<InetAddress> addresses = new ArrayList<InetAddress>(); for (LinkAddress linkAddress : mLinkAddresses) { addresses.add(linkAddress.getAddress()); } - return Collections.unmodifiableCollection(addresses); + return Collections.unmodifiableList(addresses); } /** * Returns all the addresses on this link and all the links stacked above it. * @hide */ - public Collection<InetAddress> getAllAddresses() { - Collection<InetAddress> addresses = new ArrayList<InetAddress>(); + public List<InetAddress> getAllAddresses() { + List<InetAddress> addresses = new ArrayList<InetAddress>(); for (LinkAddress linkAddress : mLinkAddresses) { addresses.add(linkAddress.getAddress()); } @@ -174,6 +180,7 @@ public class LinkProperties implements Parcelable { * same address/prefix does not already exist. If it does exist it is replaced. * @param address The {@code LinkAddress} to add. * @return true if {@code address} was added or updated, false otherwise. + * @hide */ public boolean addLinkAddress(LinkAddress address) { if (address == null) { @@ -200,6 +207,7 @@ public class LinkProperties implements Parcelable { * * @param toRemove A {@link LinkAddress} specifying the address to remove. * @return true if the address was removed, false if it did not exist. + * @hide */ public boolean removeLinkAddress(LinkAddress toRemove) { int i = findLinkAddressIndex(toRemove); @@ -214,18 +222,18 @@ public class LinkProperties implements Parcelable { * Returns all the {@link LinkAddress} on this link. Typically a link will have * one IPv4 address and one or more IPv6 addresses. * - * @return An unmodifiable {@link Collection} of {@link LinkAddress} for this link. + * @return An unmodifiable {@link List} of {@link LinkAddress} for this link. */ - public Collection<LinkAddress> getLinkAddresses() { - return Collections.unmodifiableCollection(mLinkAddresses); + public List<LinkAddress> getLinkAddresses() { + return Collections.unmodifiableList(mLinkAddresses); } /** * Returns all the addresses on this link and all the links stacked above it. * @hide */ - public Collection<LinkAddress> getAllLinkAddresses() { - Collection<LinkAddress> addresses = new ArrayList<LinkAddress>(); + public List<LinkAddress> getAllLinkAddresses() { + List<LinkAddress> addresses = new ArrayList<LinkAddress>(); addresses.addAll(mLinkAddresses); for (LinkProperties stacked: mStackedLinks.values()) { addresses.addAll(stacked.getAllLinkAddresses()); @@ -239,6 +247,7 @@ public class LinkProperties implements Parcelable { * * @param addresses The {@link Collection} of {@link LinkAddress} to set in this * object. + * @hide */ public void setLinkAddresses(Collection<LinkAddress> addresses) { mLinkAddresses.clear(); @@ -250,20 +259,21 @@ public class LinkProperties implements Parcelable { /** * Adds the given {@link InetAddress} to the list of DNS servers. * - * @param dns The {@link InetAddress} to add to the list of DNS servers. + * @param dnsServer The {@link InetAddress} to add to the list of DNS servers. + * @hide */ - public void addDns(InetAddress dns) { - if (dns != null) mDnses.add(dns); + public void addDnsServer(InetAddress dnsServer) { + if (dnsServer != null) mDnses.add(dnsServer); } /** * Returns all the {@link LinkAddress} for DNS servers on this link. * - * @return An umodifiable {@link Collection} of {@link InetAddress} for DNS servers on + * @return An umodifiable {@link List} of {@link InetAddress} for DNS servers on * this link. */ - public Collection<InetAddress> getDnses() { - return Collections.unmodifiableCollection(mDnses); + public List<InetAddress> getDnsServers() { + return Collections.unmodifiableList(mDnses); } /** @@ -271,6 +281,7 @@ public class LinkProperties implements Parcelable { * * @param domains A {@link String} listing in priority order the comma separated * domains to search when resolving host names on this link. + * @hide */ public void setDomains(String domains) { mDomains = domains; @@ -323,6 +334,7 @@ public class LinkProperties implements Parcelable { * proper course is to add either un-named or properly named {@link RouteInfo}. * * @param route A {@link RouteInfo} to add to this object. + * @hide */ public void addRoute(RouteInfo route) { if (route != null) { @@ -339,18 +351,18 @@ public class LinkProperties implements Parcelable { /** * Returns all the {@link RouteInfo} set on this link. * - * @return An unmodifiable {@link Collection} of {@link RouteInfo} for this link. + * @return An unmodifiable {@link List} of {@link RouteInfo} for this link. */ - public Collection<RouteInfo> getRoutes() { - return Collections.unmodifiableCollection(mRoutes); + public List<RouteInfo> getRoutes() { + return Collections.unmodifiableList(mRoutes); } /** * Returns all the routes on this link and all the links stacked above it. * @hide */ - public Collection<RouteInfo> getAllRoutes() { - Collection<RouteInfo> routes = new ArrayList(); + public List<RouteInfo> getAllRoutes() { + List<RouteInfo> routes = new ArrayList(); routes.addAll(mRoutes); for (LinkProperties stacked: mStackedLinks.values()) { routes.addAll(stacked.getAllRoutes()); @@ -364,6 +376,7 @@ public class LinkProperties implements Parcelable { * not enforce it and applications may ignore them. * * @param proxy A {@link ProxyInfo} defining the Http Proxy to use on this link. + * @hide */ public void setHttpProxy(ProxyInfo proxy) { mHttpProxy = proxy; @@ -419,16 +432,17 @@ public class LinkProperties implements Parcelable { * Returns all the links stacked on top of this link. * @hide */ - public Collection<LinkProperties> getStackedLinks() { - Collection<LinkProperties> stacked = new ArrayList<LinkProperties>(); + public List<LinkProperties> getStackedLinks() { + List<LinkProperties> stacked = new ArrayList<LinkProperties>(); for (LinkProperties link : mStackedLinks.values()) { stacked.add(new LinkProperties(link)); } - return Collections.unmodifiableCollection(stacked); + return Collections.unmodifiableList(stacked); } /** * Clears this object to its initial state. + * @hide */ public void clear() { mIfaceName = null; @@ -486,6 +500,7 @@ public class LinkProperties implements Parcelable { * Returns true if this link has an IPv4 address. * * @return {@code true} if there is an IPv4 address, {@code false} otherwise. + * @hide */ public boolean hasIPv4Address() { for (LinkAddress address : mLinkAddresses) { @@ -500,6 +515,7 @@ public class LinkProperties implements Parcelable { * Returns true if this link has an IPv6 address. * * @return {@code true} if there is an IPv6 address, {@code false} otherwise. + * @hide */ public boolean hasIPv6Address() { for (LinkAddress address : mLinkAddresses) { @@ -543,7 +559,7 @@ public class LinkProperties implements Parcelable { * @hide */ public boolean isIdenticalDnses(LinkProperties target) { - Collection<InetAddress> targetDnses = target.getDnses(); + Collection<InetAddress> targetDnses = target.getDnsServers(); String targetDomains = target.getDomains(); if (mDomains == null) { if (targetDomains != null) return false; @@ -696,7 +712,7 @@ public class LinkProperties implements Parcelable { result.removed = new ArrayList<InetAddress>(mDnses); result.added.clear(); if (target != null) { - for (InetAddress newAddress : target.getDnses()) { + for (InetAddress newAddress : target.getDnsServers()) { if (! result.removed.remove(newAddress)) { result.added.add(newAddress); } @@ -831,7 +847,7 @@ public class LinkProperties implements Parcelable { addressCount = in.readInt(); for (int i=0; i<addressCount; i++) { try { - netProp.addDns(InetAddress.getByAddress(in.createByteArray())); + netProp.addDnsServer(InetAddress.getByAddress(in.createByteArray())); } catch (UnknownHostException e) { } } netProp.setDomains(in.readString()); diff --git a/core/java/android/net/ProxyDataTracker.java b/core/java/android/net/ProxyDataTracker.java index 4973b3d..573a8f8 100644 --- a/core/java/android/net/ProxyDataTracker.java +++ b/core/java/android/net/ProxyDataTracker.java @@ -107,8 +107,8 @@ public class ProxyDataTracker extends BaseNetworkStateTracker { mNetworkCapabilities = new NetworkCapabilities(); mNetworkInfo.setIsAvailable(true); try { - mLinkProperties.addDns(InetAddress.getByName(DNS1)); - mLinkProperties.addDns(InetAddress.getByName(DNS2)); + mLinkProperties.addDnsServer(InetAddress.getByName(DNS1)); + mLinkProperties.addDnsServer(InetAddress.getByName(DNS2)); } catch (UnknownHostException e) { Log.e(TAG, "Could not add DNS address", e); } diff --git a/core/java/android/provider/Settings.java b/core/java/android/provider/Settings.java index bd988a6..55c66ba 100644 --- a/core/java/android/provider/Settings.java +++ b/core/java/android/provider/Settings.java @@ -6029,6 +6029,7 @@ public final class Settings { /** * Battery level [1-99] at which low power mode automatically turns on. + * If 0, it will not automatically turn on. * @hide */ public static final String LOW_POWER_MODE_TRIGGER_LEVEL = "low_power_trigger_level"; diff --git a/core/java/android/service/notification/NotificationListenerService.java b/core/java/android/service/notification/NotificationListenerService.java index fd475cd..8bd0f4d 100644 --- a/core/java/android/service/notification/NotificationListenerService.java +++ b/core/java/android/service/notification/NotificationListenerService.java @@ -29,6 +29,7 @@ import android.os.Parcel; import android.os.Parcelable; import android.os.RemoteException; import android.os.ServiceManager; +import android.util.ArrayMap; import android.util.Log; import java.util.List; @@ -54,7 +55,7 @@ public abstract class NotificationListenerService extends Service { + "[" + getClass().getSimpleName() + "]"; private INotificationListenerWrapper mWrapper = null; - private Ranking mRanking; + private RankingMap mRankingMap; private INotificationManager mNoMan; @@ -75,7 +76,43 @@ public abstract class NotificationListenerService extends Service { * object as well as its identifying information (tag and id) and source * (package name). */ - public abstract void onNotificationPosted(StatusBarNotification sbn); + public void onNotificationPosted(StatusBarNotification sbn) { + // optional + } + + /** + * Implement this method to learn about new notifications as they are posted by apps. + * + * @param sbn A data structure encapsulating the original {@link android.app.Notification} + * object as well as its identifying information (tag and id) and source + * (package name). + * @param rankingMap The current ranking map that can be used to retrieve ranking information + * for active notifications, including the newly posted one. + */ + public void onNotificationPosted(StatusBarNotification sbn, RankingMap rankingMap) { + onNotificationPosted(sbn); + } + + /** + * Implement this method to learn when notifications are removed. + * <P> + * This might occur because the user has dismissed the notification using system UI (or another + * notification listener) or because the app has withdrawn the notification. + * <P> + * NOTE: The {@link StatusBarNotification} object you receive will be "light"; that is, the + * result from {@link StatusBarNotification#getNotification} may be missing some heavyweight + * fields such as {@link android.app.Notification#contentView} and + * {@link android.app.Notification#largeIcon}. However, all other fields on + * {@link StatusBarNotification}, sufficient to match this call with a prior call to + * {@link #onNotificationPosted(StatusBarNotification)}, will be intact. + * + * @param sbn A data structure encapsulating at least the original information (tag and id) + * and source (package name) used to post the {@link android.app.Notification} that + * was just removed. + */ + public void onNotificationRemoved(StatusBarNotification sbn) { + // optional + } /** * Implement this method to learn when notifications are removed. @@ -93,8 +130,13 @@ public abstract class NotificationListenerService extends Service { * @param sbn A data structure encapsulating at least the original information (tag and id) * and source (package name) used to post the {@link android.app.Notification} that * was just removed. + * @param rankingMap The current ranking map that can be used to retrieve ranking information + * for active notifications. + * */ - public abstract void onNotificationRemoved(StatusBarNotification sbn); + public void onNotificationRemoved(StatusBarNotification sbn, RankingMap rankingMap) { + onNotificationRemoved(sbn); + } /** * Implement this method to learn about when the listener is enabled and connected to @@ -107,10 +149,11 @@ public abstract class NotificationListenerService extends Service { /** * Implement this method to be notified when the notification ranking changes. - * <P> - * Call {@link #getCurrentRanking()} to retrieve the new ranking. + * + * @param rankingMap The current ranking map that can be used to retrieve ranking information + * for active notifications. */ - public void onNotificationRankingUpdate() { + public void onNotificationRankingUpdate(RankingMap rankingMap) { // optional } @@ -241,16 +284,19 @@ public abstract class NotificationListenerService extends Service { * * <p> * The returned object represents the current ranking snapshot and only - * applies for currently active notifications. Hence you must retrieve a - * new Ranking after each notification event such as - * {@link #onNotificationPosted(StatusBarNotification)}, - * {@link #onNotificationRemoved(StatusBarNotification)}, etc. + * applies for currently active notifications. + * <p> + * Generally you should use the RankingMap that is passed with events such + * as {@link #onNotificationPosted(StatusBarNotification, RankingMap)}, + * {@link #onNotificationRemoved(StatusBarNotification, RankingMap)}, and + * so on. This method should only be used when needing access outside of + * such events, for example to retrieve the RankingMap right after + * initialization. * - * @return A {@link NotificationListenerService.Ranking} object providing - * access to ranking information + * @return A {@link RankingMap} object providing access to ranking information */ - public Ranking getCurrentRanking() { - return mRanking; + public RankingMap getCurrentRanking() { + return mRankingMap; } @Override @@ -313,7 +359,7 @@ public abstract class NotificationListenerService extends Service { synchronized (mWrapper) { applyUpdate(update); try { - NotificationListenerService.this.onNotificationPosted(sbn); + NotificationListenerService.this.onNotificationPosted(sbn, mRankingMap); } catch (Throwable t) { Log.w(TAG, "Error running onNotificationPosted", t); } @@ -326,7 +372,7 @@ public abstract class NotificationListenerService extends Service { synchronized (mWrapper) { applyUpdate(update); try { - NotificationListenerService.this.onNotificationRemoved(sbn); + NotificationListenerService.this.onNotificationRemoved(sbn, mRankingMap); } catch (Throwable t) { Log.w(TAG, "Error running onNotificationRemoved", t); } @@ -351,7 +397,7 @@ public abstract class NotificationListenerService extends Service { synchronized (mWrapper) { applyUpdate(update); try { - NotificationListenerService.this.onNotificationRankingUpdate(); + NotificationListenerService.this.onNotificationRankingUpdate(mRankingMap); } catch (Throwable t) { Log.w(TAG, "Error running onNotificationRankingUpdate", t); } @@ -360,7 +406,65 @@ public abstract class NotificationListenerService extends Service { } private void applyUpdate(NotificationRankingUpdate update) { - mRanking = new Ranking(update); + mRankingMap = new RankingMap(update); + } + + /** + * Provides access to ranking information on a currently active + * notification. + * + * <p> + * Note that this object is not updated on notification events (such as + * {@link #onNotificationPosted(StatusBarNotification, RankingMap)}, + * {@link #onNotificationRemoved(StatusBarNotification)}, etc.). Make sure + * to retrieve a new Ranking from the current {@link RankingMap} whenever + * a notification event occurs. + */ + public static class Ranking { + private final String mKey; + private final int mRank; + private final boolean mIsAmbient; + private final boolean mIsInterceptedByDnd; + + private Ranking(String key, int rank, boolean isAmbient, boolean isInterceptedByDnd) { + mKey = key; + mRank = rank; + mIsAmbient = isAmbient; + mIsInterceptedByDnd = isInterceptedByDnd; + } + + /** + * Returns the key of the notification this Ranking applies to. + */ + public String getKey() { + return mKey; + } + + /** + * Returns the rank of the notification. + * + * @return the rank of the notification, that is the 0-based index in + * the list of active notifications. + */ + public int getRank() { + return mRank; + } + + /** + * Returns whether the notification is an ambient notification, that is + * a notification that doesn't require the user's immediate attention. + */ + public boolean isAmbient() { + return mIsAmbient; + } + + /** + * Returns whether the notification was intercepted by + * "Do not disturb". + */ + public boolean isInterceptedByDoNotDisturb() { + return mIsInterceptedByDnd; + } } /** @@ -371,11 +475,14 @@ public abstract class NotificationListenerService extends Service { * Note that this object represents a ranking snapshot that only applies to * notifications active at the time of retrieval. */ - public static class Ranking implements Parcelable { + public static class RankingMap implements Parcelable { private final NotificationRankingUpdate mRankingUpdate; + private final ArrayMap<String, Ranking> mRankingCache; + private boolean mRankingCacheInitialized; - private Ranking(NotificationRankingUpdate rankingUpdate) { + private RankingMap(NotificationRankingUpdate rankingUpdate) { mRankingUpdate = rankingUpdate; + mRankingCache = new ArrayMap<>(rankingUpdate.getOrderedKeys().length); } /** @@ -389,56 +496,37 @@ public abstract class NotificationListenerService extends Service { } /** - * Returns the rank of the notification with the given key, that is the - * index of <code>key</code> in the array of keys returned by - * {@link #getOrderedKeys()}. + * Returns the Ranking for the notification with the given key. * - * @return The rank of the notification with the given key; -1 when the - * given key is unknown. + * @return the Ranking of the notification with the given key; + * <code>null</code> when the key is unknown. */ - public int getRank(String key) { - // TODO: Optimize. - String[] orderedKeys = mRankingUpdate.getOrderedKeys(); - for (int i = 0; i < orderedKeys.length; i++) { - if (orderedKeys[i].equals(key)) { - return i; + public Ranking getRanking(String key) { + synchronized (mRankingCache) { + if (!mRankingCacheInitialized) { + initializeRankingCache(); + mRankingCacheInitialized = true; } } - return -1; + return mRankingCache.get(key); } - /** - * Returns whether the notification with the given key was intercepted - * by "Do not disturb". - */ - public boolean isInterceptedByDoNotDisturb(String key) { - // TODO: Optimize. - for (String interceptedKey : mRankingUpdate.getDndInterceptedKeys()) { - if (interceptedKey.equals(key)) { - return true; - } - } - return false; - } - - /** - * Returns whether the notification with the given key is an ambient - * notification, that is a notification that doesn't require the user's - * immediate attention. - */ - public boolean isAmbient(String key) { - // TODO: Optimize. - int firstAmbientIndex = mRankingUpdate.getFirstAmbientIndex(); - if (firstAmbientIndex < 0) { - return false; - } + private void initializeRankingCache() { String[] orderedKeys = mRankingUpdate.getOrderedKeys(); - for (int i = firstAmbientIndex; i < orderedKeys.length; i++) { - if (orderedKeys[i].equals(key)) { - return true; + int firstAmbientIndex = mRankingUpdate.getFirstAmbientIndex(); + for (int i = 0; i < orderedKeys.length; i++) { + String key = orderedKeys[i]; + boolean isAmbient = firstAmbientIndex > -1 && firstAmbientIndex <= i; + boolean isInterceptedByDnd = false; + // TODO: Optimize. + for (String s : mRankingUpdate.getDndInterceptedKeys()) { + if (s.equals(key)) { + isInterceptedByDnd = true; + break; + } } + mRankingCache.put(key, new Ranking(key, i, isAmbient, isInterceptedByDnd)); } - return false; } // ----------- Parcelable @@ -453,16 +541,16 @@ public abstract class NotificationListenerService extends Service { dest.writeParcelable(mRankingUpdate, flags); } - public static final Creator<Ranking> CREATOR = new Creator<Ranking>() { + public static final Creator<RankingMap> CREATOR = new Creator<RankingMap>() { @Override - public Ranking createFromParcel(Parcel source) { + public RankingMap createFromParcel(Parcel source) { NotificationRankingUpdate rankingUpdate = source.readParcelable(null); - return new Ranking(rankingUpdate); + return new RankingMap(rankingUpdate); } @Override - public Ranking[] newArray(int size) { - return new Ranking[size]; + public RankingMap[] newArray(int size) { + return new RankingMap[size]; } }; } diff --git a/core/java/android/view/ThreadedRenderer.java b/core/java/android/view/ThreadedRenderer.java index 11db996..72b9d3e 100644 --- a/core/java/android/view/ThreadedRenderer.java +++ b/core/java/android/view/ThreadedRenderer.java @@ -74,7 +74,8 @@ public class ThreadedRenderer extends HardwareRenderer { private boolean mProfilingEnabled; ThreadedRenderer(boolean translucent) { - AtlasInitializer.sInstance.init(); + // Temporarily disabled + //AtlasInitializer.sInstance.init(); long rootNodePtr = nCreateRootRenderNode(); mRootNode = RenderNode.adopt(rootNodePtr); diff --git a/core/java/android/view/accessibility/AccessibilityInteractionClient.java b/core/java/android/view/accessibility/AccessibilityInteractionClient.java index 5b9372d..4748402 100644 --- a/core/java/android/view/accessibility/AccessibilityInteractionClient.java +++ b/core/java/android/view/accessibility/AccessibilityInteractionClient.java @@ -225,17 +225,11 @@ public final class AccessibilityInteractionClient try { IAccessibilityServiceConnection connection = getConnection(connectionId); if (connection != null) { - List<AccessibilityWindowInfo> windows = sAccessibilityCache.getWindows(); - if (windows != null) { - if (DEBUG) { - Log.i(LOG_TAG, "Window cache hit"); - } - return windows; - } - if (DEBUG) { - Log.i(LOG_TAG, "Window cache miss"); - } - windows = connection.getWindows(); + // The system is just sending data for windows that we introspected + // and changed but not ones that appeared, so we have to always call + // into the system process. This is less expensice as opposed to + // sending all windows on every window change. + List<AccessibilityWindowInfo> windows = connection.getWindows(); if (windows != null) { final int windowCount = windows.size(); for (int i = 0; i < windowCount; i++) { |