Draft 0.21
Michael H Schimek
Bill Dirks
Hans Verkuil
Martin Rubli
Copyright © 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli
This document is copyrighted © 1999-2006 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.
-
Table of Contents
Introduction
1.
-
-
1.1.
-
-
1.1.1.
Device Naming 1.1.2. Related Devices 1.1.3. Multiple Opens 1.1.4. Shared Data Streams 1.1.5. Functions
1.2.
-
-
1.6.1.
Tuners 1.6.2. Modulators 1.6.3. Radio Frequency 1.6.4. Satellite Receivers
1.7.
-
-
1.9.1.
Introduction 1.9.2. The Extended Control API 1.9.3. Enumerating Extended Controls 1.9.4. Creating Control Panels 1.9.5. MPEG Control Reference
1.10.
-
-
1.10.1.
Data Format Negotiation 1.10.2. Image Format Enumeration
1.11.
Opening and Closing Devices Querying Capabilities 1.3. Application Priority 1.4. Video Inputs and Outputs 1.5. Audio Inputs and Outputs 1.6. Tuners and Modulators Video Standards 1.8. User Controls 1.9. Extended Controls Data Formats Cropping and Scaling 1.12. Streaming Parameters
2.
-
-
-
2.1.
-
-
Packed RGB formats
-- Packed RGB formats V4L2_PIX_FMT_SBGGR8 ('BA81') -- Bayer RGB format.
2.4.
-
-
V4L2_PIX_FMT_GREY ('GREY')
-- Grey-scale image. V4L2_PIX_FMT_YUYV ('YUYV') -- Packed format with ½ horizontal chroma resolution, also known as YUV 4:2:2. V4L2_PIX_FMT_UYVY ('UYVY') -- Variation of V4L2_PIX_FMT_YUYV
with different order of samples in memory. V4L2_PIX_FMT_Y41P ('Y41P') -- Packed format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') -- Planar formats with ½ horizontal and vertical chroma resolution, also known as YUV 4:2:0. V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') -- Planar formats with ¼ horizontal and vertical chroma resolution, also known as YUV 4:1:0. V4L2_PIX_FMT_YUV422P ('422P') -- Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. Planar layout as opposed to V4L2_PIX_FMT_YUYV
. V4L2_PIX_FMT_YUV411P ('411P')-- Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. Planar layout as opposed to V4L2_PIX_FMT_Y41P
. V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')-- Formats with ½ horizontal and vertical chroma resolution, also known as YUV 4:2:0. One luminance and one chrominance plane with alternating chroma samples as opposed to V4L2_PIX_FMT_YVU420
.
2.5.
Standard Image Formats 2.2. Colorspaces 2.3. RGB Formats YUV Formats Compressed Formats 2.6. Reserved Format Identifiers
3.
-
-
-
3.1.
-
-
3.5.1.
Timecodes
3.6.
Read/Write 3.2. Streaming I/O (Memory Mapping) 3.3. Streaming I/O (User Pointers) 3.4. Asynchronous I/O 3.5. Buffers Field Order
4.
-
-
-
4.1.
-
-
4.1.1.
Querying Capabilities 4.1.2. Supplemental Functions 4.1.3. Image Format Negotiation 4.1.4. Reading Images
4.2.
-
-
4.2.1.
Querying Capabilities 4.2.2. Supplemental Functions 4.2.3. Setup 4.2.4. Overlay Window 4.2.5. Enabling Overlay
4.3.
-
-
4.3.1.
Querying Capabilities 4.3.2. Supplemental Functions 4.3.3. Image Format Negotiation 4.3.4. Writing Images
4.4.
-
-
4.6.1.
Querying Capabilities 4.6.2. Supplemental Functions 4.6.3. Raw VBI Format Negotiation 4.6.4. Reading and writing VBI images
4.7.
-
-
4.7.1.
Querying Capabilities 4.7.2. Supplemental Functions 4.7.3. Sliced VBI Format Negotiation 4.7.4. Reading and writing sliced VBI data
4.8.
-
-
4.9.1.
Querying Capabilities 4.9.2. Supplemental Functions 4.9.3. Programming
4.10.
Video Capture Interface Video Overlay Interface Video Output Interface Codec Interface 4.5. Effect Devices Interface 4.6. Raw VBI Data Interface Sliced VBI Data Interface Teletext Interface 4.9. Radio Interface RDS Interface
I.
-
-
-
V4L2 close()
-- Close a V4L2 device V4L2 ioctl() -- Program a V4L2 device ioctl VIDIOC_CROPCAP -- Information about the video cropping and scaling abilities. ioctl VIDIOC_ENUMAUDIO -- Enumerate audio inputs ioctl VIDIOC_ENUMAUDOUT -- Enumerate audio outputs ioctl VIDIOC_ENUM_FMT -- Enumerate image formats ioctl VIDIOC_ENUM_FRAMESIZES -- Enumerate frame sizes ioctl VIDIOC_ENUM_FRAMEINTERVALS -- Enumerate frame intervals ioctl VIDIOC_ENUMINPUT -- Enumerate video inputs ioctl VIDIOC_ENUMOUTPUT -- Enumerate video outputs ioctl VIDIOC_ENUMSTD -- Enumerate supported video standards ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO -- Query or select the current audio input and its attributes ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT -- Query or select the current audio output ioctl VIDIOC_G_MPEGCOMP, VIDIOC_S_MPEGCOMP -- Get or set compression parameters ioctl VIDIOC_G_CROP, VIDIOC_S_CROP -- Get or set the current cropping rectangle ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL -- Get or set the value of a control ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS -- Get or set the value of several controls, try control values. ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF -- Get or set frame buffer overlay parameters. ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT -- Get or set the data format, try a format. ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY -- Get or set tuner or modulator radio frequency ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT -- Query or select the current video input ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP -- ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR -- Get or set modulator attributes ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT -- Query or select the current video output ioctl VIDIOC_G_PARM, VIDIOC_S_PARM -- Get or set streaming parameters ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY -- Query or request the access priority associated with a file descriptor ioctl VIDIOC_G_SLICED_VBI_CAP -- Query sliced VBI capabilities ioctl VIDIOC_G_STD, VIDIOC_S_STD -- Query or select the video standard of the current input ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER -- Get or set tuner attributes ioctl VIDIOC_LOG_STATUS -- Log driver status information ioctl VIDIOC_OVERLAY -- Start or stop video overlay ioctl VIDIOC_QBUF, VIDIOC_DQBUF -- Exchange a buffer with the driver ioctl VIDIOC_QUERYBUF -- Query the status of a buffer ioctl VIDIOC_QUERYCAP -- Query device capabilities ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU -- Enumerate controls and menu control items ioctl VIDIOC_QUERYSTD -- Sense the video standard received by the current input ioctl VIDIOC_REQBUFS -- Initiate Memory Mapping or User Pointer I/O ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF -- Start or stop streaming I/O V4L2 mmap() -- Map device memory into application address space V4L2 munmap() -- Unmap device memory V4L2 open() -- Open a V4L2 device V4L2 poll() -- Wait for some event on a file descriptor V4L2 read() -- Read from a V4L2 device V4L2 select() -- Synchronous I/O multiplexing V4L2 write() -- Write to a V4L2 device
5.
-
-
6.1.
-
-
6.1.1.
Opening and Closing Devices 6.1.2. Querying Capabilities 6.1.3. Video Sources 6.1.4. Tuning 6.1.5. Image Properties 6.1.6. Audio 6.1.7. Frame Buffer Overlay 6.1.8. Cropping 6.1.9. Reading Images, Memory Mapping 6.1.10. Reading Raw VBI Data 6.1.11. Miscellaneous
6.2.
-
-
6.2.1.
Early Versions 6.2.2. V4L2 Version 0.16 1999-01-31 6.2.3. V4L2 Version 0.18 1999-03-16 6.2.4. V4L2 Version 0.19 1999-06-05 6.2.5. V4L2 Version 0.20 1999-09-10 6.2.6. V4L2 Version 0.20 incremental changes 6.2.7. V4L2 Version 0.20 2000-11-23 6.2.8. V4L2 Version 0.20 2002-07-25 6.2.9. V4L2 in Linux 2.5.46, 2002-10 6.2.10. V4L2 2003-06-19 6.2.11. V4L2 2003-11-05 6.2.12. V4L2 in Linux 2.6.6, 2004-05-09 6.2.13. V4L2 in Linux 2.6.8 6.2.14. V4L2 spec erratum 2004-08-01 6.2.15. V4L2 in Linux 2.6.14 6.2.16. V4L2 in Linux 2.6.15 6.2.17. V4L2 spec erratum 2005-11-27 6.2.18. V4L2 spec erratum 2006-01-10 6.2.19. V4L2 spec erratum 2006-02-03 6.2.20. V4L2 spec erratum 2006-02-04 6.2.21. V4L2 in Linux 2.6.17 6.2.22. V4L2 spec erratum 2006-09-23 (Draft 0.15) 6.2.23. V4L2 in Linux 2.6.18 6.2.24. V4L2 in Linux 2.6.19 6.2.25. V4L2 spec erratum 2006-10-12 (Draft 0.17)
6.3.
-
-
6.3.1.
X Video Extension 6.3.2. Digital Video 6.3.3. Audio Interfaces
Differences between V4L and V4L2 History of the V4L2 API Relation of V4L2 to other Linux multimedia APIs
A.
-
-
-
C.1.
0. PREAMBLE C.2. 1. APPLICABILITY AND DEFINITIONS C.3. 2. VERBATIM COPYING C.4. 3. COPYING IN QUANTITY C.5. 4. MODIFICATIONS C.6. 5. COMBINING DOCUMENTS C.7. 6. COLLECTIONS OF DOCUMENTS C.8. 7. AGGREGATION WITH INDEPENDENT WORKS C.9. 8. TRANSLATION C.10. 9. TERMINATION C.11. 10. FUTURE REVISIONS OF THIS LICENSE C.12. Addendum
Bibliography
-
List of Tables
1-1.
v4l2_pix_format
2-2.
v4l2_buffer
3-2.
v4l2_timecode
3-6.
v4l2_window
4-2.
v4l2_clip
[2]
4-3.
v4l2_rect
4-4.
v4l2_vbi_format
4-5.
v4l2_sliced_vbi_format
4-7.
v4l2_sliced_vbi_data
1.
v4l2_cropcap
2.
v4l2_rect
1.
v4l2_fmtdesc
2.
v4l2_frmsize_discrete
2.
v4l2_frmsize_stepwise
3.
v4l2_frmsizeenum
4.
v4l2_frmsizetypes
1.
v4l2_frmival_stepwise
2.
v4l2_frmivalenum
3.
v4l2_frmivaltypes
1.
v4l2_input
2.
v4l2_output
2.
v4l2_standard
2.
v4l2_fract
3.
v4l2_std_id
4.
v4l2_audio
2.
v4l2_audioout
1.
v4l2_mpeg_compression
1.
v4l2_crop
1.
v4l2_control
1.
v4l2_ext_control
2.
v4l2_ext_controls
3.
v4l2_framebuffer
2.
v4l2_format
1.
v4l2_frequency
1.
v4l2_jpegcompression
2.
v4l2_modulator
2.
v4l2_streamparm
2.
v4l2_captureparm
3.
v4l2_outputparm
4.
v4l2_sliced_vbi_cap
2.
v4l2_tuner
2.
v4l2_capability
2.
v4l2_queryctrl
2.
v4l2_querymenu
3.
v4l2_requestbuffers
6-1.
-
List of Figures
1-1.
-
List of Examples
1-1.
V4L2_PIX_FMT_BGR24
V4L2_PIX_FMT_SBGGR8
V4L2_PIX_FMT_GREY
V4L2_PIX_FMT_YUYV
V4L2_PIX_FMT_UYVY
V4L2_PIX_FMT_Y41P
V4L2_PIX_FMT_YVU420
V4L2_PIX_FMT_YVU410
V4L2_PIX_FMT_YUV422P
V4L2_PIX_FMT_YUV411P
V4L2_PIX_FMT_NV12