Linux媒体子系统编程指南：V4L2与数字电视API

需积分: 15 183 浏览量更新于2024-07-17 收藏 7.32MB PDF 举报

"该文档是Linux TV网站提供的关于在Linux环境下进行媒体编程的规范，主要涉及Video for Linux 2 (v4l2)接口和其他相关的音视频输入源操作。文档内容包括用户空间API、内核内部API以及Linux Digital TV驱动的具体文档，提供了详细的目录结构，方便查阅。" 在Linux系统中，媒体编程规范是一个重要的领域，尤其对于开发音视频应用的程序员来说，理解和掌握v4l2等接口是必不可少的。这份文档详细介绍了以下几个关键知识点： 1. **Linux Media Infrastructure 用户空间API**： - 包括Video for Linux 2 (v4l2) API，它是Linux下处理视频捕获和输出的主要接口，提供了对硬件设备如摄像头、电视卡等的操作。 - Digital TV API，用于处理数字电视信号的接收和解码。 - Remote Controller API，用于与遥控器等远程控制设备交互。 - Media Controller API，用于管理媒体设备间的连接和数据流。 - Consumer Electronics Control (CEC) API，用于家庭娱乐设备之间的通信。 2. **Media子系统内核内部API**： - Video4Linux设备和DigitalTV(DVB)设备的处理方式。 - RemoteController设备的处理。 - MediaController设备的实现细节。 - Consumer Electronics Control (CEC)内核支持。 - MIPICSI-2接口的描述，用于高清视频传输。 3. **Linux Digital TV 驱动特定文档**： - 引入了Linux TV驱动的基本概念和工作原理。 - 提供了如何在Linux下配置Avermedia DVB-T设备的指导。 - bt8xx系列卡的使用指南。 - 列出了由linuxtv.org的DVB驱动支持的硬件设备。 - Digital TV Conditional Access Interface (CIAPI)的介绍，用于数字电视的加密内容访问。 - dvb-usb框架的设计理念，它简化了USB数字电视设备的驱动开发。 - 常见问题解答(FAQ)提供了遇到问题时的解决方案。 - lmedm04卡和Opera设备的固件文件信息。这份文档不仅涵盖了基础的API使用，还深入到特定设备的驱动实现和调试，是开发者在Linux下进行媒体编程的强大参考资料。通过学习这份文档，开发者可以更好地理解如何利用v4l2等接口进行音视频设备的控制，实现如捕获、编码、播放等功能，同时也能掌握如何处理数字电视信号和遥控器等设备的交互。

Linux Media Subsystem Documentation, Release

fprintf(stderr, "Oops. B/G PAL is not supported.\\n");

exit(EXIT_FAILURE);

}

/* Note this is also supposed to work when only B

or G/PAL is supported. */

std_id = V4L2_STD_PAL_BG;

if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {

perror("VIDIOC_S_STD");

exit(EXIT_FAILURE);

}

Digital Video (DV) Timings

The video standards discussed so far have been dealing with Analog TV and the corresponding

video timings. Today there are many more diﬀerent hardware interfaces such as High Deﬁnition

TV interfaces (HDMI), VGA, DVI connectors etc., that carry video signals and there is a need to

extend the API to select the video timings for these interfaces. Since it is not possible to extend

the v4l2_std_id due to the limited bits available, a new set of ioctls was added to set/get video

timings at the input and output.

These ioctls deal with the detailed digital video timings that deﬁne each video format. This

includes parameters such as the active video width and height, signal polarities, frontporches,

backporches, sync widths etc. The linux/v4l2-dv-timings.h header can be used to get the

timings of the formats in the CEA-861-E and VESA DMT standards.

To enumerate and query the attributes of the DV timings supported by a device applications

use the ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS and ioctl

VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctls. To set DV timings for

the device applications use the VIDIOC_S_DV_TIMINGS ioctl and to get current DV timings

they use the VIDIOC_G_DV_TIMINGS ioctl. To detect the DV timings as seen by the video

