Home | History | Annotate | Download | only in spec 
      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 >Interfaces</TITLE
      6 ><META
      7 NAME="GENERATOR"
      8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
      9 REL="HOME"
     10 TITLE="Video for Linux Two API Specification"
     11 HREF="book1.htm"><LINK
     12 REL="PREVIOUS"
     13 TITLE="Field Order"
     14 HREF="x6386.htm"><LINK
     15 REL="NEXT"
     16 TITLE="Video Overlay Interface"
     17 HREF="x6570.htm"></HEAD
     18 ><BODY
     19 CLASS="CHAPTER"
     20 BGCOLOR="#FFFFFF"
     21 TEXT="#000000"
     22 LINK="#0000FF"
     23 VLINK="#840084"
     24 ALINK="#0000FF"
     25 ><DIV
     26 CLASS="NAVHEADER"
     27 ><TABLE
     28 SUMMARY="Header navigation table"
     29 WIDTH="100%"
     30 BORDER="0"
     31 CELLPADDING="0"
     32 CELLSPACING="0"
     33 ><TR
     34 ><TH
     35 COLSPAN="3"
     36 ALIGN="center"
     37 >Video for Linux Two API Specification: Revision 0.24</TH
     38 ></TR
     39 ><TR
     40 ><TD
     41 WIDTH="10%"
     42 ALIGN="left"
     43 VALIGN="bottom"
     44 ><A
     45 HREF="x6386.htm"
     46 ACCESSKEY="P"
     47 >Prev</A
     48 ></TD
     49 ><TD
     50 WIDTH="80%"
     51 ALIGN="center"
     52 VALIGN="bottom"
     53 ></TD
     54 ><TD
     55 WIDTH="10%"
     56 ALIGN="right"
     57 VALIGN="bottom"
     58 ><A
     59 HREF="x6570.htm"
     60 ACCESSKEY="N"
     61 >Next</A
     62 ></TD
     63 ></TR
     64 ></TABLE
     65 ><HR
     66 ALIGN="LEFT"
     67 WIDTH="100%"></DIV
     68 ><DIV
     69 CLASS="CHAPTER"
     70 ><H1
     71 ><A
     72 NAME="DEVICES"
     73 ></A
     74 >Chapter 4. Interfaces</H1
     75 ><DIV
     76 CLASS="TOC"
     77 ><DL
     78 ><DT
     79 ><B
     80 >Table of Contents</B
     81 ></DT
     82 ><DT
     83 >4.1. <A
     84 HREF="c6488.htm#CAPTURE"
     85 >Video Capture Interface</A
     86 ></DT
     87 ><DT
     88 >4.2. <A
     89 HREF="x6570.htm"
     90 >Video Overlay Interface</A
     91 ></DT
     92 ><DT
     93 >4.3. <A
     94 HREF="x6831.htm"
     95 >Video Output Interface</A
     96 ></DT
     97 ><DT
     98 >4.4. <A
     99 HREF="x6909.htm"
    100 >Video Output Overlay Interface</A
    101 ></DT
    102 ><DT
    103 >4.5. <A
    104 HREF="x6991.htm"
    105 >Codec Interface</A
    106 ></DT
    107 ><DT
    108 >4.6. <A
    109 HREF="x7002.htm"
    110 >Effect Devices Interface</A
    111 ></DT
    112 ><DT
    113 >4.7. <A
    114 HREF="x7013.htm"
    115 >Raw VBI Data Interface</A
    116 ></DT
    117 ><DT
    118 >4.8. <A
    119 HREF="x7236.htm"
    120 >Sliced VBI Data Interface</A
    121 ></DT
    122 ><DT
    123 >4.9. <A
    124 HREF="x7561.htm"
    125 >Teletext Interface</A
    126 ></DT
    127 ><DT
    128 >4.10. <A
    129 HREF="x7578.htm"
    130 >Radio Interface</A
    131 ></DT
    132 ><DT
    133 >4.11. <A
    134 HREF="x7607.htm"
    135 >RDS Interface</A
    136 ></DT
    137 ></DL
    138 ></DIV
    139 ><DIV
    140 CLASS="SECTION"
    141 ><H1
    142 CLASS="SECTION"
    143 ><A
    144 NAME="CAPTURE"
    145 >4.1. Video Capture Interface</A
    146 ></H1
    147 ><P
    148 >Video capture devices sample an analog video signal and store
    149 the digitized images in memory. Today nearly all devices can capture
    150 at full 25 or 30 frames/second. With this interface applications can
    151 control the capture process and move images from the driver into user
    152 space.</P
    153 ><P
    154 >Conventionally V4L2 video capture devices are accessed through
    155 character device special files named <TT
    156 CLASS="FILENAME"
    157 >/dev/video</TT
    158 >
    159 and <TT
    160 CLASS="FILENAME"
    161 >/dev/video0</TT
    162 > to
    163 <TT
    164 CLASS="FILENAME"
    165 >/dev/video63</TT
    166 > with major number 81 and minor
    167 numbers 0 to 63. <TT
    168 CLASS="FILENAME"
    169 >/dev/video</TT
    170 > is typically a
    171 symbolic link to the preferred video device. Note the same device
    172 files are used for video output devices.</P
    173 ><DIV
    174 CLASS="SECTION"
    175 ><H2
    176 CLASS="SECTION"
    177 ><A
    178 NAME="AEN6498"
    179 >4.1.1. Querying Capabilities</A
    180 ></H2
    181 ><P
    182 >Devices supporting the video capture interface set the
    183 <CODE
    184 CLASS="CONSTANT"
    185 >V4L2_CAP_VIDEO_CAPTURE</CODE
    186 > flag in the
    187 <CODE
    188 CLASS="STRUCTFIELD"
    189 >capabilities</CODE
    190 > field of struct&nbsp;<A
    191 HREF="r13105.htm#V4L2-CAPABILITY"
    192 >v4l2_capability</A
    193 >
    194 returned by the <A
    195 HREF="r13105.htm"
    196 ><CODE
    197 CLASS="CONSTANT"
    198 >VIDIOC_QUERYCAP</CODE
    199 ></A
    200 > ioctl. As secondary device functions
    201 they may also support the <A
    202 HREF="x6570.htm"
    203 >video overlay</A
    204 >
    205 (<CODE
    206 CLASS="CONSTANT"
    207 >V4L2_CAP_VIDEO_OVERLAY</CODE
    208 >) and the <A
    209 HREF="x7013.htm"
    210 >raw VBI capture</A
    211 >
    212 (<CODE
    213 CLASS="CONSTANT"
    214 >V4L2_CAP_VBI_CAPTURE</CODE
    215 >) interface. At least one of
    216 the read/write or streaming I/O methods must be supported. Tuners and
    217 audio inputs are optional.</P
    218 ></DIV
    219 ><DIV
    220 CLASS="SECTION"
    221 ><H2
    222 CLASS="SECTION"
    223 ><A
    224 NAME="AEN6510"
    225 >4.1.2. Supplemental Functions</A
    226 ></H2
    227 ><P
    228 >Video capture devices shall support <A
    229 HREF="x341.htm"
    230 >audio input</A
    231 >, <A
    232 HREF="x394.htm"
    233 >tuner</A
    234 >, <A
    235 HREF="x542.htm"
    236 >controls</A
    237 >,
    238 <A
    239 HREF="x1904.htm"
    240 >cropping and scaling</A
    241 > and <A
    242 HREF="x2009.htm"
    243 >streaming parameter</A
    244 > ioctls as needed.
    245 The <A
    246 HREF="x309.htm"
    247 >video input</A
    248 > and <A
    249 HREF="x448.htm"
    250 >video standard</A
    251 > ioctls must be supported by
    252 all video capture devices.</P
    253 ></DIV
    254 ><DIV
    255 CLASS="SECTION"
    256 ><H2
    257 CLASS="SECTION"
    258 ><A
    259 NAME="AEN6520"
    260 >4.1.3. Image Format Negotiation</A
    261 ></H2
    262 ><P
    263 >The result of a capture operation is determined by
    264 cropping and image format parameters. The former select an area of the
    265 video picture to capture, the latter how images are stored in memory,
    266 i.&nbsp;e. in RGB or YUV format, the number of bits per pixel or width and
    267 height. Together they also define how images are scaled in the
    268 process.</P
    269 ><P
    270 >As usual these parameters are <SPAN
    271 CLASS="emphasis"
    272 ><I
    273 CLASS="EMPHASIS"
    274 >not</I
    275 ></SPAN
    276 > reset
    277 at <A
    278 HREF="r14090.htm"
    279 ><CODE
    280 CLASS="FUNCTION"
    281 >open()</CODE
    282 ></A
    283 > time to permit Unix tool chains, programming a device
    284 and then reading from it as if it was a plain file. Well written V4L2
    285 applications ensure they really get what they want, including cropping
    286 and scaling.</P
    287 ><P
    288 >Cropping initialization at minimum requires to reset the
    289 parameters to defaults. An example is given in <A
    290 HREF="x1904.htm"
    291 >Section 1.11</A
    292 >.</P
    293 ><P
    294 >To query the current image format applications set the
    295 <CODE
    296 CLASS="STRUCTFIELD"
    297 >type</CODE
    298 > field of a struct&nbsp;<A
    299 HREF="r10944.htm#V4L2-FORMAT"
    300 >v4l2_format</A
    301 > to
    302 <CODE
    303 CLASS="CONSTANT"
    304 >V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
    305 > and call the
    306 <A
    307 HREF="r10944.htm"
    308 ><CODE
    309 CLASS="CONSTANT"
    310 >VIDIOC_G_FMT</CODE
    311 ></A
    312 > ioctl with a pointer to this structure. Drivers fill
    313 the struct&nbsp;<A
    314 HREF="c2030.htm#V4L2-PIX-FORMAT"
    315 >v4l2_pix_format</A
    316 > <CODE
    317 CLASS="STRUCTFIELD"
    318 >pix</CODE
    319 > member of the
    320 <CODE
    321 CLASS="STRUCTFIELD"
    322 >fmt</CODE
    323 > union.</P
    324 ><P
    325 >To request different parameters applications set the
    326 <CODE
    327 CLASS="STRUCTFIELD"
    328 >type</CODE
    329 > field of a struct&nbsp;<A
    330 HREF="r10944.htm#V4L2-FORMAT"
    331 >v4l2_format</A
    332 > as above and
    333 initialize all fields of the struct&nbsp;<A
    334 HREF="c2030.htm#V4L2-PIX-FORMAT"
    335 >v4l2_pix_format</A
    336 >
    337 <CODE
    338 CLASS="STRUCTFIELD"
    339 >vbi</CODE
    340 > member of the
    341 <CODE
    342 CLASS="STRUCTFIELD"
    343 >fmt</CODE
    344 > union, or better just modify the
    345 results of <CODE
    346 CLASS="CONSTANT"
    347 >VIDIOC_G_FMT</CODE
    348 >, and call the
    349 <A
    350 HREF="r10944.htm"
    351 ><CODE
    352 CLASS="CONSTANT"
    353 >VIDIOC_S_FMT</CODE
    354 ></A
    355 > ioctl with a pointer to this structure. Drivers may
    356 adjust the parameters and finally return the actual parameters as
    357 <CODE
    358 CLASS="CONSTANT"
    359 >VIDIOC_G_FMT</CODE
    360 > does.</P
    361 ><P
    362 >Like <CODE
    363 CLASS="CONSTANT"
    364 >VIDIOC_S_FMT</CODE
    365 > the
    366 <A
    367 HREF="r10944.htm"
    368 ><CODE
    369 CLASS="CONSTANT"
    370 >VIDIOC_TRY_FMT</CODE
    371 ></A
    372 > ioctl can be used to learn about hardware limitations
    373 without disabling I/O or possibly time consuming hardware
    374 preparations.</P
    375 ><P
    376 >The contents of struct&nbsp;<A
    377 HREF="c2030.htm#V4L2-PIX-FORMAT"
    378 >v4l2_pix_format</A
    379 > are discussed in <A
    380 HREF="c2030.htm"
    381 >Chapter 2</A
    382 >. See also the specification of the
    383 <CODE
    384 CLASS="CONSTANT"
    385 >VIDIOC_G_FMT</CODE
    386 >, <CODE
    387 CLASS="CONSTANT"
    388 >VIDIOC_S_FMT</CODE
    389 >
    390 and <CODE
    391 CLASS="CONSTANT"
    392 >VIDIOC_TRY_FMT</CODE
    393 > ioctls for details. Video
    394 capture devices must implement both the
    395 <CODE
    396 CLASS="CONSTANT"
    397 >VIDIOC_G_FMT</CODE
    398 > and
    399 <CODE
    400 CLASS="CONSTANT"
    401 >VIDIOC_S_FMT</CODE
    402 > ioctl, even if
    403 <CODE
    404 CLASS="CONSTANT"
    405 >VIDIOC_S_FMT</CODE
    406 > ignores all requests and always
    407 returns default parameters as <CODE
    408 CLASS="CONSTANT"
    409 >VIDIOC_G_FMT</CODE
    410 > does.
    411 <CODE
    412 CLASS="CONSTANT"
    413 >VIDIOC_TRY_FMT</CODE
    414 > is optional.</P
    415 ></DIV
    416 ><DIV
    417 CLASS="SECTION"
    418 ><H2
    419 CLASS="SECTION"
    420 ><A
    421 NAME="AEN6563"
    422 >4.1.4. Reading Images</A
    423 ></H2
    424 ><P
    425 >A video capture device may support the <A
    426 HREF="c5742.htm#RW"
    427 >read() function</A
    428 > and/or streaming (<A
    429 HREF="x5791.htm"
    430 >memory mapping</A
    431 > or <A
    432 HREF="x5884.htm"
    433 >user pointer</A
    434 >) I/O. See <A
    435 HREF="c5742.htm"
    436 >Chapter 3</A
    437 > for details.</P
    438 ></DIV
    439 ></DIV
    440 ></DIV
    441 ><DIV
    442 CLASS="NAVFOOTER"
    443 ><HR
    444 ALIGN="LEFT"
    445 WIDTH="100%"><TABLE
    446 SUMMARY="Footer navigation table"
    447 WIDTH="100%"
    448 BORDER="0"
    449 CELLPADDING="0"
    450 CELLSPACING="0"
    451 ><TR
    452 ><TD
    453 WIDTH="33%"
    454 ALIGN="left"
    455 VALIGN="top"
    456 ><A
    457 HREF="x6386.htm"
    458 ACCESSKEY="P"
    459 >Prev</A
    460 ></TD
    461 ><TD
    462 WIDTH="34%"
    463 ALIGN="center"
    464 VALIGN="top"
    465 ><A
    466 HREF="book1.htm"
    467 ACCESSKEY="H"
    468 >Home</A
    469 ></TD
    470 ><TD
    471 WIDTH="33%"
    472 ALIGN="right"
    473 VALIGN="top"
    474 ><A
    475 HREF="x6570.htm"
    476 ACCESSKEY="N"
    477 >Next</A
    478 ></TD
    479 ></TR
    480 ><TR
    481 ><TD
    482 WIDTH="33%"
    483 ALIGN="left"
    484 VALIGN="top"
    485 >Field Order</TD
    486 ><TD
    487 WIDTH="34%"
    488 ALIGN="center"
    489 VALIGN="top"
    490 >&nbsp;</TD
    491 ><TD
    492 WIDTH="33%"
    493 ALIGN="right"
    494 VALIGN="top"
    495 >Video Overlay Interface</TD
    496 ></TR
    497 ></TABLE
    498 ></DIV
    499 ></BODY
    500 ></HTML
    501 >
    502