Documentation/DocBook/v4l/libv4l.xml

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