1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _output:
11
12**********************
13Video Output Interface
14**********************
15
16Video output devices encode stills or image sequences as analog video
17signal. With this interface applications can control the encoding
18process and move images from user space to the driver.
19
20Conventionally V4L2 video output devices are accessed through character
21device special files named ``/dev/video`` and ``/dev/video0`` to
22``/dev/video63`` with major number 81 and minor numbers 0 to 63.
23``/dev/video`` is typically a symbolic link to the preferred video
24device.
25
26.. note:: The same device file names are used also for video capture devices.
27
28
29Querying Capabilities
30=====================
31
32Devices supporting the video output interface set the
33``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
34the ``capabilities`` field of struct
35:c:type:`v4l2_capability` returned by the
36:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
37functions they may also support the :ref:`raw VBI output <raw-vbi>`
38(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
39streaming I/O methods must be supported. Modulators and audio outputs
40are optional.
41
42
43Supplemental Functions
44======================
45
46Video output devices shall support :ref:`audio output <audio>`,
47:ref:`modulator <tuner>`, :ref:`controls <control>`,
48:ref:`cropping and scaling <crop>` and
49:ref:`streaming parameter <streaming-par>` ioctls as needed. The
50:ref:`video output <video>` ioctls must be supported by all video
51output devices.
52
53
54Image Format Negotiation
55========================
56
57The output is determined by cropping and image format parameters. The
58former select an area of the video picture where the image will appear,
59the latter how images are stored in memory, i. e. in RGB or YUV format,
60the number of bits per pixel or width and height. Together they also
61define how images are scaled in the process.
62
63As usual these parameters are *not* reset at :ref:`open() <func-open>`
64time to permit Unix tool chains, programming a device and then writing
65to it as if it was a plain file. Well written V4L2 applications ensure
66they really get what they want, including cropping and scaling.
67
68Cropping initialization at minimum requires to reset the parameters to
69defaults. An example is given in :ref:`crop`.
70
71To query the current image format applications set the ``type`` field of
72a struct :c:type:`v4l2_format` to
73``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
74and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
75to this structure. Drivers fill the struct
76:c:type:`v4l2_pix_format` ``pix`` or the struct
77:c:type:`v4l2_pix_format_mplane` ``pix_mp``
78member of the ``fmt`` union.
79
80To request different parameters applications set the ``type`` field of a
81struct :c:type:`v4l2_format` as above and initialize all
82fields of the struct :c:type:`v4l2_pix_format`
83``vbi`` member of the ``fmt`` union, or better just modify the results
84of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
85ioctl with a pointer to this structure. Drivers may adjust the
86parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
87does.
88
89Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
90can be used to learn about hardware limitations without disabling I/O or
91possibly time consuming hardware preparations.
92
93The contents of struct :c:type:`v4l2_pix_format` and
94struct :c:type:`v4l2_pix_format_mplane` are
95discussed in :ref:`pixfmt`. See also the specification of the
96:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
97details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
98and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
99requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
100:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
101
102
103Writing Images
104==============
105
106A video output device may support the :ref:`write() function <rw>`
107and/or streaming (:ref:`memory mapping <mmap>` or
108:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
109