1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 2<HTML 3><HEAD 4><TITLE 5>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9REL="HOME" 10TITLE="Video for Linux Two API Specification" 11HREF="book1.htm"><LINK 12REL="UP" 13TITLE="Function Reference" 14HREF="r7624.htm"><LINK 15REL="PREVIOUS" 16TITLE="ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT" 17HREF="r11612.htm"><LINK 18REL="NEXT" 19TITLE="ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY" 20HREF="r11946.htm"></HEAD 21><BODY 22CLASS="REFENTRY" 23BGCOLOR="#FFFFFF" 24TEXT="#000000" 25LINK="#0000FF" 26VLINK="#840084" 27ALINK="#0000FF" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>Video for Linux Two API Specification: Revision 0.24</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="r11612.htm" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56></TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="r11946.htm" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><H1 72><A 73NAME="VIDIOC-G-PARM" 74></A 75>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</H1 76><DIV 77CLASS="REFNAMEDIV" 78><A 79NAME="AEN11684" 80></A 81><H2 82>Name</H2 83>VIDIOC_G_PARM, VIDIOC_S_PARM -- Get or set streaming parameters</DIV 84><DIV 85CLASS="REFSYNOPSISDIV" 86><A 87NAME="AEN11688" 88></A 89><H2 90>Synopsis</H2 91><DIV 92CLASS="FUNCSYNOPSIS" 93><P 94></P 95><A 96NAME="AEN11689" 97></A 98><P 99><CODE 100><CODE 101CLASS="FUNCDEF" 102>int ioctl</CODE 103>(int fd, int request, v4l2_streamparm *argp);</CODE 104></P 105><P 106></P 107></DIV 108></DIV 109><DIV 110CLASS="REFSECT1" 111><A 112NAME="AEN11699" 113></A 114><H2 115>Arguments</H2 116><P 117></P 118><DIV 119CLASS="VARIABLELIST" 120><DL 121><DT 122><CODE 123CLASS="PARAMETER" 124>fd</CODE 125></DT 126><DD 127><P 128>File descriptor returned by <A 129HREF="r14090.htm" 130><CODE 131CLASS="FUNCTION" 132>open()</CODE 133></A 134>.</P 135></DD 136><DT 137><CODE 138CLASS="PARAMETER" 139>request</CODE 140></DT 141><DD 142><P 143>VIDIOC_G_PARM, VIDIOC_S_PARM</P 144></DD 145><DT 146><CODE 147CLASS="PARAMETER" 148>argp</CODE 149></DT 150><DD 151><P 152></P 153></DD 154></DL 155></DIV 156></DIV 157><DIV 158CLASS="REFSECT1" 159><A 160NAME="AEN11719" 161></A 162><H2 163>Description</H2 164><P 165>The current video standard determines a nominal number of 166frames per second. If less than this number of frames is to be 167captured or output, applications can request frame skipping or 168duplicating on the driver side. This is especially useful when using 169the <CODE 170CLASS="FUNCTION" 171>read()</CODE 172> or <CODE 173CLASS="FUNCTION" 174>write()</CODE 175>, which 176are not augmented by timestamps or sequence counters, and to avoid 177unneccessary data copying.</P 178><P 179>Further these ioctls can be used to determine the number of 180buffers used internally by a driver in read/write mode. For 181implications see the section discussing the <A 182HREF="r14264.htm" 183><CODE 184CLASS="FUNCTION" 185>read()</CODE 186></A 187> 188function.</P 189><P 190>To get and set the streaming parameters applications call 191the <CODE 192CLASS="CONSTANT" 193>VIDIOC_G_PARM</CODE 194> and 195<CODE 196CLASS="CONSTANT" 197>VIDIOC_S_PARM</CODE 198> ioctl, respectively. They take a 199pointer to a struct <CODE 200CLASS="STRUCTNAME" 201>v4l2_streamparm</CODE 202> which 203contains a union holding separate parameters for input and output 204devices.</P 205><DIV 206CLASS="TABLE" 207><A 208NAME="V4L2-STREAMPARM" 209></A 210><P 211><B 212>Table 1. struct <CODE 213CLASS="STRUCTNAME" 214>v4l2_streamparm</CODE 215></B 216></P 217><TABLE 218BORDER="0" 219FRAME="void" 220WIDTH="100%" 221CLASS="CALSTABLE" 222><COL 223WIDTH="20%" 224TITLE="C1"><COL 225WIDTH="20%" 226TITLE="C2"><COL 227WIDTH="20%" 228TITLE="C3"><COL 229WIDTH="40%" 230TITLE="C4"><TBODY 231VALIGN="TOP" 232><TR 233><TD 234>enum <A 235HREF="x5953.htm#V4L2-BUF-TYPE" 236>v4l2_buf_type</A 237></TD 238><TD 239><CODE 240CLASS="STRUCTFIELD" 241>type</CODE 242></TD 243><TD 244> </TD 245><TD 246>The buffer (stream) type, same as struct <A 247HREF="r10944.htm#V4L2-FORMAT" 248>v4l2_format</A 249> 250<CODE 251CLASS="STRUCTFIELD" 252>type</CODE 253>, set by the application.</TD 254></TR 255><TR 256><TD 257>union</TD 258><TD 259><CODE 260CLASS="STRUCTFIELD" 261>parm</CODE 262></TD 263><TD 264> </TD 265><TD 266> </TD 267></TR 268><TR 269><TD 270> </TD 271><TD 272>struct <A 273HREF="r11680.htm#V4L2-CAPTUREPARM" 274>v4l2_captureparm</A 275></TD 276><TD 277><CODE 278CLASS="STRUCTFIELD" 279>capture</CODE 280></TD 281><TD 282>Parameters for capture devices, used when 283<CODE 284CLASS="STRUCTFIELD" 285>type</CODE 286> is 287<CODE 288CLASS="CONSTANT" 289>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE 290>.</TD 291></TR 292><TR 293><TD 294> </TD 295><TD 296>struct <A 297HREF="r11680.htm#V4L2-OUTPUTPARM" 298>v4l2_outputparm</A 299></TD 300><TD 301><CODE 302CLASS="STRUCTFIELD" 303>output</CODE 304></TD 305><TD 306>Parameters for output devices, used when 307<CODE 308CLASS="STRUCTFIELD" 309>type</CODE 310> is 311<CODE 312CLASS="CONSTANT" 313>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE 314>.</TD 315></TR 316><TR 317><TD 318> </TD 319><TD 320>__u8</TD 321><TD 322><CODE 323CLASS="STRUCTFIELD" 324>raw_data</CODE 325>[200]</TD 326><TD 327>A place holder for future extensions and custom 328(driver defined) buffer types <CODE 329CLASS="CONSTANT" 330>V4L2_BUF_TYPE_PRIVATE</CODE 331> and 332higher.</TD 333></TR 334></TBODY 335></TABLE 336></DIV 337><DIV 338CLASS="TABLE" 339><A 340NAME="V4L2-CAPTUREPARM" 341></A 342><P 343><B 344>Table 2. struct <CODE 345CLASS="STRUCTNAME" 346>v4l2_captureparm</CODE 347></B 348></P 349><TABLE 350BORDER="0" 351FRAME="void" 352WIDTH="100%" 353CLASS="CALSTABLE" 354><COL 355WIDTH="25%" 356TITLE="C1"><COL 357WIDTH="25%" 358TITLE="C2"><COL 359WIDTH="50%" 360TITLE="C3"><TBODY 361VALIGN="TOP" 362><TR 363><TD 364>__u32</TD 365><TD 366><CODE 367CLASS="STRUCTFIELD" 368>capability</CODE 369></TD 370><TD 371>See <A 372HREF="r11680.htm#PARM-CAPS" 373>Table 4</A 374>.</TD 375></TR 376><TR 377><TD 378>__u32</TD 379><TD 380><CODE 381CLASS="STRUCTFIELD" 382>capturemode</CODE 383></TD 384><TD 385>Set by drivers and applications, see <A 386HREF="r11680.htm#PARM-FLAGS" 387>Table 5</A 388>.</TD 389></TR 390><TR 391><TD 392>struct <A 393HREF="r9288.htm#V4L2-FRACT" 394>v4l2_fract</A 395></TD 396><TD 397><CODE 398CLASS="STRUCTFIELD" 399>timeperframe</CODE 400></TD 401><TD 402><P 403>This is is the desired period between 404successive frames captured by the driver, in seconds. The 405field is intended to skip frames on the driver side, saving I/O 406bandwidth.</P 407><P 408>Applications store here the desired frame 409period, drivers return the actual frame period, which must be greater 410or equal to the nominal frame period determined by the current video 411standard (struct <A 412HREF="r9288.htm#V4L2-STANDARD" 413>v4l2_standard</A 414> <CODE 415CLASS="STRUCTFIELD" 416>frameperiod</CODE 417> 418field). Changing the video standard (also implicitly by switching the 419video input) may reset this parameter to the nominal frame period. To 420reset manually applications can just set this field to 421zero.</P 422><P 423>Drivers support this function only when they set the 424<CODE 425CLASS="CONSTANT" 426>V4L2_CAP_TIMEPERFRAME</CODE 427> flag in the 428<CODE 429CLASS="STRUCTFIELD" 430>capability</CODE 431> field.</P 432></TD 433></TR 434><TR 435><TD 436>__u32</TD 437><TD 438><CODE 439CLASS="STRUCTFIELD" 440>extendedmode</CODE 441></TD 442><TD 443>Custom (driver specific) streaming parameters. When 444unused, applications and drivers must set this field to zero. 445Applications using this field should check the driver name and 446version, see <A 447HREF="x282.htm" 448>Section 1.2</A 449>.</TD 450></TR 451><TR 452><TD 453>__u32</TD 454><TD 455><CODE 456CLASS="STRUCTFIELD" 457>readbuffers</CODE 458></TD 459><TD 460>Applications set this field to the desired number 461of buffers used internally by the driver in <A 462HREF="r14264.htm" 463><CODE 464CLASS="FUNCTION" 465>read()</CODE 466></A 467> mode. Drivers 468return the actual number of buffers. When an application requests zero 469buffers, drivers should just return the current setting rather than 470the minimum or an error code. For details see <A 471HREF="c5742.htm#RW" 472>Section 3.1</A 473>.</TD 474></TR 475><TR 476><TD 477>__u32</TD 478><TD 479><CODE 480CLASS="STRUCTFIELD" 481>reserved</CODE 482>[4]</TD 483><TD 484>Reserved for future extensions. Drivers and 485applications must set the array to zero.</TD 486></TR 487></TBODY 488></TABLE 489></DIV 490><DIV 491CLASS="TABLE" 492><A 493NAME="V4L2-OUTPUTPARM" 494></A 495><P 496><B 497>Table 3. struct <CODE 498CLASS="STRUCTNAME" 499>v4l2_outputparm</CODE 500></B 501></P 502><TABLE 503BORDER="0" 504FRAME="void" 505WIDTH="100%" 506CLASS="CALSTABLE" 507><COL 508WIDTH="25%" 509TITLE="C1"><COL 510WIDTH="25%" 511TITLE="C2"><COL 512WIDTH="50%" 513TITLE="C3"><TBODY 514VALIGN="TOP" 515><TR 516><TD 517>__u32</TD 518><TD 519><CODE 520CLASS="STRUCTFIELD" 521>capability</CODE 522></TD 523><TD 524>See <A 525HREF="r11680.htm#PARM-CAPS" 526>Table 4</A 527>.</TD 528></TR 529><TR 530><TD 531>__u32</TD 532><TD 533><CODE 534CLASS="STRUCTFIELD" 535>outputmode</CODE 536></TD 537><TD 538>Set by drivers and applications, see <A 539HREF="r11680.htm#PARM-FLAGS" 540>Table 5</A 541>.</TD 542></TR 543><TR 544><TD 545>struct <A 546HREF="r9288.htm#V4L2-FRACT" 547>v4l2_fract</A 548></TD 549><TD 550><CODE 551CLASS="STRUCTFIELD" 552>timeperframe</CODE 553></TD 554><TD 555>This is is the desired period between 556successive frames output by the driver, in seconds.</TD 557></TR 558><TR 559><TD 560COLSPAN="3" 561><P 562>The field is intended to 563repeat frames on the driver side in <A 564HREF="r14496.htm" 565><CODE 566CLASS="FUNCTION" 567>write()</CODE 568></A 569> mode (in streaming 570mode timestamps can be used to throttle the output), saving I/O 571bandwidth.</P 572><P 573>Applications store here the desired frame 574period, drivers return the actual frame period, which must be greater 575or equal to the nominal frame period determined by the current video 576standard (struct <A 577HREF="r9288.htm#V4L2-STANDARD" 578>v4l2_standard</A 579> <CODE 580CLASS="STRUCTFIELD" 581>frameperiod</CODE 582> 583field). Changing the video standard (also implicitly by switching the 584video output) may reset this parameter to the nominal frame period. To 585reset manually applications can just set this field to 586zero.</P 587><P 588>Drivers support this function only when they set the 589<CODE 590CLASS="CONSTANT" 591>V4L2_CAP_TIMEPERFRAME</CODE 592> flag in the 593<CODE 594CLASS="STRUCTFIELD" 595>capability</CODE 596> field.</P 597></TD 598></TR 599><TR 600><TD 601>__u32</TD 602><TD 603><CODE 604CLASS="STRUCTFIELD" 605>extendedmode</CODE 606></TD 607><TD 608>Custom (driver specific) streaming parameters. When 609unused, applications and drivers must set this field to zero. 610Applications using this field should check the driver name and 611version, see <A 612HREF="x282.htm" 613>Section 1.2</A 614>.</TD 615></TR 616><TR 617><TD 618>__u32</TD 619><TD 620><CODE 621CLASS="STRUCTFIELD" 622>writebuffers</CODE 623></TD 624><TD 625>Applications set this field to the desired number 626of buffers used internally by the driver in 627<CODE 628CLASS="FUNCTION" 629>write()</CODE 630> mode. Drivers return the actual number of 631buffers. When an application requests zero buffers, drivers should 632just return the current setting rather than the minimum or an error 633code. For details see <A 634HREF="c5742.htm#RW" 635>Section 3.1</A 636>.</TD 637></TR 638><TR 639><TD 640>__u32</TD 641><TD 642><CODE 643CLASS="STRUCTFIELD" 644>reserved</CODE 645>[4]</TD 646><TD 647>Reserved for future extensions. Drivers and 648applications must set the array to zero.</TD 649></TR 650></TBODY 651></TABLE 652></DIV 653><DIV 654CLASS="TABLE" 655><A 656NAME="PARM-CAPS" 657></A 658><P 659><B 660>Table 4. Streaming Parameters Capabilites</B 661></P 662><TABLE 663BORDER="0" 664FRAME="void" 665WIDTH="100%" 666CLASS="CALSTABLE" 667><COL 668WIDTH="38%" 669TITLE="C1"><COL 670WIDTH="12%" 671TITLE="C2"><COL 672WIDTH="50%" 673TITLE="C3"><TBODY 674VALIGN="TOP" 675><TR 676><TD 677><CODE 678CLASS="CONSTANT" 679>V4L2_CAP_TIMEPERFRAME</CODE 680></TD 681><TD 682>0x1000</TD 683><TD 684>The frame skipping/repeating controlled by the 685<CODE 686CLASS="STRUCTFIELD" 687>timeperframe</CODE 688> field is supported.</TD 689></TR 690></TBODY 691></TABLE 692></DIV 693><DIV 694CLASS="TABLE" 695><A 696NAME="PARM-FLAGS" 697></A 698><P 699><B 700>Table 5. Capture Parameters Flags</B 701></P 702><TABLE 703BORDER="0" 704FRAME="void" 705WIDTH="100%" 706CLASS="CALSTABLE" 707><COL 708WIDTH="38%" 709TITLE="C1"><COL 710WIDTH="12%" 711TITLE="C2"><COL 712WIDTH="50%" 713TITLE="C3"><TBODY 714VALIGN="TOP" 715><TR 716><TD 717><CODE 718CLASS="CONSTANT" 719>V4L2_MODE_HIGHQUALITY</CODE 720></TD 721><TD 722>0x0001</TD 723><TD 724><P 725>High quality imaging mode. High quality mode 726is intended for still imaging applications. The idea is to get the 727best possible image quality that the hardware can deliver. It is not 728defined how the driver writer may achieve that; it will depend on the 729hardware and the ingenuity of the driver writer. High quality mode is 730a different mode from the the regular motion video capture modes. In 731high quality mode:<P 732></P 733><UL 734><LI 735><P 736>The driver may be able to capture higher 737resolutions than for motion capture.</P 738></LI 739><LI 740><P 741>The driver may support fewer pixel formats 742than motion capture (eg; true color).</P 743></LI 744><LI 745><P 746>The driver may capture and arithmetically 747combine multiple successive fields or frames to remove color edge 748artifacts and reduce the noise in the video data.</P 749></LI 750><LI 751><P 752>The driver may capture images in slices like 753a scanner in order to handle larger format images than would otherwise 754be possible. </P 755></LI 756><LI 757><P 758>An image capture operation may be 759significantly slower than motion capture. </P 760></LI 761><LI 762><P 763>Moving objects in the image might have 764excessive motion blur. </P 765></LI 766><LI 767><P 768>Capture might only work through the 769<CODE 770CLASS="FUNCTION" 771>read()</CODE 772> call.</P 773></LI 774></UL 775></P 776></TD 777></TR 778></TBODY 779></TABLE 780></DIV 781></DIV 782><DIV 783CLASS="REFSECT1" 784><A 785NAME="AEN11934" 786></A 787><H2 788>Return Value</H2 789><P 790>On success <SPAN 791CLASS="RETURNVALUE" 792>0</SPAN 793> is returned, on error <SPAN 794CLASS="RETURNVALUE" 795>-1</SPAN 796> and the <CODE 797CLASS="VARNAME" 798>errno</CODE 799> variable is set appropriately:</P 800><P 801></P 802><DIV 803CLASS="VARIABLELIST" 804><DL 805><DT 806><SPAN 807CLASS="ERRORCODE" 808>EINVAL</SPAN 809></DT 810><DD 811><P 812>This ioctl is not supported.</P 813></DD 814></DL 815></DIV 816></DIV 817><DIV 818CLASS="NAVFOOTER" 819><HR 820ALIGN="LEFT" 821WIDTH="100%"><TABLE 822SUMMARY="Footer navigation table" 823WIDTH="100%" 824BORDER="0" 825CELLPADDING="0" 826CELLSPACING="0" 827><TR 828><TD 829WIDTH="33%" 830ALIGN="left" 831VALIGN="top" 832><A 833HREF="r11612.htm" 834ACCESSKEY="P" 835>Prev</A 836></TD 837><TD 838WIDTH="34%" 839ALIGN="center" 840VALIGN="top" 841><A 842HREF="book1.htm" 843ACCESSKEY="H" 844>Home</A 845></TD 846><TD 847WIDTH="33%" 848ALIGN="right" 849VALIGN="top" 850><A 851HREF="r11946.htm" 852ACCESSKEY="N" 853>Next</A 854></TD 855></TR 856><TR 857><TD 858WIDTH="33%" 859ALIGN="left" 860VALIGN="top" 861>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</TD 862><TD 863WIDTH="34%" 864ALIGN="center" 865VALIGN="top" 866><A 867HREF="r7624.htm" 868ACCESSKEY="U" 869>Up</A 870></TD 871><TD 872WIDTH="33%" 873ALIGN="right" 874VALIGN="top" 875>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</TD 876></TR 877></TABLE 878></DIV 879></BODY 880></HTML 881> 882