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