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