CaptureRequest.java revision 97f1c854993a65b2c700426a1e3a83b23ea65337
1/*
2 * Copyright (C) 2013 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.camera2;
18
19import android.hardware.camera2.CameraCharacteristics.Key;
20import android.hardware.camera2.impl.CameraMetadataNative;
21import android.hardware.camera2.utils.TypeReference;
22import android.os.Parcel;
23import android.os.Parcelable;
24import android.util.Rational;
25import android.view.Surface;
26
27import java.util.Collection;
28import java.util.Collections;
29import java.util.HashSet;
30import java.util.List;
31import java.util.Objects;
32
33
34/**
35 * <p>An immutable package of settings and outputs needed to capture a single
36 * image from the camera device.</p>
37 *
38 * <p>Contains the configuration for the capture hardware (sensor, lens, flash),
39 * the processing pipeline, the control algorithms, and the output buffers. Also
40 * contains the list of target Surfaces to send image data to for this
41 * capture.</p>
42 *
43 * <p>CaptureRequests can be created by using a {@link Builder} instance,
44 * obtained by calling {@link CameraDevice#createCaptureRequest}</p>
45 *
46 * <p>CaptureRequests are given to {@link CameraDevice#capture} or
47 * {@link CameraDevice#setRepeatingRequest} to capture images from a camera.</p>
48 *
49 * <p>Each request can specify a different subset of target Surfaces for the
50 * camera to send the captured data to. All the surfaces used in a request must
51 * be part of the surface list given to the last call to
52 * {@link CameraDevice#configureOutputs}, when the request is submitted to the
53 * camera device.</p>
54 *
55 * <p>For example, a request meant for repeating preview might only include the
56 * Surface for the preview SurfaceView or SurfaceTexture, while a
57 * high-resolution still capture would also include a Surface from a ImageReader
58 * configured for high-resolution JPEG images.</p>
59 *
60 * @see CameraDevice#capture
61 * @see CameraDevice#setRepeatingRequest
62 * @see CameraDevice#createCaptureRequest
63 */
64public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
65        implements Parcelable {
66
67    /**
68     * A {@code Key} is used to do capture request field lookups with
69     * {@link CaptureResult#get} or to set fields with
70     * {@link CaptureRequest.Builder#set(Key, Object)}.
71     *
72     * <p>For example, to set the crop rectangle for the next capture:
73     * <code><pre>
74     * Rect cropRectangle = new Rect(0, 0, 640, 480);
75     * captureRequestBuilder.set(SCALER_CROP_REGION, cropRectangle);
76     * </pre></code>
77     * </p>
78     *
79     * <p>To enumerate over all possible keys for {@link CaptureResult}, see
80     * {@link CameraCharacteristics#getAvailableCaptureResultKeys}.</p>
81     *
82     * @see CaptureResult#get
83     * @see CameraCharacteristics#getAvailableCaptureResultKeys
84     */
85    public final static class Key<T> {
86        private final CameraMetadataNative.Key<T> mKey;
87
88        /**
89         * Visible for testing and vendor extensions only.
90         *
91         * @hide
92         */
93        public Key(String name, Class<T> type) {
94            mKey = new CameraMetadataNative.Key<T>(name, type);
95        }
96
97        /**
98         * Visible for testing and vendor extensions only.
99         *
100         * @hide
101         */
102        public Key(String name, TypeReference<T> typeReference) {
103            mKey = new CameraMetadataNative.Key<T>(name, typeReference);
104        }
105
106        /**
107         * Return a camelCase, period separated name formatted like:
108         * {@code "root.section[.subsections].name"}.
109         *
110         * <p>Built-in keys exposed by the Android SDK are always prefixed with {@code "android."};
111         * keys that are device/platform-specific are prefixed with {@code "com."}.</p>
112         *
113         * <p>For example, {@code CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP} would
114         * have a name of {@code "android.scaler.streamConfigurationMap"}; whereas a device
115         * specific key might look like {@code "com.google.nexus.data.private"}.</p>
116         *
117         * @return String representation of the key name
118         */
119        public String getName() {
120            return mKey.getName();
121        }
122
123        /**
124         * {@inheritDoc}
125         */
126        @Override
127        public final int hashCode() {
128            return mKey.hashCode();
129        }
130
131        /**
132         * {@inheritDoc}
133         */
134        @SuppressWarnings("unchecked")
135        @Override
136        public final boolean equals(Object o) {
137            return o instanceof Key && ((Key<T>)o).mKey.equals(mKey);
138        }
139
140        /**
141         * Visible for CameraMetadataNative implementation only; do not use.
142         *
143         * TODO: Make this private or remove it altogether.
144         *
145         * @hide
146         */
147        public CameraMetadataNative.Key<T> getNativeKey() {
148            return mKey;
149        }
150
151        @SuppressWarnings({ "unchecked" })
152        /*package*/ Key(CameraMetadataNative.Key<?> nativeKey) {
153            mKey = (CameraMetadataNative.Key<T>) nativeKey;
154        }
155    }
156
157    private final HashSet<Surface> mSurfaceSet;
158    private final CameraMetadataNative mSettings;
159
160    private Object mUserTag;
161
162    /**
163     * Construct empty request.
164     *
165     * Used by Binder to unparcel this object only.
166     */
167    private CaptureRequest() {
168        mSettings = new CameraMetadataNative();
169        mSurfaceSet = new HashSet<Surface>();
170    }
171
172    /**
173     * Clone from source capture request.
174     *
175     * Used by the Builder to create an immutable copy.
176     */
177    @SuppressWarnings("unchecked")
178    private CaptureRequest(CaptureRequest source) {
179        mSettings = new CameraMetadataNative(source.mSettings);
180        mSurfaceSet = (HashSet<Surface>) source.mSurfaceSet.clone();
181        mUserTag = source.mUserTag;
182    }
183
184    /**
185     * Take ownership of passed-in settings.
186     *
187     * Used by the Builder to create a mutable CaptureRequest.
188     */
189    private CaptureRequest(CameraMetadataNative settings) {
190        mSettings = CameraMetadataNative.move(settings);
191        mSurfaceSet = new HashSet<Surface>();
192    }
193
194    /**
195     * Get a capture request field value.
196     *
197     * <p>The field definitions can be found in {@link CaptureRequest}.</p>
198     *
199     * <p>Querying the value for the same key more than once will return a value
200     * which is equal to the previous queried value.</p>
201     *
202     * @throws IllegalArgumentException if the key was not valid
203     *
204     * @param key The result field to read.
205     * @return The value of that key, or {@code null} if the field is not set.
206     */
207    public <T> T get(Key<T> key) {
208        return mSettings.get(key);
209    }
210
211    /**
212     * {@inheritDoc}
213     * @hide
214     */
215    @SuppressWarnings("unchecked")
216    @Override
217    protected <T> T getProtected(Key<?> key) {
218        return (T) mSettings.get(key);
219    }
220
221    /**
222     * {@inheritDoc}
223     * @hide
224     */
225    @SuppressWarnings("unchecked")
226    @Override
227    protected Class<Key<?>> getKeyClass() {
228        Object thisClass = Key.class;
229        return (Class<Key<?>>)thisClass;
230    }
231
232    /**
233     * {@inheritDoc}
234     */
235    @Override
236    public List<Key<?>> getKeys() {
237        // Force the javadoc for this function to show up on the CaptureRequest page
238        return super.getKeys();
239    }
240
241    /**
242     * Retrieve the tag for this request, if any.
243     *
244     * <p>This tag is not used for anything by the camera device, but can be
245     * used by an application to easily identify a CaptureRequest when it is
246     * returned by
247     * {@link CameraDevice.CaptureListener#onCaptureCompleted CaptureListener.onCaptureCompleted}
248     * </p>
249     *
250     * @return the last tag Object set on this request, or {@code null} if
251     *     no tag has been set.
252     * @see Builder#setTag
253     */
254    public Object getTag() {
255        return mUserTag;
256    }
257
258    /**
259     * Determine whether this CaptureRequest is equal to another CaptureRequest.
260     *
261     * <p>A request is considered equal to another is if it's set of key/values is equal, it's
262     * list of output surfaces is equal, and the user tag is equal.</p>
263     *
264     * @param other Another instance of CaptureRequest.
265     *
266     * @return True if the requests are the same, false otherwise.
267     */
268    @Override
269    public boolean equals(Object other) {
270        return other instanceof CaptureRequest
271                && equals((CaptureRequest)other);
272    }
273
274    private boolean equals(CaptureRequest other) {
275        return other != null
276                && Objects.equals(mUserTag, other.mUserTag)
277                && mSurfaceSet.equals(other.mSurfaceSet)
278                && mSettings.equals(other.mSettings);
279    }
280
281    @Override
282    public int hashCode() {
283        return mSettings.hashCode();
284    }
285
286    public static final Parcelable.Creator<CaptureRequest> CREATOR =
287            new Parcelable.Creator<CaptureRequest>() {
288        @Override
289        public CaptureRequest createFromParcel(Parcel in) {
290            CaptureRequest request = new CaptureRequest();
291            request.readFromParcel(in);
292
293            return request;
294        }
295
296        @Override
297        public CaptureRequest[] newArray(int size) {
298            return new CaptureRequest[size];
299        }
300    };
301
302    /**
303     * Expand this object from a Parcel.
304     * Hidden since this breaks the immutability of CaptureRequest, but is
305     * needed to receive CaptureRequests with aidl.
306     *
307     * @param in The parcel from which the object should be read
308     * @hide
309     */
310    private void readFromParcel(Parcel in) {
311        mSettings.readFromParcel(in);
312
313        mSurfaceSet.clear();
314
315        Parcelable[] parcelableArray = in.readParcelableArray(Surface.class.getClassLoader());
316
317        if (parcelableArray == null) {
318            return;
319        }
320
321        for (Parcelable p : parcelableArray) {
322            Surface s = (Surface) p;
323            mSurfaceSet.add(s);
324        }
325    }
326
327    @Override
328    public int describeContents() {
329        return 0;
330    }
331
332    @Override
333    public void writeToParcel(Parcel dest, int flags) {
334        mSettings.writeToParcel(dest, flags);
335        dest.writeParcelableArray(mSurfaceSet.toArray(new Surface[mSurfaceSet.size()]), flags);
336    }
337
338    /**
339     * @hide
340     */
341    public boolean containsTarget(Surface surface) {
342        return mSurfaceSet.contains(surface);
343    }
344
345    /**
346     * @hide
347     */
348    public Collection<Surface> getTargets() {
349        return Collections.unmodifiableCollection(mSurfaceSet);
350    }
351
352    /**
353     * A builder for capture requests.
354     *
355     * <p>To obtain a builder instance, use the
356     * {@link CameraDevice#createCaptureRequest} method, which initializes the
357     * request fields to one of the templates defined in {@link CameraDevice}.
358     *
359     * @see CameraDevice#createCaptureRequest
360     * @see #TEMPLATE_PREVIEW
361     * @see #TEMPLATE_RECORD
362     * @see #TEMPLATE_STILL_CAPTURE
363     * @see #TEMPLATE_VIDEO_SNAPSHOT
364     * @see #TEMPLATE_MANUAL
365     */
366    public final static class Builder {
367
368        private final CaptureRequest mRequest;
369
370        /**
371         * Initialize the builder using the template; the request takes
372         * ownership of the template.
373         *
374         * @hide
375         */
376        public Builder(CameraMetadataNative template) {
377            mRequest = new CaptureRequest(template);
378        }
379
380        /**
381         * <p>Add a surface to the list of targets for this request</p>
382         *
383         * <p>The Surface added must be one of the surfaces included in the most
384         * recent call to {@link CameraDevice#configureOutputs}, when the
385         * request is given to the camera device.</p>
386         *
387         * <p>Adding a target more than once has no effect.</p>
388         *
389         * @param outputTarget Surface to use as an output target for this request
390         */
391        public void addTarget(Surface outputTarget) {
392            mRequest.mSurfaceSet.add(outputTarget);
393        }
394
395        /**
396         * <p>Remove a surface from the list of targets for this request.</p>
397         *
398         * <p>Removing a target that is not currently added has no effect.</p>
399         *
400         * @param outputTarget Surface to use as an output target for this request
401         */
402        public void removeTarget(Surface outputTarget) {
403            mRequest.mSurfaceSet.remove(outputTarget);
404        }
405
406        /**
407         * Set a capture request field to a value. The field definitions can be
408         * found in {@link CaptureRequest}.
409         *
410         * @param key The metadata field to write.
411         * @param value The value to set the field to, which must be of a matching
412         * type to the key.
413         */
414        public <T> void set(Key<T> key, T value) {
415            mRequest.mSettings.set(key, value);
416        }
417
418        /**
419         * Get a capture request field value. The field definitions can be
420         * found in {@link CaptureRequest}.
421         *
422         * @throws IllegalArgumentException if the key was not valid
423         *
424         * @param key The metadata field to read.
425         * @return The value of that key, or {@code null} if the field is not set.
426         */
427        public <T> T get(Key<T> key) {
428            return mRequest.mSettings.get(key);
429        }
430
431        /**
432         * Set a tag for this request.
433         *
434         * <p>This tag is not used for anything by the camera device, but can be
435         * used by an application to easily identify a CaptureRequest when it is
436         * returned by
437         * {@link CameraDevice.CaptureListener#onCaptureCompleted CaptureListener.onCaptureCompleted}
438         *
439         * @param tag an arbitrary Object to store with this request
440         * @see CaptureRequest#getTag
441         */
442        public void setTag(Object tag) {
443            mRequest.mUserTag = tag;
444        }
445
446        /**
447         * Build a request using the current target Surfaces and settings.
448         *
449         * @return A new capture request instance, ready for submission to the
450         * camera device.
451         */
452        public CaptureRequest build() {
453            return new CaptureRequest(mRequest);
454        }
455
456
457        /**
458         * @hide
459         */
460        public boolean isEmpty() {
461            return mRequest.mSettings.isEmpty();
462        }
463
464    }
465
466    /*@O~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
467     * The key entries below this point are generated from metadata
468     * definitions in /system/media/camera/docs. Do not modify by hand or
469     * modify the comment blocks at the start or end.
470     *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
471
472
473    /**
474     * <p>The mode control selects how the image data is converted from the
475     * sensor's native color into linear sRGB color.</p>
476     * <p>When auto-white balance is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this
477     * control is overridden by the AWB routine. When AWB is disabled, the
478     * application controls how the color mapping is performed.</p>
479     * <p>We define the expected processing pipeline below. For consistency
480     * across devices, this is always the case with TRANSFORM_MATRIX.</p>
481     * <p>When either FULL or HIGH_QUALITY is used, the camera device may
482     * do additional processing but {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
483     * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} will still be provided by the
484     * camera device (in the results) and be roughly correct.</p>
485     * <p>Switching to TRANSFORM_MATRIX and using the data provided from
486     * FAST or HIGH_QUALITY will yield a picture with the same white point
487     * as what was produced by the camera device in the earlier frame.</p>
488     * <p>The expected processing pipeline is as follows:</p>
489     * <p><img alt="White balance processing pipeline" src="../../../../images/camera2/metadata/android.colorCorrection.mode/processing_pipeline.png" /></p>
490     * <p>The white balance is encoded by two values, a 4-channel white-balance
491     * gain vector (applied in the Bayer domain), and a 3x3 color transform
492     * matrix (applied after demosaic).</p>
493     * <p>The 4-channel white-balance gains are defined as:</p>
494     * <pre><code>{@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} = [ R G_even G_odd B ]
495     * </code></pre>
496     * <p>where <code>G_even</code> is the gain for green pixels on even rows of the
497     * output, and <code>G_odd</code> is the gain for green pixels on the odd rows.
498     * These may be identical for a given camera device implementation; if
499     * the camera device does not support a separate gain for even/odd green
500     * channels, it will use the <code>G_even</code> value, and write <code>G_odd</code> equal to
501     * <code>G_even</code> in the output result metadata.</p>
502     * <p>The matrices for color transforms are defined as a 9-entry vector:</p>
503     * <pre><code>{@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform} = [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ]
504     * </code></pre>
505     * <p>which define a transform from input sensor colors, <code>P_in = [ r g b ]</code>,
506     * to output linear sRGB, <code>P_out = [ r' g' b' ]</code>,</p>
507     * <p>with colors as follows:</p>
508     * <pre><code>r' = I0r + I1g + I2b
509     * g' = I3r + I4g + I5b
510     * b' = I6r + I7g + I8b
511     * </code></pre>
512     * <p>Both the input and output value ranges must match. Overflow/underflow
513     * values are clipped to fit within the range.</p>
514     *
515     * @see CaptureRequest#COLOR_CORRECTION_GAINS
516     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
517     * @see CaptureRequest#CONTROL_AWB_MODE
518     * @see #COLOR_CORRECTION_MODE_TRANSFORM_MATRIX
519     * @see #COLOR_CORRECTION_MODE_FAST
520     * @see #COLOR_CORRECTION_MODE_HIGH_QUALITY
521     */
522    public static final Key<Integer> COLOR_CORRECTION_MODE =
523            new Key<Integer>("android.colorCorrection.mode", int.class);
524
525    /**
526     * <p>A color transform matrix to use to transform
527     * from sensor RGB color space to output linear sRGB color space</p>
528     * <p>This matrix is either set by the camera device when the request
529     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or
530     * directly by the application in the request when the
531     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is TRANSFORM_MATRIX.</p>
532     * <p>In the latter case, the camera device may round the matrix to account
533     * for precision issues; the final rounded matrix should be reported back
534     * in this matrix result metadata. The transform should keep the magnitude
535     * of the output color values within <code>[0, 1.0]</code> (assuming input color
536     * values is within the normalized range <code>[0, 1.0]</code>), or clipping may occur.</p>
537     *
538     * @see CaptureRequest#COLOR_CORRECTION_MODE
539     */
540    public static final Key<android.hardware.camera2.params.ColorSpaceTransform> COLOR_CORRECTION_TRANSFORM =
541            new Key<android.hardware.camera2.params.ColorSpaceTransform>("android.colorCorrection.transform", android.hardware.camera2.params.ColorSpaceTransform.class);
542
543    /**
544     * <p>Gains applying to Bayer raw color channels for
545     * white-balance.</p>
546     * <p>These per-channel gains are either set by the camera device
547     * when the request {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not
548     * TRANSFORM_MATRIX, or directly by the application in the
549     * request when the {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is
550     * TRANSFORM_MATRIX.</p>
551     * <p>The gains in the result metadata are the gains actually
552     * applied by the camera device to the current frame.</p>
553     *
554     * @see CaptureRequest#COLOR_CORRECTION_MODE
555     */
556    public static final Key<android.hardware.camera2.params.RggbChannelVector> COLOR_CORRECTION_GAINS =
557            new Key<android.hardware.camera2.params.RggbChannelVector>("android.colorCorrection.gains", android.hardware.camera2.params.RggbChannelVector.class);
558
559    /**
560     * <p>The desired setting for the camera device's auto-exposure
561     * algorithm's antibanding compensation.</p>
562     * <p>Some kinds of lighting fixtures, such as some fluorescent
563     * lights, flicker at the rate of the power supply frequency
564     * (60Hz or 50Hz, depending on country). While this is
565     * typically not noticeable to a person, it can be visible to
566     * a camera device. If a camera sets its exposure time to the
567     * wrong value, the flicker may become visible in the
568     * viewfinder as flicker or in a final captured image, as a
569     * set of variable-brightness bands across the image.</p>
570     * <p>Therefore, the auto-exposure routines of camera devices
571     * include antibanding routines that ensure that the chosen
572     * exposure value will not cause such banding. The choice of
573     * exposure time depends on the rate of flicker, which the
574     * camera device can detect automatically, or the expected
575     * rate can be selected by the application using this
576     * control.</p>
577     * <p>A given camera device may not support all of the possible
578     * options for the antibanding mode. The
579     * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes} key contains
580     * the available modes for a given camera device.</p>
581     * <p>The default mode is AUTO, which must be supported by all
582     * camera devices.</p>
583     * <p>If manual exposure control is enabled (by setting
584     * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} to OFF),
585     * then this setting has no effect, and the application must
586     * ensure it selects exposure times that do not cause banding
587     * issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
588     * the application in this.</p>
589     *
590     * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
591     * @see CaptureRequest#CONTROL_AE_MODE
592     * @see CaptureRequest#CONTROL_MODE
593     * @see CaptureResult#STATISTICS_SCENE_FLICKER
594     * @see #CONTROL_AE_ANTIBANDING_MODE_OFF
595     * @see #CONTROL_AE_ANTIBANDING_MODE_50HZ
596     * @see #CONTROL_AE_ANTIBANDING_MODE_60HZ
597     * @see #CONTROL_AE_ANTIBANDING_MODE_AUTO
598     */
599    public static final Key<Integer> CONTROL_AE_ANTIBANDING_MODE =
600            new Key<Integer>("android.control.aeAntibandingMode", int.class);
601
602    /**
603     * <p>Adjustment to AE target image
604     * brightness</p>
605     * <p>For example, if EV step is 0.333, '6' will mean an
606     * exposure compensation of +2 EV; -3 will mean an exposure
607     * compensation of -1 EV. Note that this control will only be effective
608     * if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control will take effect even when
609     * {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p>
610     * <p>In the event of exposure compensation value being changed, camera device
611     * may take several frames to reach the newly requested exposure target.
612     * During that time, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} field will be in the SEARCHING
613     * state. Once the new exposure target is reached, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} will
614     * change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
615     * FLASH_REQUIRED (if the scene is too dark for still capture).</p>
616     *
617     * @see CaptureRequest#CONTROL_AE_LOCK
618     * @see CaptureRequest#CONTROL_AE_MODE
619     * @see CaptureResult#CONTROL_AE_STATE
620     */
621    public static final Key<Integer> CONTROL_AE_EXPOSURE_COMPENSATION =
622            new Key<Integer>("android.control.aeExposureCompensation", int.class);
623
624    /**
625     * <p>Whether AE is currently locked to its latest
626     * calculated values.</p>
627     * <p>Note that even when AE is locked, the flash may be
628     * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
629     * ON_AUTO_FLASH_REDEYE.</p>
630     * <p>When {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} is changed, even if the AE lock
631     * is ON, the camera device will still adjust its exposure value.</p>
632     * <p>If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger})
633     * when AE is already locked, the camera device will not change the exposure time
634     * ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}) and sensitivity ({@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity})
635     * parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}
636     * is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
637     * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p>
638     * <p>See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.</p>
639     *
640     * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
641     * @see CaptureRequest#CONTROL_AE_MODE
642     * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
643     * @see CaptureResult#CONTROL_AE_STATE
644     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
645     * @see CaptureRequest#SENSOR_SENSITIVITY
646     */
647    public static final Key<Boolean> CONTROL_AE_LOCK =
648            new Key<Boolean>("android.control.aeLock", boolean.class);
649
650    /**
651     * <p>The desired mode for the camera device's
652     * auto-exposure routine.</p>
653     * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is
654     * AUTO.</p>
655     * <p>When set to any of the ON modes, the camera device's
656     * auto-exposure routine is enabled, overriding the
657     * application's selected exposure time, sensor sensitivity,
658     * and frame duration ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
659     * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and
660     * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}). If one of the FLASH modes
661     * is selected, the camera device's flash unit controls are
662     * also overridden.</p>
663     * <p>The FLASH modes are only available if the camera device
664     * has a flash unit ({@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} is <code>true</code>).</p>
665     * <p>If flash TORCH mode is desired, this field must be set to
666     * ON or OFF, and {@link CaptureRequest#FLASH_MODE android.flash.mode} set to TORCH.</p>
667     * <p>When set to any of the ON modes, the values chosen by the
668     * camera device auto-exposure routine for the overridden
669     * fields for a given capture will be available in its
670     * CaptureResult.</p>
671     *
672     * @see CaptureRequest#CONTROL_MODE
673     * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
674     * @see CaptureRequest#FLASH_MODE
675     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
676     * @see CaptureRequest#SENSOR_FRAME_DURATION
677     * @see CaptureRequest#SENSOR_SENSITIVITY
678     * @see #CONTROL_AE_MODE_OFF
679     * @see #CONTROL_AE_MODE_ON
680     * @see #CONTROL_AE_MODE_ON_AUTO_FLASH
681     * @see #CONTROL_AE_MODE_ON_ALWAYS_FLASH
682     * @see #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE
683     */
684    public static final Key<Integer> CONTROL_AE_MODE =
685            new Key<Integer>("android.control.aeMode", int.class);
686
687    /**
688     * <p>List of areas to use for
689     * metering.</p>
690     * <p>The coordinate system is based on the active pixel array,
691     * with (0,0) being the top-left pixel in the active pixel array, and
692     * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
693     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
694     * bottom-right pixel in the active pixel array.</p>
695     * <p>The weight must range from 0 to 1000, and represents a weight
696     * for every pixel in the area. This means that a large metering area
697     * with the same weight as a smaller area will have more effect in
698     * the metering result. Metering areas can partially overlap and the
699     * camera device will add the weights in the overlap region.</p>
700     * <p>If all regions have 0 weight, then no specific metering area
701     * needs to be used by the camera device. If the metering region is
702     * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
703     * the camera device will ignore the sections outside the region and output the
704     * used sections in the result metadata.</p>
705     *
706     * @see CaptureRequest#SCALER_CROP_REGION
707     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
708     */
709    public static final Key<android.hardware.camera2.params.MeteringRectangle[]> CONTROL_AE_REGIONS =
710            new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class);
711
712    /**
713     * <p>Range over which fps can be adjusted to
714     * maintain exposure</p>
715     * <p>Only constrains AE algorithm, not manual control
716     * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
717     *
718     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
719     */
720    public static final Key<android.util.Range<Integer>> CONTROL_AE_TARGET_FPS_RANGE =
721            new Key<android.util.Range<Integer>>("android.control.aeTargetFpsRange", new TypeReference<android.util.Range<Integer>>() {{ }});
722
723    /**
724     * <p>Whether the camera device will trigger a precapture
725     * metering sequence when it processes this request.</p>
726     * <p>This entry is normally set to IDLE, or is not
727     * included at all in the request settings. When included and
728     * set to START, the camera device will trigger the autoexposure
729     * precapture metering sequence.</p>
730     * <p>The effect of AE precapture trigger depends on the current
731     * AE mode and state; see {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture
732     * state transition details.</p>
733     *
734     * @see CaptureResult#CONTROL_AE_STATE
735     * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
736     * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START
737     */
738    public static final Key<Integer> CONTROL_AE_PRECAPTURE_TRIGGER =
739            new Key<Integer>("android.control.aePrecaptureTrigger", int.class);
740
741    /**
742     * <p>Whether AF is currently enabled, and what
743     * mode it is set to</p>
744     * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus
745     * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} &gt; 0</code>).</p>
746     * <p>If the lens is controlled by the camera device auto-focus algorithm,
747     * the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
748     * in result metadata.</p>
749     *
750     * @see CaptureResult#CONTROL_AF_STATE
751     * @see CaptureRequest#CONTROL_MODE
752     * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
753     * @see #CONTROL_AF_MODE_OFF
754     * @see #CONTROL_AF_MODE_AUTO
755     * @see #CONTROL_AF_MODE_MACRO
756     * @see #CONTROL_AF_MODE_CONTINUOUS_VIDEO
757     * @see #CONTROL_AF_MODE_CONTINUOUS_PICTURE
758     * @see #CONTROL_AF_MODE_EDOF
759     */
760    public static final Key<Integer> CONTROL_AF_MODE =
761            new Key<Integer>("android.control.afMode", int.class);
762
763    /**
764     * <p>List of areas to use for focus
765     * estimation.</p>
766     * <p>The coordinate system is based on the active pixel array,
767     * with (0,0) being the top-left pixel in the active pixel array, and
768     * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
769     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
770     * bottom-right pixel in the active pixel array.</p>
771     * <p>The weight must range from 0 to 1000, and represents a weight
772     * for every pixel in the area. This means that a large metering area
773     * with the same weight as a smaller area will have more effect in
774     * the metering result. Metering areas can partially overlap and the
775     * camera device will add the weights in the overlap region.</p>
776     * <p>If all regions have 0 weight, then no specific metering area
777     * needs to be used by the camera device. If the metering region is
778     * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
779     * the camera device will ignore the sections outside the region and output the
780     * used sections in the result metadata.</p>
781     *
782     * @see CaptureRequest#SCALER_CROP_REGION
783     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
784     */
785    public static final Key<android.hardware.camera2.params.MeteringRectangle[]> CONTROL_AF_REGIONS =
786            new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.afRegions", android.hardware.camera2.params.MeteringRectangle[].class);
787
788    /**
789     * <p>Whether the camera device will trigger autofocus for this request.</p>
790     * <p>This entry is normally set to IDLE, or is not
791     * included at all in the request settings.</p>
792     * <p>When included and set to START, the camera device will trigger the
793     * autofocus algorithm. If autofocus is disabled, this trigger has no effect.</p>
794     * <p>When set to CANCEL, the camera device will cancel any active trigger,
795     * and return to its initial AF state.</p>
796     * <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.</p>
797     *
798     * @see CaptureResult#CONTROL_AF_STATE
799     * @see #CONTROL_AF_TRIGGER_IDLE
800     * @see #CONTROL_AF_TRIGGER_START
801     * @see #CONTROL_AF_TRIGGER_CANCEL
802     */
803    public static final Key<Integer> CONTROL_AF_TRIGGER =
804            new Key<Integer>("android.control.afTrigger", int.class);
805
806    /**
807     * <p>Whether AWB is currently locked to its
808     * latest calculated values.</p>
809     * <p>Note that AWB lock is only meaningful for AUTO
810     * mode; in other modes, AWB is already fixed to a specific
811     * setting.</p>
812     */
813    public static final Key<Boolean> CONTROL_AWB_LOCK =
814            new Key<Boolean>("android.control.awbLock", boolean.class);
815
816    /**
817     * <p>Whether AWB is currently setting the color
818     * transform fields, and what its illumination target
819     * is.</p>
820     * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
821     * <p>When set to the ON mode, the camera device's auto white balance
822     * routine is enabled, overriding the application's selected
823     * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
824     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
825     * <p>When set to the OFF mode, the camera device's auto white balance
826     * routine is disabled. The application manually controls the white
827     * balance by {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}
828     * and {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
829     * <p>When set to any other modes, the camera device's auto white balance
830     * routine is disabled. The camera device uses each particular illumination
831     * target for white balance adjustment.</p>
832     *
833     * @see CaptureRequest#COLOR_CORRECTION_GAINS
834     * @see CaptureRequest#COLOR_CORRECTION_MODE
835     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
836     * @see CaptureRequest#CONTROL_MODE
837     * @see #CONTROL_AWB_MODE_OFF
838     * @see #CONTROL_AWB_MODE_AUTO
839     * @see #CONTROL_AWB_MODE_INCANDESCENT
840     * @see #CONTROL_AWB_MODE_FLUORESCENT
841     * @see #CONTROL_AWB_MODE_WARM_FLUORESCENT
842     * @see #CONTROL_AWB_MODE_DAYLIGHT
843     * @see #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT
844     * @see #CONTROL_AWB_MODE_TWILIGHT
845     * @see #CONTROL_AWB_MODE_SHADE
846     */
847    public static final Key<Integer> CONTROL_AWB_MODE =
848            new Key<Integer>("android.control.awbMode", int.class);
849
850    /**
851     * <p>List of areas to use for illuminant
852     * estimation.</p>
853     * <p>The coordinate system is based on the active pixel array,
854     * with (0,0) being the top-left pixel in the active pixel array, and
855     * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
856     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
857     * bottom-right pixel in the active pixel array.</p>
858     * <p>The weight must range from 0 to 1000, and represents a weight
859     * for every pixel in the area. This means that a large metering area
860     * with the same weight as a smaller area will have more effect in
861     * the metering result. Metering areas can partially overlap and the
862     * camera device will add the weights in the overlap region.</p>
863     * <p>If all regions have 0 weight, then no specific metering area
864     * needs to be used by the camera device. If the metering region is
865     * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
866     * the camera device will ignore the sections outside the region and output the
867     * used sections in the result metadata.</p>
868     *
869     * @see CaptureRequest#SCALER_CROP_REGION
870     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
871     */
872    public static final Key<android.hardware.camera2.params.MeteringRectangle[]> CONTROL_AWB_REGIONS =
873            new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.awbRegions", android.hardware.camera2.params.MeteringRectangle[].class);
874
875    /**
876     * <p>Information to the camera device 3A (auto-exposure,
877     * auto-focus, auto-white balance) routines about the purpose
878     * of this capture, to help the camera device to decide optimal 3A
879     * strategy.</p>
880     * <p>This control (except for MANUAL) is only effective if
881     * <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p>
882     * <p>ZERO_SHUTTER_LAG must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
883     * contains ZSL. MANUAL must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
884     * contains MANUAL_SENSOR.</p>
885     *
886     * @see CaptureRequest#CONTROL_MODE
887     * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
888     * @see #CONTROL_CAPTURE_INTENT_CUSTOM
889     * @see #CONTROL_CAPTURE_INTENT_PREVIEW
890     * @see #CONTROL_CAPTURE_INTENT_STILL_CAPTURE
891     * @see #CONTROL_CAPTURE_INTENT_VIDEO_RECORD
892     * @see #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT
893     * @see #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG
894     * @see #CONTROL_CAPTURE_INTENT_MANUAL
895     */
896    public static final Key<Integer> CONTROL_CAPTURE_INTENT =
897            new Key<Integer>("android.control.captureIntent", int.class);
898
899    /**
900     * <p>A special color effect to apply.</p>
901     * <p>When this mode is set, a color effect will be applied
902     * to images produced by the camera device. The interpretation
903     * and implementation of these color effects is left to the
904     * implementor of the camera device, and should not be
905     * depended on to be consistent (or present) across all
906     * devices.</p>
907     * <p>A color effect will only be applied if
908     * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
909     *
910     * @see CaptureRequest#CONTROL_MODE
911     * @see #CONTROL_EFFECT_MODE_OFF
912     * @see #CONTROL_EFFECT_MODE_MONO
913     * @see #CONTROL_EFFECT_MODE_NEGATIVE
914     * @see #CONTROL_EFFECT_MODE_SOLARIZE
915     * @see #CONTROL_EFFECT_MODE_SEPIA
916     * @see #CONTROL_EFFECT_MODE_POSTERIZE
917     * @see #CONTROL_EFFECT_MODE_WHITEBOARD
918     * @see #CONTROL_EFFECT_MODE_BLACKBOARD
919     * @see #CONTROL_EFFECT_MODE_AQUA
920     */
921    public static final Key<Integer> CONTROL_EFFECT_MODE =
922            new Key<Integer>("android.control.effectMode", int.class);
923
924    /**
925     * <p>Overall mode of 3A control
926     * routines.</p>
927     * <p>High-level 3A control. When set to OFF, all 3A control
928     * by the camera device is disabled. The application must set the fields for
929     * capture parameters itself.</p>
930     * <p>When set to AUTO, the individual algorithm controls in
931     * android.control.* are in effect, such as {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p>
932     * <p>When set to USE_SCENE_MODE, the individual controls in
933     * android.control.* are mostly disabled, and the camera device implements
934     * one of the scene mode settings (such as ACTION, SUNSET, or PARTY)
935     * as it wishes. The camera device scene mode 3A settings are provided by
936     * android.control.sceneModeOverrides.</p>
937     * <p>When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference
938     * is that this frame will not be used by camera device background 3A statistics
939     * update, as if this frame is never captured. This mode can be used in the scenario
940     * where the application doesn't want a 3A manual control capture to affect
941     * the subsequent auto 3A capture results.</p>
942     *
943     * @see CaptureRequest#CONTROL_AF_MODE
944     * @see #CONTROL_MODE_OFF
945     * @see #CONTROL_MODE_AUTO
946     * @see #CONTROL_MODE_USE_SCENE_MODE
947     * @see #CONTROL_MODE_OFF_KEEP_STATE
948     */
949    public static final Key<Integer> CONTROL_MODE =
950            new Key<Integer>("android.control.mode", int.class);
951
952    /**
953     * <p>A camera mode optimized for conditions typical in a particular
954     * capture setting.</p>
955     * <p>This is the mode that that is active when
956     * <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code>. Aside from FACE_PRIORITY,
957     * these modes will disable {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
958     * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.</p>
959     * <p>The interpretation and implementation of these scene modes is left
960     * to the implementor of the camera device. Their behavior will not be
961     * consistent across all devices, and any given device may only implement
962     * a subset of these modes.</p>
963     *
964     * @see CaptureRequest#CONTROL_AE_MODE
965     * @see CaptureRequest#CONTROL_AF_MODE
966     * @see CaptureRequest#CONTROL_AWB_MODE
967     * @see CaptureRequest#CONTROL_MODE
968     * @see #CONTROL_SCENE_MODE_DISABLED
969     * @see #CONTROL_SCENE_MODE_FACE_PRIORITY
970     * @see #CONTROL_SCENE_MODE_ACTION
971     * @see #CONTROL_SCENE_MODE_PORTRAIT
972     * @see #CONTROL_SCENE_MODE_LANDSCAPE
973     * @see #CONTROL_SCENE_MODE_NIGHT
974     * @see #CONTROL_SCENE_MODE_NIGHT_PORTRAIT
975     * @see #CONTROL_SCENE_MODE_THEATRE
976     * @see #CONTROL_SCENE_MODE_BEACH
977     * @see #CONTROL_SCENE_MODE_SNOW
978     * @see #CONTROL_SCENE_MODE_SUNSET
979     * @see #CONTROL_SCENE_MODE_STEADYPHOTO
980     * @see #CONTROL_SCENE_MODE_FIREWORKS
981     * @see #CONTROL_SCENE_MODE_SPORTS
982     * @see #CONTROL_SCENE_MODE_PARTY
983     * @see #CONTROL_SCENE_MODE_CANDLELIGHT
984     * @see #CONTROL_SCENE_MODE_BARCODE
985     */
986    public static final Key<Integer> CONTROL_SCENE_MODE =
987            new Key<Integer>("android.control.sceneMode", int.class);
988
989    /**
990     * <p>Whether video stabilization is
991     * active</p>
992     * <p>If enabled, video stabilization can modify the
993     * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
994     * stabilized</p>
995     *
996     * @see CaptureRequest#SCALER_CROP_REGION
997     * @see #CONTROL_VIDEO_STABILIZATION_MODE_OFF
998     * @see #CONTROL_VIDEO_STABILIZATION_MODE_ON
999     */
1000    public static final Key<Integer> CONTROL_VIDEO_STABILIZATION_MODE =
1001            new Key<Integer>("android.control.videoStabilizationMode", int.class);
1002
1003    /**
1004     * <p>Operation mode for edge
1005     * enhancement.</p>
1006     * <p>Edge/sharpness/detail enhancement. OFF means no
1007     * enhancement will be applied by the camera device.</p>
1008     * <p>This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.</p>
1009     * <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
1010     * will be applied. HIGH_QUALITY mode indicates that the
1011     * camera device will use the highest-quality enhancement algorithms,
1012     * even if it slows down capture rate. FAST means the camera device will
1013     * not slow down capture rate when applying edge enhancement.</p>
1014     *
1015     * @see CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES
1016     * @see #EDGE_MODE_OFF
1017     * @see #EDGE_MODE_FAST
1018     * @see #EDGE_MODE_HIGH_QUALITY
1019     */
1020    public static final Key<Integer> EDGE_MODE =
1021            new Key<Integer>("android.edge.mode", int.class);
1022
1023    /**
1024     * <p>The desired mode for for the camera device's flash control.</p>
1025     * <p>This control is only effective when flash unit is available
1026     * (<code>{@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == true</code>).</p>
1027     * <p>When this control is used, the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} must be set to ON or OFF.
1028     * Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH,
1029     * ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control.</p>
1030     * <p>When set to OFF, the camera device will not fire flash for this capture.</p>
1031     * <p>When set to SINGLE, the camera device will fire flash regardless of the camera
1032     * device's auto-exposure routine's result. When used in still capture case, this
1033     * control should be used along with AE precapture metering sequence
1034     * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p>
1035     * <p>When set to TORCH, the flash will be on continuously. This mode can be used
1036     * for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
1037     * <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
1038     *
1039     * @see CaptureRequest#CONTROL_AE_MODE
1040     * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
1041     * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
1042     * @see CaptureResult#FLASH_STATE
1043     * @see #FLASH_MODE_OFF
1044     * @see #FLASH_MODE_SINGLE
1045     * @see #FLASH_MODE_TORCH
1046     */
1047    public static final Key<Integer> FLASH_MODE =
1048            new Key<Integer>("android.flash.mode", int.class);
1049
1050    /**
1051     * <p>Set operational mode for hot pixel correction.</p>
1052     * <p>Valid modes for this camera device are listed in
1053     * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
1054     * <p>Hotpixel correction interpolates out, or otherwise removes, pixels
1055     * that do not accurately encode the incoming light (i.e. pixels that
1056     * are stuck at an arbitrary value).</p>
1057     *
1058     * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
1059     * @see #HOT_PIXEL_MODE_OFF
1060     * @see #HOT_PIXEL_MODE_FAST
1061     * @see #HOT_PIXEL_MODE_HIGH_QUALITY
1062     */
1063    public static final Key<Integer> HOT_PIXEL_MODE =
1064            new Key<Integer>("android.hotPixel.mode", int.class);
1065
1066    /**
1067     * <p>A location object to use when generating image GPS metadata.</p>
1068     */
1069    public static final Key<android.location.Location> JPEG_GPS_LOCATION =
1070            new Key<android.location.Location>("android.jpeg.gpsLocation", android.location.Location.class);
1071
1072    /**
1073     * <p>GPS coordinates to include in output JPEG
1074     * EXIF</p>
1075     * @hide
1076     */
1077    public static final Key<double[]> JPEG_GPS_COORDINATES =
1078            new Key<double[]>("android.jpeg.gpsCoordinates", double[].class);
1079
1080    /**
1081     * <p>32 characters describing GPS algorithm to
1082     * include in EXIF</p>
1083     * @hide
1084     */
1085    public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
1086            new Key<String>("android.jpeg.gpsProcessingMethod", String.class);
1087
1088    /**
1089     * <p>Time GPS fix was made to include in
1090     * EXIF</p>
1091     * @hide
1092     */
1093    public static final Key<Long> JPEG_GPS_TIMESTAMP =
1094            new Key<Long>("android.jpeg.gpsTimestamp", long.class);
1095
1096    /**
1097     * <p>Orientation of JPEG image to
1098     * write</p>
1099     */
1100    public static final Key<Integer> JPEG_ORIENTATION =
1101            new Key<Integer>("android.jpeg.orientation", int.class);
1102
1103    /**
1104     * <p>Compression quality of the final JPEG
1105     * image</p>
1106     * <p>85-95 is typical usage range</p>
1107     */
1108    public static final Key<Byte> JPEG_QUALITY =
1109            new Key<Byte>("android.jpeg.quality", byte.class);
1110
1111    /**
1112     * <p>Compression quality of JPEG
1113     * thumbnail</p>
1114     */
1115    public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
1116            new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
1117
1118    /**
1119     * <p>Resolution of embedded JPEG thumbnail</p>
1120     * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
1121     * but the captured JPEG will still be a valid image.</p>
1122     * <p>When a jpeg image capture is issued, the thumbnail size selected should have
1123     * the same aspect ratio as the jpeg image.</p>
1124     * <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
1125     * ratio, the camera device creates the thumbnail by cropping it from the primary image.
1126     * For example, if the primary image has 4:3 aspect ratio, the thumbnail image has
1127     * 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to
1128     * generate the thumbnail image. The thumbnail image will always have a smaller Field
1129     * Of View (FOV) than the primary image when aspect ratios differ.</p>
1130     */
1131    public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
1132            new Key<android.util.Size>("android.jpeg.thumbnailSize", android.util.Size.class);
1133
1134    /**
1135     * <p>The ratio of lens focal length to the effective
1136     * aperture diameter.</p>
1137     * <p>This will only be supported on the camera devices that
1138     * have variable aperture lens. The aperture value can only be
1139     * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
1140     * <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
1141     * this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
1142     * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
1143     * to achieve manual exposure control.</p>
1144     * <p>The requested aperture value may take several frames to reach the
1145     * requested value; the camera device will report the current (intermediate)
1146     * aperture size in capture result metadata while the aperture is changing.
1147     * While the aperture is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
1148     * <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is one of
1149     * the ON modes, this will be overridden by the camera device
1150     * auto-exposure algorithm, the overridden values are then provided
1151     * back to the user in the corresponding result.</p>
1152     *
1153     * @see CaptureRequest#CONTROL_AE_MODE
1154     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
1155     * @see CaptureResult#LENS_STATE
1156     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
1157     * @see CaptureRequest#SENSOR_FRAME_DURATION
1158     * @see CaptureRequest#SENSOR_SENSITIVITY
1159     */
1160    public static final Key<Float> LENS_APERTURE =
1161            new Key<Float>("android.lens.aperture", float.class);
1162
1163    /**
1164     * <p>State of lens neutral density filter(s).</p>
1165     * <p>This will not be supported on most camera devices. On devices
1166     * where this is supported, this may only be set to one of the
1167     * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
1168     * <p>Lens filters are typically used to lower the amount of light the
1169     * sensor is exposed to (measured in steps of EV). As used here, an EV
1170     * step is the standard logarithmic representation, which are
1171     * non-negative, and inversely proportional to the amount of light
1172     * hitting the sensor.  For example, setting this to 0 would result
1173     * in no reduction of the incoming light, and setting this to 2 would
1174     * mean that the filter is set to reduce incoming light by two stops
1175     * (allowing 1/4 of the prior amount of light to the sensor).</p>
1176     * <p>It may take several frames before the lens filter density changes
1177     * to the requested value. While the filter density is still changing,
1178     * {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
1179     *
1180     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
1181     * @see CaptureResult#LENS_STATE
1182     */
1183    public static final Key<Float> LENS_FILTER_DENSITY =
1184            new Key<Float>("android.lens.filterDensity", float.class);
1185
1186    /**
1187     * <p>The current lens focal length; used for optical zoom.</p>
1188     * <p>This setting controls the physical focal length of the camera
1189     * device's lens. Changing the focal length changes the field of
1190     * view of the camera device, and is usually used for optical zoom.</p>
1191     * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this
1192     * setting won't be applied instantaneously, and it may take several
1193     * frames before the lens can change to the requested focal length.
1194     * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
1195     * be set to MOVING.</p>
1196     * <p>This is expected not to be supported on most devices.</p>
1197     *
1198     * @see CaptureRequest#LENS_APERTURE
1199     * @see CaptureRequest#LENS_FOCUS_DISTANCE
1200     * @see CaptureResult#LENS_STATE
1201     */
1202    public static final Key<Float> LENS_FOCAL_LENGTH =
1203            new Key<Float>("android.lens.focalLength", float.class);
1204
1205    /**
1206     * <p>Distance to plane of sharpest focus,
1207     * measured from frontmost surface of the lens</p>
1208     * <p>0 means infinity focus. Used value will be clamped
1209     * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].</p>
1210     * <p>Like {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, this setting won't be applied
1211     * instantaneously, and it may take several frames before the lens
1212     * can move to the requested focus distance. While the lens is still moving,
1213     * {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
1214     *
1215     * @see CaptureRequest#LENS_FOCAL_LENGTH
1216     * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
1217     * @see CaptureResult#LENS_STATE
1218     */
1219    public static final Key<Float> LENS_FOCUS_DISTANCE =
1220            new Key<Float>("android.lens.focusDistance", float.class);
1221
1222    /**
1223     * <p>Sets whether the camera device uses optical image stabilization (OIS)
1224     * when capturing images.</p>
1225     * <p>OIS is used to compensate for motion blur due to small movements of
1226     * the camera during capture. Unlike digital image stabilization, OIS makes
1227     * use of mechanical elements to stabilize the camera sensor, and thus
1228     * allows for longer exposure times before camera shake becomes
1229     * apparent.</p>
1230     * <p>This is not expected to be supported on most devices.</p>
1231     * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
1232     * @see #LENS_OPTICAL_STABILIZATION_MODE_ON
1233     */
1234    public static final Key<Integer> LENS_OPTICAL_STABILIZATION_MODE =
1235            new Key<Integer>("android.lens.opticalStabilizationMode", int.class);
1236
1237    /**
1238     * <p>Mode of operation for the noise reduction
1239     * algorithm</p>
1240     * <p>Noise filtering control. OFF means no noise reduction
1241     * will be applied by the camera device.</p>
1242     * <p>This must be set to a valid mode in
1243     * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</p>
1244     * <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
1245     * will be applied. HIGH_QUALITY mode indicates that the camera device
1246     * will use the highest-quality noise filtering algorithms,
1247     * even if it slows down capture rate. FAST means the camera device should not
1248     * slow down capture rate when applying noise filtering.</p>
1249     *
1250     * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
1251     * @see #NOISE_REDUCTION_MODE_OFF
1252     * @see #NOISE_REDUCTION_MODE_FAST
1253     * @see #NOISE_REDUCTION_MODE_HIGH_QUALITY
1254     */
1255    public static final Key<Integer> NOISE_REDUCTION_MODE =
1256            new Key<Integer>("android.noiseReduction.mode", int.class);
1257
1258    /**
1259     * <p>An application-specified ID for the current
1260     * request. Must be maintained unchanged in output
1261     * frame</p>
1262     * @hide
1263     */
1264    public static final Key<Integer> REQUEST_ID =
1265            new Key<Integer>("android.request.id", int.class);
1266
1267    /**
1268     * <p>(x, y, width, height).</p>
1269     * <p>A rectangle with the top-level corner of (x,y) and size
1270     * (width, height). The region of the sensor that is used for
1271     * output. Each stream must use this rectangle to produce its
1272     * output, cropping to a smaller region if necessary to
1273     * maintain the stream's aspect ratio.</p>
1274     * <p>HAL2.x uses only (x, y, width)</p>
1275     * <p>The crop region is applied after the RAW to other color space (e.g. YUV)
1276     * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage,
1277     * it is not croppable. The crop region will be ignored by raw streams.</p>
1278     * <p>For non-raw streams, any additional per-stream cropping will
1279     * be done to maximize the final pixel area of the stream.</p>
1280     * <p>For example, if the crop region is set to a 4:3 aspect
1281     * ratio, then 4:3 streams should use the exact crop
1282     * region. 16:9 streams should further crop vertically
1283     * (letterbox).</p>
1284     * <p>Conversely, if the crop region is set to a 16:9, then 4:3
1285     * outputs should crop horizontally (pillarbox), and 16:9
1286     * streams should match exactly. These additional crops must
1287     * be centered within the crop region.</p>
1288     * <p>The output streams must maintain square pixels at all
1289     * times, no matter what the relative aspect ratios of the
1290     * crop region and the stream are.  Negative values for
1291     * corner are allowed for raw output if full pixel array is
1292     * larger than active pixel array. Width and height may be
1293     * rounded to nearest larger supportable width, especially
1294     * for raw output, where only a few fixed scales may be
1295     * possible. The width and height of the crop region cannot
1296     * be set to be smaller than floor( activeArraySize.width /
1297     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor(
1298     * activeArraySize.height /
1299     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p>
1300     *
1301     * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
1302     */
1303    public static final Key<android.graphics.Rect> SCALER_CROP_REGION =
1304            new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class);
1305
1306    /**
1307     * <p>Duration each pixel is exposed to
1308     * light.</p>
1309     * <p>If the sensor can't expose this exact duration, it should shorten the
1310     * duration exposed to the nearest possible value (rather than expose longer).</p>
1311     */
1312    public static final Key<Long> SENSOR_EXPOSURE_TIME =
1313            new Key<Long>("android.sensor.exposureTime", long.class);
1314
1315    /**
1316     * <p>Duration from start of frame exposure to
1317     * start of next frame exposure.</p>
1318     * <p>The maximum frame rate that can be supported by a camera subsystem is
1319     * a function of many factors:</p>
1320     * <ul>
1321     * <li>Requested resolutions of output image streams</li>
1322     * <li>Availability of binning / skipping modes on the imager</li>
1323     * <li>The bandwidth of the imager interface</li>
1324     * <li>The bandwidth of the various ISP processing blocks</li>
1325     * </ul>
1326     * <p>Since these factors can vary greatly between different ISPs and
1327     * sensors, the camera abstraction tries to represent the bandwidth
1328     * restrictions with as simple a model as possible.</p>
1329     * <p>The model presented has the following characteristics:</p>
1330     * <ul>
1331     * <li>The image sensor is always configured to output the smallest
1332     * resolution possible given the application's requested output stream
1333     * sizes.  The smallest resolution is defined as being at least as large
1334     * as the largest requested output stream size; the camera pipeline must
1335     * never digitally upsample sensor data when the crop region covers the
1336     * whole sensor. In general, this means that if only small output stream
1337     * resolutions are configured, the sensor can provide a higher frame
1338     * rate.</li>
1339     * <li>Since any request may use any or all the currently configured
1340     * output streams, the sensor and ISP must be configured to support
1341     * scaling a single capture to all the streams at the same time.  This
1342     * means the camera pipeline must be ready to produce the largest
1343     * requested output size without any delay.  Therefore, the overall
1344     * frame rate of a given configured stream set is governed only by the
1345     * largest requested stream resolution.</li>
1346     * <li>Using more than one output stream in a request does not affect the
1347     * frame duration.</li>
1348     * <li>Certain format-streams may need to do additional background processing
1349     * before data is consumed/produced by that stream. These processors
1350     * can run concurrently to the rest of the camera pipeline, but
1351     * cannot process more than 1 capture at a time.</li>
1352     * </ul>
1353     * <p>The necessary information for the application, given the model above,
1354     * is provided via the {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap} field
1355     * using StreamConfigurationMap#getOutputMinFrameDuration(int, Size).
1356     * These are used to determine the maximum frame rate / minimum frame
1357     * duration that is possible for a given stream configuration.</p>
1358     * <p>Specifically, the application can use the following rules to
1359     * determine the minimum frame duration it can request from the camera
1360     * device:</p>
1361     * <ol>
1362     * <li>Let the set of currently configured input/output streams
1363     * be called <code>S</code>.</li>
1364     * <li>Find the minimum frame durations for each stream in <code>S</code>, by
1365     * looking it up in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap} using
1366     * StreamConfigurationMap#getOutputMinFrameDuration(int, Size) (with
1367     * its respective size/format). Let this set of frame durations be called
1368     * <code>F</code>.</li>
1369     * <li>For any given request <code>R</code>, the minimum frame duration allowed
1370     * for <code>R</code> is the maximum out of all values in <code>F</code>. Let the streams
1371     * used in <code>R</code> be called <code>S_r</code>.</li>
1372     * </ol>
1373     * <p>If none of the streams in <code>S_r</code> have a stall time (listed in
1374     * StreamConfigurationMap#getOutputStallDuration(int,Size) using its
1375     * respective size/format), then the frame duration in
1376     * <code>F</code> determines the steady state frame rate that the application will
1377     * get if it uses <code>R</code> as a repeating request. Let this special kind
1378     * of request be called <code>Rsimple</code>.</p>
1379     * <p>A repeating request <code>Rsimple</code> can be <em>occasionally</em> interleaved
1380     * by a single capture of a new request <code>Rstall</code> (which has at least
1381     * one in-use stream with a non-0 stall time) and if <code>Rstall</code> has the
1382     * same minimum frame duration this will not cause a frame rate loss
1383     * if all buffers from the previous <code>Rstall</code> have already been
1384     * delivered.</p>
1385     * <p>For more details about stalling, see
1386     * StreamConfigurationMap#getOutputStallDuration(int,Size).</p>
1387     *
1388     * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
1389     */
1390    public static final Key<Long> SENSOR_FRAME_DURATION =
1391            new Key<Long>("android.sensor.frameDuration", long.class);
1392
1393    /**
1394     * <p>Gain applied to image data. Must be
1395     * implemented through analog gain only if set to values
1396     * below 'maximum analog sensitivity'.</p>
1397     * <p>If the sensor can't apply this exact gain, it should lessen the
1398     * gain to the nearest possible value (rather than gain more).</p>
1399     * <p>ISO 12232:2006 REI method</p>
1400     */
1401    public static final Key<Integer> SENSOR_SENSITIVITY =
1402            new Key<Integer>("android.sensor.sensitivity", int.class);
1403
1404    /**
1405     * <p>A pixel <code>[R, G_even, G_odd, B]</code> that supplies the test pattern
1406     * when {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode} is SOLID_COLOR.</p>
1407     * <p>Each color channel is treated as an unsigned 32-bit integer.
1408     * The camera device then uses the most significant X bits
1409     * that correspond to how many bits are in its Bayer raw sensor
1410     * output.</p>
1411     * <p>For example, a sensor with RAW10 Bayer output would use the
1412     * 10 most significant bits from each color channel.</p>
1413     * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1414     *
1415     * @see CaptureRequest#SENSOR_TEST_PATTERN_MODE
1416     */
1417    public static final Key<int[]> SENSOR_TEST_PATTERN_DATA =
1418            new Key<int[]>("android.sensor.testPatternData", int[].class);
1419
1420    /**
1421     * <p>When enabled, the sensor sends a test pattern instead of
1422     * doing a real exposure from the camera.</p>
1423     * <p>When a test pattern is enabled, all manual sensor controls specified
1424     * by android.sensor.* should be ignored. All other controls should
1425     * work as normal.</p>
1426     * <p>For example, if manual flash is enabled, flash firing should still
1427     * occur (and that the test pattern remain unmodified, since the flash
1428     * would not actually affect it).</p>
1429     * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1430     * @see #SENSOR_TEST_PATTERN_MODE_OFF
1431     * @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
1432     * @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
1433     * @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY
1434     * @see #SENSOR_TEST_PATTERN_MODE_PN9
1435     * @see #SENSOR_TEST_PATTERN_MODE_CUSTOM1
1436     */
1437    public static final Key<Integer> SENSOR_TEST_PATTERN_MODE =
1438            new Key<Integer>("android.sensor.testPatternMode", int.class);
1439
1440    /**
1441     * <p>Quality of lens shading correction applied
1442     * to the image data.</p>
1443     * <p>When set to OFF mode, no lens shading correction will be applied by the
1444     * camera device, and an identity lens shading map data will be provided
1445     * if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
1446     * shading map with size specified as <code>android.lens.info.shadingMapSize = [ 4, 3 ]</code>,
1447     * the output android.statistics.lensShadingMap for this case will be an identity map
1448     * shown below:</p>
1449     * <pre><code>[ 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1450     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1451     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1452     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1453     * 1.0, 1.0, 1.0, 1.0,   1.0, 1.0, 1.0, 1.0,
1454     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
1455     * </code></pre>
1456     * <p>When set to other modes, lens shading correction will be applied by the
1457     * camera device. Applications can request lens shading map data by setting
1458     * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
1459     * lens shading map data in android.statistics.lensShadingMap, with size specified
1460     * by android.lens.info.shadingMapSize; the returned shading map data will be the one
1461     * applied by the camera device for this capture request.</p>
1462     * <p>The shading map data may depend on the AE and AWB statistics, therefore the reliability
1463     * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
1464     * 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),
1465     * to get best results, it is recommended that the applications wait for the AE and AWB to
1466     * be converged before using the returned shading map data.</p>
1467     *
1468     * @see CaptureRequest#CONTROL_AE_MODE
1469     * @see CaptureRequest#CONTROL_AWB_MODE
1470     * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
1471     * @see #SHADING_MODE_OFF
1472     * @see #SHADING_MODE_FAST
1473     * @see #SHADING_MODE_HIGH_QUALITY
1474     */
1475    public static final Key<Integer> SHADING_MODE =
1476            new Key<Integer>("android.shading.mode", int.class);
1477
1478    /**
1479     * <p>State of the face detector
1480     * unit</p>
1481     * <p>Whether face detection is enabled, and whether it
1482     * should output just the basic fields or the full set of
1483     * fields. Value must be one of the
1484     * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
1485     *
1486     * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
1487     * @see #STATISTICS_FACE_DETECT_MODE_OFF
1488     * @see #STATISTICS_FACE_DETECT_MODE_SIMPLE
1489     * @see #STATISTICS_FACE_DETECT_MODE_FULL
1490     */
1491    public static final Key<Integer> STATISTICS_FACE_DETECT_MODE =
1492            new Key<Integer>("android.statistics.faceDetectMode", int.class);
1493
1494    /**
1495     * <p>Operating mode for hotpixel map generation.</p>
1496     * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
1497     * If set to OFF, no hotpixel map should be returned.</p>
1498     * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
1499     *
1500     * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
1501     * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
1502     */
1503    public static final Key<Boolean> STATISTICS_HOT_PIXEL_MAP_MODE =
1504            new Key<Boolean>("android.statistics.hotPixelMapMode", boolean.class);
1505
1506    /**
1507     * <p>Whether the camera device will output the lens
1508     * shading map in output result metadata.</p>
1509     * <p>When set to ON,
1510     * android.statistics.lensShadingMap must be provided in
1511     * the output result metadata.</p>
1512     * @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF
1513     * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON
1514     */
1515    public static final Key<Integer> STATISTICS_LENS_SHADING_MAP_MODE =
1516            new Key<Integer>("android.statistics.lensShadingMapMode", int.class);
1517
1518    /**
1519     * <p>Tonemapping / contrast / gamma curve for the blue
1520     * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1521     * CONTRAST_CURVE.</p>
1522     * <p>See android.tonemap.curveRed for more details.</p>
1523     *
1524     * @see CaptureRequest#TONEMAP_MODE
1525     * @hide
1526     */
1527    public static final Key<float[]> TONEMAP_CURVE_BLUE =
1528            new Key<float[]>("android.tonemap.curveBlue", float[].class);
1529
1530    /**
1531     * <p>Tonemapping / contrast / gamma curve for the green
1532     * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1533     * CONTRAST_CURVE.</p>
1534     * <p>See android.tonemap.curveRed for more details.</p>
1535     *
1536     * @see CaptureRequest#TONEMAP_MODE
1537     * @hide
1538     */
1539    public static final Key<float[]> TONEMAP_CURVE_GREEN =
1540            new Key<float[]>("android.tonemap.curveGreen", float[].class);
1541
1542    /**
1543     * <p>Tonemapping / contrast / gamma curve for the red
1544     * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1545     * CONTRAST_CURVE.</p>
1546     * <p>Each channel's curve is defined by an array of control points:</p>
1547     * <pre><code>android.tonemap.curveRed =
1548     * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
1549     * 2 &lt;= N &lt;= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
1550     * <p>These are sorted in order of increasing <code>Pin</code>; it is always
1551     * guaranteed that input values 0.0 and 1.0 are included in the list to
1552     * define a complete mapping. For input values between control points,
1553     * the camera device must linearly interpolate between the control
1554     * points.</p>
1555     * <p>Each curve can have an independent number of points, and the number
1556     * of points can be less than max (that is, the request doesn't have to
1557     * always provide a curve with number of points equivalent to
1558     * {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}).</p>
1559     * <p>A few examples, and their corresponding graphical mappings; these
1560     * only specify the red channel and the precision is limited to 4
1561     * digits, for conciseness.</p>
1562     * <p>Linear mapping:</p>
1563     * <pre><code>android.tonemap.curveRed = [ 0, 0, 1.0, 1.0 ]
1564     * </code></pre>
1565     * <p><img alt="Linear mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/linear_tonemap.png" /></p>
1566     * <p>Invert mapping:</p>
1567     * <pre><code>android.tonemap.curveRed = [ 0, 1.0, 1.0, 0 ]
1568     * </code></pre>
1569     * <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
1570     * <p>Gamma 1/2.2 mapping, with 16 control points:</p>
1571     * <pre><code>android.tonemap.curveRed = [
1572     * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
1573     * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
1574     * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
1575     * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
1576     * </code></pre>
1577     * <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
1578     * <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
1579     * <pre><code>android.tonemap.curveRed = [
1580     * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
1581     * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
1582     * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
1583     * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
1584     * </code></pre>
1585     * <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
1586     *
1587     * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
1588     * @see CaptureRequest#TONEMAP_MODE
1589     * @hide
1590     */
1591    public static final Key<float[]> TONEMAP_CURVE_RED =
1592            new Key<float[]>("android.tonemap.curveRed", float[].class);
1593
1594    /**
1595     * <p>Tonemapping / contrast / gamma curve to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode}
1596     * is CONTRAST_CURVE.</p>
1597     * <p>The tonemapCurve consist of three curves for each of red, green, and blue
1598     * channels respectively. The following example uses the red channel as an
1599     * example. The same logic applies to green and blue channel.
1600     * Each channel's curve is defined by an array of control points:</p>
1601     * <pre><code>curveRed =
1602     * [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
1603     * 2 &lt;= N &lt;= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
1604     * <p>These are sorted in order of increasing <code>Pin</code>; it is always
1605     * guaranteed that input values 0.0 and 1.0 are included in the list to
1606     * define a complete mapping. For input values between control points,
1607     * the camera device must linearly interpolate between the control
1608     * points.</p>
1609     * <p>Each curve can have an independent number of points, and the number
1610     * of points can be less than max (that is, the request doesn't have to
1611     * always provide a curve with number of points equivalent to
1612     * {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}).</p>
1613     * <p>A few examples, and their corresponding graphical mappings; these
1614     * only specify the red channel and the precision is limited to 4
1615     * digits, for conciseness.</p>
1616     * <p>Linear mapping:</p>
1617     * <pre><code>curveRed = [ (0, 0), (1.0, 1.0) ]
1618     * </code></pre>
1619     * <p><img alt="Linear mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/linear_tonemap.png" /></p>
1620     * <p>Invert mapping:</p>
1621     * <pre><code>curveRed = [ (0, 1.0), (1.0, 0) ]
1622     * </code></pre>
1623     * <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
1624     * <p>Gamma 1/2.2 mapping, with 16 control points:</p>
1625     * <pre><code>curveRed = [
1626     * (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
1627     * (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
1628     * (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
1629     * (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
1630     * </code></pre>
1631     * <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
1632     * <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
1633     * <pre><code>curveRed = [
1634     * (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
1635     * (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
1636     * (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
1637     * (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
1638     * </code></pre>
1639     * <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
1640     *
1641     * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
1642     * @see CaptureRequest#TONEMAP_MODE
1643     */
1644    public static final Key<android.hardware.camera2.params.TonemapCurve> TONEMAP_CURVE =
1645            new Key<android.hardware.camera2.params.TonemapCurve>("android.tonemap.curve", android.hardware.camera2.params.TonemapCurve.class);
1646
1647    /**
1648     * <p>High-level global contrast/gamma/tonemapping control.</p>
1649     * <p>When switching to an application-defined contrast curve by setting
1650     * {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} to CONTRAST_CURVE, the curve is defined
1651     * per-channel with a set of <code>(in, out)</code> points that specify the
1652     * mapping from input high-bit-depth pixel value to the output
1653     * low-bit-depth value.  Since the actual pixel ranges of both input
1654     * and output may change depending on the camera pipeline, the values
1655     * are specified by normalized floating-point numbers.</p>
1656     * <p>More-complex color mapping operations such as 3D color look-up
1657     * tables, selective chroma enhancement, or other non-linear color
1658     * transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1659     * CONTRAST_CURVE.</p>
1660     * <p>This must be set to a valid mode in
1661     * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.</p>
1662     * <p>When using either FAST or HIGH_QUALITY, the camera device will
1663     * emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE android.tonemap.curve}.
1664     * These values are always available, and as close as possible to the
1665     * actually used nonlinear/nonglobal transforms.</p>
1666     * <p>If a request is sent with CONTRAST_CURVE with the camera device's
1667     * provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
1668     * roughly the same.</p>
1669     *
1670     * @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES
1671     * @see CaptureRequest#TONEMAP_CURVE
1672     * @see CaptureRequest#TONEMAP_MODE
1673     * @see #TONEMAP_MODE_CONTRAST_CURVE
1674     * @see #TONEMAP_MODE_FAST
1675     * @see #TONEMAP_MODE_HIGH_QUALITY
1676     */
1677    public static final Key<Integer> TONEMAP_MODE =
1678            new Key<Integer>("android.tonemap.mode", int.class);
1679
1680    /**
1681     * <p>This LED is nominally used to indicate to the user
1682     * that the camera is powered on and may be streaming images back to the
1683     * Application Processor. In certain rare circumstances, the OS may
1684     * disable this when video is processed locally and not transmitted to
1685     * any untrusted applications.</p>
1686     * <p>In particular, the LED <em>must</em> always be on when the data could be
1687     * transmitted off the device. The LED <em>should</em> always be on whenever
1688     * data is stored locally on the device.</p>
1689     * <p>The LED <em>may</em> be off if a trusted application is using the data that
1690     * doesn't violate the above rules.</p>
1691     * @hide
1692     */
1693    public static final Key<Boolean> LED_TRANSMIT =
1694            new Key<Boolean>("android.led.transmit", boolean.class);
1695
1696    /**
1697     * <p>Whether black-level compensation is locked
1698     * to its current values, or is free to vary.</p>
1699     * <p>When set to ON, the values used for black-level
1700     * compensation will not change until the lock is set to
1701     * OFF.</p>
1702     * <p>Since changes to certain capture parameters (such as
1703     * exposure time) may require resetting of black level
1704     * compensation, the camera device must report whether setting
1705     * the black level lock was successful in the output result
1706     * metadata.</p>
1707     * <p>For example, if a sequence of requests is as follows:</p>
1708     * <ul>
1709     * <li>Request 1: Exposure = 10ms, Black level lock = OFF</li>
1710     * <li>Request 2: Exposure = 10ms, Black level lock = ON</li>
1711     * <li>Request 3: Exposure = 10ms, Black level lock = ON</li>
1712     * <li>Request 4: Exposure = 20ms, Black level lock = ON</li>
1713     * <li>Request 5: Exposure = 20ms, Black level lock = ON</li>
1714     * <li>Request 6: Exposure = 20ms, Black level lock = ON</li>
1715     * </ul>
1716     * <p>And the exposure change in Request 4 requires the camera
1717     * device to reset the black level offsets, then the output
1718     * result metadata is expected to be:</p>
1719     * <ul>
1720     * <li>Result 1: Exposure = 10ms, Black level lock = OFF</li>
1721     * <li>Result 2: Exposure = 10ms, Black level lock = ON</li>
1722     * <li>Result 3: Exposure = 10ms, Black level lock = ON</li>
1723     * <li>Result 4: Exposure = 20ms, Black level lock = OFF</li>
1724     * <li>Result 5: Exposure = 20ms, Black level lock = ON</li>
1725     * <li>Result 6: Exposure = 20ms, Black level lock = ON</li>
1726     * </ul>
1727     * <p>This indicates to the application that on frame 4, black
1728     * levels were reset due to exposure value changes, and pixel
1729     * values may not be consistent across captures.</p>
1730     * <p>The camera device will maintain the lock to the extent
1731     * possible, only overriding the lock to OFF when changes to
1732     * other request parameters require a black level recalculation
1733     * or reset.</p>
1734     */
1735    public static final Key<Boolean> BLACK_LEVEL_LOCK =
1736            new Key<Boolean>("android.blackLevel.lock", boolean.class);
1737
1738    /*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
1739     * End generated code
1740     *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
1741}
1742