Merge remote-tracking branch 'iommu/next'
[deliverable/linux.git] / Documentation / media / uapi / v4l / vidioc-g-parm.rst
CommitLineData
5377d91f
MH
1.. -*- coding: utf-8; mode: rst -*-
2
af4a4d0d 3.. _VIDIOC_G_PARM:
5377d91f
MH
4
5**********************************
6ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
7**********************************
8
15e7d615 9Name
586027ce 10====
5377d91f 11
586027ce 12VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
5377d91f 13
15e7d615
MCC
14
15Synopsis
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 25Arguments
5377d91f
MH
26=========
27
28``fd``
29 File descriptor returned by :ref:`open() <func-open>`.
30
5377d91f
MH
31``argp``
32
33
15e7d615 34Description
5377d91f
MH
35===========
36
37The current video standard determines a nominal number of frames per
38second. If less than this number of frames is to be captured or output,
39applications can request frame skipping or duplicating on the driver
760c7010
MCC
40side. 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
42counters, and to avoid unnecessary data copying.
43
44Further these ioctls can be used to determine the number of buffers used
45internally by a driver in read/write mode. For implications see the
46section discussing the :ref:`read() <func-read>` function.
47
48To 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
fc78c7c7 50pointer to a struct :c:type:`v4l2_streamparm` which contains a
5377d91f
MH
51union 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
e8be7e97 56.. c:type:: v4l2_streamparm
fa92b04d 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
e8be7e97 72 :c:type:`v4l2_format` ``type``, set by the
56683d7d 73 application. See :c:type:`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 -
e8be7e97 87 - struct :c:type:`v4l2_captureparm`
5377d91f
MH
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 -
e8be7e97 97 - struct :c:type:`v4l2_outputparm`
5377d91f
MH
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
e8be7e97 117.. c:type:: v4l2_captureparm
fa92b04d 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
e8be7e97 143 - struct :c:type:`v4l2_fract`
5377d91f
MH
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
e8be7e97 154 (struct :c:type:`v4l2_standard` ``frameperiod``
0579e6e3
MCC
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
e8be7e97 200.. c:type:: v4l2_outputparm
fa92b04d 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
e8be7e97 226 - struct :c:type:`v4l2_fract`
5377d91f
MH
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
e8be7e97 244 (struct :c:type:`v4l2_standard` ``frameperiod``
0579e6e3
MCC
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 355Return Value
5377d91f
MH
356============
357
358On success 0 is returned, on error -1 and the ``errno`` variable is set
359appropriately. The generic error codes are described at the
360:ref:`Generic Error Codes <gen-errors>` chapter.
This page took 0.065474 seconds and 5 git commands to generate.