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