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/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _libv4l-introduction:
11
12************
13Introduction
14************
15
16libv4l is a collection of libraries which adds a thin abstraction layer
17on top of video4linux2 devices. The purpose of this (thin) layer is to
18make it easy for application writers to support a wide variety of
19devices without having to write separate code for different devices in
20the same class.
21
22An example of using libv4l is provided by
23:ref:`v4l2grab <v4l2grab-example>`.
24
25libv4l consists of 3 different libraries:
26
27
28libv4lconvert
29=============
30
31libv4lconvert is a library that converts several different pixelformats
32found in V4L2 drivers into a few common RGB and YUY formats.
33
34It 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
62Later on libv4lconvert was expanded to also be able to do various video
63processing functions to improve webcam video quality. The video
64processing is split in to 2 parts: libv4lconvert/control and
65libv4lconvert/processing.
66
67The control part is used to offer video controls which can be used to
68control the video processing functions made available by
69libv4lconvert/processing. These controls are stored application wide
70(until reboot) by using a persistent shared memory object.
71
72libv4lconvert/processing offers the actual video processing
73functionality.
74
75
76libv4l1
77=======
78
79This library offers functions that can be used to quickly make v4l1
80applications work with v4l2 devices. These functions work exactly like
81the normal open/close/etc, except that libv4l1 does full emulation of
82the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
83just pass calls through.
84
85Since those functions are emulations of the old V4L1 API, it shouldn't
86be used for new applications.
87
88
89libv4l2
90=======
91
92This library should be used for all modern V4L2 applications.
93
94It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
95of just providing the raw output of the device, it enhances the calls in
96the sense that it will use libv4lconvert to provide more video formats
97and to enhance the image quality.
98
99In most cases, libv4l2 just passes the calls directly through to the
100v4l2 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
106order 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
111available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
112keeps enumerating the hardware supported formats, plus the emulated
113formats offered by libv4l at the end.
114
115
116.. _libv4l-ops:
117
118Libv4l device control functions
119-------------------------------
120
121The common file operation methods are provided by libv4l.
122
123Those functions operate just like the gcc function ``dup()`` and
124V4L2 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
157Those 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
179v4l1compat.so wrapper library
180=============================
181
182This 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>`
186operations and redirects them to the libv4l counterparts, by using
187``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2
188API.
189
190It allows usage of binary legacy applications that still don't use
191libv4l.
192