Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / frameworks / base / 9d454fd6096dad310a476d50b5e7175e38cdc4ea / . / core / java / android / hardware / camera2 / CaptureResult.java
blob: ab1525e6dd124328483eb5a9f94399ca9cb3b760 [file] [log] [blame]
Eino-Ville Talvalab2675542012-12-12 13:29:45 -0800[diff] [blame]1/*
2 * Copyright (C) 2012 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
Eino-Ville Talvala2f1a2e42013-07-25 17:12:05 -0700[diff] [blame]17package android.hardware.camera2;
Eino-Ville Talvalab2675542012-12-12 13:29:45 -0800[diff] [blame]18
Eino-Ville Talvala70c22072013-08-27 12:09:04 -0700[diff] [blame]19import android.hardware.camera2.impl.CameraMetadataNative;
Eino-Ville Talvalab2675542012-12-12 13:29:45 -0800[diff] [blame]20
21/**
22 * <p>The results of a single image capture from the image sensor.</p>
23 *
24 * <p>Contains the final configuration for the capture hardware (sensor, lens,
25 * flash), the processing pipeline, the control algorithms, and the output
26 * buffers.</p>
27 *
28 * <p>CaptureResults are produced by a {@link CameraDevice} after processing a
29 * {@link CaptureRequest}. All properties listed for capture requests can also
30 * be queried on the capture result, to determine the final values used for
31 * capture. The result also includes additional metadata about the state of the
32 * camera device during the capture.</p>
33 *
34 */
35public final class CaptureResult extends CameraMetadata {
Eino-Ville Talvala70c22072013-08-27 12:09:04 -0700[diff] [blame]36
37 private final CameraMetadataNative mResults;
Igor Murashkin6bbf9dc2013-09-05 12:22:00 -0700[diff] [blame]38 private final CaptureRequest mRequest;
39 private final int mSequenceId;
Eino-Ville Talvala70c22072013-08-27 12:09:04 -0700[diff] [blame]40
Igor Murashkin70725502013-06-25 20:27:06 +0000[diff] [blame]41 /**
Eino-Ville Talvala70c22072013-08-27 12:09:04 -0700[diff] [blame]42 * Takes ownership of the passed-in properties object
Igor Murashkin70725502013-06-25 20:27:06 +0000[diff] [blame]43 * @hide
44 */
Igor Murashkin6bbf9dc2013-09-05 12:22:00 -0700[diff] [blame]45 public CaptureResult(CameraMetadataNative results, CaptureRequest parent, int sequenceId) {
46 if (results == null) {
47 throw new IllegalArgumentException("results was null");
48 }
49
50 if (parent == null) {
51 throw new IllegalArgumentException("parent was null");
52 }
53
Eino-Ville Talvala70c22072013-08-27 12:09:04 -0700[diff] [blame]54 mResults = results;
Igor Murashkin6bbf9dc2013-09-05 12:22:00 -0700[diff] [blame]55 mRequest = parent;
56 mSequenceId = sequenceId;
Eino-Ville Talvala70c22072013-08-27 12:09:04 -0700[diff] [blame]57 }
58
59 @Override
60 public <T> T get(Key<T> key) {
61 return mResults.get(key);
Eino-Ville Talvalab2675542012-12-12 13:29:45 -0800[diff] [blame]62 }
63
Igor Murashkin6bbf9dc2013-09-05 12:22:00 -0700[diff] [blame]64 /**
65 * Get the request associated with this result.
66 *
67 * <p>Whenever a request is successfully captured, with
68 * {@link CameraDevice.CaptureListener#onCaptureCompleted},
69 * the {@code result}'s {@code getRequest()} will return that {@code request}.
70 * </p>
71 *
72 * <p>In particular,
73 * <code><pre>cameraDevice.capture(someRequest, new CaptureListener() {
74 * {@literal @}Override
75 * void onCaptureCompleted(CaptureRequest myRequest, CaptureResult myResult) {
76 * assert(myResult.getRequest.equals(myRequest) == true);
77 * }
78 * };
79 * </code></pre>
80 * </p>
81 *
82 * @return The request associated with this result. Never {@code null}.
83 */
84 public CaptureRequest getRequest() {
85 return mRequest;
86 }
87
88 /**
89 * Get the frame number associated with this result.
90 *
91 * <p>Whenever a request has been processed, regardless of failure or success,
92 * it gets a unique frame number assigned to its future result/failure.</p>
93 *
94 * <p>This value monotonically increments, starting with 0,
95 * for every new result or failure; and the scope is the lifetime of the
96 * {@link CameraDevice}.</p>
97 *
98 * @return int frame number
99 */
100 public int getFrameNumber() {
101 return get(REQUEST_FRAME_COUNT);
102 }
103
104 /**
105 * The sequence ID for this failure that was returned by the
106 * {@link CameraDevice#capture} family of functions.
107 *
108 * <p>The sequence ID is a unique monotonically increasing value starting from 0,
109 * incremented every time a new group of requests is submitted to the CameraDevice.</p>
110 *
111 * @return int The ID for the sequence of requests that this capture result is a part of
112 *
113 * @see CameraDevice.CaptureListener#onCaptureSequenceCompleted
114 */
115 public int getSequenceId() {
116 return mSequenceId;
117 }
118
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]119 /*@O~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
120 * The key entries below this point are generated from metadata
121 * definitions in /system/media/camera/docs. Do not modify by hand or
122 * modify the comment blocks at the start or end.
123 *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
124
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]125
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]126 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]127 * <p>A color transform matrix to use to transform
128 * from sensor RGB color space to output linear sRGB color space</p>
Zhijun He49a3ca92014-02-05 13:48:09 -0800[diff] [blame]129 * <p>This matrix is either set by the camera device when the request
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]130 * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]131 * directly by the application in the request when the
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]132 * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is TRANSFORM_MATRIX.</p>
Zhijun He49a3ca92014-02-05 13:48:09 -0800[diff] [blame]133 * <p>In the latter case, the camera device may round the matrix to account
134 * for precision issues; the final rounded matrix should be reported back
135 * in this matrix result metadata. The transform should keep the magnitude
136 * of the output color values within <code>[0, 1.0]</code> (assuming input color
137 * values is within the normalized range <code>[0, 1.0]</code>), or clipping may occur.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]138 *
139 * @see CaptureRequest#COLOR_CORRECTION_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]140 */
141 public static final Key<Rational[]> COLOR_CORRECTION_TRANSFORM =
142 new Key<Rational[]>("android.colorCorrection.transform", Rational[].class);
143
144 /**
Igor Murashkin7d2a5c52014-01-17 15:07:52 -0800[diff] [blame]145 * <p>Gains applying to Bayer raw color channels for
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]146 * white-balance.</p>
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]147 * <p>The 4-channel white-balance gains are defined in
Igor Murashkin7d2a5c52014-01-17 15:07:52 -0800[diff] [blame]148 * the order of <code>[R G_even G_odd B]</code>, where <code>G_even</code> is the gain
149 * for green pixels on even rows of the output, and <code>G_odd</code>
150 * is the gain for green pixels on the odd rows. if a HAL
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]151 * does not support a separate gain for even/odd green channels,
Igor Murashkin7d2a5c52014-01-17 15:07:52 -0800[diff] [blame]152 * it should use the <code>G_even</code> value, and write <code>G_odd</code> equal to
153 * <code>G_even</code> in the output result metadata.</p>
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]154 * <p>This array is either set by the camera device when the request
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]155 * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or
Igor Murashkind5ff06a2013-08-20 15:15:06 -0700[diff] [blame]156 * directly by the application in the request when the
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]157 * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is TRANSFORM_MATRIX.</p>
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]158 * <p>The output should be the gains actually applied by the camera device to
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]159 * the current frame.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]160 *
161 * @see CaptureRequest#COLOR_CORRECTION_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]162 */
163 public static final Key<float[]> COLOR_CORRECTION_GAINS =
164 new Key<float[]>("android.colorCorrection.gains", float[].class);
165
166 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]167 * <p>The ID sent with the latest
168 * CAMERA2_TRIGGER_PRECAPTURE_METERING call</p>
169 * <p>Must be 0 if no
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]170 * CAMERA2_TRIGGER_PRECAPTURE_METERING trigger received yet
171 * by HAL. Always updated even if AE algorithm ignores the
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]172 * trigger</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]173 * @hide
174 */
175 public static final Key<Integer> CONTROL_AE_PRECAPTURE_ID =
176 new Key<Integer>("android.control.aePrecaptureId", int.class);
177
178 /**
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]179 * <p>The desired mode for the camera device's
180 * auto-exposure routine.</p>
181 * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is
182 * AUTO.</p>
183 * <p>When set to any of the ON modes, the camera device's
184 * auto-exposure routine is enabled, overriding the
185 * application's selected exposure time, sensor sensitivity,
186 * and frame duration ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
187 * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and
188 * {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}). If one of the FLASH modes
189 * is selected, the camera device's flash unit controls are
190 * also overridden.</p>
191 * <p>The FLASH modes are only available if the camera device
192 * has a flash unit ({@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} is <code>true</code>).</p>
193 * <p>If flash TORCH mode is desired, this field must be set to
194 * ON or OFF, and {@link CaptureRequest#FLASH_MODE android.flash.mode} set to TORCH.</p>
195 * <p>When set to any of the ON modes, the values chosen by the
196 * camera device auto-exposure routine for the overridden
197 * fields for a given capture will be available in its
198 * CaptureResult.</p>
199 *
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]200 * @see CaptureRequest#CONTROL_MODE
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]201 * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
202 * @see CaptureRequest#FLASH_MODE
Igor Murashkinaef3b7e2014-01-15 13:20:37 -0800[diff] [blame]203 * @see CaptureRequest#SENSOR_EXPOSURE_TIME
204 * @see CaptureRequest#SENSOR_FRAME_DURATION
Zhijun He399f05d2014-01-15 11:31:30 -0800[diff] [blame]205 * @see CaptureRequest#SENSOR_SENSITIVITY
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]206 * @see #CONTROL_AE_MODE_OFF
207 * @see #CONTROL_AE_MODE_ON
208 * @see #CONTROL_AE_MODE_ON_AUTO_FLASH
209 * @see #CONTROL_AE_MODE_ON_ALWAYS_FLASH
210 * @see #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE
211 */
212 public static final Key<Integer> CONTROL_AE_MODE =
213 new Key<Integer>("android.control.aeMode", int.class);
214
215 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]216 * <p>List of areas to use for
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]217 * metering.</p>
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]218 * <p>Each area is a rectangle plus weight: xmin, ymin,
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]219 * xmax, ymax, weight. The rectangle is defined to be inclusive of the
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]220 * specified coordinates.</p>
221 * <p>The coordinate system is based on the active pixel array,
Timothy Knight2629f272013-09-03 17:23:23 -0700[diff] [blame]222 * with (0,0) being the top-left pixel in the active pixel array, and
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]223 * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
224 * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
Timothy Knight2629f272013-09-03 17:23:23 -0700[diff] [blame]225 * bottom-right pixel in the active pixel array. The weight
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]226 * should be nonnegative.</p>
227 * <p>If all regions have 0 weight, then no specific metering area
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]228 * needs to be used by the camera device. If the metering region is
229 * outside the current {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}, the camera device
230 * will ignore the sections outside the region and output the
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]231 * used sections in the frame metadata.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]232 *
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]233 * @see CaptureRequest#SCALER_CROP_REGION
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]234 * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]235 */
236 public static final Key<int[]> CONTROL_AE_REGIONS =
237 new Key<int[]>("android.control.aeRegions", int[].class);
238
239 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]240 * <p>Current state of AE algorithm</p>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]241 * <p>Switching between or enabling AE modes ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}) always
242 * resets the AE state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
243 * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
244 * the algorithm states to INACTIVE.</p>
245 * <p>The camera device can do several state transitions between two results, if it is
246 * allowed by the state transition table. For example: INACTIVE may never actually be
247 * seen in a result.</p>
248 * <p>The state in the result is the state for this image (in sync with this image): if
249 * AE state becomes CONVERGED, then the image data associated with this result should
250 * be good to use.</p>
251 * <p>Below are state transition tables for different AE modes.</p>
252 * <table>
253 * <thead>
254 * <tr>
255 * <th align="center">State</th>
256 * <th align="center">Transition Cause</th>
257 * <th align="center">New State</th>
258 * <th align="center">Notes</th>
259 * </tr>
260 * </thead>
261 * <tbody>
262 * <tr>
263 * <td align="center">INACTIVE</td>
264 * <td align="center"></td>
265 * <td align="center">INACTIVE</td>
266 * <td align="center">Camera device auto exposure algorithm is disabled</td>
267 * </tr>
268 * </tbody>
269 * </table>
270 * <p>When {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is AE_MODE_ON_*:</p>
271 * <table>
272 * <thead>
273 * <tr>
274 * <th align="center">State</th>
275 * <th align="center">Transition Cause</th>
276 * <th align="center">New State</th>
277 * <th align="center">Notes</th>
278 * </tr>
279 * </thead>
280 * <tbody>
281 * <tr>
282 * <td align="center">INACTIVE</td>
283 * <td align="center">Camera device initiates AE scan</td>
284 * <td align="center">SEARCHING</td>
285 * <td align="center">Values changing</td>
286 * </tr>
287 * <tr>
288 * <td align="center">INACTIVE</td>
289 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
290 * <td align="center">LOCKED</td>
291 * <td align="center">Values locked</td>
292 * </tr>
293 * <tr>
294 * <td align="center">SEARCHING</td>
295 * <td align="center">Camera device finishes AE scan</td>
296 * <td align="center">CONVERGED</td>
297 * <td align="center">Good values, not changing</td>
298 * </tr>
299 * <tr>
300 * <td align="center">SEARCHING</td>
301 * <td align="center">Camera device finishes AE scan</td>
302 * <td align="center">FLASH_REQUIRED</td>
303 * <td align="center">Converged but too dark w/o flash</td>
304 * </tr>
305 * <tr>
306 * <td align="center">SEARCHING</td>
307 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
308 * <td align="center">LOCKED</td>
309 * <td align="center">Values locked</td>
310 * </tr>
311 * <tr>
312 * <td align="center">CONVERGED</td>
313 * <td align="center">Camera device initiates AE scan</td>
314 * <td align="center">SEARCHING</td>
315 * <td align="center">Values changing</td>
316 * </tr>
317 * <tr>
318 * <td align="center">CONVERGED</td>
319 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
320 * <td align="center">LOCKED</td>
321 * <td align="center">Values locked</td>
322 * </tr>
323 * <tr>
324 * <td align="center">FLASH_REQUIRED</td>
325 * <td align="center">Camera device initiates AE scan</td>
326 * <td align="center">SEARCHING</td>
327 * <td align="center">Values changing</td>
328 * </tr>
329 * <tr>
330 * <td align="center">FLASH_REQUIRED</td>
331 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
332 * <td align="center">LOCKED</td>
333 * <td align="center">Values locked</td>
334 * </tr>
335 * <tr>
336 * <td align="center">LOCKED</td>
337 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
338 * <td align="center">SEARCHING</td>
339 * <td align="center">Values not good after unlock</td>
340 * </tr>
341 * <tr>
342 * <td align="center">LOCKED</td>
343 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
344 * <td align="center">CONVERGED</td>
345 * <td align="center">Values good after unlock</td>
346 * </tr>
347 * <tr>
348 * <td align="center">LOCKED</td>
349 * <td align="center">{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
350 * <td align="center">FLASH_REQUIRED</td>
351 * <td align="center">Exposure good, but too dark</td>
352 * </tr>
353 * <tr>
354 * <td align="center">PRECAPTURE</td>
355 * <td align="center">Sequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is OFF</td>
356 * <td align="center">CONVERGED</td>
357 * <td align="center">Ready for high-quality capture</td>
358 * </tr>
359 * <tr>
360 * <td align="center">PRECAPTURE</td>
361 * <td align="center">Sequence done. {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} is ON</td>
362 * <td align="center">LOCKED</td>
363 * <td align="center">Ready for high-quality capture</td>
364 * </tr>
365 * <tr>
366 * <td align="center">Any state</td>
367 * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START</td>
368 * <td align="center">PRECAPTURE</td>
369 * <td align="center">Start AE precapture metering sequence</td>
370 * </tr>
371 * </tbody>
372 * </table>
Zhijun He60b19dc2014-02-24 10:19:20 -0800[diff] [blame]373 * <p>For the above table, the camera device may skip reporting any state changes that happen
374 * without application intervention (i.e. mode switch, trigger, locking). Any state that
375 * can be skipped in that manner is called a transient state.</p>
376 * <p>For example, for above AE modes (AE_MODE_ON_*), in addition to the state transitions
377 * listed in above table, it is also legal for the camera device to skip one or more
378 * transient states between two results. See below table for examples:</p>
379 * <table>
380 * <thead>
381 * <tr>
382 * <th align="center">State</th>
383 * <th align="center">Transition Cause</th>
384 * <th align="center">New State</th>
385 * <th align="center">Notes</th>
386 * </tr>
387 * </thead>
388 * <tbody>
389 * <tr>
390 * <td align="center">INACTIVE</td>
391 * <td align="center">Camera device finished AE scan</td>
392 * <td align="center">CONVERGED</td>
393 * <td align="center">Values are already good, transient states are skipped by camera device.</td>
394 * </tr>
395 * <tr>
396 * <td align="center">Any state</td>
397 * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START, sequence done</td>
398 * <td align="center">FLASH_REQUIRED</td>
399 * <td align="center">Converged but too dark w/o flash after a precapture sequence, transient states are skipped by camera device.</td>
400 * </tr>
401 * <tr>
402 * <td align="center">Any state</td>
403 * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START, sequence done</td>
404 * <td align="center">CONVERGED</td>
405 * <td align="center">Converged after a precapture sequence, transient states are skipped by camera device.</td>
406 * </tr>
407 * <tr>
408 * <td align="center">CONVERGED</td>
409 * <td align="center">Camera device finished AE scan</td>
410 * <td align="center">FLASH_REQUIRED</td>
411 * <td align="center">Converged but too dark w/o flash after a new scan, transient states are skipped by camera device.</td>
412 * </tr>
413 * <tr>
414 * <td align="center">FLASH_REQUIRED</td>
415 * <td align="center">Camera device finished AE scan</td>
416 * <td align="center">CONVERGED</td>
417 * <td align="center">Converged after a new scan, transient states are skipped by camera device.</td>
418 * </tr>
419 * </tbody>
420 * </table>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]421 *
422 * @see CaptureRequest#CONTROL_AE_LOCK
423 * @see CaptureRequest#CONTROL_AE_MODE
424 * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
425 * @see CaptureRequest#CONTROL_MODE
426 * @see CaptureRequest#CONTROL_SCENE_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]427 * @see #CONTROL_AE_STATE_INACTIVE
428 * @see #CONTROL_AE_STATE_SEARCHING
429 * @see #CONTROL_AE_STATE_CONVERGED
430 * @see #CONTROL_AE_STATE_LOCKED
431 * @see #CONTROL_AE_STATE_FLASH_REQUIRED
432 * @see #CONTROL_AE_STATE_PRECAPTURE
433 */
434 public static final Key<Integer> CONTROL_AE_STATE =
435 new Key<Integer>("android.control.aeState", int.class);
436
437 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]438 * <p>Whether AF is currently enabled, and what
439 * mode it is set to</p>
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]440 * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus
441 * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} &gt; 0</code>).</p>
Zhijun He78146ec2014-01-14 18:12:13 -0800[diff] [blame]442 * <p>If the lens is controlled by the camera device auto-focus algorithm,
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]443 * the camera device will report the current AF status in {@link CaptureResult#CONTROL_AF_STATE android.control.afState}
Zhijun He78146ec2014-01-14 18:12:13 -0800[diff] [blame]444 * in result metadata.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]445 *
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]446 * @see CaptureResult#CONTROL_AF_STATE
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]447 * @see CaptureRequest#CONTROL_MODE
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]448 * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]449 * @see #CONTROL_AF_MODE_OFF
450 * @see #CONTROL_AF_MODE_AUTO
451 * @see #CONTROL_AF_MODE_MACRO
452 * @see #CONTROL_AF_MODE_CONTINUOUS_VIDEO
453 * @see #CONTROL_AF_MODE_CONTINUOUS_PICTURE
454 * @see #CONTROL_AF_MODE_EDOF
455 */
456 public static final Key<Integer> CONTROL_AF_MODE =
457 new Key<Integer>("android.control.afMode", int.class);
458
459 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]460 * <p>List of areas to use for focus
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]461 * estimation.</p>
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]462 * <p>Each area is a rectangle plus weight: xmin, ymin,
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]463 * xmax, ymax, weight. The rectangle is defined to be inclusive of the
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]464 * specified coordinates.</p>
465 * <p>The coordinate system is based on the active pixel array,
Timothy Knight2629f272013-09-03 17:23:23 -0700[diff] [blame]466 * with (0,0) being the top-left pixel in the active pixel array, and
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]467 * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
468 * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
Timothy Knight2629f272013-09-03 17:23:23 -0700[diff] [blame]469 * bottom-right pixel in the active pixel array. The weight
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]470 * should be nonnegative.</p>
471 * <p>If all regions have 0 weight, then no specific focus area
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]472 * needs to be used by the camera device. If the focusing region is
473 * outside the current {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}, the camera device
474 * will ignore the sections outside the region and output the
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]475 * used sections in the frame metadata.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]476 *
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]477 * @see CaptureRequest#SCALER_CROP_REGION
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]478 * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]479 */
480 public static final Key<int[]> CONTROL_AF_REGIONS =
481 new Key<int[]>("android.control.afRegions", int[].class);
482
483 /**
Zhijun He60b19dc2014-02-24 10:19:20 -0800[diff] [blame]484 * <p>Current state of AF algorithm.</p>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]485 * <p>Switching between or enabling AF modes ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) always
486 * resets the AF state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
487 * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
488 * the algorithm states to INACTIVE.</p>
489 * <p>The camera device can do several state transitions between two results, if it is
490 * allowed by the state transition table. For example: INACTIVE may never actually be
491 * seen in a result.</p>
492 * <p>The state in the result is the state for this image (in sync with this image): if
493 * AF state becomes FOCUSED, then the image data associated with this result should
494 * be sharp.</p>
495 * <p>Below are state transition tables for different AF modes.</p>
496 * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_OFF or AF_MODE_EDOF:</p>
497 * <table>
498 * <thead>
499 * <tr>
500 * <th align="center">State</th>
501 * <th align="center">Transition Cause</th>
502 * <th align="center">New State</th>
503 * <th align="center">Notes</th>
504 * </tr>
505 * </thead>
506 * <tbody>
507 * <tr>
508 * <td align="center">INACTIVE</td>
509 * <td align="center"></td>
510 * <td align="center">INACTIVE</td>
511 * <td align="center">Never changes</td>
512 * </tr>
513 * </tbody>
514 * </table>
515 * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_AUTO or AF_MODE_MACRO:</p>
516 * <table>
517 * <thead>
518 * <tr>
519 * <th align="center">State</th>
520 * <th align="center">Transition Cause</th>
521 * <th align="center">New State</th>
522 * <th align="center">Notes</th>
523 * </tr>
524 * </thead>
525 * <tbody>
526 * <tr>
527 * <td align="center">INACTIVE</td>
528 * <td align="center">AF_TRIGGER</td>
529 * <td align="center">ACTIVE_SCAN</td>
530 * <td align="center">Start AF sweep, Lens now moving</td>
531 * </tr>
532 * <tr>
533 * <td align="center">ACTIVE_SCAN</td>
534 * <td align="center">AF sweep done</td>
535 * <td align="center">FOCUSED_LOCKED</td>
536 * <td align="center">Focused, Lens now locked</td>
537 * </tr>
538 * <tr>
539 * <td align="center">ACTIVE_SCAN</td>
540 * <td align="center">AF sweep done</td>
541 * <td align="center">NOT_FOCUSED_LOCKED</td>
542 * <td align="center">Not focused, Lens now locked</td>
543 * </tr>
544 * <tr>
545 * <td align="center">ACTIVE_SCAN</td>
546 * <td align="center">AF_CANCEL</td>
547 * <td align="center">INACTIVE</td>
548 * <td align="center">Cancel/reset AF, Lens now locked</td>
549 * </tr>
550 * <tr>
551 * <td align="center">FOCUSED_LOCKED</td>
552 * <td align="center">AF_CANCEL</td>
553 * <td align="center">INACTIVE</td>
554 * <td align="center">Cancel/reset AF</td>
555 * </tr>
556 * <tr>
557 * <td align="center">FOCUSED_LOCKED</td>
558 * <td align="center">AF_TRIGGER</td>
559 * <td align="center">ACTIVE_SCAN</td>
560 * <td align="center">Start new sweep, Lens now moving</td>
561 * </tr>
562 * <tr>
563 * <td align="center">NOT_FOCUSED_LOCKED</td>
564 * <td align="center">AF_CANCEL</td>
565 * <td align="center">INACTIVE</td>
566 * <td align="center">Cancel/reset AF</td>
567 * </tr>
568 * <tr>
569 * <td align="center">NOT_FOCUSED_LOCKED</td>
570 * <td align="center">AF_TRIGGER</td>
571 * <td align="center">ACTIVE_SCAN</td>
572 * <td align="center">Start new sweep, Lens now moving</td>
573 * </tr>
574 * <tr>
575 * <td align="center">Any state</td>
576 * <td align="center">Mode change</td>
577 * <td align="center">INACTIVE</td>
578 * <td align="center"></td>
579 * </tr>
580 * </tbody>
581 * </table>
Zhijun He60b19dc2014-02-24 10:19:20 -0800[diff] [blame]582 * <p>For the above table, the camera device may skip reporting any state changes that happen
583 * without application intervention (i.e. mode switch, trigger, locking). Any state that
584 * can be skipped in that manner is called a transient state.</p>
585 * <p>For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the
586 * state transitions listed in above table, it is also legal for the camera device to skip
587 * one or more transient states between two results. See below table for examples:</p>
588 * <table>
589 * <thead>
590 * <tr>
591 * <th align="center">State</th>
592 * <th align="center">Transition Cause</th>
593 * <th align="center">New State</th>
594 * <th align="center">Notes</th>
595 * </tr>
596 * </thead>
597 * <tbody>
598 * <tr>
599 * <td align="center">INACTIVE</td>
600 * <td align="center">AF_TRIGGER</td>
601 * <td align="center">FOCUSED_LOCKED</td>
602 * <td align="center">Focus is already good or good after a scan, lens is now locked.</td>
603 * </tr>
604 * <tr>
605 * <td align="center">INACTIVE</td>
606 * <td align="center">AF_TRIGGER</td>
607 * <td align="center">NOT_FOCUSED_LOCKED</td>
608 * <td align="center">Focus failed after a scan, lens is now locked.</td>
609 * </tr>
610 * <tr>
611 * <td align="center">FOCUSED_LOCKED</td>
612 * <td align="center">AF_TRIGGER</td>
613 * <td align="center">FOCUSED_LOCKED</td>
614 * <td align="center">Focus is already good or good after a scan, lens is now locked.</td>
615 * </tr>
616 * <tr>
617 * <td align="center">NOT_FOCUSED_LOCKED</td>
618 * <td align="center">AF_TRIGGER</td>
619 * <td align="center">FOCUSED_LOCKED</td>
620 * <td align="center">Focus is good after a scan, lens is not locked.</td>
621 * </tr>
622 * </tbody>
623 * </table>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]624 * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_VIDEO:</p>
625 * <table>
626 * <thead>
627 * <tr>
628 * <th align="center">State</th>
629 * <th align="center">Transition Cause</th>
630 * <th align="center">New State</th>
631 * <th align="center">Notes</th>
632 * </tr>
633 * </thead>
634 * <tbody>
635 * <tr>
636 * <td align="center">INACTIVE</td>
637 * <td align="center">Camera device initiates new scan</td>
638 * <td align="center">PASSIVE_SCAN</td>
639 * <td align="center">Start AF scan, Lens now moving</td>
640 * </tr>
641 * <tr>
642 * <td align="center">INACTIVE</td>
643 * <td align="center">AF_TRIGGER</td>
644 * <td align="center">NOT_FOCUSED_LOCKED</td>
645 * <td align="center">AF state query, Lens now locked</td>
646 * </tr>
647 * <tr>
648 * <td align="center">PASSIVE_SCAN</td>
649 * <td align="center">Camera device completes current scan</td>
650 * <td align="center">PASSIVE_FOCUSED</td>
651 * <td align="center">End AF scan, Lens now locked</td>
652 * </tr>
653 * <tr>
654 * <td align="center">PASSIVE_SCAN</td>
655 * <td align="center">Camera device fails current scan</td>
656 * <td align="center">PASSIVE_UNFOCUSED</td>
657 * <td align="center">End AF scan, Lens now locked</td>
658 * </tr>
659 * <tr>
660 * <td align="center">PASSIVE_SCAN</td>
661 * <td align="center">AF_TRIGGER</td>
662 * <td align="center">FOCUSED_LOCKED</td>
663 * <td align="center">Immediate trans. If focus is good, Lens now locked</td>
664 * </tr>
665 * <tr>
666 * <td align="center">PASSIVE_SCAN</td>
667 * <td align="center">AF_TRIGGER</td>
668 * <td align="center">NOT_FOCUSED_LOCKED</td>
669 * <td align="center">Immediate trans. if focus is bad, Lens now locked</td>
670 * </tr>
671 * <tr>
672 * <td align="center">PASSIVE_SCAN</td>
673 * <td align="center">AF_CANCEL</td>
674 * <td align="center">INACTIVE</td>
675 * <td align="center">Reset lens position, Lens now locked</td>
676 * </tr>
677 * <tr>
678 * <td align="center">PASSIVE_FOCUSED</td>
679 * <td align="center">Camera device initiates new scan</td>
680 * <td align="center">PASSIVE_SCAN</td>
681 * <td align="center">Start AF scan, Lens now moving</td>
682 * </tr>
683 * <tr>
684 * <td align="center">PASSIVE_UNFOCUSED</td>
685 * <td align="center">Camera device initiates new scan</td>
686 * <td align="center">PASSIVE_SCAN</td>
687 * <td align="center">Start AF scan, Lens now moving</td>
688 * </tr>
689 * <tr>
690 * <td align="center">PASSIVE_FOCUSED</td>
691 * <td align="center">AF_TRIGGER</td>
692 * <td align="center">FOCUSED_LOCKED</td>
693 * <td align="center">Immediate trans. Lens now locked</td>
694 * </tr>
695 * <tr>
696 * <td align="center">PASSIVE_UNFOCUSED</td>
697 * <td align="center">AF_TRIGGER</td>
698 * <td align="center">NOT_FOCUSED_LOCKED</td>
699 * <td align="center">Immediate trans. Lens now locked</td>
700 * </tr>
701 * <tr>
702 * <td align="center">FOCUSED_LOCKED</td>
703 * <td align="center">AF_TRIGGER</td>
704 * <td align="center">FOCUSED_LOCKED</td>
705 * <td align="center">No effect</td>
706 * </tr>
707 * <tr>
708 * <td align="center">FOCUSED_LOCKED</td>
709 * <td align="center">AF_CANCEL</td>
710 * <td align="center">INACTIVE</td>
711 * <td align="center">Restart AF scan</td>
712 * </tr>
713 * <tr>
714 * <td align="center">NOT_FOCUSED_LOCKED</td>
715 * <td align="center">AF_TRIGGER</td>
716 * <td align="center">NOT_FOCUSED_LOCKED</td>
717 * <td align="center">No effect</td>
718 * </tr>
719 * <tr>
720 * <td align="center">NOT_FOCUSED_LOCKED</td>
721 * <td align="center">AF_CANCEL</td>
722 * <td align="center">INACTIVE</td>
723 * <td align="center">Restart AF scan</td>
724 * </tr>
725 * </tbody>
726 * </table>
727 * <p>When {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode} is AF_MODE_CONTINUOUS_PICTURE:</p>
728 * <table>
729 * <thead>
730 * <tr>
731 * <th align="center">State</th>
732 * <th align="center">Transition Cause</th>
733 * <th align="center">New State</th>
734 * <th align="center">Notes</th>
735 * </tr>
736 * </thead>
737 * <tbody>
738 * <tr>
739 * <td align="center">INACTIVE</td>
740 * <td align="center">Camera device initiates new scan</td>
741 * <td align="center">PASSIVE_SCAN</td>
742 * <td align="center">Start AF scan, Lens now moving</td>
743 * </tr>
744 * <tr>
745 * <td align="center">INACTIVE</td>
746 * <td align="center">AF_TRIGGER</td>
747 * <td align="center">NOT_FOCUSED_LOCKED</td>
748 * <td align="center">AF state query, Lens now locked</td>
749 * </tr>
750 * <tr>
751 * <td align="center">PASSIVE_SCAN</td>
752 * <td align="center">Camera device completes current scan</td>
753 * <td align="center">PASSIVE_FOCUSED</td>
754 * <td align="center">End AF scan, Lens now locked</td>
755 * </tr>
756 * <tr>
757 * <td align="center">PASSIVE_SCAN</td>
758 * <td align="center">Camera device fails current scan</td>
759 * <td align="center">PASSIVE_UNFOCUSED</td>
760 * <td align="center">End AF scan, Lens now locked</td>
761 * </tr>
762 * <tr>
763 * <td align="center">PASSIVE_SCAN</td>
764 * <td align="center">AF_TRIGGER</td>
765 * <td align="center">FOCUSED_LOCKED</td>
766 * <td align="center">Eventual trans. once focus good, Lens now locked</td>
767 * </tr>
768 * <tr>
769 * <td align="center">PASSIVE_SCAN</td>
770 * <td align="center">AF_TRIGGER</td>
771 * <td align="center">NOT_FOCUSED_LOCKED</td>
772 * <td align="center">Eventual trans. if cannot focus, Lens now locked</td>
773 * </tr>
774 * <tr>
775 * <td align="center">PASSIVE_SCAN</td>
776 * <td align="center">AF_CANCEL</td>
777 * <td align="center">INACTIVE</td>
778 * <td align="center">Reset lens position, Lens now locked</td>
779 * </tr>
780 * <tr>
781 * <td align="center">PASSIVE_FOCUSED</td>
782 * <td align="center">Camera device initiates new scan</td>
783 * <td align="center">PASSIVE_SCAN</td>
784 * <td align="center">Start AF scan, Lens now moving</td>
785 * </tr>
786 * <tr>
787 * <td align="center">PASSIVE_UNFOCUSED</td>
788 * <td align="center">Camera device initiates new scan</td>
789 * <td align="center">PASSIVE_SCAN</td>
790 * <td align="center">Start AF scan, Lens now moving</td>
791 * </tr>
792 * <tr>
793 * <td align="center">PASSIVE_FOCUSED</td>
794 * <td align="center">AF_TRIGGER</td>
795 * <td align="center">FOCUSED_LOCKED</td>
796 * <td align="center">Immediate trans. Lens now locked</td>
797 * </tr>
798 * <tr>
799 * <td align="center">PASSIVE_UNFOCUSED</td>
800 * <td align="center">AF_TRIGGER</td>
801 * <td align="center">NOT_FOCUSED_LOCKED</td>
802 * <td align="center">Immediate trans. Lens now locked</td>
803 * </tr>
804 * <tr>
805 * <td align="center">FOCUSED_LOCKED</td>
806 * <td align="center">AF_TRIGGER</td>
807 * <td align="center">FOCUSED_LOCKED</td>
808 * <td align="center">No effect</td>
809 * </tr>
810 * <tr>
811 * <td align="center">FOCUSED_LOCKED</td>
812 * <td align="center">AF_CANCEL</td>
813 * <td align="center">INACTIVE</td>
814 * <td align="center">Restart AF scan</td>
815 * </tr>
816 * <tr>
817 * <td align="center">NOT_FOCUSED_LOCKED</td>
818 * <td align="center">AF_TRIGGER</td>
819 * <td align="center">NOT_FOCUSED_LOCKED</td>
820 * <td align="center">No effect</td>
821 * </tr>
822 * <tr>
823 * <td align="center">NOT_FOCUSED_LOCKED</td>
824 * <td align="center">AF_CANCEL</td>
825 * <td align="center">INACTIVE</td>
826 * <td align="center">Restart AF scan</td>
827 * </tr>
828 * </tbody>
829 * </table>
Zhijun He60b19dc2014-02-24 10:19:20 -0800[diff] [blame]830 * <p>When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO
831 * (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the
832 * camera device. When a trigger is included in a mode switch request, the trigger
833 * will be evaluated in the context of the new mode in the request.
834 * See below table for examples:</p>
835 * <table>
836 * <thead>
837 * <tr>
838 * <th align="center">State</th>
839 * <th align="center">Transition Cause</th>
840 * <th align="center">New State</th>
841 * <th align="center">Notes</th>
842 * </tr>
843 * </thead>
844 * <tbody>
845 * <tr>
846 * <td align="center">any state</td>
847 * <td align="center">CAF--&gt;AUTO mode switch</td>
848 * <td align="center">INACTIVE</td>
849 * <td align="center">Mode switch without trigger, initial state must be INACTIVE</td>
850 * </tr>
851 * <tr>
852 * <td align="center">any state</td>
853 * <td align="center">CAF--&gt;AUTO mode switch with AF_TRIGGER</td>
854 * <td align="center">trigger-reachable states from INACTIVE</td>
855 * <td align="center">Mode switch with trigger, INACTIVE is skipped</td>
856 * </tr>
857 * <tr>
858 * <td align="center">any state</td>
859 * <td align="center">AUTO--&gt;CAF mode switch</td>
860 * <td align="center">passively reachable states from INACTIVE</td>
861 * <td align="center">Mode switch without trigger, passive transient state is skipped</td>
862 * </tr>
863 * </tbody>
864 * </table>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]865 *
866 * @see CaptureRequest#CONTROL_AF_MODE
867 * @see CaptureRequest#CONTROL_MODE
868 * @see CaptureRequest#CONTROL_SCENE_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]869 * @see #CONTROL_AF_STATE_INACTIVE
870 * @see #CONTROL_AF_STATE_PASSIVE_SCAN
871 * @see #CONTROL_AF_STATE_PASSIVE_FOCUSED
872 * @see #CONTROL_AF_STATE_ACTIVE_SCAN
873 * @see #CONTROL_AF_STATE_FOCUSED_LOCKED
874 * @see #CONTROL_AF_STATE_NOT_FOCUSED_LOCKED
Eino-Ville Talvala9f880f72013-09-20 17:50:41 -0700[diff] [blame]875 * @see #CONTROL_AF_STATE_PASSIVE_UNFOCUSED
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]876 */
877 public static final Key<Integer> CONTROL_AF_STATE =
878 new Key<Integer>("android.control.afState", int.class);
879
880 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]881 * <p>The ID sent with the latest
882 * CAMERA2_TRIGGER_AUTOFOCUS call</p>
883 * <p>Must be 0 if no CAMERA2_TRIGGER_AUTOFOCUS trigger
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]884 * received yet by HAL. Always updated even if AF algorithm
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]885 * ignores the trigger</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]886 * @hide
887 */
888 public static final Key<Integer> CONTROL_AF_TRIGGER_ID =
889 new Key<Integer>("android.control.afTriggerId", int.class);
890
891 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]892 * <p>Whether AWB is currently setting the color
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]893 * transform fields, and what its illumination target
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]894 * is.</p>
Zhijun He399f05d2014-01-15 11:31:30 -0800[diff] [blame]895 * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
896 * <p>When set to the ON mode, the camera device's auto white balance
897 * routine is enabled, overriding the application's selected
898 * {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} and
899 * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
900 * <p>When set to the OFF mode, the camera device's auto white balance
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]901 * routine is disabled. The application manually controls the white
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]902 * balance by {@link CaptureRequest#COLOR_CORRECTION_TRANSFORM android.colorCorrection.transform}, {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains}
Zhijun He399f05d2014-01-15 11:31:30 -0800[diff] [blame]903 * and {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode}.</p>
904 * <p>When set to any other modes, the camera device's auto white balance
905 * routine is disabled. The camera device uses each particular illumination
906 * target for white balance adjustment.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]907 *
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]908 * @see CaptureRequest#COLOR_CORRECTION_GAINS
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]909 * @see CaptureRequest#COLOR_CORRECTION_MODE
910 * @see CaptureRequest#COLOR_CORRECTION_TRANSFORM
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]911 * @see CaptureRequest#CONTROL_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]912 * @see #CONTROL_AWB_MODE_OFF
913 * @see #CONTROL_AWB_MODE_AUTO
914 * @see #CONTROL_AWB_MODE_INCANDESCENT
915 * @see #CONTROL_AWB_MODE_FLUORESCENT
916 * @see #CONTROL_AWB_MODE_WARM_FLUORESCENT
917 * @see #CONTROL_AWB_MODE_DAYLIGHT
918 * @see #CONTROL_AWB_MODE_CLOUDY_DAYLIGHT
919 * @see #CONTROL_AWB_MODE_TWILIGHT
920 * @see #CONTROL_AWB_MODE_SHADE
921 */
922 public static final Key<Integer> CONTROL_AWB_MODE =
923 new Key<Integer>("android.control.awbMode", int.class);
924
925 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]926 * <p>List of areas to use for illuminant
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]927 * estimation.</p>
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]928 * <p>Only used in AUTO mode.</p>
929 * <p>Each area is a rectangle plus weight: xmin, ymin,
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]930 * xmax, ymax, weight. The rectangle is defined to be inclusive of the
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]931 * specified coordinates.</p>
932 * <p>The coordinate system is based on the active pixel array,
Timothy Knight2629f272013-09-03 17:23:23 -0700[diff] [blame]933 * with (0,0) being the top-left pixel in the active pixel array, and
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]934 * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1,
935 * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the
Timothy Knight2629f272013-09-03 17:23:23 -0700[diff] [blame]936 * bottom-right pixel in the active pixel array. The weight
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]937 * should be nonnegative.</p>
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]938 * <p>If all regions have 0 weight, then no specific auto-white balance (AWB) area
939 * needs to be used by the camera device. If the AWB region is
940 * outside the current {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}, the camera device
941 * will ignore the sections outside the region and output the
Ruben Brunkf59521d2014-02-03 17:14:33 -0800[diff] [blame]942 * used sections in the frame metadata.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]943 *
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]944 * @see CaptureRequest#SCALER_CROP_REGION
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]945 * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]946 */
947 public static final Key<int[]> CONTROL_AWB_REGIONS =
948 new Key<int[]>("android.control.awbRegions", int[].class);
949
950 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]951 * <p>Current state of AWB algorithm</p>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]952 * <p>Switching between or enabling AWB modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}) always
953 * resets the AWB state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
954 * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
955 * the algorithm states to INACTIVE.</p>
956 * <p>The camera device can do several state transitions between two results, if it is
957 * allowed by the state transition table. So INACTIVE may never actually be seen in
958 * a result.</p>
959 * <p>The state in the result is the state for this image (in sync with this image): if
960 * AWB state becomes CONVERGED, then the image data associated with this result should
961 * be good to use.</p>
962 * <p>Below are state transition tables for different AWB modes.</p>
963 * <p>When <code>{@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} != AWB_MODE_AUTO</code>:</p>
964 * <table>
965 * <thead>
966 * <tr>
967 * <th align="center">State</th>
968 * <th align="center">Transition Cause</th>
969 * <th align="center">New State</th>
970 * <th align="center">Notes</th>
971 * </tr>
972 * </thead>
973 * <tbody>
974 * <tr>
975 * <td align="center">INACTIVE</td>
976 * <td align="center"></td>
977 * <td align="center">INACTIVE</td>
978 * <td align="center">Camera device auto white balance algorithm is disabled</td>
979 * </tr>
980 * </tbody>
981 * </table>
982 * <p>When {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} is AWB_MODE_AUTO:</p>
983 * <table>
984 * <thead>
985 * <tr>
986 * <th align="center">State</th>
987 * <th align="center">Transition Cause</th>
988 * <th align="center">New State</th>
989 * <th align="center">Notes</th>
990 * </tr>
991 * </thead>
992 * <tbody>
993 * <tr>
994 * <td align="center">INACTIVE</td>
995 * <td align="center">Camera device initiates AWB scan</td>
996 * <td align="center">SEARCHING</td>
997 * <td align="center">Values changing</td>
998 * </tr>
999 * <tr>
1000 * <td align="center">INACTIVE</td>
1001 * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON</td>
1002 * <td align="center">LOCKED</td>
1003 * <td align="center">Values locked</td>
1004 * </tr>
1005 * <tr>
1006 * <td align="center">SEARCHING</td>
1007 * <td align="center">Camera device finishes AWB scan</td>
1008 * <td align="center">CONVERGED</td>
1009 * <td align="center">Good values, not changing</td>
1010 * </tr>
1011 * <tr>
1012 * <td align="center">SEARCHING</td>
1013 * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON</td>
1014 * <td align="center">LOCKED</td>
1015 * <td align="center">Values locked</td>
1016 * </tr>
1017 * <tr>
1018 * <td align="center">CONVERGED</td>
1019 * <td align="center">Camera device initiates AWB scan</td>
1020 * <td align="center">SEARCHING</td>
1021 * <td align="center">Values changing</td>
1022 * </tr>
1023 * <tr>
1024 * <td align="center">CONVERGED</td>
1025 * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is ON</td>
1026 * <td align="center">LOCKED</td>
1027 * <td align="center">Values locked</td>
1028 * </tr>
1029 * <tr>
1030 * <td align="center">LOCKED</td>
1031 * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFF</td>
1032 * <td align="center">SEARCHING</td>
1033 * <td align="center">Values not good after unlock</td>
1034 * </tr>
Zhijun He60b19dc2014-02-24 10:19:20 -0800[diff] [blame]1035 * </tbody>
1036 * </table>
1037 * <p>For the above table, the camera device may skip reporting any state changes that happen
1038 * without application intervention (i.e. mode switch, trigger, locking). Any state that
1039 * can be skipped in that manner is called a transient state.</p>
1040 * <p>For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions
1041 * listed in above table, it is also legal for the camera device to skip one or more
1042 * transient states between two results. See below table for examples:</p>
1043 * <table>
1044 * <thead>
1045 * <tr>
1046 * <th align="center">State</th>
1047 * <th align="center">Transition Cause</th>
1048 * <th align="center">New State</th>
1049 * <th align="center">Notes</th>
1050 * </tr>
1051 * </thead>
1052 * <tbody>
1053 * <tr>
1054 * <td align="center">INACTIVE</td>
1055 * <td align="center">Camera device finished AWB scan</td>
1056 * <td align="center">CONVERGED</td>
1057 * <td align="center">Values are already good, transient states are skipped by camera device.</td>
1058 * </tr>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]1059 * <tr>
1060 * <td align="center">LOCKED</td>
1061 * <td align="center">{@link CaptureRequest#CONTROL_AWB_LOCK android.control.awbLock} is OFF</td>
1062 * <td align="center">CONVERGED</td>
Zhijun He60b19dc2014-02-24 10:19:20 -0800[diff] [blame]1063 * <td align="center">Values good after unlock, transient states are skipped by camera device.</td>
Zhijun He228f4f92014-01-16 17:22:05 -0800[diff] [blame]1064 * </tr>
1065 * </tbody>
1066 * </table>
1067 *
1068 * @see CaptureRequest#CONTROL_AWB_LOCK
1069 * @see CaptureRequest#CONTROL_AWB_MODE
1070 * @see CaptureRequest#CONTROL_MODE
1071 * @see CaptureRequest#CONTROL_SCENE_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1072 * @see #CONTROL_AWB_STATE_INACTIVE
1073 * @see #CONTROL_AWB_STATE_SEARCHING
1074 * @see #CONTROL_AWB_STATE_CONVERGED
1075 * @see #CONTROL_AWB_STATE_LOCKED
1076 */
1077 public static final Key<Integer> CONTROL_AWB_STATE =
1078 new Key<Integer>("android.control.awbState", int.class);
1079
1080 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1081 * <p>Overall mode of 3A control
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1082 * routines.</p>
Zhijun Hef3537422013-12-16 16:56:35 -0800[diff] [blame]1083 * <p>High-level 3A control. When set to OFF, all 3A control
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1084 * by the camera device is disabled. The application must set the fields for
Zhijun Hef3537422013-12-16 16:56:35 -0800[diff] [blame]1085 * capture parameters itself.</p>
1086 * <p>When set to AUTO, the individual algorithm controls in
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1087 * android.control.* are in effect, such as {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p>
Zhijun Hef3537422013-12-16 16:56:35 -0800[diff] [blame]1088 * <p>When set to USE_SCENE_MODE, the individual controls in
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1089 * android.control.* are mostly disabled, and the camera device implements
Zhijun Hef3537422013-12-16 16:56:35 -0800[diff] [blame]1090 * one of the scene mode settings (such as ACTION, SUNSET, or PARTY)
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1091 * as it wishes. The camera device scene mode 3A settings are provided by
Zhijun Hef3537422013-12-16 16:56:35 -0800[diff] [blame]1092 * android.control.sceneModeOverrides.</p>
Zhijun He2d5e8972014-02-07 16:13:46 -0800[diff] [blame]1093 * <p>When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference
1094 * is that this frame will not be used by camera device background 3A statistics
1095 * update, as if this frame is never captured. This mode can be used in the scenario
1096 * where the application doesn't want a 3A manual control capture to affect
1097 * the subsequent auto 3A capture results.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1098 *
1099 * @see CaptureRequest#CONTROL_AF_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1100 * @see #CONTROL_MODE_OFF
1101 * @see #CONTROL_MODE_AUTO
1102 * @see #CONTROL_MODE_USE_SCENE_MODE
Zhijun He2d5e8972014-02-07 16:13:46 -0800[diff] [blame]1103 * @see #CONTROL_MODE_OFF_KEEP_STATE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1104 */
1105 public static final Key<Integer> CONTROL_MODE =
1106 new Key<Integer>("android.control.mode", int.class);
1107
1108 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1109 * <p>Operation mode for edge
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1110 * enhancement.</p>
Zhijun He28079362013-12-17 10:35:40 -0800[diff] [blame]1111 * <p>Edge/sharpness/detail enhancement. OFF means no
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1112 * enhancement will be applied by the camera device.</p>
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1113 * <p>FAST/HIGH_QUALITY both mean camera device determined enhancement
Zhijun He28079362013-12-17 10:35:40 -0800[diff] [blame]1114 * will be applied. HIGH_QUALITY mode indicates that the
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1115 * camera device will use the highest-quality enhancement algorithms,
1116 * even if it slows down capture rate. FAST means the camera device will
Zhijun He28079362013-12-17 10:35:40 -0800[diff] [blame]1117 * not slow down capture rate when applying edge enhancement.</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1118 * @see #EDGE_MODE_OFF
1119 * @see #EDGE_MODE_FAST
1120 * @see #EDGE_MODE_HIGH_QUALITY
1121 */
1122 public static final Key<Integer> EDGE_MODE =
1123 new Key<Integer>("android.edge.mode", int.class);
1124
1125 /**
Zhijun He66d065a2014-01-16 18:18:50 -0800[diff] [blame]1126 * <p>The desired mode for for the camera device's flash control.</p>
1127 * <p>This control is only effective when flash unit is available
Zhijun He153ac102014-02-03 12:25:12 -0800[diff] [blame]1128 * (<code>{@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == true</code>).</p>
Zhijun He66d065a2014-01-16 18:18:50 -0800[diff] [blame]1129 * <p>When this control is used, the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} must be set to ON or OFF.
1130 * Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH,
1131 * ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control.</p>
1132 * <p>When set to OFF, the camera device will not fire flash for this capture.</p>
1133 * <p>When set to SINGLE, the camera device will fire flash regardless of the camera
1134 * device's auto-exposure routine's result. When used in still capture case, this
1135 * control should be used along with AE precapture metering sequence
1136 * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p>
1137 * <p>When set to TORCH, the flash will be on continuously. This mode can be used
1138 * for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1139 * <p>The flash status will be reported by {@link CaptureResult#FLASH_STATE android.flash.state} in the capture result metadata.</p>
Zhijun He66d065a2014-01-16 18:18:50 -0800[diff] [blame]1140 *
1141 * @see CaptureRequest#CONTROL_AE_MODE
1142 * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
1143 * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1144 * @see CaptureResult#FLASH_STATE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1145 * @see #FLASH_MODE_OFF
1146 * @see #FLASH_MODE_SINGLE
1147 * @see #FLASH_MODE_TORCH
1148 */
1149 public static final Key<Integer> FLASH_MODE =
1150 new Key<Integer>("android.flash.mode", int.class);
1151
1152 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1153 * <p>Current state of the flash
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1154 * unit.</p>
1155 * <p>When the camera device doesn't have flash unit
1156 * (i.e. <code>{@link CameraCharacteristics#FLASH_INFO_AVAILABLE android.flash.info.available} == false</code>), this state will always be UNAVAILABLE.
1157 * Other states indicate the current flash status.</p>
1158 *
1159 * @see CameraCharacteristics#FLASH_INFO_AVAILABLE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1160 * @see #FLASH_STATE_UNAVAILABLE
1161 * @see #FLASH_STATE_CHARGING
1162 * @see #FLASH_STATE_READY
1163 * @see #FLASH_STATE_FIRED
1164 */
1165 public static final Key<Integer> FLASH_STATE =
1166 new Key<Integer>("android.flash.state", int.class);
1167
1168 /**
Ruben Brunkeba1b3a2014-02-07 18:23:50 -0800[diff] [blame]1169 * <p>Set operational mode for hot pixel correction.</p>
Ruben Brunk9d454fd2014-03-04 14:11:52 -0800[diff] [blame^]1170 * <p>Valid modes for this camera device are listed in
1171 * {@link CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES android.hotPixel.availableHotPixelModes}.</p>
Ruben Brunkeba1b3a2014-02-07 18:23:50 -0800[diff] [blame]1172 * <p>Hotpixel correction interpolates out, or otherwise removes, pixels
1173 * that do not accurately encode the incoming light (i.e. pixels that
1174 * are stuck at an arbitrary value).</p>
Ruben Brunk9d454fd2014-03-04 14:11:52 -0800[diff] [blame^]1175 *
1176 * @see CameraCharacteristics#HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES
Ruben Brunkeba1b3a2014-02-07 18:23:50 -0800[diff] [blame]1177 * @see #HOT_PIXEL_MODE_OFF
1178 * @see #HOT_PIXEL_MODE_FAST
1179 * @see #HOT_PIXEL_MODE_HIGH_QUALITY
1180 */
1181 public static final Key<Integer> HOT_PIXEL_MODE =
1182 new Key<Integer>("android.hotPixel.mode", int.class);
1183
1184 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1185 * <p>GPS coordinates to include in output JPEG
1186 * EXIF</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1187 */
1188 public static final Key<double[]> JPEG_GPS_COORDINATES =
1189 new Key<double[]>("android.jpeg.gpsCoordinates", double[].class);
1190
1191 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1192 * <p>32 characters describing GPS algorithm to
1193 * include in EXIF</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1194 */
1195 public static final Key<String> JPEG_GPS_PROCESSING_METHOD =
1196 new Key<String>("android.jpeg.gpsProcessingMethod", String.class);
1197
1198 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1199 * <p>Time GPS fix was made to include in
1200 * EXIF</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1201 */
1202 public static final Key<Long> JPEG_GPS_TIMESTAMP =
1203 new Key<Long>("android.jpeg.gpsTimestamp", long.class);
1204
1205 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1206 * <p>Orientation of JPEG image to
1207 * write</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1208 */
1209 public static final Key<Integer> JPEG_ORIENTATION =
1210 new Key<Integer>("android.jpeg.orientation", int.class);
1211
1212 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1213 * <p>Compression quality of the final JPEG
1214 * image</p>
1215 * <p>85-95 is typical usage range</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1216 */
1217 public static final Key<Byte> JPEG_QUALITY =
1218 new Key<Byte>("android.jpeg.quality", byte.class);
1219
1220 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1221 * <p>Compression quality of JPEG
1222 * thumbnail</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1223 */
1224 public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
1225 new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
1226
1227 /**
Zhijun He5a9ff372013-12-26 11:49:09 -0800[diff] [blame]1228 * <p>Resolution of embedded JPEG thumbnail</p>
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1229 * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
1230 * but the captured JPEG will still be a valid image.</p>
Zhijun He5a9ff372013-12-26 11:49:09 -0800[diff] [blame]1231 * <p>When a jpeg image capture is issued, the thumbnail size selected should have
1232 * the same aspect ratio as the jpeg image.</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1233 */
1234 public static final Key<android.hardware.camera2.Size> JPEG_THUMBNAIL_SIZE =
1235 new Key<android.hardware.camera2.Size>("android.jpeg.thumbnailSize", android.hardware.camera2.Size.class);
1236
1237 /**
Zhijun Hefb46c642014-01-14 17:57:23 -0800[diff] [blame]1238 * <p>The ratio of lens focal length to the effective
1239 * aperture diameter.</p>
1240 * <p>This will only be supported on the camera devices that
1241 * have variable aperture lens. The aperture value can only be
1242 * one of the values listed in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures}.</p>
1243 * <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is OFF,
1244 * this can be set along with {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime},
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]1245 * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}, and {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration}
Zhijun Hefb46c642014-01-14 17:57:23 -0800[diff] [blame]1246 * to achieve manual exposure control.</p>
1247 * <p>The requested aperture value may take several frames to reach the
1248 * requested value; the camera device will report the current (intermediate)
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1249 * aperture size in capture result metadata while the aperture is changing.
1250 * While the aperture is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
Zhijun Hefb46c642014-01-14 17:57:23 -0800[diff] [blame]1251 * <p>When this is supported and {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is one of
1252 * the ON modes, this will be overridden by the camera device
1253 * auto-exposure algorithm, the overridden values are then provided
1254 * back to the user in the corresponding result.</p>
1255 *
Zhijun He399f05d2014-01-15 11:31:30 -0800[diff] [blame]1256 * @see CaptureRequest#CONTROL_AE_MODE
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]1257 * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1258 * @see CaptureResult#LENS_STATE
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]1259 * @see CaptureRequest#SENSOR_EXPOSURE_TIME
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]1260 * @see CaptureRequest#SENSOR_FRAME_DURATION
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]1261 * @see CaptureRequest#SENSOR_SENSITIVITY
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1262 */
1263 public static final Key<Float> LENS_APERTURE =
1264 new Key<Float>("android.lens.aperture", float.class);
1265
1266 /**
Ruben Brunk855bae42014-01-17 10:30:32 -0800[diff] [blame]1267 * <p>State of lens neutral density filter(s).</p>
1268 * <p>This will not be supported on most camera devices. On devices
1269 * where this is supported, this may only be set to one of the
1270 * values included in {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities}.</p>
1271 * <p>Lens filters are typically used to lower the amount of light the
1272 * sensor is exposed to (measured in steps of EV). As used here, an EV
1273 * step is the standard logarithmic representation, which are
1274 * non-negative, and inversely proportional to the amount of light
1275 * hitting the sensor. For example, setting this to 0 would result
1276 * in no reduction of the incoming light, and setting this to 2 would
1277 * mean that the filter is set to reduce incoming light by two stops
1278 * (allowing 1/4 of the prior amount of light to the sensor).</p>
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1279 * <p>It may take several frames before the lens filter density changes
1280 * to the requested value. While the filter density is still changing,
1281 * {@link CaptureResult#LENS_STATE android.lens.state} will be set to MOVING.</p>
Ruben Brunk855bae42014-01-17 10:30:32 -0800[diff] [blame]1282 *
1283 * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1284 * @see CaptureResult#LENS_STATE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1285 */
1286 public static final Key<Float> LENS_FILTER_DENSITY =
1287 new Key<Float>("android.lens.filterDensity", float.class);
1288
1289 /**
Ruben Brunka20f4c22014-01-17 15:21:13 -0800[diff] [blame]1290 * <p>The current lens focal length; used for optical zoom.</p>
1291 * <p>This setting controls the physical focal length of the camera
1292 * device's lens. Changing the focal length changes the field of
1293 * view of the camera device, and is usually used for optical zoom.</p>
1294 * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this
1295 * setting won't be applied instantaneously, and it may take several
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1296 * frames before the lens can change to the requested focal length.
Ruben Brunka20f4c22014-01-17 15:21:13 -0800[diff] [blame]1297 * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
1298 * be set to MOVING.</p>
1299 * <p>This is expected not to be supported on most devices.</p>
1300 *
1301 * @see CaptureRequest#LENS_APERTURE
1302 * @see CaptureRequest#LENS_FOCUS_DISTANCE
1303 * @see CaptureResult#LENS_STATE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1304 */
1305 public static final Key<Float> LENS_FOCAL_LENGTH =
1306 new Key<Float>("android.lens.focalLength", float.class);
1307
1308 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1309 * <p>Distance to plane of sharpest focus,
1310 * measured from frontmost surface of the lens</p>
1311 * <p>Should be zero for fixed-focus cameras</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1312 */
1313 public static final Key<Float> LENS_FOCUS_DISTANCE =
1314 new Key<Float>("android.lens.focusDistance", float.class);
1315
1316 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1317 * <p>The range of scene distances that are in
1318 * sharp focus (depth of field)</p>
1319 * <p>If variable focus not supported, can still report
1320 * fixed depth of field range</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1321 */
Zhijun Hec59b0782013-09-26 10:39:36 -0700[diff] [blame]1322 public static final Key<float[]> LENS_FOCUS_RANGE =
1323 new Key<float[]>("android.lens.focusRange", float[].class);
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1324
1325 /**
Ruben Brunk00849b32014-01-17 18:30:23 -0800[diff] [blame]1326 * <p>Sets whether the camera device uses optical image stabilization (OIS)
1327 * when capturing images.</p>
1328 * <p>OIS is used to compensate for motion blur due to small movements of
1329 * the camera during capture. Unlike digital image stabilization, OIS makes
1330 * use of mechanical elements to stabilize the camera sensor, and thus
1331 * allows for longer exposure times before camera shake becomes
1332 * apparent.</p>
1333 * <p>This is not expected to be supported on most devices.</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1334 * @see #LENS_OPTICAL_STABILIZATION_MODE_OFF
1335 * @see #LENS_OPTICAL_STABILIZATION_MODE_ON
1336 */
1337 public static final Key<Integer> LENS_OPTICAL_STABILIZATION_MODE =
1338 new Key<Integer>("android.lens.opticalStabilizationMode", int.class);
1339
1340 /**
Zhijun Heca1b73a2014-02-03 12:39:53 -0800[diff] [blame]1341 * <p>Current lens status.</p>
1342 * <p>For lens parameters {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance},
1343 * {@link CaptureRequest#LENS_FILTER_DENSITY android.lens.filterDensity} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, when changes are requested,
1344 * they may take several frames to reach the requested values. This state indicates
1345 * the current status of the lens parameters.</p>
1346 * <p>When the state is STATIONARY, the lens parameters are not changing. This could be
1347 * either because the parameters are all fixed, or because the lens has had enough
1348 * time to reach the most recently-requested values.
1349 * If all these lens parameters are not changable for a camera device, as listed below:</p>
1350 * <ul>
1351 * <li>Fixed focus (<code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} == 0</code>), which means
1352 * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} parameter will always be 0.</li>
1353 * <li>Fixed focal length ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths} contains single value),
1354 * which means the optical zoom is not supported.</li>
1355 * <li>No ND filter ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities} contains only 0).</li>
1356 * <li>Fixed aperture ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures} contains single value).</li>
1357 * </ul>
1358 * <p>Then this state will always be STATIONARY.</p>
1359 * <p>When the state is MOVING, it indicates that at least one of the lens parameters
1360 * is changing.</p>
1361 *
1362 * @see CaptureRequest#LENS_APERTURE
1363 * @see CaptureRequest#LENS_FILTER_DENSITY
1364 * @see CaptureRequest#LENS_FOCAL_LENGTH
1365 * @see CaptureRequest#LENS_FOCUS_DISTANCE
1366 * @see CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES
1367 * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES
1368 * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS
1369 * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1370 * @see #LENS_STATE_STATIONARY
Igor Murashkin9ea4ae62013-09-11 21:40:11 -0700[diff] [blame]1371 * @see #LENS_STATE_MOVING
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1372 */
1373 public static final Key<Integer> LENS_STATE =
1374 new Key<Integer>("android.lens.state", int.class);
1375
1376 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1377 * <p>Mode of operation for the noise reduction
1378 * algorithm</p>
Zhijun He28079362013-12-17 10:35:40 -0800[diff] [blame]1379 * <p>Noise filtering control. OFF means no noise reduction
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1380 * will be applied by the camera device.</p>
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1381 * <p>FAST/HIGH_QUALITY both mean camera device determined noise filtering
1382 * will be applied. HIGH_QUALITY mode indicates that the camera device
1383 * will use the highest-quality noise filtering algorithms,
1384 * even if it slows down capture rate. FAST means the camera device should not
Zhijun He28079362013-12-17 10:35:40 -0800[diff] [blame]1385 * slow down capture rate when applying noise filtering.</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1386 * @see #NOISE_REDUCTION_MODE_OFF
1387 * @see #NOISE_REDUCTION_MODE_FAST
1388 * @see #NOISE_REDUCTION_MODE_HIGH_QUALITY
1389 */
1390 public static final Key<Integer> NOISE_REDUCTION_MODE =
1391 new Key<Integer>("android.noiseReduction.mode", int.class);
1392
1393 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1394 * <p>Whether a result given to the framework is the
Eino-Ville Talvala7a313102013-11-07 14:45:06 -0800[diff] [blame]1395 * final one for the capture, or only a partial that contains a
1396 * subset of the full set of dynamic metadata
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1397 * values.</p>
1398 * <p>The entries in the result metadata buffers for a
Eino-Ville Talvala7a313102013-11-07 14:45:06 -0800[diff] [blame]1399 * single capture may not overlap, except for this entry. The
1400 * FINAL buffers must retain FIFO ordering relative to the
1401 * requests that generate them, so the FINAL buffer for frame 3 must
1402 * always be sent to the framework after the FINAL buffer for frame 2, and
1403 * before the FINAL buffer for frame 4. PARTIAL buffers may be returned
1404 * in any order relative to other frames, but all PARTIAL buffers for a given
1405 * capture must arrive before the FINAL buffer for that capture. This entry may
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1406 * only be used by the camera device if quirks.usePartialResult is set to 1.</p>
Igor Murashkin3242f4f2014-01-15 12:27:41 -0800[diff] [blame]1407 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
Eino-Ville Talvala7a313102013-11-07 14:45:06 -0800[diff] [blame]1408 * @hide
1409 */
1410 public static final Key<Boolean> QUIRKS_PARTIAL_RESULT =
1411 new Key<Boolean>("android.quirks.partialResult", boolean.class);
1412
1413 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1414 * <p>A frame counter set by the framework. This value monotonically
Igor Murashkin6bbf9dc2013-09-05 12:22:00 -0700[diff] [blame]1415 * increases with every new result (that is, each new result has a unique
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1416 * frameCount value).</p>
1417 * <p>Reset on release()</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1418 */
1419 public static final Key<Integer> REQUEST_FRAME_COUNT =
1420 new Key<Integer>("android.request.frameCount", int.class);
1421
1422 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1423 * <p>An application-specified ID for the current
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1424 * request. Must be maintained unchanged in output
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1425 * frame</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1426 * @hide
1427 */
1428 public static final Key<Integer> REQUEST_ID =
1429 new Key<Integer>("android.request.id", int.class);
1430
1431 /**
Igor Murashkinc127f052014-01-17 18:06:02 -0800[diff] [blame]1432 * <p>Specifies the number of pipeline stages the frame went
1433 * through from when it was exposed to when the final completed result
1434 * was available to the framework.</p>
1435 * <p>Depending on what settings are used in the request, and
1436 * what streams are configured, the data may undergo less processing,
1437 * and some pipeline stages skipped.</p>
1438 * <p>See {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} for more details.</p>
1439 *
1440 * @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH
1441 */
1442 public static final Key<Byte> REQUEST_PIPELINE_DEPTH =
1443 new Key<Byte>("android.request.pipelineDepth", byte.class);
1444
1445 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1446 * <p>(x, y, width, height).</p>
1447 * <p>A rectangle with the top-level corner of (x,y) and size
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1448 * (width, height). The region of the sensor that is used for
1449 * output. Each stream must use this rectangle to produce its
1450 * output, cropping to a smaller region if necessary to
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1451 * maintain the stream's aspect ratio.</p>
1452 * <p>HAL2.x uses only (x, y, width)</p>
1453 * <p>Any additional per-stream cropping must be done to
1454 * maximize the final pixel area of the stream.</p>
1455 * <p>For example, if the crop region is set to a 4:3 aspect
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1456 * ratio, then 4:3 streams should use the exact crop
1457 * region. 16:9 streams should further crop vertically
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1458 * (letterbox).</p>
1459 * <p>Conversely, if the crop region is set to a 16:9, then 4:3
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1460 * outputs should crop horizontally (pillarbox), and 16:9
1461 * streams should match exactly. These additional crops must
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1462 * be centered within the crop region.</p>
1463 * <p>The output streams must maintain square pixels at all
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1464 * times, no matter what the relative aspect ratios of the
1465 * crop region and the stream are. Negative values for
1466 * corner are allowed for raw output if full pixel array is
1467 * larger than active pixel array. Width and height may be
1468 * rounded to nearest larger supportable width, especially
1469 * for raw output, where only a few fixed scales may be
1470 * possible. The width and height of the crop region cannot
1471 * be set to be smaller than floor( activeArraySize.width /
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]1472 * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor(
1473 * activeArraySize.height /
1474 * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p>
1475 *
1476 * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1477 */
1478 public static final Key<android.graphics.Rect> SCALER_CROP_REGION =
1479 new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class);
1480
1481 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1482 * <p>Duration each pixel is exposed to
1483 * light.</p>
1484 * <p>If the sensor can't expose this exact duration, it should shorten the
1485 * duration exposed to the nearest possible value (rather than expose longer).</p>
1486 * <p>1/10000 - 30 sec range. No bulb mode</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1487 */
1488 public static final Key<Long> SENSOR_EXPOSURE_TIME =
1489 new Key<Long>("android.sensor.exposureTime", long.class);
1490
1491 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1492 * <p>Duration from start of frame exposure to
Igor Murashkin143aa0b2014-01-17 15:02:34 -0800[diff] [blame]1493 * start of next frame exposure.</p>
1494 * <p>The maximum frame rate that can be supported by a camera subsystem is
1495 * a function of many factors:</p>
1496 * <ul>
1497 * <li>Requested resolutions of output image streams</li>
1498 * <li>Availability of binning / skipping modes on the imager</li>
1499 * <li>The bandwidth of the imager interface</li>
1500 * <li>The bandwidth of the various ISP processing blocks</li>
1501 * </ul>
1502 * <p>Since these factors can vary greatly between different ISPs and
1503 * sensors, the camera abstraction tries to represent the bandwidth
1504 * restrictions with as simple a model as possible.</p>
1505 * <p>The model presented has the following characteristics:</p>
1506 * <ul>
1507 * <li>The image sensor is always configured to output the smallest
1508 * resolution possible given the application's requested output stream
1509 * sizes. The smallest resolution is defined as being at least as large
1510 * as the largest requested output stream size; the camera pipeline must
1511 * never digitally upsample sensor data when the crop region covers the
1512 * whole sensor. In general, this means that if only small output stream
1513 * resolutions are configured, the sensor can provide a higher frame
1514 * rate.</li>
1515 * <li>Since any request may use any or all the currently configured
1516 * output streams, the sensor and ISP must be configured to support
1517 * scaling a single capture to all the streams at the same time. This
1518 * means the camera pipeline must be ready to produce the largest
1519 * requested output size without any delay. Therefore, the overall
1520 * frame rate of a given configured stream set is governed only by the
1521 * largest requested stream resolution.</li>
1522 * <li>Using more than one output stream in a request does not affect the
1523 * frame duration.</li>
Igor Murashkina23ffb52014-02-07 18:52:34 -0800[diff] [blame]1524 * <li>Certain format-streams may need to do additional background processing
1525 * before data is consumed/produced by that stream. These processors
1526 * can run concurrently to the rest of the camera pipeline, but
1527 * cannot process more than 1 capture at a time.</li>
Igor Murashkin143aa0b2014-01-17 15:02:34 -0800[diff] [blame]1528 * </ul>
1529 * <p>The necessary information for the application, given the model above,
Igor Murashkina23ffb52014-02-07 18:52:34 -0800[diff] [blame]1530 * is provided via the {@link CameraCharacteristics#SCALER_AVAILABLE_MIN_FRAME_DURATIONS android.scaler.availableMinFrameDurations} field.
Igor Murashkin143aa0b2014-01-17 15:02:34 -0800[diff] [blame]1531 * These are used to determine the maximum frame rate / minimum frame
1532 * duration that is possible for a given stream configuration.</p>
1533 * <p>Specifically, the application can use the following rules to
Igor Murashkina23ffb52014-02-07 18:52:34 -0800[diff] [blame]1534 * determine the minimum frame duration it can request from the camera
Igor Murashkin143aa0b2014-01-17 15:02:34 -0800[diff] [blame]1535 * device:</p>
1536 * <ol>
Igor Murashkina23ffb52014-02-07 18:52:34 -0800[diff] [blame]1537 * <li>Let the set of currently configured input/output streams
1538 * be called <code>S</code>.</li>
1539 * <li>Find the minimum frame durations for each stream in <code>S</code>, by
1540 * looking it up in {@link CameraCharacteristics#SCALER_AVAILABLE_MIN_FRAME_DURATIONS android.scaler.availableMinFrameDurations} (with
1541 * its respective size/format). Let this set of frame durations be called
1542 * <code>F</code>.</li>
1543 * <li>For any given request <code>R</code>, the minimum frame duration allowed
1544 * for <code>R</code> is the maximum out of all values in <code>F</code>. Let the streams
1545 * used in <code>R</code> be called <code>S_r</code>.</li>
Igor Murashkin143aa0b2014-01-17 15:02:34 -0800[diff] [blame]1546 * </ol>
Igor Murashkina23ffb52014-02-07 18:52:34 -0800[diff] [blame]1547 * <p>If none of the streams in <code>S_r</code> have a stall time (listed in
1548 * {@link CameraCharacteristics#SCALER_AVAILABLE_STALL_DURATIONS android.scaler.availableStallDurations}), then the frame duration in
1549 * <code>F</code> determines the steady state frame rate that the application will
1550 * get if it uses <code>R</code> as a repeating request. Let this special kind
1551 * of request be called <code>Rsimple</code>.</p>
1552 * <p>A repeating request <code>Rsimple</code> can be <em>occasionally</em> interleaved
1553 * by a single capture of a new request <code>Rstall</code> (which has at least
1554 * one in-use stream with a non-0 stall time) and if <code>Rstall</code> has the
1555 * same minimum frame duration this will not cause a frame rate loss
1556 * if all buffers from the previous <code>Rstall</code> have already been
1557 * delivered.</p>
1558 * <p>For more details about stalling, see
1559 * {@link CameraCharacteristics#SCALER_AVAILABLE_STALL_DURATIONS android.scaler.availableStallDurations}.</p>
Igor Murashkin143aa0b2014-01-17 15:02:34 -0800[diff] [blame]1560 *
Igor Murashkina23ffb52014-02-07 18:52:34 -0800[diff] [blame]1561 * @see CameraCharacteristics#SCALER_AVAILABLE_MIN_FRAME_DURATIONS
1562 * @see CameraCharacteristics#SCALER_AVAILABLE_STALL_DURATIONS
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1563 */
1564 public static final Key<Long> SENSOR_FRAME_DURATION =
1565 new Key<Long>("android.sensor.frameDuration", long.class);
1566
1567 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1568 * <p>Gain applied to image data. Must be
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1569 * implemented through analog gain only if set to values
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1570 * below 'maximum analog sensitivity'.</p>
1571 * <p>If the sensor can't apply this exact gain, it should lessen the
1572 * gain to the nearest possible value (rather than gain more).</p>
1573 * <p>ISO 12232:2006 REI method</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1574 */
1575 public static final Key<Integer> SENSOR_SENSITIVITY =
1576 new Key<Integer>("android.sensor.sensitivity", int.class);
1577
1578 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1579 * <p>Time at start of exposure of first
1580 * row</p>
1581 * <p>Monotonic, should be synced to other timestamps in
1582 * system</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1583 */
1584 public static final Key<Long> SENSOR_TIMESTAMP =
1585 new Key<Long>("android.sensor.timestamp", long.class);
1586
1587 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1588 * <p>The temperature of the sensor, sampled at the time
1589 * exposure began for this frame.</p>
1590 * <p>The thermal diode being queried should be inside the sensor PCB, or
1591 * somewhere close to it.</p>
Igor Murashkin3242f4f2014-01-15 12:27:41 -0800[diff] [blame]1592 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1593 * <p><b>Full capability</b> -
1594 * Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the
1595 * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL android.info.supportedHardwareLevel} key</p>
1596 *
1597 * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
Igor Murashkind5ff06a2013-08-20 15:15:06 -0700[diff] [blame]1598 */
1599 public static final Key<Float> SENSOR_TEMPERATURE =
1600 new Key<Float>("android.sensor.temperature", float.class);
1601
1602 /**
Ruben Brunk9b305122014-02-21 10:25:26 -0800[diff] [blame]1603 * <p>A reference illumination source roughly matching the current scene
1604 * illumination, which is used to describe the sensor color space
1605 * transformations.</p>
1606 * <p>The values in this tag correspond to the values defined for the
1607 * EXIF LightSource tag. These illuminants are standard light sources
1608 * that are often used for calibrating camera devices.</p>
1609 * @see #SENSOR_REFERENCE_ILLUMINANT_DAYLIGHT
1610 * @see #SENSOR_REFERENCE_ILLUMINANT_FLUORESCENT
1611 * @see #SENSOR_REFERENCE_ILLUMINANT_TUNGSTEN
1612 * @see #SENSOR_REFERENCE_ILLUMINANT_FLASH
1613 * @see #SENSOR_REFERENCE_ILLUMINANT_FINE_WEATHER
1614 * @see #SENSOR_REFERENCE_ILLUMINANT_CLOUDY_WEATHER
1615 * @see #SENSOR_REFERENCE_ILLUMINANT_SHADE
1616 * @see #SENSOR_REFERENCE_ILLUMINANT_DAYLIGHT_FLUORESCENT
1617 * @see #SENSOR_REFERENCE_ILLUMINANT_DAY_WHITE_FLUORESCENT
1618 * @see #SENSOR_REFERENCE_ILLUMINANT_COOL_WHITE_FLUORESCENT
1619 * @see #SENSOR_REFERENCE_ILLUMINANT_WHITE_FLUORESCENT
1620 * @see #SENSOR_REFERENCE_ILLUMINANT_STANDARD_A
1621 * @see #SENSOR_REFERENCE_ILLUMINANT_STANDARD_B
1622 * @see #SENSOR_REFERENCE_ILLUMINANT_STANDARD_C
1623 * @see #SENSOR_REFERENCE_ILLUMINANT_D55
1624 * @see #SENSOR_REFERENCE_ILLUMINANT_D65
1625 * @see #SENSOR_REFERENCE_ILLUMINANT_D75
1626 * @see #SENSOR_REFERENCE_ILLUMINANT_D50
1627 * @see #SENSOR_REFERENCE_ILLUMINANT_ISO_STUDIO_TUNGSTEN
1628 */
1629 public static final Key<Integer> SENSOR_REFERENCE_ILLUMINANT =
1630 new Key<Integer>("android.sensor.referenceIlluminant", int.class);
1631
1632 /**
Ruben Brunkd5fdd1c2014-02-07 17:33:36 -0800[diff] [blame]1633 * <p>A per-device calibration transform matrix to be applied after the
1634 * color space transform when rendering the raw image buffer.</p>
1635 * <p>This matrix is expressed as a 3x3 matrix in row-major-order, and
1636 * contains a per-device calibration transform that maps colors
1637 * from reference camera color space (i.e. the "golden module"
1638 * colorspace) into this camera device's linear native sensor color
1639 * space for the current scene illumination and white balance choice.</p>
1640 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1641 */
1642 public static final Key<Rational[]> SENSOR_CALIBRATION_TRANSFORM =
1643 new Key<Rational[]>("android.sensor.calibrationTransform", Rational[].class);
1644
1645 /**
1646 * <p>A matrix that transforms color values from CIE XYZ color space to
1647 * reference camera color space when rendering the raw image buffer.</p>
1648 * <p>This matrix is expressed as a 3x3 matrix in row-major-order, and
1649 * contains a color transform matrix that maps colors from the CIE
1650 * XYZ color space to the reference camera raw color space (i.e. the
1651 * "golden module" colorspace) for the current scene illumination and
1652 * white balance choice.</p>
1653 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1654 */
1655 public static final Key<Rational[]> SENSOR_COLOR_TRANSFORM =
1656 new Key<Rational[]>("android.sensor.colorTransform", Rational[].class);
1657
1658 /**
1659 * <p>A matrix that transforms white balanced camera colors to the CIE XYZ
1660 * colorspace with a D50 whitepoint.</p>
1661 * <p>This matrix is expressed as a 3x3 matrix in row-major-order, and contains
1662 * a color transform matrix that maps a unit vector in the linear native
1663 * sensor color space to the D50 whitepoint in CIE XYZ color space.</p>
1664 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1665 */
1666 public static final Key<Rational[]> SENSOR_FORWARD_MATRIX =
1667 new Key<Rational[]>("android.sensor.forwardMatrix", Rational[].class);
1668
1669 /**
Ruben Brunk20c76f62014-02-07 15:47:10 -0800[diff] [blame]1670 * <p>The estimated white balance at the time of capture.</p>
1671 * <p>The estimated white balance encoded as the RGB values of the
1672 * perfectly neutral color point in the linear native sensor color space.
1673 * The order of the values is R, G, B; where R is in the lowest index.</p>
1674 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1675 */
1676 public static final Key<Rational[]> SENSOR_NEUTRAL_COLOR_POINT =
1677 new Key<Rational[]>("android.sensor.neutralColorPoint", Rational[].class);
1678
1679 /**
Ruben Brunka9bfdbb2014-02-07 16:58:09 -0800[diff] [blame]1680 * <p>A mapping containing a hue shift, saturation scale, and value scale
1681 * for each pixel.</p>
1682 * <p>hue_samples, saturation_samples, and value_samples are given in
1683 * {@link CameraCharacteristics#SENSOR_PROFILE_HUE_SAT_MAP_DIMENSIONS android.sensor.profileHueSatMapDimensions}.</p>
1684 * <p>Each entry of this map contains three floats corresponding to the
1685 * hue shift, saturation scale, and value scale, respectively; where the
1686 * hue shift has the lowest index. The map entries are stored in the tag
1687 * in nested loop order, with the value divisions in the outer loop, the
1688 * hue divisions in the middle loop, and the saturation divisions in the
1689 * inner loop. All zero input saturation entries are required to have a
1690 * value scale factor of 1.0.</p>
1691 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1692 *
1693 * @see CameraCharacteristics#SENSOR_PROFILE_HUE_SAT_MAP_DIMENSIONS
1694 */
1695 public static final Key<float[]> SENSOR_PROFILE_HUE_SAT_MAP =
1696 new Key<float[]>("android.sensor.profileHueSatMap", float[].class);
1697
1698 /**
1699 * <p>A list of x,y samples defining a tone-mapping curve for gamma adjustment.</p>
1700 * <p>This tag contains a default tone curve that can be applied while
1701 * processing the image as a starting point for user adjustments.
1702 * The curve is specified as a list of value pairs in linear gamma.
1703 * The curve is interpolated using a cubic spline.</p>
1704 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1705 */
1706 public static final Key<float[]> SENSOR_PROFILE_TONE_CURVE =
1707 new Key<float[]>("android.sensor.profileToneCurve", float[].class);
1708
1709 /**
Ruben Brunk987d9f72014-02-11 18:00:24 -0800[diff] [blame]1710 * <p>The worst-case divergence between Bayer green channels.</p>
1711 * <p>This value is an estimate of the worst case split between the
1712 * Bayer green channels in the red and blue rows in the sensor color
1713 * filter array.</p>
1714 * <p>The green split is calculated as follows:</p>
1715 * <ol>
1716 * <li>A representative 5x5 pixel window W within the active
1717 * sensor array is chosen.</li>
1718 * <li>The arithmetic mean of the green channels from the red
1719 * rows (mean_Gr) within W is computed.</li>
1720 * <li>The arithmetic mean of the green channels from the blue
1721 * rows (mean_Gb) within W is computed.</li>
1722 * <li>The maximum ratio R of the two means is computed as follows:
1723 * <code>R = max((mean_Gr + 1)/(mean_Gb + 1), (mean_Gb + 1)/(mean_Gr + 1))</code></li>
1724 * </ol>
1725 * <p>The ratio R is the green split divergence reported for this property,
1726 * which represents how much the green channels differ in the mosaic
1727 * pattern. This value is typically used to determine the treatment of
1728 * the green mosaic channels when demosaicing.</p>
1729 * <p>The green split value can be roughly interpreted as follows:</p>
1730 * <ul>
1731 * <li>R &lt; 1.03 is a negligible split (&lt;3% divergence).</li>
1732 * <li>1.20 &lt;= R &gt;= 1.03 will require some software
1733 * correction to avoid demosaic errors (3-20% divergence).</li>
1734 * <li>R &gt; 1.20 will require strong software correction to produce
1735 * a usuable image (&gt;20% divergence).</li>
1736 * </ul>
1737 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1738 */
1739 public static final Key<Float> SENSOR_GREEN_SPLIT =
1740 new Key<Float>("android.sensor.greenSplit", float.class);
1741
1742 /**
Igor Murashkinc127f052014-01-17 18:06:02 -0800[diff] [blame]1743 * <p>When enabled, the sensor sends a test pattern instead of
1744 * doing a real exposure from the camera.</p>
1745 * <p>When a test pattern is enabled, all manual sensor controls specified
1746 * by android.sensor.* should be ignored. All other controls should
1747 * work as normal.</p>
1748 * <p>For example, if manual flash is enabled, flash firing should still
1749 * occur (and that the test pattern remain unmodified, since the flash
1750 * would not actually affect it).</p>
1751 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1752 * @see #SENSOR_TEST_PATTERN_MODE_OFF
1753 * @see #SENSOR_TEST_PATTERN_MODE_SOLID_COLOR
1754 * @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS
1755 * @see #SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY
1756 * @see #SENSOR_TEST_PATTERN_MODE_PN9
1757 * @see #SENSOR_TEST_PATTERN_MODE_CUSTOM1
1758 */
1759 public static final Key<Integer> SENSOR_TEST_PATTERN_MODE =
1760 new Key<Integer>("android.sensor.testPatternMode", int.class);
1761
1762 /**
Zhijun Heba93fe62014-01-17 16:43:05 -0800[diff] [blame]1763 * <p>Quality of lens shading correction applied
1764 * to the image data.</p>
1765 * <p>When set to OFF mode, no lens shading correction will be applied by the
1766 * camera device, and an identity lens shading map data will be provided
1767 * if <code>{@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} == ON</code>. For example, for lens
1768 * shading map with size specified as <code>{@link CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE android.lens.info.shadingMapSize} = [ 4, 3 ]</code>,
1769 * the output {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap} for this case will be an identity map
1770 * shown below:</p>
1771 * <pre><code>[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1772 * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1773 * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1774 * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1775 * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1776 * 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
1777 * </code></pre>
1778 * <p>When set to other modes, lens shading correction will be applied by the
1779 * camera device. Applications can request lens shading map data by setting
1780 * {@link CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE android.statistics.lensShadingMapMode} to ON, and then the camera device will provide
1781 * lens shading map data in {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap}, with size specified
1782 * by {@link CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE android.lens.info.shadingMapSize}.</p>
1783 *
1784 * @see CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE
1785 * @see CaptureResult#STATISTICS_LENS_SHADING_MAP
1786 * @see CaptureRequest#STATISTICS_LENS_SHADING_MAP_MODE
1787 * @see #SHADING_MODE_OFF
1788 * @see #SHADING_MODE_FAST
1789 * @see #SHADING_MODE_HIGH_QUALITY
Zhijun Heba93fe62014-01-17 16:43:05 -0800[diff] [blame]1790 */
1791 public static final Key<Integer> SHADING_MODE =
1792 new Key<Integer>("android.shading.mode", int.class);
1793
1794 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1795 * <p>State of the face detector
1796 * unit</p>
1797 * <p>Whether face detection is enabled, and whether it
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1798 * should output just the basic fields or the full set of
1799 * fields. Value must be one of the
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1800 * {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES android.statistics.info.availableFaceDetectModes}.</p>
1801 *
1802 * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1803 * @see #STATISTICS_FACE_DETECT_MODE_OFF
1804 * @see #STATISTICS_FACE_DETECT_MODE_SIMPLE
1805 * @see #STATISTICS_FACE_DETECT_MODE_FULL
1806 */
1807 public static final Key<Integer> STATISTICS_FACE_DETECT_MODE =
1808 new Key<Integer>("android.statistics.faceDetectMode", int.class);
1809
1810 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1811 * <p>List of unique IDs for detected
1812 * faces</p>
1813 * <p>Only available if faceDetectMode == FULL</p>
Zhijun He7f80d6f2013-11-04 10:18:05 -0800[diff] [blame]1814 * @hide
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1815 */
1816 public static final Key<int[]> STATISTICS_FACE_IDS =
1817 new Key<int[]>("android.statistics.faceIds", int[].class);
1818
1819 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1820 * <p>List of landmarks for detected
1821 * faces</p>
1822 * <p>Only available if faceDetectMode == FULL</p>
Zhijun He7f80d6f2013-11-04 10:18:05 -0800[diff] [blame]1823 * @hide
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1824 */
1825 public static final Key<int[]> STATISTICS_FACE_LANDMARKS =
1826 new Key<int[]>("android.statistics.faceLandmarks", int[].class);
1827
1828 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1829 * <p>List of the bounding rectangles for detected
1830 * faces</p>
1831 * <p>Only available if faceDetectMode != OFF</p>
Zhijun He7f80d6f2013-11-04 10:18:05 -0800[diff] [blame]1832 * @hide
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1833 */
1834 public static final Key<android.graphics.Rect[]> STATISTICS_FACE_RECTANGLES =
1835 new Key<android.graphics.Rect[]>("android.statistics.faceRectangles", android.graphics.Rect[].class);
1836
1837 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1838 * <p>List of the face confidence scores for
1839 * detected faces</p>
1840 * <p>Only available if faceDetectMode != OFF. The value should be
1841 * meaningful (for example, setting 100 at all times is illegal).</p>
Zhijun He7f80d6f2013-11-04 10:18:05 -0800[diff] [blame]1842 * @hide
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1843 */
1844 public static final Key<byte[]> STATISTICS_FACE_SCORES =
1845 new Key<byte[]>("android.statistics.faceScores", byte[].class);
1846
1847 /**
Igor Murashkin7a9b30e2013-12-11 13:31:38 -0800[diff] [blame]1848 * <p>The shading map is a low-resolution floating-point map
1849 * that lists the coefficients used to correct for vignetting, for each
1850 * Bayer color channel.</p>
1851 * <p>The least shaded section of the image should have a gain factor
1852 * of 1; all other sections should have gains above 1.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1853 * <p>When {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} = TRANSFORM_MATRIX, the map
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1854 * must take into account the colorCorrection settings.</p>
Igor Murashkin7a9b30e2013-12-11 13:31:38 -0800[diff] [blame]1855 * <p>The shading map is for the entire active pixel array, and is not
1856 * affected by the crop region specified in the request. Each shading map
1857 * entry is the value of the shading compensation map over a specific
1858 * pixel on the sensor. Specifically, with a (N x M) resolution shading
1859 * map, and an active pixel array size (W x H), shading map entry
1860 * (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at
1861 * pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels.
1862 * The map is assumed to be bilinearly interpolated between the sample points.</p>
1863 * <p>The channel order is [R, Geven, Godd, B], where Geven is the green
1864 * channel for the even rows of a Bayer pattern, and Godd is the odd rows.
1865 * The shading map is stored in a fully interleaved format, and its size
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1866 * is provided in the camera static metadata by {@link CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE android.lens.info.shadingMapSize}.</p>
Igor Murashkin7a9b30e2013-12-11 13:31:38 -0800[diff] [blame]1867 * <p>The shading map should have on the order of 30-40 rows and columns,
1868 * and must be smaller than 64x64.</p>
1869 * <p>As an example, given a very small map defined as:</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1870 * <pre><code>{@link CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE android.lens.info.shadingMapSize} = [ 4, 3 ]
1871 * {@link CaptureResult#STATISTICS_LENS_SHADING_MAP android.statistics.lensShadingMap} =
Igor Murashkin7a9b30e2013-12-11 13:31:38 -0800[diff] [blame]1872 * [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2,
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1873 * 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
1874 * 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
1875 * 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
1876 * 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
1877 * 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
Igor Murashkin7a9b30e2013-12-11 13:31:38 -0800[diff] [blame]1878 * </code></pre>
1879 * <p>The low-resolution scaling map images for each channel are
1880 * (displayed using nearest-neighbor interpolation):</p>
1881 * <p><img alt="Red lens shading map" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/red_shading.png" />
1882 * <img alt="Green (even rows) lens shading map" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/green_e_shading.png" />
1883 * <img alt="Green (odd rows) lens shading map" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/green_o_shading.png" />
1884 * <img alt="Blue lens shading map" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/blue_shading.png" /></p>
1885 * <p>As a visualization only, inverting the full-color map to recover an
1886 * image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives:</p>
1887 * <p><img alt="Image of a uniform white wall (inverse shading map)" src="../../../../images/camera2/metadata/android.statistics.lensShadingMap/inv_shading.png" /></p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1888 *
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1889 * @see CaptureRequest#COLOR_CORRECTION_MODE
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1890 * @see CameraCharacteristics#LENS_INFO_SHADING_MAP_SIZE
Eino-Ville Talvala265b34c2014-01-16 16:18:52 -0800[diff] [blame]1891 * @see CaptureResult#STATISTICS_LENS_SHADING_MAP
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1892 */
1893 public static final Key<float[]> STATISTICS_LENS_SHADING_MAP =
1894 new Key<float[]>("android.statistics.lensShadingMap", float[].class);
1895
1896 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1897 * <p>The best-fit color channel gains calculated
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1898 * by the camera device's statistics units for the current output frame.</p>
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1899 * <p>This may be different than the gains used for this frame,
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1900 * since statistics processing on data from a new frame
1901 * typically completes after the transform has already been
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1902 * applied to that frame.</p>
1903 * <p>The 4 channel gains are defined in Bayer domain,
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1904 * see {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} for details.</p>
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1905 * <p>This value should always be calculated by the AWB block,
1906 * regardless of the android.control.* current values.</p>
Igor Murashkinaef3b7e2014-01-15 13:20:37 -0800[diff] [blame]1907 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1908 *
1909 * @see CaptureRequest#COLOR_CORRECTION_GAINS
Igor Murashkinaef3b7e2014-01-15 13:20:37 -0800[diff] [blame]1910 * @hide
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1911 */
1912 public static final Key<float[]> STATISTICS_PREDICTED_COLOR_GAINS =
1913 new Key<float[]>("android.statistics.predictedColorGains", float[].class);
1914
1915 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1916 * <p>The best-fit color transform matrix estimate
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1917 * calculated by the camera device's statistics units for the current
1918 * output frame.</p>
1919 * <p>The camera device will provide the estimate from its
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1920 * statistics unit on the white balance transforms to use
Zhijun Hecc28a412014-02-24 15:11:23 -0800[diff] [blame]1921 * for the next frame. These are the values the camera device believes
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1922 * are the best fit for the current output frame. This may
1923 * be different than the transform used for this frame, since
1924 * statistics processing on data from a new frame typically
1925 * completes after the transform has already been applied to
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1926 * that frame.</p>
1927 * <p>These estimates must be provided for all frames, even if
1928 * capture settings and color transforms are set by the application.</p>
1929 * <p>This value should always be calculated by the AWB block,
1930 * regardless of the android.control.* current values.</p>
Igor Murashkinaef3b7e2014-01-15 13:20:37 -0800[diff] [blame]1931 * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
1932 * @hide
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1933 */
1934 public static final Key<Rational[]> STATISTICS_PREDICTED_COLOR_TRANSFORM =
1935 new Key<Rational[]>("android.statistics.predictedColorTransform", Rational[].class);
1936
1937 /**
Zhijun He208fb6c2014-02-03 13:09:06 -0800[diff] [blame]1938 * <p>The camera device estimated scene illumination lighting
1939 * frequency.</p>
1940 * <p>Many light sources, such as most fluorescent lights, flicker at a rate
1941 * that depends on the local utility power standards. This flicker must be
1942 * accounted for by auto-exposure routines to avoid artifacts in captured images.
1943 * The camera device uses this entry to tell the application what the scene
1944 * illuminant frequency is.</p>
1945 * <p>When manual exposure control is enabled
1946 * (<code>{@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} == OFF</code> or <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == OFF</code>),
1947 * the {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode} doesn't do the antibanding, and the
1948 * application can ensure it selects exposure times that do not cause banding
Eino-Ville Talvalad8fd6792014-02-10 12:41:04 -0800[diff] [blame]1949 * issues by looking into this metadata field. See {@link CaptureRequest#CONTROL_AE_ANTIBANDING_MODE android.control.aeAntibandingMode}
Zhijun He208fb6c2014-02-03 13:09:06 -0800[diff] [blame]1950 * for more details.</p>
1951 * <p>Report NONE if there doesn't appear to be flickering illumination.</p>
1952 *
1953 * @see CaptureRequest#CONTROL_AE_ANTIBANDING_MODE
1954 * @see CaptureRequest#CONTROL_AE_MODE
1955 * @see CaptureRequest#CONTROL_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1956 * @see #STATISTICS_SCENE_FLICKER_NONE
1957 * @see #STATISTICS_SCENE_FLICKER_50HZ
1958 * @see #STATISTICS_SCENE_FLICKER_60HZ
1959 */
1960 public static final Key<Integer> STATISTICS_SCENE_FLICKER =
1961 new Key<Integer>("android.statistics.sceneFlicker", int.class);
1962
1963 /**
Ruben Brunk9d454fd2014-03-04 14:11:52 -0800[diff] [blame^]1964 * <p>Operating mode for hotpixel map generation.</p>
1965 * <p>If set to ON, a hotpixel map is returned in {@link CaptureResult#STATISTICS_HOT_PIXEL_MAP android.statistics.hotPixelMap}.
1966 * If set to OFF, no hotpixel map should be returned.</p>
1967 * <p>This must be set to a valid mode from {@link CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES android.statistics.info.availableHotPixelMapModes}.</p>
1968 *
1969 * @see CaptureResult#STATISTICS_HOT_PIXEL_MAP
1970 * @see CameraCharacteristics#STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES
1971 */
1972 public static final Key<Boolean> STATISTICS_HOT_PIXEL_MAP_MODE =
1973 new Key<Boolean>("android.statistics.hotPixelMapMode", boolean.class);
1974
1975 /**
1976 * <p>List of <code>(x, y)</code> coordinates of hot/defective pixels on the sensor.</p>
1977 * <p>A coordinate <code>(x, y)</code> must lie between <code>(0, 0)</code>, and
1978 * <code>(width - 1, height - 1)</code> (inclusive), which are the top-left and
1979 * bottom-right of the pixel array, respectively. The width and
1980 * height dimensions are given in {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.
1981 * This may include hot pixels that lie outside of the active array
1982 * bounds given by {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</p>
1983 *
1984 * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
1985 * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
1986 */
1987 public static final Key<int[]> STATISTICS_HOT_PIXEL_MAP =
1988 new Key<int[]>("android.statistics.hotPixelMap", int[].class);
1989
1990 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]1991 * <p>Tonemapping / contrast / gamma curve for the blue
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]1992 * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
1993 * CONTRAST_CURVE.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]1994 * <p>See {@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} for more details.</p>
1995 *
Igor Murashkin3242f4f2014-01-15 12:27:41 -0800[diff] [blame]1996 * @see CaptureRequest#TONEMAP_CURVE_RED
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]1997 * @see CaptureRequest#TONEMAP_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]1998 */
Zhijun He3ffd7052013-08-19 15:45:08 -0700[diff] [blame]1999 public static final Key<float[]> TONEMAP_CURVE_BLUE =
2000 new Key<float[]>("android.tonemap.curveBlue", float[].class);
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2001
2002 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]2003 * <p>Tonemapping / contrast / gamma curve for the green
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]2004 * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
2005 * CONTRAST_CURVE.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]2006 * <p>See {@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} for more details.</p>
2007 *
Igor Murashkin3242f4f2014-01-15 12:27:41 -0800[diff] [blame]2008 * @see CaptureRequest#TONEMAP_CURVE_RED
Zhijun He5f2a47f2014-01-16 15:44:41 -0800[diff] [blame]2009 * @see CaptureRequest#TONEMAP_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2010 */
Zhijun He3ffd7052013-08-19 15:45:08 -0700[diff] [blame]2011 public static final Key<float[]> TONEMAP_CURVE_GREEN =
2012 new Key<float[]>("android.tonemap.curveGreen", float[].class);
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2013
2014 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]2015 * <p>Tonemapping / contrast / gamma curve for the red
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]2016 * channel, to use when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
2017 * CONTRAST_CURVE.</p>
2018 * <p>Each channel's curve is defined by an array of control points:</p>
2019 * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} =
2020 * [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
Zhijun He870922b2014-02-15 21:47:51 -0800[diff] [blame]2021 * 2 &lt;= N &lt;= {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}</code></pre>
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]2022 * <p>These are sorted in order of increasing <code>Pin</code>; it is always
2023 * guaranteed that input values 0.0 and 1.0 are included in the list to
2024 * define a complete mapping. For input values between control points,
2025 * the camera device must linearly interpolate between the control
2026 * points.</p>
2027 * <p>Each curve can have an independent number of points, and the number
2028 * of points can be less than max (that is, the request doesn't have to
2029 * always provide a curve with number of points equivalent to
2030 * {@link CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS android.tonemap.maxCurvePoints}).</p>
2031 * <p>A few examples, and their corresponding graphical mappings; these
2032 * only specify the red channel and the precision is limited to 4
2033 * digits, for conciseness.</p>
2034 * <p>Linear mapping:</p>
2035 * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [ 0, 0, 1.0, 1.0 ]
2036 * </code></pre>
2037 * <p><img alt="Linear mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/linear_tonemap.png" /></p>
2038 * <p>Invert mapping:</p>
2039 * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [ 0, 1.0, 1.0, 0 ]
2040 * </code></pre>
2041 * <p><img alt="Inverting mapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/inverse_tonemap.png" /></p>
2042 * <p>Gamma 1/2.2 mapping, with 16 control points:</p>
2043 * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [
2044 * 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812,
2045 * 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072,
2046 * 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685,
2047 * 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ]
2048 * </code></pre>
2049 * <p><img alt="Gamma = 1/2.2 tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/gamma_tonemap.png" /></p>
2050 * <p>Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:</p>
2051 * <pre><code>{@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed} = [
2052 * 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845,
2053 * 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130,
2054 * 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721,
2055 * 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ]
2056 * </code></pre>
2057 * <p><img alt="sRGB tonemapping curve" src="../../../../images/camera2/metadata/android.tonemap.curveRed/srgb_tonemap.png" /></p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]2058 *
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]2059 * @see CaptureRequest#TONEMAP_CURVE_RED
2060 * @see CameraCharacteristics#TONEMAP_MAX_CURVE_POINTS
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]2061 * @see CaptureRequest#TONEMAP_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2062 */
2063 public static final Key<float[]> TONEMAP_CURVE_RED =
2064 new Key<float[]>("android.tonemap.curveRed", float[].class);
2065
2066 /**
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]2067 * <p>High-level global contrast/gamma/tonemapping control.</p>
2068 * <p>When switching to an application-defined contrast curve by setting
2069 * {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} to CONTRAST_CURVE, the curve is defined
2070 * per-channel with a set of <code>(in, out)</code> points that specify the
2071 * mapping from input high-bit-depth pixel value to the output
2072 * low-bit-depth value. Since the actual pixel ranges of both input
2073 * and output may change depending on the camera pipeline, the values
2074 * are specified by normalized floating-point numbers.</p>
2075 * <p>More-complex color mapping operations such as 3D color look-up
2076 * tables, selective chroma enhancement, or other non-linear color
2077 * transforms will be disabled when {@link CaptureRequest#TONEMAP_MODE android.tonemap.mode} is
2078 * CONTRAST_CURVE.</p>
2079 * <p>When using either FAST or HIGH_QUALITY, the camera device will
2080 * emit its own tonemap curve in {@link CaptureRequest#TONEMAP_CURVE_RED android.tonemap.curveRed},
2081 * {@link CaptureRequest#TONEMAP_CURVE_GREEN android.tonemap.curveGreen}, and {@link CaptureRequest#TONEMAP_CURVE_BLUE android.tonemap.curveBlue}.
2082 * These values are always available, and as close as possible to the
2083 * actually used nonlinear/nonglobal transforms.</p>
2084 * <p>If a request is sent with TRANSFORM_MATRIX with the camera device's
2085 * provided curve in FAST or HIGH_QUALITY, the image's tonemap will be
2086 * roughly the same.</p>
Igor Murashkin3242f4f2014-01-15 12:27:41 -0800[diff] [blame]2087 *
Igor Murashkine0060932014-01-17 17:24:11 -0800[diff] [blame]2088 * @see CaptureRequest#TONEMAP_CURVE_BLUE
2089 * @see CaptureRequest#TONEMAP_CURVE_GREEN
2090 * @see CaptureRequest#TONEMAP_CURVE_RED
2091 * @see CaptureRequest#TONEMAP_MODE
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2092 * @see #TONEMAP_MODE_CONTRAST_CURVE
2093 * @see #TONEMAP_MODE_FAST
2094 * @see #TONEMAP_MODE_HIGH_QUALITY
2095 */
2096 public static final Key<Integer> TONEMAP_MODE =
2097 new Key<Integer>("android.tonemap.mode", int.class);
2098
2099 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]2100 * <p>This LED is nominally used to indicate to the user
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2101 * that the camera is powered on and may be streaming images back to the
2102 * Application Processor. In certain rare circumstances, the OS may
2103 * disable this when video is processed locally and not transmitted to
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]2104 * any untrusted applications.</p>
2105 * <p>In particular, the LED <em>must</em> always be on when the data could be
2106 * transmitted off the device. The LED <em>should</em> always be on whenever
2107 * data is stored locally on the device.</p>
2108 * <p>The LED <em>may</em> be off if a trusted application is using the data that
2109 * doesn't violate the above rules.</p>
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2110 * @hide
2111 */
2112 public static final Key<Boolean> LED_TRANSMIT =
2113 new Key<Boolean>("android.led.transmit", boolean.class);
2114
2115 /**
Igor Murashkinace5bf02013-12-10 17:36:40 -0800[diff] [blame]2116 * <p>Whether black-level compensation is locked
Eino-Ville Talvala0956af52013-12-26 13:19:10 -0800[diff] [blame]2117 * to its current values, or is free to vary.</p>
2118 * <p>Whether the black level offset was locked for this frame. Should be
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]2119 * ON if {@link CaptureRequest#BLACK_LEVEL_LOCK android.blackLevel.lock} was ON in the capture request, unless
Eino-Ville Talvala0956af52013-12-26 13:19:10 -0800[diff] [blame]2120 * a change in other capture settings forced the camera device to
2121 * perform a black level reset.</p>
Eino-Ville Talvala0da8bf52014-01-08 16:18:35 -0800[diff] [blame]2122 *
2123 * @see CaptureRequest#BLACK_LEVEL_LOCK
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2124 */
2125 public static final Key<Boolean> BLACK_LEVEL_LOCK =
2126 new Key<Boolean>("android.blackLevel.lock", boolean.class);
2127
Igor Murashkin3865a842014-01-17 18:18:39 -0800[diff] [blame]2128 /**
2129 * <p>The frame number corresponding to the last request
2130 * with which the output result (metadata + buffers) has been fully
2131 * synchronized.</p>
2132 * <p>When a request is submitted to the camera device, there is usually a
2133 * delay of several frames before the controls get applied. A camera
2134 * device may either choose to account for this delay by implementing a
2135 * pipeline and carefully submit well-timed atomic control updates, or
2136 * it may start streaming control changes that span over several frame
2137 * boundaries.</p>
2138 * <p>In the latter case, whenever a request's settings change relative to
2139 * the previous submitted request, the full set of changes may take
2140 * multiple frame durations to fully take effect. Some settings may
2141 * take effect sooner (in less frame durations) than others.</p>
2142 * <p>While a set of control changes are being propagated, this value
2143 * will be CONVERGING.</p>
2144 * <p>Once it is fully known that a set of control changes have been
2145 * finished propagating, and the resulting updated control settings
2146 * have been read back by the camera device, this value will be set
2147 * to a non-negative frame number (corresponding to the request to
2148 * which the results have synchronized to).</p>
2149 * <p>Older camera device implementations may not have a way to detect
2150 * when all camera controls have been applied, and will always set this
2151 * value to UNKNOWN.</p>
2152 * <p>FULL capability devices will always have this value set to the
2153 * frame number of the request corresponding to this result.</p>
2154 * <p><em>Further details</em>:</p>
2155 * <ul>
2156 * <li>Whenever a request differs from the last request, any future
2157 * results not yet returned may have this value set to CONVERGING (this
2158 * could include any in-progress captures not yet returned by the camera
2159 * device, for more details see pipeline considerations below).</li>
2160 * <li>Submitting a series of multiple requests that differ from the
2161 * previous request (e.g. r1, r2, r3 s.t. r1 != r2 != r3)
2162 * moves the new synchronization frame to the last non-repeating
2163 * request (using the smallest frame number from the contiguous list of
2164 * repeating requests).</li>
2165 * <li>Submitting the same request repeatedly will not change this value
2166 * to CONVERGING, if it was already a non-negative value.</li>
2167 * <li>When this value changes to non-negative, that means that all of the
2168 * metadata controls from the request have been applied, all of the
2169 * metadata controls from the camera device have been read to the
2170 * updated values (into the result), and all of the graphics buffers
2171 * corresponding to this result are also synchronized to the request.</li>
2172 * </ul>
2173 * <p><em>Pipeline considerations</em>:</p>
2174 * <p>Submitting a request with updated controls relative to the previously
2175 * submitted requests may also invalidate the synchronization state
2176 * of all the results corresponding to currently in-flight requests.</p>
2177 * <p>In other words, results for this current request and up to
2178 * {@link CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH android.request.pipelineMaxDepth} prior requests may have their
2179 * android.sync.frameNumber change to CONVERGING.</p>
2180 *
2181 * @see CameraCharacteristics#REQUEST_PIPELINE_MAX_DEPTH
2182 * @see #SYNC_FRAME_NUMBER_CONVERGING
2183 * @see #SYNC_FRAME_NUMBER_UNKNOWN
2184 * @hide
2185 */
2186 public static final Key<Integer> SYNC_FRAME_NUMBER =
2187 new Key<Integer>("android.sync.frameNumber", int.class);
2188
Eino-Ville Talvala5a32b20c2013-08-08 12:38:36 -0700[diff] [blame]2189 /*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
2190 * End generated code
2191 *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/
Igor Murashkinb779ac12013-09-05 12:40:19 -0700[diff] [blame]2192
2193 /**
2194 * <p>
2195 * List of the {@link Face Faces} detected through camera face detection
2196 * in this result.
2197 * </p>
2198 * <p>
2199 * Only available if {@link #STATISTICS_FACE_DETECT_MODE} {@code !=}
2200 * {@link CameraMetadata#STATISTICS_FACE_DETECT_MODE_OFF OFF}.
2201 * </p>
2202 *
2203 * @see Face
2204 */
2205 public static final Key<Face[]> STATISTICS_FACES =
2206 new Key<Face[]>("android.statistics.faces", Face[].class);
Eino-Ville Talvalab2675542012-12-12 13:29:45 -0800[diff] [blame]2207}