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