CaptureRequest.java revision 817f8933ee1c11130ad2ca45b5ac8ce8b729f125 
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<Rational[]> COLOR_CORRECTION_TRANSFORM =
541            new Key<Rational[]>("android.colorCorrection.transform", Rational[].class);
542
543    /**
544     * <p>Gains applying to Bayer raw color channels for
545     * white-balance.</p>
546     * <p>The 4-channel white-balance gains are defined in
547     * the order of <code>[R G_even G_odd B]</code>, where <code>G_even</code> is the gain
548     * for green pixels on even rows of the output, and <code>G_odd</code>
549     * is the gain for green pixels on the odd rows. if a HAL
550     * does not support a separate gain for even/odd green channels,
551     * it should use the <code>G_even</code> value, and write <code>G_odd</code> equal to
552     * <code>G_even</code> in the output result metadata.</p>
553     * <p>This array is either set by the camera device when the request
554     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or
555     * directly by the application in the request when the
556     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is TRANSFORM_MATRIX.</p>
557     * <p>The output should be the gains actually applied by the camera device to
558     * the current frame.</p>
559     *
560     * @see CaptureRequest#COLOR_CORRECTION_MODE
561     */
562    public static final Key<float[]> COLOR_CORRECTION_GAINS =
563            new Key<float[]>("android.colorCorrection.gains", float[].class);
564
565    /**
566     * <p>The desired setting for the camera device's auto-exposure
567     * algorithm's antibanding compensation.</p>
568     * <p>Some kinds of lighting fixtures, such as some fluorescent
569     * lights, flicker at the rate of the power supply frequency
570     * (60Hz or 50Hz, depending on country). While this is
571     * typically not noticeable to a person, it can be visible to
572     * a camera device. If a camera sets its exposure time to the
573     * wrong value, the flicker may become visible in the
574     * viewfinder as flicker or in a final captured image, as a
575     * set of variable-brightness bands across the image.</p>
576     * <p>Therefore, the auto-exposure routines of camera devices
577     * include antibanding routines that ensure that the chosen
578     * exposure value will not cause such banding. The choice of
579     * exposure time depends on the rate of flicker, which the
580     * camera device can detect automatically, or the expected
581     * rate can be selected by the application using this
582     * control.</p>
583     * <p>A given camera device may not support all of the possible
584     * options for the antibanding mode. The
585     * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES android.control.aeAvailableAntibandingModes} key contains
586     * the available modes for a given camera device.</p>
587     * <p>The default mode is AUTO, which must be supported by all
588     * camera devices.</p>
589     * <p>If manual exposure control is enabled (by setting
590     * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} or {@link CaptureRequest#CONTROL_MODE android.control.mode} to OFF),
591     * then this setting has no effect, and the application must
592     * ensure it selects exposure times that do not cause banding
593     * issues. The {@link CaptureResult#STATISTICS_SCENE_FLICKER android.statistics.sceneFlicker} key can assist
594     * the application in this.</p>
595     *
596     * @see CameraCharacteristics#CONTROL_AE_AVAILABLE_ANTIBANDING_MODES
597     * @see CaptureRequest#CONTROL_AE_MODE
598     * @see CaptureRequest#CONTROL_MODE
599     * @see CaptureResult#STATISTICS_SCENE_FLICKER
600     * @see #CONTROL_AE_ANTIBANDING_MODE_OFF
601     * @see #CONTROL_AE_ANTIBANDING_MODE_50HZ
602     * @see #CONTROL_AE_ANTIBANDING_MODE_60HZ
603     * @see #CONTROL_AE_ANTIBANDING_MODE_AUTO
604     */
605    public static final Key<Integer> CONTROL_AE_ANTIBANDING_MODE =
606            new Key<Integer>("android.control.aeAntibandingMode", int.class);
607
608    /**
609     * <p>Adjustment to AE target image
610     * brightness</p>
611     * <p>For example, if EV step is 0.333, '6' will mean an
612     * exposure compensation of +2 EV; -3 will mean an exposure
613     * compensation of -1 EV. Note that this control will only be effective
614     * if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control will take effect even when
615     * {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p>
616     * <p>In the event of exposure compensation value being changed, camera device
617     * may take several frames to reach the newly requested exposure target.
618     * During that time, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} field will be in the SEARCHING
619     * state. Once the new exposure target is reached, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} will
620     * change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
621     * FLASH_REQUIRED (if the scene is too dark for still capture).</p>
622     *
623     * @see CaptureRequest#CONTROL_AE_LOCK
624     * @see CaptureRequest#CONTROL_AE_MODE
625     * @see CaptureResult#CONTROL_AE_STATE
626     */
627    public static final Key<Integer> CONTROL_AE_EXPOSURE_COMPENSATION =
628            new Key<Integer>("android.control.aeExposureCompensation", int.class);
629
630    /**
631     * <p>Whether AE is currently locked to its latest
632     * calculated values.</p>
633     * <p>Note that even when AE is locked, the flash may be
634     * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
635     * ON_AUTO_FLASH_REDEYE.</p>
636     * <p>When {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION android.control.aeExposureCompensation} is changed, even if the AE lock
637     * is ON, the camera device will still adjust its exposure value.</p>
638     * <p>If AE precapture is triggered (see {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger})
639     * when AE is already locked, the camera device will not change the exposure time
640     * ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}) and sensitivity ({@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity})
641     * parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}
642     * is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
643     * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p>
644     * <p>See {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE lock related state transition details.</p>
645     *
646     * @see CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
647     * @see CaptureRequest#CONTROL_AE_MODE
648     * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
649     * @see CaptureResult#CONTROL_AE_STATE
650     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
651     * @see CaptureRequest#SENSOR_SENSITIVITY
652     */
653    public static final Key<Boolean> CONTROL_AE_LOCK =
654            new Key<Boolean>("android.control.aeLock", boolean.class);
655
656    /**
657     * <p>The desired mode for the camera device's
658     * auto-exposure routine.</p>
659     * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is
660     * AUTO.</p>
661     * <p>When set to any of the ON modes, the camera device's
662     * auto-exposure routine is enabled, overriding the
663     * application's selected exposure time, sensor sensitivity,
664     * and frame duration ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
665     * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and
666     * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}). If one of the FLASH modes
667     * is selected, the camera device's flash unit controls are
668     * also overridden.</p>
669     * <p>The FLASH modes are only available if the camera device
670     * has a flash unit ({@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} is <code>true</code>).</p>
671     * <p>If flash TORCH mode is desired, this field must be set to
672     * ON or OFF, and {@link CaptureRequest#FLASH_MODE android.flash.mode} set to TORCH.</p>
673     * <p>When set to any of the ON modes, the values chosen by the
674     * camera device auto-exposure routine for the overridden
675     * fields for a given capture will be available in its
676     * CaptureResult.</p>
677     *
678     * @see CaptureRequest#CONTROL_MODE
679     * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
680     * @see CaptureRequest#FLASH_MODE
681     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
682     * @see CaptureRequest#SENSOR_FRAME_DURATION
683     * @see CaptureRequest#SENSOR_SENSITIVITY
684     * @see #CONTROL_AE_MODE_OFF
685     * @see #CONTROL_AE_MODE_ON
686     * @see #CONTROL_AE_MODE_ON_AUTO_FLASH
687     * @see #CONTROL_AE_MODE_ON_ALWAYS_FLASH
688     * @see #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE
689     */
690    public static final Key<Integer> CONTROL_AE_MODE =
691            new Key<Integer>("android.control.aeMode", int.class);
692
693    /**
694     * <p>List of areas to use for
695     * metering.</p>
696     * <p>The coordinate system is based on the active pixel array,
697     * with (0,0) being the top-left pixel in the active pixel array, and
698     * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
699     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
700     * bottom-right pixel in the active pixel array. The weight
701     * should be nonnegative.</p>
702     * <p>If all regions have 0 weight, then no specific metering area
703     * needs to be used by the camera device. If the metering region is
704     * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
705     * the camera device will ignore the sections outside the region and output the
706     * used sections in the result metadata.</p>
707     *
708     * @see CaptureRequest#SCALER_CROP_REGION
709     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
710     */
711    public static final Key<android.hardware.camera2.params.MeteringRectangle[]> CONTROL_AE_REGIONS =
712            new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.aeRegions", android.hardware.camera2.params.MeteringRectangle[].class);
713
714    /**
715     * <p>Range over which fps can be adjusted to
716     * maintain exposure</p>
717     * <p>Only constrains AE algorithm, not manual control
718     * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
719     *
720     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
721     */
722    public static final Key<int[]> CONTROL_AE_TARGET_FPS_RANGE =
723            new Key<int[]>("android.control.aeTargetFpsRange", int[].class);
724
725    /**
726     * <p>Whether the camera device will trigger a precapture
727     * metering sequence when it processes this request.</p>
728     * <p>This entry is normally set to IDLE, or is not
729     * included at all in the request settings. When included and
730     * set to START, the camera device will trigger the autoexposure
731     * precapture metering sequence.</p>
732     * <p>The effect of AE precapture trigger depends on the current
733     * AE mode and state; see {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture
734     * state transition details.</p>
735     *
736     * @see CaptureResult#CONTROL_AE_STATE
737     * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
738     * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START
739     */
740    public static final Key<Integer> CONTROL_AE_PRECAPTURE_TRIGGER =
741            new Key<Integer>("android.control.aePrecaptureTrigger", int.class);
742
743    /**
744     * <p>Whether AF is currently enabled, and what
745     * mode it is set to</p>
746     * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus
747     * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} &gt; 0</code>).</p>
748     * <p>If the lens is controlled by the camera device auto-focus algorithm,
749     * the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
750     * in result metadata.</p>
751     *
752     * @see CaptureResult#CONTROL_AF_STATE
753     * @see CaptureRequest#CONTROL_MODE
754     * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
755     * @see #CONTROL_AF_MODE_OFF
756     * @see #CONTROL_AF_MODE_AUTO
757     * @see #CONTROL_AF_MODE_MACRO
758     * @see #CONTROL_AF_MODE_CONTINUOUS_VIDEO
759     * @see #CONTROL_AF_MODE_CONTINUOUS_PICTURE
760     * @see #CONTROL_AF_MODE_EDOF
761     */
762    public static final Key<Integer> CONTROL_AF_MODE =
763            new Key<Integer>("android.control.afMode", int.class);
764
765    /**
766     * <p>List of areas to use for focus
767     * estimation.</p>
768     * <p>The coordinate system is based on the active pixel array,
769     * with (0,0) being the top-left pixel in the active pixel array, and
770     * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
771     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
772     * bottom-right pixel in the active pixel array. The weight
773     * should be nonnegative.</p>
774     * <p>If all regions have 0 weight, then no specific metering area
775     * needs to be used by the camera device. If the metering region is
776     * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
777     * the camera device will ignore the sections outside the region and output the
778     * used sections in the result metadata.</p>
779     *
780     * @see CaptureRequest#SCALER_CROP_REGION
781     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
782     */
783    public static final Key<android.hardware.camera2.params.MeteringRectangle[]> CONTROL_AF_REGIONS =
784            new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.afRegions", android.hardware.camera2.params.MeteringRectangle[].class);
785
786    /**
787     * <p>Whether the camera device will trigger autofocus for this request.</p>
788     * <p>This entry is normally set to IDLE, or is not
789     * included at all in the request settings.</p>
790     * <p>When included and set to START, the camera device will trigger the
791     * autofocus algorithm. If autofocus is disabled, this trigger has no effect.</p>
792     * <p>When set to CANCEL, the camera device will cancel any active trigger,
793     * and return to its initial AF state.</p>
794     * <p>See {@link CaptureResult#CONTROL_AF_STATE android.control.afState} for what that means for each AF mode.</p>
795     *
796     * @see CaptureResult#CONTROL_AF_STATE
797     * @see #CONTROL_AF_TRIGGER_IDLE
798     * @see #CONTROL_AF_TRIGGER_START
799     * @see #CONTROL_AF_TRIGGER_CANCEL
800     */
801    public static final Key<Integer> CONTROL_AF_TRIGGER =
802            new Key<Integer>("android.control.afTrigger", int.class);
803
804    /**
805     * <p>Whether AWB is currently locked to its
806     * latest calculated values.</p>
807     * <p>Note that AWB lock is only meaningful for AUTO
808     * mode; in other modes, AWB is already fixed to a specific
809     * setting.</p>
810     */
811    public static final Key<Boolean> CONTROL_AWB_LOCK =
812            new Key<Boolean>("android.control.awbLock", boolean.class);
813
814    /**
815     * <p>Whether AWB is currently setting the color
816     * transform fields, and what its illumination target
817     * is.</p>
818     * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
819     * <p>When set to the ON mode, the camera device's auto white balance
820     * routine is enabled, overriding the application's selected
821     * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
822     * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
823     * <p>When set to the OFF mode, the camera device's auto white balance
824     * routine is disabled. The application manually controls the white
825     * balance by {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}
826     * and {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
827     * <p>When set to any other modes, the camera device's auto white balance
828     * routine is disabled. The camera device uses each particular illumination
829     * target for white balance adjustment.</p>
830     *
831     * @see CaptureRequest#COLOR_CORRECTION_GAINS
832     * @see CaptureRequest#COLOR_CORRECTION_MODE
833     * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
834     * @see CaptureRequest#CONTROL_MODE
835     * @see #CONTROL_AWB_MODE_OFF
836     * @see #CONTROL_AWB_MODE_AUTO
837     * @see #CONTROL_AWB_MODE_INCANDESCENT
838     * @see #CONTROL_AWB_MODE_FLUORESCENT
839     * @see #CONTROL_AWB_MODE_WARM_FLUORESCENT
840     * @see #CONTROL_AWB_MODE_DAYLIGHT
841     * @see #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT
842     * @see #CONTROL_AWB_MODE_TWILIGHT
843     * @see #CONTROL_AWB_MODE_SHADE
844     */
845    public static final Key<Integer> CONTROL_AWB_MODE =
846            new Key<Integer>("android.control.awbMode", int.class);
847
848    /**
849     * <p>List of areas to use for illuminant
850     * estimation.</p>
851     * <p>The coordinate system is based on the active pixel array,
852     * with (0,0) being the top-left pixel in the active pixel array, and
853     * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
854     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
855     * bottom-right pixel in the active pixel array. The weight
856     * should be nonnegative.</p>
857     * <p>If all regions have 0 weight, then no specific metering area
858     * needs to be used by the camera device. If the metering region is
859     * outside the used {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} returned in capture result metadata,
860     * the camera device will ignore the sections outside the region and output the
861     * used sections in the result metadata.</p>
862     *
863     * @see CaptureRequest#SCALER_CROP_REGION
864     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
865     */
866    public static final Key<android.hardware.camera2.params.MeteringRectangle[]> CONTROL_AWB_REGIONS =
867            new Key<android.hardware.camera2.params.MeteringRectangle[]>("android.control.awbRegions", android.hardware.camera2.params.MeteringRectangle[].class);
868
869    /**
870     * <p>Information to the camera device 3A (auto-exposure,
871     * auto-focus, auto-white balance) routines about the purpose
872     * of this capture, to help the camera device to decide optimal 3A
873     * strategy.</p>
874     * <p>This control (except for MANUAL) is only effective if
875     * <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF</code> and any 3A routine is active.</p>
876     * <p>ZERO_SHUTTER_LAG must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
877     * contains ZSL. MANUAL must be supported if {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}
878     * contains MANUAL_SENSOR.</p>
879     *
880     * @see CaptureRequest#CONTROL_MODE
881     * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
882     * @see #CONTROL_CAPTURE_INTENT_CUSTOM
883     * @see #CONTROL_CAPTURE_INTENT_PREVIEW
884     * @see #CONTROL_CAPTURE_INTENT_STILL_CAPTURE
885     * @see #CONTROL_CAPTURE_INTENT_VIDEO_RECORD
886     * @see #CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT
887     * @see #CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG
888     * @see #CONTROL_CAPTURE_INTENT_MANUAL
889     */
890    public static final Key<Integer> CONTROL_CAPTURE_INTENT =
891            new Key<Integer>("android.control.captureIntent", int.class);
892
893    /**
894     * <p>A special color effect to apply.</p>
895     * <p>When this mode is set, a color effect will be applied
896     * to images produced by the camera device. The interpretation
897     * and implementation of these color effects is left to the
898     * implementor of the camera device, and should not be
899     * depended on to be consistent (or present) across all
900     * devices.</p>
901     * <p>A color effect will only be applied if
902     * {@link CaptureRequest#CONTROL_MODE android.control.mode} != OFF.</p>
903     *
904     * @see CaptureRequest#CONTROL_MODE
905     * @see #CONTROL_EFFECT_MODE_OFF
906     * @see #CONTROL_EFFECT_MODE_MONO
907     * @see #CONTROL_EFFECT_MODE_NEGATIVE
908     * @see #CONTROL_EFFECT_MODE_SOLARIZE
909     * @see #CONTROL_EFFECT_MODE_SEPIA
910     * @see #CONTROL_EFFECT_MODE_POSTERIZE
911     * @see #CONTROL_EFFECT_MODE_WHITEBOARD
912     * @see #CONTROL_EFFECT_MODE_BLACKBOARD
913     * @see #CONTROL_EFFECT_MODE_AQUA
914     */
915    public static final Key<Integer> CONTROL_EFFECT_MODE =
916            new Key<Integer>("android.control.effectMode", int.class);
917
918    /**
919     * <p>Overall mode of 3A control
920     * routines.</p>
921     * <p>High-level 3A control. When set to OFF, all 3A control
922     * by the camera device is disabled. The application must set the fields for
923     * capture parameters itself.</p>
924     * <p>When set to AUTO, the individual algorithm controls in
925     * android.control.* are in effect, such as {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p>
926     * <p>When set to USE_SCENE_MODE, the individual controls in
927     * android.control.* are mostly disabled, and the camera device implements
928     * one of the scene mode settings (such as ACTION, SUNSET, or PARTY)
929     * as it wishes. The camera device scene mode 3A settings are provided by
930     * android.control.sceneModeOverrides.</p>
931     * <p>When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference
932     * is that this frame will not be used by camera device background 3A statistics
933     * update, as if this frame is never captured. This mode can be used in the scenario
934     * where the application doesn't want a 3A manual control capture to affect
935     * the subsequent auto 3A capture results.</p>
936     *
937     * @see CaptureRequest#CONTROL_AF_MODE
938     * @see #CONTROL_MODE_OFF
939     * @see #CONTROL_MODE_AUTO
940     * @see #CONTROL_MODE_USE_SCENE_MODE
941     * @see #CONTROL_MODE_OFF_KEEP_STATE
942     */
943    public static final Key<Integer> CONTROL_MODE =
944            new Key<Integer>("android.control.mode", int.class);
945
946    /**
947     * <p>A camera mode optimized for conditions typical in a particular
948     * capture setting.</p>
949     * <p>This is the mode that that is active when
950     * <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code>. Aside from FACE_PRIORITY,
951     * these modes will disable {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode},
952     * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, and {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} while in use.</p>
953     * <p>The interpretation and implementation of these scene modes is left
954     * to the implementor of the camera device. Their behavior will not be
955     * consistent across all devices, and any given device may only implement
956     * a subset of these modes.</p>
957     *
958     * @see CaptureRequest#CONTROL_AE_MODE
959     * @see CaptureRequest#CONTROL_AF_MODE
960     * @see CaptureRequest#CONTROL_AWB_MODE
961     * @see CaptureRequest#CONTROL_MODE
962     * @see #CONTROL_SCENE_MODE_DISABLED
963     * @see #CONTROL_SCENE_MODE_FACE_PRIORITY
964     * @see #CONTROL_SCENE_MODE_ACTION
965     * @see #CONTROL_SCENE_MODE_PORTRAIT
966     * @see #CONTROL_SCENE_MODE_LANDSCAPE
967     * @see #CONTROL_SCENE_MODE_NIGHT
968     * @see #CONTROL_SCENE_MODE_NIGHT_PORTRAIT
969     * @see #CONTROL_SCENE_MODE_THEATRE
970     * @see #CONTROL_SCENE_MODE_BEACH
971     * @see #CONTROL_SCENE_MODE_SNOW
972     * @see #CONTROL_SCENE_MODE_SUNSET
973     * @see #CONTROL_SCENE_MODE_STEADYPHOTO
974     * @see #CONTROL_SCENE_MODE_FIREWORKS
975     * @see #CONTROL_SCENE_MODE_SPORTS
976     * @see #CONTROL_SCENE_MODE_PARTY
977     * @see #CONTROL_SCENE_MODE_CANDLELIGHT
978     * @see #CONTROL_SCENE_MODE_BARCODE
979     */
980    public static final Key<Integer> CONTROL_SCENE_MODE =
981            new Key<Integer>("android.control.sceneMode", int.class);
982
983    /**
984     * <p>Whether video stabilization is
985     * active</p>
986     * <p>If enabled, video stabilization can modify the
987     * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
988     * stabilized</p>
989     *
990     * @see CaptureRequest#SCALER_CROP_REGION
991     * @see #CONTROL_VIDEO_STABILIZATION_MODE_OFF
992     * @see #CONTROL_VIDEO_STABILIZATION_MODE_ON
993     */
994    public static final Key<Integer> CONTROL_VIDEO_STABILIZATION_MODE =
995            new Key<Integer>("android.control.videoStabilizationMode", int.class);
996
997    /**
998     * <p>Operation mode for edge
999     * enhancement.</p>
1000     * <p>Edge/sharpness/detail enhancement. OFF means no
1001     * enhancement will be applied by the camera device.</p>
1002     * <p>This must be set to one of the modes listed in {@link CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES android.edge.availableEdgeModes}.</p>
1003     * <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
1004     * will be applied. HIGH_QUALITY mode indicates that the
1005     * camera device will use the highest-quality enhancement algorithms,
1006     * even if it slows down capture rate. FAST means the camera device will
1007     * not slow down capture rate when applying edge enhancement.</p>
1008     *
1009     * @see CameraCharacteristics#EDGE_AVAILABLE_EDGE_MODES
1010     * @see #EDGE_MODE_OFF
1011     * @see #EDGE_MODE_FAST
1012     * @see #EDGE_MODE_HIGH_QUALITY
1013     */
1014    public static final Key<Integer> EDGE_MODE =
1015            new Key<Integer>("android.edge.mode", int.class);
1016
1017    /**
1018     * <p>The desired mode for for the camera device's flash control.</p>
1019     * <p>This control is only effective when flash unit is available
1020     * (<code>{@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == true</code>).</p>
1021     * <p>When this control is used, the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} must be set to ON or OFF.
1022     * Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH,
1023     * ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control.</p>
1024     * <p>When set to OFF, the camera device will not fire flash for this capture.</p>
1025     * <p>When set to SINGLE, the camera device will fire flash regardless of the camera
1026     * device's auto-exposure routine's result. When used in still capture case, this
1027     * control should be used along with AE precapture metering sequence
1028     * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p>
1029     * <p>When set to TORCH, the flash will be on continuously. This mode can be used
1030     * for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
1031     * <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
1032     *
1033     * @see CaptureRequest#CONTROL_AE_MODE
1034     * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
1035     * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
1036     * @see CaptureResult#FLASH_STATE
1037     * @see #FLASH_MODE_OFF
1038     * @see #FLASH_MODE_SINGLE
1039     * @see #FLASH_MODE_TORCH
1040     */
1041    public static final Key<Integer> FLASH_MODE =
1042            new Key<Integer>("android.flash.mode", int.class);
1043
1044    /**
1045     * <p>Set operational mode for hot pixel correction.</p>
1046     * <p>Valid modes for this camera device are listed in
1047     * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
1048     * <p>Hotpixel correction interpolates out, or otherwise removes, pixels
1049     * that do not accurately encode the incoming light (i.e. pixels that
1050     * are stuck at an arbitrary value).</p>
1051     *
1052     * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
1053     * @see #HOT_PIXEL_MODE_OFF
1054     * @see #HOT_PIXEL_MODE_FAST
1055     * @see #HOT_PIXEL_MODE_HIGH_QUALITY
1056     */
1057    public static final Key<Integer> HOT_PIXEL_MODE =
1058            new Key<Integer>("android.hotPixel.mode", int.class);
1059
1060    /**
1061     * <p>GPS coordinates to include in output JPEG
1062     * EXIF</p>
1063     */
1064    public static final Key<double[]> JPEG_GPS_COORDINATES =
1065            new Key<double[]>("android.jpeg.gpsCoordinates", double[].class);
1066
1067    /**
1068     * <p>32 characters describing GPS algorithm to
1069     * include in EXIF</p>
1070     */
1071    public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
1072            new Key<String>("android.jpeg.gpsProcessingMethod", String.class);
1073
1074    /**
1075     * <p>Time GPS fix was made to include in
1076     * EXIF</p>
1077     */
1078    public static final Key<Long> JPEG_GPS_TIMESTAMP =
1079            new Key<Long>("android.jpeg.gpsTimestamp", long.class);
1080
1081    /**
1082     * <p>Orientation of JPEG image to
1083     * write</p>
1084     */
1085    public static final Key<Integer> JPEG_ORIENTATION =
1086            new Key<Integer>("android.jpeg.orientation", int.class);
1087
1088    /**
1089     * <p>Compression quality of the final JPEG
1090     * image</p>
1091     * <p>85-95 is typical usage range</p>
1092     */
1093    public static final Key<Byte> JPEG_QUALITY =
1094            new Key<Byte>("android.jpeg.quality", byte.class);
1095
1096    /**
1097     * <p>Compression quality of JPEG
1098     * thumbnail</p>
1099     */
1100    public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
1101            new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
1102
1103    /**
1104     * <p>Resolution of embedded JPEG thumbnail</p>
1105     * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
1106     * but the captured JPEG will still be a valid image.</p>
1107     * <p>When a jpeg image capture is issued, the thumbnail size selected should have
1108     * the same aspect ratio as the jpeg image.</p>
1109     */
1110    public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
1111            new Key<android.util.Size>("android.jpeg.thumbnailSize", android.util.Size.class);
1112
1113    /**
1114     * <p>The ratio of lens focal length to the effective
1115     * aperture diameter.</p>
1116     * <p>This will only be supported on the camera devices that
1117     * have variable aperture lens. The aperture value can only be
1118     * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
1119     * <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
1120     * this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
1121     * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
1122     * to achieve manual exposure control.</p>
1123     * <p>The requested aperture value may take several frames to reach the
1124     * requested value; the camera device will report the current (intermediate)
1125     * aperture size in capture result metadata while the aperture is changing.
1126     * While the aperture is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
1127     * <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is one of
1128     * the ON modes, this will be overridden by the camera device
1129     * auto-exposure algorithm, the overridden values are then provided
1130     * back to the user in the corresponding result.</p>
1131     *
1132     * @see CaptureRequest#CONTROL_AE_MODE
1133     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
1134     * @see CaptureResult#LENS_STATE
1135     * @see CaptureRequest#SENSOR_EXPOSURE_TIME
1136     * @see CaptureRequest#SENSOR_FRAME_DURATION
1137     * @see CaptureRequest#SENSOR_SENSITIVITY
1138     */
1139    public static final Key<Float> LENS_APERTURE =
1140            new Key<Float>("android.lens.aperture", float.class);
1141
1142    /**
1143     * <p>State of lens neutral density filter(s).</p>
1144     * <p>This will not be supported on most camera devices. On devices
1145     * where this is supported, this may only be set to one of the
1146     * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
1147     * <p>Lens filters are typically used to lower the amount of light the
1148     * sensor is exposed to (measured in steps of EV). As used here, an EV
1149     * step is the standard logarithmic representation, which are
1150     * non-negative, and inversely proportional to the amount of light
1151     * hitting the sensor.  For example, setting this to 0 would result
1152     * in no reduction of the incoming light, and setting this to 2 would
1153     * mean that the filter is set to reduce incoming light by two stops
1154     * (allowing 1/4 of the prior amount of light to the sensor).</p>
1155     * <p>It may take several frames before the lens filter density changes
1156     * to the requested value. While the filter density is still changing,
1157     * {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
1158     *
1159     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
1160     * @see CaptureResult#LENS_STATE
1161     */
1162    public static final Key<Float> LENS_FILTER_DENSITY =
1163            new Key<Float>("android.lens.filterDensity", float.class);
1164
1165    /**
1166     * <p>The current lens focal length; used for optical zoom.</p>
1167     * <p>This setting controls the physical focal length of the camera
1168     * device's lens. Changing the focal length changes the field of
1169     * view of the camera device, and is usually used for optical zoom.</p>
1170     * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this
1171     * setting won't be applied instantaneously, and it may take several
1172     * frames before the lens can change to the requested focal length.
1173     * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
1174     * be set to MOVING.</p>
1175     * <p>This is expected not to be supported on most devices.</p>
1176     *
1177     * @see CaptureRequest#LENS_APERTURE
1178     * @see CaptureRequest#LENS_FOCUS_DISTANCE
1179     * @see CaptureResult#LENS_STATE
1180     */
1181    public static final Key<Float> LENS_FOCAL_LENGTH =
1182            new Key<Float>("android.lens.focalLength", float.class);
1183
1184    /**
1185     * <p>Distance to plane of sharpest focus,
1186     * measured from frontmost surface of the lens</p>
1187     * <p>0 means infinity focus. Used value will be clamped
1188     * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].</p>
1189     * <p>Like {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, this setting won't be applied
1190     * instantaneously, and it may take several frames before the lens
1191     * can move to the requested focus distance. While the lens is still moving,
1192     * {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
1193     *
1194     * @see CaptureRequest#LENS_FOCAL_LENGTH
1195     * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
1196     * @see CaptureResult#LENS_STATE
1197     */
1198    public static final Key<Float> LENS_FOCUS_DISTANCE =
1199            new Key<Float>("android.lens.focusDistance", float.class);
1200
1201    /**
1202     * <p>Sets whether the camera device uses optical image stabilization (OIS)
1203     * when capturing images.</p>
1204     * <p>OIS is used to compensate for motion blur due to small movements of
1205     * the camera during capture. Unlike digital image stabilization, OIS makes
1206     * use of mechanical elements to stabilize the camera sensor, and thus
1207     * allows for longer exposure times before camera shake becomes
1208     * apparent.</p>
1209     * <p>This is not expected to be supported on most devices.</p>
1210     * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
1211     * @see #LENS_OPTICAL_STABILIZATION_MODE_ON
1212     */
1213    public static final Key<Integer> LENS_OPTICAL_STABILIZATION_MODE =
1214            new Key<Integer>("android.lens.opticalStabilizationMode", int.class);
1215
1216    /**
1217     * <p>Mode of operation for the noise reduction
1218     * algorithm</p>
1219     * <p>Noise filtering control. OFF means no noise reduction
1220     * will be applied by the camera device.</p>
1221     * <p>This must be set to a valid mode in
1222     * {@link CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES android.noiseReduction.availableNoiseReductionModes}.</p>
1223     * <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
1224     * will be applied. HIGH_QUALITY mode indicates that the camera device
1225     * will use the highest-quality noise filtering algorithms,
1226     * even if it slows down capture rate. FAST means the camera device should not
1227     * slow down capture rate when applying noise filtering.</p>
1228     *
1229     * @see CameraCharacteristics#NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES
1230     * @see #NOISE_REDUCTION_MODE_OFF
1231     * @see #NOISE_REDUCTION_MODE_FAST
1232     * @see #NOISE_REDUCTION_MODE_HIGH_QUALITY
1233     */
1234    public static final Key<Integer> NOISE_REDUCTION_MODE =
1235            new Key<Integer>("android.noiseReduction.mode", int.class);
1236
1237    /**
1238     * <p>An application-specified ID for the current
1239     * request. Must be maintained unchanged in output
1240     * frame</p>
1241     * @hide
1242     */
1243    public static final Key<Integer> REQUEST_ID =
1244            new Key<Integer>("android.request.id", int.class);
1245
1246    /**
1247     * <p>(x, y, width, height).</p>
1248     * <p>A rectangle with the top-level corner of (x,y) and size
1249     * (width, height). The region of the sensor that is used for
1250     * output. Each stream must use this rectangle to produce its
1251     * output, cropping to a smaller region if necessary to
1252     * maintain the stream's aspect ratio.</p>
1253     * <p>HAL2.x uses only (x, y, width)</p>
1254     * <p>The crop region is applied after the RAW to other color space (e.g. YUV)
1255     * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage,
1256     * it is not croppable. The crop region will be ignored by raw streams.</p>
1257     * <p>For non-raw streams, any additional per-stream cropping will
1258     * be done to maximize the final pixel area of the stream.</p>
1259     * <p>For example, if the crop region is set to a 4:3 aspect
1260     * ratio, then 4:3 streams should use the exact crop
1261     * region. 16:9 streams should further crop vertically
1262     * (letterbox).</p>
1263     * <p>Conversely, if the crop region is set to a 16:9, then 4:3
1264     * outputs should crop horizontally (pillarbox), and 16:9
1265     * streams should match exactly. These additional crops must
1266     * be centered within the crop region.</p>
1267     * <p>The output streams must maintain square pixels at all
1268     * times, no matter what the relative aspect ratios of the
1269     * crop region and the stream are.  Negative values for
1270     * corner are allowed for raw output if full pixel array is
1271     * larger than active pixel array. Width and height may be
1272     * rounded to nearest larger supportable width, especially
1273     * for raw output, where only a few fixed scales may be
1274     * possible. The width and height of the crop region cannot
1275     * be set to be smaller than floor( activeArraySize.width /
1276     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor(
1277     * activeArraySize.height /
1278     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p>
1279     *
1280     * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
1281     */
1282    public static final Key<android.graphics.Rect> SCALER_CROP_REGION =
1283            new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class);
1284
1285    /**
1286     * <p>Duration each pixel is exposed to
1287     * light.</p>
1288     * <p>If the sensor can't expose this exact duration, it should shorten the
1289     * duration exposed to the nearest possible value (rather than expose longer).</p>
1290     */
1291    public static final Key<Long> SENSOR_EXPOSURE_TIME =
1292            new Key<Long>("android.sensor.exposureTime", long.class);
1293
1294    /**
1295     * <p>Duration from start of frame exposure to
1296     * start of next frame exposure.</p>
1297     * <p>The maximum frame rate that can be supported by a camera subsystem is
1298     * a function of many factors:</p>
1299     * <ul>
1300     * <li>Requested resolutions of output image streams</li>
1301     * <li>Availability of binning / skipping modes on the imager</li>
1302     * <li>The bandwidth of the imager interface</li>
1303     * <li>The bandwidth of the various ISP processing blocks</li>
1304     * </ul>
1305     * <p>Since these factors can vary greatly between different ISPs and
1306     * sensors, the camera abstraction tries to represent the bandwidth
1307     * restrictions with as simple a model as possible.</p>
1308     * <p>The model presented has the following characteristics:</p>
1309     * <ul>
1310     * <li>The image sensor is always configured to output the smallest
1311     * resolution possible given the application's requested output stream
1312     * sizes.  The smallest resolution is defined as being at least as large
1313     * as the largest requested output stream size; the camera pipeline must
1314     * never digitally upsample sensor data when the crop region covers the
1315     * whole sensor. In general, this means that if only small output stream
1316     * resolutions are configured, the sensor can provide a higher frame
1317     * rate.</li>
1318     * <li>Since any request may use any or all the currently configured
1319     * output streams, the sensor and ISP must be configured to support
1320     * scaling a single capture to all the streams at the same time.  This
1321     * means the camera pipeline must be ready to produce the largest
1322     * requested output size without any delay.  Therefore, the overall
1323     * frame rate of a given configured stream set is governed only by the
1324     * largest requested stream resolution.</li>
1325     * <li>Using more than one output stream in a request does not affect the
1326     * frame duration.</li>
1327     * <li>Certain format-streams may need to do additional background processing
1328     * before data is consumed/produced by that stream. These processors
1329     * can run concurrently to the rest of the camera pipeline, but
1330     * cannot process more than 1 capture at a time.</li>
1331     * </ul>
1332     * <p>The necessary information for the application, given the model above,
1333     * is provided via the {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap} field
1334     * using StreamConfigurationMap#getOutputMinFrameDuration(int, Size).
1335     * These are used to determine the maximum frame rate / minimum frame
1336     * duration that is possible for a given stream configuration.</p>
1337     * <p>Specifically, the application can use the following rules to
1338     * determine the minimum frame duration it can request from the camera
1339     * device:</p>
1340     * <ol>
1341     * <li>Let the set of currently configured input/output streams
1342     * be called <code>S</code>.</li>
1343     * <li>Find the minimum frame durations for each stream in <code>S</code>, by
1344     * looking it up in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap} using
1345     * StreamConfigurationMap#getOutputMinFrameDuration(int, Size) (with
1346     * its respective size/format). Let this set of frame durations be called
1347     * <code>F</code>.</li>
1348     * <li>For any given request <code>R</code>, the minimum frame duration allowed
1349     * for <code>R</code> is the maximum out of all values in <code>F</code>. Let the streams
1350     * used in <code>R</code> be called <code>S_r</code>.</li>
1351     * </ol>
1352     * <p>If none of the streams in <code>S_r</code> have a stall time (listed in
1353     * StreamConfigurationMap#getOutputStallDuration(int,Size) using its
1354     * respective size/format), then the frame duration in
1355     * <code>F</code> determines the steady state frame rate that the application will
1356     * get if it uses <code>R</code> as a repeating request. Let this special kind
1357     * of request be called <code>Rsimple</code>.</p>
1358     * <p>A repeating request <code>Rsimple</code> can be <em>occasionally</em> interleaved
1359     * by a single capture of a new request <code>Rstall</code> (which has at least
1360     * one in-use stream with a non-0 stall time) and if <code>Rstall</code> has the
1361     * same minimum frame duration this will not cause a frame rate loss
1362     * if all buffers from the previous <code>Rstall</code> have already been
1363     * delivered.</p>
1364     * <p>For more details about stalling, see
1365     * StreamConfigurationMap#getOutputStallDuration(int,Size).</p>
1366     *
1367     * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
1368     */
1369    public static final Key<Long> SENSOR_FRAME_DURATION =
1370            new Key<Long>("android.sensor.frameDuration", long.class);
1371
1372    /**
1373     * <p>Gain applied to image data. Must be
1374     * implemented through analog gain only if set to values
1375     * below 'maximum analog sensitivity'.</p>
1376     * <p>If the sensor can't apply this exact gain, it should lessen the
1377     * gain to the nearest possible value (rather than gain more).</p>
1378     * <p>ISO 12232:2006 REI method</p>
1379     */
1380    public static final Key<Integer> SENSOR_SENSITIVITY =
1381            new Key<Integer>("android.sensor.sensitivity", int.class);
1382
1383    /**
1384     * <p>A pixel <code>[R, G_even, G_odd, B]</code> that supplies the test pattern
1385     * when {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode} is SOLID_COLOR.</p>
1386     * <p>Each color channel is treated as an unsigned 32-bit integer.
1387     * The camera device then uses the most significant X bits
1388     * that correspond to how many bits are in its Bayer raw sensor
1389     * output.</p>
1390     * <p>For example, a sensor with RAW10 Bayer output would use the
1391     * 10 most significant bits from each color channel.</p>
1392     * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1393     *
1394     * @see CaptureRequest#SENSOR_TEST_PATTERN_MODE
1395     */
1396    public static final Key<int[]> SENSOR_TEST_PATTERN_DATA =
1397            new Key<int[]>("android.sensor.testPatternData", int[].class);
1398
1399    /**
1400     * <p>When enabled, the sensor sends a test pattern instead of
1401     * doing a real exposure from the camera.</p>
1402     * <p>When a test pattern is enabled, all manual sensor controls specified
1403     * by android.sensor.* should be ignored. All other controls should
1404     * work as normal.</p>
1405     * <p>For example, if manual flash is enabled, flash firing should still
1406     * occur (and that the test pattern remain unmodified, since the flash
1407     * would not actually affect it).</p>
1408     * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1409     * @see #SENSOR_TEST_PATTERN_MODE_OFF
1410     * @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
1411     * @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
1412     * @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY
1413     * @see #SENSOR_TEST_PATTERN_MODE_PN9
1414     * @see #SENSOR_TEST_PATTERN_MODE_CUSTOM1
1415     */
1416    public static final Key<Integer> SENSOR_TEST_PATTERN_MODE =
1417            new Key<Integer>("android.sensor.testPatternMode", int.class);
1418
1419    /**
1420     * <p>Quality of lens shading correction applied
1421     * to the image data.</p>
1422     * <p>When set to OFF mode, no lens shading correction will be applied by the
1423     * camera device, and an identity lens shading map data will be provided
1424     * if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
1425     * shading map with size specified as <code>{@link CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE android.lens.info.shadingMapSize} = [ 4, 3 ]</code>,
1426     * the output {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap} for this case will be an identity map
1427     * shown below:</p>
1428     * <pre><code>[ 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1429     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1430     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1431     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
1432     * 1.0, 1.0, 1.0, 1.0,   1.0, 1.0, 1.0, 1.0,
1433     * 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
1434     * </code></pre>
1435     * <p>When set to other modes, lens shading correction will be applied by the
1436     * camera device. Applications can request lens shading map data by setting
1437     * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
1438     * lens shading map data in {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap}, with size specified
1439     * by {@link CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE android.lens.info.shadingMapSize}; the returned shading map data will be the one
1440     * applied by the camera device for this capture request.</p>
1441     * <p>The shading map data may depend on the AE and AWB statistics, therefore the reliability
1442     * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
1443     * 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),
1444     * to get best results, it is recommended that the applications wait for the AE and AWB to
1445     * be converged before using the returned shading map data.</p>
1446     *
1447     * @see CaptureRequest#CONTROL_AE_MODE
1448     * @see CaptureRequest#CONTROL_AWB_MODE
1449     * @see CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE
1450     * @see CaptureResult#STATISTICS_LENS_SHADING_MAP
1451     * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
1452     * @see #SHADING_MODE_OFF
1453     * @see #SHADING_MODE_FAST
1454     * @see #SHADING_MODE_HIGH_QUALITY
1455     */
1456    public static final Key<Integer> SHADING_MODE =
1457            new Key<Integer>("android.shading.mode", int.class);
1458
1459    /**
1460     * <p>State of the face detector
1461     * unit</p>
1462     * <p>Whether face detection is enabled, and whether it
1463     * should output just the basic fields or the full set of
1464     * fields. Value must be one of the
1465     * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
1466     *
1467     * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
1468     * @see #STATISTICS_FACE_DETECT_MODE_OFF
1469     * @see #STATISTICS_FACE_DETECT_MODE_SIMPLE
1470     * @see #STATISTICS_FACE_DETECT_MODE_FULL
1471     */
1472    public static final Key<Integer> STATISTICS_FACE_DETECT_MODE =
1473            new Key<Integer>("android.statistics.faceDetectMode", int.class);
1474
1475    /**
1476     * <p>Operating mode for hotpixel map generation.</p>
1477     * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
1478     * If set to OFF, no hotpixel map should be returned.</p>
1479     * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
1480     *
1481     * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
1482     * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
1483     */
1484    public static final Key<Boolean> STATISTICS_HOT_PIXEL_MAP_MODE =
1485            new Key<Boolean>("android.statistics.hotPixelMapMode", boolean.class);
1486
1487    /**
1488     * <p>Whether the camera device will output the lens
1489     * shading map in output result metadata.</p>
1490     * <p>When set to ON,
1491     * {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap} must be provided in
1492     * the output result metadata.</p>
1493     *
1494     * @see CaptureResult#STATISTICS_LENS_SHADING_MAP
1495     * @see #STATISTICS_LENS_SHADING_MAP_MODE_OFF
1496     * @see #STATISTICS_LENS_SHADING_MAP_MODE_ON
1497     */
1498    public static final Key<Integer> STATISTICS_LENS_SHADING_MAP_MODE =
1499            new Key<Integer>("android.statistics.lensShadingMapMode", int.class);
1500
1501    /**
1502     * <p>Tonemapping / contrast / gamma curve for the blue
1503     * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1504     * CONTRAST_CURVE.</p>
1505     * <p>See {@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} for more details.</p>
1506     *
1507     * @see CaptureRequest#TONEMAP_CURVE_RED
1508     * @see CaptureRequest#TONEMAP_MODE
1509     */
1510    public static final Key<float[]> TONEMAP_CURVE_BLUE =
1511            new Key<float[]>("android.tonemap.curveBlue", float[].class);
1512
1513    /**
1514     * <p>Tonemapping / contrast / gamma curve for the green
1515     * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1516     * CONTRAST_CURVE.</p>
1517     * <p>See {@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} for more details.</p>
1518     *
1519     * @see CaptureRequest#TONEMAP_CURVE_RED
1520     * @see CaptureRequest#TONEMAP_MODE
1521     */
1522    public static final Key<float[]> TONEMAP_CURVE_GREEN =
1523            new Key<float[]>("android.tonemap.curveGreen", float[].class);
1524
1525    /**
1526     * <p>Tonemapping / contrast / gamma curve for the red
1527     * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1528     * CONTRAST_CURVE.</p>
1529     * <p>Each channel's curve is defined by an array of control points:</p>
1530     * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} =
1531     * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
1532     * 2 &lt;= N &lt;= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
1533     * <p>These are sorted in order of increasing <code>Pin</code>; it is always
1534     * guaranteed that input values 0.0 and 1.0 are included in the list to
1535     * define a complete mapping. For input values between control points,
1536     * the camera device must linearly interpolate between the control
1537     * points.</p>
1538     * <p>Each curve can have an independent number of points, and the number
1539     * of points can be less than max (that is, the request doesn't have to
1540     * always provide a curve with number of points equivalent to
1541     * {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}).</p>
1542     * <p>A few examples, and their corresponding graphical mappings; these
1543     * only specify the red channel and the precision is limited to 4
1544     * digits, for conciseness.</p>
1545     * <p>Linear mapping:</p>
1546     * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [ 0, 0, 1.0, 1.0 ]
1547     * </code></pre>
1548     * <p><img alt="Linear mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/linear_tonemap.png" /></p>
1549     * <p>Invert mapping:</p>
1550     * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [ 0, 1.0, 1.0, 0 ]
1551     * </code></pre>
1552     * <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
1553     * <p>Gamma 1/2.2 mapping, with 16 control points:</p>
1554     * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [
1555     * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
1556     * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
1557     * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
1558     * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
1559     * </code></pre>
1560     * <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
1561     * <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
1562     * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [
1563     * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
1564     * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
1565     * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
1566     * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
1567     * </code></pre>
1568     * <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
1569     *
1570     * @see CaptureRequest#TONEMAP_CURVE_RED
1571     * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
1572     * @see CaptureRequest#TONEMAP_MODE
1573     */
1574    public static final Key<float[]> TONEMAP_CURVE_RED =
1575            new Key<float[]>("android.tonemap.curveRed", float[].class);
1576
1577    /**
1578     * <p>High-level global contrast/gamma/tonemapping control.</p>
1579     * <p>When switching to an application-defined contrast curve by setting
1580     * {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} to CONTRAST_CURVE, the curve is defined
1581     * per-channel with a set of <code>(in, out)</code> points that specify the
1582     * mapping from input high-bit-depth pixel value to the output
1583     * low-bit-depth value.  Since the actual pixel ranges of both input
1584     * and output may change depending on the camera pipeline, the values
1585     * are specified by normalized floating-point numbers.</p>
1586     * <p>More-complex color mapping operations such as 3D color look-up
1587     * tables, selective chroma enhancement, or other non-linear color
1588     * transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1589     * CONTRAST_CURVE.</p>
1590     * <p>This must be set to a valid mode in
1591     * {@link CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES android.tonemap.availableToneMapModes}.</p>
1592     * <p>When using either FAST or HIGH_QUALITY, the camera device will
1593     * emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed},
1594     * {@link CaptureRequest#TONEMAP_CURVE_GREEN android.tonemap.curveGreen}, and {@link CaptureRequest#TONEMAP_CURVE_BLUE android.tonemap.curveBlue}.
1595     * These values are always available, and as close as possible to the
1596     * actually used nonlinear/nonglobal transforms.</p>
1597     * <p>If a request is sent with CONTRAST_CURVE with the camera device's
1598     * provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
1599     * roughly the same.</p>
1600     *
1601     * @see CameraCharacteristics#TONEMAP_AVAILABLE_TONE_MAP_MODES
1602     * @see CaptureRequest#TONEMAP_CURVE_BLUE
1603     * @see CaptureRequest#TONEMAP_CURVE_GREEN
1604     * @see CaptureRequest#TONEMAP_CURVE_RED
1605     * @see CaptureRequest#TONEMAP_MODE
1606     * @see #TONEMAP_MODE_CONTRAST_CURVE
1607     * @see #TONEMAP_MODE_FAST
1608     * @see #TONEMAP_MODE_HIGH_QUALITY
1609     */
1610    public static final Key<Integer> TONEMAP_MODE =
1611            new Key<Integer>("android.tonemap.mode", int.class);
1612
1613    /**
1614     * <p>This LED is nominally used to indicate to the user
1615     * that the camera is powered on and may be streaming images back to the
1616     * Application Processor. In certain rare circumstances, the OS may
1617     * disable this when video is processed locally and not transmitted to
1618     * any untrusted applications.</p>
1619     * <p>In particular, the LED <em>must</em> always be on when the data could be
1620     * transmitted off the device. The LED <em>should</em> always be on whenever
1621     * data is stored locally on the device.</p>
1622     * <p>The LED <em>may</em> be off if a trusted application is using the data that
1623     * doesn't violate the above rules.</p>
1624     * @hide
1625     */
1626    public static final Key<Boolean> LED_TRANSMIT =
1627            new Key<Boolean>("android.led.transmit", boolean.class);
1628
1629    /**
1630     * <p>Whether black-level compensation is locked
1631     * to its current values, or is free to vary.</p>
1632     * <p>When set to ON, the values used for black-level
1633     * compensation will not change until the lock is set to
1634     * OFF.</p>
1635     * <p>Since changes to certain capture parameters (such as
1636     * exposure time) may require resetting of black level
1637     * compensation, the camera device must report whether setting
1638     * the black level lock was successful in the output result
1639     * metadata.</p>
1640     * <p>For example, if a sequence of requests is as follows:</p>
1641     * <ul>
1642     * <li>Request 1: Exposure = 10ms, Black level lock = OFF</li>
1643     * <li>Request 2: Exposure = 10ms, Black level lock = ON</li>
1644     * <li>Request 3: Exposure = 10ms, Black level lock = ON</li>
1645     * <li>Request 4: Exposure = 20ms, Black level lock = ON</li>
1646     * <li>Request 5: Exposure = 20ms, Black level lock = ON</li>
1647     * <li>Request 6: Exposure = 20ms, Black level lock = ON</li>
1648     * </ul>
1649     * <p>And the exposure change in Request 4 requires the camera
1650     * device to reset the black level offsets, then the output
1651     * result metadata is expected to be:</p>
1652     * <ul>
1653     * <li>Result 1: Exposure = 10ms, Black level lock = OFF</li>
1654     * <li>Result 2: Exposure = 10ms, Black level lock = ON</li>
1655     * <li>Result 3: Exposure = 10ms, Black level lock = ON</li>
1656     * <li>Result 4: Exposure = 20ms, Black level lock = OFF</li>
1657     * <li>Result 5: Exposure = 20ms, Black level lock = ON</li>
1658     * <li>Result 6: Exposure = 20ms, Black level lock = ON</li>
1659     * </ul>
1660     * <p>This indicates to the application that on frame 4, black
1661     * levels were reset due to exposure value changes, and pixel
1662     * values may not be consistent across captures.</p>
1663     * <p>The camera device will maintain the lock to the extent
1664     * possible, only overriding the lock to OFF when changes to
1665     * other request parameters require a black level recalculation
1666     * or reset.</p>
1667     */
1668    public static final Key<Boolean> BLACK_LEVEL_LOCK =
1669            new Key<Boolean>("android.blackLevel.lock", boolean.class);
1670
1671    /*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
1672     * End generated code
1673     *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
1674}
1675