1 .. -*- coding: utf-8; mode: rst -*-
5 **********************************
6 ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
7 **********************************
12 Get or set streaming parameters
18 .. c:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
24 File descriptor returned by :ref:`open() <func-open>`.
27 VIDIOC_G_PARM, VIDIOC_S_PARM
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.
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.
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.
54 .. flat-table:: struct v4l2_streamparm
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`
83 - struct :ref:`v4l2_captureparm <v4l2-captureparm>`
87 - Parameters for capture devices, used when ``type`` is
88 ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
93 - struct :ref:`v4l2_outputparm <v4l2-outputparm>`
97 - Parameters for output devices, used when ``type`` is
98 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
105 - ``raw_data``\ [200]
107 - A place holder for future extensions.
111 .. _v4l2-captureparm:
113 .. flat-table:: struct v4l2_captureparm
125 - See :ref:`parm-caps`.
133 - Set by drivers and applications, see :ref:`parm-flags`.
137 - struct :ref:`v4l2_fract <v4l2-fract>`
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.
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
154 Drivers support this function only when they set the
155 ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
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
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
187 - Reserved for future extensions. Drivers and applications must set
194 .. flat-table:: struct v4l2_outputparm
206 - See :ref:`parm-caps`.
214 - Set by drivers and applications, see :ref:`parm-flags`.
218 - struct :ref:`v4l2_fract <v4l2-fract>`
222 - This is the desired period between successive frames output by the
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.
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
242 Drivers support this function only when they set the
243 ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
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
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
275 - Reserved for future extensions. Drivers and applications must set
282 .. flat-table:: Streaming Parameters Capabilites
290 - ``V4L2_CAP_TIMEPERFRAME``
294 - The frame skipping/repeating controlled by the ``timeperframe``
301 .. flat-table:: Capture Parameters Flags
309 - ``V4L2_MODE_HIGHQUALITY``
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
321 - The driver may be able to capture higher resolutions than for
324 - The driver may support fewer pixel formats than motion capture
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.
331 - The driver may capture images in slices like a scanner in order
332 to handle larger format images than would otherwise be
335 - An image capture operation may be significantly slower than
338 - Moving objects in the image might have excessive motion blur.
340 - Capture might only work through the :c:func:`read()` call.
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.
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:
357 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
358 .. ------------------------------------------------------------------------------