Original Author: JeroenVreeken
Written for Version: 0.90
Translated to TWiki -- KennethLavrsen
- 05 Oct 2004
This document describes the API for the Video4Linux
loopback driver. The driver implements a video pipe using two video4linux devices. The first device is used by the program supplying the data, from now on this program will be refered to with pusher
The second device acts as if it were a normall video4linux device, it should be usable by any application that honours the video4linux specifications. This application will from now on be refered to as client
The calls and ioctls mentioned in this document refer to those as described in the Video4Linux
The loopback device has two operating modes:
- A simple one-copy mode in which pusher specifies the size of the images and the used palette and uses write to push its images to the pipe.
This mode is mostly for feeding fixed size images without any knowledge about client.
- A zero-copy mode in which pusher regularly polls the device if client does an ioctl.
In this mode pusher has almost complete control over the devices behaviour and it will be mainly used to implement complex multiple tuner/channel/size configurations. With this mode it should be possible to use the Xvideo extensions as normal video4linux capture devices.
Locating a free pipe
In order to find an unused pipe pusher
will have to scan the contents of /proc/video/vloopback/
Each pipe will have its own entry in the form of
, N being the total number of available pipes-1.
There will also be a general
file which will contain information on all entries.
Each of these files will have references to the input and output video device and will also indicate if either of them is currently in use.
has found a free pipe it can claim it by simply opening the input device.
In this mode pusher only has to provide images using the
call, the driver will handle the communication with client
or will drop the images if the output is unused. To client
the device will closely resemble a webcam driver.
In order to use it pusher
will open the input device. Before writing it will first have to set the palette it is going to use by calling
, and the size by calling
. After this it can call
for each frame it wants to send to the pipe.
When there is no application using the device the driver will simply drop the frames which will result in a 'no-copy' situation while writing to an unused pipe.
Note: when client is using read() instead of mmap() the driver will actually use a double copy.
In this mode the driver will forward nearly all ioctls to pusher
To initiate this mode pusher
will have to call
with the size of the requested buffer. The driver will allocate memory for this buffer and pusher
will gain access to it.
Note: as the allocated memory might be in use by client, pusher is NOT allowed to touch it under any circumstances with the only exception being between VIDIOCMCAPTURE and VIDIOCSYNC.
has issued an ioctl pusher
will receive a
may check to see if it is comming from vloopback by calling
first. It then has to respond by calling
with a large enough buffer for the largest possible ioctl data structure plus
sizeof(unsigned long int)
. (The largest ioctl data structure is 280 bytes in linux kernel 2.4.0-test10pre1, a buffer of 1024 bytes is recommended.)
The first bytes of this buffer will be the ioctl number. This number is an unsigned long int, the remaining data is the data supplied by client
will now have to handle this ioctl.
If it is an ioctl requesting data pusher
will answer it by calling the ioctl with the requested data.
If it is an ioctl setting data pusher
will call the ioctl with the exact same data to accept it.
will not need to handle any read requests because the kernel module will fake an mmap and sync call for it.
Starting and stopping capture
The first time
is called pusher
should initialize capture and start capturing of the requested frames into the mmapped buffer.
closes its device an
0 will be send with no data, pusher
will tell the hardware to stop.
- 05 Oct 2004