| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _libv4l-introduction: |
| 5 |
|
| 6 |
************ |
| 7 |
Introduction |
| 8 |
************ |
| 9 |
|
| 10 |
libv4l is a collection of libraries which adds a thin abstraction layer |
| 11 |
on top of video4linux2 devices. The purpose of this (thin) layer is to |
| 12 |
make it easy for application writers to support a wide variety of |
| 13 |
devices without having to write separate code for different devices in |
| 14 |
the same class. |
| 15 |
|
| 16 |
An example of using libv4l is provided by |
| 17 |
:ref:`v4l2grab <v4l2grab-example>`. |
| 18 |
|
| 19 |
libv4l consists of 3 different libraries: |
| 20 |
|
| 21 |
libv4lconvert |
| 22 |
============= |
| 23 |
|
| 24 |
libv4lconvert is a library that converts several different pixelformats |
| 25 |
found in V4L2 drivers into a few common RGB and YUY formats. |
| 26 |
|
| 27 |
It currently accepts the following V4L2 driver formats: |
| 28 |
:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, |
| 29 |
:ref:`V4L2_PIX_FMT_NV12_16L16 <V4L2-PIX-FMT-NV12-16L16>`, |
| 30 |
:ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`, |
| 31 |
:ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`, |
| 32 |
:ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`, |
| 33 |
:ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`, |
| 34 |
:ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`, |
| 35 |
:ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`, |
| 36 |
:ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`, |
| 37 |
:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`, |
| 38 |
:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, |
| 39 |
:ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`, |
| 40 |
:ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`, |
| 41 |
:ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`, |
| 42 |
:ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`, |
| 43 |
:ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`, |
| 44 |
:ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`, |
| 45 |
:ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`, |
| 46 |
:ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`, |
| 47 |
:ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`, |
| 48 |
:ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`, |
| 49 |
:ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`, |
| 50 |
:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, |
| 51 |
:ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`, |
| 52 |
:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and |
| 53 |
:ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`. |
| 54 |
|
| 55 |
Later on libv4lconvert was expanded to also be able to do various video |
| 56 |
processing functions to improve webcam video quality. The video |
| 57 |
processing is split in to 2 parts: libv4lconvert/control and |
| 58 |
libv4lconvert/processing. |
| 59 |
|
| 60 |
The control part is used to offer video controls which can be used to |
| 61 |
control the video processing functions made available by |
| 62 |
libv4lconvert/processing. These controls are stored application wide |
| 63 |
(until reboot) by using a persistent shared memory object. |
| 64 |
|
| 65 |
libv4lconvert/processing offers the actual video processing |
| 66 |
functionality. |
| 67 |
|
| 68 |
libv4l1 |
| 69 |
======= |
| 70 |
|
| 71 |
This library offers functions that can be used to quickly make v4l1 |
| 72 |
applications work with v4l2 devices. These functions work exactly like |
| 73 |
the normal open/close/etc, except that libv4l1 does full emulation of |
| 74 |
the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will |
| 75 |
just pass calls through. |
| 76 |
|
| 77 |
Since those functions are emulations of the old V4L1 API, it shouldn't |
| 78 |
be used for new applications. |
| 79 |
|
| 80 |
libv4l2 |
| 81 |
======= |
| 82 |
|
| 83 |
This library should be used for all modern V4L2 applications. |
| 84 |
|
| 85 |
It provides handles to call V4L2 open/ioctl/close/poll methods. Instead |
| 86 |
of just providing the raw output of the device, it enhances the calls in |
| 87 |
the sense that it will use libv4lconvert to provide more video formats |
| 88 |
and to enhance the image quality. |
| 89 |
|
| 90 |
In most cases, libv4l2 just passes the calls directly through to the |
| 91 |
v4l2 driver, intercepting the calls to |
| 92 |
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, |
| 93 |
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, |
| 94 |
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, |
| 95 |
:ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and |
| 96 |
:ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in |
| 97 |
order to emulate the formats |
| 98 |
:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`, |
| 99 |
:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`, |
| 100 |
:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and |
| 101 |
:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't |
| 102 |
available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>` |
| 103 |
keeps enumerating the hardware supported formats, plus the emulated |
| 104 |
formats offered by libv4l at the end. |
| 105 |
|
| 106 |
.. _libv4l-ops: |
| 107 |
|
| 108 |
Libv4l device control functions |
| 109 |
------------------------------- |
| 110 |
|
| 111 |
The common file operation methods are provided by libv4l. |
| 112 |
|
| 113 |
Those functions operate just like the gcc function ``dup()`` and |
| 114 |
V4L2 functions |
| 115 |
:c:func:`open()`, :c:func:`close()`, |
| 116 |
:c:func:`ioctl()`, :c:func:`read()`, |
| 117 |
:c:func:`mmap()` and :c:func:`munmap()`: |
| 118 |
|
| 119 |
.. c:function:: int v4l2_open(const char *file, int oflag, ...) |
| 120 |
|
| 121 |
operates like the :c:func:`open()` function. |
| 122 |
|
| 123 |
.. c:function:: int v4l2_close(int fd) |
| 124 |
|
| 125 |
operates like the :c:func:`close()` function. |
| 126 |
|
| 127 |
.. c:function:: int v4l2_dup(int fd) |
| 128 |
|
| 129 |
operates like the libc ``dup()`` function, duplicating a file handler. |
| 130 |
|
| 131 |
.. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...) |
| 132 |
|
| 133 |
operates like the :c:func:`ioctl()` function. |
| 134 |
|
| 135 |
.. c:function:: int v4l2_read (int fd, void* buffer, size_t n) |
| 136 |
|
| 137 |
operates like the :c:func:`read()` function. |
| 138 |
|
| 139 |
.. c:function:: void *v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); |
| 140 |
|
| 141 |
operates like the :c:func:`mmap()` function. |
| 142 |
|
| 143 |
.. c:function:: int v4l2_munmap(void *_start, size_t length); |
| 144 |
|
| 145 |
operates like the :c:func:`munmap()` function. |
| 146 |
|
| 147 |
Those functions provide additional control: |
| 148 |
|
| 149 |
.. c:function:: int v4l2_fd_open(int fd, int v4l2_flags) |
| 150 |
|
| 151 |
opens an already opened fd for further use through v4l2lib and possibly |
| 152 |
modify libv4l2's default behavior through the ``v4l2_flags`` argument. |
| 153 |
Currently, ``v4l2_flags`` can be ``V4L2_DISABLE_CONVERSION``, to disable |
| 154 |
format conversion. |
| 155 |
|
| 156 |
.. c:function:: int v4l2_set_control(int fd, int cid, int value) |
| 157 |
|
| 158 |
This function takes a value of 0 - 65535, and then scales that range to the |
| 159 |
actual range of the given v4l control id, and then if the cid exists and is |
| 160 |
not locked sets the cid to the scaled value. |
| 161 |
|
| 162 |
.. c:function:: int v4l2_get_control(int fd, int cid) |
| 163 |
|
| 164 |
This function returns a value of 0 - 65535, scaled to from the actual range |
| 165 |
of the given v4l control id. when the cid does not exist, could not be |
| 166 |
accessed for some reason, or some error occurred 0 is returned. |
| 167 |
|
| 168 |
v4l1compat.so wrapper library |
| 169 |
============================= |
| 170 |
|
| 171 |
This library intercepts calls to |
| 172 |
:c:func:`open()`, :c:func:`close()`, |
| 173 |
:c:func:`ioctl()`, :c:func:`mmap()` and |
| 174 |
:c:func:`munmap()` |
| 175 |
operations and redirects them to the libv4l counterparts, by using |
| 176 |
``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2 |
| 177 |
API. |
| 178 |
|
| 179 |
It allows usage of binary legacy applications that still don't use |
| 180 |
libv4l. |