Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_PARM: |
5377d91f MH |
4 | |
5 | ********************************** | |
6 | ioctl VIDIOC_G_PARM, VIDIOC_S_PARM | |
7 | ********************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp ) |
19 | :name: VIDIOC_G_PARM | |
20 | ||
21 | .. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp ) | |
22 | :name: VIDIOC_S_PARM | |
5377d91f | 23 | |
586027ce | 24 | |
15e7d615 | 25 | Arguments |
5377d91f MH |
26 | ========= |
27 | ||
28 | ``fd`` | |
29 | File descriptor returned by :ref:`open() <func-open>`. | |
30 | ||
5377d91f MH |
31 | ``argp`` |
32 | ||
33 | ||
15e7d615 | 34 | Description |
5377d91f MH |
35 | =========== |
36 | ||
37 | The current video standard determines a nominal number of frames per | |
38 | second. If less than this number of frames is to be captured or output, | |
39 | applications can request frame skipping or duplicating on the driver | |
760c7010 MCC |
40 | side. This is especially useful when using the :ref:`read() <func-read>` or |
41 | :ref:`write() <func-write>`, which are not augmented by timestamps or sequence | |
5377d91f MH |
42 | counters, and to avoid unnecessary data copying. |
43 | ||
44 | Further these ioctls can be used to determine the number of buffers used | |
45 | internally by a driver in read/write mode. For implications see the | |
46 | section discussing the :ref:`read() <func-read>` function. | |
47 | ||
48 | To get and set the streaming parameters applications call the | |
4e03cb76 | 49 | :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a |
acf309a2 | 50 | pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a |
5377d91f MH |
51 | union holding separate parameters for input and output devices. |
52 | ||
53 | ||
5bd4bb78 MCC |
54 | .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| |
55 | ||
fa92b04d MCC |
56 | .. _v4l2-streamparm: |
57 | ||
5377d91f MH |
58 | .. flat-table:: struct v4l2_streamparm |
59 | :header-rows: 0 | |
60 | :stub-columns: 0 | |
61 | :widths: 1 1 1 2 | |
62 | ||
63 | ||
64 | - .. row 1 | |
65 | ||
66 | - __u32 | |
67 | ||
68 | - ``type`` | |
69 | ||
0579e6e3 | 70 | - |
5377d91f | 71 | - The buffer (stream) type, same as struct |
0579e6e3 MCC |
72 | :ref:`v4l2_format <v4l2-format>` ``type``, set by the |
73 | application. See :ref:`v4l2-buf-type` | |
5377d91f MH |
74 | |
75 | - .. row 2 | |
76 | ||
77 | - union | |
78 | ||
79 | - ``parm`` | |
80 | ||
0579e6e3 MCC |
81 | - |
82 | - | |
5377d91f MH |
83 | |
84 | - .. row 3 | |
85 | ||
0579e6e3 | 86 | - |
5377d91f MH |
87 | - struct :ref:`v4l2_captureparm <v4l2-captureparm>` |
88 | ||
89 | - ``capture`` | |
90 | ||
91 | - Parameters for capture devices, used when ``type`` is | |
0579e6e3 | 92 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE``. |
5377d91f MH |
93 | |
94 | - .. row 4 | |
95 | ||
0579e6e3 | 96 | - |
5377d91f MH |
97 | - struct :ref:`v4l2_outputparm <v4l2-outputparm>` |
98 | ||
99 | - ``output`` | |
100 | ||
101 | - Parameters for output devices, used when ``type`` is | |
0579e6e3 | 102 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT``. |
5377d91f MH |
103 | |
104 | - .. row 5 | |
105 | ||
0579e6e3 | 106 | - |
5377d91f MH |
107 | - __u8 |
108 | ||
8968da9b | 109 | - ``raw_data``\ [200] |
5377d91f MH |
110 | |
111 | - A place holder for future extensions. | |
112 | ||
113 | ||
114 | ||
5bd4bb78 MCC |
115 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
116 | ||
fa92b04d MCC |
117 | .. _v4l2-captureparm: |
118 | ||
5377d91f MH |
119 | .. flat-table:: struct v4l2_captureparm |
120 | :header-rows: 0 | |
121 | :stub-columns: 0 | |
122 | :widths: 1 1 2 | |
123 | ||
124 | ||
125 | - .. row 1 | |
126 | ||
127 | - __u32 | |
128 | ||
129 | - ``capability`` | |
130 | ||
131 | - See :ref:`parm-caps`. | |
132 | ||
133 | - .. row 2 | |
134 | ||
135 | - __u32 | |
136 | ||
137 | - ``capturemode`` | |
138 | ||
139 | - Set by drivers and applications, see :ref:`parm-flags`. | |
140 | ||
141 | - .. row 3 | |
142 | ||
143 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
144 | ||
145 | - ``timeperframe`` | |
146 | ||
147 | - This is the desired period between successive frames captured by | |
0579e6e3 MCC |
148 | the driver, in seconds. The field is intended to skip frames on |
149 | the driver side, saving I/O bandwidth. | |
5377d91f | 150 | |
0579e6e3 MCC |
151 | Applications store here the desired frame period, drivers return |
152 | the actual frame period, which must be greater or equal to the | |
153 | nominal frame period determined by the current video standard | |
154 | (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod`` | |
155 | field). Changing the video standard (also implicitly by switching | |
156 | the video input) may reset this parameter to the nominal frame | |
157 | period. To reset manually applications can just set this field to | |
158 | zero. | |
5377d91f | 159 | |
0579e6e3 MCC |
160 | Drivers support this function only when they set the |
161 | ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. | |
5377d91f MH |
162 | |
163 | - .. row 4 | |
164 | ||
165 | - __u32 | |
166 | ||
167 | - ``extendedmode`` | |
168 | ||
169 | - Custom (driver specific) streaming parameters. When unused, | |
0579e6e3 MCC |
170 | applications and drivers must set this field to zero. Applications |
171 | using this field should check the driver name and version, see | |
172 | :ref:`querycap`. | |
5377d91f MH |
173 | |
174 | - .. row 5 | |
175 | ||
176 | - __u32 | |
177 | ||
178 | - ``readbuffers`` | |
179 | ||
180 | - Applications set this field to the desired number of buffers used | |
0579e6e3 MCC |
181 | internally by the driver in :ref:`read() <func-read>` mode. |
182 | Drivers return the actual number of buffers. When an application | |
183 | requests zero buffers, drivers should just return the current | |
184 | setting rather than the minimum or an error code. For details see | |
185 | :ref:`rw`. | |
5377d91f MH |
186 | |
187 | - .. row 6 | |
188 | ||
189 | - __u32 | |
190 | ||
8968da9b | 191 | - ``reserved``\ [4] |
5377d91f MH |
192 | |
193 | - Reserved for future extensions. Drivers and applications must set | |
0579e6e3 | 194 | the array to zero. |
5377d91f MH |
195 | |
196 | ||
197 | ||
5bd4bb78 MCC |
198 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
199 | ||
fa92b04d MCC |
200 | .. _v4l2-outputparm: |
201 | ||
5377d91f MH |
202 | .. flat-table:: struct v4l2_outputparm |
203 | :header-rows: 0 | |
204 | :stub-columns: 0 | |
205 | :widths: 1 1 2 | |
206 | ||
207 | ||
208 | - .. row 1 | |
209 | ||
210 | - __u32 | |
211 | ||
212 | - ``capability`` | |
213 | ||
214 | - See :ref:`parm-caps`. | |
215 | ||
216 | - .. row 2 | |
217 | ||
218 | - __u32 | |
219 | ||
220 | - ``outputmode`` | |
221 | ||
222 | - Set by drivers and applications, see :ref:`parm-flags`. | |
223 | ||
224 | - .. row 3 | |
225 | ||
226 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
227 | ||
228 | - ``timeperframe`` | |
229 | ||
230 | - This is the desired period between successive frames output by the | |
0579e6e3 | 231 | driver, in seconds. |
5377d91f MH |
232 | |
233 | - .. row 4 | |
234 | ||
235 | - :cspan:`2` | |
236 | ||
0579e6e3 MCC |
237 | The field is intended to repeat frames on the driver side in |
238 | :ref:`write() <func-write>` mode (in streaming mode timestamps | |
239 | can be used to throttle the output), saving I/O bandwidth. | |
5377d91f | 240 | |
0579e6e3 MCC |
241 | Applications store here the desired frame period, drivers return |
242 | the actual frame period, which must be greater or equal to the | |
243 | nominal frame period determined by the current video standard | |
244 | (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod`` | |
245 | field). Changing the video standard (also implicitly by switching | |
246 | the video output) may reset this parameter to the nominal frame | |
247 | period. To reset manually applications can just set this field to | |
248 | zero. | |
5377d91f | 249 | |
0579e6e3 MCC |
250 | Drivers support this function only when they set the |
251 | ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. | |
5377d91f MH |
252 | |
253 | - .. row 5 | |
254 | ||
255 | - __u32 | |
256 | ||
257 | - ``extendedmode`` | |
258 | ||
259 | - Custom (driver specific) streaming parameters. When unused, | |
0579e6e3 MCC |
260 | applications and drivers must set this field to zero. Applications |
261 | using this field should check the driver name and version, see | |
262 | :ref:`querycap`. | |
5377d91f MH |
263 | |
264 | - .. row 6 | |
265 | ||
266 | - __u32 | |
267 | ||
268 | - ``writebuffers`` | |
269 | ||
270 | - Applications set this field to the desired number of buffers used | |
0579e6e3 MCC |
271 | internally by the driver in :ref:`write() <func-write>` mode. Drivers |
272 | return the actual number of buffers. When an application requests | |
273 | zero buffers, drivers should just return the current setting | |
274 | rather than the minimum or an error code. For details see | |
275 | :ref:`rw`. | |
5377d91f MH |
276 | |
277 | - .. row 7 | |
278 | ||
279 | - __u32 | |
280 | ||
8968da9b | 281 | - ``reserved``\ [4] |
5377d91f MH |
282 | |
283 | - Reserved for future extensions. Drivers and applications must set | |
0579e6e3 | 284 | the array to zero. |
5377d91f MH |
285 | |
286 | ||
287 | ||
5bd4bb78 MCC |
288 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
289 | ||
fa92b04d MCC |
290 | .. _parm-caps: |
291 | ||
5377d91f MH |
292 | .. flat-table:: Streaming Parameters Capabilites |
293 | :header-rows: 0 | |
294 | :stub-columns: 0 | |
295 | :widths: 3 1 4 | |
296 | ||
297 | ||
298 | - .. row 1 | |
299 | ||
300 | - ``V4L2_CAP_TIMEPERFRAME`` | |
301 | ||
302 | - 0x1000 | |
303 | ||
304 | - The frame skipping/repeating controlled by the ``timeperframe`` | |
0579e6e3 | 305 | field is supported. |
5377d91f MH |
306 | |
307 | ||
308 | ||
5bd4bb78 MCC |
309 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
310 | ||
fa92b04d MCC |
311 | .. _parm-flags: |
312 | ||
5377d91f MH |
313 | .. flat-table:: Capture Parameters Flags |
314 | :header-rows: 0 | |
315 | :stub-columns: 0 | |
316 | :widths: 3 1 4 | |
317 | ||
318 | ||
319 | - .. row 1 | |
320 | ||
321 | - ``V4L2_MODE_HIGHQUALITY`` | |
322 | ||
323 | - 0x0001 | |
324 | ||
325 | - High quality imaging mode. High quality mode is intended for still | |
0579e6e3 MCC |
326 | imaging applications. The idea is to get the best possible image |
327 | quality that the hardware can deliver. It is not defined how the | |
328 | driver writer may achieve that; it will depend on the hardware and | |
329 | the ingenuity of the driver writer. High quality mode is a | |
330 | different mode from the regular motion video capture modes. In | |
331 | high quality mode: | |
5377d91f | 332 | |
0579e6e3 MCC |
333 | - The driver may be able to capture higher resolutions than for |
334 | motion capture. | |
5377d91f | 335 | |
0579e6e3 MCC |
336 | - The driver may support fewer pixel formats than motion capture |
337 | (eg; true color). | |
5377d91f | 338 | |
0579e6e3 MCC |
339 | - The driver may capture and arithmetically combine multiple |
340 | successive fields or frames to remove color edge artifacts and | |
341 | reduce the noise in the video data. | |
5377d91f | 342 | |
0579e6e3 MCC |
343 | - The driver may capture images in slices like a scanner in order |
344 | to handle larger format images than would otherwise be | |
345 | possible. | |
5377d91f | 346 | |
0579e6e3 MCC |
347 | - An image capture operation may be significantly slower than |
348 | motion capture. | |
5377d91f | 349 | |
0579e6e3 | 350 | - Moving objects in the image might have excessive motion blur. |
5377d91f | 351 | |
0579e6e3 | 352 | - Capture might only work through the :ref:`read() <func-read>` call. |
5377d91f MH |
353 | |
354 | ||
15e7d615 | 355 | Return Value |
5377d91f MH |
356 | ============ |
357 | ||
358 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
359 | appropriately. The generic error codes are described at the | |
360 | :ref:`Generic Error Codes <gen-errors>` chapter. |