receiver applications use the ioctl VIDIOC_QUERY_DV_TIMINGS ioctl.

Applications can make use of the Input capabilities and Output capabilities ﬂags to determine

whether the digital video ioctls can be used with the given input or output.

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, diﬀerent devices

will have diﬀerent 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 deﬁnes several IDs for speciﬁc purposes.

Drivers can also implement their own custom controls using V4L2_CID_PRIVATE_BASE

and

The use of V4L2_CID_PRIVATE_BASE is problematic because diﬀerent drivers may use the same

V4L2_CID_PRIVATE_BASE ID for diﬀerent controls. This makes it hard to programatically set such controls since

the meaning of the control with that ID is driver dependent. In order to resolve this drivers use unique IDs and the

12 Chapter 1. Linux Media Infrastructure userspace API

Linux Media Subsystem Documentation, Release

higher values. The pre-deﬁned control IDs have the preﬁx V4L2_CID_, and are listed in Control

IDs . 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 speciﬁc panel application. Predeﬁned IDs were introduced to change a few controls

programmatically, for example to mute a device during a channel switch.

Drivers may enumerate diﬀerent controls after switching the current video input or output,

tuner or modulator, or audio input or output. Diﬀerent 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.

If a control is not applicable to the current conﬁguration of the device (for example, it doesn’t

apply to the current video input) drivers set the V4L2_CTRL_FLAG_INACTIVE ﬂag.

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.

V4L2 speciﬁes an event mechanism to notify applications when controls change value (see

ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT , event V4L2_EVENT_CTRL),

panel applications might want to make use of that in order to always reﬂect the correct control

value.

All controls use machine endianness.

Control IDs

V4L2_CID_BASE First predeﬁned 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_PRIVATE_BASE IDs are mapped to those unique IDs by the kernel. Consider these V4L2_CID_PRIVATE_BASE

IDs as aliases to the real IDs.

Many applications today still use the V4L2_CID_PRIVATE_BASE IDs instead of using ioctls VIDIOC_QUERYCTRL,

VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU with the V4L2_CTRL_FLAG_NEXT_CTRL ﬂag to enumerate all

IDs, so support for V4L2_CID_PRIVATE_BASE is still around.

1.2. Part I - Video for Linux API 13

Linux Media Subsystem Documentation, Release

V4L2_CID_AUDIO_MUTE (boolean) Mute audio, i. e. set the volume to zero, however without

aﬀecting 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.

V4L2_CID_AUDIO_LOUDNESS (boolean) Loudness mode (bass boost).

V4L2_CID_BLACK_LEVEL (integer) Another name for brightness (not a synonym of

V4L2_CID_BRIGHTNESS). This control is deprecated and should not be used in new

drivers and applications.

V4L2_CID_AUTO_WHITE_BALANCE (boolean) Automatic white balance (cameras).

V4L2_CID_DO_WHITE_BALANCE (button) This is an action control. When set (the value is ig-

nored), the device will do a white balance and then hold the current setting. Contrast this

with the boolean V4L2_CID_AUTO_WHITE_BALANCE, which, when activated, keeps adjusting

the white balance.

V4L2_CID_RED_BALANCE (integer) Red chroma balance.

V4L2_CID_BLUE_BALANCE (integer) Blue chroma balance.

V4L2_CID_GAMMA (integer) Gamma adjust.

V4L2_CID_WHITENESS (integer) Whiteness for grey-scale devices. This is a synonym for

V4L2_CID_GAMMA. This control is deprecated and should not be used in new drivers and

applications.

V4L2_CID_EXPOSURE (integer) Exposure (cameras). [Unit?]

V4L2_CID_AUTOGAIN (boolean) Automatic gain/exposure control.

V4L2_CID_GAIN (integer) Gain control.

Primarily used to control gain on e.g. TV tuners but also on webcams. Most devices

control only digital gain with this control but on some this could include analogue gain as

