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 | |
18 | device. Note the same device files are used for video output devices. | |
19 | ||
20 | ||
21 | Querying Capabilities | |
22 | ===================== | |
23 | ||
24 | Devices supporting the video capture interface set the | |
25 | ``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in | |
26 | the ``capabilities`` field of struct | |
27 | :ref:`v4l2_capability <v4l2-capability>` returned by the | |
7347081e | 28 | :ref:`VIDIOC_QUERYCAP` ioctl. As secondary device |
5377d91f MH |
29 | functions they may also support the :ref:`video overlay <overlay>` |
30 | (``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>` | |
31 | (``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or | |
32 | streaming I/O methods must be supported. Tuners and audio inputs are | |
33 | optional. | |
34 | ||
35 | ||
36 | Supplemental Functions | |
37 | ====================== | |
38 | ||
39 | Video capture devices shall support :ref:`audio input <audio>`, | |
7347081e | 40 | :ref:`tuner`, :ref:`controls <control>`, |
5377d91f MH |
41 | :ref:`cropping and scaling <crop>` and |
42 | :ref:`streaming parameter <streaming-par>` ioctls as needed. The | |
43 | :ref:`video input <video>` and :ref:`video standard <standard>` | |
44 | ioctls must be supported by all video capture devices. | |
45 | ||
46 | ||
47 | Image Format Negotiation | |
48 | ======================== | |
49 | ||
50 | The result of a capture operation is determined by cropping and image | |
51 | format parameters. The former select an area of the video picture to | |
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 and height. Together they | |
54 | also define how images are scaled in the process. | |
55 | ||
56 | As usual these parameters are *not* reset at :ref:`open() <func-open>` | |
57 | time to permit Unix tool chains, programming a device and then reading | |
58 | from it as if it was a plain file. Well written V4L2 applications ensure | |
59 | they really get what they want, including cropping and scaling. | |
60 | ||
61 | Cropping initialization at minimum requires to reset the parameters to | |
62 | defaults. An example is given in :ref:`crop`. | |
63 | ||
64 | To query the current image format applications set the ``type`` field of | |
65 | a struct :ref:`v4l2_format <v4l2-format>` to | |
66 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or | |
67 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the | |
4e03cb76 | 68 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this |
5377d91f MH |
69 | structure. Drivers fill the struct |
70 | :ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct | |
71 | :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp`` | |
72 | member of the ``fmt`` union. | |
73 | ||
74 | To request different parameters applications set the ``type`` field of a | |
75 | struct :ref:`v4l2_format <v4l2-format>` as above and initialize all | |
76 | fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>` | |
77 | ``vbi`` member of the ``fmt`` union, or better just modify the results | |
4e03cb76 | 78 | of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
5377d91f | 79 | ioctl with a pointer to this structure. Drivers may adjust the |
4e03cb76 | 80 | parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` |
5377d91f MH |
81 | does. |
82 | ||
2212ff25 | 83 | Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl |
5377d91f MH |
84 | can be used to learn about hardware limitations without disabling I/O or |
85 | possibly time consuming hardware preparations. | |
86 | ||
87 | The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and | |
88 | struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are | |
89 | discussed in :ref:`pixfmt`. See also the specification of the | |
4e03cb76 MCC |
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 both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` | |
2212ff25 | 92 | and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all |
4e03cb76 | 93 | requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. |
2212ff25 | 94 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. |
5377d91f MH |
95 | |
96 | ||
97 | Reading Images | |
98 | ============== | |
99 | ||
100 | A video capture device may support the :ref:`read() function <rw>` | |
101 | and/or streaming (:ref:`memory mapping <mmap>` or | |
102 | :ref:`user pointer <userp>`) I/O. See :ref:`io` for details. | |
103 | ||
104 | ||
105 | .. ------------------------------------------------------------------------------ | |
106 | .. This file was automatically converted from DocBook-XML with the dbxml | |
107 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
108 | .. from the linux kernel, refer to: | |
109 | .. | |
110 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
111 | .. ------------------------------------------------------------------------------ |