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>Video Output Interface</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="Interfaces" 14HREF="c6488.htm"><LINK 15REL="PREVIOUS" 16TITLE="Video Overlay Interface" 17HREF="x6570.htm"><LINK 18REL="NEXT" 19TITLE="Video Output Overlay Interface" 20HREF="x6909.htm"></HEAD 21><BODY 22CLASS="SECTION" 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="x6570.htm" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56>Chapter 4. Interfaces</TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="x6909.htm" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><DIV 72CLASS="SECTION" 73><H1 74CLASS="SECTION" 75><A 76NAME="OUTPUT" 77>4.3. Video Output Interface</A 78></H1 79><P 80>Video output devices encode stills or image sequences as 81analog video signal. With this interface applications can 82control the encoding process and move images from user space to 83the driver.</P 84><P 85>Conventionally V4L2 video output devices are accessed through 86character device special files named <TT 87CLASS="FILENAME" 88>/dev/video</TT 89> 90and <TT 91CLASS="FILENAME" 92>/dev/video0</TT 93> to 94<TT 95CLASS="FILENAME" 96>/dev/video63</TT 97> with major number 81 and minor 98numbers 0 to 63. <TT 99CLASS="FILENAME" 100>/dev/video</TT 101> is typically a 102symbolic link to the preferred video device. Note the same device 103files are used for video capture devices.</P 104><DIV 105CLASS="SECTION" 106><H2 107CLASS="SECTION" 108><A 109NAME="AEN6839" 110>4.3.1. Querying Capabilities</A 111></H2 112><P 113>Devices supporting the video output interface set the 114<CODE 115CLASS="CONSTANT" 116>V4L2_CAP_VIDEO_OUTPUT</CODE 117> flag in the 118<CODE 119CLASS="STRUCTFIELD" 120>capabilities</CODE 121> field of struct <A 122HREF="r13105.htm#V4L2-CAPABILITY" 123>v4l2_capability</A 124> 125returned by the <A 126HREF="r13105.htm" 127><CODE 128CLASS="CONSTANT" 129>VIDIOC_QUERYCAP</CODE 130></A 131> ioctl. As secondary device functions 132they may also support the <A 133HREF="x7013.htm" 134>raw VBI 135output</A 136> (<CODE 137CLASS="CONSTANT" 138>V4L2_CAP_VBI_OUTPUT</CODE 139>) interface. At 140least one of the read/write or streaming I/O methods must be 141supported. Modulators and audio outputs are optional.</P 142></DIV 143><DIV 144CLASS="SECTION" 145><H2 146CLASS="SECTION" 147><A 148NAME="AEN6849" 149>4.3.2. Supplemental Functions</A 150></H2 151><P 152>Video output devices shall support <A 153HREF="x341.htm" 154>audio output</A 155>, <A 156HREF="x394.htm" 157>modulator</A 158>, <A 159HREF="x542.htm" 160>controls</A 161>, 162<A 163HREF="x1904.htm" 164>cropping and scaling</A 165> and <A 166HREF="x2009.htm" 167>streaming parameter</A 168> ioctls as needed. 169The <A 170HREF="x309.htm" 171>video output</A 172> and <A 173HREF="x448.htm" 174>video standard</A 175> ioctls must be supported by 176all video output devices.</P 177></DIV 178><DIV 179CLASS="SECTION" 180><H2 181CLASS="SECTION" 182><A 183NAME="AEN6859" 184>4.3.3. Image Format Negotiation</A 185></H2 186><P 187>The output is determined by cropping and image format 188parameters. The former select an area of the video picture where the 189image will appear, the latter how images are stored in memory, i. e. in 190RGB or YUV format, the number of bits per pixel or width and height. 191Together they also define how images are scaled in the process.</P 192><P 193>As usual these parameters are <SPAN 194CLASS="emphasis" 195><I 196CLASS="EMPHASIS" 197>not</I 198></SPAN 199> reset 200at <A 201HREF="r14090.htm" 202><CODE 203CLASS="FUNCTION" 204>open()</CODE 205></A 206> time to permit Unix tool chains, programming a device 207and then writing to it as if it was a plain file. Well written V4L2 208applications ensure they really get what they want, including cropping 209and scaling.</P 210><P 211>Cropping initialization at minimum requires to reset the 212parameters to defaults. An example is given in <A 213HREF="x1904.htm" 214>Section 1.11</A 215>.</P 216><P 217>To query the current image format applications set the 218<CODE 219CLASS="STRUCTFIELD" 220>type</CODE 221> field of a struct <A 222HREF="r10944.htm#V4L2-FORMAT" 223>v4l2_format</A 224> to 225<CODE 226CLASS="CONSTANT" 227>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE 228> and call the 229<A 230HREF="r10944.htm" 231><CODE 232CLASS="CONSTANT" 233>VIDIOC_G_FMT</CODE 234></A 235> ioctl with a pointer to this structure. Drivers fill 236the struct <A 237HREF="c2030.htm#V4L2-PIX-FORMAT" 238>v4l2_pix_format</A 239> <CODE 240CLASS="STRUCTFIELD" 241>pix</CODE 242> member of the 243<CODE 244CLASS="STRUCTFIELD" 245>fmt</CODE 246> union.</P 247><P 248>To request different parameters applications set the 249<CODE 250CLASS="STRUCTFIELD" 251>type</CODE 252> field of a struct <A 253HREF="r10944.htm#V4L2-FORMAT" 254>v4l2_format</A 255> as above and 256initialize all fields of the struct <A 257HREF="c2030.htm#V4L2-PIX-FORMAT" 258>v4l2_pix_format</A 259> 260<CODE 261CLASS="STRUCTFIELD" 262>vbi</CODE 263> member of the 264<CODE 265CLASS="STRUCTFIELD" 266>fmt</CODE 267> union, or better just modify the 268results of <CODE 269CLASS="CONSTANT" 270>VIDIOC_G_FMT</CODE 271>, and call the 272<A 273HREF="r10944.htm" 274><CODE 275CLASS="CONSTANT" 276>VIDIOC_S_FMT</CODE 277></A 278> ioctl with a pointer to this structure. Drivers may 279adjust the parameters and finally return the actual parameters as 280<CODE 281CLASS="CONSTANT" 282>VIDIOC_G_FMT</CODE 283> does.</P 284><P 285>Like <CODE 286CLASS="CONSTANT" 287>VIDIOC_S_FMT</CODE 288> the 289<A 290HREF="r10944.htm" 291><CODE 292CLASS="CONSTANT" 293>VIDIOC_TRY_FMT</CODE 294></A 295> ioctl can be used to learn about hardware limitations 296without disabling I/O or possibly time consuming hardware 297preparations.</P 298><P 299>The contents of struct <A 300HREF="c2030.htm#V4L2-PIX-FORMAT" 301>v4l2_pix_format</A 302> are discussed in <A 303HREF="c2030.htm" 304>Chapter 2</A 305>. See also the specification of the 306<CODE 307CLASS="CONSTANT" 308>VIDIOC_G_FMT</CODE 309>, <CODE 310CLASS="CONSTANT" 311>VIDIOC_S_FMT</CODE 312> 313and <CODE 314CLASS="CONSTANT" 315>VIDIOC_TRY_FMT</CODE 316> ioctls for details. Video 317output devices must implement both the 318<CODE 319CLASS="CONSTANT" 320>VIDIOC_G_FMT</CODE 321> and 322<CODE 323CLASS="CONSTANT" 324>VIDIOC_S_FMT</CODE 325> ioctl, even if 326<CODE 327CLASS="CONSTANT" 328>VIDIOC_S_FMT</CODE 329> ignores all requests and always 330returns default parameters as <CODE 331CLASS="CONSTANT" 332>VIDIOC_G_FMT</CODE 333> does. 334<CODE 335CLASS="CONSTANT" 336>VIDIOC_TRY_FMT</CODE 337> is optional.</P 338></DIV 339><DIV 340CLASS="SECTION" 341><H2 342CLASS="SECTION" 343><A 344NAME="AEN6902" 345>4.3.4. Writing Images</A 346></H2 347><P 348>A video output device may support the <A 349HREF="c5742.htm#RW" 350>write() function</A 351> and/or streaming (<A 352HREF="x5791.htm" 353>memory mapping</A 354> or <A 355HREF="x5884.htm" 356>user pointer</A 357>) I/O. See <A 358HREF="c5742.htm" 359>Chapter 3</A 360> for details.</P 361></DIV 362></DIV 363><DIV 364CLASS="NAVFOOTER" 365><HR 366ALIGN="LEFT" 367WIDTH="100%"><TABLE 368SUMMARY="Footer navigation table" 369WIDTH="100%" 370BORDER="0" 371CELLPADDING="0" 372CELLSPACING="0" 373><TR 374><TD 375WIDTH="33%" 376ALIGN="left" 377VALIGN="top" 378><A 379HREF="x6570.htm" 380ACCESSKEY="P" 381>Prev</A 382></TD 383><TD 384WIDTH="34%" 385ALIGN="center" 386VALIGN="top" 387><A 388HREF="book1.htm" 389ACCESSKEY="H" 390>Home</A 391></TD 392><TD 393WIDTH="33%" 394ALIGN="right" 395VALIGN="top" 396><A 397HREF="x6909.htm" 398ACCESSKEY="N" 399>Next</A 400></TD 401></TR 402><TR 403><TD 404WIDTH="33%" 405ALIGN="left" 406VALIGN="top" 407>Video Overlay Interface</TD 408><TD 409WIDTH="34%" 410ALIGN="center" 411VALIGN="top" 412><A 413HREF="c6488.htm" 414ACCESSKEY="U" 415>Up</A 416></TD 417><TD 418WIDTH="33%" 419ALIGN="right" 420VALIGN="top" 421>Video Output Overlay Interface</TD 422></TR 423></TABLE 424></DIV 425></BODY 426></HTML 427> 428