V4L2 API规格说明书

需积分: 32 53 浏览量更新于2024-07-25 收藏 1.95MB PDF 举报

"V4L2 API Specification是VideoforLinux Two (V4L2)接口的官方文档，详细阐述了V4L2 API的参数及其含义，由Michael H. Schimek、Bill Dirks、Hans Verkuil和Martin Rubli共同编撰，并遵循GNU Free Documentation License进行分发。此文档包含了编程示例，可以自由复制、分发和修改。" 正文: V4L2（VideoforLinux Two）是Linux操作系统下用于处理多媒体数据，尤其是视频捕获和播放的API接口。这个API提供了一种标准的方法来与各种视频硬件进行交互，包括摄像头、电视卡和其他视频输入/输出设备。V4L2 API在V4L1的基础上进行了扩展和改进，增加了更多功能和灵活性，以适应不断发展的多媒体硬件需求。在V4L2 API中，开发者可以操作的关键元素包括： 1. **设备文件**：V4L2设备通常表示为/dev/videoX，其中X是设备编号。应用程序通过打开这些设备文件来与硬件通信。 2. **缓冲区管理**：V4L2引入了缓冲区（buffer）的概念，允许用户空间程序直接操作缓冲区，提高性能。它支持两种缓冲模式：Mmap和Userptr。 3. **控制**：V4L2 API提供了许多控制接口，如VIDIOC_G_CTRL和VIDIOC_S_CTRL，用于获取和设置设备的各种参数，如亮度、对比度、饱和度等。 4. **像素格式**：V4L2定义了一系列的像素格式，如YUV、RGB等，以适应不同的视频编码。例如，V4L2文档中提到的Y16和SBGGR16是新增的像素格式，分别表示16位单通道灰度和16位 Bayer格式的RGB数据。 5. **捕获和输出**：开发者可以使用VIDIOC_REQBUFS、VIDIOC_QBUF和VIDIOC_DQBUF等函数来请求、提交和接收缓冲区，实现视频流的捕获和输出。 6. **流式传输**：V4L2支持流式传输模式，允许在设备和用户空间之间连续传输数据，提高了实时性。 7. **多路复用**：V4L2 API还支持多个并发的输入或输出流，使得一个设备可以同时处理多个视频源或目标。 8. **摄像头控制**：V4L2提供了一个专门的摄像头控制类，包括自动曝光、自动白平衡等高级特性，帮助优化图像质量。 9. **MPEG编解码**：虽然VIDIOC_G/S_MPEGCOMP已从V4L2 API中移除，但V4L2仍然支持MPEG编码和解码相关的操作，如视频压缩和解压缩。 V4L2 API的不断更新和扩展，使其能够适应新的硬件特性和应用场景，如高清视频、网络流媒体等。对于开发涉及视频处理的Linux应用来说，理解和掌握V4L2 API至关重要，因为它提供了直接与底层硬件交互的能力，从而实现高效且灵活的视频处理功能。

Chapter 1. Common API Elements

printf ("Current input: %s\n", audio.name);

Example 1-4. Switching to the ﬁrst audio input

struct v4l2_audio audio;

memset (&audio, 0, sizeof (audio)); /

clear audio.mode, audio.reserved

audio.index = 0;

if (-1 == ioctl (fd,

VIDIOC_S_AUDIO, &audio)) {

perror ("VIDIOC_S_AUDIO");

exit (EXIT_FAILURE);

}

1.6. Tuners and Modulators

1.6.1. Tuners

Video input devices can have one or more tuners demodulating a RF signal. Each tuner is associated

with one or more video inputs, depending on the number of RF connectors on the tuner. The type

ﬁeld of the respective struct v4l2_input returned by the VIDIOC_ENUMINPUT ioctl is set to

V4L2_INPUT_TYPE_TUNER and its tuner ﬁeld contains the index number of the tuner.

Radio devices have exactly one tuner with index zero, no video inputs.

To query and change tuner properties applications use the VIDIOC_G_TUNER and VIDIOC_S_TUNER

ioctl, respectively. The struct v4l2_tuner returned by VIDIOC_G_TUNER also contains signal status

information applicable when the tuner of the current video input, or a radio tuner is queried. Note

that VIDIOC_S_TUNER does not switch the current tuner, when there is more than one at all. The

tuner is solely determined by the current video input. Drivers must support both ioctls and set the

V4L2_CAP_TUNER ﬂag in the struct v4l2_capability returned by the VIDIOC_QUERYCAP ioctl when

