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