V4L2 API 规范修订版 0.23

需积分: 6 152 浏览量更新于2024-07-21 收藏 1.99MB PDF 举报

"V4L2(Revision 0.23) - 官方文档，由Michael H. Schimek、Bill Dirks、Hans Verkuil和Martin Rubli编写，是关于Video for Linux 2 API的详细规格说明，涵盖了1999年至2007年的版权。该文档允许根据GNU Free Documentation License分发和修改。" Video for Linux 2（V4L2）是Linux内核中的一个接口，用于与视频捕获设备、视频输出设备和其他多媒体硬件进行交互。V4L2 API规范的Revision 0.23是这个接口的一个特定版本，包含了对API的更新和修正。在Revision 0.23中，主要的修订包括： 1. 修复了VIDIOC_DBG_G/S_REGISTER中的一个错误，这是一个调试控制命令，用于获取或设置设备的特定寄存器值。这确保了开发者能够准确地读取和设置设备状态，以进行故障排查和优化。 2. 清晰化了打包像素格式的字节顺序。在处理视频数据时，字节顺序是至关重要的，因为不同的系统和设备可能有不同的字节序要求。这个修订确保了跨平台兼容性，避免了数据解析错误。此外，Revision 0.22引入了Video Output Overlay接口，这是一个新的功能，允许在视频输出设备上叠加图像或视频流，例如在电视输出上显示桌面或视频播放。这扩展了V4L2的能力，使其不仅限于捕获设备，还可以用于更复杂的多媒体应用。 V4L2 API提供了多种操作，如打开设备、设置捕获参数、请求帧、控制设备特性等。它支持多种视频格式、压缩和未压缩的音频以及捕获和输出设备。开发人员可以使用这些接口来创建应用程序，例如视频播放器、录像机、摄像头应用等。该文档还包括编程示例，这些示例可以自由使用和分发，为开发者提供了实现V4L2功能的实际代码参考。通过遵循这些示例和API规范，开发者可以有效地与Linux系统下的各种视频设备进行交互。 V4L2 API是Linux多媒体开发的核心部分，它的不断更新和完善确保了与现代硬件的兼容性，并为开发者提供了强大的工具来构建视频相关的应用程序。Revision 0.23的修订内容体现了这一目标，增强了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.

剩余279页未读，继续阅读

evercomer

粉丝: 0
资源: 8

V4L2 API 规范修订版 0.23

VideoForLinuxTwo_API_linux_v4l2_

Video for Linux Two API Specification Revision 2.6.32

V4L2 API 规范修订版 0.23：视频接口详解

revision

Revision

PCI Express ® Revision 3.0 + Revision 2.1 +Revision 1.1 三版本全英文.zip

301_revision

Revision-Material

Revision2k15

UCSI Revision 3.0

最新资源