Linux媒体子系统用户空间API文档

需积分: 49 50 浏览量更新于2024-07-16 收藏 879KB PDF 举报

"这是一份关于Linux Media Subsystem的用户手册，PDF版本，便于读者查阅和理解。这份文档主要关注Linux内核与用户空间接口在视频和音频流设备中的应用，如视频摄像头、模拟和数字电视接收卡、AM/FM接收卡、软件定义无线电（SDR）、流媒体捕获和输出设备、编解码器设备以及遥控器等。" 这篇文档的版权归属于LinuxTV开发者，并遵循GNU Free Documentation License 1.1或更高版本，允许复制、分发和修改，但不包含不变章节。文档中包含了该许可证的副本，供读者参考。在第一章"Linux Media Infrastructure Userspace API"中，作者介绍了该API的基本概念。此部分详细阐述了用于控制视频和音频流设备的Linux内核到用户空间的接口。这些接口涵盖了多种设备类型： 1. 第一部分涉及的领域包括： - 收音机功能 - 视频捕获和输出 - 摄像头 - 模拟电视设备 - 编解码器 2. 第二部分则详细介绍了用于数字电视和互联网协议电视（IPTV）的API。这部分可能涵盖了解码、传输流处理、EPG（电子节目指南）以及其他与数字广播相关的功能。文档的结构还可能包括其他章节，深入探讨硬件设备的典型架构、设备驱动程序的开发、设备控制协议、数据流处理以及如何与用户空间的应用程序进行交互等内容。此外，可能会讲解如何调试和测试这些接口，以及如何通过内核模块和用户空间程序实现对媒体设备的完整控制。通过对这份文档的学习，读者可以了解到如何利用Linux Media Subsystem API来开发和管理各种多媒体硬件，从而实现高效、灵活的系统集成和应用开发。这对于Linux平台上的系统管理员、软件开发者以及对多媒体硬件感兴趣的爱好者来说，都是极其宝贵的知识资源。

Linux Media Subsystem Documentation, Release

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

if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {

perror("VIDIOC_G_INPUT");

exit(EXIT_FAILURE);

}

if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {

perror("VIDIOC_ENUM_INPUT");

exit(EXIT_FAILURE);

}

if (0 == (input.std & V4L2_STD_PAL_BG)) {

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.

12 Chapter 1. Linux Media Infrastructure userspace API

Linux Media Subsystem Documentation, Release

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

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.

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

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

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

14 Chapter 1. Linux Media Infrastructure userspace API

Linux Media Subsystem Documentation, Release

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

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

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

1.2. Part I - Video for Linux API 15

Linux Media Subsystem Documentation, Release

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

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;

16 Chapter 1. Linux Media Infrastructure userspace API

剩余234页未读，继续阅读

迁旭

粉丝: 1007
资源: 20

Linux媒体子系统用户空间API文档

Linux C编程一站式学习指南

Linux下OpenOffice.org入门与PDF转换教程

Linux内核源码构建及文档指南

Luxand_FaceSDK_Documentation.pdf.zip_linux doc

LinuxCNC_Documentation.pdf

linux_Documentation_html.tar.xz

pillow_documentation.pdf

Professional_Linux_Programming.pdf

deegree_igeoportal_documentation_en.rar_MultiPlatform_

linux_sea.pdf

最新资源