| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _output: |
| 5 |
|
| 6 |
********************** |
| 7 |
Video Output Interface |
| 8 |
********************** |
| 9 |
|
| 10 |
Video output devices encode stills or image sequences as analog video |
| 11 |
signal. With this interface applications can control the encoding |
| 12 |
process and move images from user space to the driver. |
| 13 |
|
| 14 |
Conventionally V4L2 video output 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. |
| 19 |
|
| 20 |
.. note:: The same device file names are used also for video capture devices. |
| 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 |
| 28 |
:c:type:`v4l2_capability` returned by the |
| 29 |
:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device |
| 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 |
Supplemental Functions |
| 36 |
====================== |
| 37 |
|
| 38 |
Video output devices shall support :ref:`audio output <audio>`, |
| 39 |
:ref:`modulator <tuner>`, :ref:`controls <control>`, |
| 40 |
:ref:`cropping and scaling <crop>` and |
| 41 |
:ref:`streaming parameter <streaming-par>` ioctls as needed. The |
| 42 |
:ref:`video output <video>` ioctls must be supported by all video |
| 43 |
output devices. |
| 44 |
|
| 45 |
Image Format Negotiation |
| 46 |
======================== |
| 47 |
|
| 48 |
The output is determined by cropping and image format parameters. The |
| 49 |
former select an area of the video picture where the image will appear, |
| 50 |
the latter how images are stored in memory, i. e. in RGB or YUV format, |
| 51 |
the number of bits per pixel or width and height. Together they also |
| 52 |
define how images are scaled in the process. |
| 53 |
|
| 54 |
As usual these parameters are *not* reset at :c:func:`open()` |
| 55 |
time to permit Unix tool chains, programming a device and then writing |
| 56 |
to it as if it was a plain file. Well written V4L2 applications ensure |
| 57 |
they really get what they want, including cropping and scaling. |
| 58 |
|
| 59 |
Cropping initialization at minimum requires to reset the parameters to |
| 60 |
defaults. An example is given in :ref:`crop`. |
| 61 |
|
| 62 |
To query the current image format applications set the ``type`` field of |
| 63 |
a struct :c:type:`v4l2_format` to |
| 64 |
``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` |
| 65 |
and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer |
| 66 |
to this structure. Drivers fill the struct |
| 67 |
:c:type:`v4l2_pix_format` ``pix`` or the struct |
| 68 |
:c:type:`v4l2_pix_format_mplane` ``pix_mp`` |
| 69 |
member of the ``fmt`` union. |
| 70 |
|
| 71 |
To request different parameters applications set the ``type`` field of a |
| 72 |
struct :c:type:`v4l2_format` as above and initialize all |
| 73 |
fields of the struct :c:type:`v4l2_pix_format` |
| 74 |
``vbi`` member of the ``fmt`` union, or better just modify the results |
| 75 |
of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
| 76 |
ioctl with a pointer to this structure. Drivers may adjust the |
| 77 |
parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` |
| 78 |
does. |
| 79 |
|
| 80 |
Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl |
| 81 |
can be used to learn about hardware limitations without disabling I/O or |
| 82 |
possibly time consuming hardware preparations. |
| 83 |
|
| 84 |
The contents of struct :c:type:`v4l2_pix_format` and |
| 85 |
struct :c:type:`v4l2_pix_format_mplane` are |
| 86 |
discussed in :ref:`pixfmt`. See also the specification of the |
| 87 |
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for |
| 88 |
details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` |
| 89 |
and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all |
| 90 |
requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. |
| 91 |
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. |
| 92 |
|
| 93 |
Writing Images |
| 94 |
============== |
| 95 |
|
| 96 |
A video output device may support the :ref:`write() function <rw>` |
| 97 |
and/or streaming (:ref:`memory mapping <mmap>` or |
| 98 |
:ref:`user pointer <userp>`) I/O. See :ref:`io` for details. |