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