V4L2 API 规范详解

需积分: 9 22 浏览量更新于2024-07-16 1 收藏 1.44MB PDF 举报

"v4l2标准.pdf" V4L2（Video for Linux Two）是Video for Linux API的第二版，它是一个内核接口，用于处理模拟广播和视频捕获及输出驱动程序。这个API旨在统一和标准化Linux系统中与视频处理相关的硬件设备的访问方式。早期的Linux驱动程序使用的是非正式的接口，但在Linux 2.2版本中，Alan Cox设计的V4L API取而代之，其设计灵感来源于bttv驱动程序的接口。然而，随着视频设备种类的增加和技术的发展，V4L API逐渐暴露出一些不足。因此，Bill Dirks在1999年开始了V4L2的开发，目的是修复V4L的问题并支持更广泛的设备。2002年，在V4L2被纳入Linux 2.5/2.6内核之前，API进行了进一步修订。自那时起，V4L2 API持续演进，以适应不断变化的硬件需求。 V4L2 API规范草案0.12版由Michael H. Schimek、Bill Dirks和Hans Verkuil共同编写。此文档的版权自1999年至2006年由Bill Dirks、Michael H. Schimek和Hans Verkuil持有，并且遵循GNU Free Documentation License 1.1或更高版本进行分发。这意味着用户可以自由复制、分发和修改文档，但必须保留作者的版权信息。文档的修订历史记录显示，V4L2 API的细节在不断地完善和更新。例如，修订0.12版修正了struct v4l2_captureparm和struct v4l2_outputparm的描述，修订0.11版改进了struct v4l2_tuner的描述，而修订0.10版则涉及VIDIOC_G_INPUT和VIDIOC_S_PARM等函数的说明。 V4L2 API提供了多种控制和查询视频设备的功能，包括但不限于： 1. 设备枚举：通过VIDIOC_ENUMDEVS和VIDIOC_G_INPUT等 ioctl 命令，用户可以获取系统中存在的视频设备列表，并查询当前选择的输入源。 2. 视频流控制：支持打开（VIDIOC_STREAMON）、关闭（VIDIOC_STREAMOFF）视频流，以及设置捕获参数（如帧率、分辨率等）。 3. 调谐器管理：对于支持调谐器的设备，用户可以调整频率、频道和解码方式，结构体v4l2_tuner中包含了这些信息。 4. 缓冲区管理：使用Mmap机制，用户可以直接映射设备内存，实现高效的视频数据传输。 5. 控制处理：设备的各种特性（如亮度、对比度等）可以通过struct v4l2_control进行控制。此外，V4L2 API还适用于USB视频设备，因为这些设备通常需要类似的接口来与Linux内核交互。通过V4L2，开发者可以创建跨不同硬件平台的通用视频处理软件，提高了代码的可移植性和兼容性。 V4L2 API是Linux系统中处理视频和音频设备的核心接口，它为驱动开发人员和应用程序开发者提供了一套全面的工具，以便于他们能够有效地利用硬件资源，实现各种视频捕获和播放功能。随着技术的不断发展，V4L2 API将持续进化以满足新的需求和挑战。

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. 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_BRIGHTNESS integer Picture brightness, or more precisely, the black

level. Will not turn up the intelligence of the

program you’re watching.

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.

Chapter 1. Common API Elements

ID Type Description

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). [?]

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

ignored), 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.

V4L2_CID_EXPOSURE integer Exposure (cameras). [Unit?]

V4L2_CID_AUTOGAIN boolean Automatic gain/exposure control.

V4L2_CID_GAIN integer Gain control.

V4L2_CID_HFLIP boolean Mirror the picture horizontally.

V4L2_CID_VFLIP boolean Mirror the picture vertically.

V4L2_CID_HCENTER integer Horizontal image centering.

V4L2_CID_VCENTER integer Vertical image centering. Centering is intended to

physically adjust cameras. For image cropping see

Section 1.10>, for clipping Section 4.2>.

V4L2_CID_LASTP1 End of the predeﬁned control IDs (currently

V4L2_CID_VCENTER + 1).

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

Applications depending on particular custom

controls should check the driver name and

version, see Section 1.2>.

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;

剩余226页未读，继续阅读

Frankie_He

粉丝: 111
资源: 3

V4L2 API 规范详解

v4l2.pdf 中文手册(规范)

摄像头V4L2编程.pdf

v4l2.pdf.tar.gz_C++_

《linux视频驱动v4l2》.pdf

v4l2[1].pdf.tar.gz_V4L2-capture_v4l2

v4l2驅動篇.pdf

V4L2驱动程序架构.pdf

V4L2 驱动编程指南.pdf

V4l2-frameworks_0.pdf

v4l2_doc.rar_V4L2_DOC_doc_v4l_v4l2 d_v4l2 manu

最新资源