Linux TV VideoforLinux Two API 规范（2.6.32版）

需积分: 12 23 浏览量更新于2024-07-10 收藏 1.3MB PDF 举报

"Video for Linux Two API Specification.pdf" 是一份关于Linux系统下Video for Linux Two (V4L2) API的详细规范文档，由多个贡献者共同编写和更新，最新的版本是基于2009年的2.6.32内核。该文档主要涵盖了V4L2 API的设计、功能以及相关的ioctl控制接口。 V4L2（Video for Linux Two）是Linux内核中的一个框架，用于支持视频捕获、视频输出、视频编码解码等多媒体设备的驱动程序接口。这个API是对早期Video for Linux (V4L) API的扩展和改进，提供了更强大的功能和更灵活的接口设计。文档中的关键知识点包括： 1. **ioctl控制接口**：V4L2 API使用ioctl调用来与驱动进行通信，控制设备的各种操作，如设置视频格式、获取设备状态、配置捕获参数等。例如，`VIDIOC_LOG_STATUS`用于获取设备的调试信息，`VIDIOC_ENUM_FRAMESIZES`用于枚举设备支持的帧大小，`VIDIOC_ENUM_FRAMEINTERVALS`用于列举可能的帧间隔。 2. **sliced VBI API**：sliced Vertical Blanking Interval (VBI) API允许用户在视频帧的垂直消隐期间传输辅助数据，如Teletext或EIT（电子节目指南）。Hans Verkuil设计并文档化了这部分内容。 3. **MPEG流嵌入的sliced VBI数据格式**：Andy Walls详细描述了如何在MPEG流中嵌入sliced VBI数据，这有助于在数字电视信号中传输附加信息。 4. **libv4l库**：Mauro Carvalho Chehab文档化了libv4l库，这是一个用户空间库，它提供了一个简单的接口，将V4L2 API的复杂性隐藏起来，使得应用程序更容易与V4L2设备交互。 5. **v4l2grab示例**：Mauro Carvalho Chehab还设计并添加了v4l2grab示例，这是一个简单的V4L2捕获程序，可以帮助开发者理解如何使用V4L2 API来捕获视频。 6. **远程控制器章节**：文档中可能包含有关如何处理和支持远程控制器的详细信息，这对于开发与硬件遥控器配合使用的多媒体应用至关重要。 V4L2 API是Linux系统中多媒体处理的核心部分，为开发者提供了丰富的工具来处理视频输入输出、编码解码和相关设备的控制。这份文档对于理解和开发与视频设备相关的Linux应用程序非常有价值。

2021/5/7 Video for Linux Two API Specification

https://www.linuxtv.org/downloads/legacy/video4linux/API/V4L2_API/spec-single/v4l2.html#id2710266 16/137

ID Type Description

V4L2_CID_LASTP1

End of the predefined control IDs (currently V4L2_CID_COLORFX + 1).

V4L2_CID_PRIVATE_BASE

ID of the first custom (driver specific) control. Applications depending on particular custom

controls should check the driver name and version, see Section 1.2, “Querying Capabilities”.

Applications can enumerate the available controls with the VIDIOC_QUERYCTRL 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 1.8. Enumerating all controls

structv4l2_queryctrl queryctrl;

structv4l2_querymenu querymenu;

static void

enumerate_menu (void)

{

printf (" Menu items:\n");

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

querymenu.id = queryctrl.id;

for (querymenu.index = queryctrl.minimum;

querymenu.index <= queryctrl.maximum;

querymenu.index++) {

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

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

} else {

perror ("VIDIOC_QUERYMENU");

exit (EXIT_FAILURE);

}

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

for (queryctrl.id = V4L2_CID_BASE;

queryctrl.id < V4L2_CID_LASTP1;

queryctrl.id++) {

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

if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)

continue;

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

if (queryctrl.type == V4L2_CTRL_TYPE_MENU)

enumerate_menu ();

} else {

if (errno == EINVAL)

continue;

perror ("VIDIOC_QUERYCTRL");

exit (EXIT_FAILURE);

}

for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;

queryctrl.id++) {

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

if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)

continue;

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

if (queryctrl.type == V4L2_CTRL_TYPE_MENU)

enumerate_menu ();

} else {

if (errno == EINVAL)

break;

perror ("VIDIOC_QUERYCTRL");

exit (EXIT_FAILURE);

}

Example 1.9. Changing controls

structv4l2_queryctrl queryctrl;

structv4l2_control control;

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

queryctrl.id = V4L2_CID_BRIGHTNESS;

