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