1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
12 ************************
13 Camera Control Reference
14 ************************
16 The Camera class includes controls for mechanical (or equivalent
17 digital) features of a device such as controllable lenses or sensors.
20 .. _camera-control-id:
25 ``V4L2_CID_CAMERA_CLASS (class)``
26 The Camera class descriptor. Calling
27 :ref:`VIDIOC_QUERYCTRL` for this control will
28 return a description of this control class.
30 .. _v4l2-exposure-auto-type:
32 ``V4L2_CID_EXPOSURE_AUTO``
35 enum v4l2_exposure_auto_type -
36 Enables automatic adjustments of the exposure time and/or iris
37 aperture. The effect of manual changes of the exposure time or iris
38 aperture while these features are enabled is undefined, drivers
39 should ignore such requests. Possible values are:
47 * - ``V4L2_EXPOSURE_AUTO``
48 - Automatic exposure time, automatic iris aperture.
49 * - ``V4L2_EXPOSURE_MANUAL``
50 - Manual exposure time, manual iris.
51 * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
52 - Manual exposure time, auto iris.
53 * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
54 - Auto exposure time, manual iris.
58 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
59 Determines the exposure time of the camera sensor. The exposure time
60 is limited by the frame interval. Drivers should interpret the
61 values as 100 µs units, where the value 1 stands for 1/10000th of a
62 second, 10000 for 1 second and 100000 for 10 seconds.
64 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
65 When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
66 ``APERTURE_PRIORITY``, this control determines if the device may
67 dynamically vary the frame rate. By default this feature is disabled
68 (0) and the frame rate must remain constant.
70 ``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
71 Determines the automatic exposure compensation, it is effective only
72 when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
73 ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
74 terms of EV, drivers should interpret the values as 0.001 EV units,
75 where the value 1000 stands for +1 EV.
77 Increasing the exposure compensation value is equivalent to
78 decreasing the exposure value (EV) and will increase the amount of
79 light at the image sensor. The camera performs the exposure
80 compensation by adjusting absolute exposure time and/or aperture.
82 .. _v4l2-exposure-metering:
84 ``V4L2_CID_EXPOSURE_METERING``
87 enum v4l2_exposure_metering -
88 Determines how the camera measures the amount of light available for
89 the frame exposure. Possible values are:
91 .. tabularcolumns:: |p{8.5cm}|p{9.0cm}|
97 * - ``V4L2_EXPOSURE_METERING_AVERAGE``
98 - Use the light information coming from the entire frame and average
99 giving no weighting to any particular portion of the metered area.
100 * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
101 - Average the light information coming from the entire frame giving
102 priority to the center of the metered area.
103 * - ``V4L2_EXPOSURE_METERING_SPOT``
104 - Measure only very small area at the center of the frame.
105 * - ``V4L2_EXPOSURE_METERING_MATRIX``
106 - A multi-zone metering. The light intensity is measured in several
107 points of the frame and the results are combined. The algorithm of
108 the zones selection and their significance in calculating the
109 final value is device dependent.
113 ``V4L2_CID_PAN_RELATIVE (integer)``
114 This control turns the camera horizontally by the specified amount.
115 The unit is undefined. A positive value moves the camera to the
116 right (clockwise when viewed from above), a negative value to the
117 left. A value of zero does not cause motion. This is a write-only
120 ``V4L2_CID_TILT_RELATIVE (integer)``
121 This control turns the camera vertically by the specified amount.
122 The unit is undefined. A positive value moves the camera up, a
123 negative value down. A value of zero does not cause motion. This is
124 a write-only control.
126 ``V4L2_CID_PAN_RESET (button)``
127 When this control is set, the camera moves horizontally to the
130 ``V4L2_CID_TILT_RESET (button)``
131 When this control is set, the camera moves vertically to the default
134 ``V4L2_CID_PAN_ABSOLUTE (integer)``
135 This control turns the camera horizontally to the specified
136 position. Positive values move the camera to the right (clockwise
137 when viewed from above), negative values to the left. Drivers should
138 interpret the values as arc seconds, with valid values between -180
139 * 3600 and +180 * 3600 inclusive.
141 ``V4L2_CID_TILT_ABSOLUTE (integer)``
142 This control turns the camera vertically to the specified position.
143 Positive values move the camera up, negative values down. Drivers
144 should interpret the values as arc seconds, with valid values
145 between -180 * 3600 and +180 * 3600 inclusive.
147 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
148 This control sets the focal point of the camera to the specified
149 position. The unit is undefined. Positive values set the focus
150 closer to the camera, negative values towards infinity.
152 ``V4L2_CID_FOCUS_RELATIVE (integer)``
153 This control moves the focal point of the camera by the specified
154 amount. The unit is undefined. Positive values move the focus closer
155 to the camera, negative values towards infinity. This is a
158 ``V4L2_CID_FOCUS_AUTO (boolean)``
159 Enables continuous automatic focus adjustments. The effect of manual
160 focus adjustments while this feature is enabled is undefined,
161 drivers should ignore such requests.
163 ``V4L2_CID_AUTO_FOCUS_START (button)``
164 Starts single auto focus process. The effect of setting this control
165 when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
166 drivers should ignore such requests.
168 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
169 Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
170 control. It is effective only when the continuous autofocus is
171 disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
174 .. _v4l2-auto-focus-status:
176 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
177 The automatic focus status. This is a read-only control.
179 Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
180 control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
183 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
189 * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
190 - Automatic focus is not active.
191 * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
192 - Automatic focusing is in progress.
193 * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
194 - Focus has been reached.
195 * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
196 - Automatic focus has failed, the driver will not transition from
197 this state until another action is performed by an application.
201 .. _v4l2-auto-focus-range:
203 ``V4L2_CID_AUTO_FOCUS_RANGE``
206 enum v4l2_auto_focus_range -
207 Determines auto focus distance range for which lens may be adjusted.
209 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
215 * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
216 - The camera automatically selects the focus range.
217 * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
218 - Normal distance range, limited for best automatic focus
220 * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
221 - Macro (close-up) auto focus. The camera will use its minimum
222 possible distance for auto focus.
223 * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
224 - The lens is set to focus on an object at infinite distance.
228 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
229 Specify the objective lens focal length as an absolute value. The
230 zoom unit is driver-specific and its value should be a positive
233 ``V4L2_CID_ZOOM_RELATIVE (integer)``
234 Specify the objective lens focal length relatively to the current
235 value. Positive values move the zoom lens group towards the
236 telephoto direction, negative values towards the wide-angle
237 direction. The zoom unit is driver-specific. This is a write-only
240 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
241 Move the objective lens group at the specified speed until it
242 reaches physical device limits or until an explicit request to stop
243 the movement. A positive value moves the zoom lens group towards the
244 telephoto direction. A value of zero stops the zoom lens group
245 movement. A negative value moves the zoom lens group towards the
246 wide-angle direction. The zoom speed unit is driver-specific.
248 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
249 This control sets the camera's aperture to the specified value. The
250 unit is undefined. Larger values open the iris wider, smaller values
253 ``V4L2_CID_IRIS_RELATIVE (integer)``
254 This control modifies the camera's aperture by the specified amount.
255 The unit is undefined. Positive values open the iris one step
256 further, negative values close it one step further. This is a
259 ``V4L2_CID_PRIVACY (boolean)``
260 Prevent video from being acquired by the camera. When this control
261 is set to ``TRUE`` (1), no image can be captured by the camera.
262 Common means to enforce privacy are mechanical obturation of the
263 sensor and firmware image processing, but the device is not
264 restricted to these methods. Devices that implement the privacy
265 control must support read access and may support write access.
267 ``V4L2_CID_BAND_STOP_FILTER (integer)``
268 Switch the band-stop filter of a camera sensor on or off, or specify
269 its strength. Such band-stop filters can be used, for example, to
270 filter out the fluorescent light component.
272 .. _v4l2-auto-n-preset-white-balance:
274 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
277 enum v4l2_auto_n_preset_white_balance -
278 Sets white balance to automatic, manual or a preset. The presets
279 determine color temperature of the light as a hint to the camera for
280 white balance adjustments resulting in most accurate color
281 representation. The following white balance presets are listed in
282 order of increasing color temperature.
284 .. tabularcolumns:: |p{7.0 cm}|p{10.5cm}|
290 * - ``V4L2_WHITE_BALANCE_MANUAL``
291 - Manual white balance.
292 * - ``V4L2_WHITE_BALANCE_AUTO``
293 - Automatic white balance adjustments.
294 * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
295 - White balance setting for incandescent (tungsten) lighting. It
296 generally cools down the colors and corresponds approximately to
297 2500...3500 K color temperature range.
298 * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
299 - White balance preset for fluorescent lighting. It corresponds
300 approximately to 4000...5000 K color temperature.
301 * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
302 - With this setting the camera will compensate for fluorescent H
304 * - ``V4L2_WHITE_BALANCE_HORIZON``
305 - White balance setting for horizon daylight. It corresponds
306 approximately to 5000 K color temperature.
307 * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
308 - White balance preset for daylight (with clear sky). It corresponds
309 approximately to 5000...6500 K color temperature.
310 * - ``V4L2_WHITE_BALANCE_FLASH``
311 - With this setting the camera will compensate for the flash light.
312 It slightly warms up the colors and corresponds roughly to
313 5000...5500 K color temperature.
314 * - ``V4L2_WHITE_BALANCE_CLOUDY``
315 - White balance preset for moderately overcast sky. This option
316 corresponds approximately to 6500...8000 K color temperature
318 * - ``V4L2_WHITE_BALANCE_SHADE``
319 - White balance preset for shade or heavily overcast sky. It
320 corresponds approximately to 9000...10000 K color temperature.
324 .. _v4l2-wide-dynamic-range:
326 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
327 Enables or disables the camera's wide dynamic range feature. This
328 feature allows to obtain clear images in situations where intensity
329 of the illumination varies significantly throughout the scene, i.e.
330 there are simultaneously very dark and very bright areas. It is most
331 commonly realized in cameras by combining two subsequent frames with
332 different exposure times. [#f1]_
334 .. _v4l2-image-stabilization:
336 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
337 Enables or disables image stabilization.
339 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
340 Determines ISO equivalent of an image sensor indicating the sensor's
341 sensitivity to light. The numbers are expressed in arithmetic scale,
342 as per :ref:`iso12232` standard, where doubling the sensor
343 sensitivity is represented by doubling the numerical ISO value.
344 Applications should interpret the values as standard ISO values
345 multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
346 Drivers will usually support only a subset of standard ISO values.
347 The effect of setting this control while the
348 ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
349 than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
350 should ignore such requests.
352 .. _v4l2-iso-sensitivity-auto-type:
354 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
357 enum v4l2_iso_sensitivity_type -
358 Enables or disables automatic ISO sensitivity adjustments.
366 * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
367 - Manual ISO sensitivity.
368 * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
369 - Automatic ISO sensitivity adjustments.
375 ``V4L2_CID_SCENE_MODE``
378 enum v4l2_scene_mode -
379 This control allows to select scene programs as the camera automatic
380 modes optimized for common shooting scenes. Within these modes the
381 camera determines best exposure, aperture, focusing, light metering,
382 white balance and equivalent sensitivity. The controls of those
383 parameters are influenced by the scene mode control. An exact
384 behavior in each mode is subject to the camera specification.
386 When the scene mode feature is not used, this control should be set
387 to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
388 controls are accessible. The following scene programs are defined:
390 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
396 * - ``V4L2_SCENE_MODE_NONE``
397 - The scene mode feature is disabled.
398 * - ``V4L2_SCENE_MODE_BACKLIGHT``
399 - Backlight. Compensates for dark shadows when light is coming from
400 behind a subject, also by automatically turning on the flash.
401 * - ``V4L2_SCENE_MODE_BEACH_SNOW``
402 - Beach and snow. This mode compensates for all-white or bright
403 scenes, which tend to look gray and low contrast, when camera's
404 automatic exposure is based on an average scene brightness. To
405 compensate, this mode automatically slightly overexposes the
406 frames. The white balance may also be adjusted to compensate for
407 the fact that reflected snow looks bluish rather than white.
408 * - ``V4L2_SCENE_MODE_CANDLELIGHT``
409 - Candle light. The camera generally raises the ISO sensitivity and
410 lowers the shutter speed. This mode compensates for relatively
411 close subject in the scene. The flash is disabled in order to
412 preserve the ambiance of the light.
413 * - ``V4L2_SCENE_MODE_DAWN_DUSK``
414 - Dawn and dusk. Preserves the colors seen in low natural light
415 before dusk and after down. The camera may turn off the flash, and
416 automatically focus at infinity. It will usually boost saturation
417 and lower the shutter speed.
418 * - ``V4L2_SCENE_MODE_FALL_COLORS``
419 - Fall colors. Increases saturation and adjusts white balance for
420 color enhancement. Pictures of autumn leaves get saturated reds
422 * - ``V4L2_SCENE_MODE_FIREWORKS``
423 - Fireworks. Long exposure times are used to capture the expanding
424 burst of light from a firework. The camera may invoke image
426 * - ``V4L2_SCENE_MODE_LANDSCAPE``
427 - Landscape. The camera may choose a small aperture to provide deep
428 depth of field and long exposure duration to help capture detail
429 in dim light conditions. The focus is fixed at infinity. Suitable
430 for distant and wide scenery.
431 * - ``V4L2_SCENE_MODE_NIGHT``
432 - Night, also known as Night Landscape. Designed for low light
433 conditions, it preserves detail in the dark areas without blowing
434 out bright objects. The camera generally sets itself to a
435 medium-to-high ISO sensitivity, with a relatively long exposure
436 time, and turns flash off. As such, there will be increased image
437 noise and the possibility of blurred image.
438 * - ``V4L2_SCENE_MODE_PARTY_INDOOR``
439 - Party and indoor. Designed to capture indoor scenes that are lit
440 by indoor background lighting as well as the flash. The camera
441 usually increases ISO sensitivity, and adjusts exposure for the
442 low light conditions.
443 * - ``V4L2_SCENE_MODE_PORTRAIT``
444 - Portrait. The camera adjusts the aperture so that the depth of
445 field is reduced, which helps to isolate the subject against a
446 smooth background. Most cameras recognize the presence of faces in
447 the scene and focus on them. The color hue is adjusted to enhance
448 skin tones. The intensity of the flash is often reduced.
449 * - ``V4L2_SCENE_MODE_SPORTS``
450 - Sports. Significantly increases ISO and uses a fast shutter speed
451 to freeze motion of rapidly-moving subjects. Increased image noise
452 may be seen in this mode.
453 * - ``V4L2_SCENE_MODE_SUNSET``
454 - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
456 * - ``V4L2_SCENE_MODE_TEXT``
457 - Text. It applies extra contrast and sharpness, it is typically a
458 black-and-white mode optimized for readability. Automatic focus
459 may be switched to close-up mode and this setting may also involve
460 some lens-distortion correction.
464 ``V4L2_CID_3A_LOCK (bitmask)``
465 This control locks or unlocks the automatic focus, exposure and
466 white balance. The automatic adjustments can be paused independently
467 by setting the corresponding lock bit to 1. The camera then retains
468 the settings until the lock bit is cleared. The following lock bits
471 When a given algorithm is not enabled, drivers should ignore
472 requests to lock it and should return no error. An example might be
473 an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
474 ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
475 value of this control may be changed by exposure, white balance or
484 * - ``V4L2_LOCK_EXPOSURE``
485 - Automatic exposure adjustments lock.
486 * - ``V4L2_LOCK_WHITE_BALANCE``
487 - Automatic white balance adjustments lock.
488 * - ``V4L2_LOCK_FOCUS``
489 - Automatic focus lock.
493 ``V4L2_CID_PAN_SPEED (integer)``
494 This control turns the camera horizontally at the specific speed.
495 The unit is undefined. A positive value moves the camera to the
496 right (clockwise when viewed from above), a negative value to the
497 left. A value of zero stops the motion if one is in progress and has
500 ``V4L2_CID_TILT_SPEED (integer)``
501 This control turns the camera vertically at the specified speed. The
502 unit is undefined. A positive value moves the camera up, a negative
503 value down. A value of zero stops the motion if one is in progress
504 and has no effect otherwise.
507 This control may be changed to a menu control in the future, if more
508 options are required.