if (-1 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {

if (errno != EINVAL) {

perror ("VIDIOC_QUERYCTRL");

exit (EXIT_FAILURE);

} else {

printf ("V4L2_CID_BRIGHTNESS is not supported\n");

}

} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {

printf ("V4L2_CID_BRIGHTNESS is not supported\n");

} else {

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

control.id = V4L2_CID_BRIGHTNESS;

control.value = queryctrl.default_value;

2021/5/7 Video for Linux Two API Specification

https://www.linuxtv.org/downloads/legacy/video4linux/API/V4L2_API/spec-single/v4l2.html#id2710266 17/137

if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)) {

perror ("VIDIOC_S_CTRL");

exit (EXIT_FAILURE);

}

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

control.id = V4L2_CID_CONTRAST;

if (0 == ioctl (fd, VIDIOC_G_CTRL, &control)) {

control.value += 1;

/* The driver may clamp the value or return ERANGE, ignored here */

if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)

&& errno != ERANGE) {

perror ("VIDIOC_S_CTRL");

exit (EXIT_FAILURE);

}

/* Ignore if V4L2_CID_CONTRAST is unsupported */

} else if (errno != EINVAL) {

perror ("VIDIOC_G_CTRL");

exit (EXIT_FAILURE);

}

control.id = V4L2_CID_AUDIO_MUTE;

control.value = TRUE; /* silence */

/* Errors ignored */

ioctl (fd, VIDIOC_S_CTRL, &control);

1.9. Extended Controls

1.9.1. Introduction

The control mechanism as originally designed was meant to be used for user settings (brightness, saturation, etc). However, it turned out

to be a very useful model for implementing more complicated driver APIs where each driver implements only a subset of a larger API.

The MPEG encoding API was the driving force behind designing and implementing this extended control mechanism: the MPEG standard

is quite large and the currently supported hardware MPEG encoders each only implement a subset of this standard. Further more, many

parameters relating to how the video is encoded into an MPEG stream are specific to the MPEG encoding chip since the MPEG standard

only defines the format of the resulting MPEG stream, not how the video is actually encoded into that format.

Unfortunately, the original control API lacked some features needed for these new uses and so it was extended into the (not terribly

originally named) extended control API.

Even though the MPEG encoding API was the first effort to use the Extended Control API, nowadays there are also other classes of

Extended Controls, such as Camera Controls and FM Transmitter Controls. The Extended Controls API as well as all Extended Controls

classes are described in the following text.

1.9.2. The Extended Control API

Three new ioctls are available: VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS and VIDIOC_TRY_EXT_CTRLS. These ioctls act on arrays of controls (as

opposed to the VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls that act on a single control). This is needed since it is often required to atomically

change several controls at once.

Each of the new ioctls expects a pointer to a struct v4l2_ext_controls. This structure contains a pointer to the control array, a count of the

number of controls in that array and a control class. Control classes are used to group similar controls into a single class. For example,

control class V4L2_CTRL_CLASS_USER contains all user controls (i. e. all controls that can also be set using the old VIDIOC_S_CTRL ioctl). Control

class V4L2_CTRL_CLASS_MPEG contains all controls relating to MPEG encoding, etc.

All controls in the control array must belong to the specified control class. An error is returned if this is not the case.

It is also possible to use an empty control array (count == 0) to check whether the specified control class is supported.

The control array is a struct v4l2_ext_control array. The v4l2_ext_control structure is very similar to struct v4l2_control, except for the fact

that it also allows for 64-bit values and pointers to be passed.

It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is

supported in the driver and what the valid range of values is. So use the VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU ioctls to check this. Also note

that it is possible that some of the menu indices in a control of type V4L2_CTRL_TYPE_MENU may not be supported (VIDIOC_QUERYMENU will return

an error). A good example is the list of supported MPEG audio bitrates. Some drivers only support one or two bitrates, others support a

wider range.

1.9.3. Enumerating Extended Controls

The recommended way to enumerate over the extended controls is by using VIDIOC_QUERYCTRL in combination with the

V4L2_CTRL_FLAG_NEXT_CTRL flag:

structv4l2_queryctrl qctrl;

qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;

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

/* ... */

2021/5/7 Video for Linux Two API Specification

https://www.linuxtv.org/downloads/legacy/video4linux/API/V4L2_API/spec-single/v4l2.html#id2710266 18/137

qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;

}

The initial control ID is set to 0 ORed with the V4L2_CTRL_FLAG_NEXT_CTRL flag. The VIDIOC_QUERYCTRL ioctl will return the first control with a higher

