Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
1 <refentry id="vidioc-g-parm"> 2 <refmeta> 3 <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>VIDIOC_G_PARM</refname> 9 <refname>VIDIOC_S_PARM</refname> 10 <refpurpose>Get or set streaming parameters</refpurpose> 11 </refnamediv> 12 13 <refsynopsisdiv> 14 <funcsynopsis> 15 <funcprototype> 16 <funcdef>int <function>ioctl</function></funcdef> 17 <paramdef>int <parameter>fd</parameter></paramdef> 18 <paramdef>int <parameter>request</parameter></paramdef> 19 <paramdef>v4l2_streamparm *<parameter>argp</parameter></paramdef> 20 </funcprototype> 21 </funcsynopsis> 22 </refsynopsisdiv> 23 24 <refsect1> 25 <title>Arguments</title> 26 27 <variablelist> 28 <varlistentry> 29 <term><parameter>fd</parameter></term> 30 <listitem> 31 <para>&fd;</para> 32 </listitem> 33 </varlistentry> 34 <varlistentry> 35 <term><parameter>request</parameter></term> 36 <listitem> 37 <para>VIDIOC_G_PARM, VIDIOC_S_PARM</para> 38 </listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>argp</parameter></term> 42 <listitem> 43 <para></para> 44 </listitem> 45 </varlistentry> 46 </variablelist> 47 </refsect1> 48 49 <refsect1> 50 <title>Description</title> 51 52 <para>The current video standard determines a nominal number of 53 frames per second. If less than this number of frames is to be 54 captured or output, applications can request frame skipping or 55 duplicating on the driver side. This is especially useful when using 56 the <function>read()</function> or <function>write()</function>, which 57 are not augmented by timestamps or sequence counters, and to avoid 58 unnecessary data copying.</para> 59 60 <para>Further these ioctls can be used to determine the number of 61 buffers used internally by a driver in read/write mode. For 62 implications see the section discussing the &func-read; 63 function.</para> 64 65 <para>To get and set the streaming parameters applications call 66 the <constant>VIDIOC_G_PARM</constant> and 67 <constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a 68 pointer to a struct <structname>v4l2_streamparm</structname> which 69 contains a union holding separate parameters for input and output 70 devices.</para> 71 72 <table pgwide="1" frame="none" id="v4l2-streamparm"> 73 <title>struct <structname>v4l2_streamparm</structname></title> 74 <tgroup cols="4"> 75 &cs-ustr; 76 <tbody valign="top"> 77 <row> 78 <entry>__u32</entry> 79 <entry><structfield>type</structfield></entry> 80 <entry></entry> 81 <entry>The buffer (stream) type, same as &v4l2-format; 82 <structfield>type</structfield>, set by the application. See <xref 83 linkend="v4l2-buf-type" /></entry> 84 </row> 85 <row> 86 <entry>union</entry> 87 <entry><structfield>parm</structfield></entry> 88 <entry></entry> 89 <entry></entry> 90 </row> 91 <row> 92 <entry></entry> 93 <entry>&v4l2-captureparm;</entry> 94 <entry><structfield>capture</structfield></entry> 95 <entry>Parameters for capture devices, used when 96 <structfield>type</structfield> is 97 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry> 98 </row> 99 <row> 100 <entry></entry> 101 <entry>&v4l2-outputparm;</entry> 102 <entry><structfield>output</structfield></entry> 103 <entry>Parameters for output devices, used when 104 <structfield>type</structfield> is 105 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry> 106 </row> 107 <row> 108 <entry></entry> 109 <entry>__u8</entry> 110 <entry><structfield>raw_data</structfield>[200]</entry> 111 <entry>A place holder for future extensions.</entry> 112 </row> 113 </tbody> 114 </tgroup> 115 </table> 116 117 <table pgwide="1" frame="none" id="v4l2-captureparm"> 118 <title>struct <structname>v4l2_captureparm</structname></title> 119 <tgroup cols="3"> 120 &cs-str; 121 <tbody valign="top"> 122 <row> 123 <entry>__u32</entry> 124 <entry><structfield>capability</structfield></entry> 125 <entry>See <xref linkend="parm-caps" />.</entry> 126 </row> 127 <row> 128 <entry>__u32</entry> 129 <entry><structfield>capturemode</structfield></entry> 130 <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry> 131 </row> 132 <row> 133 <entry>&v4l2-fract;</entry> 134 <entry><structfield>timeperframe</structfield></entry> 135 <entry><para>This is the desired period between 136 successive frames captured by the driver, in seconds. The 137 field is intended to skip frames on the driver side, saving I/O 138 bandwidth.</para><para>Applications store here the desired frame 139 period, drivers return the actual frame period, which must be greater 140 or equal to the nominal frame period determined by the current video 141 standard (&v4l2-standard; <structfield>frameperiod</structfield> 142 field). Changing the video standard (also implicitly by switching the 143 video input) may reset this parameter to the nominal frame period. To 144 reset manually applications can just set this field to 145 zero.</para><para>Drivers support this function only when they set the 146 <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the 147 <structfield>capability</structfield> field.</para></entry> 148 </row> 149 <row> 150 <entry>__u32</entry> 151 <entry><structfield>extendedmode</structfield></entry> 152 <entry>Custom (driver specific) streaming parameters. When 153 unused, applications and drivers must set this field to zero. 154 Applications using this field should check the driver name and 155 version, see <xref linkend="querycap" />.</entry> 156 </row> 157 <row> 158 <entry>__u32</entry> 159 <entry><structfield>readbuffers</structfield></entry> 160 <entry>Applications set this field to the desired number 161 of buffers used internally by the driver in &func-read; mode. Drivers 162 return the actual number of buffers. When an application requests zero 163 buffers, drivers should just return the current setting rather than 164 the minimum or an error code. For details see <xref 165 linkend="rw" />.</entry> 166 </row> 167 <row> 168 <entry>__u32</entry> 169 <entry><structfield>reserved</structfield>[4]</entry> 170 <entry>Reserved for future extensions. Drivers and 171 applications must set the array to zero.</entry> 172 </row> 173 </tbody> 174 </tgroup> 175 </table> 176 177 <table pgwide="1" frame="none" id="v4l2-outputparm"> 178 <title>struct <structname>v4l2_outputparm</structname></title> 179 <tgroup cols="3"> 180 &cs-str; 181 <tbody valign="top"> 182 <row> 183 <entry>__u32</entry> 184 <entry><structfield>capability</structfield></entry> 185 <entry>See <xref linkend="parm-caps" />.</entry> 186 </row> 187 <row> 188 <entry>__u32</entry> 189 <entry><structfield>outputmode</structfield></entry> 190 <entry>Set by drivers and applications, see <xref 191 linkend="parm-flags" />.</entry> 192 </row> 193 <row> 194 <entry>&v4l2-fract;</entry> 195 <entry><structfield>timeperframe</structfield></entry> 196 <entry>This is the desired period between 197 successive frames output by the driver, in seconds.</entry> 198 </row> 199 <row> 200 <entry spanname="hspan"><para>The field is intended to 201 repeat frames on the driver side in &func-write; mode (in streaming 202 mode timestamps can be used to throttle the output), saving I/O 203 bandwidth.</para><para>Applications store here the desired frame 204 period, drivers return the actual frame period, which must be greater 205 or equal to the nominal frame period determined by the current video 206 standard (&v4l2-standard; <structfield>frameperiod</structfield> 207 field). Changing the video standard (also implicitly by switching the 208 video output) may reset this parameter to the nominal frame period. To 209 reset manually applications can just set this field to 210 zero.</para><para>Drivers support this function only when they set the 211 <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the 212 <structfield>capability</structfield> field.</para></entry> 213 </row> 214 <row> 215 <entry>__u32</entry> 216 <entry><structfield>extendedmode</structfield></entry> 217 <entry>Custom (driver specific) streaming parameters. When 218 unused, applications and drivers must set this field to zero. 219 Applications using this field should check the driver name and 220 version, see <xref linkend="querycap" />.</entry> 221 </row> 222 <row> 223 <entry>__u32</entry> 224 <entry><structfield>writebuffers</structfield></entry> 225 <entry>Applications set this field to the desired number 226 of buffers used internally by the driver in 227 <function>write()</function> mode. Drivers return the actual number of 228 buffers. When an application requests zero buffers, drivers should 229 just return the current setting rather than the minimum or an error 230 code. For details see <xref linkend="rw" />.</entry> 231 </row> 232 <row> 233 <entry>__u32</entry> 234 <entry><structfield>reserved</structfield>[4]</entry> 235 <entry>Reserved for future extensions. Drivers and 236 applications must set the array to zero.</entry> 237 </row> 238 </tbody> 239 </tgroup> 240 </table> 241 242 <table pgwide="1" frame="none" id="parm-caps"> 243 <title>Streaming Parameters Capabilites</title> 244 <tgroup cols="3"> 245 &cs-def; 246 <tbody valign="top"> 247 <row> 248 <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry> 249 <entry>0x1000</entry> 250 <entry>The frame skipping/repeating controlled by the 251 <structfield>timeperframe</structfield> field is supported.</entry> 252 </row> 253 </tbody> 254 </tgroup> 255 </table> 256 257 <table pgwide="1" frame="none" id="parm-flags"> 258 <title>Capture Parameters Flags</title> 259 <tgroup cols="3"> 260 &cs-def; 261 <tbody valign="top"> 262 <row> 263 <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry> 264 <entry>0x0001</entry> 265 <entry><para>High quality imaging mode. High quality mode 266 is intended for still imaging applications. The idea is to get the 267 best possible image quality that the hardware can deliver. It is not 268 defined how the driver writer may achieve that; it will depend on the 269 hardware and the ingenuity of the driver writer. High quality mode is 270 a different mode from the regular motion video capture modes. In 271 high quality mode:<itemizedlist> 272 <listitem> 273 <para>The driver may be able to capture higher 274 resolutions than for motion capture.</para> 275 </listitem> 276 <listitem> 277 <para>The driver may support fewer pixel formats 278 than motion capture (eg; true color).</para> 279 </listitem> 280 <listitem> 281 <para>The driver may capture and arithmetically 282 combine multiple successive fields or frames to remove color edge 283 artifacts and reduce the noise in the video data. 284 </para> 285 </listitem> 286 <listitem> 287 <para>The driver may capture images in slices like 288 a scanner in order to handle larger format images than would otherwise 289 be possible. </para> 290 </listitem> 291 <listitem> 292 <para>An image capture operation may be 293 significantly slower than motion capture. </para> 294 </listitem> 295 <listitem> 296 <para>Moving objects in the image might have 297 excessive motion blur. </para> 298 </listitem> 299 <listitem> 300 <para>Capture might only work through the 301 <function>read()</function> call.</para> 302 </listitem> 303 </itemizedlist></para></entry> 304 </row> 305 </tbody> 306 </tgroup> 307 </table> 308 309 </refsect1> 310 311 <refsect1> 312 &return-value; 313 </refsect1> 314 </refentry>
