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) .. _VIDIOC_G_SELECTION:
^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) ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
^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) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) .. c:macro:: VIDIOC_G_SELECTION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) ``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) .. c:macro:: VIDIOC_S_SELECTION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) ``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30)     File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33)     Pointer to struct :c:type:`v4l2_selection`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) Description
^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) The ioctls are used to query and configure selection rectangles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) To query the cropping (composing) rectangle set struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) :c:type:`v4l2_selection` ``type`` field to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) respective buffer type. The next step is setting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) value of struct :c:type:`v4l2_selection` ``target``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) to table :ref:`v4l2-selections-common` or :ref:`selection-api` for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) additional targets. The ``flags`` and ``reserved`` fields of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) :c:type:`v4l2_selection` are ignored and they must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) filled with zeros. The driver fills the rest of the structure or returns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) EINVAL error code if incorrect buffer type or target was used. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) cropping (composing) is not supported then the active rectangle is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) mutable and it is always equal to the bounds rectangle. Finally, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) struct :c:type:`v4l2_rect` ``r`` rectangle is filled with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) the current cropping (composing) coordinates. The coordinates are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) expressed in driver-dependent units. The only exception are rectangles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) for images in raw formats, whose coordinates are always expressed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) To change the cropping (composing) rectangle set the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) :c:type:`v4l2_selection` ``type`` field to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) respective buffer type. The next step is setting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) value of struct :c:type:`v4l2_selection` ``target`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) :ref:`v4l2-selections-common` or :ref:`selection-api` for additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) targets. The struct :c:type:`v4l2_rect` ``r`` rectangle need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) to be set to the desired active area. Field struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) :c:type:`v4l2_selection` ``reserved`` is ignored and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) must be filled with zeros. The driver may adjust coordinates of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) requested rectangle. An application may introduce constraints to control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) rounding behaviour. The struct :c:type:`v4l2_selection`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) ``flags`` field must be set to one of the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) -  ``0`` - The driver can adjust the rectangle size freely and shall
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73)    choose a crop/compose rectangle as close as possible to the requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74)    one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) -  ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77)    rectangle. The original rectangle must lay inside the adjusted one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) -  ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80)    rectangle. The adjusted rectangle must lay inside the original one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) -  ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)    size exactly the same as in the requested rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) Please refer to :ref:`sel-const-adjust`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) The driver may have to adjusts the requested dimensions against hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) limits and other parts as the pipeline, i.e. the bounds given by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) capture/output window or TV display. The closest possible values of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) horizontal and vertical offset and sizes are chosen according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) following priority:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 1. Satisfy constraints from struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94)    :c:type:`v4l2_selection` ``flags``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 2. Adjust width, height, left, and top to hardware limits and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)    alignments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) 3. Keep center of adjusted rectangle as close as possible to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)    original one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 4. Keep width and height as close as possible to original ones.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 5. Keep horizontal and vertical offset as close as possible to original
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)    ones.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) On success the struct :c:type:`v4l2_rect` ``r`` field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) contains the adjusted rectangle. When the parameters are unsuitable the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) application may modify the cropping (composing) or image parameters and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) repeat the cycle until satisfactory parameters have been negotiated. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) constraints flags have to be violated at then ``ERANGE`` is returned. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) error indicates that *there exist no rectangle* that satisfies the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) constraints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Selection targets and flags are documented in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) :ref:`v4l2-selections-common`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) .. _sel-const-adjust:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) .. kernel-figure::  constraints.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)     :alt:    constraints.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)     :align:  center
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)     Size adjustments with constraint flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)     Behaviour of rectangle adjustment for different constraint flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^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) .. c:type:: v4l2_selection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) .. flat-table:: struct v4l2_selection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)     :header-rows:  0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)     :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)     :widths:       1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)     * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)       - ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)       - Type of the buffer (from enum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 	:c:type:`v4l2_buf_type`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)     * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)       - ``target``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)       - Used to select between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) 	:ref:`cropping and composing rectangles <v4l2-selections-common>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)     * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)       - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)       - Flags controlling the selection rectangle adjustments, refer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 	:ref:`selection flags <v4l2-selection-flags>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)     * - struct :c:type:`v4l2_rect`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)       - ``r``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)       - The selection rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)     * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)       - ``reserved[9]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)       - Reserved fields for future use. Drivers and applications must zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) 	this array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)    Unfortunately in the case of multiplanar buffer types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)    (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)    this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)    should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)    other drivers only accepted a non-multiplanar buffer type (i.e. without the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)    ``_MPLANE`` at the end).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)    Starting with kernel 4.13 both variations are allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)     Given buffer type ``type`` or the selection target ``target`` is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)     supported, or the ``flags`` argument is not valid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) ERANGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)     It is not possible to adjust struct :c:type:`v4l2_rect`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)     ``r`` rectangle to satisfy all constraints given in the ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)     argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ENODATA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)     Selection is not supported for this input or output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) EBUSY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)     It is not possible to apply change of the selection rectangle at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)     moment. Usually because streaming is in progress.