ID than the specified one. When no such controls are found an error is returned.

If you want to get all controls within a specific control class, then you can set the initial qctrl.id value to the control class and add an extra

check to break out of the loop when a control of another control class is found:

qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;

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

if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)

break;

/* ... */

qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;

}

The 32-bit qctrl.id value is subdivided into three bit ranges: the top 4 bits are reserved for flags (e. g. V4L2_CTRL_FLAG_NEXT_CTRL) and are not

actually part of the ID. The remaining 28 bits form the control ID, of which the most significant 12 bits define the control class and the

least significant 16 bits identify the control within the control class. It is guaranteed that these last 16 bits are always non-zero for

controls. The range of 0x1000 and up are reserved for driver-specific controls. The macro V4L2_CTRL_ID2CLASS(id) returns the control class ID

based on a control ID.

If the driver does not support extended controls, then VIDIOC_QUERYCTRL will fail when used in combination with V4L2_CTRL_FLAG_NEXT_CTRL. In

that case the old method of enumerating control should be used (see 1.8). But if it is supported, then it is guaranteed to enumerate over

all controls, including driver-private controls.

1.9.4. Creating Control Panels

It is possible to create control panels for a graphical user interface where the user can select the various controls. Basically you will have to

iterate over all controls using the method described above. Each control class starts with a control of type V4L2_CTRL_TYPE_CTRL_CLASS.

VIDIOC_QUERYCTRL will return the name of this control class which can be used as the title of a tab page within a control panel.

The flags field of struct v4l2_queryctrl also contains hints on the behavior of the control. See the VIDIOC_QUERYCTRL documentation for more

details.

1.9.5. MPEG Control Reference

Below all controls within the MPEG control class are described. First the generic controls, then controls specific for certain hardware.

1.9.5.1. Generic MPEG Controls

Table 1.2. MPEG Control IDs

ID Type

Description

V4L2_CID_MPEG_CLASS class

The MPEG class descriptor. Calling VIDIOC_QUERYCTRL for this control will return a description of this control class. This

description can be used as the caption of a Tab page in a GUI, for example.

V4L2_CID_MPEG_STREAM_TYPE enum v4l2_mpeg_stream_type

The MPEG-1, -2 or -4 output stream type. One cannot assume anything here. Each hardware MPEG encoder tends to

support different subsets of the available MPEG stream types. The currently defined stream types are:

V4L2_MPEG_STREAM_TYPE_MPEG2_PS MPEG-2 program stream

V4L2_MPEG_STREAM_TYPE_MPEG2_TS MPEG-2 transport stream

V4L2_MPEG_STREAM_TYPE_MPEG1_SS MPEG-1 system stream

V4L2_MPEG_STREAM_TYPE_MPEG2_DVD MPEG-2 DVD-compatible stream

V4L2_MPEG_STREAM_TYPE_MPEG1_VCD MPEG-1 VCD-compatible stream

V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD MPEG-2 SVCD-compatible stream

V4L2_CID_MPEG_STREAM_PID_PMT integer

Program Map Table Packet ID for the MPEG transport stream (default 16)

V4L2_CID_MPEG_STREAM_PID_AUDIO integer

Audio Packet ID for the MPEG transport stream (default 256)

V4L2_CID_MPEG_STREAM_PID_VIDEO integer

Video Packet ID for the MPEG transport stream (default 260)

V4L2_CID_MPEG_STREAM_PID_PCR integer

Packet ID for the MPEG transport stream carrying PCR fields (default 259)

2021/5/7 Video for Linux Two API Specification

https://www.linuxtv.org/downloads/legacy/video4linux/API/V4L2_API/spec-single/v4l2.html#id2710266 19/137

ID Type

Description

V4L2_CID_MPEG_STREAM_PES_ID_AUDIO integer

Audio ID for MPEG PES

V4L2_CID_MPEG_STREAM_PES_ID_VIDEO integer

Video ID for MPEG PES

V4L2_CID_MPEG_STREAM_VBI_FMT enum v4l2_mpeg_stream_vbi_fmt

Some cards can embed VBI data (e. g. Closed Caption, Teletext) into the MPEG stream. This control selects whether VBI

data should be embedded, and if so, what embedding method should be used. The list of possible VBI formats

depends on the driver. The currently defined VBI format types are:

V4L2_MPEG_STREAM_VBI_FMT_NONE No VBI in the MPEG stream

V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI in private packets, IVTV format (documented in the kernel sources in the file

Documentation/video4linux/cx2341x/README.vbi)

