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