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