well. Devices that recognise the diﬀerence between digital and analogue gain use controls

V4L2_CID_DIGITAL_GAIN and V4L2_CID_ANALOGUE_GAIN.

V4L2_CID_HFLIP (boolean) Mirror the picture horizontally.

V4L2_CID_VFLIP (boolean) Mirror the picture vertically.

V4L2_CID_POWER_LINE_FREQUENCY (enum) Enables a power line fre-

quency ﬁlter to avoid ﬂicker. Possible values for enum

v4l2_power_line_frequency are: V4L2_CID_POWER_LINE_FREQUENCY_DISABLED (0),

V4L2_CID_POWER_LINE_FREQUENCY_50HZ (1), V4L2_CID_POWER_LINE_FREQUENCY_60HZ (2)

and V4L2_CID_POWER_LINE_FREQUENCY_AUTO (3).

V4L2_CID_HUE_AUTO (boolean) Enables automatic hue control by the device. The eﬀect of set-

ting V4L2_CID_HUE while automatic hue control is enabled is undeﬁned, drivers should

ignore such request.

V4L2_CID_WHITE_BALANCE_TEMPERATURE (integer) This control speciﬁes the white balance

settings as a color temperature in Kelvin. A driver should have a minimum of 2800 (incan-

descent) to 6500 (daylight). For more information about color temperature see Wikipedia.

V4L2_CID_SHARPNESS (integer) Adjusts the sharpness ﬁlters in a camera. The minimum value

disables the ﬁlters, higher values give a sharper picture.

14 Chapter 1. Linux Media Infrastructure userspace API

Linux Media Subsystem Documentation, Release

V4L2_CID_BACKLIGHT_COMPENSATION (integer) Adjusts the backlight compensation in a cam-

era. The minimum value disables backlight compensation.

V4L2_CID_CHROMA_AGC (boolean) Chroma automatic gain control.

V4L2_CID_CHROMA_GAIN (integer) Adjusts the Chroma gain control (for use when chroma AGC

is disabled).

V4L2_CID_COLOR_KILLER (boolean) Enable the color killer (i. e. force a black & white image

in case of a weak video signal).

V4L2_CID_COLORFX (enum) Selects a color eﬀect. The following values are deﬁned:

V4L2_COLORFX_NONE Color eﬀect is disabled.

V4L2_COLORFX_ANTIQUE An aging (old photo) eﬀect.

V4L2_COLORFX_ART_FREEZE Frost color eﬀect.

V4L2_COLORFX_AQUA Water color, cool tone.

V4L2_COLORFX_BW Black and white.

V4L2_COLORFX_EMBOSS Emboss, the highlights and shadows replace light/dark bound-

aries and low contrast areas are set to a gray background.

V4L2_COLORFX_GRASS_GREEN Grass green.

V4L2_COLORFX_NEGATIVE Negative.

V4L2_COLORFX_SEPIA Sepia tone.

V4L2_COLORFX_SKETCH Sketch.

V4L2_COLORFX_SKIN_WHITEN Skin whiten.

V4L2_COLORFX_SKY_BLUE Sky blue.

V4L2_COLORFX_SOLARIZATION Solarization, the image is partially reversed in tone, only color

values above or below a certain threshold are inverted.

V4L2_COLORFX_SILHOUETTE Silhouette (outline).

V4L2_COLORFX_VIVID Vivid colors.

V4L2_COLORFX_SET_CBCR The Cb and Cr chroma components are replaced by ﬁxed co-

eﬀicients determined by V4L2_CID_COLORFX_CBCR control.

V4L2_CID_COLORFX_CBCR (integer) Determines the Cb and Cr coeﬀicients for

V4L2_COLORFX_SET_CBCR color eﬀect. Bits [7:0] of the supplied 32 bit value are in-

terpreted as Cr component, bits [15:8] as Cb component and bits [31:16] must be

zero.

V4L2_CID_AUTOBRIGHTNESS (boolean) Enable Automatic Brightness.

