Video for Linux Two API Specification

http://v4l2spec.bytesex.org/spec/

 

Video for Linux Two API Specification

Revision 0.24

Michael H Schimek

            <mschimek@gmx.at>
          

Bill Dirks

Hans Verkuil

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.

---

Table of Contents

Introduction

1. Common API Elements

1.1. Opening and Closing Devices

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. Querying Capabilities

1.3. Application Priority

1.4. Video Inputs and Outputs

1.5. Audio Inputs and Outputs

1.6. Tuners and Modulators

1.6.1. Tuners

1.6.2. Modulators

1.6.3. Radio Frequency

1.6.4. Satellite Receivers

1.7. Video Standards

1.8. User Controls

1.9. Extended Controls

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.9.6. Camera Control Reference

1.10. Data Formats

1.10.1. Data Format Negotiation

1.10.2. Image Format Enumeration

1.11. Image Cropping, Insertion and Scaling

1.11.1. Cropping Structures

1.11.2. Scaling Adjustments

1.11.3. Examples

1.12. Streaming Parameters

2. Image Formats

2.1. Standard Image Formats

2.2. Colorspaces

2.3. Indexed Format

2.4. RGB Formats

Packed RGB formats -- Packed RGB formats

V4L2_PIX_FMT_SBGGR8 ('BA81') -- Bayer RGB format

V4L2_PIX_FMT_SBGGR16 ('BA82') -- Bayer RGB format

2.5. YUV Formats

Packed YUV formats -- Packed YUV formats

V4L2_PIX_FMT_GREY ('GREY') -- Grey-scale image

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_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_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.6. Compressed Formats

2.7. Reserved Format Identifiers

3. Input/Output

3.1. Read/Write

3.2. Streaming I/O (Memory Mapping)

3.3. Streaming I/O (User Pointers)

3.4. Asynchronous I/O

3.5. Buffers

3.5.1. Timecodes

3.6. Field Order

4. Interfaces

4.1. Video Capture Interface

4.1.1. Querying Capabilities

4.1.2. Supplemental Functions

4.1.3. Image Format Negotiation

4.1.4. Reading Images

4.2. Video Overlay Interface

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. Video Output Interface

4.3.1. Querying Capabilities

4.3.2. Supplemental Functions

4.3.3. Image Format Negotiation

4.3.4. Writing Images

4.4. Video Output Overlay Interface

4.4.1. Querying Capabilities

4.4.2. Framebuffer

4.4.3. Overlay Window and Scaling

4.4.4. Enabling Overlay

4.5. Codec Interface

4.6. Effect Devices Interface

4.7. Raw VBI Data Interface

4.7.1. Querying Capabilities

4.7.2. Supplemental Functions

4.7.3. Raw VBI Format Negotiation

4.7.4. Reading and writing VBI images

4.8. Sliced VBI Data Interface

4.8.1. Querying Capabilities

4.8.2. Supplemental Functions

4.8.3. Sliced VBI Format Negotiation

4.8.4. Reading and writing sliced VBI data

4.9. Teletext Interface

4.10. Radio Interface

4.10.1. Querying Capabilities

4.10.2. Supplemental Functions

4.10.3. Programming

4.11. RDS Interface

I. 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_REGISTER, VIDIOC_DBG_S_REGISTER -- Read or write hardware registers

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_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_CHIP_IDENT -- Identify the chips on a TV card

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_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_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. V4L2 Driver Programming

6. Changes

6.1. Differences between V4L and V4L2

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. Changes of the V4L2 API

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.2.26. V4L2 in Linux 2.6.21

6.2.27. V4L2 in Linux 2.6.22

6.2.28. V4L2 in Linux 2.6.24

6.2.29. V4L2 in Linux 2.6.25

6.3. Relation of V4L2 to other Linux multimedia APIs

6.3.1. X Video Extension

6.3.2. Digital Video

6.3.3. Audio Interfaces

6.4. Experimental API Elements

6.5. Obsolete API Elements

A. Video For Linux Two Header File

B. Video Capture Example

C. GNU Free Documentation License

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

List of Types

References

List of Figures

1-1. Image Cropping, Insertion and Scaling

3-1. Field Order, Top Field First Transmitted

3-2. Field Order, Bottom Field First Transmitted

4-1. Line synchronization

4-2. ITU-R 525 line numbering (M/NTSC and M/PAL)

4-3. ITU-R 625 line numbering

List of Examples

1-1. Information about the current video input

1-2. Switching to the first video input

1-3. Information about the current audio input

1-4. Switching to the first audio input

1-5. Information about the current video standard

1-6. Listing the video standards supported by the current input

1-7. Selecting a new video standard

1-8. Enumerating all controls

1-9. Changing controls

1-10. Resetting the cropping parameters

1-11. Simple downscaling

1-12. Selecting an output area

1-13. Current scaling factor and pixel aspect

2-1. ITU-R Rec. BT.601 color conversion

2-1. V4L2_PIX_FMT_BGR24 4 × 4 pixel image

2-1. V4L2_PIX_FMT_SBGGR8 4 × 4 pixel image

2-1. V4L2_PIX_FMT_SBGGR16 4 × 4 pixel image

2-1. V4L2_PIX_FMT_GREY 4 × 4 pixel image

2-1. V4L2_PIX_FMT_Y16 4 × 4 pixel image

2-1. V4L2_PIX_FMT_YUYV 4 × 4 pixel image

2-1. V4L2_PIX_FMT_UYVY 4 × 4 pixel image

2-1. V4L2_PIX_FMT_Y41P 8 × 4 pixel image

2-1. V4L2_PIX_FMT_YVU420 4 × 4 pixel image

2-1. V4L2_PIX_FMT_YVU410 4 × 4 pixel image

2-1. V4L2_PIX_FMT_YUV422P 4 × 4 pixel image

2-1. V4L2_PIX_FMT_YUV411P 4 × 4 pixel image

2-1. V4L2_PIX_FMT_NV12 4 × 4 pixel image

3-1. Mapping buffers

3-2. Initiating streaming I/O with user pointers

4-1. Finding a framebuffer device for OSD