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