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