Based on kernel version 3.0.4. Page generated on 2011-10-03 22:07 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>&v4l2-buf-type;</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.</entry> 83 </row> 84 <row> 85 <entry>union</entry> 86 <entry><structfield>parm</structfield></entry> 87 <entry></entry> 88 <entry></entry> 89 </row> 90 <row> 91 <entry></entry> 92 <entry>&v4l2-captureparm;</entry> 93 <entry><structfield>capture</structfield></entry> 94 <entry>Parameters for capture devices, used when 95 <structfield>type</structfield> is 96 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry> 97 </row> 98 <row> 99 <entry></entry> 100 <entry>&v4l2-outputparm;</entry> 101 <entry><structfield>output</structfield></entry> 102 <entry>Parameters for output devices, used when 103 <structfield>type</structfield> is 104 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry> 105 </row> 106 <row> 107 <entry></entry> 108 <entry>__u8</entry> 109 <entry><structfield>raw_data</structfield>[200]</entry> 110 <entry>A place holder for future extensions and custom 111 (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and 112 higher.</entry> 113 </row> 114 </tbody> 115 </tgroup> 116 </table> 117 118 <table pgwide="1" frame="none" id="v4l2-captureparm"> 119 <title>struct <structname>v4l2_captureparm</structname></title> 120 <tgroup cols="3"> 121 &cs-str; 122 <tbody valign="top"> 123 <row> 124 <entry>__u32</entry> 125 <entry><structfield>capability</structfield></entry> 126 <entry>See <xref linkend="parm-caps" />.</entry> 127 </row> 128 <row> 129 <entry>__u32</entry> 130 <entry><structfield>capturemode</structfield></entry> 131 <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry> 132 </row> 133 <row> 134 <entry>&v4l2-fract;</entry> 135 <entry><structfield>timeperframe</structfield></entry> 136 <entry><para>This is is the desired period between 137 successive frames captured by the driver, in seconds. The 138 field is intended to skip frames on the driver side, saving I/O 139 bandwidth.</para><para>Applications store here the desired frame 140 period, drivers return the actual frame period, which must be greater 141 or equal to the nominal frame period determined by the current video 142 standard (&v4l2-standard; <structfield>frameperiod</structfield> 143 field). Changing the video standard (also implicitly by switching the 144 video input) may reset this parameter to the nominal frame period. To 145 reset manually applications can just set this field to 146 zero.</para><para>Drivers support this function only when they set the 147 <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the 148 <structfield>capability</structfield> field.</para></entry> 149 </row> 150 <row> 151 <entry>__u32</entry> 152 <entry><structfield>extendedmode</structfield></entry> 153 <entry>Custom (driver specific) streaming parameters. When 154 unused, applications and drivers must set this field to zero. 155 Applications using this field should check the driver name and 156 version, see <xref linkend="querycap" />.</entry> 157 </row> 158 <row> 159 <entry>__u32</entry> 160 <entry><structfield>readbuffers</structfield></entry> 161 <entry>Applications set this field to the desired number 162 of buffers used internally by the driver in &func-read; mode. Drivers 163 return the actual number of buffers. When an application requests zero 164 buffers, drivers should just return the current setting rather than 165 the minimum or an error code. For details see <xref 166 linkend="rw" />.</entry> 167 </row> 168 <row> 169 <entry>__u32</entry> 170 <entry><structfield>reserved</structfield>[4]</entry> 171 <entry>Reserved for future extensions. Drivers and 172 applications must set the array to zero.</entry> 173 </row> 174 </tbody> 175 </tgroup> 176 </table> 177 178 <table pgwide="1" frame="none" id="v4l2-outputparm"> 179 <title>struct <structname>v4l2_outputparm</structname></title> 180 <tgroup cols="3"> 181 &cs-str; 182 <tbody valign="top"> 183 <row> 184 <entry>__u32</entry> 185 <entry><structfield>capability</structfield></entry> 186 <entry>See <xref linkend="parm-caps" />.</entry> 187 </row> 188 <row> 189 <entry>__u32</entry> 190 <entry><structfield>outputmode</structfield></entry> 191 <entry>Set by drivers and applications, see <xref 192 linkend="parm-flags" />.</entry> 193 </row> 194 <row> 195 <entry>&v4l2-fract;</entry> 196 <entry><structfield>timeperframe</structfield></entry> 197 <entry>This is is the desired period between 198 successive frames output by the driver, in seconds.</entry> 199 </row> 200 <row> 201 <entry spanname="hspan"><para>The field is intended to 202 repeat frames on the driver side in &func-write; mode (in streaming 203 mode timestamps can be used to throttle the output), saving I/O 204 bandwidth.</para><para>Applications store here the desired frame 205 period, drivers return the actual frame period, which must be greater 206 or equal to the nominal frame period determined by the current video 207 standard (&v4l2-standard; <structfield>frameperiod</structfield> 208 field). Changing the video standard (also implicitly by switching the 209 video output) may reset this parameter to the nominal frame period. To 210 reset manually applications can just set this field to 211 zero.</para><para>Drivers support this function only when they set the 212 <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the 213 <structfield>capability</structfield> field.</para></entry> 214 </row> 215 <row> 216 <entry>__u32</entry> 217 <entry><structfield>extendedmode</structfield></entry> 218 <entry>Custom (driver specific) streaming parameters. When 219 unused, applications and drivers must set this field to zero. 220 Applications using this field should check the driver name and 221 version, see <xref linkend="querycap" />.</entry> 222 </row> 223 <row> 224 <entry>__u32</entry> 225 <entry><structfield>writebuffers</structfield></entry> 226 <entry>Applications set this field to the desired number 227 of buffers used internally by the driver in 228 <function>write()</function> mode. Drivers return the actual number of 229 buffers. When an application requests zero buffers, drivers should 230 just return the current setting rather than the minimum or an error 231 code. For details see <xref linkend="rw" />.</entry> 232 </row> 233 <row> 234 <entry>__u32</entry> 235 <entry><structfield>reserved</structfield>[4]</entry> 236 <entry>Reserved for future extensions. Drivers and 237 applications must set the array to zero.</entry> 238 </row> 239 </tbody> 240 </tgroup> 241 </table> 242 243 <table pgwide="1" frame="none" id="parm-caps"> 244 <title>Streaming Parameters Capabilites</title> 245 <tgroup cols="3"> 246 &cs-def; 247 <tbody valign="top"> 248 <row> 249 <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry> 250 <entry>0x1000</entry> 251 <entry>The frame skipping/repeating controlled by the 252 <structfield>timeperframe</structfield> field is supported.</entry> 253 </row> 254 </tbody> 255 </tgroup> 256 </table> 257 258 <table pgwide="1" frame="none" id="parm-flags"> 259 <title>Capture Parameters Flags</title> 260 <tgroup cols="3"> 261 &cs-def; 262 <tbody valign="top"> 263 <row> 264 <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry> 265 <entry>0x0001</entry> 266 <entry><para>High quality imaging mode. High quality mode 267 is intended for still imaging applications. The idea is to get the 268 best possible image quality that the hardware can deliver. It is not 269 defined how the driver writer may achieve that; it will depend on the 270 hardware and the ingenuity of the driver writer. High quality mode is 271 a different mode from the the regular motion video capture modes. In 272 high quality mode:<itemizedlist> 273 <listitem> 274 <para>The driver may be able to capture higher 275 resolutions than for motion capture.</para> 276 </listitem> 277 <listitem> 278 <para>The driver may support fewer pixel formats 279 than motion capture (eg; true color).</para> 280 </listitem> 281 <listitem> 282 <para>The driver may capture and arithmetically 283 combine multiple successive fields or frames to remove color edge 284 artifacts and reduce the noise in the video data. 285 </para> 286 </listitem> 287 <listitem> 288 <para>The driver may capture images in slices like 289 a scanner in order to handle larger format images than would otherwise 290 be possible. </para> 291 </listitem> 292 <listitem> 293 <para>An image capture operation may be 294 significantly slower than motion capture. </para> 295 </listitem> 296 <listitem> 297 <para>Moving objects in the image might have 298 excessive motion blur. </para> 299 </listitem> 300 <listitem> 301 <para>Capture might only work through the 302 <function>read()</function> call.</para> 303 </listitem> 304 </itemizedlist></para></entry> 305 </row> 306 </tbody> 307 </tgroup> 308 </table> 309 310 </refsect1> 311 312 <refsect1> 313 &return-value; 314 315 <variablelist> 316 <varlistentry> 317 <term><errorcode>EINVAL</errorcode></term> 318 <listitem> 319 <para>This ioctl is not supported.</para> 320 </listitem> 321 </varlistentry> 322 </variablelist> 323 </refsect1> 324 </refentry> 325 326 <!-- 327 Local Variables: 328 mode: sgml 329 sgml-parent-document: "v4l2.sgml" 330 indent-tabs-mode: nil 331 End: 332 -->
