Video For Linux Sample Programs
Documentation

Made by: Aquiles Yáñez Cañas

Introduction

This sample programs are very usefull for test and educational purpose of the Video For Linux API. There are a total of nine programs, the first two make only video capture and video display respectively. Next there are a group of 3 programs who capture video from hardware and displays it in a windows, these programs differ only in the pixel format used (it can be RGB565, RGB24 or YUV420). Finally there are a group of four programs, divided in two server-client aplicattions one for TCP and one for UDP, this aplicacions can transmit and recieve video from the server to the client in a raw format (without compression), this is only an educational aplication, needless to say in real world video transmission without compression is very inefficient.


Sample Programs Description

In the folowing Table every sample program will be describe and the URL for the direct download is showed

ejemplo1

Sample program who capture by memory mapping, a fixed number of frames and stores in a buffer. The video it doesn't showed

ejemplo2_RGB565

This Program open a video window of (640*480), that window shows a one component color (only red, green or blue) and change their intensity every one second and all the range of hues is covered

ejemplo3_RGB565_v0.2

This program continously captures video and shows to a window of 640*480, with a RGB565 pixel format (only works in a 16-bit depth Desktops)

ejemplo3_RGB24_v0.2

This program continously captures video and shows to a window of 640*480, with a RGB24 pixel format (only works in 24-bit depth desktops)

ejemplo3_YUV420_v0.2

This program continously captures video and shows in a window of 640*480, with a YUV420 pixel format (only works in 24-bit depth desktops)

servidorTCP_v0.7

This is the server side program of a server-client application, who transmits video over a TCP connection, from the server to the client, in a raw format without compression

clienteTCP_v0.7

This is the client side program of a server-client application, who transmits video over a TCP connection, from the server to the client in a raw format without compression

servidorUDP_v0.7

This is the server side program of a server-client application, who transmits video over a UDP Datagrams, from the server to the client, in a raw format without compression

clienteUDP_v0.7

This is the client side program of a server-client application, who transmits video over a UDP Datagrams, from the server to the client, in a raw format without compression

These programs were made by Aquiles Yáñez, under the design guidance of Agustín González, with the exception of the image implementation (image.cpp and image.h), that was made in the original version by Ben Bridgwater and modified by Aquiles Yáñez


V4l Drivers Builds Examples

Common Prerequisites

The main prerequisites are the kernel headers and the gcc compiler, these can be installed by the folowing way (in Debian Etch):

$ sudo apt-get install gcc
$ sudo apt-get install libc6-dev
$ sudo apt-get install linux-headers-2.6.18-5-686

where 2.6.18-5-686 is the output of uname -r

qc-usb-messenger

This driver works for the wide used Logitech qc-messenger webcams (usefull for notebooks). The build instructions are:

$ wget http://home.mag.cx/messenger/source/qc-usb-messenger-1.8.tar.gz
$ wget http://bugs.gentoo.org/attachment.cgi?id=167504 -O patch.txt
$ tar xzvf qc-usb-messenger-1.8.tar.gz
$ patch -p0 < patch.txt
$ cd qc-usb-messenger-1.8
$ sudo make install
$ sudo modprobe qcmessenger
$ sudo /usr/sbin/adduser aquiles video

Library Dependencies of Programs

For the programs: ejemplo2_RGB565, ejemplo3_RGB565, ejemplo3_RGB24, ejemplo3_YUV420, clienteTCP_v0.7 y clienteUDP_v0.7, is necesary that the system have installed the xlibs. To install this library use (root):

In Debian Sarge:

# apt-get install xlibs-dev

In Debian Etch:

# apt-get install xlibs-static-dev

Sample Programs Man Page and Build instructions


ejemplo1

This program, captures a fixed number of frames, equal to the simultanously soported number of frames by the device. In addition the program shows information about the configuration settings of the video capture device.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Run the program by the following way:

$ ./ejemplo1

ejemplo2_RGB565

This program opens a window using the low level Xlib library and shows an image of only one color in all the sceen, and every second this color change in 1 unit of the RGB565 pixel format (only one color at every time), when the high limit of the color intensity is reached, the program change to a diferen color and start at the low level of the new color scale. In the third cicle the program returns to the first color, obviously because the RGB pixel format only have 3 colors (mixed of colors was not made)

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Run the program by the following way:

$ ./ejemplo2_RGB565

ejemplo3_RGB565

This program opens a window of 640*480, captures a video stream and shows continously in the window, the video is captured from the default video for linux device (/dev/video0), if you want to change the device, or windows and video capture size, feel free to make the change in the source code (just find the well desciptive variables). The video is captured in a RGB_565 pixel format and showed on a 16 bits window, this means that the program only works well in a desktop with a 16 bit depth of colors.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Run the program by the following way:

$ ./ejemplo3_RGB565

ejemplo3_RGB24

This program opens a window of 640*480, captures a video stream and shows continously in the window, the video is captured from the default video for linux device (/dev/video0), if you want to change the device, or windows and video capture size, feel free to make the change in the source code (just find the well desciptive variables). The video is captured in a RGB_24 pixel format and showed on a 24 bits window, this means that the program only works well in a desktop with a 24 bit depth of colors.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Run the program by the following way:

$ ./ejemplo3_RGB565

ejemplo3_YUV420