V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ enum v4l2_mpeg_audio_sampling_freq

MPEG Audio sampling frequency. Possible values are:

V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100 44.1 kHz

V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000 48 kHz

V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000 32 kHz

V4L2_CID_MPEG_AUDIO_ENCODING enum v4l2_mpeg_audio_encoding

MPEG Audio encoding. Possible values are:

V4L2_MPEG_AUDIO_ENCODING_LAYER_1 MPEG-1/2 Layer I encoding

V4L2_MPEG_AUDIO_ENCODING_LAYER_2 MPEG-1/2 Layer II encoding

V4L2_MPEG_AUDIO_ENCODING_LAYER_3 MPEG-1/2 Layer III encoding

V4L2_MPEG_AUDIO_ENCODING_AAC MPEG-2/4 AAC (Advanced Audio Coding)

V4L2_MPEG_AUDIO_ENCODING_AC3 AC-3 aka ATSC A/52 encoding

V4L2_CID_MPEG_AUDIO_L1_BITRATE enum v4l2_mpeg_audio_l1_bitrate

MPEG-1/2 Layer I bitrate. Possible values are:

V4L2_MPEG_AUDIO_L1_BITRATE_32K 32 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_64K 64 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_96K 96 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_128K 128 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_160K 160 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_192K 192 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_224K 224 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_256K 256 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_288K 288 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_320K 320 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_352K 352 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_384K 384 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_416K 416 kbit/s

V4L2_MPEG_AUDIO_L1_BITRATE_448K 448 kbit/s

V4L2_CID_MPEG_AUDIO_L2_BITRATE enum v4l2_mpeg_audio_l2_bitrate

MPEG-1/2 Layer II bitrate. Possible values are:

2021/5/7 Video for Linux Two API Specification

https://www.linuxtv.org/downloads/legacy/video4linux/API/V4L2_API/spec-single/v4l2.html#id2710266 20/137

ID Type

Description

V4L2_MPEG_AUDIO_L2_BITRATE_32K 32 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_48K 48 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_56K 56 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_64K 64 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_80K 80 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_96K 96 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_112K 112 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_128K 128 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_160K 160 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_192K 192 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_224K 224 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_256K 256 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_320K 320 kbit/s

V4L2_MPEG_AUDIO_L2_BITRATE_384K 384 kbit/s

V4L2_CID_MPEG_AUDIO_L3_BITRATE enum v4l2_mpeg_audio_l3_bitrate

MPEG-1/2 Layer III bitrate. Possible values are:

V4L2_MPEG_AUDIO_L3_BITRATE_32K 32 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_40K 40 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_48K 48 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_56K 56 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_64K 64 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_80K 80 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_96K 96 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_112K 112 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_128K 128 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_160K 160 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_192K 192 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_224K 224 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_256K 256 kbit/s

V4L2_MPEG_AUDIO_L3_BITRATE_320K 320 kbit/s

V4L2_CID_MPEG_AUDIO_AAC_BITRATE integer

AAC bitrate in bits per second.

V4L2_CID_MPEG_AUDIO_AC3_BITRATE enum v4l2_mpeg_audio_ac3_bitrate

AC-3 bitrate. Possible values are:

V4L2_MPEG_AUDIO_AC3_BITRATE_32K 32 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_40K 40 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_48K 48 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_56K 56 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_64K 64 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_80K 80 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_96K 96 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_112K 112 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_128K 128 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_160K 160 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_192K 192 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_224K 224 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_256K 256 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_320K 320 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_384K 384 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_448K 448 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_512K 512 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_576K 576 kbit/s

V4L2_MPEG_AUDIO_AC3_BITRATE_640K 640 kbit/s

V4L2_CID_MPEG_AUDIO_MODE enum v4l2_mpeg_audio_mode

MPEG Audio mode. Possible values are:

剩余136页未读，继续阅读

ifreecoding

粉丝: 129
资源: 27

Linux TV VideoforLinux Two API 规范（2.6.32版）

Video for Linux Two API Specification

Video for Linux Two API Specification.rar

(V4L2) Video for Linux Two API Specification.pdf

Video for Linux Two API Specification Revision 2.6.32

Video for Linux Two API Specification v4l2

Video for Linux Two API Specification (2.6.32)

Video for Linux Two API Specification(V4l2 API接口说明书)

Video for linux two API specification--V4L2 API函数说明书

video for linux two api specification

FlyCapture2 API Reference（Linux api接口）.pdf

最新资源