the device has one or more tuners.

1.6.2. Modulators

Video output devices can have one or more modulators, uh, modulating a video signal for radiation

or connection to the antenna input of a TV set or video recorder. Each modulator is associated with

one or more video outputs, depending on the number of RF connectors on the modulator. The type

ﬁeld of the respective struct v4l2_output returned by the VIDIOC_ENUMOUTPUT ioctl is set to

V4L2_OUTPUT_TYPE_MODULATOR and its modulator ﬁeld contains the index number of the

modulator. This speciﬁcation does not deﬁne radio output devices.

To query and change modulator properties applications use the VIDIOC_G_MODULATOR and

VIDIOC_S_MODULATOR ioctl. Note that VIDIOC_S_MODULATOR does not switch the current

modulator, when there is more than one at all. The modulator is solely determined by the current

video output. Drivers must support both ioctls and set the V4L2_CAP_TUNER (sic) ﬂag in the

Chapter 1. Common API Elements

struct v4l2_capability returned by the VIDIOC_QUERYCAP ioctl when the device has one or more

modulators.

1.6.3. Radio Frequency

To get and set the tuner or modulator radio frequency applications use the VIDIOC_G_FREQUENCY

and VIDIOC_S_FREQUENCY ioctl which both take a pointer to a struct v4l2_frequency. These ioctls

are used for TV and radio devices alike. Drivers must support both ioctls when the tuner or

modulator ioctls are supported, or when the device is a radio device.

1.6.4. Satellite Receivers

To be discussed. See also proposals by Peter Schlaf, video4linux-list@redhat.com on 23 Oct 2002,

subject: "Re: [V4L] Re: v4l2 api".

1.7. Video Standards

Video devices typically support one or more different video standards or variations of standards.

Each video input and output may support another set of standards. This set is reported by the std

ﬁeld of struct v4l2_input and struct v4l2_output returned by the VIDIOC_ENUMINPUT and

VIDIOC_ENUMOUTPUT ioctl, respectively.

V4L2 deﬁnes one bit for each analog video standard currently in use worldwide, and sets aside bits

for driver deﬁned standards, e. g. hybrid standards to watch NTSC video tapes on PAL TVs and vice

versa. Applications can use the predeﬁned bits to select a particular standard, although presenting the

user a menu of supported standards is preferred. To enumerate and query the attributes of the

supported standards applications use the VIDIOC_ENUMSTD ioctl.

Many of the deﬁned standards are actually just variations of a few major standards. The hardware

may in fact not distinguish between them, or do so internal and switch automatically. Therefore

enumerated standards also contain sets of one or more standard bits.

Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL signals. The ﬁrst

enumerated standard is a set of B and G/PAL, switched automatically depending on the selected

radio frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a

Composite input may collapse standards, enumerating "PAL-B/G/H/I", "NTSC-M" and

"SECAM-D/K".

To query and select the standard used by the current video input or output applications call the

VIDIOC_G_STD and VIDIOC_S_STD ioctl, respectively. The received standard can be sensed with

the VIDIOC_QUERYSTD ioctl. Note parameter of all these ioctls is a pointer to a v4l2_std_id type (a

standard set), not an index into the standard enumeration.

Drivers must implement all video

standard ioctls when the device has one or more video inputs or outputs.

Special rules apply to USB cameras where the notion of video standards makes little sense. More

generally any capture device, output devices accordingly, which is

• incapable of capturing ﬁelds or frames at the nominal rate of the video standard, or

• where timestamps refer to the instant the ﬁeld or frame was received by the driver, not the capture

time, or

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 deﬁnes several IDs for speciﬁc purposes. Drivers

can also implement their own custom controls using V4L2_CID_PRIVATE_BASE and higher values.

The pre-deﬁned control IDs have the preﬁx 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

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 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.

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

speciﬁes 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.

Table 1-1. Control IDs

ID Type Description

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_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.

剩余280页未读，继续阅读

chen_chun_guang

粉丝: 60
资源: 16

V4L2 API规格说明书

V4L2 API Specification: Video for Linux Two

V4L2 API规格说明书

V4L2 API接口详解：最新版规格与修订历史

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

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

V4L2_API_Specification

Video for Linux Two API Specification v4l2

(V4L2) Video for Linux Two API Specification.pdf

VideoForLinuxTwo_API_linux_v4l2_

V4L2 API 规范详解

最新资源