mmc: sdhci-acpi: Set MMC_CAP_CMD_DURING_TFR for Intel eMMC controllers
[deliverable/linux.git] / Documentation / media / uapi / v4l / vidioc-g-parm.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _VIDIOC_G_PARM:
4
5 **********************************
6 ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
7 **********************************
8
9 Name
10 ====
11
12 VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
13
14
15 Synopsis
16 ========
17
18 .. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
19
20
21 Arguments
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
33 Description
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
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
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
48 :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
49 pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a
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
67 -
68 - The buffer (stream) type, same as struct
69 :ref:`v4l2_format <v4l2-format>` ``type``, set by the
70 application. See :ref:`v4l2-buf-type`
71
72 - .. row 2
73
74 - union
75
76 - ``parm``
77
78 -
79 -
80
81 - .. row 3
82
83 -
84 - struct :ref:`v4l2_captureparm <v4l2-captureparm>`
85
86 - ``capture``
87
88 - Parameters for capture devices, used when ``type`` is
89 ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
90
91 - .. row 4
92
93 -
94 - struct :ref:`v4l2_outputparm <v4l2-outputparm>`
95
96 - ``output``
97
98 - Parameters for output devices, used when ``type`` is
99 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
100
101 - .. row 5
102
103 -
104 - __u8
105
106 - ``raw_data``\ [200]
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
143 the driver, in seconds. The field is intended to skip frames on
144 the driver side, saving I/O bandwidth.
145
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.
154
155 Drivers support this function only when they set the
156 ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
157
158 - .. row 4
159
160 - __u32
161
162 - ``extendedmode``
163
164 - Custom (driver specific) streaming parameters. When unused,
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`.
168
169 - .. row 5
170
171 - __u32
172
173 - ``readbuffers``
174
175 - Applications set this field to the desired number of buffers used
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`.
181
182 - .. row 6
183
184 - __u32
185
186 - ``reserved``\ [4]
187
188 - Reserved for future extensions. Drivers and applications must set
189 the array to zero.
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
224 driver, in seconds.
225
226 - .. row 4
227
228 - :cspan:`2`
229
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.
233
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.
242
243 Drivers support this function only when they set the
244 ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
245
246 - .. row 5
247
248 - __u32
249
250 - ``extendedmode``
251
252 - Custom (driver specific) streaming parameters. When unused,
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`.
256
257 - .. row 6
258
259 - __u32
260
261 - ``writebuffers``
262
263 - Applications set this field to the desired number of buffers used
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`.
269
270 - .. row 7
271
272 - __u32
273
274 - ``reserved``\ [4]
275
276 - Reserved for future extensions. Drivers and applications must set
277 the array to zero.
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``
296 field is supported.
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
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:
321
322 - The driver may be able to capture higher resolutions than for
323 motion capture.
324
325 - The driver may support fewer pixel formats than motion capture
326 (eg; true color).
327
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.
331
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.
335
336 - An image capture operation may be significantly slower than
337 motion capture.
338
339 - Moving objects in the image might have excessive motion blur.
340
341 - Capture might only work through the :ref:`read() <func-read>` call.
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.
This page took 0.040834 seconds and 5 git commands to generate.