Video for Linux Two

June 26, 2003 - Bill Dirks ( bdirks@pacbell.net )

Note: The new draft V4L2 specification for Kernel 2.5 is now at http://bytesex.org/v4l/

I am creating an overhauled Video for Linux API made to be more flexible and extensible, and to support more kinds of devices. The existing API will to keep shipping with Linux to maintain compatibility. I am calling the new API Video for Linux Two (or "V4L2" for short). A user wishing to use the new API installs the Video for Linux Two files, which replace the corresponding files for the original API.

V4L2 is a thorough overhaul of the API with respect to Video for Linux, and not backward compatible with the original API, so drivers already written for Video for Linux will have to be ported to work with V4L2.

Applications should also be ported to make the best use of V4L2, but there is a backward compatibility layer built in to the V4L2 high level driver that translates the old ioctl commands, so many applications written for the original API will still work with V4L2 drivers.

On this page you will find general information about V4L2, and V4L2 resources, including documentation and source code, and links to drivers and applications that have been written for or ported to V4L2.
 
 


Devices, Drivers, Libraries and Applications

At the People & Projects page. This is a list of people who are contributing to V4L2 or doing V4L2-related work, and the projects they are working on. These include specifications, drivers, libraries, and applications.
 
 


Linux Kernel Compatibility

V4L2 can be used on 2.2.x kernels or 2.4.x kernels. Video for Linux is embodied in the videodev.h header file and the videodev or videodevX kernel module. The module that comes with the kernel only supports the original API. To use V4L2 drivers you must get a replacement videodev.h and videodev module that includes V4L2.

The videodev package below works only with 2.2.x kernels, and supports only V4L2 drivers.

A new version, videodevX, that works in 2.2.x and 2.4.x and supports both V4L2 and v4l drivers is now available.
 
 


Documentation

These are the kernel device driver API specifications. The Driver Writer's Guide documents the V4L2 kernel-mode API functions, and provides additional information regarding how to write V4L2 drivers.
 
Video for Linux Two Documentation
Video for Linux Two Devices 1999-09-12
Video Capture API Specification 1999-09-14
Data Services Interface (VBI) Specification 2000-11-23
Codec API Specification 1999-09-13
Effects API Specification 1999-09-19
Video Output Device API Specification 1999-09-19
Standard Image Formats 2003-06-26
Driver Writer's Guide 1999-12-23
All API documents in a gzip'ed tar file: v4l2api.tgz 78 KB

Change Log for the API and Source Code
 
 


Kernel 2.2.x Source Code

For instructions on installing V4L2 see the readme file in the V4L2 source archive. You will need to configure your kernel to include Video for Linux as a module, but disable all the v4l drivers since they will not compile after the original v4l header file has been replaced with the new header file.

The v4l2samp.tgz file includes a sample device drivers which use no hardware, so you can start writing or porting applications to V4L2 even if you don't have V4L2-supported hardware yet. So far video capture and video output sample drivers are included. More information is in the readme file included in the archive.

Notice: On Sep 21, 1999 I introduced some changes into the API that are not backward compatible.
 
 

Kernel 2.2.x Video for Linux Two Source Code
V4L2 source code for kernel 2.2.x. Unpack in /usr/src/linux. videodev20010302.tgz 2001-03-02 (24KB) 
Sample drivers for kernel 2.2.x (v4l2cap.c, v4l2out.c) v4l2samp20000627.tgz 2000-06-27 (32KB)
FTP site for videodev, kernel 2.2.x. Current and previous versions. kernel2.2/videodev
FTP site for sample drivers. kernel2.2/v4l2samp

Configure Video for Linux as a module, and rebuild kernel and kernel modules if necessary.
Download videodev??????.tgz.
# cd /usr/src/linux
# tar zxvf videodev??????.tgz
# make modules; make modules_install

See the drivers/char/v4l2readme.txt file for details.

When you unpack videodev*.tgz in /usr/src/linux, it will overwrite include/linux/videodev.h and drivers/char/videodev.c. You may want to keep backup copies of these files in case you decide to go back to v4l.

Videodev.c and videodev.h are covered by the GPL. The sample drivers are public domain and have no copying or derived-work restrictions of any kind.
 
 


Kernel 2.4.x Source Code

For 2.4.x, the videodev module is replaced by videodevX, originally created by Justin Schoeman. The videodevX module supports both v4l and V4L2 drivers simultaneously. VideodevX should work on 2.2.x kernels also.

Download the videodevX package, and unpack it. It is not meant to unpacked in the kernel source tree, unpack it in some other convenient place. It will create a directory called videodevX with the videodevX source files and a Makefile.

Before installing videodevX you will need to enable Video for Linux in your kernel config as a module, and rebuild your kernel modules if necessary. Then install videodevX. See below.
 
 

Kernel 2.4.x Video for Linux Two Source Code
Latest V4L2 source code for kernel 2.4.x. videodevX-20030626.tgz 2003-06-26 (36KB) 
Latest sample capture driver for 2.4.x. v4l2samp-20020330.tgz 2002-03-30 (20KB)
FTP site for videodevX, kernel 2.4.x. kernel2.4/videodevX
FTP site for sample drivers. kernel2.4/v4l2samp

 
Configure Video for Linux as a module, and rebuild kernel and kernel modules if necessary.
Download videodevX-??????.tgz.
# tar zxvf videodevX-??????.tgz
# cd videodevX
# make
# make install

VideodevX.c and videodev.h are covered by the GPL.
 


V4L2 Sample Applications Source Code

There is a sample capture program, xcaptest.c, which exercises the capture functions of a V4L2 driver, and a video control panel program, vidpanel.c, that exercises the brightness, contrast, etc. controls on a V4L2 device. These require X Windows. In addition, command line programs vcat and vctrl programs are for capturing frames, and setting device parameters are included. All applications work with the sample capture driver.
 

Video for Linux Two Sample Applications
Sample applications (xcaptest, vidpanel, vcat, vctrl). Includes a Makefile apps20020317.tgz 2002-03-17 (10KB)
FTP site for sample applications. apps

The sample applications are public domain (not GPL), and have no copying or derived-work restrictions.
 
 


Help With V4L2 and Contributing

An excellent source of help for general Video for Linux issues is the

video4linux mail list.

If you would like to contribute to the V4L2 project, or have any questions about the API or software supporting it, send me an email. Of course, I will be happy to answer any questions about V4L2 or provide advice or assistance with writing V4L2 drivers or applications.

If you have suggestions or patches for V4L2 source code send them to me at bdirks@pacbell.net . If sending patches, I would ask that you please send patches as (gzip'ed) attachments because it has been my experience that 'patch' almost always rejects patches emailed in the body of a letter due to either tabs converted to spaces or wrapping of long lines.