1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _control: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab************* 654f38fcaSMauro Carvalho ChehabUser Controls 754f38fcaSMauro Carvalho Chehab************* 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabDevices typically have a number of user-settable controls such as 1054f38fcaSMauro Carvalho Chehabbrightness, saturation and so on, which would be presented to the user 1154f38fcaSMauro Carvalho Chehabon a graphical user interface. But, different devices will have 1254f38fcaSMauro Carvalho Chehabdifferent controls available, and furthermore, the range of possible 1354f38fcaSMauro Carvalho Chehabvalues, and the default value will vary from device to device. The 1454f38fcaSMauro Carvalho Chehabcontrol ioctls provide the information and a mechanism to create a nice 1554f38fcaSMauro Carvalho Chehabuser interface for these controls that will work correctly with any 1654f38fcaSMauro Carvalho Chehabdevice. 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho ChehabAll controls are accessed using an ID value. V4L2 defines several IDs 1954f38fcaSMauro Carvalho Chehabfor specific purposes. Drivers can also implement their own custom 2054f38fcaSMauro Carvalho Chehabcontrols using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The 2154f38fcaSMauro Carvalho Chehabpre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in 2254f38fcaSMauro Carvalho Chehab:ref:`control-id`. The ID is used when querying the attributes of a 2354f38fcaSMauro Carvalho Chehabcontrol, and when getting or setting the current value. 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho ChehabGenerally applications should present controls to the user without 2654f38fcaSMauro Carvalho Chehabassumptions about their purpose. Each control comes with a name string 2754f38fcaSMauro Carvalho Chehabthe user is supposed to understand. When the purpose is non-intuitive 2854f38fcaSMauro Carvalho Chehabthe driver writer should provide a user manual, a user interface plug-in 2954f38fcaSMauro Carvalho Chehabor a driver specific panel application. Predefined IDs were introduced 3054f38fcaSMauro Carvalho Chehabto change a few controls programmatically, for example to mute a device 3154f38fcaSMauro Carvalho Chehabduring a channel switch. 3254f38fcaSMauro Carvalho Chehab 3354f38fcaSMauro Carvalho ChehabDrivers may enumerate different controls after switching the current 3454f38fcaSMauro Carvalho Chehabvideo input or output, tuner or modulator, or audio input or output. 3554f38fcaSMauro Carvalho ChehabDifferent in the sense of other bounds, another default and current 3654f38fcaSMauro Carvalho Chehabvalue, step size or other menu items. A control with a certain *custom* 3754f38fcaSMauro Carvalho ChehabID can also change name and type. 3854f38fcaSMauro Carvalho Chehab 3954f38fcaSMauro Carvalho ChehabIf a control is not applicable to the current configuration of the 4054f38fcaSMauro Carvalho Chehabdevice (for example, it doesn't apply to the current video input) 4154f38fcaSMauro Carvalho Chehabdrivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag. 4254f38fcaSMauro Carvalho Chehab 4354f38fcaSMauro Carvalho ChehabControl values are stored globally, they do not change when switching 4454f38fcaSMauro Carvalho Chehabexcept to stay within the reported bounds. They also do not change e. g. 4554f38fcaSMauro Carvalho Chehabwhen the device is opened or closed, when the tuner radio frequency is 4654f38fcaSMauro Carvalho Chehabchanged or generally never without application request. 4754f38fcaSMauro Carvalho Chehab 4854f38fcaSMauro Carvalho ChehabV4L2 specifies an event mechanism to notify applications when controls 4954f38fcaSMauro Carvalho Chehabchange value (see 5054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_SUBSCRIBE_EVENT`, event 5154f38fcaSMauro Carvalho Chehab``V4L2_EVENT_CTRL``), panel applications might want to make use of that 5254f38fcaSMauro Carvalho Chehabin order to always reflect the correct control value. 5354f38fcaSMauro Carvalho Chehab 5454f38fcaSMauro Carvalho ChehabAll controls use machine endianness. 5554f38fcaSMauro Carvalho Chehab 5654f38fcaSMauro Carvalho Chehab 5754f38fcaSMauro Carvalho Chehab.. _control-id: 5854f38fcaSMauro Carvalho Chehab 5954f38fcaSMauro Carvalho ChehabControl IDs 6054f38fcaSMauro Carvalho Chehab=========== 6154f38fcaSMauro Carvalho Chehab 6254f38fcaSMauro Carvalho Chehab``V4L2_CID_BASE`` 6354f38fcaSMauro Carvalho Chehab First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``. 6454f38fcaSMauro Carvalho Chehab 6554f38fcaSMauro Carvalho Chehab``V4L2_CID_USER_BASE`` 6654f38fcaSMauro Carvalho Chehab Synonym of ``V4L2_CID_BASE``. 6754f38fcaSMauro Carvalho Chehab 6854f38fcaSMauro Carvalho Chehab``V4L2_CID_BRIGHTNESS`` ``(integer)`` 6954f38fcaSMauro Carvalho Chehab Picture brightness, or more precisely, the black level. 7054f38fcaSMauro Carvalho Chehab 7154f38fcaSMauro Carvalho Chehab``V4L2_CID_CONTRAST`` ``(integer)`` 7254f38fcaSMauro Carvalho Chehab Picture contrast or luma gain. 7354f38fcaSMauro Carvalho Chehab 7454f38fcaSMauro Carvalho Chehab``V4L2_CID_SATURATION`` ``(integer)`` 7554f38fcaSMauro Carvalho Chehab Picture color saturation or chroma gain. 7654f38fcaSMauro Carvalho Chehab 7754f38fcaSMauro Carvalho Chehab``V4L2_CID_HUE`` ``(integer)`` 7854f38fcaSMauro Carvalho Chehab Hue or color balance. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho Chehab``V4L2_CID_AUDIO_VOLUME`` ``(integer)`` 8154f38fcaSMauro Carvalho Chehab Overall audio volume. Note some drivers also provide an OSS or ALSA 8254f38fcaSMauro Carvalho Chehab mixer interface. 8354f38fcaSMauro Carvalho Chehab 8454f38fcaSMauro Carvalho Chehab``V4L2_CID_AUDIO_BALANCE`` ``(integer)`` 8554f38fcaSMauro Carvalho Chehab Audio stereo balance. Minimum corresponds to all the way left, 8654f38fcaSMauro Carvalho Chehab maximum to right. 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab``V4L2_CID_AUDIO_BASS`` ``(integer)`` 8954f38fcaSMauro Carvalho Chehab Audio bass adjustment. 9054f38fcaSMauro Carvalho Chehab 9154f38fcaSMauro Carvalho Chehab``V4L2_CID_AUDIO_TREBLE`` ``(integer)`` 9254f38fcaSMauro Carvalho Chehab Audio treble adjustment. 9354f38fcaSMauro Carvalho Chehab 9454f38fcaSMauro Carvalho Chehab``V4L2_CID_AUDIO_MUTE`` ``(boolean)`` 9554f38fcaSMauro Carvalho Chehab Mute audio, i. e. set the volume to zero, however without affecting 9654f38fcaSMauro Carvalho Chehab ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute 9754f38fcaSMauro Carvalho Chehab at load time to avoid excessive noise. Actually the entire device 9854f38fcaSMauro Carvalho Chehab should be reset to a low power consumption state. 9954f38fcaSMauro Carvalho Chehab 10054f38fcaSMauro Carvalho Chehab``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)`` 10154f38fcaSMauro Carvalho Chehab Loudness mode (bass boost). 10254f38fcaSMauro Carvalho Chehab 10354f38fcaSMauro Carvalho Chehab``V4L2_CID_BLACK_LEVEL`` ``(integer)`` 10454f38fcaSMauro Carvalho Chehab Another name for brightness (not a synonym of 10554f38fcaSMauro Carvalho Chehab ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not 10654f38fcaSMauro Carvalho Chehab be used in new drivers and applications. 10754f38fcaSMauro Carvalho Chehab 10854f38fcaSMauro Carvalho Chehab``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)`` 10954f38fcaSMauro Carvalho Chehab Automatic white balance (cameras). 11054f38fcaSMauro Carvalho Chehab 11154f38fcaSMauro Carvalho Chehab``V4L2_CID_DO_WHITE_BALANCE`` ``(button)`` 11254f38fcaSMauro Carvalho Chehab This is an action control. When set (the value is ignored), the 11354f38fcaSMauro Carvalho Chehab device will do a white balance and then hold the current setting. 11454f38fcaSMauro Carvalho Chehab Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``, 11554f38fcaSMauro Carvalho Chehab which, when activated, keeps adjusting the white balance. 11654f38fcaSMauro Carvalho Chehab 11754f38fcaSMauro Carvalho Chehab``V4L2_CID_RED_BALANCE`` ``(integer)`` 11854f38fcaSMauro Carvalho Chehab Red chroma balance. 11954f38fcaSMauro Carvalho Chehab 12054f38fcaSMauro Carvalho Chehab``V4L2_CID_BLUE_BALANCE`` ``(integer)`` 12154f38fcaSMauro Carvalho Chehab Blue chroma balance. 12254f38fcaSMauro Carvalho Chehab 12354f38fcaSMauro Carvalho Chehab``V4L2_CID_GAMMA`` ``(integer)`` 12454f38fcaSMauro Carvalho Chehab Gamma adjust. 12554f38fcaSMauro Carvalho Chehab 12654f38fcaSMauro Carvalho Chehab``V4L2_CID_WHITENESS`` ``(integer)`` 12754f38fcaSMauro Carvalho Chehab Whiteness for grey-scale devices. This is a synonym for 12854f38fcaSMauro Carvalho Chehab ``V4L2_CID_GAMMA``. This control is deprecated and should not be 12954f38fcaSMauro Carvalho Chehab used in new drivers and applications. 13054f38fcaSMauro Carvalho Chehab 13154f38fcaSMauro Carvalho Chehab``V4L2_CID_EXPOSURE`` ``(integer)`` 13254f38fcaSMauro Carvalho Chehab Exposure (cameras). [Unit?] 13354f38fcaSMauro Carvalho Chehab 13454f38fcaSMauro Carvalho Chehab``V4L2_CID_AUTOGAIN`` ``(boolean)`` 13554f38fcaSMauro Carvalho Chehab Automatic gain/exposure control. 13654f38fcaSMauro Carvalho Chehab 13754f38fcaSMauro Carvalho Chehab``V4L2_CID_GAIN`` ``(integer)`` 13854f38fcaSMauro Carvalho Chehab Gain control. 13954f38fcaSMauro Carvalho Chehab 14054f38fcaSMauro Carvalho Chehab Primarily used to control gain on e.g. TV tuners but also on 14154f38fcaSMauro Carvalho Chehab webcams. Most devices control only digital gain with this control 14254f38fcaSMauro Carvalho Chehab but on some this could include analogue gain as well. Devices that 14354f38fcaSMauro Carvalho Chehab recognise the difference between digital and analogue gain use 14454f38fcaSMauro Carvalho Chehab controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. 14554f38fcaSMauro Carvalho Chehab 14654f38fcaSMauro Carvalho Chehab``V4L2_CID_HFLIP`` ``(boolean)`` 14754f38fcaSMauro Carvalho Chehab Mirror the picture horizontally. 14854f38fcaSMauro Carvalho Chehab 14954f38fcaSMauro Carvalho Chehab``V4L2_CID_VFLIP`` ``(boolean)`` 15054f38fcaSMauro Carvalho Chehab Mirror the picture vertically. 15154f38fcaSMauro Carvalho Chehab 15254f38fcaSMauro Carvalho Chehab.. _v4l2-power-line-frequency: 15354f38fcaSMauro Carvalho Chehab 15454f38fcaSMauro Carvalho Chehab``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` 15554f38fcaSMauro Carvalho Chehab Enables a power line frequency filter to avoid flicker. Possible 15654f38fcaSMauro Carvalho Chehab values for ``enum v4l2_power_line_frequency`` are: 157a78801a4SMauro Carvalho Chehab 158a78801a4SMauro Carvalho Chehab ========================================== == 159a78801a4SMauro Carvalho Chehab ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0 160a78801a4SMauro Carvalho Chehab ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1 161a78801a4SMauro Carvalho Chehab ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2 162a78801a4SMauro Carvalho Chehab ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3 163a78801a4SMauro Carvalho Chehab ========================================== == 16454f38fcaSMauro Carvalho Chehab 16554f38fcaSMauro Carvalho Chehab``V4L2_CID_HUE_AUTO`` ``(boolean)`` 16654f38fcaSMauro Carvalho Chehab Enables automatic hue control by the device. The effect of setting 16754f38fcaSMauro Carvalho Chehab ``V4L2_CID_HUE`` while automatic hue control is enabled is 16854f38fcaSMauro Carvalho Chehab undefined, drivers should ignore such request. 16954f38fcaSMauro Carvalho Chehab 17054f38fcaSMauro Carvalho Chehab``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)`` 17154f38fcaSMauro Carvalho Chehab This control specifies the white balance settings as a color 17254f38fcaSMauro Carvalho Chehab temperature in Kelvin. A driver should have a minimum of 2800 17354f38fcaSMauro Carvalho Chehab (incandescent) to 6500 (daylight). For more information about color 17454f38fcaSMauro Carvalho Chehab temperature see 17554f38fcaSMauro Carvalho Chehab `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__. 17654f38fcaSMauro Carvalho Chehab 17754f38fcaSMauro Carvalho Chehab``V4L2_CID_SHARPNESS`` ``(integer)`` 17854f38fcaSMauro Carvalho Chehab Adjusts the sharpness filters in a camera. The minimum value 17954f38fcaSMauro Carvalho Chehab disables the filters, higher values give a sharper picture. 18054f38fcaSMauro Carvalho Chehab 18154f38fcaSMauro Carvalho Chehab``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)`` 18254f38fcaSMauro Carvalho Chehab Adjusts the backlight compensation in a camera. The minimum value 18354f38fcaSMauro Carvalho Chehab disables backlight compensation. 18454f38fcaSMauro Carvalho Chehab 18554f38fcaSMauro Carvalho Chehab``V4L2_CID_CHROMA_AGC`` ``(boolean)`` 18654f38fcaSMauro Carvalho Chehab Chroma automatic gain control. 18754f38fcaSMauro Carvalho Chehab 18854f38fcaSMauro Carvalho Chehab``V4L2_CID_CHROMA_GAIN`` ``(integer)`` 18954f38fcaSMauro Carvalho Chehab Adjusts the Chroma gain control (for use when chroma AGC is 19054f38fcaSMauro Carvalho Chehab disabled). 19154f38fcaSMauro Carvalho Chehab 19254f38fcaSMauro Carvalho Chehab``V4L2_CID_COLOR_KILLER`` ``(boolean)`` 19354f38fcaSMauro Carvalho Chehab Enable the color killer (i. e. force a black & white image in case 19454f38fcaSMauro Carvalho Chehab of a weak video signal). 19554f38fcaSMauro Carvalho Chehab 19654f38fcaSMauro Carvalho Chehab.. _v4l2-colorfx: 19754f38fcaSMauro Carvalho Chehab 19854f38fcaSMauro Carvalho Chehab``V4L2_CID_COLORFX`` ``(enum)`` 19954f38fcaSMauro Carvalho Chehab Selects a color effect. The following values are defined: 20054f38fcaSMauro Carvalho Chehab 20154f38fcaSMauro Carvalho Chehab 20254f38fcaSMauro Carvalho Chehab 203fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| 20454f38fcaSMauro Carvalho Chehab 20554f38fcaSMauro Carvalho Chehab.. flat-table:: 20654f38fcaSMauro Carvalho Chehab :header-rows: 0 20754f38fcaSMauro Carvalho Chehab :stub-columns: 0 20854f38fcaSMauro Carvalho Chehab :widths: 11 24 20954f38fcaSMauro Carvalho Chehab 21054f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_NONE`` 21154f38fcaSMauro Carvalho Chehab - Color effect is disabled. 21254f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_ANTIQUE`` 21354f38fcaSMauro Carvalho Chehab - An aging (old photo) effect. 21454f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_ART_FREEZE`` 21554f38fcaSMauro Carvalho Chehab - Frost color effect. 21654f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_AQUA`` 21754f38fcaSMauro Carvalho Chehab - Water color, cool tone. 21854f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_BW`` 21954f38fcaSMauro Carvalho Chehab - Black and white. 22054f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_EMBOSS`` 22154f38fcaSMauro Carvalho Chehab - Emboss, the highlights and shadows replace light/dark boundaries 22254f38fcaSMauro Carvalho Chehab and low contrast areas are set to a gray background. 22354f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_GRASS_GREEN`` 22454f38fcaSMauro Carvalho Chehab - Grass green. 22554f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_NEGATIVE`` 22654f38fcaSMauro Carvalho Chehab - Negative. 22754f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SEPIA`` 22854f38fcaSMauro Carvalho Chehab - Sepia tone. 22954f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SKETCH`` 23054f38fcaSMauro Carvalho Chehab - Sketch. 23154f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SKIN_WHITEN`` 23254f38fcaSMauro Carvalho Chehab - Skin whiten. 23354f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SKY_BLUE`` 23454f38fcaSMauro Carvalho Chehab - Sky blue. 23554f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SOLARIZATION`` 23654f38fcaSMauro Carvalho Chehab - Solarization, the image is partially reversed in tone, only color 23754f38fcaSMauro Carvalho Chehab values above or below a certain threshold are inverted. 23854f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SILHOUETTE`` 23954f38fcaSMauro Carvalho Chehab - Silhouette (outline). 24054f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_VIVID`` 24154f38fcaSMauro Carvalho Chehab - Vivid colors. 24254f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORFX_SET_CBCR`` 24354f38fcaSMauro Carvalho Chehab - The Cb and Cr chroma components are replaced by fixed coefficients 24454f38fcaSMauro Carvalho Chehab determined by ``V4L2_CID_COLORFX_CBCR`` control. 245ef9f18a9SDillon Min * - ``V4L2_COLORFX_SET_RGB`` 246ef9f18a9SDillon Min - The RGB components are replaced by the fixed RGB components determined 247ef9f18a9SDillon Min by ``V4L2_CID_COLORFX_RGB`` control. 24854f38fcaSMauro Carvalho Chehab 24954f38fcaSMauro Carvalho Chehab 250ef9f18a9SDillon Min``V4L2_CID_COLORFX_RGB`` ``(integer)`` 251ef9f18a9SDillon Min Determines the Red, Green, and Blue coefficients for 252ef9f18a9SDillon Min ``V4L2_COLORFX_SET_RGB`` color effect. 253ef9f18a9SDillon Min Bits [7:0] of the supplied 32 bit value are interpreted as Blue component, 254ef9f18a9SDillon Min bits [15:8] as Green component, bits [23:16] as Red component, and 255ef9f18a9SDillon Min bits [31:24] must be zero. 25654f38fcaSMauro Carvalho Chehab 25754f38fcaSMauro Carvalho Chehab``V4L2_CID_COLORFX_CBCR`` ``(integer)`` 25854f38fcaSMauro Carvalho Chehab Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` 25954f38fcaSMauro Carvalho Chehab color effect. Bits [7:0] of the supplied 32 bit value are 26054f38fcaSMauro Carvalho Chehab interpreted as Cr component, bits [15:8] as Cb component and bits 26154f38fcaSMauro Carvalho Chehab [31:16] must be zero. 26254f38fcaSMauro Carvalho Chehab 26354f38fcaSMauro Carvalho Chehab``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)`` 26454f38fcaSMauro Carvalho Chehab Enable Automatic Brightness. 26554f38fcaSMauro Carvalho Chehab 26654f38fcaSMauro Carvalho Chehab``V4L2_CID_ROTATE`` ``(integer)`` 26754f38fcaSMauro Carvalho Chehab Rotates the image by specified angle. Common angles are 90, 270 and 26854f38fcaSMauro Carvalho Chehab 180. Rotating the image to 90 and 270 will reverse the height and 26954f38fcaSMauro Carvalho Chehab width of the display window. It is necessary to set the new height 27054f38fcaSMauro Carvalho Chehab and width of the picture using the 27154f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the 27254f38fcaSMauro Carvalho Chehab rotation angle selected. 27354f38fcaSMauro Carvalho Chehab 27454f38fcaSMauro Carvalho Chehab``V4L2_CID_BG_COLOR`` ``(integer)`` 27554f38fcaSMauro Carvalho Chehab Sets the background color on the current output device. Background 27654f38fcaSMauro Carvalho Chehab color needs to be specified in the RGB24 format. The supplied 32 bit 27754f38fcaSMauro Carvalho Chehab value is interpreted as bits 0-7 Red color information, bits 8-15 27854f38fcaSMauro Carvalho Chehab Green color information, bits 16-23 Blue color information and bits 27954f38fcaSMauro Carvalho Chehab 24-31 must be zero. 28054f38fcaSMauro Carvalho Chehab 28154f38fcaSMauro Carvalho Chehab``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)`` 28254f38fcaSMauro Carvalho Chehab Switch on or off the illuminator 1 or 2 of the device (usually a 28354f38fcaSMauro Carvalho Chehab microscope). 28454f38fcaSMauro Carvalho Chehab 28554f38fcaSMauro Carvalho Chehab``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)`` 28654f38fcaSMauro Carvalho Chehab This is a read-only control that can be read by the application and 28754f38fcaSMauro Carvalho Chehab used as a hint to determine the number of CAPTURE buffers to pass to 28854f38fcaSMauro Carvalho Chehab REQBUFS. The value is the minimum number of CAPTURE buffers that is 28954f38fcaSMauro Carvalho Chehab necessary for hardware to work. 29054f38fcaSMauro Carvalho Chehab 29154f38fcaSMauro Carvalho Chehab``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)`` 29254f38fcaSMauro Carvalho Chehab This is a read-only control that can be read by the application and 29354f38fcaSMauro Carvalho Chehab used as a hint to determine the number of OUTPUT buffers to pass to 29454f38fcaSMauro Carvalho Chehab REQBUFS. The value is the minimum number of OUTPUT buffers that is 29554f38fcaSMauro Carvalho Chehab necessary for hardware to work. 29654f38fcaSMauro Carvalho Chehab 29754f38fcaSMauro Carvalho Chehab.. _v4l2-alpha-component: 29854f38fcaSMauro Carvalho Chehab 29954f38fcaSMauro Carvalho Chehab``V4L2_CID_ALPHA_COMPONENT`` ``(integer)`` 30054f38fcaSMauro Carvalho Chehab Sets the alpha color component. When a capture device (or capture 30154f38fcaSMauro Carvalho Chehab queue of a mem-to-mem device) produces a frame format that includes 30254f38fcaSMauro Carvalho Chehab an alpha component (e.g. 30354f38fcaSMauro Carvalho Chehab :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value 30454f38fcaSMauro Carvalho Chehab is not defined by the device or the mem-to-mem input data this 30554f38fcaSMauro Carvalho Chehab control lets you select the alpha component value of all pixels. 30654f38fcaSMauro Carvalho Chehab When an output device (or output queue of a mem-to-mem device) 30754f38fcaSMauro Carvalho Chehab consumes a frame format that doesn't include an alpha component and 30854f38fcaSMauro Carvalho Chehab the device supports alpha channel processing this control lets you 30954f38fcaSMauro Carvalho Chehab set the alpha component value of all pixels for further processing 31054f38fcaSMauro Carvalho Chehab in the device. 31154f38fcaSMauro Carvalho Chehab 31254f38fcaSMauro Carvalho Chehab``V4L2_CID_LASTP1`` 31354f38fcaSMauro Carvalho Chehab End of the predefined control IDs (currently 31454f38fcaSMauro Carvalho Chehab ``V4L2_CID_ALPHA_COMPONENT`` + 1). 31554f38fcaSMauro Carvalho Chehab 31654f38fcaSMauro Carvalho Chehab``V4L2_CID_PRIVATE_BASE`` 31754f38fcaSMauro Carvalho Chehab ID of the first custom (driver specific) control. Applications 31854f38fcaSMauro Carvalho Chehab depending on particular custom controls should check the driver name 31954f38fcaSMauro Carvalho Chehab and version, see :ref:`querycap`. 32054f38fcaSMauro Carvalho Chehab 32154f38fcaSMauro Carvalho ChehabApplications can enumerate the available controls with the 32254f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCTRL` and 32354f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a 32454f38fcaSMauro Carvalho Chehabcontrol value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and 32554f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement 32654f38fcaSMauro Carvalho Chehab``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the 32754f38fcaSMauro Carvalho Chehabdevice has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or 32854f38fcaSMauro Carvalho Chehabmore menu type controls. 32954f38fcaSMauro Carvalho Chehab 33054f38fcaSMauro Carvalho Chehab 33154f38fcaSMauro Carvalho Chehab.. _enum_all_controls: 33254f38fcaSMauro Carvalho Chehab 33354f38fcaSMauro Carvalho ChehabExample: Enumerating all controls 33454f38fcaSMauro Carvalho Chehab================================= 33554f38fcaSMauro Carvalho Chehab 33654f38fcaSMauro Carvalho Chehab.. code-block:: c 33754f38fcaSMauro Carvalho Chehab 33854f38fcaSMauro Carvalho Chehab struct v4l2_queryctrl queryctrl; 33954f38fcaSMauro Carvalho Chehab struct v4l2_querymenu querymenu; 34054f38fcaSMauro Carvalho Chehab 34154f38fcaSMauro Carvalho Chehab static void enumerate_menu(__u32 id) 34254f38fcaSMauro Carvalho Chehab { 34354f38fcaSMauro Carvalho Chehab printf(" Menu items:\\n"); 34454f38fcaSMauro Carvalho Chehab 34554f38fcaSMauro Carvalho Chehab memset(&querymenu, 0, sizeof(querymenu)); 34654f38fcaSMauro Carvalho Chehab querymenu.id = id; 34754f38fcaSMauro Carvalho Chehab 34854f38fcaSMauro Carvalho Chehab for (querymenu.index = queryctrl.minimum; 34954f38fcaSMauro Carvalho Chehab querymenu.index <= queryctrl.maximum; 35054f38fcaSMauro Carvalho Chehab querymenu.index++) { 35154f38fcaSMauro Carvalho Chehab if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) { 35254f38fcaSMauro Carvalho Chehab printf(" %s\\n", querymenu.name); 35354f38fcaSMauro Carvalho Chehab } 35454f38fcaSMauro Carvalho Chehab } 35554f38fcaSMauro Carvalho Chehab } 35654f38fcaSMauro Carvalho Chehab 35754f38fcaSMauro Carvalho Chehab memset(&queryctrl, 0, sizeof(queryctrl)); 35854f38fcaSMauro Carvalho Chehab 35954f38fcaSMauro Carvalho Chehab queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; 36054f38fcaSMauro Carvalho Chehab while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { 36154f38fcaSMauro Carvalho Chehab if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { 36254f38fcaSMauro Carvalho Chehab printf("Control %s\\n", queryctrl.name); 36354f38fcaSMauro Carvalho Chehab 36454f38fcaSMauro Carvalho Chehab if (queryctrl.type == V4L2_CTRL_TYPE_MENU) 36554f38fcaSMauro Carvalho Chehab enumerate_menu(queryctrl.id); 36654f38fcaSMauro Carvalho Chehab } 36754f38fcaSMauro Carvalho Chehab 36854f38fcaSMauro Carvalho Chehab queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; 36954f38fcaSMauro Carvalho Chehab } 37054f38fcaSMauro Carvalho Chehab if (errno != EINVAL) { 37154f38fcaSMauro Carvalho Chehab perror("VIDIOC_QUERYCTRL"); 37254f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 37354f38fcaSMauro Carvalho Chehab } 37454f38fcaSMauro Carvalho Chehab 37554f38fcaSMauro Carvalho ChehabExample: Enumerating all controls including compound controls 37654f38fcaSMauro Carvalho Chehab============================================================= 37754f38fcaSMauro Carvalho Chehab 37854f38fcaSMauro Carvalho Chehab.. code-block:: c 37954f38fcaSMauro Carvalho Chehab 38054f38fcaSMauro Carvalho Chehab struct v4l2_query_ext_ctrl query_ext_ctrl; 38154f38fcaSMauro Carvalho Chehab 38254f38fcaSMauro Carvalho Chehab memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl)); 38354f38fcaSMauro Carvalho Chehab 38454f38fcaSMauro Carvalho Chehab query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; 38554f38fcaSMauro Carvalho Chehab while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) { 38654f38fcaSMauro Carvalho Chehab if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { 38754f38fcaSMauro Carvalho Chehab printf("Control %s\\n", query_ext_ctrl.name); 38854f38fcaSMauro Carvalho Chehab 38954f38fcaSMauro Carvalho Chehab if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU) 39054f38fcaSMauro Carvalho Chehab enumerate_menu(query_ext_ctrl.id); 39154f38fcaSMauro Carvalho Chehab } 39254f38fcaSMauro Carvalho Chehab 39354f38fcaSMauro Carvalho Chehab query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; 39454f38fcaSMauro Carvalho Chehab } 39554f38fcaSMauro Carvalho Chehab if (errno != EINVAL) { 39654f38fcaSMauro Carvalho Chehab perror("VIDIOC_QUERY_EXT_CTRL"); 39754f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 39854f38fcaSMauro Carvalho Chehab } 39954f38fcaSMauro Carvalho Chehab 40054f38fcaSMauro Carvalho ChehabExample: Enumerating all user controls (old style) 40154f38fcaSMauro Carvalho Chehab================================================== 40254f38fcaSMauro Carvalho Chehab 40354f38fcaSMauro Carvalho Chehab.. code-block:: c 40454f38fcaSMauro Carvalho Chehab 40554f38fcaSMauro Carvalho Chehab 40654f38fcaSMauro Carvalho Chehab memset(&queryctrl, 0, sizeof(queryctrl)); 40754f38fcaSMauro Carvalho Chehab 40854f38fcaSMauro Carvalho Chehab for (queryctrl.id = V4L2_CID_BASE; 40954f38fcaSMauro Carvalho Chehab queryctrl.id < V4L2_CID_LASTP1; 41054f38fcaSMauro Carvalho Chehab queryctrl.id++) { 41154f38fcaSMauro Carvalho Chehab if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { 41254f38fcaSMauro Carvalho Chehab if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) 41354f38fcaSMauro Carvalho Chehab continue; 41454f38fcaSMauro Carvalho Chehab 41554f38fcaSMauro Carvalho Chehab printf("Control %s\\n", queryctrl.name); 41654f38fcaSMauro Carvalho Chehab 41754f38fcaSMauro Carvalho Chehab if (queryctrl.type == V4L2_CTRL_TYPE_MENU) 41854f38fcaSMauro Carvalho Chehab enumerate_menu(queryctrl.id); 41954f38fcaSMauro Carvalho Chehab } else { 42054f38fcaSMauro Carvalho Chehab if (errno == EINVAL) 42154f38fcaSMauro Carvalho Chehab continue; 42254f38fcaSMauro Carvalho Chehab 42354f38fcaSMauro Carvalho Chehab perror("VIDIOC_QUERYCTRL"); 42454f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 42554f38fcaSMauro Carvalho Chehab } 42654f38fcaSMauro Carvalho Chehab } 42754f38fcaSMauro Carvalho Chehab 42854f38fcaSMauro Carvalho Chehab for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; 42954f38fcaSMauro Carvalho Chehab queryctrl.id++) { 43054f38fcaSMauro Carvalho Chehab if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { 43154f38fcaSMauro Carvalho Chehab if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) 43254f38fcaSMauro Carvalho Chehab continue; 43354f38fcaSMauro Carvalho Chehab 43454f38fcaSMauro Carvalho Chehab printf("Control %s\\n", queryctrl.name); 43554f38fcaSMauro Carvalho Chehab 43654f38fcaSMauro Carvalho Chehab if (queryctrl.type == V4L2_CTRL_TYPE_MENU) 43754f38fcaSMauro Carvalho Chehab enumerate_menu(queryctrl.id); 43854f38fcaSMauro Carvalho Chehab } else { 43954f38fcaSMauro Carvalho Chehab if (errno == EINVAL) 44054f38fcaSMauro Carvalho Chehab break; 44154f38fcaSMauro Carvalho Chehab 44254f38fcaSMauro Carvalho Chehab perror("VIDIOC_QUERYCTRL"); 44354f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 44454f38fcaSMauro Carvalho Chehab } 44554f38fcaSMauro Carvalho Chehab } 44654f38fcaSMauro Carvalho Chehab 44754f38fcaSMauro Carvalho Chehab 44854f38fcaSMauro Carvalho ChehabExample: Changing controls 44954f38fcaSMauro Carvalho Chehab========================== 45054f38fcaSMauro Carvalho Chehab 45154f38fcaSMauro Carvalho Chehab.. code-block:: c 45254f38fcaSMauro Carvalho Chehab 45354f38fcaSMauro Carvalho Chehab struct v4l2_queryctrl queryctrl; 45454f38fcaSMauro Carvalho Chehab struct v4l2_control control; 45554f38fcaSMauro Carvalho Chehab 45654f38fcaSMauro Carvalho Chehab memset(&queryctrl, 0, sizeof(queryctrl)); 45754f38fcaSMauro Carvalho Chehab queryctrl.id = V4L2_CID_BRIGHTNESS; 45854f38fcaSMauro Carvalho Chehab 45954f38fcaSMauro Carvalho Chehab if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { 46054f38fcaSMauro Carvalho Chehab if (errno != EINVAL) { 46154f38fcaSMauro Carvalho Chehab perror("VIDIOC_QUERYCTRL"); 46254f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 46354f38fcaSMauro Carvalho Chehab } else { 464*6811c98cSMarek Vasut printf("V4L2_CID_BRIGHTNESS is not supported\n"); 46554f38fcaSMauro Carvalho Chehab } 46654f38fcaSMauro Carvalho Chehab } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { 467*6811c98cSMarek Vasut printf("V4L2_CID_BRIGHTNESS is not supported\n"); 46854f38fcaSMauro Carvalho Chehab } else { 46954f38fcaSMauro Carvalho Chehab memset(&control, 0, sizeof (control)); 47054f38fcaSMauro Carvalho Chehab control.id = V4L2_CID_BRIGHTNESS; 47154f38fcaSMauro Carvalho Chehab control.value = queryctrl.default_value; 47254f38fcaSMauro Carvalho Chehab 47354f38fcaSMauro Carvalho Chehab if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) { 47454f38fcaSMauro Carvalho Chehab perror("VIDIOC_S_CTRL"); 47554f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 47654f38fcaSMauro Carvalho Chehab } 47754f38fcaSMauro Carvalho Chehab } 47854f38fcaSMauro Carvalho Chehab 47954f38fcaSMauro Carvalho Chehab memset(&control, 0, sizeof(control)); 48054f38fcaSMauro Carvalho Chehab control.id = V4L2_CID_CONTRAST; 48154f38fcaSMauro Carvalho Chehab 48254f38fcaSMauro Carvalho Chehab if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) { 48354f38fcaSMauro Carvalho Chehab control.value += 1; 48454f38fcaSMauro Carvalho Chehab 48554f38fcaSMauro Carvalho Chehab /* The driver may clamp the value or return ERANGE, ignored here */ 48654f38fcaSMauro Carvalho Chehab 48754f38fcaSMauro Carvalho Chehab if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control) 48854f38fcaSMauro Carvalho Chehab && errno != ERANGE) { 48954f38fcaSMauro Carvalho Chehab perror("VIDIOC_S_CTRL"); 49054f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 49154f38fcaSMauro Carvalho Chehab } 49254f38fcaSMauro Carvalho Chehab /* Ignore if V4L2_CID_CONTRAST is unsupported */ 49354f38fcaSMauro Carvalho Chehab } else if (errno != EINVAL) { 49454f38fcaSMauro Carvalho Chehab perror("VIDIOC_G_CTRL"); 49554f38fcaSMauro Carvalho Chehab exit(EXIT_FAILURE); 49654f38fcaSMauro Carvalho Chehab } 49754f38fcaSMauro Carvalho Chehab 49854f38fcaSMauro Carvalho Chehab control.id = V4L2_CID_AUDIO_MUTE; 49954f38fcaSMauro Carvalho Chehab control.value = 1; /* silence */ 50054f38fcaSMauro Carvalho Chehab 50154f38fcaSMauro Carvalho Chehab /* Errors ignored */ 50254f38fcaSMauro Carvalho Chehab ioctl(fd, VIDIOC_S_CTRL, &control); 50354f38fcaSMauro Carvalho Chehab 50454f38fcaSMauro Carvalho Chehab.. [#f1] 50554f38fcaSMauro Carvalho Chehab The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different 50654f38fcaSMauro Carvalho Chehab drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different 50754f38fcaSMauro Carvalho Chehab controls. This makes it hard to programmatically set such controls 50854f38fcaSMauro Carvalho Chehab since the meaning of the control with that ID is driver dependent. In 50954f38fcaSMauro Carvalho Chehab order to resolve this drivers use unique IDs and the 51054f38fcaSMauro Carvalho Chehab ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the 51154f38fcaSMauro Carvalho Chehab kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to 51254f38fcaSMauro Carvalho Chehab the real IDs. 51354f38fcaSMauro Carvalho Chehab 51454f38fcaSMauro Carvalho Chehab Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs 51554f38fcaSMauro Carvalho Chehab instead of using :ref:`VIDIOC_QUERYCTRL` with 51654f38fcaSMauro Carvalho Chehab the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so 51754f38fcaSMauro Carvalho Chehab support for ``V4L2_CID_PRIVATE_BASE`` is still around. 518