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