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/userspace-api/media/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******************************************** 13ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION 14******************************************** 15 16Name 17==== 18 19VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles 20 21 22Synopsis 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 33Arguments 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 42Description 43=========== 44 45The ioctls are used to query and configure selection rectangles. 46 47To query the cropping (composing) rectangle set struct 48:c:type:`v4l2_selection` ``type`` field to the 49respective buffer type. The next step is setting the 50value of struct :c:type:`v4l2_selection` ``target`` 51field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer 52to table :ref:`v4l2-selections-common` or :ref:`selection-api` for 53additional targets. The ``flags`` and ``reserved`` fields of struct 54:c:type:`v4l2_selection` are ignored and they must be 55filled with zeros. The driver fills the rest of the structure or returns 56EINVAL error code if incorrect buffer type or target was used. If 57cropping (composing) is not supported then the active rectangle is not 58mutable and it is always equal to the bounds rectangle. Finally, the 59struct :c:type:`v4l2_rect` ``r`` rectangle is filled with 60the current cropping (composing) coordinates. The coordinates are 61expressed in driver-dependent units. The only exception are rectangles 62for images in raw formats, whose coordinates are always expressed in 63pixels. 64 65To change the cropping (composing) rectangle set the struct 66:c:type:`v4l2_selection` ``type`` field to the 67respective buffer type. The next step is setting the 68value 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 71targets. The struct :c:type:`v4l2_rect` ``r`` rectangle need 72to be set to the desired active area. Field struct 73:c:type:`v4l2_selection` ``reserved`` is ignored and 74must be filled with zeros. The driver may adjust coordinates of the 75requested rectangle. An application may introduce constraints to control 76rounding 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 92Please refer to :ref:`sel-const-adjust`. 93 94The driver may have to adjusts the requested dimensions against hardware 95limits and other parts as the pipeline, i.e. the bounds given by the 96capture/output window or TV display. The closest possible values of 97horizontal and vertical offset and sizes are chosen according to 98following priority: 99 1001. Satisfy constraints from struct 101 :c:type:`v4l2_selection` ``flags``. 102 1032. Adjust width, height, left, and top to hardware limits and 104 alignments. 105 1063. Keep center of adjusted rectangle as close as possible to the 107 original one. 108 1094. Keep width and height as close as possible to original ones. 110 1115. Keep horizontal and vertical offset as close as possible to original 112 ones. 113 114On success the struct :c:type:`v4l2_rect` ``r`` field 115contains the adjusted rectangle. When the parameters are unsuitable the 116application may modify the cropping (composing) or image parameters and 117repeat the cycle until satisfactory parameters have been negotiated. If 118constraints flags have to be violated at then ``ERANGE`` is returned. The 119error indicates that *there exist no rectangle* that satisfies the 120constraints. 121 122Selection 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 179Return Value 180============ 181 182On success 0 is returned, on error -1 and the ``errno`` variable is set 183appropriately. The generic error codes are described at the 184:ref:`Generic Error Codes <gen-errors>` chapter. 185 186EINVAL 187 Given buffer type ``type`` or the selection target ``target`` is not 188 supported, or the ``flags`` argument is not valid. 189 190ERANGE 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 195ENODATA 196 Selection is not supported for this input or output. 197 198EBUSY 199 It is not possible to apply change of the selection rectangle at the 200 moment. Usually because streaming is in progress. 201
