Video for Linux Two API Specification
Revision 0.24
Michael H Schimek
mschimek@gmx.at
Bill Dirks
Hans Verkuil
Martin Rubli
Video for Linux Two API Specification: Revision 0.24
by Michael H Schimek, Bill Dirks, Hans Verkuil, and Martin Rubli
Copyright © 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Bill Dirks, Michael H. Schimek,
Hans Verkuil, Martin Rubli
This document is copyrighted © 1999-2008 by Bill Dirks, Michael H. Schimek, Hans Verkuil and 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.24 2008-03-04 Revised by: mhs
Added pixel format Y16 and SBGGR16, new controls and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.
Revision 0.23 2007-08-30 Revised by: mhs
Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of packed pixel formats.
Revision 0.22 2007-08-29 Revised by: mhs
Added the Video Output Overlay interface, new MPEG controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. Clarifications in the cropping chapter, about RGB pixel formats, the mmap(), poll(), select(), read() and write() functions. Typographical fixes.
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
Clarified the purpose of the audioset field 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 defines.
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 clarifications.
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 Makefile to generate a PDF. SGML fixes. 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.............................................................................................................. 14
1.9.1. Introduction ........................................................................................................... 14
1.9.2. The Extended Control API .................................................................................... 15
1.9.3. Enumerating Extended Controls............................................................................ 15
1.9.4. Creating Control Panels......................................................................................... 16
1.9.5. MPEG Control Reference...................................................................................... 16
1.9.5.1. Generic MPEG Controls........................................................................... 16
1.9.5.2. CX2341x MPEG Controls ........................................................................ 19
1.9.6. Camera Control Reference .................................................................................... 20
1.10. Data Formats .................................................................................................................... 22
1.10.1. Data Format Negotiation ..................................................................................... 22
1.10.2. Image Format Enumeration................................................................................. 22
1.11. Image Cropping, Insertion and Scaling............................................................................ 23
1.11.1. Cropping Structures.............................................................................................23
1.11.2. Scaling Adjustments............................................................................................ 24
1.11.3. Examples ............................................................................................................. 24
1.12. Streaming Parameters....................................................................................................... 27
2. Image Formats .............................................................................................................................. 29
2.1. Standard Image Formats .................................................................................................... 29
2.2. Colorspaces ........................................................................................................................ 30
2.3. Indexed Format .................................................................................................................. 33
2.4. RGB Formats ..................................................................................................................... 34
Packed RGB formats ....................................................................................................... 34
V4L2_PIX_FMT_SBGGR8 (’BA81’) ............................................................................ 37
V4L2_PIX_FMT_SBGGR16 (’BA82’) .......................................................................... 38
2.5. YUV Formats..................................................................................................................... 39
Packed YUV formats....................................................................................................... 39
V4L2_PIX_FMT_GREY (’GREY’) ............................................................................... 40
V4L2_PIX_FMT_Y16 (’Y16 ’) ...................................................................................... 41
V4L2_PIX_FMT_YUYV (’YUYV’).............................................................................. 42
iv
V4L2_PIX_FMT_UYVY (’UYVY’).............................................................................. 43
V4L2_PIX_FMT_Y41P (’Y41P’)................................................................................... 44
V4L2_PIX_FMT_YVU420 (’YV12’), V4L2_PIX_FMT_YUV420 (’YU12’).............. 45
V4L2_PIX_FMT_YVU410 (’YVU9’), V4L2_PIX_FMT_YUV410 (’YUV9’)............46
V4L2_PIX_FMT_YUV422P (’422P’)............................................................................ 47
V4L2_PIX_FMT_YUV411P (’411P’)............................................................................ 48
V4L2_PIX_FMT_NV12 (’NV12’), V4L2_PIX_FMT_NV21 (’NV21’) ....................... 49
2.6. Compressed Formats.......................................................................................................... 50
2.7. Reserved Format Identifiers ............................................................................................... 50
3. Input/Output ................................................................................................................................. 51
3.1. Read/Write ......................................................................................................................... 51
3.2. Streaming I/O (Memory Mapping) .................................................................................... 51
3.3. Streaming I/O (User Pointers)............................................................................................ 54
3.4. Asynchronous I/O .............................................................................................................. 55
3.5. Buffers................................................................................................................................ 55
3.5.1. Timecodes.............................................................................................................. 59
3.6. Field Order ......................................................................................................................... 60
4. Interfaces ....................................................................................................................................... 66
4.1. Video Capture Interface ..................................................................................................... 66
4.1.1. Querying Capabilities............................................................................................ 66
4.1.2. Supplemental Functions ........................................................................................ 66
4.1.3. Image Format Negotiation..................................................................................... 66
4.1.4. Reading Images ..................................................................................................... 67
4.2. Video Overlay Interface ..................................................................................................... 67
4.2.1. Querying Capabilities............................................................................................ 67
4.2.2. Supplemental Functions ........................................................................................ 67
4.2.3. Setup ...................................................................................................................... 67
4.2.4. Overlay Window.................................................................................................... 68
4.2.5. Enabling Overlay................................................................................................... 70
4.3. Video Output Interface....................................................................................................... 70
4.3.1. Querying Capabilities............................................................................................ 71
4.3.2. Supplemental Functions ........................................................................................ 71
4.3.3. Image Format Negotiation..................................................................................... 71
4.3.4. Writing Images ...................................................................................................... 71
4.4. Video Output Overlay Interface ......................................................................................... 72
4.4.1. Querying Capabilities............................................................................................ 72
4.4.2. Framebuffer ........................................................................................................... 72
4.4.3. Overlay Window and Scaling ................................................................................73
4.4.4. Enabling Overlay................................................................................................... 74
4.5. Codec Interface .................................................................................................................. 74
4.6. Effect Devices Interface ..................................................................................................... 74
4.7. Raw VBI Data Interface..................................................................................................... 74
4.7.1. Querying Capabilities............................................................................................ 75
4.7.2. Supplemental Functions ........................................................................................ 75
4.7.3. Raw VBI Format Negotiation................................................................................ 75
4.7.4. Reading and writing VBI images .......................................................................... 81
4.8. Sliced VBI Data Interface .................................................................................................. 81
4.8.1. Querying Capabilities............................................................................................ 81
4.8.2. Supplemental Functions ........................................................................................ 82
4.8.3. Sliced VBI Format Negotiation .............................................................................82
4.8.4. Reading and writing sliced VBI data..................................................................... 83
v
评论0