V4L2linux视频API详解

4星 · 超过85%的资源需积分: 12 153 浏览量更新于2023-05-29 评论收藏 1.86MB PDF 举报

身份认证购VIP最低享 7 折!

领优惠券(最高得80元）

资源详情

资源评论

资源推荐

Video for Linux Two API Speciﬁcation

Draft 0.21

Michael H Schimek

mschimek@gmx.at

Bill Dirks

Hans Verkuil

Martin Rubli

Video for Linux Two API Speciﬁcation: Draft 0.21

by Michael H Schimek, Bill Dirks, Hans Verkuil, and Martin Rubli

Martin Rubli

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1

or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no

Back-Cover Texts. A copy of the license is included in the appendix entitled "GNU Free Documentation License".

Programming examples can be used and distributed without restrictions.

Revision History

Revision 0.21 2006-12-19 Revised by: mhs

Fixed a link in the VIDIOC_G_EXT_CTRLS section.

Revision 0.20 2006-11-24 Revised by: mhs

Clariﬁed the purpose of the audioset ﬁeld in struct v4l2_input and v4l2_output.

Revision 0.19 2006-10-19 Revised by: mhs

Documented V4L2_PIX_FMT_RGB444.

Revision 0.18 2006-10-18 Revised by: mhs

Added the description of extended controls by Hans Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.

Revision 0.17 2006-10-12 Revised by: mhs

Corrected V4L2_PIX_FMT_HM12 description.

Revision 0.16 2006-10-08 Revised by: mhs

VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.

Revision 0.15 2006-09-23 Revised by: mhs

Cleaned up the bibliography, added BT.653 and BT.1119. capture.c/start_capturing() for user pointer I/O did not initialize the buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See the history chapter for API changes.

Revision 0.14 2006-09-14 Revised by: mr

Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of digital devices.

Revision 0.13 2006-04-07 Revised by: mhs

Corrected the description of struct v4l2_window clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 deﬁnes.

Revision 0.12 2006-02-03 Revised by: mhs

Corrected the description of struct v4l2_captureparm and v4l2_outputparm.

Revision 0.11 2006-01-27 Revised by: mhs

Improved the description of struct v4l2_tuner.

Revision 0.10 2006-01-10 Revised by: mhs

VIDIOC_G_INPUT and VIDIOC_S_PARM clariﬁcations.

Revision 0.9 2005-11-27 Revised by: mhs

Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard selection example. Various updates.

Revision 0.8 2004-10-04 Revised by: mhs

Somehow a piece of junk slipped into the capture example, removed.

Revision 0.7 2004-09-19 Revised by: mhs

Fixed video standard selection, control enumeration, downscaling and aspect example. Added read and user pointer i/o to video capture example.

Revision 0.6 2004-08-01 Revised by: mhs

v4l2_buffer changes, added video capture example, various corrections.

Revision 0.5 2003-11-05 Revised by: mhs

Pixel format erratum.

Revision 0.4 2003-09-17 Revised by: mhs

Corrected source and Makeﬁle to generate a PDF. SGML ﬁxes. Added latest API changes. Closed gaps in the history chapter.

Revision 0.3 2003-02-05 Revised by: mhs

Another draft, more corrections.

Revision 0.2 2003-01-15 Revised by: mhs

Second draft, with corrections pointed out by Gerd Knorr.

Revision 0.1 2002-12-01 Revised by: mhs

First draft, based on documentation by Bill Dirks and discussions on the V4L mailing list.

Table of Contents

Introduction......................................................................................................................................... x

1. Common API Elements.................................................................................................................. 1

1.1. Opening and Closing Devices.............................................................................................. 1

1.1.1. Device Naming ........................................................................................................ 1

1.1.2. Related Devices ....................................................................................................... 2

1.1.3. Multiple Opens ........................................................................................................ 2

1.1.4. Shared Data Streams................................................................................................ 3

1.1.5. Functions ................................................................................................................. 3

1.2. Querying Capabilities .......................................................................................................... 3

1.3. Application Priority.............................................................................................................. 3

1.4. Video Inputs and Outputs.....................................................................................................4

1.5. Audio Inputs and Outputs .................................................................................................... 5

1.6. Tuners and Modulators......................................................................................................... 6

1.6.1. Tuners ...................................................................................................................... 6

1.6.2. Modulators............................................................................................................... 6

1.6.3. Radio Frequency...................................................................................................... 7

1.6.4. Satellite Receivers ...................................................................................................7

1.7. Video Standards ................................................................................................................... 7

1.8. User Controls ....................................................................................................................... 9

1.9. Extended Controls.............................................................................................................. 13

1.9.1. Introduction ........................................................................................................... 14

1.9.2. The Extended Control API .................................................................................... 14

1.9.3. Enumerating Extended Controls............................................................................ 14

1.9.4. Creating Control Panels......................................................................................... 15

1.9.5. MPEG Control Reference...................................................................................... 15

1.9.5.1. Generic MPEG Controls........................................................................... 15

1.9.5.2. CX2341x MPEG Controls ........................................................................ 18

1.10. Data Formats .................................................................................................................... 19

1.10.1. Data Format Negotiation ..................................................................................... 19

1.10.2. Image Format Enumeration................................................................................. 20

1.11. Cropping and Scaling....................................................................................................... 20

1.12. Streaming Parameters....................................................................................................... 24

2. Image Formats .............................................................................................................................. 26

2.1. Standard Image Formats .................................................................................................... 26

2.2. Colorspaces ........................................................................................................................ 27

2.3. RGB Formats ..................................................................................................................... 30

Packed RGB formats ....................................................................................................... 30

V4L2_PIX_FMT_SBGGR8 (’BA81’) ............................................................................ 33

2.4. YUV Formats..................................................................................................................... 34

V4L2_PIX_FMT_GREY (’GREY’) ............................................................................... 34

V4L2_PIX_FMT_YUYV (’YUYV’).............................................................................. 35

V4L2_PIX_FMT_UYVY (’UYVY’).............................................................................. 36

V4L2_PIX_FMT_Y41P (’Y41P’)................................................................................... 37

V4L2_PIX_FMT_YVU420 (’YV12’), V4L2_PIX_FMT_YUV420 (’YU12’).............. 38

V4L2_PIX_FMT_YVU410 (’YVU9’), V4L2_PIX_FMT_YUV410 (’YUV9’)............39

V4L2_PIX_FMT_YUV422P (’422P’)............................................................................ 40

V4L2_PIX_FMT_YUV411P (’411P’)............................................................................ 41

V4L2_PIX_FMT_NV12 (’NV12’), V4L2_PIX_FMT_NV21 (’NV21’) ....................... 42

2.5. Compressed Formats.......................................................................................................... 43

iii

2.6. Reserved Format Identiﬁers ............................................................................................... 43

3. Input/Output ................................................................................................................................. 44

3.1. Read/Write ......................................................................................................................... 44

3.2. Streaming I/O (Memory Mapping) .................................................................................... 44

3.3. Streaming I/O (User Pointers)............................................................................................ 47

3.4. Asynchronous I/O .............................................................................................................. 48

3.5. Buffers................................................................................................................................ 48

3.5.1. Timecodes.............................................................................................................. 52

3.6. Field Order ......................................................................................................................... 53

4. Device Types .................................................................................................................................. 58

4.1. Video Capture Interface ..................................................................................................... 58

4.1.1. Querying Capabilities............................................................................................ 58

4.1.2. Supplemental Functions ........................................................................................ 58

4.1.3. Image Format Negotiation..................................................................................... 58

4.1.4. Reading Images ..................................................................................................... 59

4.2. Video Overlay Interface ..................................................................................................... 59

4.2.1. Querying Capabilities............................................................................................ 59

4.2.2. Supplemental Functions ........................................................................................ 59

4.2.3. Setup ...................................................................................................................... 59

4.2.4. Overlay Window.................................................................................................... 60

4.2.5. Enabling Overlay................................................................................................... 62

4.3. Video Output Interface....................................................................................................... 62

4.3.1. Querying Capabilities............................................................................................ 62

4.3.2. Supplemental Functions ........................................................................................ 62

4.3.3. Image Format Negotiation..................................................................................... 63

4.3.4. Writing Images ...................................................................................................... 63

4.4. Codec Interface .................................................................................................................. 63

4.5. Effect Devices Interface ..................................................................................................... 64

4.6. Raw VBI Data Interface..................................................................................................... 64

4.6.1. Querying Capabilities............................................................................................ 64

4.6.2. Supplemental Functions ........................................................................................ 64

4.6.3. Raw VBI Format Negotiation................................................................................ 65

4.6.4. Reading and writing VBI images .......................................................................... 71

4.7. Sliced VBI Data Interface .................................................................................................. 71

4.7.1. Querying Capabilities............................................................................................ 71

4.7.2. Supplemental Functions ........................................................................................ 72

4.7.3. Sliced VBI Format Negotiation .............................................................................72

4.7.4. Reading and writing sliced VBI data..................................................................... 73

4.8. Teletext Interface................................................................................................................ 74

4.9. Radio Interface................................................................................................................... 75

4.9.1. Querying Capabilities............................................................................................ 75

4.9.2. Supplemental Functions ........................................................................................ 75

4.9.3. Programming ......................................................................................................... 75

4.10. RDS Interface................................................................................................................... 75

I. Function Reference ....................................................................................................................... 77

V4L2 close() ............................................................................................................................. 79

V4L2 ioctl()............................................................................................................................... 80

ioctl VIDIOC_CROPCAP......................................................................................................... 82

ioctl VIDIOC_ENUMAUDIO .................................................................................................. 84

ioctl VIDIOC_ENUMAUDOUT .............................................................................................. 85

ioctl VIDIOC_ENUM_FMT..................................................................................................... 86

ioctl VIDIOC_ENUM_FRAMESIZES .................................................................................... 88

ioctl VIDIOC_ENUM_FRAMEINTERVALS.......................................................................... 91

ioctl VIDIOC_ENUMINPUT ................................................................................................... 94

ioctl VIDIOC_ENUMOUTPUT ............................................................................................... 97

ioctl VIDIOC_ENUMSTD ....................................................................................................... 99

ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO .................................................................... 104

ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT ............................................................ 106

ioctl VIDIOC_G_MPEGCOMP, VIDIOC_S_MPEGCOMP ................................................. 108

ioctl VIDIOC_G_CROP, VIDIOC_S_CROP .........................................................................109

ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL ......................................................................... 111

ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS113

ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF.......................................................................... 116

ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT.......................................... 119

ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY .............................................. 122

ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT ...................................................................... 124

ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP ..................................................... 126

ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR ........................................... 128

ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT .............................................................. 131

ioctl VIDIOC_G_PARM, VIDIOC_S_PARM........................................................................ 133

ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY ......................................................... 137

ioctl VIDIOC_G_SLICED_VBI_CAP ................................................................................... 139

ioctl VIDIOC_G_STD, VIDIOC_S_STD .............................................................................. 141

ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER................................................................... 142

ioctl VIDIOC_LOG_STATUS ................................................................................................ 147

ioctl VIDIOC_OVERLAY ...................................................................................................... 148

ioctl VIDIOC_QBUF, VIDIOC_DQBUF............................................................................... 149

ioctl VIDIOC_QUERYBUF ................................................................................................... 151

ioctl VIDIOC_QUERYCAP ................................................................................................... 153

ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU...................................................... 156

ioctl VIDIOC_QUERYSTD.................................................................................................... 161

ioctl VIDIOC_REQBUFS....................................................................................................... 163

ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF ......................................................... 165

V4L2 mmap().......................................................................................................................... 167

V4L2 munmap()...................................................................................................................... 169

V4L2 open()............................................................................................................................ 170

V4L2 poll() ............................................................................................................................. 172

V4L2 read()............................................................................................................................. 173

V4L2 select()........................................................................................................................... 175

V4L2 write() ........................................................................................................................... 176

5. V4L2 Driver Programming........................................................................................................ 178

6. History .........................................................................................................................................179

6.1. Differences between V4L and V4L2 ............................................................................... 179

6.1.1. Opening and Closing Devices ............................................................................. 179

6.1.2. Querying Capabilities.......................................................................................... 179

6.1.3. Video Sources ......................................................................................................181

6.1.4. Tuning.................................................................................................................. 182

6.1.5. Image Properties.................................................................................................. 182

6.1.6. Audio ................................................................................................................... 183

6.1.7. Frame Buffer Overlay.......................................................................................... 184

6.1.8. Cropping .............................................................................................................. 184