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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.