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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _libv4l-introduction:
   4
   5 ************
   6 Introduction
   7 ************
   8
   9 libv4l is a collection of libraries which adds a thin abstraction layer
  10 on top of video4linux2 devices. The purpose of this (thin) layer is to
  11 make it easy for application writers to support a wide variety of
  12 devices without having to write separate code for different devices in
  13 the same class.
  14
  15 An example of using libv4l is provided by
  16 :ref:`v4l2grab <v4l2grab-example>`.
  17
  18 libv4l consists of 3 different libraries:
  19
  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_HM12 <V4L2-PIX-FMT-HM12>`,
  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
  69 libv4l1
  70 =======
  71
  72 This library offers functions that can be used to quickly make v4l1
  73 applications work with v4l2 devices. These functions work exactly like
  74 the normal open/close/etc, except that libv4l1 does full emulation of
  75 the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
  76 just pass calls through.
  77
  78 Since those functions are emulations of the old V4L1 API, it shouldn't
  79 be used for new applications.
  80
  81
  82 libv4l2
  83 =======
  84
  85 This library should be used for all modern V4L2 applications.
  86
  87 It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
  88 of just providing the raw output of the device, it enhances the calls in
  89 the sense that it will use libv4lconvert to provide more video formats
  90 and to enhance the image quality.
  91
  92 In most cases, libv4l2 just passes the calls directly through to the
  93 v4l2 driver, intercepting the calls to
  94 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`,
  95 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`,
  96 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
  97 :ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and
  98 :ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in
  99 order to emulate the formats
 100 :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
 101 :ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
 102 :ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and
 103 :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't
 104 available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
 105 keeps enumerating the hardware supported formats, plus the emulated
 106 formats offered by libv4l at the end.
 107
 108
 109 .. _libv4l-ops:
 110
 111 Libv4l device control functions
 112 -------------------------------
 113
 114 The common file operation methods are provided by libv4l.
 115
 116 Those functions operate just like glibc
 117 open/close/dup/ioctl/read/mmap/munmap:
 118
 119 -  :c:type:`int v4l2_open(const char *file, int oflag, ...)` - operates like the
 120    standard :ref:`open() <func-open>` function.
 121
 122 -  :c:type:`int v4l2_close(int fd)` - operates like the standard
 123    :ref:`close() <func-close>` function.
 124
 125 -  :c:type:`int v4l2_dup(int fd)` - operates like the standard dup() function,
 126    duplicating a file handler.
 127
 128 -  :c:type:`int v4l2_ioctl (int fd, unsigned long int request, ...)` - operates
 129    like the standard :ref:`ioctl() <func-ioctl>` function.
 130
 131 -  :c:type:`int v4l2_read (int fd, void* buffer, size_t n)` - operates like the
 132    standard :ref:`read() <func-read>` function.
 133
 134 -  :c:type:`void v4l2_mmap(void *start, size_t length, int prot, int flags, int
 135    fd, int64_t offset);` - operates like the standard
 136    :ref:`mmap() <func-mmap>` function.
 137
 138 -  :c:type:`int v4l2_munmap(void *_start, size_t length);` - operates like the
 139    standard :ref:`munmap() <func-munmap>` function.
 140
 141 Those functions provide additional control:
 142
 143 -  :c:type:`int v4l2_fd_open(int fd, int v4l2_flags)` - opens an already opened
 144    fd for further use through v4l2lib and possibly modify libv4l2's
 145    default behavior through the v4l2_flags argument. Currently,
 146    v4l2_flags can be ``V4L2_DISABLE_CONVERSION``, to disable format
 147    conversion.
 148
 149 -  :c:type:`int v4l2_set_control(int fd, int cid, int value)` - This function
 150    takes a value of 0 - 65535, and then scales that range to the actual
 151    range of the given v4l control id, and then if the cid exists and is
 152    not locked sets the cid to the scaled value.
 153
 154 -  :c:type:`int v4l2_get_control(int fd, int cid)` - This function returns a
 155    value of 0 - 65535, scaled to from the actual range of the given v4l
 156    control id. when the cid does not exist, could not be accessed for
 157    some reason, or some error occurred 0 is returned.
 158
 159
 160 v4l1compat.so wrapper library
 161 =============================
 162
 163 This library intercepts calls to open/close/ioctl/mmap/mmunmap
 164 operations and redirects them to the libv4l counterparts, by using
 165 LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2
 166 API.
 167
 168 It allows usage of binary legacy applications that still don't use
 169 libv4l.