1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 6. Libv4l Userspace Library</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="v4l2spec.html" title="Part I. Video for Linux Two API Specification"><link rel="prev" href="driver.html" title="Chapter 5. V4L2 Driver Programming"><link rel="next" href="compat.html" title="Chapter 7. Changes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Libv4l Userspace Library</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="driver.html">Prev</a> </td><th width="60%" align="center">Part I. Video for Linux Two API Specification</th><td width="20%" align="right"> <a accesskey="n" href="compat.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="libv4l"></a>Chapter 6. Libv4l Userspace Library</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="libv4l.html#libv4l-introduction">Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="libv4l.html#idp1110684244">libv4lconvert</a></span></dt><dt><span class="section"><a href="libv4l.html#idp1110702668">libv4l1</a></span></dt><dt><span class="section"><a href="libv4l.html#idp1110703876">libv4l2</a></span></dt><dt><span class="section"><a href="libv4l.html#idp1110719444">v4l1compat.so wrapper library</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="libv4l-introduction"></a>Introduction</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="libv4l.html#idp1110684244">libv4lconvert</a></span></dt><dt><span class="section"><a href="libv4l.html#idp1110702668">libv4l1</a></span></dt><dt><span class="section"><a href="libv4l.html#idp1110703876">libv4l2</a></span></dt><dt><span class="section"><a href="libv4l.html#idp1110719444">v4l1compat.so wrapper library</a></span></dt></dl></div><p>libv4l is a collection of libraries which adds a thin abstraction 2layer on top of video4linux2 devices. The purpose of this (thin) layer 3is to make it easy for application writers to support a wide variety of 4devices without having to write separate code for different devices in the 5same class.</p><p>An example of using libv4l is provided by 6<a class="link" href="v4l2grab-example.html" title="Appendix E. Video Grabber example using libv4l">v4l2grab</a>. 7</p><p>libv4l consists of 3 different libraries:</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110684244"></a>libv4lconvert</h3></div></div></div><p>libv4lconvert is a library that converts several 8different pixelformats found in V4L2 drivers into a few common RGB and 9YUY formats.</p><p>It currently accepts the following V4L2 driver formats: 10<a class="link" href="packed-rgb.html#V4L2-PIX-FMT-BGR24"><code class="constant">V4L2_PIX_FMT_BGR24</code></a>, 11<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-HM12"><code class="constant">V4L2_PIX_FMT_HM12</code></a>, 12<a class="link" href="ch02s10.html#V4L2-PIX-FMT-JPEG"><code class="constant">V4L2_PIX_FMT_JPEG</code></a>, 13<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-MJPEG"><code class="constant">V4L2_PIX_FMT_MJPEG</code></a>, 14<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-MR97310A"><code class="constant">V4L2_PIX_FMT_MR97310A</code></a>, 15<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-OV511"><code class="constant">V4L2_PIX_FMT_OV511</code></a>, 16<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-OV518"><code class="constant">V4L2_PIX_FMT_OV518</code></a>, 17<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-PAC207"><code class="constant">V4L2_PIX_FMT_PAC207</code></a>, 18<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-PJPG"><code class="constant">V4L2_PIX_FMT_PJPG</code></a>, 19<a class="link" href="packed-rgb.html#V4L2-PIX-FMT-RGB24"><code class="constant">V4L2_PIX_FMT_RGB24</code></a>, 20<a class="link" href="V4L2-PIX-FMT-SBGGR8.html" title="V4L2_PIX_FMT_SBGGR8 ('BA81')"><code class="constant">V4L2_PIX_FMT_SBGGR8</code></a>, 21<a class="link" href="V4L2-PIX-FMT-SGBRG8.html" title="V4L2_PIX_FMT_SGBRG8 ('GBRG')"><code class="constant">V4L2_PIX_FMT_SGBRG8</code></a>, 22<a class="link" href="V4L2-PIX-FMT-SGRBG8.html" title="V4L2_PIX_FMT_SGRBG8 ('GRBG')"><code class="constant">V4L2_PIX_FMT_SGRBG8</code></a>, 23<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SN9C10X"><code class="constant">V4L2_PIX_FMT_SN9C10X</code></a>, 24<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SN9C20X-I420"><code class="constant">V4L2_PIX_FMT_SN9C20X_I420</code></a>, 25<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SPCA501"><code class="constant">V4L2_PIX_FMT_SPCA501</code></a>, 26<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SPCA505"><code class="constant">V4L2_PIX_FMT_SPCA505</code></a>, 27<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SPCA508"><code class="constant">V4L2_PIX_FMT_SPCA508</code></a>, 28<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SPCA561"><code class="constant">V4L2_PIX_FMT_SPCA561</code></a>, 29<a class="link" href="pixfmt-reserved.html#V4L2-PIX-FMT-SQ905C"><code class="constant">V4L2_PIX_FMT_SQ905C</code></a>, 30<code class="constant">V4L2_PIX_FMT_SRGGB8</code>, 31<a class="link" href="V4L2-PIX-FMT-UYVY.html" title="V4L2_PIX_FMT_UYVY ('UYVY')"><code class="constant">V4L2_PIX_FMT_UYVY</code></a>, 32<a class="link" href="re24.html#V4L2-PIX-FMT-YUV420"><code class="constant">V4L2_PIX_FMT_YUV420</code></a>, 33<a class="link" href="V4L2-PIX-FMT-YUYV.html" title="V4L2_PIX_FMT_YUYV ('YUYV')"><code class="constant">V4L2_PIX_FMT_YUYV</code></a>, 34<a class="link" href="re24.html#V4L2-PIX-FMT-YVU420"><code class="constant">V4L2_PIX_FMT_YVU420</code></a>, 35and <a class="link" href="V4L2-PIX-FMT-YVYU.html" title="V4L2_PIX_FMT_YVYU ('YVYU')"><code class="constant">V4L2_PIX_FMT_YVYU</code></a>. 36</p><p>Later on libv4lconvert was expanded to also be able to do 37various video processing functions to improve webcam video quality. 38The video processing is split in to 2 parts: libv4lconvert/control and 39libv4lconvert/processing.</p><p>The control part is used to offer video controls which can 40be used to control the video processing functions made available by 41 libv4lconvert/processing. These controls are stored application wide 42(until reboot) by using a persistent shared memory object.</p><p>libv4lconvert/processing offers the actual video 43processing functionality.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110702668"></a>libv4l1</h3></div></div></div><p>This library offers functions that can be used to quickly 44make v4l1 applications work with v4l2 devices. These functions work exactly 45like the normal open/close/etc, except that libv4l1 does full emulation of 46the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it 47will just pass calls through.</p><p>Since those functions are emulations of the old V4L1 API, 48it shouldn't be used for new applications.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110703876"></a>libv4l2</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="libv4l.html#libv4l-ops">Libv4l device control functions</a></span></dt></dl></div><p>This library should be used for all modern V4L2 49applications.</p><p>It provides handles to call V4L2 open/ioctl/close/poll 50methods. Instead of just providing the raw output of the device, it enhances 51the calls in the sense that it will use libv4lconvert to provide more video 52formats and to enhance the image quality.</p><p>In most cases, libv4l2 just passes the calls directly 53through to the v4l2 driver, intercepting the calls to 54<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_TRY_FMT</code></a>, 55<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> 56<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> 57<a class="link" href="vidioc-enum-framesizes.html" title="ioctl VIDIOC_ENUM_FRAMESIZES"><code class="constant">VIDIOC_ENUM_FRAMESIZES</code></a> 58and <a class="link" href="vidioc-enum-frameintervals.html" title="ioctl VIDIOC_ENUM_FRAMEINTERVALS"><code class="constant">VIDIOC_ENUM_FRAMEINTERVALS</code></a> 59in order to emulate the formats 60<a class="link" href="packed-rgb.html#V4L2-PIX-FMT-BGR24"><code class="constant">V4L2_PIX_FMT_BGR24</code></a>, 61<a class="link" href="packed-rgb.html#V4L2-PIX-FMT-RGB24"><code class="constant">V4L2_PIX_FMT_RGB24</code></a>, 62<a class="link" href="re24.html#V4L2-PIX-FMT-YUV420"><code class="constant">V4L2_PIX_FMT_YUV420</code></a>, 63and <a class="link" href="re24.html#V4L2-PIX-FMT-YVU420"><code class="constant">V4L2_PIX_FMT_YVU420</code></a>, 64if they aren't available in the driver. 65<a class="link" href="vidioc-enum-fmt.html" title="ioctl VIDIOC_ENUM_FMT"><code class="constant">VIDIOC_ENUM_FMT</code></a> 66keeps enumerating the hardware supported formats, plus the emulated formats 67offered by libv4l at the end. 68</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="libv4l-ops"></a>Libv4l device control functions</h4></div></div></div><p>The common file operation methods are provided by 69libv4l.</p><p>Those functions operate just like glibc 70open/close/dup/ioctl/read/mmap/munmap:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>int v4l2_open(const char *file, int oflag, 71...) - 72operates like the standard <a class="link" href="func-open.html" title="V4L2 open()">open()</a> function. 73</p></li><li class="listitem"><p>int v4l2_close(int fd) - 74operates like the standard <a class="link" href="func-close.html" title="V4L2 close()">close()</a> function. 75</p></li><li class="listitem"><p>int v4l2_dup(int fd) - 76operates like the standard dup() function, duplicating a file handler. 77</p></li><li class="listitem"><p>int v4l2_ioctl (int fd, unsigned long int request, ...) - 78operates like the standard <a class="link" href="func-ioctl.html" title="V4L2 ioctl()">ioctl()</a> function. 79</p></li><li class="listitem"><p>int v4l2_read (int fd, void* buffer, size_t n) - 80operates like the standard <a class="link" href="func-read.html" title="V4L2 read()">read()</a> function. 81</p></li><li class="listitem"><p>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - 82operates like the standard <a class="link" href="func-mmap.html" title="V4L2 mmap()">mmap()</a> function. 83</p></li><li class="listitem"><p>int v4l2_munmap(void *_start, size_t length); - 84operates like the standard <a class="link" href="func-munmap.html" title="V4L2 munmap()">munmap()</a> function. 85</p></li></ul></div><p>Those functions provide additional control:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>int v4l2_fd_open(int fd, int v4l2_flags) - 86opens an already opened fd for further use through v4l2lib and possibly 87modify libv4l2's default behavior through the v4l2_flags argument. 88Currently, v4l2_flags can be <code class="constant">V4L2_DISABLE_CONVERSION</code>, 89to disable format conversion. 90</p></li><li class="listitem"><p>int v4l2_set_control(int fd, int cid, int value) - 91This function takes a value of 0 - 65535, and then scales that range to 92the actual range of the given v4l control id, and then if the cid exists 93and is not locked sets the cid to the scaled value. 94</p></li><li class="listitem"><p>int v4l2_get_control(int fd, int cid) - 95This function returns a value of 0 - 65535, scaled to from the actual range 96of the given v4l control id. when the cid does not exist, could not be 97accessed for some reason, or some error occurred 0 is returned. 98</p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110719444"></a>v4l1compat.so wrapper library</h3></div></div></div><p>This library intercepts calls to 99open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l 100counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also 101emulates V4L1 calls via V4L2 API.</p><p>It allows usage of binary legacy applications that 102still don't use libv4l.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="driver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="v4l2spec.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="compat.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. V4L2 Driver Programming </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Changes</td></tr></table></div></body></html> 103