Documentation/media/uapi/v4l/libv4l-introduction.rst

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