media/v4l/control.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
9 Devices typically have a number of user-settable controls such as
10 brightness, saturation and so on, which would be presented to the user
13 values, and the default value will vary from device to device. The
14 control ioctls provide the information and a mechanism to create a nice
21 pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
22 :ref:`control-id`. The ID is used when querying the attributes of a
25 Generally applications should present controls to the user without
27 the user is supposed to understand. When the purpose is non-intuitive
28 the driver writer should provide a user manual, a user interface plug-in
30 to change a few controls programmatically, for example to mute a device
39 If a control is not applicable to the current configuration of the
40 device (for example, it doesn't apply to the current video input)
44 except to stay within the reported bounds. They also do not change e. g.
48 V4L2 specifies an event mechanism to notify applications when controls
51 ``V4L2_EVENT_CTRL``), panel applications might want to make use of that
52 in order to always reflect the correct control value.
57 .. _control-id:
63     First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
85     Audio stereo balance. Minimum corresponds to all the way left,
86     maximum to right.
95     Mute audio, i. e. set the volume to zero, however without affecting
97     at load time to avoid excessive noise. Actually the entire device
98     should be reset to a low power consumption state.
127     Whiteness for grey-scale devices. This is a synonym for
140     Primarily used to control gain on e.g. TV tuners but also on
141     webcams. Most devices control only digital gain with this control
143     recognise the difference between digital and analogue gain use
152 .. _v4l2-power-line-frequency:
155     Enables a power line frequency filter to avoid flicker. Possible
173     (incandescent) to 6500 (daylight). For more information about color
196 .. _v4l2-colorfx:
205 .. flat-table::
206     :header-rows:  0
207     :stub-columns: 0
210     * - ``V4L2_COLORFX_NONE``
211       - Color effect is disabled.
212     * - ``V4L2_COLORFX_ANTIQUE``
213       - An aging (old photo) effect.
214     * - ``V4L2_COLORFX_ART_FREEZE``
215       - Frost color effect.
216     * - ``V4L2_COLORFX_AQUA``
217       - Water color, cool tone.
218     * - ``V4L2_COLORFX_BW``
219       - Black and white.
220     * - ``V4L2_COLORFX_EMBOSS``
221       - Emboss, the highlights and shadows replace light/dark boundaries
222 	and low contrast areas are set to a gray background.
223     * - ``V4L2_COLORFX_GRASS_GREEN``
224       - Grass green.
225     * - ``V4L2_COLORFX_NEGATIVE``
226       - Negative.
227     * - ``V4L2_COLORFX_SEPIA``
228       - Sepia tone.
229     * - ``V4L2_COLORFX_SKETCH``
230       - Sketch.
231     * - ``V4L2_COLORFX_SKIN_WHITEN``
232       - Skin whiten.
233     * - ``V4L2_COLORFX_SKY_BLUE``
234       - Sky blue.
235     * - ``V4L2_COLORFX_SOLARIZATION``
236       - Solarization, the image is partially reversed in tone, only color
238     * - ``V4L2_COLORFX_SILHOUETTE``
239       - Silhouette (outline).
240     * - ``V4L2_COLORFX_VIVID``
241       - Vivid colors.
242     * - ``V4L2_COLORFX_SET_CBCR``
243       - The Cb and Cr chroma components are replaced by fixed coefficients
245     * - ``V4L2_COLORFX_SET_RGB``
246       - The RGB components are replaced by the fixed RGB components determined
268     180. Rotating the image to 90 and 270 will reverse the height and
269     width of the display window. It is necessary to set the new height
271     :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
276     color needs to be specified in the RGB24 format. The supplied 32 bit
277     value is interpreted as bits 0-7 Red color information, bits 8-15
278     Green color information, bits 16-23 Blue color information and bits
279     24-31 must be zero.
286     This is a read-only control that can be read by the application and
287     used as a hint to determine the number of CAPTURE buffers to pass to
289     necessary for hardware to work.
292     This is a read-only control that can be read by the application and
293     used as a hint to determine the number of OUTPUT buffers to pass to
295     necessary for hardware to work.
297 .. _v4l2-alpha-component:
301     queue of a mem-to-mem device) produces a frame format that includes
303     :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value
304     is not defined by the device or the mem-to-mem input data this
306     When an output device (or output queue of a mem-to-mem device)
336 .. code-block:: c
378 .. code-block:: c
403 .. code-block:: c
451 .. code-block:: c
459     if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
473 	if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
487 	if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
507    controls. This makes it hard to programmatically set such controls
509    order to resolve this drivers use unique IDs and the
510    ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
511    kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
516    the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so