Orange Pi5 kernel

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