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
146 .. _v4l2-cid-hflip:
151 .. _v4l2-cid-vflip:
156 .. _v4l2-power-line-frequency:
159     Enables a power line frequency filter to avoid flicker. Possible
177     (incandescent) to 6500 (daylight). For more information about color
200 .. _v4l2-colorfx:
209 .. flat-table::
210     :header-rows:  0
211     :stub-columns: 0
214     * - ``V4L2_COLORFX_NONE``
215       - Color effect is disabled.
216     * - ``V4L2_COLORFX_ANTIQUE``
217       - An aging (old photo) effect.
218     * - ``V4L2_COLORFX_ART_FREEZE``
219       - Frost color effect.
220     * - ``V4L2_COLORFX_AQUA``
221       - Water color, cool tone.
222     * - ``V4L2_COLORFX_BW``
223       - Black and white.
224     * - ``V4L2_COLORFX_EMBOSS``
225       - Emboss, the highlights and shadows replace light/dark boundaries
226 	and low contrast areas are set to a gray background.
227     * - ``V4L2_COLORFX_GRASS_GREEN``
228       - Grass green.
229     * - ``V4L2_COLORFX_NEGATIVE``
230       - Negative.
231     * - ``V4L2_COLORFX_SEPIA``
232       - Sepia tone.
233     * - ``V4L2_COLORFX_SKETCH``
234       - Sketch.
235     * - ``V4L2_COLORFX_SKIN_WHITEN``
236       - Skin whiten.
237     * - ``V4L2_COLORFX_SKY_BLUE``
238       - Sky blue.
239     * - ``V4L2_COLORFX_SOLARIZATION``
240       - Solarization, the image is partially reversed in tone, only color
242     * - ``V4L2_COLORFX_SILHOUETTE``
243       - Silhouette (outline).
244     * - ``V4L2_COLORFX_VIVID``
245       - Vivid colors.
246     * - ``V4L2_COLORFX_SET_CBCR``
247       - The Cb and Cr chroma components are replaced by fixed coefficients
249     * - ``V4L2_COLORFX_SET_RGB``
250       - The RGB components are replaced by the fixed RGB components determined
272     180. Rotating the image to 90 and 270 will reverse the height and
273     width of the display window. It is necessary to set the new height
275     :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
280     color needs to be specified in the RGB24 format. The supplied 32 bit
281     value is interpreted as bits 0-7 Red color information, bits 8-15
282     Green color information, bits 16-23 Blue color information and bits
283     24-31 must be zero.
290     This is a read-only control that can be read by the application and
291     used as a hint to determine the number of CAPTURE buffers to pass to
293     necessary for hardware to work.
296     This is a read-only control that can be read by the application and
297     used as a hint to determine the number of OUTPUT buffers to pass to
299     necessary for hardware to work.
301 .. _v4l2-alpha-component:
305     queue of a mem-to-mem device) produces a frame format that includes
307     :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value
308     is not defined by the device or the mem-to-mem input data this
310     When an output device (or output queue of a mem-to-mem device)
340 .. code-block:: c
382 .. code-block:: c
407 .. code-block:: c
455 .. code-block:: c
463     if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
477 	if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
491 	if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
511    controls. This makes it hard to programmatically set such controls
513    order to resolve this drivers use unique IDs and the
514    ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
515    kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
520    the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so