| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _VIDIOC_G_PARM: |
| 5 |
|
| 6 |
********************************** |
| 7 |
ioctl VIDIOC_G_PARM, VIDIOC_S_PARM |
| 8 |
********************************** |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters |
| 14 |
|
| 15 |
Synopsis |
| 16 |
======== |
| 17 |
|
| 18 |
.. c:macro:: VIDIOC_G_PARM |
| 19 |
|
| 20 |
``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)`` |
| 21 |
|
| 22 |
.. c:macro:: VIDIOC_S_PARM |
| 23 |
|
| 24 |
``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)`` |
| 25 |
|
| 26 |
Arguments |
| 27 |
========= |
| 28 |
|
| 29 |
``fd`` |
| 30 |
File descriptor returned by :c:func:`open()`. |
| 31 |
|
| 32 |
``argp`` |
| 33 |
Pointer to struct :c:type:`v4l2_streamparm`. |
| 34 |
|
| 35 |
Description |
| 36 |
=========== |
| 37 |
|
| 38 |
Applications can request a different frame interval. The capture or |
| 39 |
output device will be reconfigured to support the requested frame |
| 40 |
interval if possible. Optionally drivers may choose to skip or |
| 41 |
repeat frames to achieve the requested frame interval. |
| 42 |
|
| 43 |
For stateful encoders (see :ref:`encoder`) this represents the |
| 44 |
frame interval that is typically embedded in the encoded video stream. |
| 45 |
|
| 46 |
Changing the frame interval shall never change the format. Changing the |
| 47 |
format, on the other hand, may change the frame interval. |
| 48 |
|
| 49 |
Further these ioctls can be used to determine the number of buffers used |
| 50 |
internally by a driver in read/write mode. For implications see the |
| 51 |
section discussing the :c:func:`read()` function. |
| 52 |
|
| 53 |
To get and set the streaming parameters applications call the |
| 54 |
:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and |
| 55 |
:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a |
| 56 |
pointer to a struct :c:type:`v4l2_streamparm` which contains a |
| 57 |
union holding separate parameters for input and output devices. |
| 58 |
|
| 59 |
.. tabularcolumns:: |p{3.7cm}|p{3.5cm}|p{10.1cm}| |
| 60 |
|
| 61 |
.. c:type:: v4l2_streamparm |
| 62 |
|
| 63 |
.. flat-table:: struct v4l2_streamparm |
| 64 |
:header-rows: 0 |
| 65 |
:stub-columns: 0 |
| 66 |
:widths: 1 1 2 |
| 67 |
|
| 68 |
* - __u32 |
| 69 |
- ``type`` |
| 70 |
- The buffer (stream) type, same as struct |
| 71 |
:c:type:`v4l2_format` ``type``, set by the |
| 72 |
application. See :c:type:`v4l2_buf_type`. |
| 73 |
* - union { |
| 74 |
- ``parm`` |
| 75 |
* - struct :c:type:`v4l2_captureparm` |
| 76 |
- ``capture`` |
| 77 |
- Parameters for capture devices, used when ``type`` is |
| 78 |
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or |
| 79 |
``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. |
| 80 |
* - struct :c:type:`v4l2_outputparm` |
| 81 |
- ``output`` |
| 82 |
- Parameters for output devices, used when ``type`` is |
| 83 |
``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. |
| 84 |
* - __u8 |
| 85 |
- ``raw_data``\ [200] |
| 86 |
- A place holder for future extensions. |
| 87 |
* - } |
| 88 |
|
| 89 |
|
| 90 |
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| |
| 91 |
|
| 92 |
.. c:type:: v4l2_captureparm |
| 93 |
|
| 94 |
.. flat-table:: struct v4l2_captureparm |
| 95 |
:header-rows: 0 |
| 96 |
:stub-columns: 0 |
| 97 |
:widths: 1 1 2 |
| 98 |
|
| 99 |
* - __u32 |
| 100 |
- ``capability`` |
| 101 |
- See :ref:`parm-caps`. |
| 102 |
* - __u32 |
| 103 |
- ``capturemode`` |
| 104 |
- Set by drivers and applications, see :ref:`parm-flags`. |
| 105 |
* - struct :c:type:`v4l2_fract` |
| 106 |
- ``timeperframe`` |
| 107 |
- This is the desired period between successive frames captured by |
| 108 |
the driver, in seconds. |
| 109 |
* - :cspan:`2` |
| 110 |
|
| 111 |
This will configure the speed at which the video source (e.g. a sensor) |
| 112 |
generates video frames. If the speed is fixed, then the driver may |
| 113 |
choose to skip or repeat frames in order to achieve the requested |
| 114 |
frame rate. |
| 115 |
|
| 116 |
For stateful encoders (see :ref:`encoder`) this represents the |
| 117 |
frame interval that is typically embedded in the encoded video stream. |
| 118 |
|
| 119 |
Applications store here the desired frame period, drivers return |
| 120 |
the actual frame period. |
| 121 |
|
| 122 |
Changing the video standard (also implicitly by switching |
| 123 |
the video input) may reset this parameter to the nominal frame |
| 124 |
period. To reset manually applications can just set this field to |
| 125 |
zero. |
| 126 |
|
| 127 |
Drivers support this function only when they set the |
| 128 |
``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. |
| 129 |
* - __u32 |
| 130 |
- ``extendedmode`` |
| 131 |
- Custom (driver specific) streaming parameters. When unused, |
| 132 |
applications and drivers must set this field to zero. Applications |
| 133 |
using this field should check the driver name and version, see |
| 134 |
:ref:`querycap`. |
| 135 |
* - __u32 |
| 136 |
- ``readbuffers`` |
| 137 |
- Applications set this field to the desired number of buffers used |
| 138 |
internally by the driver in :c:func:`read()` mode. |
| 139 |
Drivers return the actual number of buffers. When an application |
| 140 |
requests zero buffers, drivers should just return the current |
| 141 |
setting rather than the minimum or an error code. For details see |
| 142 |
:ref:`rw`. |
| 143 |
* - __u32 |
| 144 |
- ``reserved``\ [4] |
| 145 |
- Reserved for future extensions. Drivers and applications must set |
| 146 |
the array to zero. |
| 147 |
|
| 148 |
|
| 149 |
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| |
| 150 |
|
| 151 |
.. c:type:: v4l2_outputparm |
| 152 |
|
| 153 |
.. flat-table:: struct v4l2_outputparm |
| 154 |
:header-rows: 0 |
| 155 |
:stub-columns: 0 |
| 156 |
:widths: 1 1 2 |
| 157 |
|
| 158 |
* - __u32 |
| 159 |
- ``capability`` |
| 160 |
- See :ref:`parm-caps`. |
| 161 |
* - __u32 |
| 162 |
- ``outputmode`` |
| 163 |
- Set by drivers and applications, see :ref:`parm-flags`. |
| 164 |
* - struct :c:type:`v4l2_fract` |
| 165 |
- ``timeperframe`` |
| 166 |
- This is the desired period between successive frames output by the |
| 167 |
driver, in seconds. |
| 168 |
* - :cspan:`2` |
| 169 |
|
| 170 |
The field is intended to repeat frames on the driver side in |
| 171 |
:c:func:`write()` mode (in streaming mode timestamps |
| 172 |
can be used to throttle the output), saving I/O bandwidth. |
| 173 |
|
| 174 |
For stateful encoders (see :ref:`encoder`) this represents the |
| 175 |
frame interval that is typically embedded in the encoded video stream |
| 176 |
and it provides a hint to the encoder of the speed at which raw |
| 177 |
frames are queued up to the encoder. |
| 178 |
|
| 179 |
Applications store here the desired frame period, drivers return |
| 180 |
the actual frame period. |
| 181 |
|
| 182 |
Changing the video standard (also implicitly by switching |
| 183 |
the video output) may reset this parameter to the nominal frame |
| 184 |
period. To reset manually applications can just set this field to |
| 185 |
zero. |
| 186 |
|
| 187 |
Drivers support this function only when they set the |
| 188 |
``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field. |
| 189 |
* - __u32 |
| 190 |
- ``extendedmode`` |
| 191 |
- Custom (driver specific) streaming parameters. When unused, |
| 192 |
applications and drivers must set this field to zero. Applications |
| 193 |
using this field should check the driver name and version, see |
| 194 |
:ref:`querycap`. |
| 195 |
* - __u32 |
| 196 |
- ``writebuffers`` |
| 197 |
- Applications set this field to the desired number of buffers used |
| 198 |
internally by the driver in :c:func:`write()` mode. Drivers |
| 199 |
return the actual number of buffers. When an application requests |
| 200 |
zero buffers, drivers should just return the current setting |
| 201 |
rather than the minimum or an error code. For details see |
| 202 |
:ref:`rw`. |
| 203 |
* - __u32 |
| 204 |
- ``reserved``\ [4] |
| 205 |
- Reserved for future extensions. Drivers and applications must set |
| 206 |
the array to zero. |
| 207 |
|
| 208 |
|
| 209 |
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| |
| 210 |
|
| 211 |
.. _parm-caps: |
| 212 |
|
| 213 |
.. flat-table:: Streaming Parameters Capabilities |
| 214 |
:header-rows: 0 |
| 215 |
:stub-columns: 0 |
| 216 |
:widths: 3 1 4 |
| 217 |
|
| 218 |
* - ``V4L2_CAP_TIMEPERFRAME`` |
| 219 |
- 0x1000 |
| 220 |
- The frame period can be modified by setting the ``timeperframe`` |
| 221 |
field. |
| 222 |
|
| 223 |
|
| 224 |
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| |
| 225 |
|
| 226 |
.. _parm-flags: |
| 227 |
|
| 228 |
.. flat-table:: Capture Parameters Flags |
| 229 |
:header-rows: 0 |
| 230 |
:stub-columns: 0 |
| 231 |
:widths: 3 1 4 |
| 232 |
|
| 233 |
* - ``V4L2_MODE_HIGHQUALITY`` |
| 234 |
- 0x0001 |
| 235 |
- High quality imaging mode. High quality mode is intended for still |
| 236 |
imaging applications. The idea is to get the best possible image |
| 237 |
quality that the hardware can deliver. It is not defined how the |
| 238 |
driver writer may achieve that; it will depend on the hardware and |
| 239 |
the ingenuity of the driver writer. High quality mode is a |
| 240 |
different mode from the regular motion video capture modes. In |
| 241 |
high quality mode: |
| 242 |
|
| 243 |
- The driver may be able to capture higher resolutions than for |
| 244 |
motion capture. |
| 245 |
|
| 246 |
- The driver may support fewer pixel formats than motion capture |
| 247 |
(eg; true color). |
| 248 |
|
| 249 |
- The driver may capture and arithmetically combine multiple |
| 250 |
successive fields or frames to remove color edge artifacts and |
| 251 |
reduce the noise in the video data. |
| 252 |
|
| 253 |
- The driver may capture images in slices like a scanner in order |
| 254 |
to handle larger format images than would otherwise be |
| 255 |
possible. |
| 256 |
|
| 257 |
- An image capture operation may be significantly slower than |
| 258 |
motion capture. |
| 259 |
|
| 260 |
- Moving objects in the image might have excessive motion blur. |
| 261 |
|
| 262 |
- Capture might only work through the :c:func:`read()` call. |
| 263 |
|
| 264 |
Return Value |
| 265 |
============ |
| 266 |
|
| 267 |
On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 268 |
appropriately. The generic error codes are described at the |
| 269 |
:ref:`Generic Error Codes <gen-errors>` chapter. |