Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _output: | |
4 | ||
5 | ********************** | |
6 | Video Output Interface | |
7 | ********************** | |
8 | ||
9 | Video output devices encode stills or image sequences as analog video | |
10 | signal. With this interface applications can control the encoding | |
11 | process and move images from user space to the driver. | |
12 | ||
13 | Conventionally V4L2 video output devices are accessed through character | |
14 | device special files named ``/dev/video`` and ``/dev/video0`` to | |
15 | ``/dev/video63`` with major number 81 and minor numbers 0 to 63. | |
16 | ``/dev/video`` is typically a symbolic link to the preferred video | |
706f8a99 MCC |
17 | device. |
18 | ||
8d4b231a | 19 | .. note:: The same device file names are used also for video capture devices. |
5377d91f MH |
20 | |
21 | ||
22 | Querying Capabilities | |
23 | ===================== | |
24 | ||
25 | Devices supporting the video output interface set the | |
26 | ``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in | |
27 | the ``capabilities`` field of struct | |
e8be7e97 | 28 | :c:type:`v4l2_capability` returned by the |
7347081e | 29 | :ref:`VIDIOC_QUERYCAP` ioctl. As secondary device |
5377d91f MH |
30 | functions they may also support the :ref:`raw VBI output <raw-vbi>` |
31 | (``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or | |
32 | streaming I/O methods must be supported. Modulators and audio outputs | |
33 | are optional. | |
34 | ||
35 | ||
36 | Supplemental Functions | |
37 | ====================== | |
38 | ||
39 | Video output devices shall support :ref:`audio output <audio>`, | |
40 | :ref:`modulator <tuner>`, :ref:`controls <control>`, | |
41 | :ref:`cropping and scaling <crop>` and | |
42 | :ref:`streaming parameter <streaming-par>` ioctls as needed. The | |
43 | :ref:`video output <video>` and :ref:`video standard <standard>` | |
44 | ioctls must be supported by all video output devices. | |
45 | ||
46 | ||
47 | Image Format Negotiation | |
48 | ======================== | |
49 | ||
50 | The output is determined by cropping and image format parameters. The | |
51 | former select an area of the video picture where the image will appear, | |
52 | the latter how images are stored in memory, i. e. in RGB or YUV format, | |
53 | the number of bits per pixel or width and height. Together they also | |
54 | 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 writing | |
58 | to 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 | |
e8be7e97 | 65 | a struct :c:type:`v4l2_format` to |
5377d91f | 66 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` |
4e03cb76 | 67 | and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer |
5377d91f | 68 | to this structure. Drivers fill the struct |
e8be7e97 MCC |
69 | :c:type:`v4l2_pix_format` ``pix`` or the struct |
70 | :c:type:`v4l2_pix_format_mplane` ``pix_mp`` | |
5377d91f MH |
71 | member of the ``fmt`` union. |
72 | ||
73 | To request different parameters applications set the ``type`` field of a | |
e8be7e97 MCC |
74 | struct :c:type:`v4l2_format` as above and initialize all |
75 | fields of the struct :c:type:`v4l2_pix_format` | |
5377d91f | 76 | ``vbi`` member of the ``fmt`` union, or better just modify the results |
4e03cb76 | 77 | of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
5377d91f | 78 | ioctl with a pointer to this structure. Drivers may adjust the |
4e03cb76 | 79 | parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` |
5377d91f MH |
80 | does. |
81 | ||
2212ff25 | 82 | Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl |
5377d91f MH |
83 | can be used to learn about hardware limitations without disabling I/O or |
84 | possibly time consuming hardware preparations. | |
85 | ||
e8be7e97 MCC |
86 | The contents of struct :c:type:`v4l2_pix_format` and |
87 | struct :c:type:`v4l2_pix_format_mplane` are | |
5377d91f | 88 | discussed in :ref:`pixfmt`. See also the specification of the |
4e03cb76 MCC |
89 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for |
90 | details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` | |
2212ff25 | 91 | and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all |
4e03cb76 | 92 | requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. |
2212ff25 | 93 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. |
5377d91f MH |
94 | |
95 | ||
96 | Writing Images | |
97 | ============== | |
98 | ||
99 | A video output device may support the :ref:`write() function <rw>` | |
100 | and/or streaming (:ref:`memory mapping <mmap>` or | |
101 | :ref:`user pointer <userp>`) I/O. See :ref:`io` for details. |