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) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) *************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) Configuration
^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) Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) select an area in a video signal or a buffer, and to query for default
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) settings and hardware limits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) Video hardware can have various cropping, composing and scaling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) limitations. It may only scale up or down, support only discrete scaling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) factors, or have different scaling abilities in the horizontal and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) vertical directions. Also it may not support scaling at all. At the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) time the cropping/composing rectangles may have to be aligned, and both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) the source and the sink may have arbitrary upper and lower size limits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) Therefore, as usual, drivers are expected to adjust the requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) parameters and return the actual values selected. An application can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) control the rounding behaviour using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) :ref:`constraint flags <v4l2-selection-flags>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) Configuration of video capture
^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) See figure :ref:`sel-targets-capture` for examples of the selection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) targets available for a video capture device. It is recommended to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) configure the cropping targets before to the composing targets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) The range of coordinates of the top left corner, width and height of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) target. It is recommended for the driver developers to put the top/left
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) corner at position ``(0,0)``. The rectangle's coordinates are expressed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) The top left corner, width and height of the source rectangle, that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) active cropping area must lie completely inside the capture boundaries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) The driver may further adjust the requested size and/or position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) according to hardware limitations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) Each capture device has a default source rectangle, given by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) ``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) driver writer considers the complete picture. Drivers shall set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) active crop rectangle to the default when the driver is first loaded,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) but not later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) The composing targets refer to a memory buffer. The limits of composing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) coordinates are expressed in pixels. The rectangle's top/left corner
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) must be located at position ``(0,0)``. The width and height are equal to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) The part of a buffer into which the image is inserted by the hardware is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) coordinates are also expressed in the same coordinate system as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) bounds rectangle. The composing rectangle must lie completely inside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) bounds rectangle. The driver must adjust the composing rectangle to fit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) to the bounding limits. Moreover, the driver can perform other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) adjustments according to hardware limitations. The application can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) control rounding behaviour using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) :ref:`constraint flags <v4l2-selection-flags>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) For capture devices the default composing rectangle is queried using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) ``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) The part of a buffer that is modified by the hardware is given by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) ``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) ``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) during insertion process. All pixels outside this rectangle *must not*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) be changed by the hardware. The content of pixels that lie inside the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) padded area but outside active area is undefined. The application can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) use the padded and active rectangles to detect where the rubbish pixels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) are located and remove them if needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) Configuration of video output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) For output devices targets and ioctls are used similarly to the video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) capture case. The *composing* rectangle refers to the insertion of an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) image into a video signal. The cropping rectangles refer to a memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) buffer. It is recommended to configure the composing targets before to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) the cropping targets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) The cropping targets refer to the memory buffer that contains an image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) to be inserted into a video signal or graphical screen. The limits of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) All coordinates are expressed in pixels. The top/left corner is always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) point ``(0,0)``. The width and height is equal to the image size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) The top left corner, width and height of the source rectangle, that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) the area from which image date are processed by the hardware, is given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) same coordinate system as the bounds rectangle. The active cropping area
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) must lie completely inside the crop boundaries and the driver may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) further adjust the requested size and/or position according to hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) limitations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) For output devices the default cropping rectangle is queried using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) ``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The part of a video signal or graphics display where the image is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) target. The rectangle's coordinates are expressed in pixels. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) composing rectangle must lie completely inside the bounds rectangle. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) driver must adjust the area to fit to the bounding limits. Moreover, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) driver can perform other adjustments according to hardware limitations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) The device has a default composing rectangle, given by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) the driver writer considers the complete picture. It is recommended for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) the driver developers to put the top/left corner at position ``(0,0)``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Drivers shall set the active composing rectangle to the default one when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) the driver is first loaded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The devices may introduce additional content to video signal other than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) an image from memory buffers. It includes borders around an image.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) However, such a padded area is driver-dependent feature not covered by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) this document. Driver developers are encouraged to keep padded rectangle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) equal to active one. The padded target is accessed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) ``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) from the ``V4L2_SEL_TGT_COMPOSE`` target.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Scaling control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) An application can detect if scaling is performed by comparing the width
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) ``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) scaling is applied. The application can compute the scaling ratios using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) these values.