5.1. Introduction

libv4l is a collection of libraries which adds a thin abstraction layer on top of video4linux2 devices. The purpose of this (thin) layer is to make it easy for application writers to support a wide variety of devices without having to write separate code for different devices in the same class.

An example of using libv4l is provided by v4l2grab.

libv4l consists of 3 different libraries:

5.1.1. libv4lconvert

libv4lconvert is a library that converts several different pixelformats found in V4L2 drivers into a few common RGB and YUY formats.

It currently accepts the following V4L2 driver formats: V4L2_PIX_FMT_BGR24, V4L2_PIX_FMT_HM12, V4L2_PIX_FMT_JPEG, V4L2_PIX_FMT_MJPEG, V4L2_PIX_FMT_MR97310A, V4L2_PIX_FMT_OV511, V4L2_PIX_FMT_OV518, V4L2_PIX_FMT_PAC207, V4L2_PIX_FMT_PJPG, V4L2_PIX_FMT_RGB24, V4L2_PIX_FMT_SBGGR8, V4L2_PIX_FMT_SGBRG8, V4L2_PIX_FMT_SGRBG8, V4L2_PIX_FMT_SN9C10X, V4L2_PIX_FMT_SN9C20X_I420, V4L2_PIX_FMT_SPCA501, V4L2_PIX_FMT_SPCA505, V4L2_PIX_FMT_SPCA508, V4L2_PIX_FMT_SPCA561, V4L2_PIX_FMT_SQ905C, V4L2_PIX_FMT_SRGGB8, V4L2_PIX_FMT_UYVY, V4L2_PIX_FMT_YUV420, V4L2_PIX_FMT_YUYV, V4L2_PIX_FMT_YVU420, and V4L2_PIX_FMT_YVYU.

Later on libv4lconvert was expanded to also be able to do various video processing functions to improve webcam video quality. The video processing is split in to 2 parts: libv4lconvert/control and libv4lconvert/processing.

The control part is used to offer video controls which can be used to control the video processing functions made available by libv4lconvert/processing. These controls are stored application wide (until reboot) by using a persistent shared memory object.

libv4lconvert/processing offers the actual video processing functionality.

5.1.2. libv4l1

This library offers functions that can be used to quickly make v4l1 applications work with v4l2 devices. These functions work exactly like the normal open/close/etc, except that libv4l1 does full emulation of the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will just pass calls through.

Since those functions are emulations of the old V4L1 API, it shouldn't be used for new applications.

5.1.3. libv4l2

This library should be used for all modern V4L2 applications.

It provides handles to call V4L2 open/ioctl/close/poll methods. Instead of just providing the raw output of the device, it enhances the calls in the sense that it will use libv4lconvert to provide more video formats and to enhance the image quality.

In most cases, libv4l2 just passes the calls directly through to the v4l2 driver, intercepting the calls to VIDIOC_TRY_FMT, VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS in order to emulate the formats V4L2_PIX_FMT_BGR24, V4L2_PIX_FMT_RGB24, V4L2_PIX_FMT_YUV420, and V4L2_PIX_FMT_YVU420, if they aren't available in the driver. VIDIOC_ENUM_FMT keeps enumerating the hardware supported formats, plus the emulated formats offered by libv4l at the end.

5.1.3.1. Libv4l device control functions

The common file operation methods are provided by libv4l.

Those functions operate just like the gcc function dup() and V4L2 functions open(), close(), ioctl(), read(), mmap() and munmap():

int v4l2_open(const char *file, int oflag, ...)

operates like the open() function.

int v4l2_close(int fd)

operates like the close() function.

int v4l2_dup(int fd)

operates like the libc dup() function, duplicating a file handler.

int v4l2_ioctl(int fd, unsigned long int request, ...)

operates like the ioctl() function.

int v4l2_read(int fd, void* buffer, size_t n)

operates like the read() function.

void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset);

operates like the munmap() function.

int v4l2_munmap(void *_start, size_t length);

operates like the munmap() function.

Those functions provide additional control:

int v4l2_fd_open(int fd, int v4l2_flags)

opens an already opened fd for further use through v4l2lib and possibly modify libv4l2's default behavior through the v4l2_flags argument. Currently, v4l2_flags can be V4L2_DISABLE_CONVERSION, to disable format conversion.

int v4l2_set_control(int fd, int cid, int value)

This function takes a value of 0 - 65535, and then scales that range to the actual range of the given v4l control id, and then if the cid exists and is not locked sets the cid to the scaled value.

int v4l2_get_control(int fd, int cid)

This function returns a value of 0 - 65535, scaled to from the actual range of the given v4l control id. when the cid does not exist, could not be accessed for some reason, or some error occurred 0 is returned.

5.1.4. v4l1compat.so wrapper library

This library intercepts calls to open(), close(), ioctl(), mmap() and munmap() operations and redirects them to the libv4l counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2 API.

It allows usage of binary legacy applications that still don't use libv4l.