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