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