V4L2_CID_ROTATE (integer) Rotates the image by speciﬁed angle. Common angles are 90,

270 and 180. Rotating the image to 90 and 270 will reverse the height and width of the

display window. It is necessary to set the new height and width of the picture using the

VIDIOC_S_FMT ioctl according to the rotation angle selected.

V4L2_CID_BG_COLOR (integer) Sets the background color on the current output device. Back-

ground color needs to be speciﬁed in the RGB24 format. The supplied 32 bit value is

interpreted as bits 0-7 Red color information, bits 8-15 Green color information, bits 16-23

Blue color information and bits 24-31 must be zero.

V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2 (boolean) Switch on or oﬀ the illumi-

nator 1 or 2 of the device (usually a microscope).

V4L2_CID_MIN_BUFFERS_FOR_CAPTURE (integer) This is a read-only control that can be read

by the application and used as a hint to determine the number of CAPTURE buﬀers to pass

to REQBUFS. The value is the minimum number of CAPTURE buﬀers that is necessary for

1.2. Part I - Video for Linux API 15

Linux Media Subsystem Documentation, Release

hardware to work.

V4L2_CID_MIN_BUFFERS_FOR_OUTPUT (integer) This is a read-only control that can be read by

the application and used as a hint to determine the number of OUTPUT buﬀers to pass

to REQBUFS. The value is the minimum number of OUTPUT buﬀers that is necessary for

hardware to work.

V4L2_CID_ALPHA_COMPONENT (integer) Sets the alpha color component. When a capture de-

vice (or capture queue of a mem-to-mem device) produces a frame format that includes an

alpha component (e.g. packed RGB image formats ) and the alpha value is not deﬁned by

the device or the mem-to-mem input data this control lets you select the alpha component

value of all pixels. When an output device (or output queue of a mem-to-mem device) con-

sumes a frame format that doesn’t include an alpha component and the device supports

alpha channel processing this control lets you set the alpha component value of all pixels

for further processing in the device.

V4L2_CID_LASTP1 End of the predeﬁned control IDs (currently V4L2_CID_ALPHA_COMPONENT +

1).

V4L2_CID_PRIVATE_BASE ID of the ﬁrst custom (driver speciﬁc) control. Applications depend-

ing on particular custom controls should check the driver name and version, see Querying

Capabilities .

Applications can enumerate the available controls with the ioctls VIDIOC_QUERYCTRL, VID-

IOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU and VIDIOC_QUERYMENU ioctls, get

and set a control value with the VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls. Drivers must

implement VIDIOC_QUERYCTRL, VIDIOC_G_CTRL and VIDIOC_S_CTRL when the device has one or

more controls, VIDIOC_QUERYMENU when it has one or more menu type controls.

Example: Enumerating all controls

struct v4l2_queryctrl queryctrl;

struct v4l2_querymenu querymenu;

static void enumerate_menu(__u32 id)

{

printf(" Menu items:\\n");

memset(&querymenu, 0, sizeof(querymenu));

querymenu.id = id;

for (querymenu.index = queryctrl.minimum;

querymenu.index <= queryctrl.maximum;

querymenu.index++) {

if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {

printf(" %s\\n", querymenu.name);

}

memset(&queryctrl, 0, sizeof(queryctrl));

queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;

while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {

if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {

16 Chapter 1. Linux Media Infrastructure userspace API

剩余1386页未读，继续阅读

潮颜

粉丝: 1
资源: 10

Linux媒体子系统编程指南：V4L2与数字电视API

linux-v4l2完整源代码

Linux 下 v4l2 和 Qt 连接usb摄像头

Linux内核编码规范(中文)

V4L2编程规范

Linux下V4L2编程小结.

Linux视频编程必备：V4L2 API详解与实例

Linux下V4L2 API中文规范

Linux视频开发标准：V4L2 API详解

linux v4l2 spec ch

Linux V4L2驱动详解

最新资源