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