Documentation/media/uapi/v4l/vidioc-g-selection.rst

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