0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _libv4l-introduction:
0005
0006 ************
0007 Introduction
0008 ************
0009
0010 libv4l is a collection of libraries which adds a thin abstraction layer
0011 on top of video4linux2 devices. The purpose of this (thin) layer is to
0012 make it easy for application writers to support a wide variety of
0013 devices without having to write separate code for different devices in
0014 the same class.
0015
0016 An example of using libv4l is provided by
0017 :ref:`v4l2grab <v4l2grab-example>`.
0018
0019 libv4l consists of 3 different libraries:
0020
0021 libv4lconvert
0022 =============
0023
0024 libv4lconvert is a library that converts several different pixelformats
0025 found in V4L2 drivers into a few common RGB and YUY formats.
0026
0027 It currently accepts the following V4L2 driver formats:
0028 :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
0029 :ref:`V4L2_PIX_FMT_NV12_16L16 <V4L2-PIX-FMT-NV12-16L16>`,
0030 :ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`,
0031 :ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`,
0032 :ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`,
0033 :ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`,
0034 :ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`,
0035 :ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`,
0036 :ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`,
0037 :ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
0038 :ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`,
0039 :ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`,
0040 :ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`,
0041 :ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`,
0042 :ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`,
0043 :ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`,
0044 :ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`,
0045 :ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`,
0046 :ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`,
0047 :ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`,
0048 :ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`,
0049 :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`,
0050 :ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`,
0051 :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`,
0052 :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and
0053 :ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`.
0054
0055 Later on libv4lconvert was expanded to also be able to do various video
0056 processing functions to improve webcam video quality. The video
0057 processing is split in to 2 parts: libv4lconvert/control and
0058 libv4lconvert/processing.
0059
0060 The control part is used to offer video controls which can be used to
0061 control the video processing functions made available by
0062 libv4lconvert/processing. These controls are stored application wide
0063 (until reboot) by using a persistent shared memory object.
0064
0065 libv4lconvert/processing offers the actual video processing
0066 functionality.
0067
0068 libv4l1
0069 =======
0070
0071 This library offers functions that can be used to quickly make v4l1
0072 applications work with v4l2 devices. These functions work exactly like
0073 the normal open/close/etc, except that libv4l1 does full emulation of
0074 the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
0075 just pass calls through.
0076
0077 Since those functions are emulations of the old V4L1 API, it shouldn't
0078 be used for new applications.
0079
0080 libv4l2
0081 =======
0082
0083 This library should be used for all modern V4L2 applications.
0084
0085 It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
0086 of just providing the raw output of the device, it enhances the calls in
0087 the sense that it will use libv4lconvert to provide more video formats
0088 and to enhance the image quality.
0089
0090 In most cases, libv4l2 just passes the calls directly through to the
0091 v4l2 driver, intercepting the calls to
0092 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`,
0093 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`,
0094 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
0095 :ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and
0096 :ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in
0097 order to emulate the formats
0098 :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
0099 :ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
0100 :ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and
0101 :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't
0102 available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
0103 keeps enumerating the hardware supported formats, plus the emulated
0104 formats offered by libv4l at the end.
0105
0106 .. _libv4l-ops:
0107
0108 Libv4l device control functions
0109 -------------------------------
0110
0111 The common file operation methods are provided by libv4l.
0112
0113 Those functions operate just like the gcc function ``dup()`` and
0114 V4L2 functions
0115 :c:func:`open()`, :c:func:`close()`,
0116 :c:func:`ioctl()`, :c:func:`read()`,
0117 :c:func:`mmap()` and :c:func:`munmap()`:
0118
0119 .. c:function:: int v4l2_open(const char *file, int oflag, ...)
0120
0121 operates like the :c:func:`open()` function.
0122
0123 .. c:function:: int v4l2_close(int fd)
0124
0125 operates like the :c:func:`close()` function.
0126
0127 .. c:function:: int v4l2_dup(int fd)
0128
0129 operates like the libc ``dup()`` function, duplicating a file handler.
0130
0131 .. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...)
0132
0133 operates like the :c:func:`ioctl()` function.
0134
0135 .. c:function:: int v4l2_read (int fd, void* buffer, size_t n)
0136
0137 operates like the :c:func:`read()` function.
0138
0139 .. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset);
0140
0141 operates like the :c:func:`munmap()` function.
0142
0143 .. c:function:: int v4l2_munmap(void *_start, size_t length);
0144
0145 operates like the :c:func:`munmap()` function.
0146
0147 Those functions provide additional control:
0148
0149 .. c:function:: int v4l2_fd_open(int fd, int v4l2_flags)
0150
0151 opens an already opened fd for further use through v4l2lib and possibly
0152 modify libv4l2's default behavior through the ``v4l2_flags`` argument.
0153 Currently, ``v4l2_flags`` can be ``V4L2_DISABLE_CONVERSION``, to disable
0154 format conversion.
0155
0156 .. c:function:: int v4l2_set_control(int fd, int cid, int value)
0157
0158 This function takes a value of 0 - 65535, and then scales that range to the
0159 actual range of the given v4l control id, and then if the cid exists and is
0160 not locked sets the cid to the scaled value.
0161
0162 .. c:function:: int v4l2_get_control(int fd, int cid)
0163
0164 This function returns a value of 0 - 65535, scaled to from the actual range
0165 of the given v4l control id. when the cid does not exist, could not be
0166 accessed for some reason, or some error occurred 0 is returned.
0167
0168 v4l1compat.so wrapper library
0169 =============================
0170
0171 This library intercepts calls to
0172 :c:func:`open()`, :c:func:`close()`,
0173 :c:func:`ioctl()`, :c:func:`mmap()` and
0174 :c:func:`munmap()`
0175 operations and redirects them to the libv4l counterparts, by using
0176 ``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2
0177 API.
0178
0179 It allows usage of binary legacy applications that still don't use
0180 libv4l.
