Part I. Video for Linux Two API Specification
Prev   Next

Part I. Video for Linux Two API Specification

Revision 2.6.39

Michael H Schimek


    
  

Bill Dirks

Original author of the V4L2 API and documentation. 

Hans Verkuil

Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls and major parts of the sliced VBI API. 


    
  

Martin Rubli

Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls. 

Andy Walls

Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.  


    
  

Mauro Carvalho Chehab

Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. 


    
  

Muralidharan Karicheri

Documented the Digital Video timings API. 


    
  

Pawel Osciak

Designed and documented the multi-planar API. 


    
  

Copyright © 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak

Except when explicitly stated as GPL, programming examples within this part can be used and distributed without restrictions.

Revision History
Revision 2.6.392011-03-01mcc, po
Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the multi-planar API.
Revision 2.6.372010-08-06hv
Removed obsolete vtx (videotext) API.
Revision 2.6.332009-12-03mk
Added documentation for the Digital Video timings API.
Revision 2.6.322009-08-31mcc
Now, revisions will match the kernel version where the V4L2 API changes will be used by the Linux Kernel. Also added Remote Controller chapter.
Revision 0.292009-08-26ev
Added documentation for string controls and for FM Transmitter controls.
Revision 0.282009-08-26gl
Added V4L2_CID_BAND_STOP_FILTER documentation.
Revision 0.272009-08-15mcc
Added libv4l and Remote Controller documentation; added v4l2grab and keytable application examples.
Revision 0.262009-07-23hv
Finalized the RDS capture API. Added modulator and RDS encoder capabilities. Added support for string controls.
Revision 0.252009-01-18hv
Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
Revision 0.242008-03-04mhs
Added pixel formats Y16 and SBGGR16, new controls and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.
Revision 0.232007-08-30mhs
Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of packed pixel formats.
Revision 0.222007-08-29mhs
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.212006-12-19mhs
Fixed a link in the VIDIOC_G_EXT_CTRLS section.
Revision 0.202006-11-24mhs
Clarified the purpose of the audioset field in struct v4l2_input and v4l2_output.
Revision 0.192006-10-19mhs
Documented V4L2_PIX_FMT_RGB444.
Revision 0.182006-10-18mhs
Added the description of extended controls by Hans Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
Revision 0.172006-10-12mhs
Corrected V4L2_PIX_FMT_HM12 description.
Revision 0.162006-10-08mhs
VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.
Revision 0.152006-09-23mhs
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.142006-09-14mr
Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of digital devices.
Revision 0.132006-04-07mhs
Corrected the description of struct v4l2_window clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 defines.
Revision 0.122006-02-03mhs
Corrected the description of struct v4l2_captureparm and v4l2_outputparm.
Revision 0.112006-01-27mhs
Improved the description of struct v4l2_tuner.
Revision 0.102006-01-10mhs
VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
Revision 0.92005-11-27mhs
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.82004-10-04mhs
Somehow a piece of junk slipped into the capture example, removed.
Revision 0.72004-09-19mhs
Fixed video standard selection, control enumeration, downscaling and aspect example. Added read and user pointer i/o to video capture example.
Revision 0.62004-08-01mhs
v4l2_buffer changes, added video capture example, various corrections.
Revision 0.52003-11-05mhs
Pixel format erratum.
Revision 0.42003-09-17mhs
Corrected source and Makefile to generate a PDF. SGML fixes. Added latest API changes. Closed gaps in the history chapter.
Revision 0.32003-02-05mhs
Another draft, more corrections.
Revision 0.22003-01-15mhs
Second draft, with corrections pointed out by Gerd Knorr.
Revision 0.12002-12-01mhs
First draft, based on documentation by Bill Dirks and discussions on the V4L mailing list.

Table of Contents

