1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2 .. c:namespace:: V4L
3
4 .. _libv4l-introduction:
5
6 ************
7 Introduction
8 ************
9
10 libv4l is a collection of libraries which adds
11 on top of video4linux2 devices. The purpose of
12 make it easy for application writers to suppor
13 devices without having to write separate code
14 the same class.
15
16 An example of using libv4l is provided by
17 :ref:`v4l2grab <v4l2grab-example>`.
18
19 libv4l consists of 3 different libraries:
20
21 libv4lconvert
22 =============
23
24 libv4lconvert is a library that converts sever
25 found in V4L2 drivers into a few common RGB an
26
27 It currently accepts the following V4L2 driver
28 :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`
29 :ref:`V4L2_PIX_FMT_NV12_16L16 <V4L2-PIX-FMT-NV
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-MR97
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-SN9C1
42 :ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-
43 :ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA5
44 :ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA5
45 :ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA5
46 :ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA5
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
53 :ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`.
54
55 Later on libv4lconvert was expanded to also be
56 processing functions to improve webcam video q
57 processing is split in to 2 parts: libv4lconve
58 libv4lconvert/processing.
59
60 The control part is used to offer video contro
61 control the video processing functions made av
62 libv4lconvert/processing. These controls are s
63 (until reboot) by using a persistent shared me
64
65 libv4lconvert/processing offers the actual vid
66 functionality.
67
68 libv4l1
69 =======
70
71 This library offers functions that can be used
72 applications work with v4l2 devices. These fun
73 the normal open/close/etc, except that libv4l1
74 the v4l1 api on top of v4l2 drivers, in case o
75 just pass calls through.
76
77 Since those functions are emulations of the ol
78 be used for new applications.
79
80 libv4l2
81 =======
82
83 This library should be used for all modern V4L
84
85 It provides handles to call V4L2 open/ioctl/cl
86 of just providing the raw output of the device
87 the sense that it will use libv4lconvert to pr
88 and to enhance the image quality.
89
90 In most cases, libv4l2 just passes the calls d
91 v4l2 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_FRAM
96 :ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_
97 order 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
101 :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420
102 available in the driver. :ref:`VIDIOC_ENUM_FMT
103 keeps enumerating the hardware supported forma
104 formats offered by libv4l at the end.
105
106 .. _libv4l-ops:
107
108 Libv4l device control functions
109 -------------------------------
110
111 The common file operation methods are provided
112
113 Those functions operate just like the gcc func
114 V4L2 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
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()` functio
126
127 .. c:function:: int v4l2_dup(int fd)
128
129 operates like the libc ``dup()`` function,
130
131 .. c:function:: int v4l2_ioctl (int fd, unsign
132
133 operates like the :c:func:`ioctl()` functio
134
135 .. c:function:: int v4l2_read (int fd, void* b
136
137 operates like the :c:func:`read()` function
138
139 .. c:function:: void *v4l2_mmap(void *start, s
140
141 operates like the :c:func:`mmap()` function
142
143 .. c:function:: int v4l2_munmap(void *_start,
144
145 operates like the :c:func:`munmap()` functi
146
147 Those functions provide additional control:
148
149 .. c:function:: int v4l2_fd_open(int fd, int v
150
151 opens an already opened fd for further use
152 modify libv4l2's default behavior through t
153 Currently, ``v4l2_flags`` can be ``V4L2_DIS
154 format conversion.
155
156 .. c:function:: int v4l2_set_control(int fd, i
157
158 This function takes a value of 0 - 65535, a
159 actual range of the given v4l control id, a
160 not locked sets the cid to the scaled value
161
162 .. c:function:: int v4l2_get_control(int fd, i
163
164 This function returns a value of 0 - 65535,
165 of the given v4l control id. when the cid d
166 accessed for some reason, or some error occ
167
168 v4l1compat.so wrapper library
169 =============================
170
171 This library intercepts calls to
172 :c:func:`open()`, :c:func:`close()`,
173 :c:func:`ioctl()`, :c:func:`mmap()` and
174 :c:func:`munmap()`
175 operations and redirects them to the libv4l co
176 ``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also
177 API.
178
179 It allows usage of binary legacy applications
180 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.