Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_SELECTION: |
5377d91f MH |
4 | |
5 | ******************************************** | |
6 | ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION | |
7 | ******************************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
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 | |
5377d91f | 24 | |
586027ce | 25 | |
15e7d615 | 26 | Arguments |
5377d91f MH |
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 | ||
15e7d615 | 38 | Description |
5377d91f MH |
39 | =========== |
40 | ||
41 | The ioctls are used to query and configure selection rectangles. | |
42 | ||
43 | To query the cropping (composing) rectangle set struct | |
e8be7e97 | 44 | :c:type:`v4l2_selection` ``type`` field to the |
5377d91f MH |
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 | |
e8be7e97 | 50 | value of struct :c:type:`v4l2_selection` ``target`` |
5377d91f MH |
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 | |
e8be7e97 | 54 | :c:type:`v4l2_selection` are ignored and they must be |
5377d91f MH |
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 | |
e8be7e97 | 59 | struct :c:type:`v4l2_rect` ``r`` rectangle is filled with |
5377d91f MH |
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 | |
e8be7e97 | 66 | :c:type:`v4l2_selection` ``type`` field to the |
5377d91f MH |
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 | |
e8be7e97 | 72 | value of struct :c:type:`v4l2_selection` ``target`` to |
5377d91f MH |
73 | ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table |
74 | :ref:`v4l2-selections-common` or :ref:`selection-api` for additional | |
e8be7e97 | 75 | targets. The struct :c:type:`v4l2_rect` ``r`` rectangle need |
5377d91f | 76 | to be set to the desired active area. Field struct |
e8be7e97 | 77 | :c:type:`v4l2_selection` ``reserved`` is ignored and |
5377d91f MH |
78 | must be filled with zeros. The driver may adjust coordinates of the |
79 | requested rectangle. An application may introduce constraints to control | |
e8be7e97 | 80 | rounding behaviour. The struct :c:type:`v4l2_selection` |
5377d91f MH |
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 | |
e8be7e97 | 105 | :c:type:`v4l2_selection` ``flags``. |
5377d91f MH |
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 | ||
e8be7e97 | 118 | On success the struct :c:type:`v4l2_rect` ``r`` field |
5377d91f MH |
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 | |
cdb4af0f | 122 | constraints flags have to be violated at then ``ERANGE`` is returned. The |
5377d91f MH |
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 | ||
e8be7e97 | 143 | .. c:type:: v4l2_selection |
5377d91f | 144 | |
5bd4bb78 MCC |
145 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
146 | ||
5377d91f MH |
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 | |
56683d7d | 160 | :c:type:`v4l2_buf_type`). |
5377d91f MH |
161 | |
162 | - .. row 2 | |
163 | ||
164 | - __u32 | |
165 | ||
166 | - ``target`` | |
167 | ||
168 | - Used to select between | |
0579e6e3 | 169 | :ref:`cropping and composing rectangles <v4l2-selections-common>`. |
5377d91f MH |
170 | |
171 | - .. row 3 | |
172 | ||
173 | - __u32 | |
174 | ||
175 | - ``flags`` | |
176 | ||
177 | - Flags controlling the selection rectangle adjustments, refer to | |
0579e6e3 | 178 | :ref:`selection flags <v4l2-selection-flags>`. |
5377d91f MH |
179 | |
180 | - .. row 4 | |
181 | ||
e8be7e97 | 182 | - struct :c:type:`v4l2_rect` |
5377d91f MH |
183 | |
184 | - ``r`` | |
185 | ||
186 | - The selection rectangle. | |
187 | ||
188 | - .. row 5 | |
189 | ||
190 | - __u32 | |
191 | ||
8968da9b | 192 | - ``reserved[9]`` |
5377d91f MH |
193 | |
194 | - Reserved fields for future use. Drivers and applications must zero | |
0579e6e3 | 195 | this array. |
5377d91f MH |
196 | |
197 | ||
15e7d615 | 198 | Return Value |
5377d91f MH |
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 | |
e8be7e97 | 210 | It is not possible to adjust struct :c:type:`v4l2_rect` |
5377d91f MH |
211 | ``r`` rectangle to satisfy all constraints given in the ``flags`` |
212 | argument. | |
213 | ||
3f8d56b0 HV |
214 | ENODATA |
215 | Selection is not supported for this input or output. | |
216 | ||
5377d91f MH |
217 | EBUSY |
218 | It is not possible to apply change of the selection rectangle at the | |
219 | moment. Usually because streaming is in progress. |