diff options
Diffstat (limited to 'core/java/android')
49 files changed, 2119 insertions, 1660 deletions
diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java index 23b5f29..f6883e2 100644 --- a/core/java/android/app/Activity.java +++ b/core/java/android/app/Activity.java @@ -5326,7 +5326,8 @@ public class Activity extends ContextThemeWrapper * * @hide */ - void convertToTranslucent(TranslucentConversionListener callback, ActivityOptions options) { + public void convertToTranslucent(TranslucentConversionListener callback, + ActivityOptions options) { boolean drawComplete; try { mTranslucentCallback = callback; @@ -5615,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/ActivityOptions.java b/core/java/android/app/ActivityOptions.java index a057c3e..9160452 100644 --- a/core/java/android/app/ActivityOptions.java +++ b/core/java/android/app/ActivityOptions.java @@ -394,8 +394,18 @@ public class ActivityOptions { if (sharedElements != null) { for (int i = 0; i < sharedElements.length; i++) { Pair<View, String> sharedElement = sharedElements[i]; - names.add(sharedElement.second); - mappedNames.add(sharedElement.first.getViewName()); + String sharedElementName = sharedElement.second; + if (sharedElementName == null) { + throw new IllegalArgumentException("Shared element name must not be null"); + } + String viewName = sharedElement.first.getViewName(); + if (viewName == null) { + throw new IllegalArgumentException("Shared elements must have non-null " + + "viewNames"); + } + + names.add(sharedElementName); + mappedNames.add(viewName); } } diff --git a/core/java/android/app/ActivityTransitionCoordinator.java b/core/java/android/app/ActivityTransitionCoordinator.java index a4384f8..1f3218b 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); @@ -269,6 +279,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) { @@ -335,6 +347,10 @@ abstract class ActivityTransitionCoordinator extends ResultReceiver { String name = mAllSharedElementNames.get(i); View sharedElement = sharedElements.get(name); if (sharedElement != null) { + if (sharedElement.getViewName() == null) { + throw new IllegalArgumentException("Shared elements must have " + + "non-null viewNames"); + } mSharedElementNames.add(name); mSharedElements.add(sharedElement); } 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/ActivityView.java b/core/java/android/app/ActivityView.java index c29d75e..94ea2c5 100644 --- a/core/java/android/app/ActivityView.java +++ b/core/java/android/app/ActivityView.java @@ -354,9 +354,11 @@ public class ActivityView extends ViewGroup { private static class ActivityContainerWrapper { private final IActivityContainer mIActivityContainer; private final CloseGuard mGuard = CloseGuard.get(); + boolean mOpened; // Protected by mGuard. ActivityContainerWrapper(IActivityContainer container) { mIActivityContainer = container; + mOpened = true; mGuard.open("release"); } @@ -424,11 +426,16 @@ public class ActivityView extends ViewGroup { } void release() { - if (DEBUG) Log.v(TAG, "ActivityContainerWrapper: release called"); - try { - mIActivityContainer.release(); - mGuard.close(); - } catch (RemoteException e) { + synchronized (mGuard) { + if (mOpened) { + if (DEBUG) Log.v(TAG, "ActivityContainerWrapper: release called"); + try { + mIActivityContainer.release(); + mGuard.close(); + } catch (RemoteException e) { + } + mOpened = false; + } } } diff --git a/core/java/android/app/ContextImpl.java b/core/java/android/app/ContextImpl.java index ad506e4..52d4585 100644 --- a/core/java/android/app/ContextImpl.java +++ b/core/java/android/app/ContextImpl.java @@ -135,7 +135,7 @@ import android.view.textservice.TextServicesManager; import android.accounts.AccountManager; import android.accounts.IAccountManager; import android.app.admin.DevicePolicyManager; -import android.app.task.ITaskManager; +import android.app.job.IJobScheduler; import android.app.trust.TrustManager; import com.android.internal.annotations.GuardedBy; @@ -706,10 +706,10 @@ class ContextImpl extends Context { return new UsageStatsManager(ctx.getOuterContext()); }}); - registerService(TASK_SERVICE, new ServiceFetcher() { + registerService(JOB_SCHEDULER_SERVICE, new ServiceFetcher() { public Object createService(ContextImpl ctx) { - IBinder b = ServiceManager.getService(TASK_SERVICE); - return new TaskManagerImpl(ITaskManager.Stub.asInterface(b)); + IBinder b = ServiceManager.getService(JOB_SCHEDULER_SERVICE); + return new JobSchedulerImpl(IJobScheduler.Stub.asInterface(b)); }}); } 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/TaskManagerImpl.java b/core/java/android/app/JobSchedulerImpl.java index fe29fb7..09038d5 100644 --- a/core/java/android/app/TaskManagerImpl.java +++ b/core/java/android/app/JobSchedulerImpl.java @@ -17,38 +17,38 @@ // in android.app so ContextImpl has package access package android.app; -import android.app.task.ITaskManager; -import android.app.task.Task; -import android.app.task.TaskManager; +import android.app.job.JobInfo; +import android.app.job.JobScheduler; +import android.app.job.IJobScheduler; import android.os.RemoteException; import java.util.List; /** - * Concrete implementation of the TaskManager interface + * Concrete implementation of the JobScheduler interface * @hide */ -public class TaskManagerImpl extends TaskManager { - ITaskManager mBinder; +public class JobSchedulerImpl extends JobScheduler { + IJobScheduler mBinder; - /* package */ TaskManagerImpl(ITaskManager binder) { + /* package */ JobSchedulerImpl(IJobScheduler binder) { mBinder = binder; } @Override - public int schedule(Task task) { + public int schedule(JobInfo job) { try { - return mBinder.schedule(task); + return mBinder.schedule(job); } catch (RemoteException e) { - return TaskManager.RESULT_FAILURE; + return JobScheduler.RESULT_FAILURE; } } @Override - public void cancel(int taskId) { + public void cancel(int jobId) { try { - mBinder.cancel(taskId); + mBinder.cancel(jobId); } catch (RemoteException e) {} } @@ -62,9 +62,9 @@ public class TaskManagerImpl extends TaskManager { } @Override - public List<Task> getAllPendingTasks() { + public List<JobInfo> getAllPendingJobs() { try { - return mBinder.getAllPendingTasks(); + return mBinder.getAllPendingJobs(); } catch (RemoteException e) { return null; } diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java index a1cdf59..276f936 100644 --- a/core/java/android/app/Notification.java +++ b/core/java/android/app/Notification.java @@ -23,7 +23,6 @@ import android.content.Context; import android.content.Intent; import android.content.res.Resources; import android.graphics.Bitmap; -import android.graphics.BitmapFactory; import android.graphics.Canvas; import android.graphics.PorterDuff; import android.graphics.drawable.Drawable; @@ -31,7 +30,6 @@ import android.media.AudioManager; import android.media.session.MediaSessionToken; import android.net.Uri; import android.os.BadParcelableException; -import android.os.Build; import android.os.Bundle; import android.os.Parcel; import android.os.Parcelable; @@ -2568,7 +2566,7 @@ public class Notification implements Parcelable R.id.icon, true, -1, - mColor, + resolveColor(), PorterDuff.Mode.SRC_ATOP, -1); } @@ -2595,17 +2593,22 @@ public class Notification implements Parcelable R.id.right_icon, true, -1, - mColor, + resolveColor(), PorterDuff.Mode.SRC_ATOP, -1); } } + private int sanitizeColor() { + if (mColor != COLOR_DEFAULT) { + mColor |= 0xFF000000; // no alpha for custom colors + } + return mColor; + } + private int resolveColor() { if (mColor == COLOR_DEFAULT) { - mColor = mContext.getResources().getColor(R.color.notification_icon_bg_color); - } else { - mColor |= 0xFF000000; // no alpha for custom colors + return mContext.getResources().getColor(R.color.notification_icon_bg_color); } return mColor; } @@ -2621,7 +2624,7 @@ public class Notification implements Parcelable n.iconLevel = mSmallIconLevel; n.number = mNumber; - n.color = resolveColor(); + n.color = sanitizeColor(); n.contentView = makeContentView(); n.contentIntent = mContentIntent; 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/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java index 4aa4294..04be028 100644 --- a/core/java/android/app/admin/DevicePolicyManager.java +++ b/core/java/android/app/admin/DevicePolicyManager.java @@ -136,7 +136,7 @@ public class DevicePolicyManager { * @hide */ public static final String ACTION_PROVISIONING_USER_HAS_CONSENTED - = "android.app.action.USER_HAS_CONSENTED"; + = "android.app.action.ACTION_PROVISIONING_USER_HAS_CONSENTED"; /** * A String extra holding the name of the package of the mobile device management application diff --git a/core/java/android/app/task/ITaskCallback.aidl b/core/java/android/app/job/IJobCallback.aidl index d8a32fd..2d3948f 100644 --- a/core/java/android/app/task/ITaskCallback.aidl +++ b/core/java/android/app/job/IJobCallback.aidl @@ -14,43 +14,40 @@ * limitations under the License. */ -package android.app.task; - -import android.app.task.ITaskService; -import android.app.task.TaskParams; +package android.app.job; /** - * The server side of the TaskManager IPC protocols. The app-side implementation + * The server side of the JobScheduler IPC protocols. The app-side implementation * invokes on this interface to indicate completion of the (asynchronous) instructions * issued by the server. * * In all cases, the 'who' parameter is the caller's service binder, used to track - * which Task Service instance is reporting. + * which Job Service instance is reporting. * * {@hide} */ -interface ITaskCallback { +interface IJobCallback { /** * Immediate callback to the system after sending a start signal, used to quickly detect ANR. * - * @param taskId Unique integer used to identify this task. - * @param ongoing True to indicate that the client is processing the task. False if the task is + * @param jobId Unique integer used to identify this job. + * @param ongoing True to indicate that the client is processing the job. False if the job is * complete */ - void acknowledgeStartMessage(int taskId, boolean ongoing); + void acknowledgeStartMessage(int jobId, boolean ongoing); /** * Immediate callback to the system after sending a stop signal, used to quickly detect ANR. * - * @param taskId Unique integer used to identify this task. - * @param rescheulde Whether or not to reschedule this task. + * @param jobId Unique integer used to identify this job. + * @param reschedule Whether or not to reschedule this job. */ - void acknowledgeStopMessage(int taskId, boolean reschedule); + void acknowledgeStopMessage(int jobId, boolean reschedule); /* - * Tell the task manager that the client is done with its execution, so that it can go on to + * Tell the job manager that the client is done with its execution, so that it can go on to * the next one and stop attributing wakelock time to us etc. * - * @param taskId Unique integer used to identify this task. - * @param reschedule Whether or not to reschedule this task. + * @param jobId Unique integer used to identify this job. + * @param reschedule Whether or not to reschedule this job. */ - void taskFinished(int taskId, boolean reschedule); + void jobFinished(int jobId, boolean reschedule); } diff --git a/core/java/android/app/task/ITaskManager.aidl b/core/java/android/app/job/IJobScheduler.aidl index b56c78a..f1258ae 100644 --- a/core/java/android/app/task/ITaskManager.aidl +++ b/core/java/android/app/job/IJobScheduler.aidl @@ -14,17 +14,17 @@ * limitations under the License. */ -package android.app.task; +package android.app.job; -import android.app.task.Task; +import android.app.job.JobInfo; /** - * IPC interface that supports the app-facing {@link #TaskManager} api. + * IPC interface that supports the app-facing {@link #JobScheduler} api. * {@hide} */ -interface ITaskManager { - int schedule(in Task task); - void cancel(int taskId); +interface IJobScheduler { + int schedule(in JobInfo job); + void cancel(int jobId); void cancelAll(); - List<Task> getAllPendingTasks(); + List<JobInfo> getAllPendingJobs(); } diff --git a/core/java/android/app/task/ITaskService.aidl b/core/java/android/app/job/IJobService.aidl index 87b0191..63f8b81 100644 --- a/core/java/android/app/task/ITaskService.aidl +++ b/core/java/android/app/job/IJobService.aidl @@ -14,22 +14,19 @@ * limitations under the License. */ -package android.app.task; +package android.app.job; -import android.app.task.ITaskCallback; -import android.app.task.TaskParams; - -import android.os.Bundle; +import android.app.job.JobParameters; /** * Interface that the framework uses to communicate with application code that implements a - * TaskService. End user code does not implement this interface directly; instead, the app's - * service implementation will extend android.app.task.TaskService. + * JobService. End user code does not implement this interface directly; instead, the app's + * service implementation will extend android.app.job.JobService. * {@hide} */ -oneway interface ITaskService { - /** Begin execution of application's task. */ - void startTask(in TaskParams taskParams); +oneway interface IJobService { + /** Begin execution of application's job. */ + void startJob(in JobParameters jobParams); /** Stop execution of application's task. */ - void stopTask(in TaskParams taskParams); + void stopJob(in JobParameters jobParams); } diff --git a/core/java/android/app/task/Task.aidl b/core/java/android/app/job/JobInfo.aidl index 1f25439..7b198a8 100644 --- a/core/java/android/app/task/Task.aidl +++ b/core/java/android/app/job/JobInfo.aidl @@ -14,7 +14,6 @@ * limitations under the License. */ -package android.app.task; +package android.app.job; -parcelable Task; -
\ No newline at end of file +parcelable JobInfo; diff --git a/core/java/android/app/task/Task.java b/core/java/android/app/job/JobInfo.java index 0e660b3..a22e4cd 100644 --- a/core/java/android/app/task/Task.java +++ b/core/java/android/app/job/JobInfo.java @@ -14,7 +14,7 @@ * limitations under the License */ -package android.app.task; +package android.app.job; import android.content.ComponentName; import android.os.Bundle; @@ -23,22 +23,22 @@ import android.os.Parcelable; import android.os.PersistableBundle; /** - * Container of data passed to the {@link android.app.task.TaskManager} fully encapsulating the + * Container of data passed to the {@link android.app.job.JobScheduler} fully encapsulating the * parameters required to schedule work against the calling application. These are constructed - * using the {@link Task.Builder}. + * using the {@link JobInfo.Builder}. */ -public class Task implements Parcelable { +public class JobInfo implements Parcelable { public interface NetworkType { /** Default. */ public final int NONE = 0; - /** This task requires network connectivity. */ + /** This job requires network connectivity. */ public final int ANY = 1; - /** This task requires network connectivity that is unmetered. */ + /** This job requires network connectivity that is unmetered. */ public final int UNMETERED = 2; } /** - * Amount of backoff a task has initially by default, in milliseconds. + * Amount of backoff a job has initially by default, in milliseconds. * @hide. */ public static final long DEFAULT_INITIAL_BACKOFF_MILLIS = 5000L; @@ -63,7 +63,7 @@ public class Task implements Parcelable { public final int EXPONENTIAL = 1; } - private final int taskId; + private final int jobId; // TODO: Change this to use PersistableBundle when that lands in master. private final PersistableBundle extras; private final ComponentName service; @@ -80,10 +80,10 @@ public class Task implements Parcelable { private final int backoffPolicy; /** - * Unique task id associated with this class. This is assigned to your task by the scheduler. + * Unique job id associated with this class. This is assigned to your job by the scheduler. */ public int getId() { - return taskId; + return jobId; } /** @@ -94,43 +94,43 @@ public class Task implements Parcelable { } /** - * Name of the service endpoint that will be called back into by the TaskManager. + * Name of the service endpoint that will be called back into by the JobScheduler. */ public ComponentName getService() { return service; } /** - * Whether this task needs the device to be plugged in. + * Whether this job needs the device to be plugged in. */ public boolean isRequireCharging() { return requireCharging; } /** - * Whether this task needs the device to be in an Idle maintenance window. + * Whether this job needs the device to be in an Idle maintenance window. */ public boolean isRequireDeviceIdle() { return requireDeviceIdle; } /** - * See {@link android.app.task.Task.NetworkType} for a description of this value. + * See {@link android.app.job.JobInfo.NetworkType} for a description of this value. */ public int getNetworkCapabilities() { return networkCapabilities; } /** - * Set for a task that does not recur periodically, to specify a delay after which the task - * will be eligible for execution. This value is not set if the task recurs periodically. + * Set for a job that does not recur periodically, to specify a delay after which the job + * will be eligible for execution. This value is not set if the job recurs periodically. */ public long getMinLatencyMillis() { return minLatencyMillis; } /** - * See {@link Builder#setOverrideDeadline(long)}. This value is not set if the task recurs + * See {@link Builder#setOverrideDeadline(long)}. This value is not set if the job recurs * periodically. */ public long getMaxExecutionDelayMillis() { @@ -138,23 +138,23 @@ public class Task implements Parcelable { } /** - * Track whether this task will repeat with a given period. + * Track whether this job will repeat with a given period. */ public boolean isPeriodic() { return isPeriodic; } /** - * Set to the interval between occurrences of this task. This value is <b>not</b> set if the - * task does not recur periodically. + * Set to the interval between occurrences of this job. This value is <b>not</b> set if the + * job does not recur periodically. */ public long getIntervalMillis() { return intervalMillis; } /** - * The amount of time the TaskManager will wait before rescheduling a failed task. This value - * will be increased depending on the backoff policy specified at task creation time. Defaults + * The amount of time the JobScheduler will wait before rescheduling a failed job. This value + * will be increased depending on the backoff policy specified at job creation time. Defaults * to 5 seconds. */ public long getInitialBackoffMillis() { @@ -162,7 +162,7 @@ public class Task implements Parcelable { } /** - * See {@link android.app.task.Task.BackoffPolicy} for an explanation of the values this field + * See {@link android.app.job.JobInfo.BackoffPolicy} for an explanation of the values this field * can take. This defaults to exponential. */ public int getBackoffPolicy() { @@ -187,8 +187,8 @@ public class Task implements Parcelable { return hasLateConstraint; } - private Task(Parcel in) { - taskId = in.readInt(); + private JobInfo(Parcel in) { + jobId = in.readInt(); extras = in.readPersistableBundle(); service = in.readParcelable(null); requireCharging = in.readInt() == 1; @@ -204,10 +204,10 @@ public class Task implements Parcelable { hasLateConstraint = in.readInt() == 1; } - private Task(Task.Builder b) { - taskId = b.mTaskId; + private JobInfo(JobInfo.Builder b) { + jobId = b.mJobId; extras = b.mExtras; - service = b.mTaskService; + service = b.mJobService; requireCharging = b.mRequiresCharging; requireDeviceIdle = b.mRequiresDeviceIdle; networkCapabilities = b.mNetworkCapabilities; @@ -228,7 +228,7 @@ public class Task implements Parcelable { @Override public void writeToParcel(Parcel out, int flags) { - out.writeInt(taskId); + out.writeInt(jobId); out.writePersistableBundle(extras); out.writeParcelable(service, flags); out.writeInt(requireCharging ? 1 : 0); @@ -244,23 +244,23 @@ public class Task implements Parcelable { out.writeInt(hasLateConstraint ? 1 : 0); } - public static final Creator<Task> CREATOR = new Creator<Task>() { + public static final Creator<JobInfo> CREATOR = new Creator<JobInfo>() { @Override - public Task createFromParcel(Parcel in) { - return new Task(in); + public JobInfo createFromParcel(Parcel in) { + return new JobInfo(in); } @Override - public Task[] newArray(int size) { - return new Task[size]; + public JobInfo[] newArray(int size) { + return new JobInfo[size]; } }; - /** Builder class for constructing {@link Task} objects. */ + /** Builder class for constructing {@link JobInfo} objects. */ public static final class Builder { - private int mTaskId; + private int mJobId; private PersistableBundle mExtras = PersistableBundle.EMPTY; - private ComponentName mTaskService; + private ComponentName mJobService; // Requirements. private boolean mRequiresCharging; private boolean mRequiresDeviceIdle; @@ -280,15 +280,15 @@ public class Task implements Parcelable { private boolean mBackoffPolicySet = false; /** - * @param taskId Application-provided id for this task. Subsequent calls to cancel, or - * tasks created with the same taskId, will update the pre-existing task with + * @param jobId Application-provided id for this job. Subsequent calls to cancel, or + * jobs created with the same jobId, will update the pre-existing job with * the same id. - * @param taskService The endpoint that you implement that will receive the callback from the - * TaskManager. + * @param jobService The endpoint that you implement that will receive the callback from the + * JobScheduler. */ - public Builder(int taskId, ComponentName taskService) { - mTaskService = taskService; - mTaskId = taskId; + public Builder(int jobId, ComponentName jobService) { + mJobService = jobService; + mJobId = jobId; } /** @@ -302,10 +302,10 @@ public class Task implements Parcelable { /** * Set some description of the kind of network capabilities you would like to have. This - * will be a parameter defined in {@link android.app.task.Task.NetworkType}. + * will be a parameter defined in {@link android.app.job.JobInfo.NetworkType}. * Not calling this function means the network is not necessary. * Bear in mind that calling this function defines network as a strict requirement for your - * task if the network requested is not available your task will never run. See + * job if the network requested is not available your job will never run. See * {@link #setOverrideDeadline(long)} to change this behaviour. */ public Builder setRequiredNetworkCapabilities(int networkCapabilities) { @@ -313,10 +313,10 @@ public class Task implements Parcelable { return this; } - /* - * Specify that to run this task, the device needs to be plugged in. This defaults to + /** + * Specify that to run this job, the device needs to be plugged in. This defaults to * false. - * @param requireCharging Whether or not the device is plugged in. + * @param requiresCharging Whether or not the device is plugged in. */ public Builder setRequiresCharging(boolean requiresCharging) { mRequiresCharging = requiresCharging; @@ -324,11 +324,11 @@ public class Task implements Parcelable { } /** - * Specify that to run, the task needs the device to be in idle mode. This defaults to + * Specify that to run, the job needs the device to be in idle mode. This defaults to * false. * <p>Idle mode is a loose definition provided by the system, which means that the device * is not in use, and has not been in use for some time. As such, it is a good time to - * perform resource heavy tasks. Bear in mind that battery usage will still be attributed + * perform resource heavy jobs. Bear in mind that battery usage will still be attributed * to your application, and surfaced to the user in battery stats.</p> * @param requiresDeviceIdle Whether or not the device need be within an idle maintenance * window. @@ -339,17 +339,17 @@ public class Task implements Parcelable { } /** - * Specify that this task should recur with the provided interval, not more than once per - * period. You have no control over when within this interval this task will be executed, + * Specify that this job should recur with the provided interval, not more than once per + * period. You have no control over when within this interval this job will be executed, * only the guarantee that it will be executed at most once within this interval. - * A periodic task will be repeated until the phone is turned off, however it will only be + * A periodic job will be repeated until the phone is turned off, however it will only be * persisted beyond boot if the client app has declared the * {@link android.Manifest.permission#RECEIVE_BOOT_COMPLETED} permission. You can schedule - * periodic tasks without this permission, they simply will cease to exist after the phone + * periodic jobs without this permission, they simply will cease to exist after the phone * restarts. * Setting this function on the builder with {@link #setMinimumLatency(long)} or * {@link #setOverrideDeadline(long)} will result in an error. - * @param intervalMillis Millisecond interval for which this task will repeat. + * @param intervalMillis Millisecond interval for which this job will repeat. */ public Builder setPeriodic(long intervalMillis) { mIsPeriodic = true; @@ -359,11 +359,11 @@ public class Task implements Parcelable { } /** - * Specify that this task should be delayed by the provided amount of time. - * Because it doesn't make sense setting this property on a periodic task, doing so will + * Specify that this job should be delayed by the provided amount of time. + * Because it doesn't make sense setting this property on a periodic job, doing so will * throw an {@link java.lang.IllegalArgumentException} when - * {@link android.app.task.Task.Builder#build()} is called. - * @param minLatencyMillis Milliseconds before which this task will not be considered for + * {@link android.app.job.JobInfo.Builder#build()} is called. + * @param minLatencyMillis Milliseconds before which this job will not be considered for * execution. */ public Builder setMinimumLatency(long minLatencyMillis) { @@ -373,11 +373,11 @@ public class Task implements Parcelable { } /** - * Set deadline which is the maximum scheduling latency. The task will be run by this + * Set deadline which is the maximum scheduling latency. The job will be run by this * deadline even if other requirements are not met. Because it doesn't make sense setting - * this property on a periodic task, doing so will throw an + * this property on a periodic job, doing so will throw an * {@link java.lang.IllegalArgumentException} when - * {@link android.app.task.Task.Builder#build()} is called. + * {@link android.app.job.JobInfo.Builder#build()} is called. */ public Builder setOverrideDeadline(long maxExecutionDelayMillis) { mMaxExecutionDelayMillis = maxExecutionDelayMillis; @@ -389,13 +389,13 @@ public class Task implements Parcelable { * Set up the back-off/retry policy. * This defaults to some respectable values: {5 seconds, Exponential}. We cap back-off at * 1hr. - * Note that trying to set a backoff criteria for a task with + * Note that trying to set a backoff criteria for a job with * {@link #setRequiresDeviceIdle(boolean)} will throw an exception when you call build(). - * This is because back-off typically does not make sense for these types of tasks. See - * {@link android.app.task.TaskService#taskFinished(android.app.task.TaskParams, boolean)} - * for more description of the return value for the case of a task executing while in idle + * This is because back-off typically does not make sense for these types of jobs. See + * {@link android.app.job.JobService#jobFinished(android.app.job.JobParameters, boolean)} + * for more description of the return value for the case of a job executing while in idle * mode. - * @param initialBackoffMillis Millisecond time interval to wait initially when task has + * @param initialBackoffMillis Millisecond time interval to wait initially when job has * failed. * @param backoffPolicy is one of {@link BackoffPolicy} */ @@ -407,25 +407,25 @@ public class Task implements Parcelable { } /** - * @return The task object to hand to the TaskManager. This object is immutable. + * @return The job object to hand to the JobScheduler. This object is immutable. */ - public Task build() { + public JobInfo build() { mExtras = new PersistableBundle(mExtras); // Make our own copy. - // Check that a deadline was not set on a periodic task. + // Check that a deadline was not set on a periodic job. if (mIsPeriodic && (mMaxExecutionDelayMillis != 0L)) { throw new IllegalArgumentException("Can't call setOverrideDeadline() on a " + - "periodic task."); + "periodic job."); } if (mIsPeriodic && (mMinLatencyMillis != 0L)) { throw new IllegalArgumentException("Can't call setMinimumLatency() on a " + - "periodic task"); + "periodic job"); } if (mBackoffPolicySet && mRequiresDeviceIdle) { - throw new IllegalArgumentException("An idle mode task will not respect any" + + throw new IllegalArgumentException("An idle mode job will not respect any" + " back-off policy, so calling setBackoffCriteria with" + " setRequiresDeviceIdle is an error."); } - return new Task(this); + return new JobInfo(this); } } diff --git a/core/java/android/app/task/TaskParams.aidl b/core/java/android/app/job/JobParameters.aidl index 9b25855..e7551b9 100644 --- a/core/java/android/app/task/TaskParams.aidl +++ b/core/java/android/app/job/JobParameters.aidl @@ -14,6 +14,6 @@ * limitations under the License. */ -package android.app.task; +package android.app.job; -parcelable TaskParams;
\ No newline at end of file +parcelable JobParameters; diff --git a/core/java/android/app/task/TaskParams.java b/core/java/android/app/job/JobParameters.java index f4908c6..724856a 100644 --- a/core/java/android/app/task/TaskParams.java +++ b/core/java/android/app/job/JobParameters.java @@ -14,40 +14,42 @@ * limitations under the License */ -package android.app.task; +package android.app.job; +import android.app.job.IJobCallback; +import android.app.job.IJobCallback.Stub; import android.os.IBinder; import android.os.Parcel; import android.os.Parcelable; import android.os.PersistableBundle; /** - * Contains the parameters used to configure/identify your task. You do not create this object + * Contains the parameters used to configure/identify your job. You do not create this object * yourself, instead it is handed in to your application by the System. */ -public class TaskParams implements Parcelable { +public class JobParameters implements Parcelable { - private final int taskId; + private final int jobId; private final PersistableBundle extras; private final IBinder callback; /** @hide */ - public TaskParams(int taskId, PersistableBundle extras, IBinder callback) { - this.taskId = taskId; + public JobParameters(int jobId, PersistableBundle extras, IBinder callback) { + this.jobId = jobId; this.extras = extras; this.callback = callback; } /** - * @return The unique id of this task, specified at creation time. + * @return The unique id of this job, specified at creation time. */ - public int getTaskId() { - return taskId; + public int getJobId() { + return jobId; } /** - * @return The extras you passed in when constructing this task with - * {@link android.app.task.Task.Builder#setExtras(android.os.PersistableBundle)}. This will + * @return The extras you passed in when constructing this job with + * {@link android.app.job.JobInfo.Builder#setExtras(android.os.PersistableBundle)}. This will * never be null. If you did not set any extras this will be an empty bundle. */ public PersistableBundle getExtras() { @@ -55,12 +57,12 @@ public class TaskParams implements Parcelable { } /** @hide */ - public ITaskCallback getCallback() { - return ITaskCallback.Stub.asInterface(callback); + public IJobCallback getCallback() { + return IJobCallback.Stub.asInterface(callback); } - private TaskParams(Parcel in) { - taskId = in.readInt(); + private JobParameters(Parcel in) { + jobId = in.readInt(); extras = in.readPersistableBundle(); callback = in.readStrongBinder(); } @@ -72,20 +74,20 @@ public class TaskParams implements Parcelable { @Override public void writeToParcel(Parcel dest, int flags) { - dest.writeInt(taskId); + dest.writeInt(jobId); dest.writePersistableBundle(extras); dest.writeStrongBinder(callback); } - public static final Creator<TaskParams> CREATOR = new Creator<TaskParams>() { + public static final Creator<JobParameters> CREATOR = new Creator<JobParameters>() { @Override - public TaskParams createFromParcel(Parcel in) { - return new TaskParams(in); + public JobParameters createFromParcel(Parcel in) { + return new JobParameters(in); } @Override - public TaskParams[] newArray(int size) { - return new TaskParams[size]; + public JobParameters[] newArray(int size) { + return new JobParameters[size]; } }; } diff --git a/core/java/android/app/job/JobScheduler.java b/core/java/android/app/job/JobScheduler.java new file mode 100644 index 0000000..7fe192c --- /dev/null +++ b/core/java/android/app/job/JobScheduler.java @@ -0,0 +1,72 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ + +package android.app.job; + +import java.util.List; + +import android.content.Context; + +/** + * Class for scheduling various types of jobs with the scheduling framework on the device. + * + * <p>You do not + * instantiate this class directly; instead, retrieve it through + * {@link android.content.Context#getSystemService + * Context.getSystemService(Context.JOB_SCHEDULER_SERVICE)}. + */ +public abstract class JobScheduler { + /** + * Returned from {@link #schedule(JobInfo)} when an invalid parameter was supplied. This can occur + * if the run-time for your job is too short, or perhaps the system can't resolve the + * requisite {@link JobService} in your package. + */ + public static final int RESULT_FAILURE = 0; + /** + * Returned from {@link #schedule(JobInfo)} if this application has made too many requests for + * work over too short a time. + */ + // TODO: Determine if this is necessary. + public static final int RESULT_SUCCESS = 1; + + /** + * @param job The job you wish scheduled. See + * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs + * you can schedule. + * @return If >0, this int returns the jobId of the successfully scheduled job. + * Otherwise you have to compare the return value to the error codes defined in this class. + */ + public abstract int schedule(JobInfo job); + + /** + * Cancel a job that is pending in the JobScheduler. + * @param jobId unique identifier for this job. Obtain this value from the jobs returned by + * {@link #getAllPendingJobs()}. + * @return + */ + public abstract void cancel(int jobId); + + /** + * Cancel all jobs that have been registered with the JobScheduler by this package. + */ + public abstract void cancelAll(); + + /** + * @return a list of all the jobs registered by this package that have not yet been executed. + */ + public abstract List<JobInfo> getAllPendingJobs(); + +} diff --git a/core/java/android/app/task/TaskService.java b/core/java/android/app/job/JobService.java index 8ce4484..eea0268 100644 --- a/core/java/android/app/task/TaskService.java +++ b/core/java/android/app/job/JobService.java @@ -14,9 +14,12 @@ * limitations under the License */ -package android.app.task; +package android.app.job; import android.app.Service; +import android.app.job.IJobCallback; +import android.app.job.IJobService; +import android.app.job.IJobService.Stub; import android.content.Intent; import android.os.Handler; import android.os.IBinder; @@ -28,72 +31,72 @@ import android.util.Log; import com.android.internal.annotations.GuardedBy; /** - * <p>Entry point for the callback from the {@link android.app.task.TaskManager}.</p> + * <p>Entry point for the callback from the {@link android.app.job.JobScheduler}.</p> * <p>This is the base class that handles asynchronous requests that were previously scheduled. You - * are responsible for overriding {@link TaskService#onStartTask(TaskParams)}, which is where - * you will implement your task logic.</p> - * <p>This service executes each incoming task on a {@link android.os.Handler} running on your + * are responsible for overriding {@link JobService#onStartJob(JobParameters)}, which is where + * you will implement your job logic.</p> + * <p>This service executes each incoming job on a {@link android.os.Handler} running on your * application's main thread. This means that you <b>must</b> offload your execution logic to * another thread/handler/{@link android.os.AsyncTask} of your choosing. Not doing so will result - * in blocking any future callbacks from the TaskManager - specifically - * {@link #onStopTask(android.app.task.TaskParams)}, which is meant to inform you that the + * in blocking any future callbacks from the JobManager - specifically + * {@link #onStopJob(android.app.job.JobParameters)}, which is meant to inform you that the * scheduling requirements are no longer being met.</p> */ -public abstract class TaskService extends Service { - private static final String TAG = "TaskService"; +public abstract class JobService extends Service { + private static final String TAG = "JobService"; /** - * Task services must be protected with this permission: + * Job services must be protected with this permission: * * <pre class="prettyprint"> - * <service android:name="MyTaskService" - * android:permission="android.permission.BIND_TASK_SERVICE" > + * <service android:name="MyJobService" + * android:permission="android.permission.BIND_JOB_SERVICE" > * ... * </service> * </pre> * - * <p>If a task service is declared in the manifest but not protected with this + * <p>If a job service is declared in the manifest but not protected with this * permission, that service will be ignored by the OS. */ public static final String PERMISSION_BIND = - "android.permission.BIND_TASK_SERVICE"; + "android.permission.BIND_JOB_SERVICE"; /** * Identifier for a message that will result in a call to - * {@link #onStartTask(android.app.task.TaskParams)}. + * {@link #onStartJob(android.app.job.JobParameters)}. */ - private final int MSG_EXECUTE_TASK = 0; + private final int MSG_EXECUTE_JOB = 0; /** - * Message that will result in a call to {@link #onStopTask(android.app.task.TaskParams)}. + * Message that will result in a call to {@link #onStopJob(android.app.job.JobParameters)}. */ - private final int MSG_STOP_TASK = 1; + private final int MSG_STOP_JOB = 1; /** - * Message that the client has completed execution of this task. + * Message that the client has completed execution of this job. */ - private final int MSG_TASK_FINISHED = 2; + private final int MSG_JOB_FINISHED = 2; /** Lock object for {@link #mHandler}. */ private final Object mHandlerLock = new Object(); /** - * Handler we post tasks to. Responsible for calling into the client logic, and handling the + * Handler we post jobs to. Responsible for calling into the client logic, and handling the * callback to the system. */ @GuardedBy("mHandlerLock") - TaskHandler mHandler; + JobHandler mHandler; /** Binder for this service. */ - ITaskService mBinder = new ITaskService.Stub() { + IJobService mBinder = new IJobService.Stub() { @Override - public void startTask(TaskParams taskParams) { + public void startJob(JobParameters jobParams) { ensureHandler(); - Message m = Message.obtain(mHandler, MSG_EXECUTE_TASK, taskParams); + Message m = Message.obtain(mHandler, MSG_EXECUTE_JOB, jobParams); m.sendToTarget(); } @Override - public void stopTask(TaskParams taskParams) { + public void stopJob(JobParameters jobParams) { ensureHandler(); - Message m = Message.obtain(mHandler, MSG_STOP_TASK, taskParams); + Message m = Message.obtain(mHandler, MSG_STOP_JOB, jobParams); m.sendToTarget(); } }; @@ -102,7 +105,7 @@ public abstract class TaskService extends Service { void ensureHandler() { synchronized (mHandlerLock) { if (mHandler == null) { - mHandler = new TaskHandler(getMainLooper()); + mHandler = new JobHandler(getMainLooper()); } } } @@ -112,45 +115,45 @@ public abstract class TaskService extends Service { * (app-specified) mechanism. * @hide */ - class TaskHandler extends Handler { - TaskHandler(Looper looper) { + class JobHandler extends Handler { + JobHandler(Looper looper) { super(looper); } @Override public void handleMessage(Message msg) { - final TaskParams params = (TaskParams) msg.obj; + final JobParameters params = (JobParameters) msg.obj; switch (msg.what) { - case MSG_EXECUTE_TASK: + case MSG_EXECUTE_JOB: try { - boolean workOngoing = TaskService.this.onStartTask(params); + boolean workOngoing = JobService.this.onStartJob(params); ackStartMessage(params, workOngoing); } catch (Exception e) { - Log.e(TAG, "Error while executing task: " + params.getTaskId()); + Log.e(TAG, "Error while executing job: " + params.getJobId()); throw new RuntimeException(e); } break; - case MSG_STOP_TASK: + case MSG_STOP_JOB: try { - boolean ret = TaskService.this.onStopTask(params); + boolean ret = JobService.this.onStopJob(params); ackStopMessage(params, ret); } catch (Exception e) { - Log.e(TAG, "Application unable to handle onStopTask.", e); + Log.e(TAG, "Application unable to handle onStopJob.", e); throw new RuntimeException(e); } break; - case MSG_TASK_FINISHED: + case MSG_JOB_FINISHED: final boolean needsReschedule = (msg.arg2 == 1); - ITaskCallback callback = params.getCallback(); + IJobCallback callback = params.getCallback(); if (callback != null) { try { - callback.taskFinished(params.getTaskId(), needsReschedule); + callback.jobFinished(params.getJobId(), needsReschedule); } catch (RemoteException e) { - Log.e(TAG, "Error reporting task finish to system: binder has gone" + + Log.e(TAG, "Error reporting job finish to system: binder has gone" + "away."); } } else { - Log.e(TAG, "finishTask() called for a nonexistent task id."); + Log.e(TAG, "finishJob() called for a nonexistent job id."); } break; default: @@ -159,34 +162,34 @@ public abstract class TaskService extends Service { } } - private void ackStartMessage(TaskParams params, boolean workOngoing) { - final ITaskCallback callback = params.getCallback(); - final int taskId = params.getTaskId(); + private void ackStartMessage(JobParameters params, boolean workOngoing) { + final IJobCallback callback = params.getCallback(); + final int jobId = params.getJobId(); if (callback != null) { try { - callback.acknowledgeStartMessage(taskId, workOngoing); + callback.acknowledgeStartMessage(jobId, workOngoing); } catch(RemoteException e) { - Log.e(TAG, "System unreachable for starting task."); + Log.e(TAG, "System unreachable for starting job."); } } else { if (Log.isLoggable(TAG, Log.DEBUG)) { - Log.d(TAG, "Attempting to ack a task that has already been processed."); + Log.d(TAG, "Attempting to ack a job that has already been processed."); } } } - private void ackStopMessage(TaskParams params, boolean reschedule) { - final ITaskCallback callback = params.getCallback(); - final int taskId = params.getTaskId(); + private void ackStopMessage(JobParameters params, boolean reschedule) { + final IJobCallback callback = params.getCallback(); + final int jobId = params.getJobId(); if (callback != null) { try { - callback.acknowledgeStopMessage(taskId, reschedule); + callback.acknowledgeStopMessage(jobId, reschedule); } catch(RemoteException e) { - Log.e(TAG, "System unreachable for stopping task."); + Log.e(TAG, "System unreachable for stopping job."); } } else { if (Log.isLoggable(TAG, Log.DEBUG)) { - Log.d(TAG, "Attempting to ack a task that has already been processed."); + Log.d(TAG, "Attempting to ack a job that has already been processed."); } } } @@ -198,59 +201,59 @@ public abstract class TaskService extends Service { } /** - * Override this method with the callback logic for your task. Any such logic needs to be + * Override this method with the callback logic for your job. Any such logic needs to be * performed on a separate thread, as this function is executed on your application's main * thread. * - * @param params Parameters specifying info about this task, including the extras bundle you - * optionally provided at task-creation time. + * @param params Parameters specifying info about this job, including the extras bundle you + * optionally provided at job-creation time. * @return True if your service needs to process the work (on a separate thread). False if - * there's no more work to be done for this task. + * there's no more work to be done for this job. */ - public abstract boolean onStartTask(TaskParams params); + public abstract boolean onStartJob(JobParameters params); /** - * This method is called if the system has determined that you must stop execution of your task - * even before you've had a chance to call {@link #taskFinished(TaskParams, boolean)}. + * This method is called if the system has determined that you must stop execution of your job + * even before you've had a chance to call {@link #jobFinished(JobParameters, boolean)}. * * <p>This will happen if the requirements specified at schedule time are no longer met. For * example you may have requested WiFi with - * {@link android.app.task.Task.Builder#setRequiredNetworkCapabilities(int)}, yet while your - * task was executing the user toggled WiFi. Another example is if you had specified - * {@link android.app.task.Task.Builder#setRequiresDeviceIdle(boolean)}, and the phone left its + * {@link android.app.job.JobInfo.Builder#setRequiredNetworkCapabilities(int)}, yet while your + * job was executing the user toggled WiFi. Another example is if you had specified + * {@link android.app.job.JobInfo.Builder#setRequiresDeviceIdle(boolean)}, and the phone left its * idle maintenance window. You are solely responsible for the behaviour of your application * upon receipt of this message; your app will likely start to misbehave if you ignore it. One * immediate repercussion is that the system will cease holding a wakelock for you.</p> * - * @param params Parameters specifying info about this task. - * @return True to indicate to the TaskManager whether you'd like to reschedule this task based - * on the retry criteria provided at task creation-time. False to drop the task. Regardless of - * the value returned, your task must stop executing. + * @param params Parameters specifying info about this job. + * @return True to indicate to the JobManager whether you'd like to reschedule this job based + * on the retry criteria provided at job creation-time. False to drop the job. Regardless of + * the value returned, your job must stop executing. */ - public abstract boolean onStopTask(TaskParams params); + public abstract boolean onStopJob(JobParameters params); /** - * Callback to inform the TaskManager you've finished executing. This can be called from any + * Callback to inform the JobManager you've finished executing. This can be called from any * thread, as it will ultimately be run on your application's main thread. When the system * receives this message it will release the wakelock being held. * <p> * You can specify post-execution behaviour to the scheduler here with - * <code>needsReschedule </code>. This will apply a back-off timer to your task based on + * <code>needsReschedule </code>. This will apply a back-off timer to your job based on * the default, or what was set with - * {@link android.app.task.Task.Builder#setBackoffCriteria(long, int)}. The original - * requirements are always honoured even for a backed-off task. Note that a task running in - * idle mode will not be backed-off. Instead what will happen is the task will be re-added + * {@link android.app.job.JobInfo.Builder#setBackoffCriteria(long, int)}. The original + * requirements are always honoured even for a backed-off job. Note that a job running in + * idle mode will not be backed-off. Instead what will happen is the job will be re-added * to the queue and re-executed within a future idle maintenance window. * </p> * - * @param params Parameters specifying system-provided info about this task, this was given to - * your application in {@link #onStartTask(TaskParams)}. - * @param needsReschedule True if this task is complete, false if you want the TaskManager to + * @param params Parameters specifying system-provided info about this job, this was given to + * your application in {@link #onStartJob(JobParameters)}. + * @param needsReschedule True if this job is complete, false if you want the JobManager to * reschedule you. */ - public final void taskFinished(TaskParams params, boolean needsReschedule) { + public final void jobFinished(JobParameters params, boolean needsReschedule) { ensureHandler(); - Message m = Message.obtain(mHandler, MSG_TASK_FINISHED, params); + Message m = Message.obtain(mHandler, MSG_JOB_FINISHED, params); m.arg2 = needsReschedule ? 1 : 0; m.sendToTarget(); } 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/app/task/TaskManager.java b/core/java/android/app/task/TaskManager.java deleted file mode 100644 index 00f57da..0000000 --- a/core/java/android/app/task/TaskManager.java +++ /dev/null @@ -1,72 +0,0 @@ -/* - * Copyright (C) 2014 The Android Open Source Project - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License - */ - -package android.app.task; - -import java.util.List; - -import android.content.Context; - -/** - * Class for scheduling various types of tasks with the scheduling framework on the device. - * - * <p>You do not - * instantiate this class directly; instead, retrieve it through - * {@link android.content.Context#getSystemService - * Context.getSystemService(Context.TASK_SERVICE)}. - */ -public abstract class TaskManager { - /* - * Returned from {@link #schedule(Task)} when an invalid parameter was supplied. This can occur - * if the run-time for your task is too short, or perhaps the system can't resolve the - * requisite {@link TaskService} in your package. - */ - public static final int RESULT_FAILURE = 0; - /** - * Returned from {@link #schedule(Task)} if this application has made too many requests for - * work over too short a time. - */ - // TODO: Determine if this is necessary. - public static final int RESULT_SUCCESS = 1; - - /** - * @param task The task you wish scheduled. See - * {@link android.app.task.Task.Builder Task.Builder} for more detail on the sorts of tasks - * you can schedule. - * @return If >0, this int returns the taskId of the successfully scheduled task. - * Otherwise you have to compare the return value to the error codes defined in this class. - */ - public abstract int schedule(Task task); - - /** - * Cancel a task that is pending in the TaskManager. - * @param taskId unique identifier for this task. Obtain this value from the tasks returned by - * {@link #getAllPendingTasks()}. - * @return - */ - public abstract void cancel(int taskId); - - /** - * Cancel all tasks that have been registered with the TaskManager by this package. - */ - public abstract void cancelAll(); - - /** - * @return a list of all the tasks registered by this package that have not yet been executed. - */ - public abstract List<Task> getAllPendingTasks(); - -} diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java index 2897887..ccf8451 100644 --- a/core/java/android/content/Context.java +++ b/core/java/android/content/Context.java @@ -2059,7 +2059,7 @@ public abstract class Context { PRINT_SERVICE, MEDIA_SESSION_SERVICE, BATTERY_SERVICE, - TASK_SERVICE, + JOB_SCHEDULER_SERVICE, }) @Retention(RetentionPolicy.SOURCE) public @interface ServiceName {} @@ -2116,8 +2116,8 @@ public abstract class Context { * <dd> A {@link android.app.DownloadManager} for requesting HTTP downloads * <dt> {@link #BATTERY_SERVICE} ("batterymanager") * <dd> A {@link android.os.BatteryManager} for managing battery state - * <dt> {@link #TASK_SERVICE} ("taskmanager") - * <dd> A {@link android.app.task.TaskManager} for managing scheduled tasks + * <dt> {@link #JOB_SCHEDULER_SERVICE} ("taskmanager") + * <dd> A {@link android.app.job.JobScheduler} for managing scheduled tasks * </dl> * * <p>Note: System services obtained via this API may be closely associated with @@ -2171,8 +2171,8 @@ public abstract class Context { * @see android.app.DownloadManager * @see #BATTERY_SERVICE * @see android.os.BatteryManager - * @see #TASK_SERVICE - * @see android.app.task.TaskManager + * @see #JOB_SCHEDULER_SERVICE + * @see android.app.job.JobScheduler */ public abstract Object getSystemService(@ServiceName @NonNull String name); @@ -2769,12 +2769,12 @@ public abstract class Context { /** * Use with {@link #getSystemService} to retrieve a {@link - * android.app.task.TaskManager} instance for managing occasional + * android.app.job.JobScheduler} instance for managing occasional * background tasks. * @see #getSystemService - * @see android.app.task.TaskManager + * @see android.app.job.JobScheduler */ - public static final String TASK_SERVICE = "task"; + public static final String JOB_SCHEDULER_SERVICE = "jobscheduler"; /** * Determine whether the given permission is allowed for a particular diff --git a/core/java/android/hardware/camera2/CameraCaptureSession.java b/core/java/android/hardware/camera2/CameraCaptureSession.java index 5fd0f9b..d98bdc2 100644 --- a/core/java/android/hardware/camera2/CameraCaptureSession.java +++ b/core/java/android/hardware/camera2/CameraCaptureSession.java @@ -29,19 +29,19 @@ import java.util.List; * * <p>Creating a session is an expensive operation and can take several hundred milliseconds, since * it requires configuring the camera device's internal pipelines and allocating memory buffers for - * sending images to the desired targets. While - * {@link CameraDevice#createCaptureSession createCaptureSession} will provide a - * CameraCaptureSession object immediately, configuration won't be complete until the - * {@link CameraCaptureSession.StateListener#onConfigured onConfigured} callback is called for the - * first time. If configuration cannot be completed, then the + * sending images to the desired targets. Therefore the setup is done asynchronously, and + * {@link CameraDevice#createCaptureSession createCaptureSession} will send the ready-to-use + * CameraCaptureSession to the provided listener's + * {@link CameraCaptureSession.StateListener#onConfigured onConfigured} callback. If configuration + * cannot be completed, then the * {@link CameraCaptureSession.StateListener#onConfigureFailed onConfigureFailed} is called, and the * session will not become active.</p> - * + *<!-- * <p>Any capture requests (repeating or non-repeating) submitted before the session is ready will * be queued up and will begin capture once the session becomes ready. In case the session cannot be * configured and {@link StateListener#onConfigureFailed onConfigureFailed} is called, all queued * capture requests are discarded.</p> - * + *--> * <p>If a new session is created by the camera device, then the previous session is closed, and its * associated {@link StateListener#onClosed onClosed} callback will be invoked. All * of the session methods will throw an IllegalStateException if called once the session is @@ -166,10 +166,6 @@ public abstract class CameraCaptureSession implements AutoCloseable { * capture request will be processed before any further repeating * requests are processed.<p> * - * <p>Repeating requests are a simple way for an application to maintain a - * preview or other continuous stream of frames, without having to submit - * requests through {@link #capture} at video rates.</p> - * * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling * {@link #abortCaptures} will also clear the request.</p> * @@ -323,7 +319,7 @@ public abstract class CameraCaptureSession implements AutoCloseable { * * @see #setRepeatingRequest * @see #setRepeatingBurst - * @see #configureOutputs + * @see CameraDevice#createCaptureSession */ public abstract void abortCaptures() throws CameraAccessException; diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index 08cfc87..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> * @@ -320,7 +320,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <p>List of frame rate ranges supported by the - * AE algorithm/hardware</p> + * auto-exposure (AE) algorithm/hardware</p> */ public static final Key<android.util.Range<Integer>[]> CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES = new Key<android.util.Range<Integer>[]>("android.control.aeAvailableTargetFpsRanges", new TypeReference<android.util.Range<Integer>[]>() {{ }}); @@ -343,7 +343,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<Rational>("android.control.aeCompensationStep", Rational.class); /** - * <p>List of AF modes that can be + * <p>List of auto-focus (AF) modes that can be * selected with {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p> * <p>Not all the auto-focus modes may be supported by a * given camera device. This entry lists the valid modes for @@ -496,7 +496,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<int[]>("android.hotPixel.availableHotPixelModes", int[].class); /** - * <p>Supported resolutions for the JPEG thumbnail</p> + * <p>Supported resolutions for the JPEG thumbnail.</p> * <p>Below condiditions will be satisfied for this size list:</p> * <ul> * <li>The sizes will be sorted by increasing pixel area (width x height). @@ -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,17 +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>A typical use case for this might be: after requesting an 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> + * <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 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); @@ -805,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> @@ -814,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 = @@ -837,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 @@ -862,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 @@ -878,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 = @@ -926,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); @@ -1326,15 +1326,21 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<android.graphics.Rect>("android.sensor.info.activeArraySize", android.graphics.Rect.class); /** - * <p>Range of valid sensitivities</p> + * <p>Range of valid sensitivities.</p> + * <p>The minimum and maximum valid values for the + * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} control.</p> + * <p>The values are the standard ISO sensitivity values, + * as defined in ISO 12232:2006.</p> + * + * @see CaptureRequest#SENSOR_SENSITIVITY */ public static final Key<android.util.Range<Integer>> SENSOR_INFO_SENSITIVITY_RANGE = 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 @@ -1372,8 +1378,11 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <p>The physical dimensions of the full pixel - * array</p> - * <p>Needed for FOV calculation for old API</p> + * array.</p> + * <p>This is the physical size of the sensor pixel + * array defined by {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p> + * + * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE */ public static final Key<android.util.SizeF> SENSOR_INFO_PHYSICAL_SIZE = new Key<android.util.SizeF>("android.sensor.info.physicalSize", android.util.SizeF.class); @@ -1381,9 +1390,17 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri /** * <p>Dimensions of full pixel array, possibly * including black calibration pixels.</p> - * <p>Maximum output resolution for raw format must - * match this in - * android.scaler.availableStreamConfigurations.</p> + * <p>The pixel count of the full pixel array, + * which covers {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area.</p> + * <p>If a camera device supports raw sensor formats, either this + * or {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} is the maximum output + * raw size listed in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}. + * If a size corresponding to pixelArraySize is listed, the resulting + * raw sensor image will include black pixels.</p> + * + * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE */ public static final Key<android.util.Size> SENSOR_INFO_PIXEL_ARRAY_SIZE = new Key<android.util.Size>("android.sensor.info.pixelArraySize", android.util.Size.class); @@ -1638,8 +1655,8 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri new Key<Integer>("android.sensor.orientation", int.class); /** - * <p>Optional. Defaults to [OFF]. Lists the supported test - * pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.</p> + * <p>Lists the supported sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.</p> + * <p>Optional. Defaults to [OFF].</p> * <p><b>Optional</b> - This value may be {@code null} on some devices.</p> * * @see CaptureRequest#SENSOR_TEST_PATTERN_MODE @@ -1648,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> @@ -1663,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); @@ -1673,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/CameraDevice.java b/core/java/android/hardware/camera2/CameraDevice.java index e9213c5..68f4d64 100644 --- a/core/java/android/hardware/camera2/CameraDevice.java +++ b/core/java/android/hardware/camera2/CameraDevice.java @@ -52,7 +52,7 @@ public abstract class CameraDevice implements AutoCloseable { * Create a request suitable for a camera preview window. Specifically, this * means that high frame rate is given priority over the highest-quality * post-processing. These requests would normally be used with the - * {@link #setRepeatingRequest} method. + * {@link CameraCaptureSession#setRepeatingRequest} method. * * @see #createCaptureRequest */ @@ -61,7 +61,7 @@ public abstract class CameraDevice implements AutoCloseable { /** * Create a request suitable for still image capture. Specifically, this * means prioritizing image quality over frame rate. These requests would - * commonly be used with the {@link #capture} method. + * commonly be used with the {@link CameraCaptureSession#capture} method. * * @see #createCaptureRequest */ @@ -71,7 +71,7 @@ public abstract class CameraDevice implements AutoCloseable { * Create a request suitable for video recording. Specifically, this means * that a stable frame rate is used, and post-processing is set for * recording quality. These requests would commonly be used with the - * {@link #setRepeatingRequest} method. + * {@link CameraCaptureSession#setRepeatingRequest} method. * * @see #createCaptureRequest */ @@ -81,8 +81,8 @@ public abstract class CameraDevice implements AutoCloseable { * Create a request suitable for still image capture while recording * video. Specifically, this means maximizing image quality without * disrupting the ongoing recording. These requests would commonly be used - * with the {@link #capture} method while a request based on - * {@link #TEMPLATE_RECORD} is is in use with {@link #setRepeatingRequest}. + * with the {@link CameraCaptureSession#capture} method while a request based on + * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}. * * @see #createCaptureRequest */ @@ -132,116 +132,6 @@ public abstract class CameraDevice implements AutoCloseable { /** * <p>Set up a new output set of Surfaces for the camera device.</p> * - * <p>The configuration determines the set of potential output Surfaces for - * the camera device for each capture request. A given request may use all - * or a only some of the outputs. This method must be called before requests - * can be submitted to the camera with {@link #capture capture}, - * {@link #captureBurst captureBurst}, - * {@link #setRepeatingRequest setRepeatingRequest}, or - * {@link #setRepeatingBurst setRepeatingBurst}.</p> - * - * <p>Surfaces suitable for inclusion as a camera output can be created for - * various use cases and targets:</p> - * - * <ul> - * - * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Set - * the size of the Surface with - * {@link android.view.SurfaceHolder#setFixedSize} to be one of the - * supported - * {@link StreamConfigurationMap#getOutputSizes(Class) processed sizes} - * before calling {@link android.view.SurfaceHolder#getSurface}.</li> - * - * <li>For accessing through an OpenGL texture via a - * {@link android.graphics.SurfaceTexture SurfaceTexture}: Set the size of - * the SurfaceTexture with - * {@link android.graphics.SurfaceTexture#setDefaultBufferSize} to be one - * of the supported - * {@link StreamConfigurationMap#getOutputSizes(Class) processed sizes} - * before creating a Surface from the SurfaceTexture with - * {@link Surface#Surface}.</li> - * - * <li>For recording with {@link android.media.MediaCodec}: Call - * {@link android.media.MediaCodec#createInputSurface} after configuring - * the media codec to use one of the - * {@link StreamConfigurationMap#getOutputSizes(Class) processed sizes} - * </li> - * - * <li>For recording with {@link android.media.MediaRecorder}: TODO</li> - * - * <li>For efficient YUV processing with {@link android.renderscript}: - * Create a RenderScript - * {@link android.renderscript.Allocation Allocation} with a supported YUV - * type, the IO_INPUT flag, and one of the supported - * {@link StreamConfigurationMap#getOutputSizes(int) processed sizes}. Then - * obtain the Surface with - * {@link android.renderscript.Allocation#getSurface}.</li> - * - * <li>For access to uncompressed or {@link ImageFormat#JPEG JPEG} data in the application: - * Create a {@link android.media.ImageReader} object with the desired - * {@link StreamConfigurationMap#getOutputFormats() image format}, and a size from the matching - * {@link StreamConfigurationMap#getOutputSizes(int) processed size} and {@code format}. - * Then obtain a {@link Surface} from it.</li> - * </ul> - * - * </p> - * - * <p>This function can take several hundred milliseconds to execute, since - * camera hardware may need to be powered on or reconfigured.</p> - * - * <p>The camera device will query each Surface's size and formats upon this - * call, so they must be set to a valid setting at this time (in particular: - * if the format is user-visible, it must be one of - * {@link StreamConfigurationMap#getOutputFormats}; and the size must be one of - * {@link StreamConfigurationMap#getOutputSizes(int)}).</p> - * - * <p>When this method is called with valid Surfaces, the device will transition to the {@link - * StateListener#onBusy busy state}. Once configuration is complete, the device will transition - * into the {@link StateListener#onIdle idle state}. Capture requests using the newly-configured - * Surfaces may then be submitted with {@link #capture}, {@link #captureBurst}, {@link - * #setRepeatingRequest}, or {@link #setRepeatingBurst}.</p> - * - * <p>If this method is called while the camera device is still actively processing previously - * submitted captures, then the following sequence of events occurs: The device transitions to - * the busy state and calls the {@link StateListener#onBusy} callback. Second, if a repeating - * request is set it is cleared. Third, the device finishes up all in-flight and pending - * requests. Finally, once the device is idle, it then reconfigures its outputs, and calls the - * {@link StateListener#onIdle} method once it is again ready to accept capture - * requests. Therefore, no submitted work is discarded. To idle as fast as possible, use {@link - * #flush} and wait for the idle callback before calling configureOutputs. This will discard - * work, but reaches the new configuration sooner.</p> - * - * <p>Using larger resolution outputs, or more outputs, can result in slower - * output rate from the device.</p> - * - * <p>Configuring the outputs with an empty or null list will transition the camera into an - * {@link StateListener#onUnconfigured unconfigured state} instead of the {@link - * StateListener#onIdle idle state}. </p> - * - * <p>Calling configureOutputs with the same arguments as the last call to - * configureOutputs has no effect, and the {@link StateListener#onBusy busy} - * and {@link StateListener#onIdle idle} state transitions will happen - * immediately.</p> - * - * @param outputs The new set of Surfaces that should be made available as - * targets for captured image data. - * - * @throws IllegalArgumentException if the set of output Surfaces do not - * meet the requirements - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera device is not idle, or - * if the camera device has been closed - * - * @see StateListener#onBusy - * @see StateListener#onIdle - * @see StateListener#onActive - * @see StateListener#onUnconfigured - * @see #stopRepeating - * @see #flush - * @see StreamConfigurationMap#getOutputFormats() - * @see StreamConfigurationMap#getOutputSizes(int) - * @see StreamConfigurationMap#getOutputSizes(Class) * @deprecated Use {@link #createCaptureSession} instead */ @Deprecated @@ -342,10 +232,7 @@ public abstract class CameraDevice implements AutoCloseable { * @param listener The listener to notify about the status of the new capture session. * @param handler The handler on which the listener should be invoked, or {@code null} to use * the current thread's {@link android.os.Looper looper}. - * <!-- - * @return A new camera capture session to use, or null if an empty/null set of Surfaces is - * provided. - * --> + * * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, * the listener is null, or the handler is null but the current * thread has no looper. @@ -393,92 +280,16 @@ public abstract class CameraDevice implements AutoCloseable { /** * <p>Submit a request for an image to be captured by this CameraDevice.</p> * - * <p>The request defines all the parameters for capturing the single image, - * including sensor, lens, flash, and post-processing settings.</p> - * - * <p>Each request will produce one {@link CaptureResult} and produce new - * frames for one or more target Surfaces, set with the CaptureRequest - * builder's {@link CaptureRequest.Builder#addTarget} method. The target - * surfaces must be configured as active outputs with - * {@link #configureOutputs} before calling this method.</p> - * - * <p>Multiple requests can be in progress at once. They are processed in - * first-in, first-out order, with minimal delays between each - * capture. Requests submitted through this method have higher priority than - * those submitted through {@link #setRepeatingRequest} or - * {@link #setRepeatingBurst}, and will be processed as soon as the current - * repeat/repeatBurst processing completes.</p> - * - * @param request the settings for this capture - * @param listener The callback object to notify once this request has been - * processed. If null, no metadata will be produced for this capture, - * although image data will still be produced. - * @param handler the handler on which the listener should be invoked, or - * {@code null} to use the current thread's {@link android.os.Looper - * looper}. - * - * @return int A unique capture sequence ID used by - * {@link CaptureListener#onCaptureSequenceCompleted}. - * - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera is currently busy or unconfigured, - * or the camera device has been closed. - * @throws IllegalArgumentException If the request targets Surfaces not - * currently configured as outputs. Or if the handler is null, the listener - * is not null, and the calling thread has no looper. - * - * @see #captureBurst - * @see #setRepeatingRequest - * @see #setRepeatingBurst - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession#capture} instead */ @Deprecated public abstract int capture(CaptureRequest request, CaptureListener listener, Handler handler) throws CameraAccessException; /** - * Submit a list of requests to be captured in sequence as a burst. The - * burst will be captured in the minimum amount of time possible, and will - * not be interleaved with requests submitted by other capture or repeat - * calls. - * - * <p>The requests will be captured in order, each capture producing one - * {@link CaptureResult} and image buffers for one or more target - * {@link android.view.Surface surfaces}. The target surfaces for each - * request (set with {@link CaptureRequest.Builder#addTarget}) must be - * configured as active outputs with {@link #configureOutputs} before - * calling this method.</p> - * - * <p>The main difference between this method and simply calling - * {@link #capture} repeatedly is that this method guarantees that no - * other requests will be interspersed with the burst.</p> + * Submit a list of requests to be captured in sequence as a burst. * - * @param requests the list of settings for this burst capture - * @param listener The callback object to notify each time one of the - * requests in the burst has been processed. If null, no metadata will be - * produced for any requests in this burst, although image data will still - * be produced. - * @param handler the handler on which the listener should be invoked, or - * {@code null} to use the current thread's {@link android.os.Looper - * looper}. - * - * @return int A unique capture sequence ID used by - * {@link CaptureListener#onCaptureSequenceCompleted}. - * - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera is currently busy or unconfigured, - * or the camera device has been closed. - * @throws IllegalArgumentException If the requests target Surfaces not - * currently configured as outputs. Or if the handler is null, the listener - * is not null, and the calling thread has no looper. Or if no requests were - * passed in. - * - * @see #capture - * @see #setRepeatingRequest - * @see #setRepeatingBurst - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession#captureBurst} instead */ @Deprecated public abstract int captureBurst(List<CaptureRequest> requests, CaptureListener listener, @@ -487,58 +298,7 @@ public abstract class CameraDevice implements AutoCloseable { /** * Request endlessly repeating capture of images by this CameraDevice. * - * <p>With this method, the CameraDevice will continually capture images - * using the settings in the provided {@link CaptureRequest}, at the maximum - * rate possible.</p> - * - * <p>Repeating requests are a simple way for an application to maintain a - * preview or other continuous stream of frames, without having to - * continually submit identical requests through {@link #capture}.</p> - * - * <p>Repeat requests have lower priority than those submitted - * through {@link #capture} or {@link #captureBurst}, so if - * {@link #capture} is called when a repeating request is active, the - * capture request will be processed before any further repeating - * requests are processed.<p> - * - * <p>Repeating requests are a simple way for an application to maintain a - * preview or other continuous stream of frames, without having to submit - * requests through {@link #capture} at video rates.</p> - * - * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling - * {@link #flush} will also clear the request.</p> - * - * <p>Calling this method will replace any earlier repeating request or - * burst set up by this method or {@link #setRepeatingBurst}, although any - * in-progress burst will be completed before the new repeat request will be - * used.</p> - * - * @param request the request to repeat indefinitely - * @param listener The callback object to notify every time the - * request finishes processing. If null, no metadata will be - * produced for this stream of requests, although image data will - * still be produced. - * @param handler the handler on which the listener should be invoked, or - * {@code null} to use the current thread's {@link android.os.Looper - * looper}. - * - * @return int A unique capture sequence ID used by - * {@link CaptureListener#onCaptureSequenceCompleted}. - * - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera is currently busy or unconfigured, - * or the camera device has been closed. - * @throws IllegalArgumentException If the requests reference Surfaces not - * currently configured as outputs. Or if the handler is null, the listener - * is not null, and the calling thread has no looper. - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingBurst - * @see #stopRepeating - * @see #flush - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession#setRepeatingRequest} instead */ @Deprecated public abstract int setRepeatingRequest(CaptureRequest request, CaptureListener listener, @@ -548,58 +308,7 @@ public abstract class CameraDevice implements AutoCloseable { * <p>Request endlessly repeating capture of a sequence of images by this * CameraDevice.</p> * - * <p>With this method, the CameraDevice will continually capture images, - * cycling through the settings in the provided list of - * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p> - * - * <p>If a request is submitted through {@link #capture} or - * {@link #captureBurst}, the current repetition of the request list will be - * completed before the higher-priority request is handled. This guarantees - * that the application always receives a complete repeat burst captured in - * minimal time, instead of bursts interleaved with higher-priority - * captures, or incomplete captures.</p> - * - * <p>Repeating burst requests are a simple way for an application to - * maintain a preview or other continuous stream of frames where each - * request is different in a predicatable way, without having to continually - * submit requests through {@link #captureBurst} .</p> - * - * <p>To stop the repeating capture, call {@link #stopRepeating}. Any - * ongoing burst will still be completed, however. Calling - * {@link #flush} will also clear the request.</p> - * - * <p>Calling this method will replace a previously-set repeating request or - * burst set up by this method or {@link #setRepeatingRequest}, although any - * in-progress burst will be completed before the new repeat burst will be - * used.</p> - * - * @param requests the list of requests to cycle through indefinitely - * @param listener The callback object to notify each time one of the - * requests in the repeating bursts has finished processing. If null, no - * metadata will be produced for this stream of requests, although image - * data will still be produced. - * @param handler the handler on which the listener should be invoked, or - * {@code null} to use the current thread's {@link android.os.Looper - * looper}. - * - * @return int A unique capture sequence ID used by - * {@link CaptureListener#onCaptureSequenceCompleted}. - * - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera is currently busy or unconfigured, - * or the camera device has been closed. - * @throws IllegalArgumentException If the requests reference Surfaces not - * currently configured as outputs. Or if the handler is null, the listener - * is not null, and the calling thread has no looper. Or if no requests were - * passed in. - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingRequest - * @see #stopRepeating - * @see #flush - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession#setRepeatingBurst} instead */ @Deprecated public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener, @@ -608,24 +317,9 @@ public abstract class CameraDevice implements AutoCloseable { /** * <p>Cancel any ongoing repeating capture set by either * {@link #setRepeatingRequest setRepeatingRequest} or - * {@link #setRepeatingBurst}. Has no effect on requests submitted through - * {@link #capture capture} or {@link #captureBurst captureBurst}.</p> + * {@link #setRepeatingBurst}. * - * <p>Any currently in-flight captures will still complete, as will any - * burst that is mid-capture. To ensure that the device has finished - * processing all of its capture requests and is in idle state, wait for the - * {@link StateListener#onIdle} callback after calling this - * method..</p> - * - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera is currently busy or unconfigured, - * or the camera device has been closed. - * - * @see #setRepeatingRequest - * @see #setRepeatingBurst - * @see StateListener#onIdle - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession#stopRepeating} instead */ @Deprecated public abstract void stopRepeating() throws CameraAccessException; @@ -634,36 +328,7 @@ public abstract class CameraDevice implements AutoCloseable { * Flush all captures currently pending and in-progress as fast as * possible. * - * <p>The camera device will discard all of its current work as fast as - * possible. Some in-flight captures may complete successfully and call - * {@link CaptureListener#onCaptureCompleted}, while others will trigger - * their {@link CaptureListener#onCaptureFailed} callbacks. If a repeating - * request or a repeating burst is set, it will be cleared by the flush.</p> - * - * <p>This method is the fastest way to idle the camera device for - * reconfiguration with {@link #configureOutputs}, at the cost of discarding - * in-progress work. Once the flush is complete, the idle callback will be - * called.</p> - * - * <p>Flushing will introduce at least a brief pause in the stream of data - * from the camera device, since once the flush is complete, the first new - * request has to make it through the entire camera pipeline before new - * output buffers are produced.</p> - * - * <p>This means that using {@code flush()} to simply remove pending - * requests is not recommended; it's best used for quickly switching output - * configurations, or for cancelling long in-progress requests (such as a - * multi-second capture).</p> - * - * @throws CameraAccessException if the camera device is no longer connected or has - * encountered a fatal error - * @throws IllegalStateException if the camera is not idle/active, - * or the camera device has been closed. - * - * @see #setRepeatingRequest - * @see #setRepeatingBurst - * @see #configureOutputs - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession#abortCaptures} instead */ @Deprecated public abstract void flush() throws CameraAccessException; @@ -690,15 +355,7 @@ public abstract class CameraDevice implements AutoCloseable { * <p>A listener for tracking the progress of a {@link CaptureRequest} * submitted to the camera device.</p> * - * <p>This listener is called when a request triggers a capture to start, - * and when the capture is complete. In case on an error capturing an image, - * the error method is triggered instead of the completion method.</p> - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingRequest - * @see #setRepeatingBurst - * @deprecated Use {@link CameraCaptureSession} instead + * @deprecated Use {@link CameraCaptureSession.CaptureListener} instead */ @Deprecated public static abstract class CaptureListener { @@ -715,29 +372,6 @@ public abstract class CameraDevice implements AutoCloseable { * This method is called when the camera device has started capturing * the output image for the request, at the beginning of image exposure. * - * <p>This callback is invoked right as the capture of a frame begins, - * so it is the most appropriate time for playing a shutter sound, - * or triggering UI indicators of capture.</p> - * - * <p>The request that is being used for this capture is provided, along - * with the actual timestamp for the start of exposure. This timestamp - * matches the timestamp that will be included in - * {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field}, - * and in the buffers sent to each output Surface. These buffer - * timestamps are accessible through, for example, - * {@link android.media.Image#getTimestamp() Image.getTimestamp()} or - * {@link android.graphics.SurfaceTexture#getTimestamp()}.</p> - * - * <p>For the simplest way to play a shutter sound camera shutter or a - * video recording start/stop sound, see the - * {@link android.media.MediaActionSound} class.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera the CameraDevice sending the callback - * @param request the request for the capture that just begun - * @param timestamp the timestamp at start of capture, in nanoseconds. - * * @see android.media.MediaActionSound */ public void onCaptureStarted(CameraDevice camera, @@ -749,25 +383,6 @@ public abstract class CameraDevice implements AutoCloseable { * This method is called when some results from an image capture are * available. * - * <p>The result provided here will contain some subset of the fields of - * a full result. Multiple onCapturePartial calls may happen per - * capture; a given result field will only be present in one partial - * capture at most. The final onCaptureCompleted call will always - * contain all the fields, whether onCapturePartial was called or - * not.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera The CameraDevice sending the callback. - * @param request The request that was given to the CameraDevice - * @param result The partial output metadata from the capture, which - * includes a subset of the CaptureResult fields. - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingRequest - * @see #setRepeatingBurst - * * @hide */ public void onCapturePartial(CameraDevice camera, @@ -779,37 +394,6 @@ public abstract class CameraDevice implements AutoCloseable { * This method is called when an image capture makes partial forward progress; some * (but not all) results from an image capture are available. * - * <p>The result provided here will contain some subset of the fields of - * a full result. Multiple {@link #onCaptureProgressed} calls may happen per - * capture; a given result field will only be present in one partial - * capture at most. The final {@link #onCaptureCompleted} call will always - * contain all the fields (in particular, the union of all the fields of all - * the partial results composing the total result).</p> - * - * <p>For each request, some result data might be available earlier than others. The typical - * delay between each partial result (per request) is a single frame interval. - * For performance-oriented use-cases, applications should query the metadata they need - * to make forward progress from the partial results and avoid waiting for the completed - * result.</p> - * - * <p>Each request will generate at least {@code 1} partial results, and at most - * {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT} partial results.</p> - * - * <p>Depending on the request settings, the number of partial results per request - * will vary, although typically the partial count could be the same as long as the - * camera device subsystems enabled stay the same.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera The CameraDevice sending the callback. - * @param request The request that was given to the CameraDevice - * @param partialResult The partial output metadata from the capture, which - * includes a subset of the {@link TotalCaptureResult} fields. - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingRequest - * @see #setRepeatingBurst */ public void onCaptureProgressed(CameraDevice camera, CaptureRequest request, CaptureResult partialResult) { @@ -819,26 +403,6 @@ public abstract class CameraDevice implements AutoCloseable { /** * This method is called when an image capture has fully completed and all the * result metadata is available. - * - * <p>This callback will always fire after the last {@link #onCaptureProgressed}; - * in other words, no more partial results will be delivered once the completed result - * is available.</p> - * - * <p>For performance-intensive use-cases where latency is a factor, consider - * using {@link #onCaptureProgressed} instead.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera The CameraDevice sending the callback. - * @param request The request that was given to the CameraDevice - * @param result The total output metadata from the capture, including the - * final capture parameters and the state of the camera system during - * capture. - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingRequest - * @see #setRepeatingBurst */ public void onCaptureCompleted(CameraDevice camera, CaptureRequest request, TotalCaptureResult result) { @@ -849,29 +413,6 @@ public abstract class CameraDevice implements AutoCloseable { * This method is called instead of {@link #onCaptureCompleted} when the * camera device failed to produce a {@link CaptureResult} for the * request. - * - * <p>Other requests are unaffected, and some or all image buffers from - * the capture may have been pushed to their respective output - * streams.</p> - * - * <p>Some partial results may have been delivered before the capture fails; - * however after this callback fires, no more partial results will be delivered by - * {@link #onCaptureProgressed}.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera - * The CameraDevice sending the callback. - * @param request - * The request that was given to the CameraDevice - * @param failure - * The output failure from the capture, including the failure reason - * and the frame number. - * - * @see #capture - * @see #captureBurst - * @see #setRepeatingRequest - * @see #setRepeatingBurst */ public void onCaptureFailed(CameraDevice camera, CaptureRequest request, CaptureFailure failure) { @@ -882,26 +423,6 @@ public abstract class CameraDevice implements AutoCloseable { * This method is called independently of the others in CaptureListener, * when a capture sequence finishes and all {@link CaptureResult} * or {@link CaptureFailure} for it have been returned via this listener. - * - * <p>In total, there will be at least one result/failure returned by this listener - * before this callback is invoked. If the capture sequence is aborted before any - * requests have been processed, {@link #onCaptureSequenceAborted} is invoked instead.</p> - * - * <p>The default implementation does nothing.</p> - * - * @param camera - * The CameraDevice sending the callback. - * @param sequenceId - * A sequence ID returned by the {@link #capture} family of functions. - * @param frameNumber - * The last frame number (returned by {@link CaptureResult#getFrameNumber} - * or {@link CaptureFailure#getFrameNumber}) in the capture sequence. - * - * @see CaptureResult#getFrameNumber() - * @see CaptureFailure#getFrameNumber() - * @see CaptureResult#getSequenceId() - * @see CaptureFailure#getSequenceId() - * @see #onCaptureSequenceAborted */ public void onCaptureSequenceCompleted(CameraDevice camera, int sequenceId, long frameNumber) { @@ -912,25 +433,6 @@ public abstract class CameraDevice implements AutoCloseable { * This method is called independently of the others in CaptureListener, * when a capture sequence aborts before any {@link CaptureResult} * or {@link CaptureFailure} for it have been returned via this listener. - * - * <p>Due to the asynchronous nature of the camera device, not all submitted captures - * are immediately processed. It is possible to clear out the pending requests - * by a variety of operations such as {@link CameraDevice#stopRepeating} or - * {@link CameraDevice#flush}. When such an event happens, - * {@link #onCaptureSequenceCompleted} will not be called.</p> - * - * <p>The default implementation does nothing.</p> - * - * @param camera - * The CameraDevice sending the callback. - * @param sequenceId - * A sequence ID returned by the {@link #capture} family of functions. - * - * @see CaptureResult#getFrameNumber() - * @see CaptureFailure#getFrameNumber() - * @see CaptureResult#getSequenceId() - * @see CaptureFailure#getSequenceId() - * @see #onCaptureSequenceCompleted */ public void onCaptureSequenceAborted(CameraDevice camera, int sequenceId) { @@ -945,14 +447,14 @@ public abstract class CameraDevice implements AutoCloseable { * <p>A listener must be provided to the {@link CameraManager#openCamera} * method to open a camera device.</p> * - * <p>These events include notifications about the device becoming idle ( - * allowing for {@link #configureOutputs} to be called), about device - * disconnection, and about unexpected device errors.</p> + * <p>These events include notifications about the device completing startup ( + * allowing for {@link #createCaptureSession} to be called), about device + * disconnection or closure, and about unexpected device errors.</p> * - * <p>Events about the progress of specific {@link CaptureRequest - * CaptureRequests} are provided through a {@link CaptureListener} given to - * the {@link #capture}, {@link #captureBurst}, {@link - * #setRepeatingRequest}, or {@link #setRepeatingBurst} methods. + * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided + * through a {@link CameraCaptureSession.CaptureListener} given to the + * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, + * {@link CameraCaptureSession#setRepeatingRequest}, or {@link CameraCaptureSession#setRepeatingBurst} methods. * * @see CameraManager#openCamera */ @@ -1026,8 +528,9 @@ public abstract class CameraDevice implements AutoCloseable { /** * The method called when a camera device has finished opening. * - * <p>An opened camera will immediately afterwards transition into - * {@link #onUnconfigured}.</p> + * <p>At this point, the camera device is ready to use, and + * {@link CameraDevice#createCaptureSession} can be called to set up the first capture + * session.</p> * * @param camera the camera device that has become opened */ @@ -1036,21 +539,7 @@ public abstract class CameraDevice implements AutoCloseable { /** * The method called when a camera device has no outputs configured. * - * <p>An unconfigured camera device needs to be configured with - * {@link CameraDevice#configureOutputs} before being able to - * submit any capture request.</p> - * - * <p>This state may be entered by a newly opened camera or by - * calling {@link CameraDevice#configureOutputs} with a null/empty - * list of Surfaces when idle.</p> - * - * <p>Any attempts to submit a capture request while in this state - * will result in an {@link IllegalStateException} being thrown.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera the camera device has that become unconfigured - * @deprecated Use {@link CameraCaptureSession.StateListener} instead. + * @deprecated Use {@link #onOpened} instead. */ @Deprecated public void onUnconfigured(CameraDevice camera) { @@ -1061,27 +550,7 @@ public abstract class CameraDevice implements AutoCloseable { * The method called when a camera device begins processing * {@link CaptureRequest capture requests}. * - * <p>A camera may not be re-configured while in this state. The camera - * will transition to the idle state once all pending captures have - * completed. If a repeating request is set, the camera will remain active - * until it is cleared and the remaining requests finish processing. To - * transition to the idle state as quickly as possible, call {@link #flush()}, - * which will idle the camera device as quickly as possible, likely canceling - * most in-progress captures.</p> - * - * <p>All calls except for {@link CameraDevice#configureOutputs} are - * legal while in this state. - * </p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera the camera device that has become active - * - * @see CameraDevice#capture - * @see CameraDevice#captureBurst - * @see CameraDevice#setRepeatingBurst - * @see CameraDevice#setRepeatingRequest - * @deprecated Use {@link CameraCaptureSession.StateListener} instead. + * @deprecated Use {@link CameraCaptureSession.StateListener#onActive} instead. */ @Deprecated public void onActive(CameraDevice camera) { @@ -1091,32 +560,7 @@ public abstract class CameraDevice implements AutoCloseable { /** * The method called when a camera device is busy. * - * <p>A camera becomes busy while it's outputs are being configured - * (after a call to {@link CameraDevice#configureOutputs} or while it's - * being flushed (after a call to {@link CameraDevice#flush}.</p> - * - * <p>Once the on-going operations are complete, the camera will automatically - * transition into {@link #onIdle} if there is at least one configured output, - * or {@link #onUnconfigured} otherwise.</p> - * - * <p>Any attempts to manipulate the camera while its is busy - * will result in an {@link IllegalStateException} being thrown.</p> - * - * <p>Only the following methods are valid to call while in this state: - * <ul> - * <li>{@link CameraDevice#getId}</li> - * <li>{@link CameraDevice#createCaptureRequest}</li> - * <li>{@link CameraDevice#close}</li> - * </ul> - * </p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera the camera device that has become busy - * - * @see CameraDevice#configureOutputs - * @see CameraDevice#flush - * @deprecated Use {@link CameraCaptureSession.StateListener} instead. + * @deprecated Use {@link CameraCaptureSession.StateListener#onConfigured} instead. */ @Deprecated public void onBusy(CameraDevice camera) { @@ -1142,30 +586,7 @@ public abstract class CameraDevice implements AutoCloseable { * The method called when a camera device has finished processing all * submitted capture requests and has reached an idle state. * - * <p>An idle camera device can have its outputs changed by calling {@link - * CameraDevice#configureOutputs}, which will transition it into the busy state.</p> - * - * <p>To idle and reconfigure outputs without canceling any submitted - * capture requests, the application needs to clear its repeating - * request/burst, if set, with {@link CameraDevice#stopRepeating}, and - * then wait for this callback to be called before calling {@link - * CameraDevice#configureOutputs}.</p> - * - * <p>To idle and reconfigure a camera device as fast as possible, the - * {@link CameraDevice#flush} method can be used, which will discard all - * pending and in-progress capture requests. Once the {@link - * CameraDevice#flush} method is called, the application must wait for - * this callback to fire before calling {@link - * CameraDevice#configureOutputs}.</p> - * - * <p>The default implementation of this method does nothing.</p> - * - * @param camera the camera device that has become idle - * - * @see CameraDevice#configureOutputs - * @see CameraDevice#stopRepeating - * @see CameraDevice#flush - * @deprecated Use {@link CameraCaptureSession.StateListener} instead. + * @deprecated Use {@link CameraCaptureSession.StateListener#onReady} instead. */ @Deprecated public void onIdle(CameraDevice camera) { @@ -1221,7 +642,7 @@ public abstract class CameraDevice implements AutoCloseable { * * @param camera The device reporting the error * @param error The error code, one of the - * {@code CameraDeviceListener.ERROR_*} values. + * {@code StateListener.ERROR_*} values. * * @see #ERROR_CAMERA_DEVICE * @see #ERROR_CAMERA_SERVICE diff --git a/core/java/android/hardware/camera2/CameraManager.java b/core/java/android/hardware/camera2/CameraManager.java index 7c0f37e..0901562 100644 --- a/core/java/android/hardware/camera2/CameraManager.java +++ b/core/java/android/hardware/camera2/CameraManager.java @@ -35,7 +35,7 @@ import android.util.ArrayMap; import java.util.ArrayList; /** - * <p>An interface for iterating, listing, and connecting to + * <p>A system service manager for detecting, characterizing, and connecting to * {@link CameraDevice CameraDevices}.</p> * * <p>You can get an instance of this class by calling @@ -357,14 +357,18 @@ public final class CameraManager { } /** - * Interface for listening to camera devices becoming available or - * unavailable. + * A listener for camera devices becoming available or + * unavailable to open. * * <p>Cameras become available when they are no longer in use, or when a new * removable camera is connected. They become unavailable when some * application or service starts using a camera, or when a removable camera * is disconnected.</p> * + * <p>Extend this listener and pass an instance of the subclass to + * {@link CameraManager#addAvailabilityListener} to be notified of such availability + * changes.</p> + * * @see addAvailabilityListener */ public static abstract class AvailabilityListener { diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index 94a5a79..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,12 +357,14 @@ 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 value in - * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</li> + * 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 * by the camera device.</li> * </ul> * + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES */ @@ -371,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; @@ -523,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 */ @@ -534,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; @@ -548,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> @@ -590,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 @@ -604,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 @@ -656,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 @@ -672,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 @@ -689,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> * @@ -705,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> * @@ -720,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; @@ -739,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; @@ -752,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 @@ -760,12 +771,14 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_AF_MODE_OFF = 0; /** - * <p>If lens is not fixed focus.</p> - * <p>Use {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} to determine if lens - * is fixed-focus. In this mode, the lens does not move unless + * <p>Basic automatic focus mode.</p> + * <p>In this mode, the lens does not move unless * the autofocus trigger action is called. When that trigger - * is activated, AF must transition to ACTIVE_SCAN, then to + * is activated, AF will transition to ACTIVE_SCAN, then to * the outcome of the scan (FOCUSED or NOT_FOCUSED).</p> + * <p>Always supported if lens is not fixed focus.</p> + * <p>Use {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} to determine if lens + * is fixed-focus.</p> * <p>Triggering AF_CANCEL resets the lens position to default, * and sets the AF state to INACTIVE.</p> * @@ -775,11 +788,16 @@ public abstract class CameraMetadata<TKey> { public static final int CONTROL_AF_MODE_AUTO = 1; /** + * <p>Close-up focusing mode.</p> * <p>In this mode, the lens does not move unless the - * autofocus trigger action is called.</p> - * <p>When that trigger is activated, AF must transition to + * autofocus trigger action is called. When that trigger is + * activated, AF will transition to ACTIVE_SCAN, then to + * the outcome of the scan (FOCUSED or NOT_FOCUSED). This + * mode is optimized for focusing on objects very close to + * the camera.</p> + * <p>When that trigger is activated, AF will transition to * ACTIVE_SCAN, then to the outcome of the scan (FOCUSED or - * NOT_FOCUSED). Triggering cancel AF resets the lens + * NOT_FOCUSED). Triggering cancel AF resets the lens * position to default, and sets the AF state to * INACTIVE.</p> * @see CaptureRequest#CONTROL_AF_MODE @@ -830,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 */ @@ -865,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> @@ -878,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 @@ -889,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; @@ -957,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; @@ -997,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 @@ -1025,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; @@ -1085,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 @@ -1119,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; @@ -1137,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}, @@ -1154,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; @@ -1224,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; @@ -1257,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; @@ -1271,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; @@ -1318,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 @@ -1329,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 @@ -1340,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 @@ -1371,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; @@ -1395,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; @@ -1500,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; @@ -1522,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; @@ -1545,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; @@ -1573,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; @@ -1591,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 @@ -1600,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 */ @@ -1629,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 @@ -1645,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 */ @@ -1710,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 */ @@ -1767,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 */ @@ -1791,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 @@ -1807,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; @@ -1826,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, @@ -1842,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 d4dfdd5..bf7bd37 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -43,14 +43,14 @@ import java.util.Objects; * <p>CaptureRequests can be created by using a {@link Builder} instance, * obtained by calling {@link CameraDevice#createCaptureRequest}</p> * - * <p>CaptureRequests are given to {@link CameraDevice#capture} or - * {@link CameraDevice#setRepeatingRequest} to capture images from a camera.</p> + * <p>CaptureRequests are given to {@link CameraCaptureSession#capture} or + * {@link CameraCaptureSession#setRepeatingRequest} to capture images from a camera.</p> * * <p>Each request can specify a different subset of target Surfaces for the * camera to send the captured data to. All the surfaces used in a request must * be part of the surface list given to the last call to - * {@link CameraDevice#configureOutputs}, when the request is submitted to the - * camera device.</p> + * {@link CameraDevice#createCaptureSession}, when the request is submitted to the + * session.</p> * * <p>For example, a request meant for repeating preview might only include the * Surface for the preview SurfaceView or SurfaceTexture, while a @@ -357,11 +357,11 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * request fields to one of the templates defined in {@link CameraDevice}. * * @see CameraDevice#createCaptureRequest - * @see #TEMPLATE_PREVIEW - * @see #TEMPLATE_RECORD - * @see #TEMPLATE_STILL_CAPTURE - * @see #TEMPLATE_VIDEO_SNAPSHOT - * @see #TEMPLATE_MANUAL + * @see CameraDevice#TEMPLATE_PREVIEW + * @see CameraDevice#TEMPLATE_RECORD + * @see CameraDevice#TEMPLATE_STILL_CAPTURE + * @see CameraDevice#TEMPLATE_VIDEO_SNAPSHOT + * @see CameraDevice#TEMPLATE_MANUAL */ public final static class Builder { @@ -381,7 +381,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <p>Add a surface to the list of targets for this request</p> * * <p>The Surface added must be one of the surfaces included in the most - * recent call to {@link CameraDevice#configureOutputs}, when the + * recent call to {@link CameraDevice#createCaptureSession}, when the * request is given to the camera device.</p> * * <p>Adding a target more than once has no effect.</p> @@ -473,7 +473,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>The mode control selects how the image data is converted from the * sensor's native color into linear sRGB color.</p> - * <p>When auto-white balance is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this + * <p>When auto-white balance (AWB) is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this * control is overridden by the AWB routine. When AWB is disabled, the * application controls how the color mapping is performed.</p> * <p>We define the expected processing pipeline below. For consistency @@ -524,7 +524,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>A color transform matrix to use to transform - * from sensor RGB color space to output linear sRGB color space</p> + * from sensor RGB color space to output linear sRGB color space.</p> * <p>This matrix is either set by the camera device when the request * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or * directly by the application in the request when the @@ -600,13 +600,17 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.control.aeAntibandingMode", int.class); /** - * <p>Adjustment to AE target image - * brightness</p> - * <p>For example, if EV step is 0.333, '6' will mean an - * exposure compensation of +2 EV; -3 will mean an exposure - * compensation of -1 EV. Note that this control will only be effective - * if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control will take effect even when - * {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p> + * <p>Adjustment to auto-exposure (AE) target image + * brightness.</p> + * <p>The adjustment is measured as a count of steps, with the + * step size defined by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} and the + * allowed range by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}.</p> + * <p>For example, if the exposure value (EV) step is 0.333, '6' + * will mean an exposure compensation of +2 EV; -3 will mean an + * exposure compensation of -1 EV. One EV represents a doubling + * of image brightness. Note that this control will only be + * effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control + * will take effect even when {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p> * <p>In the event of exposure compensation value being changed, camera device * may take several frames to reach the newly requested exposure target. * During that time, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} field will be in the SEARCHING @@ -614,6 +618,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or * FLASH_REQUIRED (if the scene is too dark for still capture).</p> * + * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE + * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP * @see CaptureRequest#CONTROL_AE_LOCK * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureResult#CONTROL_AE_STATE @@ -622,7 +628,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.control.aeExposureCompensation", int.class); /** - * <p>Whether AE is currently locked to its latest + * <p>Whether auto-exposure (AE) is currently locked to its latest * calculated values.</p> * <p>Note that even when AE is locked, the flash may be * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH / @@ -711,9 +717,9 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>Range over which fps can be adjusted to - * maintain exposure</p> - * <p>Only constrains AE algorithm, not manual control - * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p> + * maintain exposure.</p> + * <p>Only constrains auto-exposure (AE) algorithm, not + * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p> * * @see CaptureRequest#SENSOR_EXPOSURE_TIME */ @@ -727,9 +733,18 @@ 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 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> + * <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> * * @see CaptureResult#CONTROL_AE_STATE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE @@ -739,8 +754,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.control.aePrecaptureTrigger", int.class); /** - * <p>Whether AF is currently enabled, and what - * mode it is set to</p> + * <p>Whether auto-focus (AF) is currently enabled, and what + * mode it is set to.</p> * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0</code>).</p> * <p>If the lens is controlled by the camera device auto-focus algorithm, @@ -793,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 @@ -804,31 +823,37 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.control.afTrigger", int.class); /** - * <p>Whether AWB is currently locked to its + * <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); /** - * <p>Whether AWB is currently setting the color + * <p>Whether auto-white balance (AWB) is currently setting the color * 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 @@ -879,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 @@ -955,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 @@ -963,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 @@ -988,7 +1016,9 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>Whether video stabilization is - * active</p> + * 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> @@ -1030,7 +1060,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <p>When set to OFF, the camera device will not fire flash for this capture.</p> * <p>When set to SINGLE, the camera device will fire flash regardless of the camera * device's auto-exposure routine's result. When used in still capture case, this - * control should be used along with AE precapture metering sequence + * control should be used along with auto-exposure (AE) precapture metering sequence * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p> * <p>When set to TORCH, the flash will be on continuously. This mode can be used * for use cases such as preview, auto-focus assist, still capture, or video recording.</p> @@ -1102,21 +1132,21 @@ 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> + * image.</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); /** - * <p>Resolution of embedded JPEG thumbnail</p> + * <p>Resolution of embedded JPEG thumbnail.</p> * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, * but the captured JPEG will still be a valid image.</p> * <p>When a jpeg image capture is issued, the thumbnail size selected should have @@ -1204,7 +1234,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> /** * <p>Distance to plane of sharpest focus, - * measured from frontmost surface of the lens</p> + * measured from frontmost surface of the lens.</p> * <p>0 means infinity focus. Used value will be clamped * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].</p> * <p>Like {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, this setting won't be applied @@ -1222,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 */ @@ -1235,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 @@ -1265,40 +1300,39 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.request.id", int.class); /** - * <p>(x, y, width, height).</p> - * <p>A rectangle with the top-level corner of (x,y) and size - * (width, height). The region of the sensor that is used for - * output. Each stream must use this rectangle to produce its - * output, cropping to a smaller region if necessary to - * maintain the stream's aspect ratio.</p> - * <p>HAL2.x uses only (x, y, width)</p> - * <p>The crop region is applied after the RAW to other color space (e.g. YUV) - * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, - * it is not croppable. The crop region will be ignored by raw streams.</p> + * <p>The region of the sensor to read out for this capture.</p> + * <p>The crop region coordinate system is based off + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the + * top-left corner of the sensor active array.</p> + * <p>Output streams use this rectangle to produce their output, + * cropping to a smaller region if necessary to maintain the + * stream's aspect ratio, then scaling the sensor input to + * match the output's configured resolution.</p> + * <p>The crop region is applied after the RAW to other color + * space (e.g. YUV) conversion. Since raw streams + * (e.g. RAW16) don't have the conversion stage, they are not + * croppable. The crop region will be ignored by raw streams.</p> * <p>For non-raw streams, any additional per-stream cropping will * be done to maximize the final pixel area of the stream.</p> * <p>For example, if the crop region is set to a 4:3 aspect - * ratio, then 4:3 streams should use the exact crop - * region. 16:9 streams should further crop vertically + * ratio, then 4:3 streams will use the exact crop + * region. 16:9 streams will further crop vertically * (letterbox).</p> * <p>Conversely, if the crop region is set to a 16:9, then 4:3 - * outputs should crop horizontally (pillarbox), and 16:9 - * streams should match exactly. These additional crops must + * outputs will crop horizontally (pillarbox), and 16:9 + * streams will match exactly. These additional crops will * be centered within the crop region.</p> - * <p>The output streams must maintain square pixels at all - * times, no matter what the relative aspect ratios of the - * crop region and the stream are. Negative values for - * corner are allowed for raw output if full pixel array is - * larger than active pixel array. Width and height may be - * rounded to nearest larger supportable width, especially - * for raw output, where only a few fixed scales may be - * possible. The width and height of the crop region cannot - * be set to be smaller than floor( activeArraySize.width / - * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor( - * activeArraySize.height / - * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p> + * <p>The width and height of the crop region cannot + * be set to be smaller than + * <code>floor( activeArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code> and + * <code>floor( activeArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code>, respectively.</p> + * <p>The camera device may adjust the crop region to account + * for rounding and other hardware requirements; the final + * crop region used will be included in the output capture + * result.</p> * * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE */ public static final Key<android.graphics.Rect> SCALER_CROP_REGION = new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class); @@ -1391,12 +1425,20 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Long>("android.sensor.frameDuration", long.class); /** - * <p>Gain applied to image data. Must be - * implemented through analog gain only if set to values - * below 'maximum analog sensitivity'.</p> - * <p>If the sensor can't apply this exact gain, it should lessen the - * gain to the nearest possible value (rather than gain more).</p> - * <p>ISO 12232:2006 REI method</p> + * <p>The amount of gain applied to sensor data + * before processing.</p> + * <p>The sensitivity is the standard ISO sensitivity value, + * as defined in ISO 12232:2006.</p> + * <p>The sensitivity must be within {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}, and + * if if it less than {@link CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY android.sensor.maxAnalogSensitivity}, the camera device + * is guaranteed to use only analog amplification for applying the gain.</p> + * <p>If the camera device cannot apply the exact sensitivity + * requested, it will reduce the gain to the nearest supported + * value. The final sensitivity used will be available in the + * output capture result.</p> + * + * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE + * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY */ public static final Key<Integer> SENSOR_SENSITIVITY = new Key<Integer>("android.sensor.sensitivity", int.class); @@ -1421,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 @@ -1459,7 +1501,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * lens shading map data in android.statistics.lensShadingMap, with size specified * by android.lens.info.shadingMapSize; the returned shading map data will be the one * applied by the camera device for this capture request.</p> - * <p>The shading map data may depend on the AE and AWB statistics, therefore the reliability + * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF), * to get best results, it is recommended that the applications wait for the AE and AWB to @@ -1476,8 +1518,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> new Key<Integer>("android.shading.mode", int.class); /** - * <p>State of the face detector - * unit</p> + * <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 * fields. Value must be one of the @@ -1494,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 @@ -1507,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 7d07c92..3d17ed3 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -319,7 +319,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>The mode control selects how the image data is converted from the * sensor's native color into linear sRGB color.</p> - * <p>When auto-white balance is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this + * <p>When auto-white balance (AWB) is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this * control is overridden by the AWB routine. When AWB is disabled, the * application controls how the color mapping is performed.</p> * <p>We define the expected processing pipeline below. For consistency @@ -370,7 +370,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>A color transform matrix to use to transform - * from sensor RGB color space to output linear sRGB color space</p> + * from sensor RGB color space to output linear sRGB color space.</p> * <p>This matrix is either set by the camera device when the request * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or * directly by the application in the request when the @@ -446,13 +446,17 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.aeAntibandingMode", int.class); /** - * <p>Adjustment to AE target image - * brightness</p> - * <p>For example, if EV step is 0.333, '6' will mean an - * exposure compensation of +2 EV; -3 will mean an exposure - * compensation of -1 EV. Note that this control will only be effective - * if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control will take effect even when - * {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p> + * <p>Adjustment to auto-exposure (AE) target image + * brightness.</p> + * <p>The adjustment is measured as a count of steps, with the + * step size defined by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} and the + * allowed range by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}.</p> + * <p>For example, if the exposure value (EV) step is 0.333, '6' + * will mean an exposure compensation of +2 EV; -3 will mean an + * exposure compensation of -1 EV. One EV represents a doubling + * of image brightness. Note that this control will only be + * effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control + * will take effect even when {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p> * <p>In the event of exposure compensation value being changed, camera device * may take several frames to reach the newly requested exposure target. * During that time, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} field will be in the SEARCHING @@ -460,6 +464,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or * FLASH_REQUIRED (if the scene is too dark for still capture).</p> * + * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE + * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP * @see CaptureRequest#CONTROL_AE_LOCK * @see CaptureRequest#CONTROL_AE_MODE * @see CaptureResult#CONTROL_AE_STATE @@ -468,7 +474,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.aeExposureCompensation", int.class); /** - * <p>Whether AE is currently locked to its latest + * <p>Whether auto-exposure (AE) is currently locked to its latest * calculated values.</p> * <p>Note that even when AE is locked, the flash may be * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH / @@ -557,9 +563,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Range over which fps can be adjusted to - * maintain exposure</p> - * <p>Only constrains AE algorithm, not manual control - * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p> + * maintain exposure.</p> + * <p>Only constrains auto-exposure (AE) algorithm, not + * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p> * * @see CaptureRequest#SENSOR_EXPOSURE_TIME */ @@ -573,9 +579,18 @@ 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 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> + * <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> * * @see CaptureResult#CONTROL_AE_STATE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE @@ -585,7 +600,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.aePrecaptureTrigger", int.class); /** - * <p>Current state of 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 @@ -783,8 +798,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.aeState", int.class); /** - * <p>Whether AF is currently enabled, and what - * mode it is set to</p> + * <p>Whether auto-focus (AF) is currently enabled, and what + * mode it is set to.</p> * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} > 0</code>).</p> * <p>If the lens is controlled by the camera device auto-focus algorithm, @@ -837,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 @@ -848,7 +867,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.afTrigger", int.class); /** - * <p>Current state of AF algorithm.</p> + * <p>Current state of auto-focus (AF) algorithm.</p> * <p>Switching between or enabling AF modes ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) always * resets the AF 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 @@ -1027,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> @@ -1057,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> @@ -1130,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> @@ -1245,31 +1264,37 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.afState", int.class); /** - * <p>Whether AWB is currently locked to its + * <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); /** - * <p>Whether AWB is currently setting the color + * <p>Whether auto-white balance (AWB) is currently setting the color * 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 @@ -1320,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 @@ -1338,7 +1363,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.control.captureIntent", int.class); /** - * <p>Current state of AWB algorithm</p> + * <p>Current state of auto-white balance (AWB) algorithm.</p> * <p>Switching between or enabling AWB modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}) always * resets the AWB 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 @@ -1526,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 @@ -1534,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 @@ -1559,7 +1587,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Whether video stabilization is - * active</p> + * 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> @@ -1601,7 +1631,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <p>When set to OFF, the camera device will not fire flash for this capture.</p> * <p>When set to SINGLE, the camera device will fire flash regardless of the camera * device's auto-exposure routine's result. When used in still capture case, this - * control should be used along with AE precapture metering sequence + * control should be used along with auto-exposure (AE) precapture metering sequence * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p> * <p>When set to TORCH, the flash will be on continuously. This mode can be used * for use cases such as preview, auto-focus assist, still capture, or video recording.</p> @@ -1690,21 +1720,21 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Compression quality of the final JPEG - * image</p> - * <p>85-95 is typical usage range</p> + * image.</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); /** - * <p>Resolution of embedded JPEG thumbnail</p> + * <p>Resolution of embedded JPEG thumbnail.</p> * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, * but the captured JPEG will still be a valid image.</p> * <p>When a jpeg image capture is issued, the thumbnail size selected should have @@ -1792,7 +1822,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>Distance to plane of sharpest focus, - * measured from frontmost surface of the lens</p> + * measured from frontmost surface of the lens.</p> * <p>Should be zero for fixed-focus cameras</p> */ public static final Key<Float> LENS_FOCUS_DISTANCE = @@ -1800,7 +1830,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { /** * <p>The range of scene distances that are in - * sharp focus (depth of field)</p> + * sharp focus (depth of field).</p> * <p>If variable focus not supported, can still report * fixed depth of field range</p> */ @@ -1810,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 */ @@ -1859,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 @@ -1934,40 +1969,39 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Byte>("android.request.pipelineDepth", byte.class); /** - * <p>(x, y, width, height).</p> - * <p>A rectangle with the top-level corner of (x,y) and size - * (width, height). The region of the sensor that is used for - * output. Each stream must use this rectangle to produce its - * output, cropping to a smaller region if necessary to - * maintain the stream's aspect ratio.</p> - * <p>HAL2.x uses only (x, y, width)</p> - * <p>The crop region is applied after the RAW to other color space (e.g. YUV) - * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, - * it is not croppable. The crop region will be ignored by raw streams.</p> + * <p>The region of the sensor to read out for this capture.</p> + * <p>The crop region coordinate system is based off + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the + * top-left corner of the sensor active array.</p> + * <p>Output streams use this rectangle to produce their output, + * cropping to a smaller region if necessary to maintain the + * stream's aspect ratio, then scaling the sensor input to + * match the output's configured resolution.</p> + * <p>The crop region is applied after the RAW to other color + * space (e.g. YUV) conversion. Since raw streams + * (e.g. RAW16) don't have the conversion stage, they are not + * croppable. The crop region will be ignored by raw streams.</p> * <p>For non-raw streams, any additional per-stream cropping will * be done to maximize the final pixel area of the stream.</p> * <p>For example, if the crop region is set to a 4:3 aspect - * ratio, then 4:3 streams should use the exact crop - * region. 16:9 streams should further crop vertically + * ratio, then 4:3 streams will use the exact crop + * region. 16:9 streams will further crop vertically * (letterbox).</p> * <p>Conversely, if the crop region is set to a 16:9, then 4:3 - * outputs should crop horizontally (pillarbox), and 16:9 - * streams should match exactly. These additional crops must + * outputs will crop horizontally (pillarbox), and 16:9 + * streams will match exactly. These additional crops will * be centered within the crop region.</p> - * <p>The output streams must maintain square pixels at all - * times, no matter what the relative aspect ratios of the - * crop region and the stream are. Negative values for - * corner are allowed for raw output if full pixel array is - * larger than active pixel array. Width and height may be - * rounded to nearest larger supportable width, especially - * for raw output, where only a few fixed scales may be - * possible. The width and height of the crop region cannot - * be set to be smaller than floor( activeArraySize.width / - * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor( - * activeArraySize.height / - * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p> + * <p>The width and height of the crop region cannot + * be set to be smaller than + * <code>floor( activeArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code> and + * <code>floor( activeArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code>, respectively.</p> + * <p>The camera device may adjust the crop region to account + * for rounding and other hardware requirements; the final + * crop region used will be included in the output capture + * result.</p> * * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE */ public static final Key<android.graphics.Rect> SCALER_CROP_REGION = new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class); @@ -2060,21 +2094,35 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Long>("android.sensor.frameDuration", long.class); /** - * <p>Gain applied to image data. Must be - * implemented through analog gain only if set to values - * below 'maximum analog sensitivity'.</p> - * <p>If the sensor can't apply this exact gain, it should lessen the - * gain to the nearest possible value (rather than gain more).</p> - * <p>ISO 12232:2006 REI method</p> + * <p>The amount of gain applied to sensor data + * before processing.</p> + * <p>The sensitivity is the standard ISO sensitivity value, + * as defined in ISO 12232:2006.</p> + * <p>The sensitivity must be within {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}, and + * if if it less than {@link CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY android.sensor.maxAnalogSensitivity}, the camera device + * is guaranteed to use only analog amplification for applying the gain.</p> + * <p>If the camera device cannot apply the exact sensitivity + * requested, it will reduce the gain to the nearest supported + * value. The final sensitivity used will be available in the + * output capture result.</p> + * + * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE + * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY */ public static final Key<Integer> SENSOR_SENSITIVITY = new Key<Integer>("android.sensor.sensitivity", int.class); /** * <p>Time at start of exposure of first - * row</p> - * <p>Monotonic, should be synced to other timestamps in - * system</p> + * row of the image sensor, in nanoseconds.</p> + * <p>The timestamps are also included in all image + * buffers produced for the same capture, and will be identical + * on all the outputs. The timestamps measure time since an + * unspecified starting point, and are monotonically + * increasing.</p> + * <p>They can be compared with the timestamps for other captures + * from the same camera device, but are not guaranteed to be + * comparable to any other time source.</p> */ public static final Key<Long> SENSOR_TIMESTAMP = new Key<Long>("android.sensor.timestamp", long.class); @@ -2150,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 @@ -2188,7 +2236,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * lens shading map data in android.statistics.lensShadingMap, with size specified * by android.lens.info.shadingMapSize; the returned shading map data will be the one * applied by the camera device for this capture request.</p> - * <p>The shading map data may depend on the AE and AWB statistics, therefore the reliability + * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF), * to get best results, it is recommended that the applications wait for the AE and AWB to @@ -2205,8 +2253,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { new Key<Integer>("android.shading.mode", int.class); /** - * <p>State of the face detector - * unit</p> + * <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 * fields. Value must be one of the @@ -2221,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 = @@ -2231,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 = @@ -2240,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 = @@ -2250,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 = @@ -2370,7 +2433,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * applied to that frame.</p> * <p>The 4 channel gains are defined in Bayer domain, * see {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} for details.</p> - * <p>This value should always be calculated by the AWB block, + * <p>This value should always be calculated by the auto-white balance (AWB) block, * regardless of the android.control.* current values.</p> * <p><b>Optional</b> - This value may be {@code null} on some devices.</p> * @@ -2396,7 +2459,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * that frame.</p> * <p>These estimates must be provided for all frames, even if * capture settings and color transforms are set by the application.</p> - * <p>This value should always be calculated by the AWB block, + * <p>This value should always be calculated by the auto-white balance (AWB) block, * regardless of the android.control.* current values.</p> * <p><b>Optional</b> - This value may be {@code null} on some devices.</p> * @deprecated @@ -2415,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 @@ -2435,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 @@ -2463,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/package.html b/core/java/android/hardware/camera2/package.html index 9f6c2a9..ef0d7bd 100644 --- a/core/java/android/hardware/camera2/package.html +++ b/core/java/android/hardware/camera2/package.html @@ -34,49 +34,71 @@ framerate on most Android devices.</p> CameraDevices} provide a set of static property information that describes the hardware device and the available settings and output parameters for the device. This information is provided through the -{@link android.hardware.camera2.CameraCharacteristics} object.</p> +{@link android.hardware.camera2.CameraCharacteristics} object, and is +available through {@link +android.hardware.camera2.CameraManager#getCameraCharacteristics}</p> <p>To capture or stream images from a camera device, the application -must first configure a set of output Surfaces for use with the camera -device, with {@link -android.hardware.camera2.CameraDevice#configureOutputs}. Each -Surface has to be pre-configured with an appropriate size and format -(if applicable) to match the sizes and formats available from the -camera device. A target Surface can be obtained from a variety of -classes, including {@link android.view.SurfaceView}, {@link -android.graphics.SurfaceTexture} via {@link -android.view.Surface#Surface(SurfaceTexture), {@link -android.media.MediaCodec}, and {@link android.media.ImageReader}. +must first create a {@link +android.hardware.camera2.CameraCaptureSession camera capture session} +with a set of output Surfaces for use with the camera device, with +{@link +android.hardware.camera2.CameraDevice#createCaptureSession}. Each +Surface has to be pre-configured with an {@link +android.hardware.camera2.params.StreamConfigurationMap appropriate +size and format} (if applicable) to match the sizes and formats +available from the camera device. A target Surface can be obtained +from a variety of classes, including {@link android.view.SurfaceView}, +{@link android.graphics.SurfaceTexture} via +{@link android.view.Surface#Surface(SurfaceTexture)}, +{@link android.media.MediaCodec}, {@link android.media.MediaRecorder}, +{@link android.renderscript.Allocation}, and {@link android.media.ImageReader}. </p> +<p>Generally, camera preview images are sent to {@link +android.view.SurfaceView} or {@link android.view.TextureView} (via its +{@link android.graphics.SurfaceTexture}). Capture of JPEG images or +RAW buffers for {@link android.hardware.camera2.DngCreator} can be done +with {@link android.media.ImageReader} with the +{android.graphics.ImageFormat#JPEG} and +{android.graphics.ImageFormat#RAW_SENSOR} formats. Application-driven +processing of camera data in RenderScript, OpenGL ES, or directly in +managed or native code is best done through {@link +android.renderscript.Allocation} with a YUV {@link +android.renderscript.Type}, {@link android.graphics.SurfaceTexture}, +and {@link android.media.ImageReader} with a +{android.graphics.ImageFormat#YUV_420_888} format, respectively.</p> + <p>The application then needs to construct a {@link android.hardware.camera2.CaptureRequest}, which defines all the capture parameters needed by a camera device to capture a single image. The request also lists which of the configured output Surfaces should be used as targets for this capture. The CameraDevice has a {@link android.hardware.camera2.CameraDevice#createCaptureRequest -convenience factory method} for creating a request for a given use -case which is optimized for the Android device the application is -running on.</p> +factory method} for creating a {@link +android.hardware.camera2.CaptureRequest.Builder request builder} for a +given use case, which is optimized for the Android device the +application is running on.</p> -<p>Once the request has been set up, it can be handed to the -CameraDevice either for a one-shot {@link -android.hardware.camera2.CameraDevice#capture} or for an endlessly -{@link android.hardware.camera2.CameraDevice#setRepeatingRequest -repeating} use. Both methods also accept a list of requests to use as -a burst capture / repeating burst. Repeating requests have a lower -priority than captures, so a request submitted +<p>Once the request has been set up, it can be handed to the active +capture session either for a one-shot {@link +android.hardware.camera2.CameraCaptureSession#capture capture} or for +an endlessly {@link +android.hardware.camera2.CameraCaptureSession#setRepeatingRequest +repeating} use. Both methods also have a variant that accepts a list +of requests to use as a burst capture / repeating burst. Repeating +requests have a lower priority than captures, so a request submitted through <code>capture()</code> while there's a repeating request -configured will be captured as soon as the current repeat (burst) -capture completes.</p> +configured will be captured before any new instances of the currently +repeating (burst) capture will begin capture.</p> <p>After processing a request, the camera device will produce a {@link -android.hardware.camera2.CaptureResult} object, which contains +android.hardware.camera2.TotalCaptureResult} object, which contains information about the state of the camera device at time of capture, and the final settings used. These may vary somewhat from the request, if rounding or resolving contradictory parameters was necessary. The camera device will also send a frame of image data into each of the -output streams included in the request. These are produced +output {@code Surfaces} included in the request. These are produced asynchronously relative to the output CaptureResult, sometimes substantially later.</p> diff --git a/core/java/android/hardware/camera2/params/StreamConfiguration.java b/core/java/android/hardware/camera2/params/StreamConfiguration.java index 1c6b6e9..a6fc10f 100644 --- a/core/java/android/hardware/camera2/params/StreamConfiguration.java +++ b/core/java/android/hardware/camera2/params/StreamConfiguration.java @@ -28,8 +28,9 @@ import android.util.Size; /** * Immutable class to store the available stream - * {@link CameraCharacteristics#SCALER_AVAILABLE_STREAM_CONFIGURATIONS configurations} to be used - * when configuring streams with {@link CameraDevice#configureOutputs}. + * {@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 --> * * <p>This is the authoritative list for all input/output formats (and sizes respectively @@ -124,7 +125,7 @@ public final class StreamConfiguration { * * @return {@code true} if output configuration, {@code false} otherwise * - * @see CameraDevice#configureOutputs + * @see CameraDevice#createCaptureSession */ public boolean isOutput() { return !mInput; diff --git a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java index 4cd6d15..3036425 100644 --- a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java +++ b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java @@ -34,8 +34,10 @@ import static com.android.internal.util.Preconditions.*; /** * Immutable class to store the available stream - * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP configurations} to be used - * when configuring streams with {@link CameraDevice#configureOutputs}. + * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP configurations} to set up + * {@link android.view.Surface Surfaces} for creating a + * {@link android.hardware.camera2.CameraCaptureSession capture session} with + * {@link android.hardware.camera2.CameraDevice#createCaptureSession}. * <!-- TODO: link to input stream configuration --> * * <p>This is the authoritative list for all <!-- input/ -->output formats (and sizes respectively @@ -56,7 +58,7 @@ import static com.android.internal.util.Preconditions.*; * }</code></pre> * * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP - * @see CameraDevice#configureOutputs + * @see CameraDevice#createCaptureSession */ public final class StreamConfigurationMap { @@ -155,8 +157,8 @@ public final class StreamConfigurationMap { } /** - * Determine whether or not output streams can be - * {@link CameraDevice#configureOutputs configured} with a particular user-defined format. + * Determine whether or not output surfaces with a particular user-defined format can be passed + * {@link CameraDevice#createCaptureSession createCaptureSession}. * * <p>This method determines that the output {@code format} is supported by the camera device; * each output {@code surface} target may or may not itself support that {@code format}. @@ -168,7 +170,7 @@ public final class StreamConfigurationMap { * @param format an image format from either {@link ImageFormat} or {@link PixelFormat} * @return * {@code true} iff using a {@code surface} with this {@code format} will be - * supported with {@link CameraDevice#configureOutputs} + * supported with {@link CameraDevice#createCaptureSession} * * @throws IllegalArgumentException * if the image format was not a defined named constant @@ -176,7 +178,7 @@ public final class StreamConfigurationMap { * * @see ImageFormat * @see PixelFormat - * @see CameraDevice#configureOutputs + * @see CameraDevice#createCaptureSession */ public boolean isOutputSupportedFor(int format) { checkArgumentFormat(format); @@ -210,7 +212,7 @@ public final class StreamConfigurationMap { * * <p>Generally speaking this means that creating a {@link Surface} from that class <i>may</i> * provide a producer endpoint that is suitable to be used with - * {@link CameraDevice#configureOutputs}.</p> + * {@link CameraDevice#createCaptureSession}.</p> * * <p>Since not all of the above classes support output of all format and size combinations, * the particular combination should be queried with {@link #isOutputSupportedFor(Surface)}.</p> @@ -220,7 +222,7 @@ public final class StreamConfigurationMap { * * @throws NullPointerException if {@code klass} was {@code null} * - * @see CameraDevice#configureOutputs + * @see CameraDevice#createCaptureSession * @see #isOutputSupportedFor(Surface) */ public static <T> boolean isOutputSupportedFor(Class<T> klass) { @@ -244,8 +246,8 @@ public final class StreamConfigurationMap { } /** - * Determine whether or not the {@code surface} in its current state is suitable to be - * {@link CameraDevice#configureOutputs configured} as an output. + * Determine whether or not the {@code surface} in its current state is suitable to be included + * in a {@link CameraDevice#createCaptureSession capture session} as an output. * * <p>Not all surfaces are usable with the {@link CameraDevice}, and not all configurations * of that {@code surface} are compatible. Some classes that provide the {@code surface} are @@ -269,7 +271,7 @@ public final class StreamConfigurationMap { * * @throws NullPointerException if {@code surface} was {@code null} * - * @see CameraDevice#configureOutputs + * @see CameraDevice#createCaptureSession * @see #isOutputSupportedFor(Class) */ public boolean isOutputSupportedFor(Surface surface) { diff --git a/core/java/android/net/RouteInfo.java b/core/java/android/net/RouteInfo.java index af27e1d..8b42bcd 100644 --- a/core/java/android/net/RouteInfo.java +++ b/core/java/android/net/RouteInfo.java @@ -361,7 +361,7 @@ public class RouteInfo implements Parcelable { RouteInfo target = (RouteInfo) obj; - return Objects.equals(mDestination, target.getDestination()) && + return Objects.equals(mDestination, target.getDestinationLinkAddress()) && Objects.equals(mGateway, target.getGateway()) && Objects.equals(mInterface, target.getInterface()); } diff --git a/core/java/android/provider/Browser.java b/core/java/android/provider/Browser.java index fa85903..3853003 100644 --- a/core/java/android/provider/Browser.java +++ b/core/java/android/provider/Browser.java @@ -156,8 +156,8 @@ public class Browser { * @param title Title for the bookmark. Can be null or empty string. * @param url Url for the bookmark. Can be null or empty string. */ - public static final void saveBookmark(Context c, - String title, + public static final void saveBookmark(Context c, + String title, String url) { Intent i = new Intent(Intent.ACTION_INSERT, Browser.BOOKMARKS_URI); i.putExtra("title", title); @@ -234,10 +234,10 @@ public class Browser { * * @param cr The ContentResolver used to access the database. */ - public static final Cursor getAllBookmarks(ContentResolver cr) throws + public static final Cursor getAllBookmarks(ContentResolver cr) throws IllegalStateException { return cr.query(Bookmarks.CONTENT_URI, - new String[] { Bookmarks.URL }, + new String[] { Bookmarks.URL }, Bookmarks.IS_FOLDER + " = 0", null, null); } @@ -398,24 +398,17 @@ public class Browser { // TODO make a single request to the provider to do this in a single transaction Cursor cursor = null; try { - + // Select non-bookmark history, ordered by date cursor = cr.query(History.CONTENT_URI, new String[] { History._ID, History.URL, History.DATE_LAST_VISITED }, null, null, History.DATE_LAST_VISITED + " ASC"); if (cursor.moveToFirst() && cursor.getCount() >= MAX_HISTORY_COUNT) { - WebIconDatabase iconDb = null; - if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.KITKAT) { - iconDb = WebIconDatabase.getInstance(); - } /* eliminate oldest history items */ for (int i = 0; i < TRUNCATE_N_OLDEST; i++) { cr.delete(ContentUris.withAppendedId(History.CONTENT_URI, cursor.getLong(0)), null, null); - if (iconDb != null) { - iconDb.releaseIconForPageUrl(cursor.getString(1)); - } if (!cursor.moveToNext()) break; } } @@ -475,18 +468,6 @@ public class Browser { cursor = cr.query(History.CONTENT_URI, new String[] { History.URL }, whereClause, null, null); if (cursor.moveToFirst()) { - WebIconDatabase iconDb = null; - if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.KITKAT) { - iconDb = WebIconDatabase.getInstance(); - } - do { - // Delete favicons - // TODO don't release if the URL is bookmarked - if (iconDb != null) { - iconDb.releaseIconForPageUrl(cursor.getString(0)); - } - } while (cursor.moveToNext()); - cr.delete(History.CONTENT_URI, whereClause, null); } } catch (IllegalStateException e) { @@ -531,7 +512,7 @@ public class Browser { * @param cr The ContentResolver used to access the database. * @param url url to remove. */ - public static final void deleteFromHistory(ContentResolver cr, + public static final void deleteFromHistory(ContentResolver cr, String url) { cr.delete(History.CONTENT_URI, History.URL + "=?", new String[] { url }); } @@ -565,7 +546,7 @@ public class Browser { Log.e(LOGTAG, "clearSearches", e); } } - + /** * Request all icons from the database. This call must either be called * in the main thread or have had Looper.prepare() invoked in the calling @@ -574,14 +555,12 @@ public class Browser { * @param cr The ContentResolver used to access the database. * @param where Clause to be used to limit the query from the database. * Must be an allowable string to be passed into a database query. - * @param listener IconListener that gets the icons once they are + * @param listener IconListener that gets the icons once they are * retrieved. */ public static final void requestAllIcons(ContentResolver cr, String where, WebIconDatabase.IconListener listener) { - if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.KITKAT) { - WebIconDatabase.getInstance().bulkRequestIconForPageUrl(cr, where, listener); - } + // Do nothing: this is no longer used. } /** diff --git a/core/java/android/provider/Settings.java b/core/java/android/provider/Settings.java index bec401e..1001677 100644 --- a/core/java/android/provider/Settings.java +++ b/core/java/android/provider/Settings.java @@ -791,6 +791,15 @@ public final class Settings { @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_PAIRING_SETTINGS = "android.settings.PAIRING_SETTINGS"; + /** + * Activity Action: Show battery saver settings. + * + * @hide + */ + @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) + public static final String ACTION_BATTERY_SAVER_SETTINGS + = "android.settings.BATTERY_SAVER_SETTINGS"; + // End of Intent actions for Settings /** @@ -6024,6 +6033,13 @@ public final class Settings { */ public static final String LOW_POWER_MODE = "low_power"; + /** + * 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"; + /** * If 1, the activity manager will aggressively finish activities and * processes as soon as they are no longer needed. If 0, the normal 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/service/voice/DspInfo.java b/core/java/android/service/voice/DspInfo.java new file mode 100644 index 0000000..0862309 --- /dev/null +++ b/core/java/android/service/voice/DspInfo.java @@ -0,0 +1,56 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.service.voice; + +import java.util.UUID; + +/** + * Properties of the DSP hardware on the device. + * @hide + */ +public class DspInfo { + /** + * Unique voice engine Id (changes with each version). + */ + public final UUID voiceEngineId; + + /** + * Human readable voice detection engine implementor. + */ + public final String voiceEngineImplementor; + /** + * Human readable voice detection engine description. + */ + public final String voiceEngineDescription; + /** + * Human readable voice detection engine version + */ + public final int voiceEngineVersion; + /** + * Rated power consumption when detection is active. + */ + public final int powerConsumptionMw; + + public DspInfo(UUID voiceEngineId, String voiceEngineImplementor, + String voiceEngineDescription, int version, int powerConsumptionMw) { + this.voiceEngineId = voiceEngineId; + this.voiceEngineImplementor = voiceEngineImplementor; + this.voiceEngineDescription = voiceEngineDescription; + this.voiceEngineVersion = version; + this.powerConsumptionMw = powerConsumptionMw; + } +} diff --git a/core/java/android/service/voice/KeyphraseEnrollmentInfo.java b/core/java/android/service/voice/KeyphraseEnrollmentInfo.java new file mode 100644 index 0000000..ebe41ce --- /dev/null +++ b/core/java/android/service/voice/KeyphraseEnrollmentInfo.java @@ -0,0 +1,246 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.service.voice; + +import android.Manifest; +import android.content.Intent; +import android.content.pm.ApplicationInfo; +import android.content.pm.PackageManager; +import android.content.pm.ResolveInfo; +import android.content.res.Resources; +import android.content.res.TypedArray; +import android.content.res.XmlResourceParser; +import android.util.AttributeSet; +import android.util.Slog; +import android.util.Xml; + +import org.xmlpull.v1.XmlPullParser; +import org.xmlpull.v1.XmlPullParserException; + +import java.io.IOException; +import java.util.List; + +/** @hide */ +public class KeyphraseEnrollmentInfo { + private static final String TAG = "KeyphraseEnrollmentInfo"; + /** + * Name under which a Hotword enrollment component publishes information about itself. + * This meta-data should reference an XML resource containing a + * <code><{@link + * android.R.styleable#VoiceEnrollmentApplication + * voice-enrollment-application}></code> tag. + */ + private static final String VOICE_KEYPHRASE_META_DATA = "android.voice_enrollment"; + /** + * Activity Action: Show activity for managing the keyphrases for hotword detection. + * This needs to be defined by an activity that supports enrolling users for hotword/keyphrase + * detection. + */ + public static final String ACTION_MANAGE_VOICE_KEYPHRASES = + "com.android.intent.action.MANAGE_VOICE_KEYPHRASES"; + /** + * Intent extra: The intent extra for un-enrolling a user for a particular keyphrase. + */ + public static final String EXTRA_VOICE_KEYPHRASE_UNENROLL = + "com.android.intent.extra.VOICE_KEYPHRASE_UNENROLL"; + /** + * Intent extra: The hint text to be shown on the voice keyphrase management UI. + */ + public static final String EXTRA_VOICE_KEYPHRASE_HINT_TEXT = + "com.android.intent.extra.VOICE_KEYPHRASE_HINT_TEXT"; + /** + * Intent extra: The voice locale to use while managing the keyphrase. + */ + public static final String EXTRA_VOICE_KEYPHRASE_LOCALE = + "com.android.intent.extra.VOICE_KEYPHRASE_LOCALE"; + + private KeyphraseInfo[] mKeyphrases; + private String mEnrollmentPackage; + private String mParseError; + + public KeyphraseEnrollmentInfo(PackageManager pm) { + // Find the apps that supports enrollment for hotword keyhphrases, + // Pick a privileged app and obtain the information about the supported keyphrases + // from its metadata. + List<ResolveInfo> ris = pm.queryIntentActivities( + new Intent(ACTION_MANAGE_VOICE_KEYPHRASES), PackageManager.MATCH_DEFAULT_ONLY); + if (ris == null || ris.isEmpty()) { + // No application capable of enrolling for voice keyphrases is present. + mParseError = "No enrollment application found"; + return; + } + + boolean found = false; + ApplicationInfo ai = null; + for (ResolveInfo ri : ris) { + try { + ai = pm.getApplicationInfo( + ri.activityInfo.packageName, PackageManager.GET_META_DATA); + if ((ai.flags & ApplicationInfo.FLAG_PRIVILEGED) == 0) { + // The application isn't privileged (/system/priv-app). + // The enrollment application needs to be a privileged system app. + Slog.w(TAG, ai.packageName + "is not a privileged system app"); + continue; + } + if (!Manifest.permission.MANAGE_VOICE_KEYPHRASES.equals(ai.permission)) { + // The application trying to manage keyphrases doesn't + // require the MANAGE_VOICE_KEYPHRASES permission. + Slog.w(TAG, ai.packageName + " does not require MANAGE_VOICE_KEYPHRASES"); + continue; + } + mEnrollmentPackage = ai.packageName; + found = true; + break; + } catch (PackageManager.NameNotFoundException e) { + Slog.w(TAG, "error parsing voice enrollment meta-data", e); + } + } + + if (!found) { + mKeyphrases = null; + mParseError = "No suitable enrollment application found"; + return; + } + + XmlResourceParser parser = null; + try { + parser = ai.loadXmlMetaData(pm, VOICE_KEYPHRASE_META_DATA); + if (parser == null) { + mParseError = "No " + VOICE_KEYPHRASE_META_DATA + " meta-data for " + + ai.packageName; + return; + } + + Resources res = pm.getResourcesForApplication(ai); + AttributeSet attrs = Xml.asAttributeSet(parser); + + int type; + while ((type=parser.next()) != XmlPullParser.END_DOCUMENT + && type != XmlPullParser.START_TAG) { + } + + String nodeName = parser.getName(); + if (!"voice-enrollment-application".equals(nodeName)) { + mParseError = "Meta-data does not start with voice-enrollment-application tag"; + return; + } + + TypedArray array = res.obtainAttributes(attrs, + com.android.internal.R.styleable.VoiceEnrollmentApplication); + int searchKeyphraseId = array.getInt( + com.android.internal.R.styleable.VoiceEnrollmentApplication_searchKeyphraseId, + -1); + if (searchKeyphraseId != -1) { + String searchKeyphrase = array.getString(com.android.internal.R.styleable + .VoiceEnrollmentApplication_searchKeyphrase); + String searchKeyphraseSupportedLocales = + array.getString(com.android.internal.R.styleable + .VoiceEnrollmentApplication_searchKeyphraseSupportedLocales); + String[] supportedLocales = new String[0]; + // Get all the supported locales from the comma-delimted string. + if (searchKeyphraseSupportedLocales != null + && !searchKeyphraseSupportedLocales.isEmpty()) { + supportedLocales = searchKeyphraseSupportedLocales.split(","); + } + mKeyphrases = new KeyphraseInfo[1]; + mKeyphrases[0] = new KeyphraseInfo( + searchKeyphraseId, searchKeyphrase, supportedLocales); + } else { + mParseError = "searchKeyphraseId not specified in meta-data"; + return; + } + } catch (XmlPullParserException e) { + mParseError = "Error parsing keyphrase enrollment meta-data: " + e; + Slog.w(TAG, "error parsing keyphrase enrollment meta-data", e); + return; + } catch (IOException e) { + mParseError = "Error parsing keyphrase enrollment meta-data: " + e; + Slog.w(TAG, "error parsing keyphrase enrollment meta-data", e); + return; + } catch (PackageManager.NameNotFoundException e) { + mParseError = "Error parsing keyphrase enrollment meta-data: " + e; + Slog.w(TAG, "error parsing keyphrase enrollment meta-data", e); + return; + } finally { + if (parser != null) parser.close(); + } + } + + public String getParseError() { + return mParseError; + } + + /** + * @return An array of available keyphrases that can be enrolled on the system. + * It may be null if no keyphrases can be enrolled. + */ + public KeyphraseInfo[] getKeyphrases() { + return mKeyphrases; + } + + /** + * Returns an intent to launch an activity that manages the given keyphrase + * for the locale. + * + * @param enroll Indicates if the intent should enroll the user or un-enroll them. + * @param keyphrase The keyphrase that the user needs to be enrolled to. + * @param locale The locale for which the enrollment needs to be performed. + * @return An {@link Intent} to manage the keyphrase. This can be null if managing the + * given keyphrase/locale combination isn't possible. + */ + public Intent getManageKeyphraseIntent(boolean enroll, String keyphrase, String locale) { + if (mEnrollmentPackage == null || mEnrollmentPackage.isEmpty()) { + Slog.w(TAG, "No enrollment application exists"); + return null; + } + + if (isKeyphraseEnrollmentSupported(keyphrase, locale)) { + Intent intent = new Intent(ACTION_MANAGE_VOICE_KEYPHRASES) + .setPackage(mEnrollmentPackage) + .putExtra(EXTRA_VOICE_KEYPHRASE_HINT_TEXT, keyphrase) + .putExtra(EXTRA_VOICE_KEYPHRASE_LOCALE, locale); + if (!enroll) intent.putExtra(EXTRA_VOICE_KEYPHRASE_UNENROLL, true); + return intent; + } + return null; + } + + /** + * Indicates if enrollment is supported for the given keyphrase & locale. + * + * @param keyphrase The keyphrase that the user needs to be enrolled to. + * @param locale The locale for which the enrollment needs to be performed. + * @return true, if an enrollment client supports the given keyphrase and the given locale. + */ + public boolean isKeyphraseEnrollmentSupported(String keyphrase, String locale) { + if (mKeyphrases == null || mKeyphrases.length == 0) { + Slog.w(TAG, "Enrollment application doesn't support keyphrases"); + return false; + } + for (KeyphraseInfo keyphraseInfo : mKeyphrases) { + // Check if the given keyphrase is supported in the locale provided by + // the enrollment application. + String supportedKeyphrase = keyphraseInfo.keyphrase; + if (supportedKeyphrase.equalsIgnoreCase(keyphrase) + && keyphraseInfo.supportedLocales.contains(locale)) { + return true; + } + } + Slog.w(TAG, "Enrollment application doesn't support the given keyphrase"); + return false; + } +} diff --git a/core/java/android/service/voice/KeyphraseInfo.java b/core/java/android/service/voice/KeyphraseInfo.java new file mode 100644 index 0000000..d266e1a --- /dev/null +++ b/core/java/android/service/voice/KeyphraseInfo.java @@ -0,0 +1,27 @@ +package android.service.voice; + +import android.util.ArraySet; + +/** + * A Voice Keyphrase. + * @hide + */ +public class KeyphraseInfo { + public final int id; + public final String keyphrase; + public final ArraySet<String> supportedLocales; + + public KeyphraseInfo(int id, String keyphrase, String[] supportedLocales) { + this.id = id; + this.keyphrase = keyphrase; + this.supportedLocales = new ArraySet<String>(supportedLocales.length); + for (String locale : supportedLocales) { + this.supportedLocales.add(locale); + } + } + + @Override + public String toString() { + return "id=" + id + ", keyphrase=" + keyphrase + ", supported-locales=" + supportedLocales; + } +} diff --git a/core/java/android/service/voice/SoundTriggerManager.java b/core/java/android/service/voice/SoundTriggerManager.java new file mode 100644 index 0000000..2d049b9 --- /dev/null +++ b/core/java/android/service/voice/SoundTriggerManager.java @@ -0,0 +1,73 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.service.voice; + +import android.hardware.soundtrigger.SoundTrigger; +import android.hardware.soundtrigger.SoundTrigger.ModuleProperties; + +import java.util.ArrayList; + +/** + * Manager for {@link SoundTrigger} APIs. + * Currently this just acts as an abstraction over all SoundTrigger API calls. + * @hide + */ +public class SoundTriggerManager { + /** The {@link DspInfo} for the system, or null if none exists. */ + public DspInfo dspInfo; + + public SoundTriggerManager() { + ArrayList <ModuleProperties> modules = new ArrayList<>(); + int status = SoundTrigger.listModules(modules); + if (status != SoundTrigger.STATUS_OK || modules.size() == 0) { + // TODO(sansid, elaurent): Figure out how to handle errors in listing the modules here. + dspInfo = null; + } else { + // TODO(sansid, elaurent): Figure out how to determine which module corresponds to the + // DSP hardware. + ModuleProperties properties = modules.get(0); + dspInfo = new DspInfo(properties.uuid, properties.implementor, properties.description, + properties.version, properties.powerConsumptionMw); + } + } + + /** + * @return True, if the keyphrase is supported on DSP for the given locale. + */ + public boolean isKeyphraseSupported(String keyphrase, String locale) { + // TODO(sansid): We also need to look into a SoundTrigger API that let's us + // query this. For now just return supported if there's a DSP available. + return dspInfo != null; + } + + /** + * @return True, if the keyphrase is has been enrolled for the given locale. + */ + public boolean isKeyphraseEnrolled(String keyphrase, String locale) { + // TODO(sansid, elaurent): Query SoundTrigger to list currently loaded sound models. + // They have been enrolled. + return false; + } + + /** + * @return True, if a recognition for the keyphrase is active for the given locale. + */ + public boolean isKeyphraseActive(String keyphrase, String locale) { + // TODO(sansid, elaurent): Check if the recognition for the keyphrase is currently active. + return false; + } +} diff --git a/core/java/android/service/voice/VoiceInteractionService.java b/core/java/android/service/voice/VoiceInteractionService.java index e15489b..e0329f8 100644 --- a/core/java/android/service/voice/VoiceInteractionService.java +++ b/core/java/android/service/voice/VoiceInteractionService.java @@ -17,7 +17,6 @@ package android.service.voice; import android.annotation.SdkConstant; -import android.app.Instrumentation; import android.app.Service; import android.content.Context; import android.content.Intent; @@ -25,8 +24,11 @@ import android.os.Bundle; import android.os.IBinder; import android.os.RemoteException; import android.os.ServiceManager; + +import com.android.internal.annotations.VisibleForTesting; import com.android.internal.app.IVoiceInteractionManagerService; + /** * Top-level service of the current global voice interactor, which is providing * support for hotwording, the back-end of a {@link android.app.VoiceInteractor}, etc. @@ -51,6 +53,16 @@ public class VoiceInteractionService extends Service { public static final String SERVICE_INTERFACE = "android.service.voice.VoiceInteractionService"; + // TODO(sansid): Unhide these. + /** @hide */ + public static final int KEYPHRASE_UNAVAILABLE = 0; + /** @hide */ + public static final int KEYPHRASE_UNENROLLED = 1; + /** @hide */ + public static final int KEYPHRASE_ENROLLED = 2; + /** @hide */ + public static final int KEYPHRASE_ACTIVE = 3; + /** * Name under which a VoiceInteractionService component publishes information about itself. * This meta-data should reference an XML resource containing a @@ -64,6 +76,9 @@ public class VoiceInteractionService extends Service { IVoiceInteractionManagerService mSystemService; + private SoundTriggerManager mSoundTriggerManager; + private KeyphraseEnrollmentInfo mKeyphraseEnrollmentInfo; + public void startSession(Bundle args) { try { mSystemService.startSession(mInterface, args); @@ -76,6 +91,8 @@ public class VoiceInteractionService extends Service { super.onCreate(); mSystemService = IVoiceInteractionManagerService.Stub.asInterface( ServiceManager.getService(Context.VOICE_INTERACTION_MANAGER_SERVICE)); + mKeyphraseEnrollmentInfo = new KeyphraseEnrollmentInfo(getPackageManager()); + mSoundTriggerManager = new SoundTriggerManager(); } @Override @@ -85,4 +102,44 @@ public class VoiceInteractionService extends Service { } return null; } + + /** + * Gets the state of always-on hotword detection for the given keyphrase and locale + * on this system. + * Availability implies that the hardware on this system is capable of listening for + * the given keyphrase or not. + * The return code is one of {@link #KEYPHRASE_UNAVAILABLE}, {@link #KEYPHRASE_UNENROLLED} + * {@link #KEYPHRASE_ENROLLED} or {@link #KEYPHRASE_ACTIVE}. + * + * @param keyphrase The keyphrase whose availability is being checked. + * @param locale The locale for which the availability is being checked. + * @return Indicates if always-on hotword detection is available for the given keyphrase. + * TODO(sansid): Unhide this. + * @hide + */ + public final int getAlwaysOnKeyphraseAvailability(String keyphrase, String locale) { + // The available keyphrases is a combination of DSP availability and + // the keyphrases that have an enrollment application for them. + if (!mSoundTriggerManager.isKeyphraseSupported(keyphrase, locale) + || !mKeyphraseEnrollmentInfo.isKeyphraseEnrollmentSupported(keyphrase, locale)) { + return KEYPHRASE_UNAVAILABLE; + } + if (!mSoundTriggerManager.isKeyphraseEnrolled(keyphrase, locale)) { + return KEYPHRASE_UNENROLLED; + } + if (!mSoundTriggerManager.isKeyphraseActive(keyphrase, locale)) { + return KEYPHRASE_ENROLLED; + } else { + return KEYPHRASE_ACTIVE; + } + } + + /** + * @return Details of keyphrases available for enrollment. + * @hide + */ + @VisibleForTesting + protected final KeyphraseEnrollmentInfo getKeyphraseEnrollmentInfo() { + return mKeyphraseEnrollmentInfo; + } } diff --git a/core/java/android/speech/tts/RequestConfig.java b/core/java/android/speech/tts/RequestConfig.java index 4b5385f..84880c0 100644 --- a/core/java/android/speech/tts/RequestConfig.java +++ b/core/java/android/speech/tts/RequestConfig.java @@ -1,3 +1,18 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ package android.speech.tts; import android.media.AudioManager; diff --git a/core/java/android/speech/tts/RequestConfigHelper.java b/core/java/android/speech/tts/RequestConfigHelper.java index b25c985..3b5490b 100644 --- a/core/java/android/speech/tts/RequestConfigHelper.java +++ b/core/java/android/speech/tts/RequestConfigHelper.java @@ -1,3 +1,18 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ package android.speech.tts; import android.speech.tts.TextToSpeechClient.EngineStatus; diff --git a/core/java/android/speech/tts/SynthesisRequestV2.java b/core/java/android/speech/tts/SynthesisRequestV2.java index 130e3f9..a42aa16 100644 --- a/core/java/android/speech/tts/SynthesisRequestV2.java +++ b/core/java/android/speech/tts/SynthesisRequestV2.java @@ -1,3 +1,18 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ package android.speech.tts; import android.os.Bundle; diff --git a/core/java/android/speech/tts/VoiceInfo.java b/core/java/android/speech/tts/VoiceInfo.java index 16b9a97..71629dc 100644 --- a/core/java/android/speech/tts/VoiceInfo.java +++ b/core/java/android/speech/tts/VoiceInfo.java @@ -1,3 +1,18 @@ +/* + * Copyright (C) 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ package android.speech.tts; import android.os.Bundle; diff --git a/core/java/android/text/util/Linkify.java b/core/java/android/text/util/Linkify.java index deb138d..c1341e1 100644 --- a/core/java/android/text/util/Linkify.java +++ b/core/java/android/text/util/Linkify.java @@ -465,32 +465,39 @@ public class Linkify { String address; int base = 0; - while ((address = WebView.findAddress(string)) != null) { - int start = string.indexOf(address); + try { + while ((address = WebView.findAddress(string)) != null) { + int start = string.indexOf(address); - if (start < 0) { - break; - } + if (start < 0) { + break; + } - LinkSpec spec = new LinkSpec(); - int length = address.length(); - int end = start + length; - - spec.start = base + start; - spec.end = base + end; - string = string.substring(end); - base += end; - - String encodedAddress = null; - - try { - encodedAddress = URLEncoder.encode(address,"UTF-8"); - } catch (UnsupportedEncodingException e) { - continue; - } + LinkSpec spec = new LinkSpec(); + int length = address.length(); + int end = start + length; - spec.url = "geo:0,0?q=" + encodedAddress; - links.add(spec); + spec.start = base + start; + spec.end = base + end; + string = string.substring(end); + base += end; + + String encodedAddress = null; + + try { + encodedAddress = URLEncoder.encode(address,"UTF-8"); + } catch (UnsupportedEncodingException e) { + continue; + } + + spec.url = "geo:0,0?q=" + encodedAddress; + links.add(spec); + } + } catch (UnsupportedOperationException e) { + // findAddress may fail with an unsupported exception on platforms without a WebView. + // In this case, we will not append anything to the links variable: it would have died + // in WebView.findAddress. + return; } } diff --git a/core/java/android/transition/Transition.java b/core/java/android/transition/Transition.java index e9c2bba..0a4f641 100644 --- a/core/java/android/transition/Transition.java +++ b/core/java/android/transition/Transition.java @@ -603,76 +603,76 @@ public abstract class Transition implements Cloneable { for (int i = 0; i < startValuesList.size(); ++i) { TransitionValues start = startValuesList.get(i); TransitionValues end = endValuesList.get(i); - // Only bother trying to animate with values that differ between start/end - if (start != null || end != null) { - if (start == null || !start.equals(end)) { - if (DBG) { - View view = (end != null) ? end.view : start.view; - Log.d(LOG_TAG, " differing start/end values for view " + - view); - if (start == null || end == null) { - Log.d(LOG_TAG, " " + ((start == null) ? - "start null, end non-null" : "start non-null, end null")); - } else { - for (String key : start.values.keySet()) { - Object startValue = start.values.get(key); - Object endValue = end.values.get(key); - if (startValue != endValue && !startValue.equals(endValue)) { - Log.d(LOG_TAG, " " + key + ": start(" + startValue + - "), end(" + endValue +")"); - } + // Only bother trying to animate with valid values that differ between start/end + boolean isInvalidStart = start != null && !isValidTarget(start.view); + boolean isInvalidEnd = end != null && !isValidTarget(end.view); + boolean isChanged = start != end && (start == null || !start.equals(end)); + if (isChanged && !isInvalidStart && !isInvalidEnd) { + if (DBG) { + View view = (end != null) ? end.view : start.view; + Log.d(LOG_TAG, " differing start/end values for view " + view); + if (start == null || end == null) { + Log.d(LOG_TAG, " " + ((start == null) ? + "start null, end non-null" : "start non-null, end null")); + } else { + for (String key : start.values.keySet()) { + Object startValue = start.values.get(key); + Object endValue = end.values.get(key); + if (startValue != endValue && !startValue.equals(endValue)) { + Log.d(LOG_TAG, " " + key + ": start(" + startValue + + "), end(" + endValue + ")"); } } } - // TODO: what to do about targetIds and itemIds? - Animator animator = createAnimator(sceneRoot, start, end); - if (animator != null) { - // Save animation info for future cancellation purposes - View view = null; - TransitionValues infoValues = null; - if (end != null) { - view = end.view; - String[] properties = getTransitionProperties(); - if (view != null && properties != null && properties.length > 0) { - infoValues = new TransitionValues(); - infoValues.view = view; - TransitionValues newValues = endValues.viewValues.get(view); - if (newValues != null) { - for (int j = 0; j < properties.length; ++j) { - infoValues.values.put(properties[j], - newValues.values.get(properties[j])); - } + } + // TODO: what to do about targetIds and itemIds? + Animator animator = createAnimator(sceneRoot, start, end); + if (animator != null) { + // Save animation info for future cancellation purposes + View view = null; + TransitionValues infoValues = null; + if (end != null) { + view = end.view; + String[] properties = getTransitionProperties(); + if (view != null && properties != null && properties.length > 0) { + infoValues = new TransitionValues(); + infoValues.view = view; + TransitionValues newValues = endValues.viewValues.get(view); + if (newValues != null) { + for (int j = 0; j < properties.length; ++j) { + infoValues.values.put(properties[j], + newValues.values.get(properties[j])); } - int numExistingAnims = runningAnimators.size(); - for (int j = 0; j < numExistingAnims; ++j) { - Animator anim = runningAnimators.keyAt(j); - AnimationInfo info = runningAnimators.get(anim); - if (info.values != null && info.view == view && - ((info.name == null && getName() == null) || - info.name.equals(getName()))) { - if (info.values.equals(infoValues)) { - // Favor the old animator - animator = null; - break; - } + } + int numExistingAnims = runningAnimators.size(); + for (int j = 0; j < numExistingAnims; ++j) { + Animator anim = runningAnimators.keyAt(j); + AnimationInfo info = runningAnimators.get(anim); + if (info.values != null && info.view == view && + ((info.name == null && getName() == null) || + info.name.equals(getName()))) { + if (info.values.equals(infoValues)) { + // Favor the old animator + animator = null; + break; } } } - } else { - view = (start != null) ? start.view : null; } - if (animator != null) { - if (mPropagation != null) { - long delay = mPropagation - .getStartDelay(sceneRoot, this, start, end); - startDelays.put(mAnimators.size(), delay); - minStartDelay = Math.min(delay, minStartDelay); - } - AnimationInfo info = new AnimationInfo(view, getName(), - sceneRoot.getWindowId(), infoValues); - runningAnimators.put(animator, info); - mAnimators.add(animator); + } else { + view = (start != null) ? start.view : null; + } + if (animator != null) { + if (mPropagation != null) { + long delay = mPropagation + .getStartDelay(sceneRoot, this, start, end); + startDelays.put(mAnimators.size(), delay); + minStartDelay = Math.min(delay, minStartDelay); } + AnimationInfo info = new AnimationInfo(view, getName(), + sceneRoot.getWindowId(), infoValues); + runningAnimators.put(animator, info); + mAnimators.add(animator); } } } 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++) { |