Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_ENUM_FRAMESIZES: |
5377d91f MH |
4 | |
5 | **************************** | |
6 | ioctl VIDIOC_ENUM_FRAMESIZES | |
7 | **************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp ) |
5377d91f | 19 | |
586027ce | 20 | |
15e7d615 | 21 | Arguments |
5377d91f MH |
22 | ========= |
23 | ||
24 | ``fd`` | |
25 | File descriptor returned by :ref:`open() <func-open>`. | |
26 | ||
27 | ``request`` | |
28 | VIDIOC_ENUM_FRAMESIZES | |
29 | ||
30 | ``argp`` | |
31 | Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>` | |
32 | that contains an index and pixel format and receives a frame width | |
33 | and height. | |
34 | ||
35 | ||
15e7d615 | 36 | Description |
5377d91f MH |
37 | =========== |
38 | ||
39 | This ioctl allows applications to enumerate all frame sizes (i. e. width | |
40 | and height in pixels) that the device supports for the given pixel | |
41 | format. | |
42 | ||
43 | The supported pixel formats can be obtained by using the | |
7347081e | 44 | :ref:`VIDIOC_ENUM_FMT` function. |
5377d91f MH |
45 | |
46 | The return value and the content of the ``v4l2_frmsizeenum.type`` field | |
47 | depend on the type of frame sizes the device supports. Here are the | |
48 | semantics of the function for the different cases: | |
49 | ||
50 | - **Discrete:** The function returns success if the given index value | |
51 | (zero-based) is valid. The application should increase the index by | |
52 | one for each call until ``EINVAL`` is returned. The | |
53 | ``v4l2_frmsizeenum.type`` field is set to | |
54 | ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the | |
55 | ``discrete`` member is valid. | |
56 | ||
57 | - **Step-wise:** The function returns success if the given index value | |
58 | is zero and ``EINVAL`` for any other index value. The | |
59 | ``v4l2_frmsizeenum.type`` field is set to | |
60 | ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the | |
61 | ``stepwise`` member is valid. | |
62 | ||
63 | - **Continuous:** This is a special case of the step-wise type above. | |
64 | The function returns success if the given index value is zero and | |
65 | ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type`` | |
66 | field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of | |
67 | the union only the ``stepwise`` member is valid and the | |
68 | ``step_width`` and ``step_height`` values are set to 1. | |
69 | ||
70 | When the application calls the function with index zero, it must check | |
71 | the ``type`` field to determine the type of frame size enumeration the | |
72 | device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does | |
73 | it make sense to increase the index value to receive more frame sizes. | |
74 | ||
b6b6e678 MCC |
75 | .. note:: |
76 | ||
77 | The order in which the frame sizes are returned has no special | |
706f8a99 MCC |
78 | meaning. In particular does it not say anything about potential default |
79 | format sizes. | |
5377d91f MH |
80 | |
81 | Applications can assume that the enumeration data does not change | |
82 | without any interaction from the application itself. This means that the | |
83 | enumeration data is consistent if the application does not perform any | |
84 | other ioctl calls while it runs the frame size enumeration. | |
85 | ||
86 | ||
87 | Structs | |
88 | ======= | |
89 | ||
90 | In the structs below, *IN* denotes a value that has to be filled in by | |
91 | the application, *OUT* denotes values that the driver fills in. The | |
92 | application should zero out all members except for the *IN* fields. | |
93 | ||
94 | ||
95 | .. _v4l2-frmsize-discrete: | |
96 | ||
97 | .. flat-table:: struct v4l2_frmsize_discrete | |
98 | :header-rows: 0 | |
99 | :stub-columns: 0 | |
100 | :widths: 1 1 2 | |
101 | ||
102 | ||
103 | - .. row 1 | |
104 | ||
105 | - __u32 | |
106 | ||
107 | - ``width`` | |
108 | ||
109 | - Width of the frame [pixel]. | |
110 | ||
111 | - .. row 2 | |
112 | ||
113 | - __u32 | |
114 | ||
115 | - ``height`` | |
116 | ||
117 | - Height of the frame [pixel]. | |
118 | ||
119 | ||
120 | ||
121 | .. _v4l2-frmsize-stepwise: | |
122 | ||
123 | .. flat-table:: struct v4l2_frmsize_stepwise | |
124 | :header-rows: 0 | |
125 | :stub-columns: 0 | |
126 | :widths: 1 1 2 | |
127 | ||
128 | ||
129 | - .. row 1 | |
130 | ||
131 | - __u32 | |
132 | ||
133 | - ``min_width`` | |
134 | ||
135 | - Minimum frame width [pixel]. | |
136 | ||
137 | - .. row 2 | |
138 | ||
139 | - __u32 | |
140 | ||
141 | - ``max_width`` | |
142 | ||
143 | - Maximum frame width [pixel]. | |
144 | ||
145 | - .. row 3 | |
146 | ||
147 | - __u32 | |
148 | ||
149 | - ``step_width`` | |
150 | ||
151 | - Frame width step size [pixel]. | |
152 | ||
153 | - .. row 4 | |
154 | ||
155 | - __u32 | |
156 | ||
157 | - ``min_height`` | |
158 | ||
159 | - Minimum frame height [pixel]. | |
160 | ||
161 | - .. row 5 | |
162 | ||
163 | - __u32 | |
164 | ||
165 | - ``max_height`` | |
166 | ||
167 | - Maximum frame height [pixel]. | |
168 | ||
169 | - .. row 6 | |
170 | ||
171 | - __u32 | |
172 | ||
173 | - ``step_height`` | |
174 | ||
175 | - Frame height step size [pixel]. | |
176 | ||
177 | ||
178 | ||
179 | .. _v4l2-frmsizeenum: | |
180 | ||
181 | .. flat-table:: struct v4l2_frmsizeenum | |
182 | :header-rows: 0 | |
183 | :stub-columns: 0 | |
184 | ||
185 | ||
186 | - .. row 1 | |
187 | ||
188 | - __u32 | |
189 | ||
190 | - ``index`` | |
191 | ||
0579e6e3 | 192 | - |
5377d91f MH |
193 | - IN: Index of the given frame size in the enumeration. |
194 | ||
195 | - .. row 2 | |
196 | ||
197 | - __u32 | |
198 | ||
199 | - ``pixel_format`` | |
200 | ||
0579e6e3 | 201 | - |
5377d91f MH |
202 | - IN: Pixel format for which the frame sizes are enumerated. |
203 | ||
204 | - .. row 3 | |
205 | ||
206 | - __u32 | |
207 | ||
208 | - ``type`` | |
209 | ||
0579e6e3 | 210 | - |
5377d91f MH |
211 | - OUT: Frame size type the device supports. |
212 | ||
213 | - .. row 4 | |
214 | ||
215 | - union | |
216 | ||
0579e6e3 MCC |
217 | - |
218 | - | |
5377d91f MH |
219 | - OUT: Frame size with the given index. |
220 | ||
221 | - .. row 5 | |
222 | ||
0579e6e3 | 223 | - |
5377d91f MH |
224 | - struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>` |
225 | ||
226 | - ``discrete`` | |
227 | ||
0579e6e3 | 228 | - |
5377d91f MH |
229 | |
230 | - .. row 6 | |
231 | ||
0579e6e3 | 232 | - |
5377d91f MH |
233 | - struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>` |
234 | ||
235 | - ``stepwise`` | |
236 | ||
0579e6e3 | 237 | - |
5377d91f MH |
238 | |
239 | - .. row 7 | |
240 | ||
241 | - __u32 | |
242 | ||
8968da9b | 243 | - ``reserved[2]`` |
5377d91f | 244 | |
0579e6e3 | 245 | - |
5377d91f | 246 | - Reserved space for future use. Must be zeroed by drivers and |
0579e6e3 | 247 | applications. |
5377d91f MH |
248 | |
249 | ||
250 | ||
251 | Enums | |
252 | ===== | |
253 | ||
254 | ||
255 | .. _v4l2-frmsizetypes: | |
256 | ||
257 | .. flat-table:: enum v4l2_frmsizetypes | |
258 | :header-rows: 0 | |
259 | :stub-columns: 0 | |
260 | :widths: 3 1 4 | |
261 | ||
262 | ||
263 | - .. row 1 | |
264 | ||
265 | - ``V4L2_FRMSIZE_TYPE_DISCRETE`` | |
266 | ||
267 | - 1 | |
268 | ||
269 | - Discrete frame size. | |
270 | ||
271 | - .. row 2 | |
272 | ||
273 | - ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` | |
274 | ||
275 | - 2 | |
276 | ||
277 | - Continuous frame size. | |
278 | ||
279 | - .. row 3 | |
280 | ||
281 | - ``V4L2_FRMSIZE_TYPE_STEPWISE`` | |
282 | ||
283 | - 3 | |
284 | ||
285 | - Step-wise defined frame size. | |
286 | ||
287 | ||
15e7d615 | 288 | Return Value |
5377d91f MH |
289 | ============ |
290 | ||
291 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
292 | appropriately. The generic error codes are described at the | |
293 | :ref:`Generic Error Codes <gen-errors>` chapter. |