0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _output:
0005
0006 **********************
0007 Video Output Interface
0008 **********************
0009
0010 Video output devices encode stills or image sequences as analog video
0011 signal. With this interface applications can control the encoding
0012 process and move images from user space to the driver.
0013
0014 Conventionally V4L2 video output devices are accessed through character
0015 device special files named ``/dev/video`` and ``/dev/video0`` to
0016 ``/dev/video63`` with major number 81 and minor numbers 0 to 63.
0017 ``/dev/video`` is typically a symbolic link to the preferred video
0018 device.
0019
0020 .. note:: The same device file names are used also for video capture devices.
0021
0022 Querying Capabilities
0023 =====================
0024
0025 Devices supporting the video output interface set the
0026 ``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
0027 the ``capabilities`` field of struct
0028 :c:type:`v4l2_capability` returned by the
0029 :ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
0030 functions they may also support the :ref:`raw VBI output <raw-vbi>`
0031 (``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
0032 streaming I/O methods must be supported. Modulators and audio outputs
0033 are optional.
0034
0035 Supplemental Functions
0036 ======================
0037
0038 Video output devices shall support :ref:`audio output <audio>`,
0039 :ref:`modulator <tuner>`, :ref:`controls <control>`,
0040 :ref:`cropping and scaling <crop>` and
0041 :ref:`streaming parameter <streaming-par>` ioctls as needed. The
0042 :ref:`video output <video>` ioctls must be supported by all video
0043 output devices.
0044
0045 Image Format Negotiation
0046 ========================
0047
0048 The output is determined by cropping and image format parameters. The
0049 former select an area of the video picture where the image will appear,
0050 the latter how images are stored in memory, i. e. in RGB or YUV format,
0051 the number of bits per pixel or width and height. Together they also
0052 define how images are scaled in the process.
0053
0054 As usual these parameters are *not* reset at :c:func:`open()`
0055 time to permit Unix tool chains, programming a device and then writing
0056 to it as if it was a plain file. Well written V4L2 applications ensure
0057 they really get what they want, including cropping and scaling.
0058
0059 Cropping initialization at minimum requires to reset the parameters to
0060 defaults. An example is given in :ref:`crop`.
0061
0062 To query the current image format applications set the ``type`` field of
0063 a struct :c:type:`v4l2_format` to
0064 ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
0065 and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
0066 to this structure. Drivers fill the struct
0067 :c:type:`v4l2_pix_format` ``pix`` or the struct
0068 :c:type:`v4l2_pix_format_mplane` ``pix_mp``
0069 member of the ``fmt`` union.
0070
0071 To request different parameters applications set the ``type`` field of a
0072 struct :c:type:`v4l2_format` as above and initialize all
0073 fields of the struct :c:type:`v4l2_pix_format`
0074 ``vbi`` member of the ``fmt`` union, or better just modify the results
0075 of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
0076 ioctl with a pointer to this structure. Drivers may adjust the
0077 parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
0078 does.
0079
0080 Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
0081 can be used to learn about hardware limitations without disabling I/O or
0082 possibly time consuming hardware preparations.
0083
0084 The contents of struct :c:type:`v4l2_pix_format` and
0085 struct :c:type:`v4l2_pix_format_mplane` are
0086 discussed in :ref:`pixfmt`. See also the specification of the
0087 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
0088 details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
0089 and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
0090 requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
0091 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
0092
0093 Writing Images
0094 ==============
0095
0096 A video output device may support the :ref:`write() function <rw>`
0097 and/or streaming (:ref:`memory mapping <mmap>` or
0098 :ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
