1Introduction 2------------ 3 4libv4l is a collection of libraries which adds a thin abstraction layer on 5top of video4linux2 devices. The purpose of this (thin) layer is to make it 6easy for application writers to support a wide variety of devices without 7having to write separate code for different devices in the same class. 8 9All libv4l components are licensed under the GNU Lesser General Public 10License version 2 or (at your option) any later version. 11 12libv4l consists of 3 different libraries: 13 14 15libv4lconvert 16------------- 17 18libv4lconvert started as a library to convert from any (known) pixelformat to 19V4l2_PIX_FMT_BGR24, RGB24, YUV420 or YVU420. 20 21The list of know source formats is large and continually growing, so instead 22of keeping an (almost always outdated) list here in the README, I refer you 23to the source, see the list of defines at the top of 24libv4lconvert/libv4lconvert.c for the full list. 25For more details on the v4lconvert_ functions see libv4lconvert.h. 26 27Later on libv4lconvert was expanded to also be able to do various video 28processing functions to improve webcam video quality on a software basis. So 29the name no longer 100% covers the functionality. The video processing is 30split in to 2 parts, libv4lconvert/control and libv4lconvert/processing. 31 32The control part is used to offer video controls which can be used to control 33the video processing functions made available by libv4lconvert/processing. 34These controls are stored application wide (until reboot) by using a 35persistent shared memory object. 36 37libv4lconvert/processing offers the actual video processing functionality. 38 39 40libv4l1 41------- 42 43This offers functions like v4l1_open, v4l1_ioctl, etc. which can by used to 44quickly make v4l1 applications work with v4l2 devices. These functions work 45exactly like the normal open/close/etc, except that libv4l1 does full emulation 46of the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will just 47pass calls through. For more details on the v4l1_ functions see libv4l1.h . 48 49 50libv4l2 51------- 52 53This offers functions like v4l2_open, v4l2_ioctl, etc. which can by used to 54quickly make v4l2 applications work with v4l2 devices with weird formats. 55libv4l2 mostly passes calls directly through to the v4l2 driver. When the 56app does a TRY_FMT / S_FMT with a not supported format libv4l2 will get in 57the middle and emulate the format (if an app wants to know which formats the 58hardware can _really_ do it should use ENUM_FMT, not randomly try a bunch of 59S_FMT's). For more details on the v4l2_ functions see libv4l2.h . 60 61 62libdvbv5 63-------- 64 65This library provides the DVBv5 API to userspace programs. It can be used to 66open DVB adapters, tune transponders and read PES and other data streams. 67There are as well several parsers for DVB, ATSC, ISBT formats. 68 69The API is currently EXPERIMENTAL and likely to change. 70Run configure with --enable-libdvbv5 in order to build a shared lib and 71install the header files. 72 73 74wrappers 75-------- 76 77The functionality provided by libv4l1 for v4l1 apps and libv4l2 for v4l2 apps 78can also be used by existing apps without modifying them. For this purpose 792 wrapper libraries are provided which can be preloaded before starting the 80application using the LD_PRELOAD environment variable. These wrappers will 81then intercept calls to open/close/ioctl/etc. and if these calls directed 82towards a video device the wrapper will redirect the call to the libv4lX 83counterparts. 84 85The preloadable libv4l1 wrapper which adds v4l2 device compatibility to v4l1 86applications is called v4l1compat.so. The preloadable libv4l2 wrapper which 87adds support for various pixelformats to v4l2 applications is called 88v4l2convert.so. 89 90Example usage (after install in default location): 91$ export LD_PRELOAD=/usr/local/lib/libv4l/v4l1compat.so 92$ camorama 93 94 95Prerequisites 96------------- 97 98libv4l requires shmem file system support in the kernel (CONFIG_SHMEM). 99 100 101FAQ 102--- 103 104Q: Why libv4l, whats wrong with directly accessing v4l2 devices ? 105Q: Do we really need yet another library ? 106A: Current webcam using applications like ekiga contain code to handle many 107different specific pixelformats webcam's use, but that code only supports a 108small subset of all native webcam (compressed) pixelformats. Other current 109v4l2 applications do not support anything but rgb pixelformats (xawtv for 110example) and this will not work with most webcams at all. 111 112With gspca being ported to v4l2 and thus decoding to normal formats being 113removed from the device driver as this really belongs in userspace, ekiga 114would need to be extended with many more often chip dependent formats, like 115the bayer compression used by the spca561 and the (different) compression used 116by the pac207 and the (again different) compression used by the sn9c102. Adding 117support for all these formats should not be done at the application level, as 118then it needs to be written for each application separately. Licensing issues 119with the decompressors will then also become a problem as just cut and pasting 120from one application to another is bound to hit license incompatibilities. 121 122So clearly this belongs in a library, and in a library with a license which 123allows this code to be used from as many different applications as possible. 124Hence libv4l was born. 125 126 127Q: Under which license may I use and distribute libv4l? 128A: The libv4l libraries are licensed under the GNU Library General Publishing 129License version 2 or (at your option) any later version. See the included 130COPYING.LIBV4L file. The decompression helpers are licensed under the GNU 131Library Publishing License version 2 (as they are derived from kernel code) 132 133 134Q: Okay so I get the use of having a libv4lconvert, but why libv4l1 ? 135A: Many v4l2 drivers do not offer full v4l1 compatibility. They often do not 136implemented the CGMBUF ioctl and v4l1 style mmap call. Adding support to all 137these drivers for this is a lot of work and more importantly unnecessary 138adds code to kernel space. 139 140Also even if the CGMBUF ioctl and v4l1 style mmap are supported, then most 141cams still deliver pixelformats which v4l1 applications do not understand. 142 143This libv4l1 was born as an easy way to get v4l1 applications to work with 144v4l2 devices without requiring full v4l1 emulation (including format 145conversion) in the kernel, and without requiring major changes to the 146applications. 147 148 149Q: Why should I use libv4l2 in my app instead of direct device access 150 combined with libv4lconvert? 151A: libv4l2 is mainly meant for quickly and easily adding support for more 152pixelformats to existing v4l2 applications. So if you feel better directly 153accessing the device in combination with libv4lconvert that's fine too. 154 155Notice that libv4l2 also does emulation of the read() call on devices which 156do not support it in the driver. In the background this uses mmap buffers 157(even on devices which do support the read call). This mmap gives libv4lconvert 158zero-copy access to the captured frame, and then it can write the converted 159data directly to the buffer the application provided to v4l2_read(). Thus 160another reason to use libv4l2 is to get the no memcpy advantage of the mmap 161capture method combined with the simplicity of making a simple read() call. 162 163 164Q: Where to send bugreports / questions? 165A: Please send libv4l questions / bugreports to the: 166 Linux Media Mailing List <linux-media@vger.kernel.org> 167 Subscription is not necessary to send mail to this list. If you're not 168 subscribed please put yourself in the CC of your original mail so you 169 will receive replies. 170 171Q: How do I port my application to libv4l1? 172A: Just replace the open call for your device by v4l1_open and all 173 following calls concerning this device file descriptor by their 174 counterpart v4l1_xxx (for a list see libv4l1.h). 175 176Q: How do I port my application to libv4l2? 177A: Just replace the open call for your device by v4l2_open and all 178 following calls concerning this device file descriptor by their 179 counterpart v4l2_xxx (for a list see libv4l2.h). 180 181Q: I still need an example how to convert my application! 182A: Check out the patches for the VLC media player: 183 https://trac.videolan.org/vlc/attachment/ticket/1804/vlc-0.8.6-libv4l1.patch 184 https://trac.videolan.org/vlc/attachment/ticket/1804/vlc-0.9.3-libv4l2.patch 185