| 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _VIDIOC_G_SELECTION: |
| 4 | |
| 5 | ******************************************** |
| 6 | ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION |
| 7 | ******************************************** |
| 8 | |
| 9 | Name |
| 10 | ==== |
| 11 | |
| 12 | VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles |
| 13 | |
| 14 | |
| 15 | Synopsis |
| 16 | ======== |
| 17 | |
| 18 | .. c:function:: int ioctl( int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp ) |
| 19 | :name: VIDIOC_G_SELECTION |
| 20 | |
| 21 | |
| 22 | .. c:function:: int ioctl( int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp ) |
| 23 | :name: VIDIOC_S_SELECTION |
| 24 | |
| 25 | |
| 26 | Arguments |
| 27 | ========= |
| 28 | |
| 29 | ``fd`` |
| 30 | File descriptor returned by :ref:`open() <func-open>`. |
| 31 | |
| 32 | ``request`` |
| 33 | VIDIOC_G_SELECTION, VIDIOC_S_SELECTION |
| 34 | |
| 35 | ``argp`` |
| 36 | |
| 37 | |
| 38 | Description |
| 39 | =========== |
| 40 | |
| 41 | The ioctls are used to query and configure selection rectangles. |
| 42 | |
| 43 | To query the cropping (composing) rectangle set struct |
| 44 | :c:type:`v4l2_selection` ``type`` field to the |
| 45 | respective buffer type. Do not use the multiplanar buffer types. Use |
| 46 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of |
| 47 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use |
| 48 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of |
| 49 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. 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. Do not use multiplanar buffers. Use |
| 68 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of |
| 69 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use |
| 70 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of |
| 71 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the |
| 72 | value of struct :c:type:`v4l2_selection` ``target`` to |
| 73 | ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table |
| 74 | :ref:`v4l2-selections-common` or :ref:`selection-api` for additional |
| 75 | targets. The struct :c:type:`v4l2_rect` ``r`` rectangle need |
| 76 | to be set to the desired active area. Field struct |
| 77 | :c:type:`v4l2_selection` ``reserved`` is ignored and |
| 78 | must be filled with zeros. The driver may adjust coordinates of the |
| 79 | requested rectangle. An application may introduce constraints to control |
| 80 | rounding behaviour. The struct :c:type:`v4l2_selection` |
| 81 | ``flags`` field must be set to one of the following: |
| 82 | |
| 83 | - ``0`` - The driver can adjust the rectangle size freely and shall |
| 84 | choose a crop/compose rectangle as close as possible to the requested |
| 85 | one. |
| 86 | |
| 87 | - ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the |
| 88 | rectangle. The original rectangle must lay inside the adjusted one. |
| 89 | |
| 90 | - ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the |
| 91 | rectangle. The adjusted rectangle must lay inside the original one. |
| 92 | |
| 93 | - ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the |
| 94 | size exactly the same as in the requested rectangle. |
| 95 | |
| 96 | Please refer to :ref:`sel-const-adjust`. |
| 97 | |
| 98 | The driver may have to adjusts the requested dimensions against hardware |
| 99 | limits and other parts as the pipeline, i.e. the bounds given by the |
| 100 | capture/output window or TV display. The closest possible values of |
| 101 | horizontal and vertical offset and sizes are chosen according to |
| 102 | following priority: |
| 103 | |
| 104 | 1. Satisfy constraints from struct |
| 105 | :c:type:`v4l2_selection` ``flags``. |
| 106 | |
| 107 | 2. Adjust width, height, left, and top to hardware limits and |
| 108 | alignments. |
| 109 | |
| 110 | 3. Keep center of adjusted rectangle as close as possible to the |
| 111 | original one. |
| 112 | |
| 113 | 4. Keep width and height as close as possible to original ones. |
| 114 | |
| 115 | 5. Keep horizontal and vertical offset as close as possible to original |
| 116 | ones. |
| 117 | |
| 118 | On success the struct :c:type:`v4l2_rect` ``r`` field |
| 119 | contains the adjusted rectangle. When the parameters are unsuitable the |
| 120 | application may modify the cropping (composing) or image parameters and |
| 121 | repeat the cycle until satisfactory parameters have been negotiated. If |
| 122 | constraints flags have to be violated at then ``ERANGE`` is returned. The |
| 123 | error indicates that *there exist no rectangle* that satisfies the |
| 124 | constraints. |
| 125 | |
| 126 | Selection targets and flags are documented in |
| 127 | :ref:`v4l2-selections-common`. |
| 128 | |
| 129 | |
| 130 | .. _sel-const-adjust: |
| 131 | |
| 132 | .. figure:: vidioc-g-selection_files/constraints.* |
| 133 | :alt: constraints.png |
| 134 | :align: center |
| 135 | |
| 136 | Size adjustments with constraint flags. |
| 137 | |
| 138 | Behaviour of rectangle adjustment for different constraint flags. |
| 139 | |
| 140 | |
| 141 | |
| 142 | |
| 143 | .. c:type:: v4l2_selection |
| 144 | |
| 145 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
| 146 | |
| 147 | .. flat-table:: struct v4l2_selection |
| 148 | :header-rows: 0 |
| 149 | :stub-columns: 0 |
| 150 | :widths: 1 1 2 |
| 151 | |
| 152 | |
| 153 | - .. row 1 |
| 154 | |
| 155 | - __u32 |
| 156 | |
| 157 | - ``type`` |
| 158 | |
| 159 | - Type of the buffer (from enum |
| 160 | :c:type:`v4l2_buf_type`). |
| 161 | |
| 162 | - .. row 2 |
| 163 | |
| 164 | - __u32 |
| 165 | |
| 166 | - ``target`` |
| 167 | |
| 168 | - Used to select between |
| 169 | :ref:`cropping and composing rectangles <v4l2-selections-common>`. |
| 170 | |
| 171 | - .. row 3 |
| 172 | |
| 173 | - __u32 |
| 174 | |
| 175 | - ``flags`` |
| 176 | |
| 177 | - Flags controlling the selection rectangle adjustments, refer to |
| 178 | :ref:`selection flags <v4l2-selection-flags>`. |
| 179 | |
| 180 | - .. row 4 |
| 181 | |
| 182 | - struct :c:type:`v4l2_rect` |
| 183 | |
| 184 | - ``r`` |
| 185 | |
| 186 | - The selection rectangle. |
| 187 | |
| 188 | - .. row 5 |
| 189 | |
| 190 | - __u32 |
| 191 | |
| 192 | - ``reserved[9]`` |
| 193 | |
| 194 | - Reserved fields for future use. Drivers and applications must zero |
| 195 | this array. |
| 196 | |
| 197 | |
| 198 | Return Value |
| 199 | ============ |
| 200 | |
| 201 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 202 | appropriately. The generic error codes are described at the |
| 203 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 204 | |
| 205 | EINVAL |
| 206 | Given buffer type ``type`` or the selection target ``target`` is not |
| 207 | supported, or the ``flags`` argument is not valid. |
| 208 | |
| 209 | ERANGE |
| 210 | It is not possible to adjust struct :c:type:`v4l2_rect` |
| 211 | ``r`` rectangle to satisfy all constraints given in the ``flags`` |
| 212 | argument. |
| 213 | |
| 214 | ENODATA |
| 215 | Selection is not supported for this input or output. |
| 216 | |
| 217 | EBUSY |
| 218 | It is not possible to apply change of the selection rectangle at the |
| 219 | moment. Usually because streaming is in progress. |