This program opens a window of 640*480, captures a video stream and shows in the window, the video is captured from the default video for linux device (/dev/video0), if you want to change the device, or windows and video capture size, feel free to make the change in the source code (just find the well descriptive variables). The video is captured in a RGB_24 pixel format and showed on a 24 bits window, this means that the program only works well in a desktop with a 24 bit depth of colors. Because de video is displayed only in a RGB pixel format, this program needs to do an additional task of converting from YUV420 to RGB24. This piece of code is very interesting, because is a good introduction (of course very basic) to video processing.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Run the program by the following way:

$ ./ejemplo3_YUV420

Demo Client-Server Video Transmission application over TCP

This is a very basic client-server video transmission application, who captures the video with the same video for linux functions of the other programs, and transmit a video stream over the network, without compression, needless to say, in real world compresion is imperative. The transmission is made over a single TCP socket. The server capture and transmit the video and the client receives and displays it. This application is also a very good example of a client server TCP socket transmission application.

Always the server must be executed before of the client

servidorTCP_v0.7

This program first, shows information of the video capture parameters, then waits for a client connection, when this happend, transmits video continously to the client. This server program does not display the video.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Program usage:

./servidorTCP [Listening Port] [640*480 | 320*240]

With:

[Listening Port] The Listening TCP port of the server.
[640*480 | 320*240] The resolution of the transmited video. The supported resolutions are: 640*480 and 320*240. The client program must be configured in the same video resolution.

clienteTCP_v0.7

The client program is responsible for receiving and showing in a window the video transmited by the server. In order to receive the video, uses the function recv several times, and when receives a fixed number of bytes equal to the size of one frame, then display one frame in the window, and next begin with the reception of the next frame, and so on, infinites times.

Para compilar usar:

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Program usage:

$ ./clienteTCP [server IP] [server port] [640*480 | 320*240]

With:

[server IP] The IPv4 address of the server.
[server port] The server TCP port.
[640*480 | 320*240] The resolution of the transmited video (the same configured in the server).

Demo Client-Server Video Transmission application over UDP

This application uses the same video for linux functions for video capture (server) and for display the images (client), used by the former application. But the video transmission implmentation is very diferent. UDP is Datagram oriented, and every datagram could be at last big as the maximun window size, this size (in LAN network) is not enougth for the size of one video frame (the bigest one 640x480). Due to that reason, is necessary a frame fragmentation in rectangules (who fix in a Network max window size), this are horizontal rectangles (all of the same height and width), of the entire width of the screen and ordered from up to down. The total number of rectangles multiplied by the height of one rectangle is equal to the total heigth of one frame.

The transmission is made rectangle by rectangle (one rectangle by datagram) from the upper to the lowest one, until complete the entire frame. And next continuing with the next video frame. In addition in the first byte of every datagram (rectangle) a numeric id (binary format) of the rectangule is send, this is necesary for the client, for the recontruction of the frame

Always the server must be executed before of the client

servidorUDP_v0.7

This program first, shows information of the video capture and network parameters, then waits for a client connection, when this happend, transmits video continously to the client. This server program does not display the video.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Program usage:

./servidorUDP [Listening Port] [640*480 | 320*240]

With:

[Listening Port] The Listening TCP port of the server.
[640*480 | 320*240] The resolution of the transmited video. The supported resolutions are: 640*480 and 320*240. The client program must be configured in the same video resolution.

clienteUDP_v0.7

The client program is responsible for receiving and reconstruc every frame, sent in several paquets for the server. The client program when receive each packet, send some kind of an ACK packet to the server. The server only send the next paquet when receive the ACK paquet, othewise if the server is faster than the client, then data loss may occur. The client can recognize packet loss (with the first byte (id) of every frame). If packet loss occur, the client trows a warning to the standard output, and in the respective rectangle, shows the same position rectangle of the previous frame.

Build the program by the following way:

$ make

Remove binary files by the following way:

$ make clean

Program usage:

$ ./clienteUDP [server IP] [server port] [640*480 | 320*240]

With:

[server IP] The IPv4 address of the server.
[server port] The server TCP port.
[640*480 | 320*240] The resolution of the transmited video (the same configured in the server).

Sample programs execution

TCP server-client application

In order to transmit video (320x240) from a machine with a v4l device (server), to another one with graphic environment (client), the next sentenses are necesary:

In the server:

./servidorTCP 1234 320*240

In the client:

./clienteTCP 192.168.0.4 1234 320*240

V4l Utilities

XAWTV

XAWTV is a tv an video viewer. This program is also very usefull to getting info about video for linux devices. With the following command XAWTV trows info about every device compliant with Video For Linux or Video For Linux II API:

$ xawtv -hwscan
This is xawtv-3.95.dfsg.1, running on Linux/i686 (2.6.18-5-686)
looking for available devices
port 67-67
    type : Xvideo, image scaler
    name : ATI Radeon Video Overlay

/dev/video0: OK                         [ -device /dev/video0 ]
    type : v4l2
    name : Sabrent SBT-TVFM (saa7130)
    flags: overlay capture tuner

ioctl: VIDIOC_QUERYCAP(driver="";card="";bus_info="";version=0.0.0;capabilities=0x0 []): Error desconocido 515
/dev/video1: OK                         [ -device /dev/video1 ]
    type : v4l
    name : Logitech QuickCam USB
    flags:  capture

The type field indicates if the device is v4l or v4l2 compliant.


Appendix - Programming on Video For Linux

This section, shows the most important structures and the basic programming principles in video for linux

The is available, the annex F-1, from the "Memoria de Titulación" of the students Aquiles Yáñez (also the author of these programs) and Mauricio Venegas, made on the second semester of 2005, with the theme "Transmisión de video de alta calida a través de redes IP" (high quality video transmission over IP networks)

Annex F-1

Last modified on: 16/12/2008