1 .. -*- coding: utf-8; mode: rst -*-
5 **********************************
6 ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
7 **********************************
12 VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
18 .. c:function:: int ioctl( int fd, VIDIOC_G_PARM, v4l2_streamparm *argp )
21 .. c:function:: int ioctl( int fd, VIDIOC_S_PARM, v4l2_streamparm *argp )
29 File descriptor returned by :ref:`open() <func-open>`.
32 Pointer to struct :c:type:`v4l2_streamparm`.
38 The current video standard determines a nominal number of frames per
39 second. If less than this number of frames is to be captured or output,
40 applications can request frame skipping or duplicating on the driver
41 side. This is especially useful when using the :ref:`read() <func-read>` or
42 :ref:`write() <func-write>`, which are not augmented by timestamps or sequence
43 counters, and to avoid unnecessary data copying.
45 Further these ioctls can be used to determine the number of buffers used
46 internally by a driver in read/write mode. For implications see the
47 section discussing the :ref:`read() <func-read>` function.
49 To get and set the streaming parameters applications call the
50 :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
51 pointer to a struct :c:type:`v4l2_streamparm` which contains a
52 union holding separate parameters for input and output devices.
55 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
57 .. c:type:: v4l2_streamparm
59 .. flat-table:: struct v4l2_streamparm
67 - The buffer (stream) type, same as struct
68 :c:type:`v4l2_format` ``type``, set by the
69 application. See :c:type:`v4l2_buf_type`.
75 - struct :c:type:`v4l2_captureparm`
77 - Parameters for capture devices, used when ``type`` is
78 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
79 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``.
81 - struct :c:type:`v4l2_outputparm`
83 - Parameters for output devices, used when ``type`` is
84 ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
88 - A place holder for future extensions.
92 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
94 .. c:type:: v4l2_captureparm
96 .. flat-table:: struct v4l2_captureparm
103 - See :ref:`parm-caps`.
106 - Set by drivers and applications, see :ref:`parm-flags`.
107 * - struct :c:type:`v4l2_fract`
109 - This is the desired period between successive frames captured by
110 the driver, in seconds. The field is intended to skip frames on
111 the driver side, saving I/O bandwidth.
113 Applications store here the desired frame period, drivers return
114 the actual frame period, which must be greater or equal to the
115 nominal frame period determined by the current video standard
116 (struct :c:type:`v4l2_standard` ``frameperiod``
117 field). Changing the video standard (also implicitly by switching
118 the video input) may reset this parameter to the nominal frame
119 period. To reset manually applications can just set this field to
122 Drivers support this function only when they set the
123 ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
126 - Custom (driver specific) streaming parameters. When unused,
127 applications and drivers must set this field to zero. Applications
128 using this field should check the driver name and version, see
132 - Applications set this field to the desired number of buffers used
133 internally by the driver in :ref:`read() <func-read>` mode.
134 Drivers return the actual number of buffers. When an application
135 requests zero buffers, drivers should just return the current
136 setting rather than the minimum or an error code. For details see
140 - Reserved for future extensions. Drivers and applications must set
145 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
147 .. c:type:: v4l2_outputparm
149 .. flat-table:: struct v4l2_outputparm
156 - See :ref:`parm-caps`.
159 - Set by drivers and applications, see :ref:`parm-flags`.
160 * - struct :c:type:`v4l2_fract`
162 - This is the desired period between successive frames output by the
166 The field is intended to repeat frames on the driver side in
167 :ref:`write() <func-write>` mode (in streaming mode timestamps
168 can be used to throttle the output), saving I/O bandwidth.
170 Applications store here the desired frame period, drivers return
171 the actual frame period, which must be greater or equal to the
172 nominal frame period determined by the current video standard
173 (struct :c:type:`v4l2_standard` ``frameperiod``
174 field). Changing the video standard (also implicitly by switching
175 the video output) may reset this parameter to the nominal frame
176 period. To reset manually applications can just set this field to
179 Drivers support this function only when they set the
180 ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
183 - Custom (driver specific) streaming parameters. When unused,
184 applications and drivers must set this field to zero. Applications
185 using this field should check the driver name and version, see
189 - Applications set this field to the desired number of buffers used
190 internally by the driver in :ref:`write() <func-write>` mode. Drivers
191 return the actual number of buffers. When an application requests
192 zero buffers, drivers should just return the current setting
193 rather than the minimum or an error code. For details see
197 - Reserved for future extensions. Drivers and applications must set
202 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
206 .. flat-table:: Streaming Parameters Capabilites
211 * - ``V4L2_CAP_TIMEPERFRAME``
213 - The frame skipping/repeating controlled by the ``timeperframe``
218 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
222 .. flat-table:: Capture Parameters Flags
227 * - ``V4L2_MODE_HIGHQUALITY``
229 - High quality imaging mode. High quality mode is intended for still
230 imaging applications. The idea is to get the best possible image
231 quality that the hardware can deliver. It is not defined how the
232 driver writer may achieve that; it will depend on the hardware and
233 the ingenuity of the driver writer. High quality mode is a
234 different mode from the regular motion video capture modes. In
237 - The driver may be able to capture higher resolutions than for
240 - The driver may support fewer pixel formats than motion capture
243 - The driver may capture and arithmetically combine multiple
244 successive fields or frames to remove color edge artifacts and
245 reduce the noise in the video data.
247 - The driver may capture images in slices like a scanner in order
248 to handle larger format images than would otherwise be
251 - An image capture operation may be significantly slower than
254 - Moving objects in the image might have excessive motion blur.
256 - Capture might only work through the :ref:`read() <func-read>` call.
262 On success 0 is returned, on error -1 and the ``errno`` variable is set
263 appropriately. The generic error codes are described at the
264 :ref:`Generic Error Codes <gen-errors>` chapter.