![](https://csdnimg.cn/release/download_crawler_static/9242557/bg14.jpg)
Chapter 1. Common API Elements
1.8. User Controls
Devices typically have a number of user-settable controls such as brightness, saturation and so on,
which would be presented to the user on a graphical user interface. But, different devices will have
different controls available, and furthermore, the range of possible values, and the default value will
vary from device to device. The control ioctls provide the information and a mechanism to create a
nice user interface for these controls that will work correctly with any device.
All controls are accessed using an ID value. V4L2 defines several IDs for specific purposes. Drivers
can also implement their own custom controls using V4L2_CID_PRIVATE_BASE and higher values.
The pre-defined control IDs have the prefix V4L2_CID_, and are listed in Table 1-1. The ID is used
when querying the attributes of a control, and when getting or setting the current value.
Generally applications should present controls to the user without assumptions about their purpose.
Each control comes with a name string the user is supposed to understand. When the purpose is
non-intuitive the driver writer should provide a user manual, a user interface plug-in or a driver
specific panel application. Predefined IDs were introduced to change a few controls
programmatically, for example to mute a device during a channel switch.
Drivers may enumerate different controls after switching the current video input or output, tuner or
modulator, or audio input or output. Different in the sense of other bounds, another default and
current value, step size or other menu items. A control with a certain custom ID can also change
name and type.
9
Control values are stored globally, they do not change when switching except to stay
within the reported bounds. They also do not change e. g. when the device is opened or closed, when
the tuner radio frequency is changed or generally never without application request. Since V4L2
specifies no event mechanism, panel applications intended to cooperate with other panel applications
(be they built into a larger application, as a TV viewer) may need to regularly poll control values to
update their user interface.
10
Table 1-1. Control IDs
ID Type Description
V4L2_CID_BASE First predefined ID, equal to
V4L2_CID_BRIGHTNESS.
V4L2_CID_USER_BASE Synonym of V4L2_CID_BASE.
V4L2_CID_BRIGHTNESS integer Picture brightness, or more precisely, the black
level.
V4L2_CID_CONTRAST integer Picture contrast or luma gain.
V4L2_CID_SATURATION integer Picture color saturation or chroma gain.
V4L2_CID_HUE integer Hue or color balance.
V4L2_CID_AUDIO_VOLUME integer Overall audio volume. Note some drivers also
provide an OSS or ALSA mixer interface.
V4L2_CID_AUDIO_BALANCE integer Audio stereo balance. Minimum corresponds to
all the way left, maximum to right.
V4L2_CID_AUDIO_BASS integer Audio bass adjustment.
V4L2_CID_AUDIO_TREBLE integer Audio treble adjustment.
V4L2_CID_AUDIO_MUTE boolean Mute audio, i. e. set the volume to zero, however
without affecting V4L2_CID_AUDIO_VOLUME.
Like ALSA drivers, V4L2 drivers must mute at
load time to avoid excessive noise. Actually the
entire device should be reset to a low power
consumption state.
10