| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> |
| <HTML |
| ><HEAD |
| ><TITLE |
| >Interfaces</TITLE |
| ><META |
| NAME="GENERATOR" |
| CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK |
| REL="HOME" |
| TITLE="Video for Linux Two API Specification" |
| HREF="book1.htm"><LINK |
| REL="PREVIOUS" |
| TITLE="Field Order" |
| HREF="x6386.htm"><LINK |
| REL="NEXT" |
| TITLE="Video Overlay Interface" |
| HREF="x6570.htm"></HEAD |
| ><BODY |
| CLASS="CHAPTER" |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#840084" |
| ALINK="#0000FF" |
| ><DIV |
| CLASS="NAVHEADER" |
| ><TABLE |
| SUMMARY="Header navigation table" |
| WIDTH="100%" |
| BORDER="0" |
| CELLPADDING="0" |
| CELLSPACING="0" |
| ><TR |
| ><TH |
| COLSPAN="3" |
| ALIGN="center" |
| >Video for Linux Two API Specification: Revision 0.24</TH |
| ></TR |
| ><TR |
| ><TD |
| WIDTH="10%" |
| ALIGN="left" |
| VALIGN="bottom" |
| ><A |
| HREF="x6386.htm" |
| ACCESSKEY="P" |
| >Prev</A |
| ></TD |
| ><TD |
| WIDTH="80%" |
| ALIGN="center" |
| VALIGN="bottom" |
| ></TD |
| ><TD |
| WIDTH="10%" |
| ALIGN="right" |
| VALIGN="bottom" |
| ><A |
| HREF="x6570.htm" |
| ACCESSKEY="N" |
| >Next</A |
| ></TD |
| ></TR |
| ></TABLE |
| ><HR |
| ALIGN="LEFT" |
| WIDTH="100%"></DIV |
| ><DIV |
| CLASS="CHAPTER" |
| ><H1 |
| ><A |
| NAME="DEVICES" |
| ></A |
| >Chapter 4. Interfaces</H1 |
| ><DIV |
| CLASS="TOC" |
| ><DL |
| ><DT |
| ><B |
| >Table of Contents</B |
| ></DT |
| ><DT |
| >4.1. <A |
| HREF="c6488.htm#CAPTURE" |
| >Video Capture Interface</A |
| ></DT |
| ><DT |
| >4.2. <A |
| HREF="x6570.htm" |
| >Video Overlay Interface</A |
| ></DT |
| ><DT |
| >4.3. <A |
| HREF="x6831.htm" |
| >Video Output Interface</A |
| ></DT |
| ><DT |
| >4.4. <A |
| HREF="x6909.htm" |
| >Video Output Overlay Interface</A |
| ></DT |
| ><DT |
| >4.5. <A |
| HREF="x6991.htm" |
| >Codec Interface</A |
| ></DT |
| ><DT |
| >4.6. <A |
| HREF="x7002.htm" |
| >Effect Devices Interface</A |
| ></DT |
| ><DT |
| >4.7. <A |
| HREF="x7013.htm" |
| >Raw VBI Data Interface</A |
| ></DT |
| ><DT |
| >4.8. <A |
| HREF="x7236.htm" |
| >Sliced VBI Data Interface</A |
| ></DT |
| ><DT |
| >4.9. <A |
| HREF="x7561.htm" |
| >Teletext Interface</A |
| ></DT |
| ><DT |
| >4.10. <A |
| HREF="x7578.htm" |
| >Radio Interface</A |
| ></DT |
| ><DT |
| >4.11. <A |
| HREF="x7607.htm" |
| >RDS Interface</A |
| ></DT |
| ></DL |
| ></DIV |
| ><DIV |
| CLASS="SECTION" |
| ><H1 |
| CLASS="SECTION" |
| ><A |
| NAME="CAPTURE" |
| >4.1. Video Capture Interface</A |
| ></H1 |
| ><P |
| >Video capture devices sample an analog video signal and store |
| the digitized images in memory. Today nearly all devices can capture |
| at full 25 or 30 frames/second. With this interface applications can |
| control the capture process and move images from the driver into user |
| space.</P |
| ><P |
| >Conventionally V4L2 video capture devices are accessed through |
| character device special files named <TT |
| CLASS="FILENAME" |
| >/dev/video</TT |
| > |
| and <TT |
| CLASS="FILENAME" |
| >/dev/video0</TT |
| > to |
| <TT |
| CLASS="FILENAME" |
| >/dev/video63</TT |
| > with major number 81 and minor |
| numbers 0 to 63. <TT |
| CLASS="FILENAME" |
| >/dev/video</TT |
| > is typically a |
| symbolic link to the preferred video device. Note the same device |
| files are used for video output devices.</P |
| ><DIV |
| CLASS="SECTION" |
| ><H2 |
| CLASS="SECTION" |
| ><A |
| NAME="AEN6498" |
| >4.1.1. Querying Capabilities</A |
| ></H2 |
| ><P |
| >Devices supporting the video capture interface set the |
| <CODE |
| CLASS="CONSTANT" |
| >V4L2_CAP_VIDEO_CAPTURE</CODE |
| > flag in the |
| <CODE |
| CLASS="STRUCTFIELD" |
| >capabilities</CODE |
| > field of struct <A |
| HREF="r13105.htm#V4L2-CAPABILITY" |
| >v4l2_capability</A |
| > |
| returned by the <A |
| HREF="r13105.htm" |
| ><CODE |
| CLASS="CONSTANT" |
| >VIDIOC_QUERYCAP</CODE |
| ></A |
| > ioctl. As secondary device functions |
| they may also support the <A |
| HREF="x6570.htm" |
| >video overlay</A |
| > |
| (<CODE |
| CLASS="CONSTANT" |
| >V4L2_CAP_VIDEO_OVERLAY</CODE |
| >) and the <A |
| HREF="x7013.htm" |
| >raw VBI capture</A |
| > |
| (<CODE |
| CLASS="CONSTANT" |
| >V4L2_CAP_VBI_CAPTURE</CODE |
| >) interface. At least one of |
| the read/write or streaming I/O methods must be supported. Tuners and |
| audio inputs are optional.</P |
| ></DIV |
| ><DIV |
| CLASS="SECTION" |
| ><H2 |
| CLASS="SECTION" |
| ><A |
| NAME="AEN6510" |
| >4.1.2. Supplemental Functions</A |
| ></H2 |
| ><P |
| >Video capture devices shall support <A |
| HREF="x341.htm" |
| >audio input</A |
| >, <A |
| HREF="x394.htm" |
| >tuner</A |
| >, <A |
| HREF="x542.htm" |
| >controls</A |
| >, |
| <A |
| HREF="x1904.htm" |
| >cropping and scaling</A |
| > and <A |
| HREF="x2009.htm" |
| >streaming parameter</A |
| > ioctls as needed. |
| The <A |
| HREF="x309.htm" |
| >video input</A |
| > and <A |
| HREF="x448.htm" |
| >video standard</A |
| > ioctls must be supported by |
| all video capture devices.</P |
| ></DIV |
| ><DIV |
| CLASS="SECTION" |
| ><H2 |
| CLASS="SECTION" |
| ><A |
| NAME="AEN6520" |
| >4.1.3. Image Format Negotiation</A |
| ></H2 |
| ><P |
| >The result of a capture operation is determined by |
| cropping and image format parameters. The former select an area of the |
| video picture to capture, the latter how images are stored in memory, |
| i. e. in RGB or YUV format, the number of bits per pixel or width and |
| height. Together they also define how images are scaled in the |
| process.</P |
| ><P |
| >As usual these parameters are <SPAN |
| CLASS="emphasis" |
| ><I |
| CLASS="EMPHASIS" |
| >not</I |
| ></SPAN |
| > reset |
| at <A |
| HREF="r14090.htm" |
| ><CODE |
| CLASS="FUNCTION" |
| >open()</CODE |
| ></A |
| > time to permit Unix tool chains, programming a device |
| and then reading from it as if it was a plain file. Well written V4L2 |
| applications ensure they really get what they want, including cropping |
| and scaling.</P |
| ><P |
| >Cropping initialization at minimum requires to reset the |
| parameters to defaults. An example is given in <A |
| HREF="x1904.htm" |
| >Section 1.11</A |
| >.</P |
| ><P |
| >To query the current image format applications set the |
| <CODE |
| CLASS="STRUCTFIELD" |
| >type</CODE |
| > field of a struct <A |
| HREF="r10944.htm#V4L2-FORMAT" |
| >v4l2_format</A |
| > to |
| <CODE |
| CLASS="CONSTANT" |
| >V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE |
| > and call the |
| <A |
| HREF="r10944.htm" |
| ><CODE |
| CLASS="CONSTANT" |
| >VIDIOC_G_FMT</CODE |
| ></A |
| > ioctl with a pointer to this structure. Drivers fill |
| the struct <A |
| HREF="c2030.htm#V4L2-PIX-FORMAT" |
| >v4l2_pix_format</A |
| > <CODE |
| CLASS="STRUCTFIELD" |
| >pix</CODE |
| > member of the |
| <CODE |
| CLASS="STRUCTFIELD" |
| >fmt</CODE |
| > union.</P |
| ><P |
| >To request different parameters applications set the |
| <CODE |
| CLASS="STRUCTFIELD" |
| >type</CODE |
| > field of a struct <A |
| HREF="r10944.htm#V4L2-FORMAT" |
| >v4l2_format</A |
| > as above and |
| initialize all fields of the struct <A |
| HREF="c2030.htm#V4L2-PIX-FORMAT" |
| >v4l2_pix_format</A |
| > |
| <CODE |
| CLASS="STRUCTFIELD" |
| >vbi</CODE |
| > member of the |
| <CODE |
| CLASS="STRUCTFIELD" |
| >fmt</CODE |
| > union, or better just modify the |
| results of <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_G_FMT</CODE |
| >, and call the |
| <A |
| HREF="r10944.htm" |
| ><CODE |
| CLASS="CONSTANT" |
| >VIDIOC_S_FMT</CODE |
| ></A |
| > ioctl with a pointer to this structure. Drivers may |
| adjust the parameters and finally return the actual parameters as |
| <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_G_FMT</CODE |
| > does.</P |
| ><P |
| >Like <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_S_FMT</CODE |
| > the |
| <A |
| HREF="r10944.htm" |
| ><CODE |
| CLASS="CONSTANT" |
| >VIDIOC_TRY_FMT</CODE |
| ></A |
| > ioctl can be used to learn about hardware limitations |
| without disabling I/O or possibly time consuming hardware |
| preparations.</P |
| ><P |
| >The contents of struct <A |
| HREF="c2030.htm#V4L2-PIX-FORMAT" |
| >v4l2_pix_format</A |
| > are discussed in <A |
| HREF="c2030.htm" |
| >Chapter 2</A |
| >. See also the specification of the |
| <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_G_FMT</CODE |
| >, <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_S_FMT</CODE |
| > |
| and <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_TRY_FMT</CODE |
| > ioctls for details. Video |
| capture devices must implement both the |
| <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_G_FMT</CODE |
| > and |
| <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_S_FMT</CODE |
| > ioctl, even if |
| <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_S_FMT</CODE |
| > ignores all requests and always |
| returns default parameters as <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_G_FMT</CODE |
| > does. |
| <CODE |
| CLASS="CONSTANT" |
| >VIDIOC_TRY_FMT</CODE |
| > is optional.</P |
| ></DIV |
| ><DIV |
| CLASS="SECTION" |
| ><H2 |
| CLASS="SECTION" |
| ><A |
| NAME="AEN6563" |
| >4.1.4. Reading Images</A |
| ></H2 |
| ><P |
| >A video capture device may support the <A |
| HREF="c5742.htm#RW" |
| >read() function</A |
| > and/or streaming (<A |
| HREF="x5791.htm" |
| >memory mapping</A |
| > or <A |
| HREF="x5884.htm" |
| >user pointer</A |
| >) I/O. See <A |
| HREF="c5742.htm" |
| >Chapter 3</A |
| > for details.</P |
| ></DIV |
| ></DIV |
| ></DIV |
| ><DIV |
| CLASS="NAVFOOTER" |
| ><HR |
| ALIGN="LEFT" |
| WIDTH="100%"><TABLE |
| SUMMARY="Footer navigation table" |
| WIDTH="100%" |
| BORDER="0" |
| CELLPADDING="0" |
| CELLSPACING="0" |
| ><TR |
| ><TD |
| WIDTH="33%" |
| ALIGN="left" |
| VALIGN="top" |
| ><A |
| HREF="x6386.htm" |
| ACCESSKEY="P" |
| >Prev</A |
| ></TD |
| ><TD |
| WIDTH="34%" |
| ALIGN="center" |
| VALIGN="top" |
| ><A |
| HREF="book1.htm" |
| ACCESSKEY="H" |
| >Home</A |
| ></TD |
| ><TD |
| WIDTH="33%" |
| ALIGN="right" |
| VALIGN="top" |
| ><A |
| HREF="x6570.htm" |
| ACCESSKEY="N" |
| >Next</A |
| ></TD |
| ></TR |
| ><TR |
| ><TD |
| WIDTH="33%" |
| ALIGN="left" |
| VALIGN="top" |
| >Field Order</TD |
| ><TD |
| WIDTH="34%" |
| ALIGN="center" |
| VALIGN="top" |
| > </TD |
| ><TD |
| WIDTH="33%" |
| ALIGN="right" |
| VALIGN="top" |
| >Video Overlay Interface</TD |
| ></TR |
| ></TABLE |
| ></DIV |
| ></BODY |
| ></HTML |
| > |