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