Merge remote-tracking branch 'lightnvm/for-next'
[deliverable/linux.git] / Documentation / media / uapi / v4l / libv4l-introduction.rst
CommitLineData
5377d91f
MH
1.. -*- coding: utf-8; mode: rst -*-
2
3.. _libv4l-introduction:
4
5************
6Introduction
7************
8
9libv4l is a collection of libraries which adds a thin abstraction layer
10on top of video4linux2 devices. The purpose of this (thin) layer is to
11make it easy for application writers to support a wide variety of
12devices without having to write separate code for different devices in
13the same class.
14
15An example of using libv4l is provided by
16:ref:`v4l2grab <v4l2grab-example>`.
17
18libv4l consists of 3 different libraries:
19
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>`,
bb2ade02 48:ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`,
5377d91f
MH
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
68
69libv4l1
70=======
71
72This library offers functions that can be used to quickly make v4l1
73applications work with v4l2 devices. These functions work exactly like
74the normal open/close/etc, except that libv4l1 does full emulation of
75the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
76just pass calls through.
77
78Since those functions are emulations of the old V4L1 API, it shouldn't
79be used for new applications.
80
81
82libv4l2
83=======
84
85This library should be used for all modern V4L2 applications.
86
87It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
88of just providing the raw output of the device, it enhances the calls in
89the sense that it will use libv4lconvert to provide more video formats
90and to enhance the image quality.
91
92In most cases, libv4l2 just passes the calls directly through to the
93v4l2 driver, intercepting the calls to
af4a4d0d 94:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`,
bb2ade02
MCC
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
5377d91f
MH
99order 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
bb2ade02 104available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
5377d91f
MH
105keeps enumerating the hardware supported formats, plus the emulated
106formats offered by libv4l at the end.
107
108
109.. _libv4l-ops:
110
111Libv4l device control functions
112-------------------------------
113
114The common file operation methods are provided by libv4l.
115
e452134c
MCC
116Those functions operate just like the gcc function ``dup()`` and
117V4L2 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>`:
5377d91f 121
9281f251 122.. c:function:: int v4l2_open(const char *file, int oflag, ...)
5377d91f 123
e452134c 124 operates like the :c:func:`open() <v4l2-open>` function.
5377d91f 125
9281f251 126.. c:function:: int v4l2_close(int fd)
5377d91f 127
e452134c 128 operates like the :c:func:`close() <v4l2-close>` function.
5377d91f 129
9281f251 130.. c:function:: int v4l2_dup(int fd)
5377d91f 131
e452134c 132 operates like the libc ``dup()`` function, duplicating a file handler.
5377d91f 133
9281f251
MCC
134.. c:function:: int v4l2_ioctl (int fd, unsigned long int request, ...)
135
e452134c 136 operates like the :c:func:`ioctl() <v4l2-ioctl>` function.
9281f251
MCC
137
138.. c:function:: int v4l2_read (int fd, void* buffer, size_t n)
139
e452134c 140 operates like the :c:func:`read() <v4l2-read>` function.
9281f251
MCC
141
142.. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset);
143
e452134c 144 operates like the :c:func:`munmap() <v4l2-munmap>` function.
9281f251
MCC
145
146.. c:function:: int v4l2_munmap(void *_start, size_t length);
e452134c
MCC
147
148 operates like the :c:func:`munmap() <v4l2-munmap>` function.
5377d91f
MH
149
150Those functions provide additional control:
151
9281f251
MCC
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
e452134c
MCC
155 modify libv4l2's default behavior through the ``v4l2_flags`` argument.
156 Currently, ``v4l2_flags`` can be ``V4L2_DISABLE_CONVERSION``, to disable
9281f251 157 format conversion.
5377d91f 158
9281f251
MCC
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
5377d91f
MH
163 not locked sets the cid to the scaled value.
164
9281f251
MCC
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.
5377d91f
MH
170
171
172v4l1compat.so wrapper library
173=============================
174
e452134c
MCC
175This 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>`
5377d91f 179operations and redirects them to the libv4l counterparts, by using
e452134c 180``LD_PRELOAD=/usr/lib/v4l1compat.so``. It also emulates V4L1 calls via V4L2
5377d91f
MH
181API.
182
183It allows usage of binary legacy applications that still don't use
184libv4l.
This page took 0.055773 seconds and 5 git commands to generate.