1. Common API Elements
Opening and Closing Devices
Device Naming
Related Devices
Multiple Opens
Shared Data Streams
Functions
Querying Capabilities
Application Priority
Video Inputs and Outputs
Audio Inputs and Outputs
Tuners and Modulators
Tuners
Modulators
Radio Frequency
Video Standards
Digital Video (DV) Timings
User Controls
Extended Controls
Introduction
The Extended Control API
Enumerating Extended Controls
Creating Control Panels
MPEG Control Reference
Camera Control Reference
FM Transmitter Control Reference
Data Formats
Data Format Negotiation
Image Format Enumeration
Single- and multi-planar APIs
Multi-planar formats
Calls that distinguish between single and multi-planar APIs
Image Cropping, Insertion and Scaling
Cropping Structures
Scaling Adjustments
Examples
Streaming Parameters
2. Image Formats
Single-planar format structure
Multi-planar format structures
Standard Image Formats
Colorspaces
Indexed Format
RGB Formats
Packed RGB formats — Packed RGB formats
V4L2_PIX_FMT_SBGGR8 ('BA81') — Bayer RGB format
V4L2_PIX_FMT_SGBRG8 ('GBRG') — Bayer RGB format
V4L2_PIX_FMT_SGRBG8 ('GRBG') — Bayer RGB format
V4L2_PIX_FMT_SRGGB8 ('RGGB') — Bayer RGB format
V4L2_PIX_FMT_SBGGR16 ('BYR2') — Bayer RGB format
V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'), — 10-bit Bayer formats expanded to 16 bits
V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'), — 12-bit Bayer formats expanded to 16 bits
YUV Formats
Packed YUV formats — Packed YUV formats
V4L2_PIX_FMT_GREY ('GREY') — Grey-scale image
V4L2_PIX_FMT_Y10 ('Y10 ') — Grey-scale image
V4L2_PIX_FMT_Y12 ('Y12 ') — Grey-scale image
V4L2_PIX_FMT_Y10BPACK ('Y10B') — Grey-scale image as a bit-packed array
V4L2_PIX_FMT_Y16 ('Y16 ') — 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_YVYU ('YVYU') — Variation of V4L2_PIX_FMT_YUYV with different order of samples in memory
V4L2_PIX_FMT_VYUY ('VYUY') — Variation of V4L2_PIX_FMT_YUYV with different order of samples in memory
V4L2_PIX_FMT_Y41P ('Y41P') — 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_YUV420M ('YU12M') — Variation of V4L2_PIX_FMT_YUV420 with planes non contiguous in memory.
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
V4L2_PIX_FMT_NV12M ('NV12M') — Variation of V4L2_PIX_FMT_NV12 with planes non contiguous in memory.
V4L2_PIX_FMT_NV12MT ('TM12') — Formats with ½ horizontal and vertical chroma resolution. This format has two planes - one for luminance and one for chrominance. Chroma samples are interleaved. The difference to V4L2_PIX_FMT_NV12 is the memory layout. Pixels are grouped in macroblocks of 64x32 size. The order of macroblocks in memory is also not standard.
V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') — Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. One luminance and one chrominance plane with alternating chroma samples as opposed to V4L2_PIX_FMT_YVU420
V4L2_PIX_FMT_M420 ('M420') — Format with ½ horizontal and vertical chroma resolution, also known as YUV 4:2:0. Hybrid plane line-interleaved layout.
Compressed Formats
Reserved Format Identifiers
3. Input/Output
Read/Write
Streaming I/O (Memory Mapping)
Streaming I/O (User Pointers)
Asynchronous I/O
Buffers
Timecodes
Field Order
4. Interfaces
Video Capture Interface
Querying Capabilities
Supplemental Functions
Image Format Negotiation
Reading Images
Video Overlay Interface
Querying Capabilities
Supplemental Functions
Setup
Overlay Window
Enabling Overlay
Video Output Interface
Querying Capabilities
Supplemental Functions
Image Format Negotiation
Writing Images
Video Output Overlay Interface
Querying Capabilities
Framebuffer
Overlay Window and Scaling
Enabling Overlay
Codec Interface
Effect Devices Interface
Raw VBI Data Interface
Querying Capabilities
Supplemental Functions
Raw VBI Format Negotiation
Reading and writing VBI images
Sliced VBI Data Interface
Querying Capabilities
Supplemental Functions
Sliced VBI Format Negotiation
Reading and writing sliced VBI data
Sliced VBI Data in MPEG Streams
Teletext Interface
Radio Interface
Querying Capabilities
Supplemental Functions
Programming
RDS Interface
Querying Capabilities
Reading RDS data
Writing RDS data
RDS datastructures
Event Interface
Sub-device Interface
Controls
Events
Pad-level Formats
Media Bus Formats
5. V4L2 Driver Programming
6. Libv4l Userspace Library
Introduction
libv4lconvert
libv4l1
libv4l2
v4l1compat.so wrapper library
7. Changes
Differences between V4L and V4L2
Opening and Closing Devices
Querying Capabilities
Video Sources
Tuning
Image Properties
Audio
Frame Buffer Overlay
Cropping
Reading Images, Memory Mapping
Reading Raw VBI Data
Miscellaneous
Changes of the V4L2 API
Early Versions
V4L2 Version 0.16 1999-01-31
V4L2 Version 0.18 1999-03-16
V4L2 Version 0.19 1999-06-05
V4L2 Version 0.20 (1999-09-10)
V4L2 Version 0.20 incremental changes
V4L2 Version 0.20 2000-11-23
V4L2 Version 0.20 2002-07-25
V4L2 in Linux 2.5.46, 2002-10
V4L2 2003-06-19
V4L2 2003-11-05
V4L2 in Linux 2.6.6, 2004-05-09
V4L2 in Linux 2.6.8
V4L2 spec erratum 2004-08-01
V4L2 in Linux 2.6.14
V4L2 in Linux 2.6.15
V4L2 spec erratum 2005-11-27
V4L2 spec erratum 2006-01-10
V4L2 spec erratum 2006-02-03
V4L2 spec erratum 2006-02-04
V4L2 in Linux 2.6.17
V4L2 spec erratum 2006-09-23 (Draft 0.15)
V4L2 in Linux 2.6.18
V4L2 in Linux 2.6.19
V4L2 spec erratum 2006-10-12 (Draft 0.17)
V4L2 in Linux 2.6.21
V4L2 in Linux 2.6.22
V4L2 in Linux 2.6.24
V4L2 in Linux 2.6.25
V4L2 in Linux 2.6.26
V4L2 in Linux 2.6.27
V4L2 in Linux 2.6.28
V4L2 in Linux 2.6.29
V4L2 in Linux 2.6.30
V4L2 in Linux 2.6.32
V4L2 in Linux 2.6.33
V4L2 in Linux 2.6.34
V4L2 in Linux 2.6.37
V4L2 in Linux 2.6.39
Relation of V4L2 to other Linux multimedia APIs
Experimental API Elements
Obsolete API Elements
A. Function Reference
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_DBG_G_CHIP_IDENT — Identify the chips on a TV card
ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER — Read or write hardware registers
ioctl VIDIOC_DQEVENT — Dequeue event
ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD — Execute an encoder command
ioctl VIDIOC_ENUMAUDIO — Enumerate audio inputs
ioctl VIDIOC_ENUMAUDOUT — Enumerate audio outputs
ioctl VIDIOC_ENUM_DV_PRESETS — Enumerate supported Digital Video presets
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_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_DV_PRESET, VIDIOC_S_DV_PRESET — Query or select the DV preset of the current input or output
ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS — Get or set custom DV timings for input or output
ioctl VIDIOC_G_ENC_INDEX — Get meta data about a compressed video stream
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_QUERY_DV_PRESET — Sense the DV preset received by the current input
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_S_HW_FREQ_SEEK — Perform a hardware frequency seek
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF — Start or stop streaming I/O
ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL — Enumerate frame intervals
ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE — Enumerate media bus frame sizes
ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE — Enumerate media bus formats
ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP — Get or set the crop rectangle on a subdev pad
ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT — Get or set the data format on a subdev pad
ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL — Get or set the frame interval on a subdev pad
ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT — Subscribe or unsubscribe event
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
B. Video For Linux Two Header File
C. Video Capture Example
D. Video Grabber example using libv4l
List of Types
References
Prev   Next
Introduction Home Chapter 1. Common API Elements