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 .. _capture: 10 .. _capture:
5 11
6 *********************** 12 ***********************
7 Video Capture Interface 13 Video Capture Interface
8 *********************** 14 ***********************
9 15
10 Video capture devices sample an analog video s 16 Video capture devices sample an analog video signal and store the
11 digitized images in memory. Today nearly all d 17 digitized images in memory. Today nearly all devices can capture at full
12 25 or 30 frames/second. With this interface ap 18 25 or 30 frames/second. With this interface applications can control the
13 capture process and move images from the drive 19 capture process and move images from the driver into user space.
14 20
15 Conventionally V4L2 video capture devices are 21 Conventionally V4L2 video capture devices are accessed through character
16 device special files named ``/dev/video`` and 22 device special files named ``/dev/video`` and ``/dev/video0`` to
17 ``/dev/video63`` with major number 81 and mino 23 ``/dev/video63`` with major number 81 and minor numbers 0 to 63.
18 ``/dev/video`` is typically a symbolic link to 24 ``/dev/video`` is typically a symbolic link to the preferred video
19 device. 25 device.
20 26
21 .. note:: The same device file names are used 27 .. note:: The same device file names are used for video output devices.
22 28
>> 29
23 Querying Capabilities 30 Querying Capabilities
24 ===================== 31 =====================
25 32
26 Devices supporting the video capture interface 33 Devices supporting the video capture interface set the
27 ``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO 34 ``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in
28 the ``capabilities`` field of struct 35 the ``capabilities`` field of struct
29 :c:type:`v4l2_capability` returned by the 36 :c:type:`v4l2_capability` returned by the
30 :ref:`VIDIOC_QUERYCAP` ioctl. As secondary dev 37 :ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
31 functions they may also support the :ref:`vide 38 functions they may also support the :ref:`video overlay <overlay>`
32 (``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw 39 (``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
33 (``V4L2_CAP_VBI_CAPTURE``) interface. At least 40 (``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
34 streaming I/O methods must be supported. Tuner 41 streaming I/O methods must be supported. Tuners and audio inputs are
35 optional. 42 optional.
36 43
>> 44
37 Supplemental Functions 45 Supplemental Functions
38 ====================== 46 ======================
39 47
40 Video capture devices shall support :ref:`audi 48 Video capture devices shall support :ref:`audio input <audio>`,
41 :ref:`tuner`, :ref:`controls <control>`, 49 :ref:`tuner`, :ref:`controls <control>`,
42 :ref:`cropping and scaling <crop>` and 50 :ref:`cropping and scaling <crop>` and
43 :ref:`streaming parameter <streaming-par>` ioc 51 :ref:`streaming parameter <streaming-par>` ioctls as needed. The
44 :ref:`video input <video>` ioctls must be supp 52 :ref:`video input <video>` ioctls must be supported by all video
45 capture devices. 53 capture devices.
46 54
>> 55
47 Image Format Negotiation 56 Image Format Negotiation
48 ======================== 57 ========================
49 58
50 The result of a capture operation is determine 59 The result of a capture operation is determined by cropping and image
51 format parameters. The former select an area o 60 format parameters. The former select an area of the video picture to
52 capture, the latter how images are stored in m 61 capture, the latter how images are stored in memory, i. e. in RGB or YUV
53 format, the number of bits per pixel or width 62 format, the number of bits per pixel or width and height. Together they
54 also define how images are scaled in the proce 63 also define how images are scaled in the process.
55 64
56 As usual these parameters are *not* reset at : !! 65 As usual these parameters are *not* reset at :ref:`open() <func-open>`
57 time to permit Unix tool chains, programming a 66 time to permit Unix tool chains, programming a device and then reading
58 from it as if it was a plain file. Well writte 67 from it as if it was a plain file. Well written V4L2 applications ensure
59 they really get what they want, including crop 68 they really get what they want, including cropping and scaling.
60 69
61 Cropping initialization at minimum requires to 70 Cropping initialization at minimum requires to reset the parameters to
62 defaults. An example is given in :ref:`crop`. 71 defaults. An example is given in :ref:`crop`.
63 72
64 To query the current image format applications 73 To query the current image format applications set the ``type`` field of
65 a struct :c:type:`v4l2_format` to 74 a struct :c:type:`v4l2_format` to
66 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or 75 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
67 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and cal 76 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
68 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with 77 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
69 structure. Drivers fill the struct 78 structure. Drivers fill the struct
70 :c:type:`v4l2_pix_format` ``pix`` or the struc 79 :c:type:`v4l2_pix_format` ``pix`` or the struct
71 :c:type:`v4l2_pix_format_mplane` ``pix_mp`` 80 :c:type:`v4l2_pix_format_mplane` ``pix_mp``
72 member of the ``fmt`` union. 81 member of the ``fmt`` union.
73 82
74 To request different parameters applications s 83 To request different parameters applications set the ``type`` field of a
75 struct :c:type:`v4l2_format` as above and init 84 struct :c:type:`v4l2_format` as above and initialize all
76 fields of the struct :c:type:`v4l2_pix_format` 85 fields of the struct :c:type:`v4l2_pix_format`
77 ``vbi`` member of the ``fmt`` union, or better 86 ``vbi`` member of the ``fmt`` union, or better just modify the results
78 of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and cal 87 of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
79 ioctl with a pointer to this structure. Driver 88 ioctl with a pointer to this structure. Drivers may adjust the
80 parameters and finally return the actual param 89 parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
81 does. 90 does.
82 91
83 Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :r 92 Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
84 can be used to learn about hardware limitation 93 can be used to learn about hardware limitations without disabling I/O or
85 possibly time consuming hardware preparations. 94 possibly time consuming hardware preparations.
86 95
87 The contents of struct :c:type:`v4l2_pix_forma 96 The contents of struct :c:type:`v4l2_pix_format` and
88 struct :c:type:`v4l2_pix_format_mplane` are 97 struct :c:type:`v4l2_pix_format_mplane` are
89 discussed in :ref:`pixfmt`. See also the speci 98 discussed in :ref:`pixfmt`. See also the specification of the
90 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDI 99 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
91 details. Video capture devices must implement 100 details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
92 and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, 101 and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
93 requests and always returns default parameters 102 requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
94 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is option 103 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
>> 104
95 105
96 Reading Images 106 Reading Images
97 ============== 107 ==============
98 108
99 A video capture device may support the :ref:`r 109 A video capture device may support the :ref:`read() function <func-read>`
100 and/or streaming (:ref:`memory mapping <func-m 110 and/or streaming (:ref:`memory mapping <func-mmap>` or
101 :ref:`user pointer <userp>`) I/O. See :ref:`io 111 :ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.