diff options
| author | Mauro Carvalho Chehab <devnull@localhost> | 2005-06-06 05:06:27 +0000 |
|---|---|---|
| committer | Mauro Carvalho Chehab <devnull@localhost> | 2005-06-06 05:06:27 +0000 |
| commit | f8d05d9880fd42933c22b034c6d7a66616bbc75f (patch) | |
| tree | a569f6a86782fe1f56c5bb78ce18bec8535558b1 | |
| parent | 3adf8f9ab443cee03665784580e82ea4a33ce005 (diff) | |
| download | mediapointer-dvb-s2-f8d05d9880fd42933c22b034c6d7a66616bbc75f.tar.gz mediapointer-dvb-s2-f8d05d9880fd42933c22b034c6d7a66616bbc75f.tar.bz2 | |
Include API specs for both versions:
* doc/V4L2_API.html:
- Included V4L2 API from http://v4l2spec.bytesex.org
*doc/V4L1_API.html
- Include Obsoleted V4L API from doc on kernel-2.6.12-rc5-mm2
| -rw-r--r-- | v4l/API/V4L1_API.html | 399 | ||||
| -rw-r--r-- | v4l/API/V4L2_API.html | 39683 | ||||
| -rw-r--r-- | v4l/ChangeLog | 9 |
3 files changed, 40090 insertions, 1 deletions
diff --git a/v4l/API/V4L1_API.html b/v4l/API/V4L1_API.html new file mode 100644 index 000000000..4b3d8f640 --- /dev/null +++ b/v4l/API/V4L1_API.html @@ -0,0 +1,399 @@ +<HTML><HEAD> +<TITLE>Video4Linux Kernel API Reference v0.1:19990430</TITLE> +</HEAD> +<! Revision History: > +<! 4/30/1999 - Fred Gleason (fredg@wava.com)> +<! Documented extensions for the Radio Data System (RDS) extensions > +<BODY bgcolor="#ffffff"> +<H3>Devices</H3> +Video4Linux provides the following sets of device files. These live on the +character device formerly known as "/dev/bttv". /dev/bttv should be a +symlink to /dev/video0 for most people. +<P> +<TABLE> +<TR><TH>Device Name</TH><TH>Minor Range</TH><TH>Function</TH> +<TR><TD>/dev/video</TD><TD>0-63</TD><TD>Video Capture Interface</TD> +<TR><TD>/dev/radio</TD><TD>64-127</TD><TD>AM/FM Radio Devices</TD> +<TR><TD>/dev/vtx</TD><TD>192-223</TD><TD>Teletext Interface Chips</TD> +<TR><TD>/dev/vbi</TD><TD>224-239</TD><TD>Raw VBI Data (Intercast/teletext)</TD> +</TABLE> +<P> +Video4Linux programs open and scan the devices to find what they are looking +for. Capability queries define what each interface supports. The +described API is only defined for video capture cards. The relevant subset +applies to radio cards. Teletext interfaces talk the existing VTX API. +<P> +<H3>Capability Query Ioctl</H3> +The <B>VIDIOCGCAP</B> ioctl call is used to obtain the capability +information for a video device. The <b>struct video_capability</b> object +passed to the ioctl is completed and returned. It contains the following +information +<P> +<TABLE> +<TR><TD><b>name[32]</b><TD>Canonical name for this interface</TD> +<TR><TD><b>type</b><TD>Type of interface</TD> +<TR><TD><b>channels</b><TD>Number of radio/tv channels if appropriate</TD> +<TR><TD><b>audios</b><TD>Number of audio devices if appropriate</TD> +<TR><TD><b>maxwidth</b><TD>Maximum capture width in pixels</TD> +<TR><TD><b>maxheight</b><TD>Maximum capture height in pixels</TD> +<TR><TD><b>minwidth</b><TD>Minimum capture width in pixels</TD> +<TR><TD><b>minheight</b><TD>Minimum capture height in pixels</TD> +</TABLE> +<P> +The type field lists the capability flags for the device. These are +as follows +<P> +<TABLE> +<TR><TH>Name</TH><TH>Description</TH> +<TR><TD><b>VID_TYPE_CAPTURE</b><TD>Can capture to memory</TD> +<TR><TD><b>VID_TYPE_TUNER</b><TD>Has a tuner of some form</TD> +<TR><TD><b>VID_TYPE_TELETEXT</b><TD>Has teletext capability</TD> +<TR><TD><b>VID_TYPE_OVERLAY</b><TD>Can overlay its image onto the frame buffer</TD> +<TR><TD><b>VID_TYPE_CHROMAKEY</b><TD>Overlay is Chromakeyed</TD> +<TR><TD><b>VID_TYPE_CLIPPING</b><TD>Overlay clipping is supported</TD> +<TR><TD><b>VID_TYPE_FRAMERAM</b><TD>Overlay overwrites frame buffer memory</TD> +<TR><TD><b>VID_TYPE_SCALES</b><TD>The hardware supports image scaling</TD> +<TR><TD><b>VID_TYPE_MONOCHROME</b><TD>Image capture is grey scale only</TD> +<TR><TD><b>VID_TYPE_SUBCAPTURE</b><TD>Capture can be of only part of the image</TD> +</TABLE> +<P> +The minimum and maximum sizes listed for a capture device do not imply all +that all height/width ratios or sizes within the range are possible. A +request to set a size will be honoured by the largest available capture +size whose capture is no large than the requested rectangle in either +direction. For example the quickcam has 3 fixed settings. +<P> +<H3>Frame Buffer</H3> +Capture cards that drop data directly onto the frame buffer must be told the +base address of the frame buffer, its size and organisation. This is a +privileged ioctl and one that eventually X itself should set. +<P> +The <b>VIDIOCSFBUF</b> ioctl sets the frame buffer parameters for a capture +card. If the card does not do direct writes to the frame buffer then this +ioctl will be unsupported. The <b>VIDIOCGFBUF</b> ioctl returns the +currently used parameters. The structure used in both cases is a +<b>struct video_buffer</b>. +<P> +<TABLE> +<TR><TD><b>void *base</b></TD><TD>Base physical address of the buffer</TD> +<TR><TD><b>int height</b></TD><TD>Height of the frame buffer</TD> +<TR><TD><b>int width</b></TD><TD>Width of the frame buffer</TD> +<TR><TD><b>int depth</b></TD><TD>Depth of the frame buffer</TD> +<TR><TD><b>int bytesperline</b></TD><TD>Number of bytes of memory between the start of two adjacent lines</TD> +</TABLE> +<P> +Note that these values reflect the physical layout of the frame buffer. +The visible area may be smaller. In fact under XFree86 this is commonly the +case. XFree86 DGA can provide the parameters required to set up this ioctl. +Setting the base address to NULL indicates there is no physical frame buffer +access. +<P> +<H3>Capture Windows</H3> +The capture area is described by a <b>struct video_window</b>. This defines +a capture area and the clipping information if relevant. The +<b>VIDIOCGWIN</b> ioctl recovers the current settings and the +<b>VIDIOCSWIN</b> sets new values. A successful call to <b>VIDIOCSWIN</b> +indicates that a suitable set of parameters have been chosen. They do not +indicate that exactly what was requested was granted. The program should +call <b>VIDIOCGWIN</b> to check if the nearest match was suitable. The +<b>struct video_window</b> contains the following fields. +<P> +<TABLE> +<TR><TD><b>x</b><TD>The X co-ordinate specified in X windows format.</TD> +<TR><TD><b>y</b><TD>The Y co-ordinate specified in X windows format.</TD> +<TR><TD><b>width</b><TD>The width of the image capture.</TD> +<TR><TD><b>height</b><TD>The height of the image capture.</TD> +<TR><TD><b>chromakey</b><TD>A host order RGB32 value for the chroma key.</TD> +<TR><TD><b>flags</b><TD>Additional capture flags.</TD> +<TR><TD><b>clips</b><TD>A list of clipping rectangles. <em>(Set only)</em></TD> +<TR><TD><b>clipcount</b><TD>The number of clipping rectangles. <em>(Set only)</em></TD> +</TABLE> +<P> +Clipping rectangles are passed as an array. Each clip consists of the following +fields available to the user. +<P> +<TABLE> +<TR><TD><b>x</b></TD><TD>X co-ordinate of rectangle to skip</TD> +<TR><TD><b>y</b></TD><TD>Y co-ordinate of rectangle to skip</TD> +<TR><TD><b>width</b></TD><TD>Width of rectangle to skip</TD> +<TR><TD><b>height</b></TD><TD>Height of rectangle to skip</TD> +</TABLE> +<P> +Merely setting the window does not enable capturing. Overlay capturing +(i.e. PCI-PCI transfer to the frame buffer of the video card) +is activated by passing the <b>VIDIOCCAPTURE</b> ioctl a value of 1, and +disabled by passing it a value of 0. +<P> +Some capture devices can capture a subfield of the image they actually see. +This is indicated when VIDEO_TYPE_SUBCAPTURE is defined. +The video_capture describes the time and special subfields to capture. +The video_capture structure contains the following fields. +<P> +<TABLE> +<TR><TD><b>x</b></TD><TD>X co-ordinate of source rectangle to grab</TD> +<TR><TD><b>y</b></TD><TD>Y co-ordinate of source rectangle to grab</TD> +<TR><TD><b>width</b></TD><TD>Width of source rectangle to grab</TD> +<TR><TD><b>height</b></TD><TD>Height of source rectangle to grab</TD> +<TR><TD><b>decimation</b></TD><TD>Decimation to apply</TD> +<TR><TD><b>flags</b></TD><TD>Flag settings for grabbing</TD> +</TABLE> +The available flags are +<P> +<TABLE> +<TR><TH>Name</TH><TH>Description</TH> +<TR><TD><b>VIDEO_CAPTURE_ODD</b><TD>Capture only odd frames</TD> +<TR><TD><b>VIDEO_CAPTURE_EVEN</b><TD>Capture only even frames</TD> +</TABLE> +<P> +<H3>Video Sources</H3> +Each video4linux video or audio device captures from one or more +source <b>channels</b>. Each channel can be queries with the +<b>VDIOCGCHAN</b> ioctl call. Before invoking this function the caller +must set the channel field to the channel that is being queried. On return +the <b>struct video_channel</b> is filled in with information about the +nature of the channel itself. +<P> +The <b>VIDIOCSCHAN</b> ioctl takes an integer argument and switches the +capture to this input. It is not defined whether parameters such as colour +settings or tuning are maintained across a channel switch. The caller should +maintain settings as desired for each channel. (This is reasonable as +different video inputs may have different properties). +<P> +The <b>struct video_channel</b> consists of the following +<P> +<TABLE> +<TR><TD><b>channel</b></TD><TD>The channel number</TD> +<TR><TD><b>name</b></TD><TD>The input name - preferably reflecting the label +on the card input itself</TD> +<TR><TD><b>tuners</b></TD><TD>Number of tuners for this input</TD> +<TR><TD><b>flags</b></TD><TD>Properties the tuner has</TD> +<TR><TD><b>type</b></TD><TD>Input type (if known)</TD> +<TR><TD><b>norm</b><TD>The norm for this channel</TD> +</TABLE> +<P> +The flags defined are +<P> +<TABLE> +<TR><TD><b>VIDEO_VC_TUNER</b><TD>Channel has tuners.</TD> +<TR><TD><b>VIDEO_VC_AUDIO</b><TD>Channel has audio.</TD> +<TR><TD><b>VIDEO_VC_NORM</b><TD>Channel has norm setting.</TD> +</TABLE> +<P> +The types defined are +<P> +<TABLE> +<TR><TD><b>VIDEO_TYPE_TV</b><TD>The input is a TV input.</TD> +<TR><TD><b>VIDEO_TYPE_CAMERA</b><TD>The input is a camera.</TD> +</TABLE> +<P> +<H3>Image Properties</H3> +The image properties of the picture can be queried with the <b>VIDIOCGPICT</b> +ioctl which fills in a <b>struct video_picture</b>. The <b>VIDIOCSPICT</b> +ioctl allows values to be changed. All values except for the palette type +are scaled between 0-65535. +<P> +The <b>struct video_picture</b> consists of the following fields +<P> +<TABLE> +<TR><TD><b>brightness</b><TD>Picture brightness</TD> +<TR><TD><b>hue</b><TD>Picture hue (colour only)</TD> +<TR><TD><b>colour</b><TD>Picture colour (colour only)</TD> +<TR><TD><b>contrast</b><TD>Picture contrast</TD> +<TR><TD><b>whiteness</b><TD>The whiteness (greyscale only)</TD> +<TR><TD><b>depth</b><TD>The capture depth (may need to match the frame buffer depth)</TD> +<TR><TD><b>palette</b><TD>Reports the palette that should be used for this image</TD> +</TABLE> +<P> +The following palettes are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_PALETTE_GREY</b><TD>Linear intensity grey scale (255 is brightest).</TD> +<TR><TD><b>VIDEO_PALETTE_HI240</b><TD>The BT848 8bit colour cube.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB565</b><TD>RGB565 packed into 16 bit words.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB555</b><TD>RGV555 packed into 16 bit words, top bit undefined.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB24</b><TD>RGB888 packed into 24bit words.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB32</b><TD>RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined.</TD> +<TR><TD><b>VIDEO_PALETTE_YUV422</b><TD>Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V</TD> +<TR><TD><b>VIDEO_PALETTE_YUYV</b><TD>Describe me</TD> +<TR><TD><b>VIDEO_PALETTE_UYVY</b><TD>Describe me</TD> +<TR><TD><b>VIDEO_PALETTE_YUV420</b><TD>YUV420 capture</TD> +<TR><TD><b>VIDEO_PALETTE_YUV411</b><TD>YUV411 capture</TD> +<TR><TD><b>VIDEO_PALETTE_RAW</b><TD>RAW capture (BT848)</TD> +<TR><TD><b>VIDEO_PALETTE_YUV422P</b><TD>YUV 4:2:2 Planar</TD> +<TR><TD><b>VIDEO_PALETTE_YUV411P</b><TD>YUV 4:1:1 Planar</TD> +</TABLE> +<P> +<H3>Tuning</H3> +Each video input channel can have one or more tuners associated with it. Many +devices will not have tuners. TV cards and radio cards will have one or more +tuners attached. +<P> +Tuners are described by a <b>struct video_tuner</b> which can be obtained by +the <b>VIDIOCGTUNER</b> ioctl. Fill in the tuner number in the structure +then pass the structure to the ioctl to have the data filled in. The +tuner can be switched using <b>VIDIOCSTUNER</b> which takes an integer argument +giving the tuner to use. A struct tuner has the following fields +<P> +<TABLE> +<TR><TD><b>tuner</b><TD>Number of the tuner</TD> +<TR><TD><b>name</b><TD>Canonical name for this tuner (eg FM/AM/TV)</TD> +<TR><TD><b>rangelow</b><TD>Lowest tunable frequency</TD> +<TR><TD><b>rangehigh</b><TD>Highest tunable frequency</TD> +<TR><TD><b>flags</b><TD>Flags describing the tuner</TD> +<TR><TD><b>mode</b><TD>The video signal mode if relevant</TD> +<TR><TD><b>signal</b><TD>Signal strength if known - between 0-65535</TD> +</TABLE> +<P> +The following flags exist +<P> +<TABLE> +<TR><TD><b>VIDEO_TUNER_PAL</b><TD>PAL tuning is supported</TD> +<TR><TD><b>VIDEO_TUNER_NTSC</b><TD>NTSC tuning is supported</TD> +<TR><TD><b>VIDEO_TUNER_SECAM</b><TD>SECAM tuning is supported</TD> +<TR><TD><b>VIDEO_TUNER_LOW</b><TD>Frequency is in a lower range</TD> +<TR><TD><b>VIDEO_TUNER_NORM</b><TD>The norm for this tuner is settable</TD> +<TR><TD><b>VIDEO_TUNER_STEREO_ON</b><TD>The tuner is seeing stereo audio</TD> +<TR><TD><b>VIDEO_TUNER_RDS_ON</b><TD>The tuner is seeing a RDS datastream</TD> +<TR><TD><b>VIDEO_TUNER_MBS_ON</b><TD>The tuner is seeing a MBS datastream</TD> +</TABLE> +<P> +The following modes are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_MODE_PAL</b><TD>The tuner is in PAL mode</TD> +<TR><TD><b>VIDEO_MODE_NTSC</b><TD>The tuner is in NTSC mode</TD> +<TR><TD><b>VIDEO_MODE_SECAM</b><TD>The tuner is in SECAM mode</TD> +<TR><TD><b>VIDEO_MODE_AUTO</b><TD>The tuner auto switches, or mode does not apply</TD> +</TABLE> +<P> +Tuning frequencies are an unsigned 32bit value in 1/16th MHz or if the +<b>VIDEO_TUNER_LOW</b> flag is set they are in 1/16th KHz. The current +frequency is obtained as an unsigned long via the <b>VIDIOCGFREQ</b> ioctl and +set by the <b>VIDIOCSFREQ</b> ioctl. +<P> +<H3>Audio</H3> +TV and Radio devices have one or more audio inputs that may be selected. +The audio properties are queried by passing a <b>struct video_audio</b> to <b>VIDIOCGAUDIO</b> ioctl. The +<b>VIDIOCSAUDIO</b> ioctl sets audio properties. +<P> +The structure contains the following fields +<P> +<TABLE> +<TR><TD><b>audio</b><TD>The channel number</TD> +<TR><TD><b>volume</b><TD>The volume level</TD> +<TR><TD><b>bass</b><TD>The bass level</TD> +<TR><TD><b>treble</b><TD>The treble level</TD> +<TR><TD><b>flags</b><TD>Flags describing the audio channel</TD> +<TR><TD><b>name</b><TD>Canonical name for the audio input</TD> +<TR><TD><b>mode</b><TD>The mode the audio input is in</TD> +<TR><TD><b>balance</b><TD>The left/right balance</TD> +<TR><TD><b>step</b><TD>Actual step used by the hardware</TD> +</TABLE> +<P> +The following flags are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_AUDIO_MUTE</b><TD>The audio is muted</TD> +<TR><TD><b>VIDEO_AUDIO_MUTABLE</b><TD>Audio muting is supported</TD> +<TR><TD><b>VIDEO_AUDIO_VOLUME</b><TD>The volume is controllable</TD> +<TR><TD><b>VIDEO_AUDIO_BASS</b><TD>The bass is controllable</TD> +<TR><TD><b>VIDEO_AUDIO_TREBLE</b><TD>The treble is controllable</TD> +<TR><TD><b>VIDEO_AUDIO_BALANCE</b><TD>The balance is controllable</TD> +</TABLE> +<P> +The following decoding modes are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_SOUND_MONO</b><TD>Mono signal</TD> +<TR><TD><b>VIDEO_SOUND_STEREO</b><TD>Stereo signal (NICAM for TV)</TD> +<TR><TD><b>VIDEO_SOUND_LANG1</b><TD>European TV alternate language 1</TD> +<TR><TD><b>VIDEO_SOUND_LANG2</b><TD>European TV alternate language 2</TD> +</TABLE> +<P> +<H3>Reading Images</H3> +Each call to the <b>read</b> syscall returns the next available image +from the device. It is up to the caller to set format and size (using +the VIDIOCSPICT and VIDIOCSWIN ioctls) and then to pass a suitable +size buffer and length to the function. Not all devices will support +read operations. +<P> +A second way to handle image capture is via the mmap interface if supported. +To use the mmap interface a user first sets the desired image size and depth +properties. Next the VIDIOCGMBUF ioctl is issued. This reports the size +of buffer to mmap and the offset within the buffer for each frame. The +number of frames supported is device dependent and may only be one. +<P> +The video_mbuf structure contains the following fields +<P> +<TABLE> +<TR><TD><b>size</b><TD>The number of bytes to map</TD> +<TR><TD><b>frames</b><TD>The number of frames</TD> +<TR><TD><b>offsets</b><TD>The offset of each frame</TD> +</TABLE> +<P> +Once the mmap has been made the VIDIOCMCAPTURE ioctl starts the +capture to a frame using the format and image size specified in the +video_mmap (which should match or be below the initial query size). +When the VIDIOCMCAPTURE ioctl returns the frame is <em>not</em> +captured yet, the driver just instructed the hardware to start the +capture. The application has to use the VIDIOCSYNC ioctl to wait +until the capture of a frame is finished. VIDIOCSYNC takes the frame +number you want to wait for as argument. +<p> +It is allowed to call VIDIOCMCAPTURE multiple times (with different +frame numbers in video_mmap->frame of course) and thus have multiple +outstanding capture requests. A simple way do to double-buffering +using this feature looks like this: +<pre> +/* setup everything */ +VIDIOCMCAPTURE(0) +while (whatever) { + VIDIOCMCAPTURE(1) + VIDIOCSYNC(0) + /* process frame 0 while the hardware captures frame 1 */ + VIDIOCMCAPTURE(0) + VIDIOCSYNC(1) + /* process frame 1 while the hardware captures frame 0 */ +} +</pre> +Note that you are <em>not</em> limited to only two frames. The API +allows up to 32 frames, the VIDIOCGMBUF ioctl returns the number of +frames the driver granted. Thus it is possible to build deeper queues +to avoid loosing frames on load peaks. +<p> +While capturing to memory the driver will make a "best effort" attempt +to capture to screen as well if requested. This normally means all +frames that "miss" memory mapped capture will go to the display. +<P> +A final ioctl exists to allow a device to obtain related devices if a +driver has multiple components (for example video0 may not be associated +with vbi0 which would cause an intercast display program to make a bad +mistake). The VIDIOCGUNIT ioctl reports the unit numbers of the associated +devices if any exist. The video_unit structure has the following fields. +<P> +<TABLE> +<TR><TD><b>video</b><TD>Video capture device</TD> +<TR><TD><b>vbi</b><TD>VBI capture device</TD> +<TR><TD><b>radio</b><TD>Radio device</TD> +<TR><TD><b>audio</b><TD>Audio mixer</TD> +<TR><TD><b>teletext</b><TD>Teletext device</TD> +</TABLE> +<P> +<H3>RDS Datastreams</H3> +For radio devices that support it, it is possible to receive Radio Data +System (RDS) data by means of a read() on the device. The data is packed in +groups of three, as follows: +<TABLE> +<TR><TD>First Octet</TD><TD>Least Significant Byte of RDS Block</TD></TR> +<TR><TD>Second Octet</TD><TD>Most Significant Byte of RDS Block +<TR><TD>Third Octet</TD><TD>Bit 7:</TD><TD>Error bit. Indicates that +an uncorrectable error occurred during reception of this block.</TD></TR> +<TR><TD> </TD><TD>Bit 6:</TD><TD>Corrected bit. Indicates that +an error was corrected for this data block.</TD></TR> +<TR><TD> </TD><TD>Bits 5-3:</TD><TD>Received Offset. Indicates the +offset received by the sync system.</TD></TR> +<TR><TD> </TD><TD>Bits 2-0:</TD><TD>Offset Name. Indicates the +offset applied to this data.</TD></TR> +</TABLE> +</BODY> +</HTML> diff --git a/v4l/API/V4L2_API.html b/v4l/API/V4L2_API.html new file mode 100644 index 000000000..f1ef6aed3 --- /dev/null +++ b/v4l/API/V4L2_API.html @@ -0,0 +1,39683 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML +><HEAD +><TITLE +>Video for Linux Two API Specification</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD +><BODY +CLASS="BOOK" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="BOOK" +><A +NAME="INDEX" +></A +><DIV +CLASS="TITLEPAGE" +><H1 +CLASS="TITLE" +><A +NAME="AEN2" +>Video for Linux Two API Specification</A +></H1 +><H2 +CLASS="SUBTITLE" +>Draft 0.8</H2 +><H3 +CLASS="AUTHOR" +><A +NAME="AEN6" +></A +>Michael H Schimek</H3 +><DIV +CLASS="AFFILIATION" +><DIV +CLASS="ADDRESS" +><P +CLASS="ADDRESS" +> <CODE +CLASS="EMAIL" +><<A +HREF="mailto:mschimek@gmx.at" +>mschimek@gmx.at</A +>></CODE +><br> + </P +></DIV +></DIV +><H3 +CLASS="AUTHOR" +><A +NAME="AEN13" +></A +>Bill Dirks</H3 +><P +CLASS="COPYRIGHT" +>Copyright © 1999, 2000, 2001, 2002, 2003, 2004 Bill Dirks, Michael H. Schimek</P +><DIV +CLASS="LEGALNOTICE" +><P +></P +><A +NAME="AEN25" +></A +><P +>This document is copyrighted © 1999-2004 by Bill +Dirks and Michael H. Schimek.</P +><P +>Permission is granted to copy, distribute and/or modify +this document under the terms of the GNU Free Documentation License, +Version 1.1 or any later version published by the Free Software +Foundation; with no Invariant Sections, with no Front-Cover Texts, and +with no Back-Cover Texts. A copy of the license is included in the +appendix entitled "GNU Free Documentation License".</P +><P +>Programming examples can be used without +restriction.</P +><P +></P +></DIV +><HR></DIV +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="#AEN71" +>Introduction</A +></DT +><DT +>1. <A +HREF="#COMMON" +>Common API Elements</A +></DT +><DD +><DL +><DT +>1.1. <A +HREF="#OPEN" +>Opening and Closing Devices</A +></DT +><DD +><DL +><DT +>1.1.1. <A +HREF="#AEN100" +>Device Naming</A +></DT +><DT +>1.1.2. <A +HREF="#RELATED" +>Related Devices</A +></DT +><DT +>1.1.3. <A +HREF="#AEN153" +>Multiple Opens</A +></DT +><DT +>1.1.4. <A +HREF="#AEN170" +>Shared Data Streams</A +></DT +><DT +>1.1.5. <A +HREF="#AEN173" +>Functions</A +></DT +></DL +></DD +><DT +>1.2. <A +HREF="#QUERYCAP" +>Querying Capabilities</A +></DT +><DT +>1.3. <A +HREF="#APP-PRI" +>Application Priority</A +></DT +><DT +>1.4. <A +HREF="#VIDEO" +>Video Inputs and Outputs</A +></DT +><DT +>1.5. <A +HREF="#AUDIO" +>Audio Inputs and Outputs</A +></DT +><DT +>1.6. <A +HREF="#TUNER" +>Tuners and Modulators</A +></DT +><DD +><DL +><DT +>1.6.1. <A +HREF="#AEN296" +>Tuners</A +></DT +><DT +>1.6.2. <A +HREF="#AEN318" +>Modulators</A +></DT +><DT +>1.6.3. <A +HREF="#AEN337" +>Radio Frequency</A +></DT +><DT +>1.6.4. <A +HREF="#AEN345" +>Satellite Receivers</A +></DT +></DL +></DD +><DT +>1.7. <A +HREF="#STANDARD" +>Video Standards</A +></DT +><DT +>1.8. <A +HREF="#CONTROL" +>Controls</A +></DT +><DT +>1.9. <A +HREF="#FORMAT" +>Data Formats</A +></DT +><DD +><DL +><DT +>1.9.1. <A +HREF="#AEN656" +>Data Format Negotiation</A +></DT +><DT +>1.9.2. <A +HREF="#AEN689" +>Image Format Enumeration</A +></DT +></DL +></DD +><DT +>1.10. <A +HREF="#CROP" +>Cropping and Scaling</A +></DT +><DT +>1.11. <A +HREF="#STREAMING-PAR" +>Streaming Parameters</A +></DT +></DL +></DD +><DT +>2. <A +HREF="#PIXFMT" +>Image Formats</A +></DT +><DD +><DL +><DT +>2.1. <A +HREF="#AEN880" +>Standard Image Formats</A +></DT +><DT +>2.2. <A +HREF="#COLORSPACES" +>Colorspaces</A +></DT +><DT +>2.3. <A +HREF="#PIXFMT-RGB" +>RGB Formats</A +></DT +><DT +>2.4. <A +HREF="#YUV-FORMATS" +>YUV Formats</A +></DT +><DD +><DL +><DT +><A +HREF="#PIXFMT-GREY" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +></A +> -- Grey-scale image.</DT +><DT +><A +HREF="#PIXFMT-YUYV" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +></A +> -- Packed format with ½ horizontal chroma +resolution, also known as YUV 4:2:2.</DT +><DT +><A +HREF="#PIXFMT-UYVY" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +></A +> -- Variation of +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +> with different order of samples +in memory.</DT +><DT +><A +HREF="#PIXFMT-Y41P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +></A +> -- Packed format with ¼ horizontal chroma +resolution, also known as YUV 4:1:1.</DT +><DT +><A +HREF="#PIXFMT-YVU420" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV420</CODE +></A +> -- Planar formats with ½ horizontal and +vertical chroma resolution, also known as YUV 4:2:0.</DT +><DT +><A +HREF="#PIXFMT-YVU410" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV410</CODE +></A +> -- Planar formats with ¼ horizontal and +vertical chroma resolution, also known as YUV 4:1:0.</DT +><DT +><A +HREF="#PIXFMT-YUV422P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +></A +> -- Format with ½ horizontal chroma resolution, +also known as YUV 4:2:2. Planar layout as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +>.</DT +><DT +><A +HREF="#PIXFMT-YUV411P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +></A +> -- Format with ¼ horizontal chroma resolution, +also known as YUV 4:1:1. Planar layout as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +>.</DT +><DT +><A +HREF="#AEN3002" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV21</CODE +></A +> -- Formats with ½ horizontal and vertical +chroma resolution, also known as YUV 4:2:0. One luminance and one +chrominance plane with alternating chroma samples as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>.</DT +></DL +></DD +><DT +>2.5. <A +HREF="#AEN3167" +>Compressed Formats</A +></DT +><DT +>2.6. <A +HREF="#PIXFMT-RESERVED" +>Reserved Format Identifiers</A +></DT +></DL +></DD +><DT +>3. <A +HREF="#IO" +>Input/Output</A +></DT +><DD +><DL +><DT +>3.1. <A +HREF="#RW" +>Read/Write</A +></DT +><DT +>3.2. <A +HREF="#MMAP" +>Streaming I/O (Memory Mapping)</A +></DT +><DT +>3.3. <A +HREF="#USERP" +>Streaming I/O (User Pointers)</A +></DT +><DT +>3.4. <A +HREF="#ASYNC" +>Asynchronous I/O</A +></DT +><DT +>3.5. <A +HREF="#BUFFER" +>Buffers</A +></DT +><DD +><DL +><DT +>3.5.1. <A +HREF="#AEN3738" +>Timecodes</A +></DT +></DL +></DD +><DT +>3.6. <A +HREF="#FIELD-ORDER" +>Field Order</A +></DT +></DL +></DD +><DT +>4. <A +HREF="#DEVICES" +>Device Types</A +></DT +><DD +><DL +><DT +>4.1. <A +HREF="#CAPTURE" +>Video Capture Interface</A +></DT +><DD +><DL +><DT +>4.1.1. <A +HREF="#AEN3960" +>Querying Capabilities</A +></DT +><DT +>4.1.2. <A +HREF="#AEN3972" +>Supplemental Functions</A +></DT +><DT +>4.1.3. <A +HREF="#AEN3982" +>Image Format Negotiation</A +></DT +><DT +>4.1.4. <A +HREF="#AEN4024" +>Reading Images</A +></DT +></DL +></DD +><DT +>4.2. <A +HREF="#OVERLAY" +>Video Overlay Interface</A +></DT +><DD +><DL +><DT +>4.2.1. <A +HREF="#AEN4048" +>Querying Capabilities</A +></DT +><DT +>4.2.2. <A +HREF="#AEN4056" +>Supplemental Functions</A +></DT +><DT +>4.2.3. <A +HREF="#AEN4066" +>Setup</A +></DT +><DT +>4.2.4. <A +HREF="#AEN4092" +>Overlay Window</A +></DT +><DT +>4.2.5. <A +HREF="#AEN4266" +>Enabling Overlay</A +></DT +></DL +></DD +><DT +>4.3. <A +HREF="#OUTPUT" +>Video Output Interface</A +></DT +><DD +><DL +><DT +>4.3.1. <A +HREF="#AEN4279" +>Querying Capabilities</A +></DT +><DT +>4.3.2. <A +HREF="#AEN4289" +>Supplemental Functions</A +></DT +><DT +>4.3.3. <A +HREF="#AEN4299" +>Image Format Negotiation</A +></DT +><DT +>4.3.4. <A +HREF="#AEN4341" +>Writing Images</A +></DT +></DL +></DD +><DT +>4.4. <A +HREF="#CODEC" +>Codec Interface</A +></DT +><DT +>4.5. <A +HREF="#EFFECT" +>Effect Devices Interface</A +></DT +><DT +>4.6. <A +HREF="#RAW-VBI" +>Raw VBI Data Interface</A +></DT +><DD +><DL +><DT +>4.6.1. <A +HREF="#AEN4383" +>Querying Capabilities</A +></DT +><DT +>4.6.2. <A +HREF="#AEN4392" +>Supplemental Functions</A +></DT +><DT +>4.6.3. <A +HREF="#AEN4399" +>Raw VBI Format Negotiation</A +></DT +><DT +>4.6.4. <A +HREF="#AEN4571" +>Reading and writing VBI images</A +></DT +></DL +></DD +><DT +>4.7. <A +HREF="#SLICED" +>Sliced VBI Data Interface</A +></DT +><DD +><DL +><DT +>4.7.1. <A +HREF="#AEN4599" +>Querying Capabilities</A +></DT +><DT +>4.7.2. <A +HREF="#AEN4608" +>Supplemental Functions</A +></DT +><DT +>4.7.3. <A +HREF="#AEN4615" +>Sliced VBI Format Negotiation</A +></DT +><DT +>4.7.4. <A +HREF="#AEN4760" +>Reading and writing sliced VBI data</A +></DT +></DL +></DD +><DT +>4.8. <A +HREF="#TTX" +>Teletext Interface</A +></DT +><DT +>4.9. <A +HREF="#RADIO" +>Radio Interface</A +></DT +><DD +><DL +><DT +>4.9.1. <A +HREF="#AEN4799" +>Querying Capabilities</A +></DT +><DT +>4.9.2. <A +HREF="#AEN4808" +>Supplemental Functions</A +></DT +><DT +>4.9.3. <A +HREF="#AEN4814" +>Programming</A +></DT +></DL +></DD +><DT +>4.10. <A +HREF="#RDS" +>RDS Interface</A +></DT +></DL +></DD +><DT +>I. <A +HREF="#USER-FUNC" +>Function Reference</A +></DT +><DD +><DL +><DT +><A +HREF="#FUNC-CLOSE" +>close</A +> -- Close a V4L2 device</DT +><DT +><A +HREF="#FUNC-IOCTL" +>ioctl</A +> -- Program a V4L2 device</DT +><DT +><A +HREF="#VIDIOC-CROPCAP" +>ioctl VIDIOC_CROPCAP</A +> -- Information about the video cropping and scaling abilities.</DT +><DT +><A +HREF="#VIDIOC-ENUMAUDIO" +>ioctl VIDIOC_ENUMAUDIO</A +> -- Enumerate audio inputs</DT +><DT +><A +HREF="#VIDIOC-ENUMAUDIOOUT" +>ioctl VIDIOC_ENUMAUDOUT</A +> -- Enumerate audio outputs</DT +><DT +><A +HREF="#VIDIOC-ENUM-FMT" +>ioctl VIDIOC_ENUM_FMT</A +> -- Enumerate image formats</DT +><DT +><A +HREF="#VIDIOC-ENUMINPUT" +>ioctl VIDIOC_ENUMINPUT</A +> -- Enumerate video inputs</DT +><DT +><A +HREF="#VIDIOC-ENUMOUTPUT" +>ioctl VIDIOC_ENUMOUTPUT</A +> -- Enumerate video outputs</DT +><DT +><A +HREF="#VIDIOC-ENUMSTD" +>ioctl VIDIOC_ENUMSTD</A +> -- Enumerate supported video standards</DT +><DT +><A +HREF="#VIDIOC-G-AUDIO" +>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</A +> -- Query or select the current audio input and its +attributes</DT +><DT +><A +HREF="#VIDIOC-G-AUDIOOUT" +>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</A +> -- Query or select the current audio output</DT +><DT +><A +HREF="#VIDIOC-G-COMP" +>ioctl VIDIOC_G_COMP, VIDIOC_S_COMP</A +> -- Get or set compression parameters</DT +><DT +><A +HREF="#VIDIOC-G-CROP" +>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</A +> -- Get or set the current cropping rectangle</DT +><DT +><A +HREF="#VIDIOC-G-CTRL" +>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</A +> -- Get or set the value of a control</DT +><DT +><A +HREF="#VIDIOC-G-FBUF" +>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</A +> -- Get or set frame buffer overlay parameters.</DT +><DT +><A +HREF="#VIDIOC-G-FMT" +>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</A +> -- Get or set the data format, try a format.</DT +><DT +><A +HREF="#VIDIOC-G-FREQUENCY" +>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</A +> -- Get or set tuner or modulator radio +frequency</DT +><DT +><A +HREF="#VIDIOC-G-INPUT" +>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</A +> -- Query or select the current video input</DT +><DT +><A +HREF="#VIDIOC-G-JPEGCOMP" +>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</A +> -- </DT +><DT +><A +HREF="#VIDIOC-G-MODULATOR" +>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</A +> -- Get or set modulator attributes</DT +><DT +><A +HREF="#VIDIOC-G-OUTPUT" +>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</A +> -- Query or select the current video output</DT +><DT +><A +HREF="#VIDIOC-G-PARM" +>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</A +> -- Get or set streaming parameters</DT +><DT +><A +HREF="#VIDIOC-G-PRIORITY" +>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</A +> -- Query or request the access priority associated with a +file descriptor</DT +><DT +><A +HREF="#VIDIOC-G-STD" +>ioctl VIDIOC_G_STD, VIDIOC_S_STD</A +> -- Query or select the video standard of the current input</DT +><DT +><A +HREF="#VIDIOC-G-TUNER" +>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</A +> -- Get or set tuner attributes</DT +><DT +><A +HREF="#VIDIOC-OVERLAY" +>ioctl VIDIOC_OVERLAY</A +> -- Start or stop video overlay</DT +><DT +><A +HREF="#VIDIOC-QBUF" +>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</A +> -- Exchange a buffer with the driver</DT +><DT +><A +HREF="#VIDIOC-QUERYBUF" +>ioctl VIDIOC_QUERYBUF</A +> -- Query the status of a buffer</DT +><DT +><A +HREF="#VIDIOC-QUERYCAP" +>ioctl VIDIOC_QUERYCAP</A +> -- Query device capabilities</DT +><DT +><A +HREF="#VIDIOC-QUERYCTRL" +>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</A +> -- Enumerate controls and menu control items</DT +><DT +><A +HREF="#VIDIOC-QUERYSTD" +>ioctl VIDIOC_QUERYSTD</A +> -- Sense the video standard received by the current input</DT +><DT +><A +HREF="#VIDIOC-REQBUFS" +>ioctl VIDIOC_REQBUFS</A +> -- Initiate Memory Mapping or User Pointer I/O</DT +><DT +><A +HREF="#VIDIOC-STREAMON" +>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</A +> -- Start or stop streaming I/O.</DT +><DT +><A +HREF="#FUNC-MMAP" +>mmap</A +> -- Map device memory into application address space</DT +><DT +><A +HREF="#FUNC-MUNMAP" +>munmap</A +> -- Unmap device memory</DT +><DT +><A +HREF="#FUNC-OPEN" +>open</A +> -- Open a V4L2 device</DT +><DT +><A +HREF="#FUNC-POLL" +>poll</A +> -- Wait for some event on a file descriptor</DT +><DT +><A +HREF="#FUNC-READ" +>read</A +> -- Read from a V4L2 device</DT +><DT +><A +HREF="#FUNC-SELECT" +>select</A +> -- Synchronous I/O multiplexing</DT +><DT +><A +HREF="#FUNC-WRITE" +>write</A +> -- Write to a V4L2 device</DT +></DL +></DD +><DT +>5. <A +HREF="#DRIVER" +>Driver Interface</A +></DT +><DD +><DL +><DT +>5.1. <A +HREF="#FOO" +>to do</A +></DT +><DD +><DL +><DT +>5.1.1. <A +HREF="#AEN9774" +>to do</A +></DT +></DL +></DD +></DL +></DD +><DT +>6. <A +HREF="#COMPAT" +>History</A +></DT +><DD +><DL +><DT +>6.1. <A +HREF="#DIFF-V4L" +>Differences between V4L and V4L2</A +></DT +><DD +><DL +><DT +>6.1.1. <A +HREF="#AEN9783" +>Opening and Closing Devices</A +></DT +><DT +>6.1.2. <A +HREF="#AEN9847" +>Querying Capabilities</A +></DT +><DT +>6.1.3. <A +HREF="#AEN9977" +>Video Sources</A +></DT +><DT +>6.1.4. <A +HREF="#AEN10033" +>Tuning</A +></DT +><DT +>6.1.5. <A +HREF="#V4L-IMAGE-PROPERTIES" +>Image Properties</A +></DT +><DT +>6.1.6. <A +HREF="#AEN10276" +>Audio</A +></DT +><DT +>6.1.7. <A +HREF="#AEN10361" +>Frame Buffer Overlay</A +></DT +><DT +>6.1.8. <A +HREF="#AEN10425" +>Cropping</A +></DT +><DT +>6.1.9. <A +HREF="#AEN10458" +>Reading Images, Memory Mapping</A +></DT +><DT +>6.1.10. <A +HREF="#AEN10541" +>Reading Raw VBI Data</A +></DT +><DT +>6.1.11. <A +HREF="#AEN10594" +>Miscellaneous</A +></DT +></DL +></DD +><DT +>6.2. <A +HREF="#HIST-V4L2" +>History of the V4L2 API</A +></DT +><DD +><DL +><DT +>6.2.1. <A +HREF="#AEN10604" +>Early Versions</A +></DT +><DT +>6.2.2. <A +HREF="#AEN10618" +>V4L2 Version 0.16 1999-01-31</A +></DT +><DT +>6.2.3. <A +HREF="#AEN10621" +>V4L2 Version 0.18 1999-03-16</A +></DT +><DT +>6.2.4. <A +HREF="#AEN10624" +>V4L2 Version 0.19 1999-06-05</A +></DT +><DT +>6.2.5. <A +HREF="#AEN10633" +>V4L2 Version 0.20 1999-09-10</A +></DT +><DT +>6.2.6. <A +HREF="#AEN10672" +>V4L2 Version 0.20 incremental changes</A +></DT +><DT +>6.2.7. <A +HREF="#AEN10694" +>V4L2 Version 0.20 2000-11-23</A +></DT +><DT +>6.2.8. <A +HREF="#AEN10709" +>V4L2 Version 0.20 2002-07-25</A +></DT +><DT +>6.2.9. <A +HREF="#AEN10712" +>V4L2 in Linux 2.5.46, 2002-10</A +></DT +><DT +>6.2.10. <A +HREF="#AEN11094" +>V4L2 2003-06-19</A +></DT +><DT +>6.2.11. <A +HREF="#AEN11136" +>V4L2 2003-11-05</A +></DT +><DT +>6.2.12. <A +HREF="#AEN11178" +>V4L2 in Linux 2.6.6, 2004-05-09</A +></DT +><DT +>6.2.13. <A +HREF="#AEN11186" +>V4L2 in Linux 2.6.8</A +></DT +><DT +>6.2.14. <A +HREF="#AEN11196" +>V4L2 spec erratum 2004-08-01</A +></DT +></DL +></DD +><DT +>6.3. <A +HREF="#OTHER" +>Relation of V4L2 to other Linux multimedia APIs</A +></DT +><DD +><DL +><DT +>6.3.1. <A +HREF="#XVIDEO" +>X Video Extension</A +></DT +><DT +>6.3.2. <A +HREF="#AEN11233" +>Digital Video</A +></DT +><DT +>6.3.3. <A +HREF="#AEN11237" +>Audio Interfaces</A +></DT +></DL +></DD +></DL +></DD +><DT +>A. <A +HREF="#VIDEODEV" +>Video For Linux Two Header File</A +></DT +><DT +>B. <A +HREF="#CAPTURE-EXAMPLE" +>Video Capture Example</A +></DT +><DT +>C. <A +HREF="#FDL" +>GNU Free Documentation License</A +></DT +><DD +><DL +><DT +>C.1. <A +HREF="#FDL-PREAMBLE" +>0. PREAMBLE</A +></DT +><DT +>C.2. <A +HREF="#FDL-SECTION1" +>1. APPLICABILITY AND DEFINITIONS</A +></DT +><DT +>C.3. <A +HREF="#FDL-SECTION2" +>2. VERBATIM COPYING</A +></DT +><DT +>C.4. <A +HREF="#FDL-SECTION3" +>3. COPYING IN QUANTITY</A +></DT +><DT +>C.5. <A +HREF="#FDL-SECTION4" +>4. MODIFICATIONS</A +></DT +><DT +>C.6. <A +HREF="#FDL-SECTION5" +>5. COMBINING DOCUMENTS</A +></DT +><DT +>C.7. <A +HREF="#FDL-SECTION6" +>6. COLLECTIONS OF DOCUMENTS</A +></DT +><DT +>C.8. <A +HREF="#FDL-SECTION7" +>7. AGGREGATION WITH INDEPENDENT WORKS</A +></DT +><DT +>C.9. <A +HREF="#FDL-SECTION8" +>8. TRANSLATION</A +></DT +><DT +>C.10. <A +HREF="#FDL-SECTION9" +>9. TERMINATION</A +></DT +><DT +>C.11. <A +HREF="#FDL-SECTION10" +>10. FUTURE REVISIONS OF THIS LICENSE</A +></DT +><DT +>C.12. <A +HREF="#FDL-USING" +>Addendum</A +></DT +></DL +></DD +><DT +><A +HREF="#AEN11623" +>Bibliography</A +></DT +></DL +></DIV +><DIV +CLASS="LOT" +><DL +CLASS="LOT" +><DT +><B +>List of Tables</B +></DT +><DT +>1-1. <A +HREF="#CONTROL-ID" +>Control IDs</A +></DT +><DT +>2-1. <A +HREF="#V4L2-PIX-FORMAT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_pix_format</CODE +></A +></DT +><DT +>2-2. <A +HREF="#V4L2-COLORSPACE" +>enum v4l2_colorspace</A +></DT +><DT +>2-3. <A +HREF="#RGB-FORMATS" +>Packed RGB Image Formats</A +></DT +><DT +>2-4. <A +HREF="#RESERVED-FORMATS" +>Reserved Image Formats</A +></DT +><DT +>3-1. <A +HREF="#V4L2-BUFFER" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_buffer</CODE +></A +></DT +><DT +>3-2. <A +HREF="#V4L2-BUF-TYPE" +>enum v4l2_buf_type</A +></DT +><DT +>3-3. <A +HREF="#BUFFER-FLAGS" +>Buffer Flags</A +></DT +><DT +>3-4. <A +HREF="#V4L2-MEMORY" +>enum v4l2_memory</A +></DT +><DT +>3-5. <A +HREF="#V4L2-TIMECODE" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_timecode</CODE +></A +></DT +><DT +>3-6. <A +HREF="#TIMECODE-TYPE" +>Timecode Types</A +></DT +><DT +>3-7. <A +HREF="#TIMECODE-FLAGS" +>Timecode Flags</A +></DT +><DT +>3-8. <A +HREF="#V4L2-FIELD" +>enum v4l2_field</A +></DT +><DT +>4-1. <A +HREF="#V4L2-WINDOW" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_window</CODE +></A +></DT +><DT +>4-2. <A +HREF="#V4L2-CLIP" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_clip</CODE +><A +NAME="AEN4216" +HREF="#FTN.AEN4216" +><SPAN +CLASS="footnote" +>[22]</SPAN +></A +></A +></DT +><DT +>4-3. <A +HREF="#V4L2-RECT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_rect</CODE +></A +></DT +><DT +>4-4. <A +HREF="#V4L2-VBI-FORMAT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_vbi_format</CODE +></A +></DT +><DT +>4-5. <A +HREF="#VBIFMT-FLAGS" +>Raw VBI Format Flags</A +></DT +><DT +>4-6. <A +HREF="#V4L2-SLICED-VBI-FORMAT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_sliced_vbi_format</CODE +></A +></DT +><DT +>4-7. <A +HREF="#V4L2-SLICED-DATA" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_sliced_data</CODE +></A +></DT +><DT +>4-8. <A +HREF="#SLICED-VBI-TYPES" +>Sliced VBI data formats</A +></DT +><DT +>1. <A +HREF="#V4L2-CROPCAP" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_cropcap</CODE +></A +></DT +><DT +>2. <A +HREF="#V4L2-RECT-CROP" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_rect</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-FMTDESC" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_fmtdesc</CODE +></A +></DT +><DT +>2. <A +HREF="#FMTDESC-FLAGS" +>Image Format Description Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-INPUT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_input</CODE +></A +></DT +><DT +>2. <A +HREF="#INPUT-TYPE" +>Input Types</A +></DT +><DT +>3. <A +HREF="#INPUT-STATUS" +>Input Status Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-OUTPUT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_output</CODE +></A +></DT +><DT +>2. <A +HREF="#OUTPUT-TYPE" +>Output Type</A +></DT +><DT +>1. <A +HREF="#V4L2-STANDARD" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_standard</CODE +></A +></DT +><DT +>2. <A +HREF="#V4L2-FRACT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_fract</CODE +></A +></DT +><DT +>3. <A +HREF="#V4L2-STD-ID" +>typedef <CODE +CLASS="STRUCTNAME" +>v4l2_std_id</CODE +></A +></DT +><DT +>4. <A +HREF="#VIDEO-STANDARDS" +>Video Standards (based on [<A +HREF="#ITU470" +><ABBR +CLASS="ABBREV" +>ITU470</ABBR +></A +>])</A +></DT +><DT +>1. <A +HREF="#V4L2-AUDIO" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_audio</CODE +></A +></DT +><DT +>2. <A +HREF="#AUDIO-CAPABILITY" +>Audio Capability Flags</A +></DT +><DT +>3. <A +HREF="#AUDIO-MODE" +>Audio Modes</A +></DT +><DT +>1. <A +HREF="#V4L2-AUDIOOUT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_audioout</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-COMPRESSION" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_compression</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-CROP" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_crop</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-CONTROL" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_control</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-FRAMEBUFFER" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_framebuffer</CODE +></A +></DT +><DT +>2. <A +HREF="#FRAMEBUFFER-CAP" +>Frame Buffer Capability Flags</A +></DT +><DT +>3. <A +HREF="#FRAMEBUFFER-FLAGS" +>Frame Buffer Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-FORMAT" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_format</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-FREQUENCY" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_frequency</CODE +></A +></DT +><DT +>1. <A +HREF="#V4L2-JPEGCOMPRESSION" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_jpegcompression</CODE +></A +></DT +><DT +>2. <A +HREF="#JPEG-MARKERS" +>JPEG Markers Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-MODULATOR" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_modulator</CODE +></A +></DT +><DT +>2. <A +HREF="#MODULATOR-TXSUBCHANS" +>Modulator Audio Transmission Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-STREAMPARM" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_streamparm</CODE +></A +></DT +><DT +>2. <A +HREF="#V4L2-CAPTUREPARM" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_captureparm</CODE +></A +></DT +><DT +>3. <A +HREF="#V4L2-OUTPUTPARM" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_outputparm</CODE +></A +></DT +><DT +>4. <A +HREF="#PARM-CAPS" +>Streaming Parameters Capabilites</A +></DT +><DT +>5. <A +HREF="#PARM-FLAGS" +>Capture Parameters Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-PRIORITY" +>enum v4l2_priority</A +></DT +><DT +>1. <A +HREF="#V4L2-TUNER" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_tuner</CODE +></A +></DT +><DT +>2. <A +HREF="#V4L2-TUNER-TYPE" +>enum v4l2_tuner_type</A +></DT +><DT +>3. <A +HREF="#TUNER-CAPABILITY" +>Tuner and Modulator Capability Flags</A +></DT +><DT +>4. <A +HREF="#TUNER-RXSUBCHANS" +>Tuner Audio Reception Flags</A +></DT +><DT +>5. <A +HREF="#TUNER-AUDMODE" +>Tuner Audio Modes</A +></DT +><DT +>6. <A +HREF="#TUNER-MATRIX" +>Tuner Audio Matrix</A +></DT +><DT +>1. <A +HREF="#V4L2-CAPABILITY" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_capability</CODE +></A +></DT +><DT +>2. <A +HREF="#DEVICE-CAPABILITIES" +>Device Capabilities Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-QUERYCTRL" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_queryctrl</CODE +></A +></DT +><DT +>2. <A +HREF="#V4L2-QUERYMENU" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_querymenu</CODE +></A +></DT +><DT +>3. <A +HREF="#V4L2-CTRL-TYPE" +>enum v4l2_ctrl_type</A +></DT +><DT +>4. <A +HREF="#CONTROL-FLAGS" +>Control Flags</A +></DT +><DT +>1. <A +HREF="#V4L2-REQUESTBUFFERS" +>struct <CODE +CLASS="STRUCTNAME" +>v4l2_requestbuffers</CODE +></A +></DT +><DT +>6-1. <A +HREF="#V4L-DEV" +>V4L Device Types, Names and Numbers</A +></DT +></DL +></DIV +><DIV +CLASS="LOT" +><DL +CLASS="LOT" +><DT +><B +>List of Figures</B +></DT +><DT +>1-1. <A +HREF="#CROP-SCALE" +>Cropping and Scaling</A +></DT +><DT +>3-1. <A +HREF="#FIELDSEQ-TB" +>Field Order, Top Field First Transmitted</A +></DT +><DT +>3-2. <A +HREF="#FIELDSEQ-BT" +>Field Order, Bottom Field First Transmitted</A +></DT +><DT +>4-1. <A +HREF="#VBI-HSYNC" +>Line synchronization</A +></DT +><DT +>4-2. <A +HREF="#VBI-525" +>ITU-R 525 line numbering (M/NTSC and M/PAL)</A +></DT +><DT +>4-3. <A +HREF="#VBI-625" +>ITU-R 625 line numbering</A +></DT +></DL +></DIV +><DIV +CLASS="LOT" +><DL +CLASS="LOT" +><DT +><B +>List of Examples</B +></DT +><DT +>1-1. <A +HREF="#AEN228" +>Information about the current video input</A +></DT +><DT +>1-2. <A +HREF="#AEN236" +>Switching to the first video input</A +></DT +><DT +>1-3. <A +HREF="#AEN282" +>Information about the current audio input</A +></DT +><DT +>1-4. <A +HREF="#AEN288" +>Switching to the first audio input</A +></DT +><DT +>1-5. <A +HREF="#AEN410" +>Information about the current video standard</A +></DT +><DT +>1-6. <A +HREF="#AEN419" +>Listing the video standards supported by the current +input</A +></DT +><DT +>1-7. <A +HREF="#AEN430" +>Selecting a new video standard</A +></DT +><DT +>1-8. <A +HREF="#AEN630" +>Enumerating all controls</A +></DT +><DT +>1-9. <A +HREF="#AEN641" +>Changing controls</A +></DT +><DT +>1-10. <A +HREF="#AEN747" +>Resetting the cropping parameters</A +></DT +><DT +>1-11. <A +HREF="#AEN757" +>Simple downscaling</A +></DT +><DT +>1-12. <A +HREF="#AEN765" +>Current scaling factor and pixel aspect</A +></DT +><DT +>2-1. <A +HREF="#AEN984" +>ITU-R Rec. BT.601 color conversion</A +></DT +><DT +>2-2. <A +HREF="#AEN1675" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR24</CODE +> 4 × 4 pixel +image</A +></DT +><DT +>2-1. <A +HREF="#AEN1819" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN1881" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN2026" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN2175" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +> 8 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN2402" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN2564" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN2702" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN2869" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>2-1. <A +HREF="#AEN3026" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +> 4 × 4 +pixel image</A +></DT +><DT +>3-1. <A +HREF="#AEN3316" +>Mapping buffers</A +></DT +><DT +>3-2. <A +HREF="#AEN3392" +>Initiating streaming I/O with user pointers</A +></DT +></DL +></DIV +><DIV +CLASS="PREFACE" +><HR><H1 +><A +NAME="AEN71" +></A +>Introduction</H1 +><P +>[to do]</P +><P +>If you have questions or ideas regarding the API, please try +the Video4Linux mailing list: <A +HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" +TARGET="_top" +>https://listman.redhat.com/mailman/listinfo/video4linux-list</A +></P +><P +>For documentation related requests contact the maintainer at +<A +HREF="mailto:mschimek@gmx.at" +TARGET="_top" +>mschimek@gmx.at</A +>.</P +><P +>The latest version of this document and the DocBook SGML +sources is currently hosted at <A +HREF="http://bytesex.org" +TARGET="_top" +>http://bytesex.org</A +>, site of the V4L +and V4L2 source code maintainer Gerd Knorr.</P +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="COMMON" +></A +>Chapter 1. Common API Elements</H1 +><P +>Programming a V4L2 device consists of these +steps:</P +><P +></P +><UL +><LI +><P +>Opening the device</P +></LI +><LI +><P +>Changing device properties, selecting a video and audio +input, video standard, picture brightness a. o.</P +></LI +><LI +><P +>Negotiating a data format</P +></LI +><LI +><P +>Negotiating an input/output method</P +></LI +><LI +><P +>The actual input/output loop</P +></LI +><LI +><P +>Closing the device</P +></LI +></UL +><P +>In practice most steps are optional and can be executed out of +order. It depends on the V4L2 device type, you can read about the +details in <A +HREF="#DEVICES" +>Chapter 4</A +>. In this chapter we will discuss +the basic concepts applicable to all devices.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="OPEN" +>1.1. Opening and Closing Devices</A +></H2 +><DIV +CLASS="SECTION" +><H3 +CLASS="SECTION" +><A +NAME="AEN100" +>1.1.1. Device Naming</A +></H3 +><P +>V4L2 drivers are implemented as kernel modules, loaded +manually by the system administrator or automatically when a device is +first opened. The driver modules plug into the "videodev" kernel +module. It provides helper functions and a common application +interface as specified in this document.</P +><P +>Each driver thus loaded registers one or more device nodes +with major number 81 and a minor number between 0 and 255. Assigning +minor numbers to V4L2 devices is entirely up to the system administrator, +this is primarily intended to solve conflicts between devices.<A +NAME="AEN104" +HREF="#FTN.AEN104" +><SPAN +CLASS="footnote" +>[1]</SPAN +></A +> The module options to select minor numbers are named +after the device special file with a "_nr" suffix. For example "video_nr" +for <TT +CLASS="FILENAME" +>/dev/video</TT +> video capture devices. The number is +an offset to the base minor number associated with the device type. +<A +NAME="AEN107" +HREF="#FTN.AEN107" +><SPAN +CLASS="footnote" +>[2]</SPAN +></A +> When the driver supports multiple devices of the same +type more than one minor number can be assigned, separated by commas: +<DIV +CLASS="INFORMALEXAMPLE" +><P +></P +><A +NAME="AEN109" +></A +><PRE +CLASS="SCREEN" +>> insmod mydriver.o video_nr=0,1 radio_nr=0,1</PRE +><P +></P +></DIV +></P +><P +>In <TT +CLASS="FILENAME" +>/etc/modules.conf</TT +> this may be +written as: <DIV +CLASS="INFORMALEXAMPLE" +><P +></P +><A +NAME="AEN113" +></A +><PRE +CLASS="SCREEN" +>alias char-major-81-0 mydriver +alias char-major-81-1 mydriver +alias char-major-81-64 mydriver <A +NAME="ALIAS" +><IMG +SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts1.gif" +HSPACE="0" +VSPACE="0" +BORDER="0" +ALT="(1)"></A +> +options mydriver video_nr=0,1 radio_nr=0,1 <A +NAME="OPTIONS" +><IMG +SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts2.gif" +HSPACE="0" +VSPACE="0" +BORDER="0" +ALT="(2)"></A +> + </PRE +><DIV +CLASS="CALLOUTLIST" +><DL +COMPACT="COMPACT" +><DT +><A +HREF="#ALIAS" +><IMG +SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts1.gif" +HSPACE="0" +VSPACE="0" +BORDER="0" +ALT="(1)"></A +></DT +><DD +>When an application attempts to open a device +special file with major number 81 and minor number 0, 1, or 64, load +"mydriver" (and the "videodev" module it depends upon).</DD +><DT +><A +HREF="#OPTIONS" +><IMG +SRC="/usr/share/sgml/docbook/stylesheet/dsssl/modular/images/callouts2.gif" +HSPACE="0" +VSPACE="0" +BORDER="0" +ALT="(2)"></A +></DT +><DD +>Register the first two video capture devices with +minor number 0 and 1 (base number is 0), the first two radio device +with minor number 64 and 65 (base 64).</DD +></DL +></DIV +><P +></P +></DIV +> When no minor number is given as module +option the driver supplies a default. <A +HREF="#DEVICES" +>Chapter 4</A +> +recommends the base minor numbers to be used for the various device +types. Obviously minor numbers must be unique. When the number is +already in use the <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>offending device</I +></SPAN +> will not be +registered. </P +><P +>By convention system administrators create various +character device special files with these major and minor numbers in +the <TT +CLASS="FILENAME" +>/dev</TT +> directory. The names recomended for the +different V4L2 device types are listed in <A +HREF="#DEVICES" +>Chapter 4</A +>.</P +><P +>The creation of character special files (with +<SPAN +CLASS="APPLICATION" +>mknod</SPAN +>) is a privileged operation and +devices cannot be opened by major and minor number. That means +applications cannot <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>reliable</I +></SPAN +> scan for loaded or +installed drivers. The user must enter a device name, or the +application can try the conventional device names.</P +><P +>Under the device filesystem (devfs) the minor number +options are ignored. V4L2 drivers (or by proxy the "videodev" module) +automatically create the required device files in the +<TT +CLASS="FILENAME" +>/dev/v4l</TT +> directory using the conventional device +names above.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="RELATED" +>1.1.2. Related Devices</A +></H3 +><P +>Devices can support several related functions. For example +video capturing, video overlay and VBI capturing are related because +these functions share, amongst other, the same video input and tuner +frequency. V4L and earlier versions of V4L2 used the same device name +and minor number for video capturing and overlay, but different ones +for VBI. Experience showed this approach has several problems<A +NAME="AEN135" +HREF="#FTN.AEN135" +><SPAN +CLASS="footnote" +>[3]</SPAN +></A +>, and to make things worse the V4L videodev module +used to prohibit multiple opens of a device.</P +><P +>As a remedy the present version of the V4L2 API relaxed the +concept of device types with specific names and minor numbers. For +compatibility with old applications drivers must still register different +minor numbers to assign a default function to the device. But if related +functions are supported by the driver they must be available under all +registered minor numbers. The desired function can be selected after +opening the device as described in <A +HREF="#DEVICES" +>Chapter 4</A +>.</P +><P +>Imagine a driver supporting video capturing, video +overlay, raw VBI capturing, and FM radio reception. It registers three +devices with minor number 0, 64 and 224 (this numbering scheme is +inherited from the V4L API). Regardless if +<TT +CLASS="FILENAME" +>/dev/video</TT +> (81, 0) or +<TT +CLASS="FILENAME" +>/dev/vbi</TT +> (81, 224) is opened the application can +select any one of the video capturing, overlay or VBI capturing +functions. Without programming (e. g. reading from the device +with <SPAN +CLASS="APPLICATION" +>dd</SPAN +> or <SPAN +CLASS="APPLICATION" +>cat</SPAN +>) +<TT +CLASS="FILENAME" +>/dev/video</TT +> captures video images, while +<TT +CLASS="FILENAME" +>/dev/vbi</TT +> captures raw VBI data. +<TT +CLASS="FILENAME" +>/dev/radio</TT +> (81, 64) is invariable a radio device, +unrelated to the video functions. Being unrelated does not imply the +devices can be used at the same time, however. The +<CODE +CLASS="FUNCTION" +>open()</CODE +> function may very well return an +<SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code.</P +><P +>Besides video input or output the hardware may also +support audio sampling or playback. If so, these functions are +implemented as OSS or ALSA PCM devices and eventually OSS or ALSA +audio mixer. The V4L2 API makes no provisions yet to find these +related devices. If you have an idea please write to the Video4Linux +mailing list: <A +HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" +TARGET="_top" +>https://listman.redhat.com/mailman/listinfo/video4linux-list</A +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN153" +>1.1.3. Multiple Opens</A +></H3 +><P +>In general, V4L2 devices can be opened more than once. +When this is supported by the driver, users can for example start a +"panel" application to change controls like brightness or audio +volume, while another application captures video and audio. In other words, panel +applications are comparable to an OSS or ALSA audio mixer application. +When a device supports multiple functions like capturing and overlay +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>simultaneously</I +></SPAN +>, multiple opens allow concurrent +use of the device by forked processes or specialized applications.</P +><P +>Multiple opens are optional, although drivers should +permit at least concurrent accesses without data exchange, i. e. +panel applications. This implies <CODE +CLASS="FUNCTION" +>open()</CODE +> can +return an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code when the device is already in use, as well as +<CODE +CLASS="FUNCTION" +>ioctl()</CODE +> functions initiating data exchange +(namely the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl), and the <CODE +CLASS="FUNCTION" +>read()</CODE +> +and <CODE +CLASS="FUNCTION" +>write()</CODE +> functions.</P +><P +>Mere opening a V4L2 device does not grant exclusive +access.<A +NAME="AEN166" +HREF="#FTN.AEN166" +><SPAN +CLASS="footnote" +>[4]</SPAN +></A +> Initiating data exchange however assigns the right +to read or write the requested type of data, and to change related +properties, to this file descriptor. Applications can request +additional access privileges using the priority mechanism described in +<A +HREF="#APP-PRI" +>Section 1.3</A +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN170" +>1.1.4. Shared Data Streams</A +></H3 +><P +>V4L2 drivers should not support multiple applications +reading or writing the same data stream on a device by copying +buffers, time multiplexing or similar means. This is better handled by +a proxy application in user space. When the driver supports stream +sharing anyway it must be implemented transparently. The V4L2 API does +not specify how conflicts are solved. </P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN173" +>1.1.5. Functions</A +></H3 +><P +>To open and close V4L2 devices applications use the <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> and <A +HREF="#FUNC-CLOSE" +><CODE +CLASS="FUNCTION" +>close()</CODE +></A +> function, +respectively. Devices are programmed using the <A +HREF="#FUNC-IOCTL" +><CODE +CLASS="FUNCTION" +>ioctl()</CODE +></A +> function as +explained in the following sections.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="QUERYCAP" +>1.2. Querying Capabilities</A +></H2 +><P +>Because V4L2 covers a wide variety of devices not all +aspects of the API are equally applicable to all types of devices. +Furthermore devices of the same type have different capabilities and +this specification permits the omission of a few complicated and less +important parts of the API.</P +><P +>The <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl is available to check if the kernel +device is compatible with this specification, and to query the <A +HREF="#DEVICES" +>functions</A +> and <A +HREF="#IO" +>I/O +methods</A +> supported by the device. Other features can be queried +by calling the respective ioctl, for example <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +> +to learn about the number, types and names of video connectors on the +device. Although abstraction is a major objective of this API, the +ioctl also allows driver specific applications to reliable identify +the driver.</P +><P +>All V4L2 drivers must support +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +>. Applications should always call +this ioctl after opening the device.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="APP-PRI" +>1.3. Application Priority</A +></H2 +><P +>When multiple applications share a device it may be +desirable to assign them different priorities. Contrary to the +traditional "rm -rf /" school of thought a video recording application +could for example block other applications from changing video +controls or switching the current TV channel. Another objective is to +permit low priority applications working in background, which can be +preempted by user controlled applications and automatically regain +control of the device at a later time.</P +><P +>Since these features cannot be implemented entirely in user +space V4L2 defines the <A +HREF="#VIDIOC-G-PRIORITY" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_PRIORITY</CODE +></A +> and <A +HREF="#VIDIOC-G-PRIORITY" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_PRIORITY</CODE +></A +> +ioctls to request and query the access priority associate with a file +descriptor. Opening a device assigns a medium priority, compatible +with earlier versions of V4L2 and drivers not supporting these ioctls. +Applications requiring a different priority will usually call +<CODE +CLASS="CONSTANT" +>VIDIOC_S_PRIORITY</CODE +> after verifying the device with +the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl.</P +><P +>Ioctls changing driver properties, such as <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_INPUT</CODE +></A +>, +return an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code after another application obtained higher priority. +An event mechanism to notify applications about asynchronous property +changes has been proposed but not added yet.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="VIDEO" +>1.4. Video Inputs and Outputs</A +></H2 +><P +>Video inputs and outputs are physical connectors of a +device. These can be for example RF connectors (antenna/cable), CVBS +a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI +capture devices have inputs, output devices have outputs, at least one +each. Radio devices have no video inputs or outputs.</P +><P +>To learn about the number and attributes of the +available inputs and outputs applications can enumerate them with the +<A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +> and <A +HREF="#VIDIOC-ENUMOUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMOUTPUT</CODE +></A +> ioctl, respectively. The +struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> returned by the <CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +> +ioctl also contains signal status information applicable when the +current video input is queried.</P +><P +>The <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +></A +> and <A +HREF="#VIDIOC-G-OUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_OUTPUT</CODE +></A +> ioctl return the +index of the current video input or output. To select a different +input or output applications call the <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_INPUT</CODE +></A +> and +<A +HREF="#VIDIOC-G-OUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_OUTPUT</CODE +></A +> ioctl. Drivers must implement all the input ioctls +when the device has one or more inputs, all the output ioctls when the +device has one or more outputs.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN228" +></A +><P +><B +>Example 1-1. Information about the current video input</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> input; +int index; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +></A +>, &index)) { + perror ("VIDIOC_G_INPUT"); + exit (EXIT_FAILURE); +} + +memset (&input, 0, sizeof (input)); +input.index = index; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +>, &input)) { + perror ("VIDIOC_ENUMINPUT"); + exit (EXIT_FAILURE); +} + +printf ("Current input: %s\n", input.name); + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN236" +></A +><P +><B +>Example 1-2. Switching to the first video input</B +></P +><PRE +CLASS="PROGRAMLISTING" +>int index; + +index = 0; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_INPUT</CODE +></A +>, &index)) { + perror ("VIDIOC_S_INPUT"); + exit (EXIT_FAILURE); +} + </PRE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AUDIO" +>1.5. Audio Inputs and Outputs</A +></H2 +><P +>Audio inputs and outputs are physical connectors of a +device. Video capture devices have inputs, output devices have +outputs, zero or more each. Radio devices have no audio inputs or +outputs. They have exactly one tuner which in fact +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>is</I +></SPAN +> an audio source, but this API associates +tuners with video inputs or outputs only, and radio devices have +none of these.<A +NAME="AEN245" +HREF="#FTN.AEN245" +><SPAN +CLASS="footnote" +>[5]</SPAN +></A +> A connector on a TV card to loop back the received +audio signal to a sound card is not considered an audio output.</P +><P +>Audio and video inputs and outputs are associated. Selecting +a video source also selects an audio source. This is most evident when +the video and audio source is a tuner. Further audio connectors can +combine with more than one video input or output. Assumed two +composite video inputs and two audio inputs exist, there may be up to +four valid combinations. The relation of video and audio connectors +is defined in the <CODE +CLASS="STRUCTFIELD" +>audioset</CODE +> field of the +respective struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> or struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +>, where each bit represents +the index number, starting at zero, of one audio input or output.</P +><P +>To learn about the number and attributes of the +available inputs and outputs applications can enumerate them with the +<A +HREF="#VIDIOC-ENUMAUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDIO</CODE +></A +> and <A +HREF="#VIDIOC-ENUMAUDIOOUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDOUT</CODE +></A +> ioctl, respectively. The +struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> returned by the <CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDIO</CODE +> ioctl +also contains signal status information applicable when the current +audio input is queried.</P +><P +>The <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +></A +> and <A +HREF="#VIDIOC-G-AUDIOOUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDOUT</CODE +></A +> ioctl report +the current audio input and output, respectively. Note that, unlike +<A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +></A +> and <A +HREF="#VIDIOC-G-OUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_OUTPUT</CODE +></A +> these ioctls return a structure +as <CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDIO</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDOUT</CODE +> do, not just an index.</P +><P +>To select an audio input and change its properties +applications call the <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDIO</CODE +></A +> ioctl. To select an audio +output (which presently has no changeable properties) applications +call the <A +HREF="#VIDIOC-G-AUDIOOUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDOUT</CODE +></A +> ioctl.</P +><P +>Drivers must implement all input ioctls when the device +has one or more inputs, all output ioctls when the device has one +or more outputs. When the device has any audio inputs or outputs the +driver must set the <CODE +CLASS="CONSTANT" +>V4L2_CAP_AUDIO</CODE +> flag in the +struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN282" +></A +><P +><B +>Example 1-3. Information about the current audio input</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> audio; + +memset (&audio, 0, sizeof (audio)); + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +></A +>, &audio)) { + perror ("VIDIOC_G_AUDIO"); + exit (EXIT_FAILURE); +} + +printf ("Current input: %s\n", audio.name); + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN288" +></A +><P +><B +>Example 1-4. Switching to the first audio input</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> audio; + +memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */ + +audio.index = 0; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDIO</CODE +></A +>, &audio)) { + perror ("VIDIOC_S_AUDIO"); + exit (EXIT_FAILURE); +} + </PRE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="TUNER" +>1.6. Tuners and Modulators</A +></H2 +><DIV +CLASS="SECTION" +><H3 +CLASS="SECTION" +><A +NAME="AEN296" +>1.6.1. Tuners</A +></H3 +><P +>Video input devices can have one or more tuners +demodulating a RF signal. Each tuner is associated with one or more +video inputs, depending on the number of RF connectors on the tuner. +The <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of the respective +struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> returned by the <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +> ioctl is set to +<CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_TUNER</CODE +> and its +<CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> field contains the index number of +the tuner.</P +><P +>Radio devices have exactly one tuner with index zero, no +video inputs.</P +><P +>To query and change tuner properties applications use the +<A +HREF="#VIDIOC-G-TUNER" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_TUNER</CODE +></A +> and <A +HREF="#VIDIOC-G-TUNER" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_TUNER</CODE +></A +> ioctl, respectively. The +struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> returned by <CODE +CLASS="CONSTANT" +>VIDIOC_G_TUNER</CODE +> also +contains signal status information applicable when the tuner of the +current video input, or a radio tuner is queried. Note that +<CODE +CLASS="CONSTANT" +>VIDIOC_S_TUNER</CODE +> does not switch the current tuner, +when there is more than one at all. The tuner is solely determined by +the current video input. Drivers must support both ioctls and set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_TUNER</CODE +> flag in the struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl when the device has one or +more tuners.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN318" +>1.6.2. Modulators</A +></H3 +><P +>Video output devices can have one or more modulators, uh, +modulating a video signal for radiation or connection to the antenna +input of a TV set or video recorder. Each modulator is associated with +one or more video outputs, depending on the number of RF connectors on +the modulator. The <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of the +respective struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> returned by the <A +HREF="#VIDIOC-ENUMOUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMOUTPUT</CODE +></A +> is set to +<CODE +CLASS="CONSTANT" +>V4L2_OUTPUT_TYPE_MODULATOR</CODE +> and its +<CODE +CLASS="STRUCTFIELD" +>modulator</CODE +> field contains the index number +of the modulator. This specification does not define radio output +devices.</P +><P +>To query and change modulator properties applications use +the <A +HREF="#VIDIOC-G-MODULATOR" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_MODULATOR</CODE +></A +> and <A +HREF="#VIDIOC-G-MODULATOR" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_MODULATOR</CODE +></A +> ioctl. Note that +<CODE +CLASS="CONSTANT" +>VIDIOC_S_MODULATOR</CODE +> does not switch the current +modulator, when there is more than one at all. The modulator is solely +determined by the current video output. Drivers must support both +ioctls and set the <CODE +CLASS="CONSTANT" +>V4L2_CAP_TUNER</CODE +> (sic) flag in +the struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl when the +device has one or more modulators.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN337" +>1.6.3. Radio Frequency</A +></H3 +><P +>To get and set the tuner or modulator radio frequency +applications use the <A +HREF="#VIDIOC-G-FREQUENCY" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FREQUENCY</CODE +></A +> and <A +HREF="#VIDIOC-G-FREQUENCY" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FREQUENCY</CODE +></A +> +ioctl which both take a pointer to a struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +>. These ioctls +are used for TV and radio devices alike. Drivers must support both +ioctls when the tuner or modulator ioctls are supported, or +when the device is a radio device.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN345" +>1.6.4. Satellite Receivers</A +></H3 +><P +>To be discussed. See also +proposals by Peter Schlaf, video4linux-list@redhat.com on 23 Oct 2002, +subject: "Re: [V4L] Re: v4l2 api".</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="STANDARD" +>1.7. Video Standards</A +></H2 +><P +>Video devices typically support one or more different video +standards or variations of standards. Each video input and output may +support another set of standards. This set is reported by the +<CODE +CLASS="STRUCTFIELD" +>std</CODE +> field of struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> and +struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> returned by the <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +> and +<A +HREF="#VIDIOC-ENUMOUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMOUTPUT</CODE +></A +> ioctl, respectively.</P +><P +>V4L2 defines one bit for each analog video standard +currently in use worldwide, and sets aside bits for driver defined +standards, e. g. hybrid standards to watch NTSC video tapes on PAL TVs +and vice versa. Applications can use the predefined bits to select a +particular standard, although presenting the user a menu of supported +standards is preferred. To enumerate and query the attributes of the +supported standards applications use the <A +HREF="#VIDIOC-ENUMSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +></A +> ioctl.</P +><P +>Many of the defined standards are actually just variations +of a few major standards. The hardware may in fact not distinguish +between them, or do so internal and switch automatically. Therefore +enumerated standards also contain sets of one or more standard +bits.</P +><P +>Assume a hypothetic tuner capable of demodulating B/PAL, +G/PAL and I/PAL signals. The first enumerated standard is a set of B +and G/PAL, switched automatically depending on the selected radio +frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" +choice. Similar a Composite input may collapse standards, enumerating +"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<A +NAME="AEN363" +HREF="#FTN.AEN363" +><SPAN +CLASS="footnote" +>[6]</SPAN +></A +></P +><P +>To query and select the standard used by the current video +input or output applications call the <A +HREF="#VIDIOC-G-STD" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +></A +> and +<A +HREF="#VIDIOC-G-STD" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +></A +> ioctl, respectively. The <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>received</I +></SPAN +> +standard can be sensed with the <A +HREF="#VIDIOC-QUERYSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYSTD</CODE +></A +> ioctl. Note parameter of all these ioctls is a pointer to a <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> type (a standard set), <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> an index into the standard enumeration.<A +NAME="AEN375" +HREF="#FTN.AEN375" +><SPAN +CLASS="footnote" +>[7]</SPAN +></A +> Drivers must implement all video standard ioctls +when the device has one or more video inputs or outputs.</P +><P +>Special rules apply to USB cameras where the notion of video +standards makes little sense. More generally any capture device, +output devices accordingly, which is <P +></P +><UL +><LI +><P +>incapable of capturing fields or frames at the nominal +rate of the video standard, or</P +></LI +><LI +><P +>where <A +HREF="#BUFFER" +>timestamps</A +> refer +to the instant the field or frame was received by the driver, not the +capture time, or</P +></LI +><LI +><P +>where <A +HREF="#BUFFER" +>sequence numbers</A +> +refer to the frames received by the driver, not the captured +frames.</P +></LI +></UL +> Here the driver shall set the +<CODE +CLASS="STRUCTFIELD" +>std</CODE +> field of struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> and struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> +to zero, the <CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYSTD</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +> ioctls shall return the +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.<A +NAME="AEN407" +HREF="#FTN.AEN407" +><SPAN +CLASS="footnote" +>[8]</SPAN +></A +></P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN410" +></A +><P +><B +>Example 1-5. Information about the current video standard</B +></P +><PRE +CLASS="PROGRAMLISTING" +><A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> std; +struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> standard; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-STD" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +></A +>, &std)) { + /* Note when VIDIOC_ENUMSTD always returns EINVAL this + is no video device or it falls under the USB exception, + and VIDIOC_G_STD returning EINVAL is no error. */ + + perror ("VIDIOC_G_STD"); + exit (EXIT_FAILURE); +} + +memset (&standard, 0, sizeof (standard)); +standard.index = 0; + +while (0 == ioctl (fd, <A +HREF="#VIDIOC-ENUMSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +></A +>, &standard)) { + if (standard.id & std) { + printf ("Current video standard: %s\n", standard.name); + exit (EXIT_SUCCESS); + } + + standard.index++; +} + +/* EINVAL indicates the end of the enumeration, which cannot be + empty unless this device falls under the USB exception. */ + +if (errno == EINVAL || standard.index == 0) { + perror ("VIDIOC_ENUMSTD"); + exit (EXIT_FAILURE); +} + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN419" +></A +><P +><B +>Example 1-6. Listing the video standards supported by the current +input</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> input; +struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> standard; + +memset (&input, 0, sizeof (input)); + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +></A +>, &input.index)) { + perror ("VIDIOC_G_INPUT"); + exit (EXIT_FAILURE); +} + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +>, &input)) { + perror ("VIDIOC_ENUM_INPUT"); + exit (EXIT_FAILURE); +} + +printf ("Current input %s supports:\n", input.name); + +memset (&standard, 0, sizeof (standard)); +standard.index = 0; + +while (0 == ioctl (fd, <A +HREF="#VIDIOC-ENUMSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +></A +>, &standard)) { + if (standard.id & input.std) + printf ("%s\n", standard.name); + + standard.index++; +} + +/* EINVAL indicates the end of the enumeration, which cannot be + empty unless this device falls under the USB exception. */ + +if (errno != EINVAL || standard.index == 0) { + perror ("VIDIOC_ENUMSTD"); + exit (EXIT_FAILURE); +} + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN430" +></A +><P +><B +>Example 1-7. Selecting a new video standard</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> input; + +memset (&input, 0, sizeof (input)); + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +></A +>, &input.index)) { + perror ("VIDIOC_G_INPUT"); + exit (EXIT_FAILURE); +} + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +>, &input)) { + perror ("VIDIOC_ENUM_INPUT"); + exit (EXIT_FAILURE); +} + +if (0 == (input.std & V4L2_STD_PAL_BG)) { + fprintf (stderr, "Oops. B/G PAL is not supported.\n"); + exit (EXIT_FAILURE); +} + +/* Note this is also supposed to work when only B + <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>or</I +></SPAN +> G/PAL is supported. */ + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-STD" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +></A +>, V4L2_STD_PAL_BG)) { + perror ("VIDIOC_S_STD"); + exit (EXIT_FAILURE); +} + </PRE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="CONTROL" +>1.8. Controls</A +></H2 +><P +>Devices typically have a number of user-settable controls +such as brightness, saturation and so on, which would be presented to +the user on a graphical user interface. But, different devices +will have different controls available, and furthermore, the range of +possible values, and the default value will vary from device to +device. The control ioctls provide the information and a mechanism to +create a nice user interface for these controls that will work +correctly with any device.</P +><P +>All controls are accessed using an ID value. V4L2 defines +several IDs for specific purposes. Drivers can also implement their +own custom controls using <CODE +CLASS="CONSTANT" +>V4L2_CID_PRIVATE_BASE</CODE +> +and higher values. The pre-defined control IDs have the prefix +<CODE +CLASS="CONSTANT" +>V4L2_CID_</CODE +>, and are listed in <A +HREF="#CONTROL-ID" +>Table 1-1</A +>. The ID is used when querying the attributes of +a control, and when getting or setting the current value.</P +><P +>Generally applications should present controls to the user +without assumptions about their purpose. Each control comes with a +name string the user is supposed to understand. When the purpose is +non-intuitive the driver writer should provide a user manual, a user +interface plug-in or a driver specific panel application. Predefined +IDs were introduced to change a few controls programmatically, for +example to mute a device during a channel switch.</P +><P +>Drivers may enumerate different controls after switching the +current video input or output, tuner or modulator, or audio input or +output. Different in the sense of other bounds, another default and +current value, step size or other menu items. A control with a certain +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>custom</I +></SPAN +> ID can also change name and type.<A +NAME="AEN451" +HREF="#FTN.AEN451" +><SPAN +CLASS="footnote" +>[9]</SPAN +></A +> Control values are stored globally, they do not +change when switching except to stay within the reported bounds. They +also do not change e. g. when the device is opened or closed, when the +tuner radio frequency is changed or generally never without +application request. Since V4L2 specifies no event mechanism, panel +applications intended to cooperate with other panel applications (be +they built into a larger application, as a TV viewer) may need to +regularly poll control values to update their user +interface.<A +NAME="AEN454" +HREF="#FTN.AEN454" +><SPAN +CLASS="footnote" +>[10]</SPAN +></A +></P +><DIV +CLASS="TABLE" +><A +NAME="CONTROL-ID" +></A +><P +><B +>Table 1-1. Control IDs</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><THEAD +><TR +><TH +>ID</TH +><TH +>Type</TH +><TH +>Description</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_BASE</CODE +></TD +><TD +> </TD +><TD +>First predefined ID, equal to +<CODE +CLASS="CONSTANT" +>V4L2_CID_BRIGHTNESS</CODE +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_BRIGHTNESS</CODE +></TD +><TD +>integer</TD +><TD +>Picture brightness, or more precisely, the black + level. Will not turn up the intelligence of the program + you're watching.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_CONTRAST</CODE +></TD +><TD +>integer</TD +><TD +>Picture contrast or luma gain.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_SATURATION</CODE +></TD +><TD +>integer</TD +><TD +>Picture color saturation or chroma gain.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_HUE</CODE +></TD +><TD +>integer</TD +><TD +>Hue or color balance.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_VOLUME</CODE +></TD +><TD +>integer</TD +><TD +>Overall audio volume. Note some drivers also +provide an OSS or ALSA mixer interface.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_BALANCE</CODE +></TD +><TD +>integer</TD +><TD +>Audio stereo balance. Minimum corresponds to all +the way left, maximum to right.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_BASS</CODE +></TD +><TD +>integer</TD +><TD +>Audio bass adjustment.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_TREBLE</CODE +></TD +><TD +>integer</TD +><TD +>Audio treble adjustment.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_MUTE</CODE +></TD +><TD +>boolean</TD +><TD +>Mute audio, i. e. set the volume to zero, however +without affecting <CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_VOLUME</CODE +>. Like +ALSA drivers, V4L2 drivers must mute at load time to avoid excessive +noise. Actually the entire device should be reset to a low power +consumption state.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_LOUDNESS</CODE +></TD +><TD +>boolean</TD +><TD +>Loudness mode (bass boost).</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_BLACK_LEVEL</CODE +></TD +><TD +>integer</TD +><TD +>Another name for brightness (not a synonym of +<CODE +CLASS="CONSTANT" +>V4L2_CID_BRIGHTNESS</CODE +>). [?]</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUTO_WHITE_BALANCE</CODE +></TD +><TD +>boolean</TD +><TD +>Automatic white balance (cameras).</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_DO_WHITE_BALANCE</CODE +></TD +><TD +>button</TD +><TD +>This is an action control. When set (the value is +ignored), the device will do a white balance and then hold the current +setting. Contrast this with the boolean +<CODE +CLASS="CONSTANT" +>V4L2_CID_AUTO_WHITE_BALANCE</CODE +>, which, when +activated, keeps adjusting the white balance.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_RED_BALANCE</CODE +></TD +><TD +>integer</TD +><TD +>Red chroma balance.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_BLUE_BALANCE</CODE +></TD +><TD +>integer</TD +><TD +>Blue chroma balance.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_GAMMA</CODE +></TD +><TD +>integer</TD +><TD +>Gamma adjust.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_WHITENESS</CODE +></TD +><TD +>integer</TD +><TD +>Whiteness for grey-scale devices. This is a synonym +for <CODE +CLASS="CONSTANT" +>V4L2_CID_GAMMA</CODE +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_EXPOSURE</CODE +></TD +><TD +>integer</TD +><TD +>Exposure (cameras). [Unit?]</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUTOGAIN</CODE +></TD +><TD +>boolean</TD +><TD +>Automatic gain/exposure control.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_GAIN</CODE +></TD +><TD +>integer</TD +><TD +>Gain control.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_HFLIP</CODE +></TD +><TD +>boolean</TD +><TD +>Mirror the picture horizontally.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_VFLIP</CODE +></TD +><TD +>boolean</TD +><TD +>Mirror the picture vertically.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_HCENTER</CODE +></TD +><TD +>integer</TD +><TD +>Horizontal image centering.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_VCENTER</CODE +></TD +><TD +>integer</TD +><TD +>Vertical image centering. Centering is intended to +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>physically</I +></SPAN +> adjust cameras. For image cropping see +<A +HREF="#CROP" +>Section 1.10</A +>, for clipping <A +HREF="#OVERLAY" +>Section 4.2</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_LASTP1</CODE +></TD +><TD +> </TD +><TD +>End of the predefined control IDs + (currently <CODE +CLASS="CONSTANT" +>V4L2_CID_VCENTER</CODE +> + 1).</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_PRIVATE_BASE</CODE +></TD +><TD +> </TD +><TD +>ID of the first custom (driver specific) control. +Applications depending on particular custom controls should check the +driver name and version, see <A +HREF="#QUERYCAP" +>Section 1.2</A +>.</TD +></TR +></TBODY +></TABLE +></DIV +><P +>Applications can enumerate the available controls with the +<A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +> and <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYMENU</CODE +></A +> ioctls, get and set a +control value with the <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +></A +> and <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +> ioctls. +Drivers must implement <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +> when the device has one or more +controls, <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYMENU</CODE +> when it has one or +more menu type controls.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN630" +></A +><P +><B +>Example 1-8. Enumerating all controls</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> queryctrl; +struct <A +HREF="#V4L2-QUERYMENU" +>v4l2_querymenu</A +> querymenu; + +static void +enumerate_menu (void) +{ + printf (" Menu items:\n"); + + memset (&querymenu, 0, sizeof (querymenu)); + querymenu.id = queryctrl.id; + + for (querymenu.index = queryctrl.minimum; + querymenu.index <= queryctrl.maximum; + querymenu.index++) { + if (0 == ioctl (fd, <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYMENU</CODE +></A +>, &querymenu)) { + printf (" %s\n", querymenu.name); + } else { + perror ("VIDIOC_QUERYMENU"); + exit (EXIT_FAILURE); + } + } +} + +memset (&queryctrl, 0, sizeof (queryctrl)); + +for (queryctrl.id = V4L2_CID_BASE; + queryctrl.id < V4L2_CID_LASTP1; + queryctrl.id++) { + if (0 == ioctl (fd, <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +>, &queryctrl)) { + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf ("Control %s\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu (); + } else { + if (errno == EINVAL) + continue; + + perror ("VIDIOC_QUERYCTRL"); + exit (EXIT_FAILURE); + } +} + +for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; + queryctrl.id++) { + if (0 == ioctl (fd, <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +>, &queryctrl)) { + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf ("Control %s\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu (); + } else { + if (errno == EINVAL) + break; + + perror ("VIDIOC_QUERYCTRL"); + exit (EXIT_FAILURE); + } +} + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN641" +></A +><P +><B +>Example 1-9. Changing controls</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> queryctrl; +struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +> control; + +memset (&queryctrl, 0, sizeof (queryctrl)); +queryctrl.id = V4L2_CID_BRIGHTNESS; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +>, &queryctrl)) { + if (errno != EINVAL) { + perror ("VIDIOC_QUERYCTRL"); + exit (EXIT_FAILURE); + } else { + printf ("V4L2_CID_BRIGHTNESS is not supported\n"); + } +} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { + printf ("V4L2_CID_BRIGHTNESS is not supported\n"); +} else { + memset (&control, 0, sizeof (control)); + control.id = V4L2_CID_BRIGHTNESS; + control.value = queryctrl.default_value; + + if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +>, &control)) { + perror ("VIDIOC_S_CTRL"); + exit (EXIT_FAILURE); + } +} + +memset (&control, 0, sizeof (control)); +control.id = V4L2_CID_CONTRAST; + +if (0 == ioctl (fd, <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +></A +>, &control)) { + control.value += 1; + + /* The driver may clamp the value or return ERANGE, ignored here */ + + if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +>, &control) + && errno != ERANGE) { + perror ("VIDIOC_S_CTRL"); + exit (EXIT_FAILURE); + } +/* Ignore if V4L2_CID_CONTRAST is unsupported */ +} else if (errno != EINVAL) { + perror ("VIDIOC_G_CTRL"); + exit (EXIT_FAILURE); +} + +control.id = V4L2_CID_AUDIO_MUTE; +control.value = TRUE; /* silence */ + +/* Errors ignored */ +ioctl (fd, VIDIOC_S_CTRL, &control); + </PRE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="FORMAT" +>1.9. Data Formats</A +></H2 +><DIV +CLASS="SECTION" +><H3 +CLASS="SECTION" +><A +NAME="AEN656" +>1.9.1. Data Format Negotiation</A +></H3 +><P +>Different devices exchange different kinds of data with +applications, for example video images, raw or sliced VBI data, RDS +datagrams. Even within one kind many different formats are possible, +in particular an abundance of image formats. Although drivers must +provide a default and the selection persists across closing and +reopening a device, applications should always negotiate a data format +before engaging in data exchange. Negotiation means the application +asks for a particular format and the driver selects and reports the +best the hardware can do to satisfy the request. Of course +applications can also just query the current selection.</P +><P +>A single mechanism exists to negotiate all data formats +using the aggregate struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> and the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> and +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctls. Additionally the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +></A +> ioctl can be +used to examine what the hardware <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>could</I +></SPAN +> do, +without actually selecting a new data format. The data formats +supported by the V4L2 API are covered in the respective device section +in <A +HREF="#DEVICES" +>Chapter 4</A +>. For a closer look at image formats see +<A +HREF="#PIXFMT" +>Chapter 2</A +>.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> ioctl is a major +turning-point in the initialization sequence. Prior to this point +multiple panel applications can access the same device concurrently to +select the current input, change controls or modify other properties. +The first <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> assigns a logical stream +(video data, VBI data etc.) exclusively to one file descriptor.</P +><P +>Exclusive means no other application, more precisely no +other file descriptor, can grab this stream or change device +properties inconsistent with the negotiated parameters. A video +standard change for example, when the new standard uses a different +number of scan lines, can invalidate the selected image format. +Therefore only the file descriptor owning the stream can make +invalidating changes. Accordingly multiple file descriptors which +grabbed different logical streams prevent each other from interfering +with their settings. When for example video overlay is about to start +or already in progress, simultaneous video capturing may be restricted +to the same cropping and image size.</P +><P +>When applications omit the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> ioctl its locking side effects are +implied by the next step, the selection of an I/O method with the +<A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl or implicit with the first <A +HREF="#FUNC-READ" +><CODE +CLASS="FUNCTION" +>read()</CODE +></A +> or +<A +HREF="#FUNC-WRITE" +><CODE +CLASS="FUNCTION" +>write()</CODE +></A +> call.</P +><P +>Generally only one logical stream can be assigned to a +file descriptor, the exception being drivers permitting simultaneous +video capturing and overlay using the same file descriptor for +compatibility with V4L and earlier versions of V4L2. Switching the +logical stream or returning into "panel mode" is possible by closing +and reopening the device. Drivers <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>may</I +></SPAN +> support a +switch using <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +>.</P +><P +>All drivers exchanging data with +applications must support the <CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> ioctl. Implementation of the +<CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +> is highly recommended but +optional.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN689" +>1.9.2. Image Format Enumeration</A +></H3 +><P +>Apart of the generic format negotiation functions +a special ioctl to enumerate all image formats supported by video +capture, overlay or output devices is available.<A +NAME="AEN692" +HREF="#FTN.AEN692" +><SPAN +CLASS="footnote" +>[11]</SPAN +></A +></P +><P +>The <A +HREF="#VIDIOC-ENUM-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUM_FMT</CODE +></A +> ioctl must be supported +by all drivers exchanging image data with applications.</P +><DIV +CLASS="IMPORTANT" +><BLOCKQUOTE +CLASS="IMPORTANT" +><P +><B +>Important: </B +>Drivers are not supposed to convert image formats in +kernel space. They must enumerate only formats directly supported by +the hardware. If necessary driver writers should publish an example +conversion routine or library for integration into applications.</P +></BLOCKQUOTE +></DIV +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="CROP" +>1.10. Cropping and Scaling</A +></H2 +><P +>Some video capture devices can take a subsection of the +complete picture and shrink or enlarge to an image of arbitrary size. +We call these abilities cropping and scaling. Not quite correct +"cropping" shall also refer to the inverse process, output devices +showing an image in only a region of the picture, and/or scaled +from a source image of different size.</P +><P +>To crop and scale this API defines a source and target +rectangle. On a video capture and overlay device the source is the +received video picture, the target is the captured or overlaid image. +On a video output device the source is the image passed by the +application and the target is the generated video picture. The +remainder of this section refers only to video capture drivers, the +definitions apply to output drivers accordingly.</P +><DIV +CLASS="FIGURE" +><A +NAME="CROP-SCALE" +></A +><P +><B +>Figure 1-1. Cropping and Scaling</B +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="crop.gif"></P +></DIV +></DIV +><P +>It is assumed the driver can capture a subsection of the +picture within an arbitrary capture window. Its bounds are defined by +struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +>, giving the coordinates of the top, left corner and +width and height of the window in pixels. Origin and units of the +coordinate system in the analog domain are arbitrarily chosen by the +driver writer.<A +NAME="AEN714" +HREF="#FTN.AEN714" +><SPAN +CLASS="footnote" +>[12]</SPAN +></A +></P +><P +>The source rectangle is defined by struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +>, giving the +coordinates of its top, left corner, width and height using the same +coordinate system as struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +>. The source rectangle must lie +completely within the capture window. Further each driver defines a +default source rectangle. The center of this rectangle shall align +with the center of the active picture area of the video signal, and +cover what the driver writer considers the complete picture. The +source rectangle is set to the default when the driver is first +loaded, but not later.</P +><P +>The target rectangle is given either by the +<CODE +CLASS="STRUCTFIELD" +>width</CODE +> and <CODE +CLASS="STRUCTFIELD" +>height</CODE +> +fields of struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> or the <CODE +CLASS="STRUCTFIELD" +>width</CODE +> +and <CODE +CLASS="STRUCTFIELD" +>height</CODE +> fields of the struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> +<CODE +CLASS="STRUCTFIELD" +>w</CODE +> substructure of struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +>.</P +><P +>In principle cropping and scaling always happens. When the +device supports scaling but not cropping, applications will be unable +to change the cropping rectangle. It remains at the defaults all the +time. When the device supports cropping but not scaling, changing the +image size will also affect the cropping size in order to maintain a +constant scaling factor. The position of the cropping rectangle is +only adjusted to move the rectangle completely inside the capture +window.</P +><P +>When cropping and scaling is supported applications can +change both the source and target rectangle. Various hardware +limitations must be expected, for example discrete scaling factors, +different scaling abilities in horizontal and vertical direction, +limitations of the image size or the cropping alignment. Therefore as +usual drivers adjust the requested parameters against hardware +capabilities and return the actual values selected. An important +difference, because two rectangles are defined, is that the last +rectangle changed shall take priority, and the driver may also adjust +the opposite rectangle.</P +><P +>Suppose scaling is restricted to a factor 1:1 or 2:1 in +either direction and the image size must be a multiple of +16 × 16 pixels. The cropping rectangle be set to the +upper limit, 640 × 400 pixels at offset 0, 0. Let +a video capture application request an image size of +300 × 225 pixels, assuming video will be scaled down +from the "full picture" accordingly. The driver will set the image +size to the closest possible values 304 × 224, then +choose the cropping rectangle closest to the requested size, that is +608 × 224 (224 × 2:1 would exceed the +limit 400). The offset 0, 0 is still valid, thus unmodified. +Given the default cropping rectangle reported by +<CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +> the application can easily propose +another offset to center the cropping rectangle. Now the application may +insist on covering an area using an aspect closer to the original +request. Sheepish it asks for a cropping rectangle of +608 × 456 pixels. The present scaling factors limit +cropping to 640 × 384, so the driver returns the +cropping size 608 × 384 and accordingly adjusts +the image size to 304 × 192.</P +><P +>Eventually some crop or scale parameters are locked, for +example when the driver supports simultaneous video capturing and +overlay, another application already started overlay and the cropping +parameters cannot be changed anymore. Also <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +></A +> cannot +change the cropping rectangle. In these cases the driver has to +approach the closest values possible without adjusting the opposite +rectangle.</P +><P +>The struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +>, which also reports the pixel aspect ratio, +can be obtained with the <A +HREF="#VIDIOC-CROPCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +></A +> ioctl. To get or set the +current cropping rectangle applications call the <A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +></A +> or +<A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +></A +> ioctl, respectively. All video capture and output +devices must support the <CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +> ioctl. +The <CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +> ioctls only when the cropping +rectangle can be changed.</P +><P +>Note as usual the cropping parameters remain unchanged +across closing and reopening a device. Applications should ensure the +parameters are suitable before starting I/O.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN747" +></A +><P +><B +>Example 1-10. Resetting the cropping parameters</B +></P +><P +>(A video capture device is assumed.)</P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> cropcap; +struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +> crop; + +memset (&cropcap, 0, sizeof (cropcap)); +cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-CROPCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +></A +>, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); +} + +memset (&crop, 0, sizeof (crop)); +crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +crop.c = cropcap.defrect; + +/* Ignore if cropping is not supported (EINVAL) */ + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +></A +>, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); +} + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN757" +></A +><P +><B +>Example 1-11. Simple downscaling</B +></P +><P +>(A video capture device is assumed.)</P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> cropcap; +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> format; + +reset_cropping_parameters (); + +/* Scale down to 1/4 size of full picture */ + +memset (&format, 0, sizeof (format)); /* defaults */ + +format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +format.fmt.pix.width = cropcap.defrect.width >> 1; +format.fmt.pix.height = cropcap.defrect.height >> 1; +format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +>, &format)) { + perror ("VIDIOC_S_FORMAT"); + exit (EXIT_FAILURE); +} + +/* We could check now what we got, the exact scaling factor + or if the driver can scale at all. At mere 2:1 the cropping + rectangle was probably not changed. */ + </PRE +></DIV +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN765" +></A +><P +><B +>Example 1-12. Current scaling factor and pixel aspect</B +></P +><P +>(A video capture device is assumed.)</P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> cropcap; +struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +> crop; +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> format; +double hscale, vscale; +double aspect; +int dwidth, dheight; + +memset (&cropcap, 0, sizeof (cropcap)); +cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-CROPCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +></A +>, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); +} + +memset (&crop, 0, sizeof (crop)); +crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +></A +>, &crop)) { + if (errno != EINVAL) { + perror ("VIDIOC_G_CROP"); + exit (EXIT_FAILURE); + } + + /* Cropping not supported */ + crop.c = cropcap.defrect; +} + +memset (&format, 0, sizeof (format)); +format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +>, &format)) { + perror ("VIDIOC_G_FMT"); + exit (EXIT_FAILURE); +} + +hscale = format.fmt.pix.width / (double) crop.c.width; +vscale = format.fmt.pix.height / (double) crop.c.height; + +aspect = cropcap.pixelaspect.numerator / + (double) cropcap.pixelaspect.denominator; +aspect = aspect * hscale / vscale; + +/* Aspect corrected display size */ + +dwidth = format.fmt.pix.width / aspect; +dheight = format.fmt.pix.height; + </PRE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="STREAMING-PAR" +>1.11. Streaming Parameters</A +></H2 +><P +>Streaming parameters are intended to optimize the video +capture process as well as I/O. Presently applications can request a +high quality capture mode with the <A +HREF="#VIDIOC-G-PARM" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_PARM</CODE +></A +> ioctl.</P +><P +>The current video standard determines a nominal number of +frames per second. If less than this number of frames is to be +captured or output, applications can request frame skipping or +duplicating on the driver side. This is espcially useful when using +the <CODE +CLASS="FUNCTION" +>read()</CODE +> or <CODE +CLASS="FUNCTION" +>write()</CODE +>, which +are not augmented by timestamps or sequence counters, and to avoid +uneccessary data copying.</P +><P +>Finally these ioctls can be used to determine the number of +buffers used internally by a driver in read/write mode. For +implications see the section discussing the <A +HREF="#FUNC-READ" +><CODE +CLASS="FUNCTION" +>read()</CODE +></A +> +function.</P +><P +>To get and set the streaming parameters applications call +the <A +HREF="#VIDIOC-G-PARM" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_PARM</CODE +></A +> and <A +HREF="#VIDIOC-G-PARM" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_PARM</CODE +></A +> ioctl, respectively. They take +a pointer to a struct <A +HREF="#V4L2-STREAMPARM" +>v4l2_streamparm</A +>, which contains a union holding +separate parameters for input and output devices.</P +><P +>These ioctls are optional, drivers need not implement +them. If so, they return the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="PIXFMT" +></A +>Chapter 2. Image Formats</H1 +><P +>The V4L2 API was primarily designed for devices exchanging +image data with applications. The +<CODE +CLASS="STRUCTNAME" +>v4l2_pix_format</CODE +> structure defines the format +and layout of an image in memory. Image formats are negotiated with +the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl. (The explanations here focus on video +capturing and output, for overlay frame buffer formats see also +<A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +></A +>.)</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-PIX-FORMAT" +></A +><P +><B +>Table 2-1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_pix_format</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>width</CODE +></TD +><TD +>Image width in pixels.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>height</CODE +></TD +><TD +>Image height in pixels.</TD +></TR +><TR +><TD +COLSPAN="3" +>Applications set these fields to +request an image size, drivers return the closest possible values. In +case of planar formats the <CODE +CLASS="STRUCTFIELD" +>width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>height</CODE +> applies to the largest plane. To +avoid ambiguities drivers must return values rounded up to a multiple +of the scale factor of any smaller planes. For example when the image +format is YUV 4:2:0, <CODE +CLASS="STRUCTFIELD" +>width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>height</CODE +> must be multiples of two.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +></TD +><TD +>The pixel format or type of compression, set by the +application. This is a little endian <A +HREF="#V4L2-FOURCC" +>four character code</A +>. V4L2 defines +standard RGB formats in <A +HREF="#RGB-FORMATS" +>Table 2-3</A +>, YUV formats in <A +HREF="#YUV-FORMATS" +>Section 2.4</A +>, and reserved codes in <A +HREF="#RESERVED-FORMATS" +>Table 2-4</A +></TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>field</CODE +></TD +><TD +>Video images are typically interlaced. Applications +can request to capture or output only the top or bottom field, or both +fields interlaced or sequentially stored in one buffer or alternating +in separate buffers. Drivers return the actual field order selected. +For details see <A +HREF="#FIELD-ORDER" +>Section 3.6</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +></TD +><TD +>Distance in bytes between the leftmost pixels in two +adjacent lines.</TD +></TR +><TR +><TD +COLSPAN="3" +><P +>Both applications and drivers +can set this field to request padding bytes at the end of each line. +Drivers however may ignore the value requested by the application, +returning <CODE +CLASS="STRUCTFIELD" +>width</CODE +> times bytes per pixel or a +larger value required by the hardware. That implies applications can +just set this field to zero to get a reasonable +default.</P +><P +>Video hardware may access padding bytes, +therefore they must reside in accessible memory. Consider cases where +padding bytes after the last line of an image cross a system page +boundary. Input devices may write padding bytes, the value is +undefined. Output devices ignore the contents of padding +bytes.</P +><P +>When the image format is planar the +<CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +> value applies to the largest +plane and is divided by the same factor as the +<CODE +CLASS="STRUCTFIELD" +>width</CODE +> field for any smaller planes. For +example the Cb and Cr planes of a YUV 4:2:0 image have half as many +padding bytes following each line as the Y plane. To avoid ambiguities +drivers must return a <CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +> value +rounded up to a multiple of the scale factor.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>sizeimage</CODE +></TD +><TD +>Size in bytes of the buffer to hold a complete image, +set by the driver. Usually this is +<CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +> times +<CODE +CLASS="STRUCTFIELD" +>height</CODE +>. When the image consists of variable +length compressed data this is the maximum number of bytes required to +hold an image.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-COLORSPACE" +>v4l2_colorspace</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>colorspace</CODE +></TD +><TD +>This information supplements the +<CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +> and must be set by the driver, +see <A +HREF="#COLORSPACES" +>Section 2.2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>priv</CODE +></TD +><TD +>Reserved for custom (driver defined) additional +information about formats. When not used drivers and applications must +set this field to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN880" +>2.1. Standard Image Formats</A +></H2 +><P +>In order to exchange images between drivers and +applications, it is necessary to have standard image data formats +which both sides will interpret the same way. V4L2 includes several +such formats, and this section is intended to be an unambiguous +specification of the standard image data formats in V4L2.</P +><P +>V4L2 drivers are not limited to these formats, however. +Driver-specific formats are possible. In that case the application may +depend on a codec to convert images to one of the standard formats +when needed. But the data can still be stored and retrieved in the +proprietary format. For example, a device may support a proprietary +compressed format. Applications can still capture and save the data in +the compressed format, saving much disk space, and later use a codec +to convert the images to the X Windows screen format when the video is +to be displayed.</P +><P +>Even so, ultimately, some standard formats are needed, so +the V4L2 specification would not be complete without well-defined +standard formats.</P +><P +>The V4L2 standard formats are mainly uncompressed formats. The +pixels are always arranged in memory from left to right, and from top +to bottom. The first byte of data in the image buffer is always for +the leftmost pixel of the topmost row. Following that is the pixel +immediately to its right, and so on until the end of the top row of +pixels. Following the rightmost pixel of the row there may be zero or +more bytes of padding to guarantee that each row of pixel data has a +certain alignment. Following the pad bytes, if any, is data for the +leftmost pixel of the second row from the top, and so on. The last row +has just as many pad bytes after it as the other rows.</P +><P +>In V4L2 each format has an identifier which looks like +<CODE +CLASS="CONSTANT" +>PIX_FMT_XXX</CODE +>, defined in the <A +HREF="#VIDEODEV" +>videodev.h</A +> header file. These identifiers +represent <A +HREF="#V4L2-FOURCC" +>four character codes</A +> +which are also listed below, however they are not the same as those +used in the Windows world.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="COLORSPACES" +>2.2. Colorspaces</A +></H2 +><P +>[intro]</P +><P +> <P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>Gamma Correction</DT +><DD +><P +>[to do]</P +><P +>E'<SUB +>R</SUB +> = f(R)</P +><P +>E'<SUB +>G</SUB +> = f(G)</P +><P +>E'<SUB +>B</SUB +> = f(B)</P +></DD +><DT +>Construction of luminance and color-difference +signals</DT +><DD +><P +>[to do]</P +><P +>E'<SUB +>Y</SUB +> = +Coeff<SUB +>R</SUB +> E'<SUB +>R</SUB +> ++ Coeff<SUB +>G</SUB +> E'<SUB +>G</SUB +> ++ Coeff<SUB +>B</SUB +> E'<SUB +>B</SUB +></P +><P +>(E'<SUB +>R</SUB +> - E'<SUB +>Y</SUB +>) = E'<SUB +>R</SUB +> +- Coeff<SUB +>R</SUB +> E'<SUB +>R</SUB +> +- Coeff<SUB +>G</SUB +> E'<SUB +>G</SUB +> +- Coeff<SUB +>B</SUB +> E'<SUB +>B</SUB +></P +><P +>(E'<SUB +>B</SUB +> - E'<SUB +>Y</SUB +>) = E'<SUB +>B</SUB +> +- Coeff<SUB +>R</SUB +> E'<SUB +>R</SUB +> +- Coeff<SUB +>G</SUB +> E'<SUB +>G</SUB +> +- Coeff<SUB +>B</SUB +> E'<SUB +>B</SUB +></P +></DD +><DT +>Re-normalized color-difference signals</DT +><DD +><P +>The color-difference signals are scaled back to unity +range [-0.5;+0.5]:</P +><P +>K<SUB +>B</SUB +> = 0.5 / (1 - Coeff<SUB +>B</SUB +>)</P +><P +>K<SUB +>R</SUB +> = 0.5 / (1 - Coeff<SUB +>R</SUB +>)</P +><P +>P<SUB +>B</SUB +> = +K<SUB +>B</SUB +> (E'<SUB +>B</SUB +> - E'<SUB +>Y</SUB +>) = + 0.5 (Coeff<SUB +>R</SUB +> / Coeff<SUB +>B</SUB +>) E'<SUB +>R</SUB +> ++ 0.5 (Coeff<SUB +>G</SUB +> / Coeff<SUB +>B</SUB +>) E'<SUB +>G</SUB +> ++ 0.5 E'<SUB +>B</SUB +></P +><P +>P<SUB +>R</SUB +> = +K<SUB +>R</SUB +> (E'<SUB +>R</SUB +> - E'<SUB +>Y</SUB +>) = + 0.5 E'<SUB +>R</SUB +> ++ 0.5 (Coeff<SUB +>G</SUB +> / Coeff<SUB +>R</SUB +>) E'<SUB +>G</SUB +> ++ 0.5 (Coeff<SUB +>B</SUB +> / Coeff<SUB +>R</SUB +>) E'<SUB +>B</SUB +></P +></DD +><DT +>Quantization</DT +><DD +><P +>[to do]</P +><P +>Y' = (Lum. Levels - 1) · E'<SUB +>Y</SUB +> + Lum. Offset</P +><P +>C<SUB +>B</SUB +> = (Chrom. Levels - 1) +· P<SUB +>B</SUB +> + Chrom. Offset</P +><P +>C<SUB +>R</SUB +> = (Chrom. Levels - 1) +· P<SUB +>R</SUB +> + Chrom. Offset</P +><P +>Rounding to the nearest integer and clamping to the range +[0;255] finally yields the digital color components Y'CbCr +stored in YUV images.</P +></DD +></DL +></DIV +> + </P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN984" +></A +><P +><B +>Example 2-1. ITU-R Rec. BT.601 color conversion</B +></P +><P +>Forward Transformation</P +><PRE +CLASS="PROGRAMLISTING" +>int ER, EG, EB; /* gamma corrected RGB input [0;255] */ +int Y1, Cb, Cr; /* output [0;255] */ + +double r, g, b; /* temporaries */ +double y1, pb, pr; + +int +clamp (double x) +{ + int r = x; /* round to nearest */ + + if (r < 0) return 0; + else if (r > 255) return 255; + else return r; +} + +r = ER / 255.0; +g = EG / 255.0; +b = EB / 255.0; + +y1 = 0.299 * r + 0.587 * g + 0.114 * b; +pb = -0.169 * r - 0.331 * g + 0.5 * b; +pr = 0.5 * r - 0.419 * g - 0.081 * b; + +Y1 = clamp (219 * y1 + 16); +Cb = clamp (224 * pb + 128); +Cr = clamp (224 * pr + 128); + +/* or shorter */ + +y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; + +Y1 = clamp ( (219 / 255.0) * y1 + 16); +Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); +Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); + </PRE +><P +>Inverse Transformation</P +><PRE +CLASS="PROGRAMLISTING" +>int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ +int ER, EG, EB; /* output [0;255] */ + +double r, g, b; /* temporaries */ +double y1, pb, pr; + +int +clamp (double x) +{ + int r = x; /* round to nearest */ + + if (r < 0) return 0; + else if (r > 255) return 255; + else return r; +} + +y1 = (255 / 219.0) * (Y1 - 16); +pb = (255 / 224.0) * (Cb - 128); +pr = (255 / 224.0) * (Cr - 128); + +r = 1.0 * y1 + 0 * pb + 1.402 * pr; +g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; +b = 1.0 * y1 + 1.772 * pb + 0 * pr; + +ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ +EG = clamp (g * 255); +EB = clamp (b * 255); + </PRE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-COLORSPACE" +></A +><P +><B +>Table 2-2. enum v4l2_colorspace</B +></P +><TABLE +BORDER="1" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="9%" +ALIGN="LEFT"><COL +WIDTH="9%" +ALIGN="CENTER"><COL +WIDTH="9%" +ALIGN="LEFT"><COL +WIDTH="9%" +TITLE="CR"><COL +WIDTH="9%" +TITLE="CG"><COL +WIDTH="9%" +TITLE="CB"><COL +WIDTH="9%" +TITLE="WP"><COL +WIDTH="9%" +TITLE="GC"><COL +WIDTH="9%" +TITLE="LUM"><COL +WIDTH="9%" +TITLE="QY"><COL +WIDTH="9%" +TITLE="QC"><THEAD +><TR +><TH +ROWSPAN="2" +>Identifier</TH +><TH +ROWSPAN="2" +>Value</TH +><TH +ROWSPAN="2" +>Description</TH +><TH +COLSPAN="3" +>Chromaticities<A +NAME="AEN1013" +HREF="#FTN.AEN1013" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TH +><TH +ROWSPAN="2" +>White Point</TH +><TH +ROWSPAN="2" +>Gamma Correction</TH +><TH +ROWSPAN="2" +>Luminance E'<SUB +>Y</SUB +></TH +><TH +COLSPAN="2" +>Quantization</TH +></TR +><TR +><TH +>Red</TH +><TH +>Green</TH +><TH +>Blue</TH +><TH +>Y'</TH +><TH +>Cb, Cr</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_SMPTE170M</CODE +></TD +><TD +>1</TD +><TD +>NTSC/PAL according to <A +HREF="#SMPTE170M" +><ABBR +CLASS="ABBREV" +>SMPTE170M</ABBR +></A +>, +<A +HREF="#ITU601" +><ABBR +CLASS="ABBREV" +>ITU601</ABBR +></A +></TD +><TD +>x = 0.630, y = 0.340</TD +><TD +>x = 0.310, y = 0.595</TD +><TD +>x = 0.155, y = 0.070</TD +><TD +>x = 0.3127, y = 0.3290, + Illuminant D<SUB +>65</SUB +></TD +><TD +>E' = 4.5 I for I ≤0.018, +1.099 I<SUP +>0.45</SUP +> - 0.099 for 0.018 < I</TD +><TD +>0.299 E'<SUB +>R</SUB +> ++ 0.587 E'<SUB +>G</SUB +> ++ 0.114 E'<SUB +>B</SUB +></TD +><TD +>219 E'<SUB +>Y</SUB +> + 16</TD +><TD +>224 P<SUB +>B,R</SUB +> + 128</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_SMPTE240M</CODE +></TD +><TD +>2</TD +><TD +>1125-Line (US) HDTV, see <A +HREF="#SMPTE240M" +><ABBR +CLASS="ABBREV" +>SMPTE240M</ABBR +></A +></TD +><TD +>x = 0.630, y = 0.340</TD +><TD +>x = 0.310, y = 0.595</TD +><TD +>x = 0.155, y = 0.070</TD +><TD +>x = 0.3127, y = 0.3290, + Illuminant D<SUB +>65</SUB +></TD +><TD +>E' = 4 I for I ≤0.0228, +1.1115 I<SUP +>0.45</SUP +> - 0.1115 for 0.0228 < I</TD +><TD +>0.212 E'<SUB +>R</SUB +> ++ 0.701 E'<SUB +>G</SUB +> ++ 0.087 E'<SUB +>B</SUB +></TD +><TD +>219 E'<SUB +>Y</SUB +> + 16</TD +><TD +>224 P<SUB +>B,R</SUB +> + 128</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_REC709</CODE +></TD +><TD +>3</TD +><TD +>HDTV and modern devices, see <A +HREF="#ITU709" +><ABBR +CLASS="ABBREV" +>ITU709</ABBR +></A +></TD +><TD +>x = 0.640, y = 0.330</TD +><TD +>x = 0.300, y = 0.600</TD +><TD +>x = 0.150, y = 0.060</TD +><TD +>x = 0.3127, y = 0.3290, + Illuminant D<SUB +>65</SUB +></TD +><TD +>E' = 4.5 I for I ≤0.018, +1.099 I<SUP +>0.45</SUP +> - 0.099 for 0.018 < I</TD +><TD +>0.2125 E'<SUB +>R</SUB +> ++ 0.7154 E'<SUB +>G</SUB +> ++ 0.0721 E'<SUB +>B</SUB +></TD +><TD +>219 E'<SUB +>Y</SUB +> + 16</TD +><TD +>224 P<SUB +>B,R</SUB +> + 128</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_BT878</CODE +></TD +><TD +>4</TD +><TD +>Broken Bt878 extents<A +NAME="AEN1096" +HREF="#FTN.AEN1096" +><SPAN +CLASS="footnote" +>[b]</SPAN +></A +>, <A +HREF="#ITU601" +><ABBR +CLASS="ABBREV" +>ITU601</ABBR +></A +></TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>0.299 E'<SUB +>R</SUB +> ++ 0.587 E'<SUB +>G</SUB +> ++ 0.114 E'<SUB +>B</SUB +></TD +><TD +><SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>237</I +></SPAN +> E'<SUB +>Y</SUB +> + 16</TD +><TD +>224 P<SUB +>B,R</SUB +> + 128 (probably)</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_470_SYSTEM_M</CODE +></TD +><TD +>5</TD +><TD +>M/NTSC<A +NAME="AEN1119" +HREF="#FTN.AEN1119" +><SPAN +CLASS="footnote" +>[c]</SPAN +></A +> according to <A +HREF="#ITU470" +><ABBR +CLASS="ABBREV" +>ITU470</ABBR +></A +>, <A +HREF="#ITU601" +><ABBR +CLASS="ABBREV" +>ITU601</ABBR +></A +></TD +><TD +>x = 0.67, y = 0.33</TD +><TD +>x = 0.21, y = 0.71</TD +><TD +>x = 0.14, y = 0.08</TD +><TD +>x = 0.310, y = 0.316, Illuminant C</TD +><TD +>?</TD +><TD +>0.299 E'<SUB +>R</SUB +> ++ 0.587 E'<SUB +>G</SUB +> ++ 0.114 E'<SUB +>B</SUB +></TD +><TD +>219 E'<SUB +>Y</SUB +> + 16</TD +><TD +>224 P<SUB +>B,R</SUB +> + 128</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_470_SYSTEM_BG</CODE +></TD +><TD +>6</TD +><TD +>625-line PAL and SECAM systems according to <A +HREF="#ITU470" +><ABBR +CLASS="ABBREV" +>ITU470</ABBR +></A +>, <A +HREF="#ITU601" +><ABBR +CLASS="ABBREV" +>ITU601</ABBR +></A +></TD +><TD +>x = 0.64, y = 0.33</TD +><TD +>x = 0.29, y = 0.60</TD +><TD +>x = 0.15, y = 0.06</TD +><TD +>x = 0.313, y = 0.329, +Illuminant D<SUB +>65</SUB +></TD +><TD +>?</TD +><TD +>0.299 E'<SUB +>R</SUB +> ++ 0.587 E'<SUB +>G</SUB +> ++ 0.114 E'<SUB +>B</SUB +></TD +><TD +>219 E'<SUB +>Y</SUB +> + 16</TD +><TD +>224 P<SUB +>B,R</SUB +> + 128</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_JPEG</CODE +></TD +><TD +>7</TD +><TD +>JPEG Y'CbCr, see <A +HREF="#JFIF" +><ABBR +CLASS="ABBREV" +>JFIF</ABBR +></A +>, <A +HREF="#ITU601" +><ABBR +CLASS="ABBREV" +>ITU601</ABBR +></A +></TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>0.299 E'<SUB +>R</SUB +> ++ 0.587 E'<SUB +>G</SUB +> ++ 0.114 E'<SUB +>B</SUB +></TD +><TD +>256 E'<SUB +>Y</SUB +> + 16<A +NAME="AEN1175" +HREF="#FTN.AEN1175" +><SPAN +CLASS="footnote" +>[d]</SPAN +></A +></TD +><TD +>256 P<SUB +>B,R</SUB +> + 128</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_SRGB</CODE +></TD +><TD +>8</TD +><TD +>[?]</TD +><TD +>x = 0.640, y = 0.330</TD +><TD +>x = 0.300, y = 0.600</TD +><TD +>x = 0.150, y = 0.060</TD +><TD +>x = 0.3127, y = 0.3290, + Illuminant D<SUB +>65</SUB +></TD +><TD +>E' = 4.5 I for I ≤0.018, +1.099 I<SUP +>0.45</SUP +> - 0.099 for 0.018 < I</TD +><TD +COLSPAN="3" +>n/a</TD +></TR +></TBODY +><TR +><TD +COLSPAN="11" +>Notes:<BR><A +NAME="FTN.AEN1013" +>a. </A +>The coordinates of the color primaries are +given in the CIE system (1931)<BR><A +NAME="FTN.AEN1096" +>b. </A +>The ubiquitous Bt878 video capture chip +quantizes E'<SUB +>Y</SUB +> to 238 levels, yielding a range +of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … +235. This is not a typo in the Bt878 documentation, it has been +implemented in silicon. The chroma extents are unclear.<BR><A +NAME="FTN.AEN1119" +>c. </A +>No identifier exists for M/PAL which uses +the chromaticities of M/NTSC, the remaining parameters are equal to B and +G/PAL.<BR><A +NAME="FTN.AEN1175" +>d. </A +>Note JFIF quantizes +Y'P<SUB +>B</SUB +>P<SUB +>R</SUB +> in range [0;+1] and +[-0.5;+0.5] to <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>257</I +></SPAN +> levels, however Y'CbCr signals +are still clamped to [0;255].<BR></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="PIXFMT-RGB" +>2.3. RGB Formats</A +></H2 +><P +>These formats are designed to match the pixel formats of +typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits +per pixel. These are all packed-pixel formats, meaning all the data +for a pixel lie next to each other in memory.</P +><P +>When one of these formats is used, drivers shall report the +colorspace <CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_SRGB</CODE +>.</P +><DIV +CLASS="TABLE" +><A +NAME="RGB-FORMATS" +></A +><P +><B +>Table 2-3. Packed RGB Image Formats</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="9%" +ALIGN="LEFT" +TITLE="ID"><COL +WIDTH="9%" +TITLE="FOURCC"><COL +WIDTH="9%" +TITLE="BIT"><COL +WIDTH="9%" +TITLE="B07"><COL><COL><COL><COL><COL><COL><COL +WIDTH="9%" +TITLE="B00"><COL><COL +WIDTH="9%" +TITLE="B17"><COL><COL><COL><COL><COL><COL><COL +WIDTH="9%" +TITLE="B10"><COL><COL +WIDTH="9%" +TITLE="B27"><COL><COL><COL><COL><COL><COL><COL +WIDTH="9%" +TITLE="B20"><COL><COL +WIDTH="9%" +TITLE="B37"><COL><COL><COL><COL><COL><COL><THEAD +><TR +><TH +ROWSPAN="2" +>Identifier</TH +><TH +ROWSPAN="2" +>Code</TH +><TH +> </TH +><TH +COLSPAN="8" +>Byte 0</TH +><TH +> </TH +><TH +COLSPAN="8" +>Byte 1</TH +><TH +> </TH +><TH +COLSPAN="8" +>Byte 2</TH +><TH +> </TH +><TH +COLSPAN="8" +>Byte 3</TH +></TR +><TR +><TH +>Bit</TH +><TH +>7</TH +><TH +>6</TH +><TH +>5</TH +><TH +>4</TH +><TH +>3</TH +><TH +>2</TH +><TH +>1</TH +><TH +>0</TH +><TH +> </TH +><TH +>7</TH +><TH +>6</TH +><TH +>5</TH +><TH +>4</TH +><TH +>3</TH +><TH +>2</TH +><TH +>1</TH +><TH +>0</TH +><TH +> </TH +><TH +>7</TH +><TH +>6</TH +><TH +>5</TH +><TH +>4</TH +><TH +>3</TH +><TH +>2</TH +><TH +>1</TH +><TH +>0</TH +><TH +> </TH +><TH +>7</TH +><TH +>6</TH +><TH +>5</TH +><TH +>4</TH +><TH +>3</TH +><TH +>2</TH +><TH +>1</TH +><TH +>0</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB332</CODE +></TD +><TD +>'RGB1'</TD +><TD +> </TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB555</CODE +></TD +><TD +>'RGBO'</TD +><TD +> </TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>?</TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB565</CODE +></TD +><TD +>'RGBP'</TD +><TD +> </TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +>g<SUB +>5</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB555X</CODE +></TD +><TD +>'RGBQ'</TD +><TD +> </TD +><TD +>?</TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +> </TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB565X</CODE +></TD +><TD +>'RGBR'</TD +><TD +> </TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +>g<SUB +>5</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +> </TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR24</CODE +></TD +><TD +>'BGR3'</TD +><TD +> </TD +><TD +>b<SUB +>7</SUB +></TD +><TD +>b<SUB +>6</SUB +></TD +><TD +>b<SUB +>5</SUB +></TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>g<SUB +>7</SUB +></TD +><TD +>g<SUB +>6</SUB +></TD +><TD +>g<SUB +>5</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>r<SUB +>7</SUB +></TD +><TD +>r<SUB +>6</SUB +></TD +><TD +>r<SUB +>5</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB24</CODE +></TD +><TD +>'RGB3'</TD +><TD +> </TD +><TD +>r<SUB +>7</SUB +></TD +><TD +>r<SUB +>6</SUB +></TD +><TD +>r<SUB +>5</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>g<SUB +>7</SUB +></TD +><TD +>g<SUB +>6</SUB +></TD +><TD +>g<SUB +>5</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>b<SUB +>7</SUB +></TD +><TD +>b<SUB +>6</SUB +></TD +><TD +>b<SUB +>5</SUB +></TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR32</CODE +></TD +><TD +>'BGR4'</TD +><TD +> </TD +><TD +>b<SUB +>7</SUB +></TD +><TD +>b<SUB +>6</SUB +></TD +><TD +>b<SUB +>5</SUB +></TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>g<SUB +>7</SUB +></TD +><TD +>g<SUB +>6</SUB +></TD +><TD +>g<SUB +>5</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>r<SUB +>7</SUB +></TD +><TD +>r<SUB +>6</SUB +></TD +><TD +>r<SUB +>5</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB32</CODE +></TD +><TD +>'RGB4'</TD +><TD +> </TD +><TD +>r<SUB +>7</SUB +></TD +><TD +>r<SUB +>6</SUB +></TD +><TD +>r<SUB +>5</SUB +></TD +><TD +>r<SUB +>4</SUB +></TD +><TD +>r<SUB +>3</SUB +></TD +><TD +>r<SUB +>2</SUB +></TD +><TD +>r<SUB +>1</SUB +></TD +><TD +>r<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>g<SUB +>7</SUB +></TD +><TD +>g<SUB +>6</SUB +></TD +><TD +>g<SUB +>5</SUB +></TD +><TD +>g<SUB +>4</SUB +></TD +><TD +>g<SUB +>3</SUB +></TD +><TD +>g<SUB +>2</SUB +></TD +><TD +>g<SUB +>1</SUB +></TD +><TD +>g<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>b<SUB +>7</SUB +></TD +><TD +>b<SUB +>6</SUB +></TD +><TD +>b<SUB +>5</SUB +></TD +><TD +>b<SUB +>4</SUB +></TD +><TD +>b<SUB +>3</SUB +></TD +><TD +>b<SUB +>2</SUB +></TD +><TD +>b<SUB +>1</SUB +></TD +><TD +>b<SUB +>0</SUB +></TD +><TD +> </TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +><TD +>?</TD +></TR +></TBODY +></TABLE +></DIV +><P +>Bit 7 is the most significant bit. ? = undefined bit, +ignored on output, random value on input.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN1675" +></A +><P +><B +>Example 2-2. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR24</CODE +> 4 × 4 pixel +image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN1681" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>B<SUB +>00</SUB +></TD +><TD +>G<SUB +>00</SUB +></TD +><TD +>R<SUB +>00</SUB +></TD +><TD +>B<SUB +>01</SUB +></TD +><TD +>G<SUB +>01</SUB +></TD +><TD +>R<SUB +>01</SUB +></TD +><TD +>B<SUB +>02</SUB +></TD +><TD +>G<SUB +>02</SUB +></TD +><TD +>R<SUB +>02</SUB +></TD +><TD +>B<SUB +>03</SUB +></TD +><TD +>G<SUB +>03</SUB +></TD +><TD +>R<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>B<SUB +>10</SUB +></TD +><TD +>G<SUB +>10</SUB +></TD +><TD +>R<SUB +>10</SUB +></TD +><TD +>B<SUB +>11</SUB +></TD +><TD +>G<SUB +>11</SUB +></TD +><TD +>R<SUB +>11</SUB +></TD +><TD +>B<SUB +>12</SUB +></TD +><TD +>G<SUB +>12</SUB +></TD +><TD +>R<SUB +>12</SUB +></TD +><TD +>B<SUB +>13</SUB +></TD +><TD +>G<SUB +>13</SUB +></TD +><TD +>R<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 24:</TD +><TD +>B<SUB +>20</SUB +></TD +><TD +>G<SUB +>20</SUB +></TD +><TD +>R<SUB +>20</SUB +></TD +><TD +>B<SUB +>21</SUB +></TD +><TD +>G<SUB +>21</SUB +></TD +><TD +>R<SUB +>21</SUB +></TD +><TD +>B<SUB +>22</SUB +></TD +><TD +>G<SUB +>22</SUB +></TD +><TD +>R<SUB +>22</SUB +></TD +><TD +>B<SUB +>23</SUB +></TD +><TD +>G<SUB +>23</SUB +></TD +><TD +>R<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 36:</TD +><TD +>B<SUB +>30</SUB +></TD +><TD +>G<SUB +>30</SUB +></TD +><TD +>R<SUB +>30</SUB +></TD +><TD +>B<SUB +>31</SUB +></TD +><TD +>G<SUB +>31</SUB +></TD +><TD +>R<SUB +>31</SUB +></TD +><TD +>B<SUB +>32</SUB +></TD +><TD +>G<SUB +>32</SUB +></TD +><TD +>R<SUB +>32</SUB +></TD +><TD +>B<SUB +>33</SUB +></TD +><TD +>G<SUB +>33</SUB +></TD +><TD +>R<SUB +>33</SUB +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +><DIV +CLASS="IMPORTANT" +><BLOCKQUOTE +CLASS="IMPORTANT" +><P +><B +>Important: </B +>Drivers may interpret these formats differently.</P +><P +>The <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB555</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB565</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB555X</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB565X</CODE +> formats are uncommon. Video +and display hardware typically supports variants with reversed order +of color components, i. e. blue towards the least, red towards the most +significant bit. Although presumably the original authors had the +common formats in mind, the definitions were always very clear and +cannot be simply regarded as erroneous.</P +><P +>If <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB332</CODE +> has been +chosen in accordance with the 15 and 16 bit formats, this format might +as well be interpreted differently, as "rrrgggbb" rather than +"bbgggrrr".</P +><P +>Finally some drivers, most prominently the BTTV driver, +might interpret <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB32</CODE +> as the +big-endian variant of <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR32</CODE +>, +consisting of bytes "?RGB" in memory. V4L2 never defined such a +format, lack of a <CODE +CLASS="CONSTANT" +>X</CODE +> suffix to the symbol suggests +it was intended this way, and a new symbol and four character code +should have been used instead.</P +><P +>Until these issues are solved, application writers are +advised that drivers might interpret these formats either way.</P +></BLOCKQUOTE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="YUV-FORMATS" +>2.4. YUV Formats</A +></H2 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="#PIXFMT-GREY" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +></A +> -- Grey-scale image.</DT +><DT +><A +HREF="#PIXFMT-YUYV" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +></A +> -- Packed format with ½ horizontal chroma +resolution, also known as YUV 4:2:2.</DT +><DT +><A +HREF="#PIXFMT-UYVY" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +></A +> -- Variation of +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +> with different order of samples +in memory.</DT +><DT +><A +HREF="#PIXFMT-Y41P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +></A +> -- Packed format with ¼ horizontal chroma +resolution, also known as YUV 4:1:1.</DT +><DT +><A +HREF="#PIXFMT-YVU420" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV420</CODE +></A +> -- Planar formats with ½ horizontal and +vertical chroma resolution, also known as YUV 4:2:0.</DT +><DT +><A +HREF="#PIXFMT-YVU410" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV410</CODE +></A +> -- Planar formats with ¼ horizontal and +vertical chroma resolution, also known as YUV 4:1:0.</DT +><DT +><A +HREF="#PIXFMT-YUV422P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +></A +> -- Format with ½ horizontal chroma resolution, +also known as YUV 4:2:2. Planar layout as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +>.</DT +><DT +><A +HREF="#PIXFMT-YUV411P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +></A +> -- Format with ¼ horizontal chroma resolution, +also known as YUV 4:1:1. Planar layout as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +>.</DT +><DT +><A +HREF="#AEN3002" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV21</CODE +></A +> -- Formats with ½ horizontal and vertical +chroma resolution, also known as YUV 4:2:0. One luminance and one +chrominance plane with alternating chroma samples as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>.</DT +></DL +></DIV +><P +>YUV is the format native to TV broadcast and composite video +signals. It separates the brightness information (Y) from the color +information (U and V or Cb and Cr). The color information consists of +red and blue <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>color difference</I +></SPAN +> signals, this way +the green component can be reconstructed by subtracting from the +brightness component. See <A +HREF="#COLORSPACES" +>Section 2.2</A +> for conversion +examples. YUV was chosen because early television would only transmit +brightness information. To add color in a way compatible with existing +receivers a new signal carrier was added to transmit the color +difference signals. Secondary in the YUV format the U and V components +usually have lower resolution than the Y component. This is an analog +video compression technique taking advantage of a property of the +human visual system, being more sensitive to brightness +information.</P +><H1 +><A +NAME="PIXFMT-GREY" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN1812" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +> ('GREY') -- Grey-scale image.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN1816" +></A +><H2 +>Description</H2 +><P +>This is a grey-scale image. It is really a degenerate +Y'CbCr format which simply contains no Cb or Cr data.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN1819" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN1825" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 4:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-YUYV" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN1873" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +> +('YUYV') -- Packed format with ½ horizontal chroma +resolution, also known as YUV 4:2:2.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN1877" +></A +><H2 +>Description</H2 +><P +>In this format each four bytes is two pixels. Each four +bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and +the Cb and Cr belong to both pixels. As you can see, the Cr and Cb +components have half the horizontal resolution of the Y component. +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV </CODE +> is known in the Windows +environment as YUY2.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN1881" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN1887" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Cb<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +><TD +>Cr<SUB +>01</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Cb<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +><TD +>Cr<SUB +>11</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Cb<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Cr<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Cb<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +><TD +>Cr<SUB +>21</SUB +></TD +></TR +><TR +><TD +>start + 24:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Cb<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Cr<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Cb<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +><TD +>Cr<SUB +>31</SUB +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN1966" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-UYVY" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN2018" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +> +('UYVY') -- Variation of +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +> with different order of samples +in memory.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN2023" +></A +><H2 +>Description</H2 +><P +>In this format each four bytes is two pixels. Each four +bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and +the Cb and Cr belong to both pixels. As you can see, the Cr and Cb +components have half the horizontal resolution of the Y +component.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN2026" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2032" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Cb<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Cr<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Cb<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Cr<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Cb<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Cr<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Cb<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Cr<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 24:</TD +><TD +>Cb<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Cr<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Cb<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Cr<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2111" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-Y41P" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN2163" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +> +('Y41P') -- Packed format with ¼ horizontal chroma +resolution, also known as YUV 4:1:1.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN2167" +></A +><H2 +>Description</H2 +><P +>In this format each 12 bytes is eight pixels. In the +twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair +goes with the first four Y's, and the second CbCr pair goes with the +other four Y's. The Cb and Cr components have one fourth the +horizontal resolution of the Y component.</P +><P +>Do not confuse this format with <A +HREF="#PIXFMT-YUV411P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +></A +>. +Y41P is derived from "YUV 4:1:1 <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>packed</I +></SPAN +>", possibly +in reference to a Windows FOURCC, while YUV411P stands for "YUV 4:1:1 +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>planar</I +></SPAN +>".</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN2175" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +> 8 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2181" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Cb<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Cr<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +><TD +>Y'<SUB +>04</SUB +></TD +><TD +>Y'<SUB +>05</SUB +></TD +><TD +>Y'<SUB +>06</SUB +></TD +><TD +>Y'<SUB +>07</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Cb<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Cr<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +><TD +>Y'<SUB +>14</SUB +></TD +><TD +>Y'<SUB +>15</SUB +></TD +><TD +>Y'<SUB +>16</SUB +></TD +><TD +>Y'<SUB +>17</SUB +></TD +></TR +><TR +><TD +>start + 24:</TD +><TD +>Cb<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Cr<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Cb<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Cr<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +><TD +>Y'<SUB +>24</SUB +></TD +><TD +>Y'<SUB +>25</SUB +></TD +><TD +>Y'<SUB +>26</SUB +></TD +><TD +>Y'<SUB +>27</SUB +></TD +></TR +><TR +><TD +>start + 36:</TD +><TD +>Cb<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Cr<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Cb<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Cr<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +><TD +>Y'<SUB +>34</SUB +></TD +><TD +>Y'<SUB +>35</SUB +></TD +><TD +>Y'<SUB +>36</SUB +></TD +><TD +>Y'<SUB +>37</SUB +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2292" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +><TD +> </TD +><TD +>4</TD +><TD +> </TD +><TD +>5</TD +><TD +> </TD +><TD +>6</TD +><TD +> </TD +><TD +>7</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-YVU420" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV420</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN2385" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +> +('YV12'), <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV420</CODE +> +('YU12') -- Planar formats with ½ horizontal and +vertical chroma resolution, also known as YUV 4:2:0.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN2391" +></A +><H2 +>Description</H2 +><P +>These are planar formats, as opposed to a packed format. +The three components are separated into three sub- images or planes. +The Y plane is first. The Y plane has one byte per pixel. For +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>, the Cr plane immediately +follows the Y plane in memory. The Cr plane is half the width and half +the height of the Y plane (and of the image). Each Cr belongs to four +pixels, a two-by-two square of the image. For example, +Cr<SUB +>0</SUB +> belongs to Y'<SUB +>00</SUB +>, +Y'<SUB +>01</SUB +>, Y'<SUB +>10</SUB +>, and +Y'<SUB +>11</SUB +>. Following the Cr plane is the Cb plane, +just like the Cr plane. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV420</CODE +> is +the same except the Cb plane comes first, then the Cr plane.</P +><P +>If the Y plane has pad bytes after each row, then the Cr +and Cb planes have half as many pad bytes after their rows. In other +words, two Cx rows (including padding) is exactly as long as one Y row +(including padding).</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN2402" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2408" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 4:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +>Cr<SUB +>01</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 18:</TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +>Cr<SUB +>11</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 20:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +>Cb<SUB +>01</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 22:</TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +>Cb<SUB +>11</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2479" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-YVU410" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV410</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN2552" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +> +('YVU9'), <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV410</CODE +> +('YUV9') -- Planar formats with ¼ horizontal and +vertical chroma resolution, also known as YUV 4:1:0.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN2558" +></A +><H2 +>Description</H2 +><P +>These are planar formats, as opposed to a packed format. +The three components are separated into three sub-images or planes. +The Y plane is first. The Y plane has one byte per pixel. For +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +>, the Cr plane immediately +follows the Y plane in memory. The Cr plane is ¼ the width and +¼ the height of the Y plane (and of the image). Each Cr belongs +to 16 pixels, a four-by-four square of the image. Following the Cr +plane is the Cb plane, just like the Cr plane. +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV410</CODE +> is the same, except the Cb +plane comes first, then the Cr plane.</P +><P +>If the Y plane has pad bytes after each row, then the Cr +and Cb planes have ¼ as many pad bytes after their rows. In +other words, four Cx rows (including padding) are exactly as long as +one Y row (including padding).</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN2564" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2570" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 4:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 17:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2625" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-YUV422P" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN2690" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +> +('422P') -- Format with ½ horizontal chroma resolution, +also known as YUV 4:2:2. Planar layout as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +>.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN2695" +></A +><H2 +>Description</H2 +><P +>This format is not commonly used. This is a planar +version of the YUYV format. The three components are separated into +three sub-images or planes. The Y plane is first. The Y plane has one +byte per pixel. The Cb plane immediately follows the Y plane in +memory. The Cb plane is half the width of the Y plane (and of the +image). Each Cb belongs to two pixels. For example, +Cb<SUB +>0</SUB +> belongs to Y'<SUB +>00</SUB +>, +Y'<SUB +>01</SUB +>. Following the Cb plane is the Cr plane, +just like the Cb plane.</P +><P +>If the Y plane has pad bytes after each row, then the Cr +and Cb planes have half as many pad bytes after their rows. In other +words, two Cx rows (including padding) is exactly as long as one Y row +(including padding).</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN2702" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2708" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 4:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +>Cb<SUB +>01</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 18:</TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +>Cb<SUB +>11</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 20:</TD +><TD +>Cb<SUB +>20</SUB +></TD +><TD +>Cb<SUB +>21</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 22:</TD +><TD +>Cb<SUB +>30</SUB +></TD +><TD +>Cb<SUB +>31</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 24:</TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +>Cr<SUB +>01</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 26:</TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +>Cr<SUB +>11</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 28:</TD +><TD +>Cr<SUB +>20</SUB +></TD +><TD +>Cr<SUB +>21</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 30:</TD +><TD +>Cr<SUB +>30</SUB +></TD +><TD +>Cr<SUB +>31</SUB +></TD +><TD +> </TD +><TD +> </TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2803" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="PIXFMT-YUV411P" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN2855" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +> +('411P') -- Format with ¼ horizontal chroma resolution, +also known as YUV 4:1:1. Planar layout as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +>.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN2860" +></A +><H2 +>Description</H2 +><P +>This format is not commonly used. This is a planar +format similar to the 4:2:2 planar format except with half as many +chroma. The three components are separated into three sub-images or +planes. The Y plane is first. The Y plane has one byte per pixel. The +Cb plane immediately follows the Y plane in memory. The Cb plane is +¼ the width of the Y plane (and of the image). Each Cb belongs +to 4 pixels all on the same row. For example, +Cb<SUB +>0</SUB +> belongs to Y'<SUB +>00</SUB +>, +Y'<SUB +>01</SUB +>, Y'<SUB +>02</SUB +> and +Y'<SUB +>03</SUB +>. Following the Cb plane is the Cr plane, +just like the Cb plane.</P +><P +>If the Y plane has pad bytes after each row, then the Cr +and Cb planes have ¼ as many pad bytes after their rows. In +other words, four C x rows (including padding) is exactly as long as +one Y row (including padding).</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN2869" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2875" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 4:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 17:</TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 18:</TD +><TD +>Cb<SUB +>20</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 19:</TD +><TD +>Cb<SUB +>30</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 20:</TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 21:</TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 22:</TD +><TD +>Cr<SUB +>20</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>start + 23:</TD +><TD +>Cr<SUB +>30</SUB +></TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN2954" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +>C</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +><H1 +><A +NAME="AEN3002" +></A +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV21</CODE +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN3007" +></A +><H2 +>Name</H2 +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +> +('NV12'), <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV21</CODE +> +('NV21') -- Formats with ½ horizontal and vertical +chroma resolution, also known as YUV 4:2:0. One luminance and one +chrominance plane with alternating chroma samples as opposed to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +>.</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN3014" +></A +><H2 +>Description</H2 +><P +>These are two-plane versions of the YUV 4:2:0 format. +The three components are separated into two sub-images or planes. The +Y plane is first. The Y plane has one byte per pixel. For +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +>, a combined CbCr plane +immediately follows the Y plane in memory. The CbCr plane is the same +width, in bytes, as the Y plane (and of the image), but is half as +tall in pixels. Each CbCr pair belongs to four pixels. For example, +Cb<SUB +>0</SUB +>/Cr<SUB +>0</SUB +> belongs to +Y'<SUB +>00</SUB +>, Y'<SUB +>01</SUB +>, +Y'<SUB +>10</SUB +>, Y'<SUB +>11</SUB +>. +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV21</CODE +> is the same except the Cb and +Cr bytes are swapped, the CrCb plane starts with a Cr byte.</P +><P +>If the Y plane has pad bytes after each row, then the +CbCr plane has as many pad bytes after its rows.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN3026" +></A +><P +><B +>Example 2-1. <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_NV12</CODE +> 4 × 4 +pixel image</B +></P +><DIV +CLASS="FORMALPARA" +><P +><B +>Byte Order. </B +>Each cell is one byte. + <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN3032" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL +WIDTH="2*" +ALIGN="LEFT"><COL><COL><COL><COL><TBODY +><TR +><TD +>start + 0:</TD +><TD +>Y'<SUB +>00</SUB +></TD +><TD +>Y'<SUB +>01</SUB +></TD +><TD +>Y'<SUB +>02</SUB +></TD +><TD +>Y'<SUB +>03</SUB +></TD +></TR +><TR +><TD +>start + 4:</TD +><TD +>Y'<SUB +>10</SUB +></TD +><TD +>Y'<SUB +>11</SUB +></TD +><TD +>Y'<SUB +>12</SUB +></TD +><TD +>Y'<SUB +>13</SUB +></TD +></TR +><TR +><TD +>start + 8:</TD +><TD +>Y'<SUB +>20</SUB +></TD +><TD +>Y'<SUB +>21</SUB +></TD +><TD +>Y'<SUB +>22</SUB +></TD +><TD +>Y'<SUB +>23</SUB +></TD +></TR +><TR +><TD +>start + 12:</TD +><TD +>Y'<SUB +>30</SUB +></TD +><TD +>Y'<SUB +>31</SUB +></TD +><TD +>Y'<SUB +>32</SUB +></TD +><TD +>Y'<SUB +>33</SUB +></TD +></TR +><TR +><TD +>start + 16:</TD +><TD +>Cb<SUB +>00</SUB +></TD +><TD +>Cr<SUB +>00</SUB +></TD +><TD +>Cb<SUB +>01</SUB +></TD +><TD +>Cr<SUB +>01</SUB +></TD +></TR +><TR +><TD +>start + 20:</TD +><TD +>Cb<SUB +>10</SUB +></TD +><TD +>Cr<SUB +>10</SUB +></TD +><TD +>Cb<SUB +>11</SUB +></TD +><TD +>Cr<SUB +>11</SUB +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="FORMALPARA" +><P +><B +>Color Sample Location. </B +> <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN3099" +></A +><TABLE +BORDER="0" +FRAME="void" +CLASS="CALSTABLE" +><COL><COL><COL><COL><COL><COL><COL><TBODY +><TR +><TD +> </TD +><TD +>0</TD +><TD +> </TD +><TD +>1</TD +><TD +> </TD +><TD +>2</TD +><TD +> </TD +><TD +>3</TD +></TR +><TR +><TD +>0</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +></TR +><TR +><TD +>1</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +>2</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +><TR +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +><TD +> </TD +><TD +> </TD +><TD +>C</TD +><TD +> </TD +></TR +><TR +><TD +>3</TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +><TD +> </TD +><TD +>Y</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> + </P +></DIV +></DIV +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN3167" +>2.5. Compressed Formats</A +></H2 +><P +>[to do, see also <A +HREF="#VIDIOC-G-COMP" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_COMP</CODE +></A +>, <A +HREF="#VIDIOC-G-COMP" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_COMP</CODE +></A +>, +<A +HREF="#VIDIOC-G-JPEGCOMP" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_JPEGCOMP</CODE +></A +>, <A +HREF="#VIDIOC-G-JPEGCOMP" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_JPEGCOMP</CODE +></A +>. The only compressed standard +format should be [M]JPEG.]</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="PIXFMT-RESERVED" +>2.6. Reserved Format Identifiers</A +></H2 +><P +>These formats are not defined by this specification, they +are just listed for reference and to avoid naming conflicts. If you +want to register your own format, send an e-mail to V4L2 maintainer +Gerd Knorr <A +HREF="http://bytesex.org/" +TARGET="_top" +>http://bytesex.org/</A +> +for inclusion in the <TT +CLASS="FILENAME" +>videodev.h</TT +> file. If you want +to share your format with other developers add a link to your +documentation and send a copy to the maintainer of this document, +Michael Schimek <CODE +CLASS="EMAIL" +><<A +HREF="mailto:mschimek@gmx.at" +>mschimek@gmx.at</A +>></CODE +>, for inclusion in this +section. If you think your format should be listed in a standard +format section please make a proposal on the V4L mailing list: +<A +HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" +TARGET="_top" +>https://listman.redhat.com/mailman/listinfo/video4linux-list</A +>.</P +><DIV +CLASS="TABLE" +><A +NAME="RESERVED-FORMATS" +></A +><P +><B +>Table 2-4. Reserved Image Formats</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><THEAD +><TR +><TH +>Identifier</TH +><TH +>Code</TH +><TH +>Details</TH +></TR +></THEAD +><TBODY +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YYUV</CODE +> + </TD +><TD +>'YYUV'</TD +><TD +>unknown</TD +></TR +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_HI240</CODE +> + </TD +><TD +>'HI24'</TD +><TD +> Used by the BTTV driver, <A +HREF="http://bytesex.org/bttv/" +TARGET="_top" +>http://bytesex.org/bttv/</A +> + </TD +></TR +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_MJPEG</CODE +> + </TD +><TD +>'MJPG'</TD +><TD +>Used by the Zoran driver</TD +></TR +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_JPEG</CODE +> + </TD +><TD +>'JPEG'</TD +><TD +>unknown [?]</TD +></TR +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_DV</CODE +> + </TD +><TD +>'dvsd'</TD +><TD +>unknown</TD +></TR +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_MPEG</CODE +> + </TD +><TD +>'MPEG'</TD +><TD +>unknown</TD +></TR +><TR +><TD +> <CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_WNVA</CODE +> + </TD +><TD +>'WNVA'</TD +><TD +> Used by the Winnov Videum driver, <A +HREF="http://www.thedirks.org/winnov/" +TARGET="_top" +>http://www.thedirks.org/winnov/</A +> + </TD +></TR +></TBODY +></TABLE +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="IO" +></A +>Chapter 3. Input/Output</H1 +><P +>The V4L2 API defines several different methods to read from or +write to a device. All drivers exchanging data with applications must +support at least one of them.</P +><P +>The classic I/O method using the <CODE +CLASS="FUNCTION" +>read()</CODE +> +and <CODE +CLASS="FUNCTION" +>write()</CODE +> function is automatically selected +after opening a V4L2 device. When the driver does not support this +method attempts to read or write will fail at any time.</P +><P +>Other methods must be negotiated. To select the streaming I/O +method with memory mapped or user buffers applications call the +<A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl. The asynchronous I/O method is not defined +yet.</P +><P +>Video overlay can be considered another I/O method, although +the application does not directly receive the image data. It is +selected by initiating video overlay with the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl. +For more information see <A +HREF="#OVERLAY" +>Section 4.2</A +>.</P +><P +>Generally exactly one I/O method, including overlay, is +associated with each file descriptor. The only exceptions are +applications not exchanging data with a driver ("panel applications", +see <A +HREF="#OPEN" +>Section 1.1</A +>) and drivers permitting simultaneous video capturing +and overlay using the same file descriptor, for compatibility with V4L +and earlier versions of V4L2.</P +><P +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +> would permit this to some degree, +but for simplicity drivers need not support switching the I/O method +(after first switching away from read/write) other than by closing +and reopening the device.</P +><P +>The following sections describe the various I/O methods in +more detail.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="RW" +>3.1. Read/Write</A +></H2 +><P +>Input and output devices support the +<CODE +CLASS="FUNCTION" +>read()</CODE +> and <CODE +CLASS="FUNCTION" +>write()</CODE +> function, +respectively, when the <CODE +CLASS="CONSTANT" +>V4L2_CAP_READWRITE</CODE +> flag in +the <CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl is set.</P +><P +>Drivers may need the CPU to copy the data, but they may also +support DMA to or from user memory, so this I/O method is not +necessarily less efficient than other methods merely exchanging buffer +pointers. It is considered inferior though because no meta-information +like frame counters or timestamps are passed. This information is +necessary to recognize frame dropping and to synchronize with other +data streams. However this is also the simplest I/O method, requiring +little or no setup to exchange data. It permits command line stunts +like this (the <SPAN +CLASS="APPLICATION" +>vidctrl</SPAN +> tool is +fictitious):</P +><DIV +CLASS="INFORMALEXAMPLE" +><P +></P +><A +NAME="AEN3266" +></A +><PRE +CLASS="SCREEN" +>> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 +> dd if=/dev/video of=myimage.422 bs=202752 count=1</PRE +><P +></P +></DIV +><P +>To read from the device applications use the +<A +HREF="#FUNC-READ" +><CODE +CLASS="FUNCTION" +>read()</CODE +></A +> function, to write the <A +HREF="#FUNC-WRITE" +><CODE +CLASS="FUNCTION" +>write()</CODE +></A +> function. +Drivers must implement one I/O method if they +exchange data with applications, but it need not be this.<A +NAME="AEN3273" +HREF="#FTN.AEN3273" +><SPAN +CLASS="footnote" +>[13]</SPAN +></A +> When reading or writing is supported, the driver +must also support the <A +HREF="#FUNC-SELECT" +><CODE +CLASS="FUNCTION" +>select()</CODE +></A +> and <A +HREF="#FUNC-POLL" +><CODE +CLASS="FUNCTION" +>poll()</CODE +></A +> +function.<A +NAME="AEN3279" +HREF="#FTN.AEN3279" +><SPAN +CLASS="footnote" +>[14]</SPAN +></A +></P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="MMAP" +>3.2. Streaming I/O (Memory Mapping)</A +></H2 +><P +>Input and output devices support this I/O method when the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_STREAMING</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl is set. There are two +streaming methods, to determine if the memory mapping flavor is +supported applications must call the <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl.</P +><P +>Streaming is an I/O method where only pointers to buffers +are exchanged between application and driver, the data itself is not +copied. Memory mapping is primarily intended to map buffers in device +memory into the application's address space. Device memory can be for +example the video memory on a graphics card with a video capture +add-on. However, being the most efficient I/O method available for a +long time, many other drivers support streaming as well, allocating +buffers in DMA-able main memory.</P +><P +>A driver can support many sets of buffers. Each set is +identified by a unique buffer type value. The sets are independent and +each set can hold a different type of data. To access different sets +at the same time different file descriptors must be used.<A +NAME="AEN3296" +HREF="#FTN.AEN3296" +><SPAN +CLASS="footnote" +>[15]</SPAN +></A +></P +><P +>To allocate device buffers applications call the +<A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl with the desired number of buffers and buffer +type, for example <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +>. +This ioctl can also be used to change the number of buffers or to free +the allocated memory, provided none of the buffers are still +mapped.</P +><P +>Before applications can access the buffers they must map +them into their address space with the <A +HREF="#FUNC-MMAP" +><CODE +CLASS="FUNCTION" +>mmap()</CODE +></A +> function. The +location of the buffers in device memory can be determined with the +<A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +> ioctl. The <CODE +CLASS="STRUCTFIELD" +>m.offset</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>length</CODE +> returned in a struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> are +passed as sixth and second parameter to the +<CODE +CLASS="FUNCTION" +>mmap()</CODE +> function. The offset and length values +must not be modified. Remember the buffers are allocated in physical +memory, as opposed to virtual memory which can be swapped out to disk. +Applications should free the buffers as soon as possible with the +<A +HREF="#FUNC-MUNMAP" +><CODE +CLASS="FUNCTION" +>munmap()</CODE +></A +> function.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN3316" +></A +><P +><B +>Example 3-1. Mapping buffers</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> reqbuf; +struct { + void *start; + size_t length; +} *buffers; +unsigned int i; + +memset (&reqbuf, 0, sizeof (reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_MMAP; +reqbuf.count = 20; + +if (-1 == ioctl (fd, <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +>, &reqbuf)) { + if (errno == EINVAL) + printf ("Video capturing or mmap-streaming is not supported\n"); + else + perror ("VIDIOC_REQBUFS"); + + exit (EXIT_FAILURE); +} + +/* We want at least five buffers. */ + +if (reqbuf.count < 5) { + /* You may need to free the buffers here. */ + printf ("Not enough buffer memory\n"); + exit (EXIT_FAILURE); +} + +buffers = calloc (reqbuf.count, sizeof (*buffers)); +assert (buffers != NULL); + +for (i = 0; i < reqbuf.count; i++) { + struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> buffer; + + memset (&buffer, 0, sizeof (buffer)); + buffer.type = reqbuf.type; + buffer.memory = V4L2_MEMORY_MMAP; + buffer.index = i; + + if (-1 == ioctl (fd, <A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +>, &buffer)) { + perror ("VIDIOC_QUERYBUF"); + exit (EXIT_FAILURE); + } + + buffers[i].length = buffer.length; /* remember for munmap() */ + + buffers[i].start = mmap (NULL, buffer.length, + PROT_READ | PROT_WRITE, /* required */ + MAP_SHARED, /* recommended */ + fd, buffer.m.offset); + + if (buffers[i].start == MAP_FAILED) { + /* You may need to unmap and free the so far + mapped buffers here. */ + perror ("mmap"); + exit (EXIT_FAILURE); + } +} + +/* Cleanup. */ + +for (i = 0; i < reqbuf.count; i++) + munmap (buffers[i].start, buffers[i].length); + </PRE +></DIV +><P +>Streaming drivers maintain two buffer queues, an incoming +and an outgoing queue. They separate the synchronous capture or output +operation locked to a video clock from the application which is +subject to random disk or network delays and preemption by +other processes, thereby reducing the probability of data loss. +The queues are organized as FIFOs, buffers will be +output in the order enqueued in the incoming FIFO, and were +captured in the order dequeued from the outgoing FIFO.</P +><P +>The driver may require a minimum number of buffers enqueued +at all times to function, apart of this no limit exists on the number +of buffers applications can enqueue in advance, or dequeue and +process. They can also enqueue in a different order than buffers have +been dequeued, and the driver can <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>fill</I +></SPAN +> enqueued +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>empty</I +></SPAN +> buffers in any order. <A +NAME="AEN3329" +HREF="#FTN.AEN3329" +><SPAN +CLASS="footnote" +>[16]</SPAN +></A +> The index number of a buffer (struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +<CODE +CLASS="STRUCTFIELD" +>index</CODE +>) plays no role here, it only +identifies the buffer.</P +><P +>Initially all mapped buffers are in dequeued state, +inaccessible by the driver. For capturing applications it is customary +to first enqueue all mapped buffers, then to start capturing and enter +the read loop. Here the application waits until a filled buffer can be +dequeued, and re-enqueues the buffer when the data is no longer +needed. Output applications fill and enqueue buffers, when enough +buffers are stacked up the output is started with +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +>. In the write loop, when +the application runs out of free buffers, it must wait until an empty +buffer can be dequeued and reused.</P +><P +>To enqueue and dequeue a buffer applications use the +<A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> and <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl. The status of a buffer being +mapped, enqueued, full or empty can be determined at any time using the +<A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +> ioctl. Two methods exist to suspend execution of the +application until one or more buffers can be dequeued. By default +<CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> blocks when no buffer is in the +outgoing queue. When the <CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag was +given to the <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> function, <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> +returns immediately with an <SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +> error code when no buffer is available. The +<A +HREF="#FUNC-SELECT" +><CODE +CLASS="FUNCTION" +>select()</CODE +></A +> or <A +HREF="#FUNC-POLL" +><CODE +CLASS="FUNCTION" +>poll()</CODE +></A +> function are always available.</P +><P +>To start and stop capturing or output applications call the +<A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> and <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +> ioctl. Note +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> removes all buffers from both +queues as a side effect. Since there is no notion of doing anything +"now" on a multitasking system, if an application needs to synchronize +with another event it should examine the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +<CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +> of captured buffers, or set the +field before enqueuing buffers for output.</P +><P +>Drivers implementing memory mapping I/O must +support the <CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +>, <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> ioctl, the +<CODE +CLASS="FUNCTION" +>mmap()</CODE +>, <CODE +CLASS="FUNCTION" +>munmap()</CODE +>, +<CODE +CLASS="FUNCTION" +>select()</CODE +> and <CODE +CLASS="FUNCTION" +>poll()</CODE +> +function.<A +NAME="AEN3371" +HREF="#FTN.AEN3371" +><SPAN +CLASS="footnote" +>[17]</SPAN +></A +></P +><P +>[capture example]</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="USERP" +>3.3. Streaming I/O (User Pointers)</A +></H2 +><P +>Input and output devices support this I/O method when the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_STREAMING</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl is set. If the particular user +pointer method (not only memory mapping) is supported must be +determined by calling the <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl.</P +><P +>This I/O method combines advantages of the read/write and +memory mapping methods. Buffers are allocated by the application +itself, and can reside for example in virtual or shared memory. Only +pointers to data are exchanged, these pointers and meta-information +are passed in struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +>. The driver must be switched +into user pointer I/O mode by calling the <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> with the +desired buffer type. No buffers are allocated beforehands, +consequently they are not indexed and cannot be queried like mapped +buffers with the <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +> ioctl.</P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN3392" +></A +><P +><B +>Example 3-2. Initiating streaming I/O with user pointers</B +></P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> reqbuf; + +memset (&reqbuf, 0, sizeof (reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_USERPTR; + +if (ioctl (fd, <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +>, &reqbuf) == -1) { + if (errno == EINVAL) + printf ("Video capturing or user pointer streaming is not supported\n"); + else + perror ("VIDIOC_REQBUFS"); + + exit (EXIT_FAILURE); +} + </PRE +></DIV +><P +>Buffer addresses and sizes are passed on the fly with the +<A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> ioctl. Although buffers are commonly cycled, +applications can pass different addresses and sizes at each +<CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +> call. If required by the hardware the +driver swaps memory pages within physical memory to create a +continuous area of memory. This happens transparently to the +application in the virtual memory subsystem of the kernel. When buffer +pages have been swapped out to disk they are brought back and finally +locked in physical memory for DMA.<A +NAME="AEN3402" +HREF="#FTN.AEN3402" +><SPAN +CLASS="footnote" +>[18]</SPAN +></A +></P +><P +>Filled or displayed buffers are dequeued with the +<A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl. The driver can unlock the memory pages at any +time between the completion of the DMA and this ioctl. The memory is +also unlocked when <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +> is called, <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +>, or +when the device is closed. Applications must take care not to free +buffers without dequeuing. For once, the buffers remain locked until +further, wasting physical memory. Second the driver will not be +notified when the memory is returned to the application's free list +and subsequently reused for other purposes, possibly completing the +requested DMA and overwriting valuable data.</P +><P +>For capturing applications it is customary to enqueue a +number of empty buffers, to start capturing and enter the read loop. +Here the application waits until a filled buffer can be dequeued, and +re-enqueues the buffer when the data is no longer needed. Output +applications fill and enqueue buffers, when enough buffers are stacked +up output is started. In the write loop, when the application +runs out of free buffers it must wait until an empty buffer can be +dequeued and reused. Two methods exist to suspend execution of the +application until one or more buffers can be dequeued. By default +<CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> blocks when no buffer is in the +outgoing queue. When the <CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag was +given to the <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> function, <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> +returns immediately with an <SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +> error code when no buffer is available. The +<A +HREF="#FUNC-SELECT" +><CODE +CLASS="FUNCTION" +>select()</CODE +></A +> or <A +HREF="#FUNC-POLL" +><CODE +CLASS="FUNCTION" +>poll()</CODE +></A +> function are always available.</P +><P +>To start and stop capturing or output applications call the +<A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> and <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +> ioctl. Note +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> removes all buffers from both +queues and unlocks all buffers as a side effect. Since there is no +notion of doing anything "now" on a multitasking system, if an +application needs to synchronize with another event it should examine +the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> <CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +> of captured +buffers, or set the field before enqueuing buffers for output.</P +><P +>Drivers implementing user pointer I/O must +support the <CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +>, <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> ioctl, the +<CODE +CLASS="FUNCTION" +>select()</CODE +> and <CODE +CLASS="FUNCTION" +>poll()</CODE +> function.<A +NAME="AEN3438" +HREF="#FTN.AEN3438" +><SPAN +CLASS="footnote" +>[19]</SPAN +></A +></P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="ASYNC" +>3.4. Asynchronous I/O</A +></H2 +><P +>This method is not defined yet.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="BUFFER" +>3.5. Buffers</A +></H2 +><P +>A buffer contains data exchanged by application and +driver using one of the Streaming I/O methods. Only pointers to +buffers are exchanged, the data itself is not copied. These pointers, +together with meta-information like timestamps or field parity, are +stored in a struct <CODE +CLASS="STRUCTNAME" +>v4l2_buffer</CODE +>, argument to +the <A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +>, <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> and <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl.</P +><P +>Nominally timestamps refer to the first data byte transmitted. +In practice however the wide range of hardware covered by the V4L2 API +limits timestamp accuracy. Often an interrupt routine will +sample the system clock shortly after the field or frame was stored +completely in memory. So applications must expect a constant +difference up to one field or frame period plus a small (few scan +lines) random error. The delay and error can be much +larger due to compression or transmission over an external bus when +the frames are not properly stamped by the sender. This is frequently +the case with USB cameras. Here timestamps refer to the instant the +field or frame was received by the driver, not the capture time. These +devices identify by not enumerating any video standards, see <A +HREF="#STANDARD" +>Section 1.7</A +>.</P +><P +>Similar limitations apply to output timestamps. Typically +the video hardware locks to a clock controlling the video timing, the +horizontal and vertical synchronization pulses. At some point in the +line sequence, possibly the vertical blanking, an interrupt routine +samples the system clock, compares against the timestamp and programs +the hardware to repeat the previous field or frame, or to display the +buffer contents.</P +><P +>Apart of limitations of the video device and natural +inaccuracies of all clocks, it should be noted system time itself is +not perfectly stable. It can be affected by power saving cycles, +warped to insert leap seconds, or even turned back or forth by the +system administrator affecting long term measurements. <A +NAME="AEN3460" +HREF="#FTN.AEN3460" +><SPAN +CLASS="footnote" +>[20]</SPAN +></A +></P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-BUFFER" +></A +><P +><B +>Table 3-1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_buffer</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="50%" +TITLE="C1"><COL><COL><COL +WIDTH="50%" +TITLE="C4"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +> </TD +><TD +>Number of the buffer, set by the application. This +field is only used for <A +HREF="#MMAP" +>memory mapping</A +> I/O +and can range from zero to the number of buffers allocated +with the <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl (struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> <CODE +CLASS="STRUCTFIELD" +>count</CODE +>) minus one.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +> </TD +><TD +>Type of the buffer, same as struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> or struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +>, set by the application.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>bytesused</CODE +></TD +><TD +> </TD +><TD +>The number of bytes occupied by the data in the +buffer. It depends on the negotiated data format and may change with +each buffer for compressed variable size data like JPEG images. +Drivers must set this field when <CODE +CLASS="STRUCTFIELD" +>type</CODE +> +refers to an input stream, applications when an output stream.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>flags</CODE +></TD +><TD +> </TD +><TD +>Flags set by the application or driver, see <A +HREF="#BUFFER-FLAGS" +>Table 3-3</A +>.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>field</CODE +></TD +><TD +> </TD +><TD +>Indicates the field order of the image in the +buffer, see <A +HREF="#V4L2-FIELD" +>Table 3-8</A +>. This field is not used when +the buffer contains VBI data. Drivers must set it when +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> refers to an input stream, +applications when an output stream.</TD +></TR +><TR +><TD +>struct timeval</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +></TD +><TD +> </TD +><TD +><P +>For input streams this is the +system time (as returned by the <CODE +CLASS="FUNCTION" +>gettimeofday()</CODE +> +function) when the first data byte was captured. For output streams +the data will not be displayed before this time, secondary to the +nominal frame rate determined by the current video standard in +enqueued order. Applications can for example zero this field to +display frames as soon as possible. The driver stores the time at +which the first data byte was actually sent out in the +<CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +> field. This permits +applications to monitor the drift between the video and system +clock.</P +></TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-TIMECODE" +>v4l2_timecode</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>timecode</CODE +></TD +><TD +> </TD +><TD +>When <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +> and the +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_TIMECODE</CODE +> flag is set in +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +>, this structure contains a frame +timecode. In <A +HREF="#V4L2-FIELD" +>V4L2_FIELD_ALTERNATE</A +> +mode the top and bottom field contain the same timecode. +Timecodes are intended to help video editing and are typically recorded on +video tapes, but also embedded in compressed formats like MPEG. This +field is independent of the <CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>sequence</CODE +> fields.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>sequence</CODE +></TD +><TD +> </TD +><TD +>Set by the driver, counting the frames in the +sequence.</TD +></TR +><TR +><TD +COLSPAN="4" +><P +>In <A +HREF="#V4L2-FIELD" +>V4L2_FIELD_ALTERNATE</A +> mode the top and +bottom field have the same sequence number. The count starts at zero +and includes dropped or repeated frames. A dropped frame was received +by an input device but could not be stored due to lack of free buffer +space. A repeated frame was displayed again by an output device +because the application did not pass new data in +time.</P +><P +>Note this may count the frames received +e.g. over USB, without taking into account the frames dropped by the +remote hardware due to limited compression throughput or bus +bandwidth. These devices identify by not enumerating any video +standards, see <A +HREF="#STANDARD" +>Section 1.7</A +>.</P +></TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>memory</CODE +></TD +><TD +> </TD +><TD +>This field must be set by applications and/or drivers +in accordance with the selected I/O method.</TD +></TR +><TR +><TD +>union</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>m</CODE +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>offset</CODE +></TD +><TD +>When <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +> this is the offset of the buffer +from the start of the device memory. The value is returned by the +driver and apart of serving as parameter to the <A +HREF="#FUNC-MMAP" +><CODE +CLASS="FUNCTION" +>mmap()</CODE +></A +> function +not useful for applications. See <A +HREF="#MMAP" +>Section 3.2</A +> for details.</TD +></TR +><TR +><TD +> </TD +><TD +>unsigned long</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>userptr</CODE +></TD +><TD +>When <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_USERPTR</CODE +> this is a pointer to the +buffer (casted to unsigned long type) in virtual memory, set by the +application. See <A +HREF="#USERP" +>Section 3.3</A +> for details.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>length</CODE +></TD +><TD +> </TD +><TD +>Size of the buffer (not the payload) in bytes.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>input</CODE +></TD +><TD +> </TD +><TD +>Some video capture drivers support rapid and +synchronous video input changes, a function useful for example in +video surveillance applications. For this purpose applications set the +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_INPUT</CODE +> flag, and this field to the +number of a video input as in struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> field +<CODE +CLASS="STRUCTFIELD" +>index</CODE +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +></TD +><TD +> </TD +><TD +>A place holder for future extensions and custom +(driver defined) buffer types +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> and higher.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-BUF-TYPE" +></A +><P +><B +>Table 3-2. enum v4l2_buf_type</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +></TD +><TD +>1</TD +><TD +>Buffer of a video capture stream, see <A +HREF="#CAPTURE" +>Section 4.1</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +></TD +><TD +>2</TD +><TD +>Buffer of a video output stream, see <A +HREF="#OUTPUT" +>Section 4.3</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +></TD +><TD +>3</TD +><TD +>Buffer for video overlay, see <A +HREF="#OVERLAY" +>Section 4.2</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_CAPTURE</CODE +></TD +><TD +>4</TD +><TD +>Buffer of a raw VBI capture stream, see <A +HREF="#RAW-VBI" +>Section 4.6</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_OUTPUT</CODE +></TD +><TD +>5</TD +><TD +>Buffer of a raw VBI output stream, see <A +HREF="#RAW-VBI" +>Section 4.6</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +></TD +><TD +>0x80</TD +><TD +>This and higher values are reserved for custom +(driver defined) buffer types.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="BUFFER-FLAGS" +></A +><P +><B +>Table 3-3. Buffer Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_MAPPED</CODE +></TD +><TD +>0x0001</TD +><TD +>The buffer resides in device memory and has been mapped +into the application's address space, see <A +HREF="#MMAP" +>Section 3.2</A +> for details. +Drivers set or clear this flag when the +<A +HREF="#VIDIOC-QUERYBUF" +>VIDIOC_QUERYBUF</A +>, <A +HREF="#VIDIOC-QBUF" +>VIDIOC_QBUF</A +> or <A +HREF="#VIDIOC-QBUF" +>VIDIOC_DQBUF</A +> ioctl is called. Set by the driver.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_QUEUED</CODE +></TD +><TD +>0x0002</TD +><TD +>Internally drivers maintain two buffer queues, an +incoming and outgoing queue. When this flag is set, the buffer is +currently on the incoming queue. It automatically moves to the +outgoing queue after the buffer has been filled (capture devices) or +displayed (output devices). Drivers set or clear this flag when the +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +> ioctl is called. After +(successful) calling the <CODE +CLASS="CONSTANT" +>VIDIOC_QBUF </CODE +>ioctl it is +always set and after <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> always +cleared.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_DONE</CODE +></TD +><TD +>0x0004</TD +><TD +>When this flag is set, the buffer is currently on +the outgoing queue, ready to be dequeued from the driver. Drivers set +or clear this flag when the <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +> ioctl +is called. After calling the <CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +> or +<CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> it is always cleared. Of course a +buffer cannot be on both queues at the same time, the +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_QUEUED</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_DONE</CODE +> flag are mutually exclusive. +They can be both cleared however, then the buffer is in "dequeued" +state, in the application domain to say so.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_KEYFRAME</CODE +></TD +><TD +>0x0008</TD +><TD +>Drivers set or clear this flag when calling the +<CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> ioctl. It may be set by video +capture devices when the buffer contains a compressed image which is a +key frame (or field), i.e. can be decompressed on its own.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_PFRAME</CODE +></TD +><TD +>0x0010</TD +><TD +>Similar to <CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_KEYFRAME</CODE +> +this flags predicted frames or fields which contain only differences to a +previous key frame.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_BFRAME</CODE +></TD +><TD +>0x0020</TD +><TD +>Similar to <CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_PFRAME</CODE +> + this is a bidirectional predicted frame or field. [ooc tbd]</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_TIMECODE</CODE +></TD +><TD +>0x0100</TD +><TD +>The <CODE +CLASS="STRUCTFIELD" +>timecode</CODE +> field is valid. +Drivers set or clear this flag when the <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> +ioctl is called.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_INPUT</CODE +></TD +><TD +>0x0200</TD +><TD +>The <CODE +CLASS="STRUCTFIELD" +>input</CODE +> field is valid. +Applications set or clear this flag before calling the +<CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +> ioctl.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-MEMORY" +></A +><P +><B +>Table 3-4. enum v4l2_memory</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +></TD +><TD +>1</TD +><TD +>The buffer is used for <A +HREF="#MMAP" +>memory +mapping</A +> I/O.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_MEMORY_USERPTR</CODE +></TD +><TD +>2</TD +><TD +>The buffer is used for <A +HREF="#USERP" +>user +pointer</A +> I/O.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_MEMORY_OVERLAY</CODE +></TD +><TD +>3</TD +><TD +>[to do]</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN3738" +>3.5.1. Timecodes</A +></H3 +><P +>The <CODE +CLASS="STRUCTNAME" +>v4l2_timecode</CODE +> structure is +designed to hold a <A +HREF="#SMPTE12M" +><ABBR +CLASS="ABBREV" +>SMPTE12M</ABBR +></A +> or similar timecode. +(struct <CODE +CLASS="STRUCTNAME" +>timeval</CODE +> timestamps are stored in +struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> field <CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +>.)</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-TIMECODE" +></A +><P +><B +>Table 3-5. struct <CODE +CLASS="STRUCTNAME" +>v4l2_timecode</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Frame rate the timecodes are based on, see <A +HREF="#TIMECODE-TYPE" +>Table 3-6</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>flags</CODE +></TD +><TD +>Timecode flags, see <A +HREF="#TIMECODE-FLAGS" +>Table 3-7</A +>.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>frames</CODE +></TD +><TD +>Frame count, 0 ... 23/24/29/49/59, depending on the + type of timecode.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>seconds</CODE +></TD +><TD +>Seconds count, 0 ... 59. This is a binary, not BCD number.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>minutes</CODE +></TD +><TD +>Minutes count, 0 ... 59. This is a binary, not BCD number.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>hours</CODE +></TD +><TD +>Hours count, 0 ... 29. This is a binary, not BCD number.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>userbits</CODE +>[4]</TD +><TD +>The "user group" bits from the timecode.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="TIMECODE-TYPE" +></A +><P +><B +>Table 3-6. Timecode Types</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_TYPE_24FPS</CODE +></TD +><TD +>1</TD +><TD +>24 frames per second, i. e. film.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_TYPE_25FPS</CODE +></TD +><TD +>2</TD +><TD +>25 frames per second, i.e. PAL or SECAM video.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_TYPE_30FPS</CODE +></TD +><TD +>3</TD +><TD +>30 frames per second, i.e. NTSC video.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_TYPE_50FPS</CODE +></TD +><TD +>4</TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_TYPE_60FPS</CODE +></TD +><TD +>5</TD +><TD +> </TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="TIMECODE-FLAGS" +></A +><P +><B +>Table 3-7. Timecode Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_FLAG_DROPFRAME</CODE +></TD +><TD +>0x0001</TD +><TD +>Indicates "drop frame" semantics for counting frames +in 29.97 fps material. When set, frame numbers 0 and 1 at the start of +each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the +count.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_FLAG_COLORFRAME</CODE +></TD +><TD +>0x0002</TD +><TD +>The "color frame" flag.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_USERBITS_field</CODE +></TD +><TD +>0x000C</TD +><TD +>Field mask for the "binary group flags".</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_USERBITS_USERDEFINED</CODE +></TD +><TD +>0x0000</TD +><TD +>Unspecified format.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TC_USERBITS_8BITCHARS</CODE +></TD +><TD +>0x0008</TD +><TD +>8-bit ISO characters.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="FIELD-ORDER" +>3.6. Field Order</A +></H2 +><P +>We have to distinguish between progressive and interlaced +video. Progressive video transmits all lines of a video image +sequentially. Interlaced video divides an image into two fields, +containing only the odd and even lines of the image, respectively. +Alternating the so called odd and even field are transmitted, and due +to a small delay between fields a cathode ray TV displays the lines +interleaved, yielding the original frame. This curious technique was +invented because at refresh rates similar to film the image would +fade out too quickly. Transmitting fields reduces the flicker without +the necessity of doubling the frame rate and with it the bandwidth +required for each channel.</P +><P +>It is important to understand a video camera does not expose +one frame at a time, merely transmitting the frames separated into +fields. The fields are in fact captured at two different instances in +time. An object on screen may well move between one field and the +next. For applications analysing motion it is of paramount importance +to recognize which field of a frame is older, the <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>temporal +order</I +></SPAN +>.</P +><P +>When the driver provides or accepts images field by field +rather than interleaved, it is also important applications understand +how the fields combine to frames. We distinguish between top and +bottom fields, the <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>spatial order</I +></SPAN +>: The first line +of the top field is the first line of an interlaced frame, the first +line of the bottom field is the second line of that frame.</P +><P +>However because fields were captured one after the other, +arguing whether a frame commences with the top or bottom field is +pointless. Any two successive top and bottom, or bottom and top fields +yield a valid frame. Only when the source was progressive to begin +with, e. g. when transferring film to video, two fields may come from +the same frame, creating a natural order.</P +><P +>Counter to intuition the top field is not necessarily the +older field. Whether the older field contains the top or bottom lines +is a convention determined by the video standard. Hence the +distinction between temporal and spatial order of fields. The diagrams +below should make this clearer.</P +><P +>All video capture and output devices must report the current +field order. Some drivers may permit the selection of a different +order, to this end applications initialize the +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> field of struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> before +calling the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl. If this is not desired it should +have the value <CODE +CLASS="CONSTANT" +>V4L2_FIELD_ANY</CODE +> (0).</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-FIELD" +></A +><P +><B +>Table 3-8. enum v4l2_field</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_ANY</CODE +></TD +><TD +>0</TD +><TD +>Applications request this field order when any +one of the <CODE +CLASS="CONSTANT" +>V4L2_FIELD_NONE</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +>, or +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_INTERLACED</CODE +> formats is acceptable. +Drivers choose depending on hardware capabilities or e. g. the +requested image size, and return the actual field order. struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> can never be +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_ANY</CODE +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_NONE</CODE +></TD +><TD +>1</TD +><TD +>Images are in progressive format, not interlaced. +The driver may also indicate this order when it cannot distinguish +between <CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +></TD +><TD +>2</TD +><TD +>Images consist of the top field only.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +></TD +><TD +>3</TD +><TD +>Images consist of the bottom field only. +Applications may wish to prevent a device from capturing interlaced +images because they will have "comb" or "feathering" artefacts around +moving objects.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_INTERLACED</CODE +></TD +><TD +>4</TD +><TD +>Images contain both fields, interleaved line by +line. The temporal order of the fields (whether the top or bottom +field is first transmitted) depends on the current video standard. +M/NTSC transmits the bottom field first, all other standards the top +field first.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_SEQ_TB</CODE +></TD +><TD +>5</TD +><TD +>Images contain both fields, the top field lines +are stored first in memory, immediately followed by the bottom field +lines. Fields are always stored in temporal order, the older one first +in memory. Image sizes refer to the frame, not fields.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_SEQ_BT</CODE +></TD +><TD +>6</TD +><TD +>Images contain both fields, the bottom field +lines are stored first in memory, immediately followed by the top +field lines. Fields are always stored in temporal order, the older one +first in memory. Image sizes refer to the frame, not fields.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_ALTERNATE</CODE +></TD +><TD +>7</TD +><TD +>The two fields of a frame are passed in separate +buffers, in temporal order, i. e. the older one first. To indicate the field +parity (whether the current field is a top or bottom field) the driver +or application, depending on data direction, must set struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> to +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +>. Any two successive fields pair +to build a frame. If fields are successive, without any dropped fields +between them (fields can drop individually), can be determined from +the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> <CODE +CLASS="STRUCTFIELD" +>sequence</CODE +> field. Image +sizes refer to the frame, not fields. This format cannot be selected +when using the read/write I/O method.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="FIGURE" +><A +NAME="FIELDSEQ-TB" +></A +><P +><B +>Figure 3-1. Field Order, Top Field First Transmitted</B +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="fieldseq_tb.gif"></P +></DIV +></DIV +><DIV +CLASS="FIGURE" +><A +NAME="FIELDSEQ-BT" +></A +><P +><B +>Figure 3-2. Field Order, Bottom Field First Transmitted</B +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="fieldseq_bt.gif"></P +></DIV +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="DEVICES" +></A +>Chapter 4. Device Types</H1 +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="CAPTURE" +>4.1. Video Capture Interface</A +></H2 +><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 capture device.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN3960" +>4.1.1. Querying Capabilities</A +></H3 +><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="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +>. As secondary device functions they +may also support the <A +HREF="#OVERLAY" +>video overlay</A +> +(<CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OVERLAY</CODE +>) and the <A +HREF="#RAW-VBI" +>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" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN3972" +>4.1.2. Supplemental Functions</A +></H3 +><P +>Video capture devices shall support <A +HREF="#AUDIO" +>audio input</A +>, <A +HREF="#TUNER" +>tuner</A +>, <A +HREF="#CONTROL" +>controls</A +>, +<A +HREF="#CROP" +>cropping and scaling</A +> and <A +HREF="#STREAMING-PAR" +>streaming parameter</A +> ioctls as needed. +The <A +HREF="#VIDEO" +>video input</A +> and <A +HREF="#STANDARD" +>video standard</A +> ioctls must be supported by +all video capture devices.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN3982" +>4.1.3. Image Format Negotiation</A +></H3 +><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 <CODE +CLASS="FUNCTION" +>open()</CODE +> 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="#CROP" +>Section 1.10</A +>.</P +><P +>To query the current image format applications set the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> to +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +> and call the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> ioctl with a pointer to this structure. Drivers fill +the struct <A +HREF="#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="#V4L2-FORMAT" +>v4l2_format</A +> as above and +initialize all fields of the struct <A +HREF="#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="#VIDIOC-G-FMT" +><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="#VIDIOC-G-FMT" +><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="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> are discussed in <A +HREF="#PIXFMT" +>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" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4024" +>4.1.4. Reading Images</A +></H3 +><P +>A video capture device may support the <A +HREF="#RW" +>read() function</A +> and/or streaming (<A +HREF="#MMAP" +>memory mapping</A +> or <A +HREF="#USERP" +>user pointer</A +>) I/O. See <A +HREF="#IO" +>Chapter 3</A +> for details.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="OVERLAY" +>4.2. Video Overlay Interface</A +></H2 +><FONT +COLOR="RED" +>Also known as Frame Buffer Overlay or Previewing</FONT +><P +>Video overlay devices have the ability to genlock (TV-)video +into the (VGA-)video signal of a graphics card, or to store captured +images directly in video memory of a graphics card, typically with +clipping. This can be considerable more efficient than capturing +images and displaying them by other means. In the old days when only +nuclear power plants needed cooling towers this used to be the only +way to put live video into a window.</P +><P +>Video overlay devices are accessed through the same character +special files as <A +HREF="#CAPTURE" +>video capture</A +> devices. +Note the default function of a <TT +CLASS="FILENAME" +>/dev/video</TT +> device +is video capturing. The overlay function is only available after +calling the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl.</P +><P +>The driver may support simultaneous overlay and capturing +using the read/write and streaming I/O methods. If so, operation at +the nominal frame rate of the video standard is not guaranteed. Frames +may be directed away from overlay to capture, or one field may be used +for overlay and the other for capture if the capture parameters permit +this.</P +><P +>Applications should use different file descriptors for +capturing and overlay. This must be supported by all drivers capable +of simultaneous capturing and overlay. Optionally these drivers may +also permit capturing and overlay with a single file descriptor for +compatibility with V4L and earlier versions of V4L2.<A +NAME="AEN4042" +HREF="#FTN.AEN4042" +><SPAN +CLASS="footnote" +>[21]</SPAN +></A +></P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4048" +>4.2.1. Querying Capabilities</A +></H3 +><P +>Devices supporting the video overlay interface set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OVERLAY</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +>. The overlay I/O method specified +below must be supported. Tuners and audio inputs are optional.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4056" +>4.2.2. Supplemental Functions</A +></H3 +><P +>Video overlay devices shall support <A +HREF="#AUDIO" +>audio input</A +>, <A +HREF="#TUNER" +>tuner</A +>, <A +HREF="#CONTROL" +>controls</A +>, +<A +HREF="#CROP" +>cropping and scaling</A +> and <A +HREF="#STREAMING-PAR" +>streaming parameter</A +> ioctls as needed. +The <A +HREF="#VIDEO" +>video input</A +> and <A +HREF="#STANDARD" +>video standard</A +> ioctls must be supported by +all video overlay devices.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4066" +>4.2.3. Setup</A +></H3 +><P +>Before overlay can commence applications must program the +driver with frame buffer parameters, namely the address and size of +the frame buffer and the image format, for example RGB 5:6:5. The +<A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +></A +> and <A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +></A +> ioctls are available to get +and set these parameters, respectively. The +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +> ioctl is privileged because it +allows to set up DMA into physical memory, bypassing the memory +protection mechanisms of the kernel. Only the superuser can change the +frame buffer address and size. Users are not supposed to run TV +applications as root or with SUID bit set. A small helper application +with suitable privileges should query the graphics system and program +the V4L2 driver at the appropriate time.</P +><P +>Some devices add the video overlay to the output signal +of the graphics card. In this case the frame buffer is not modified by +the video device, and the frame buffer address and pixel format are +not needed by the driver. The <CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +> ioctl +is not privileged. An application can check for this type of device by +calling the <CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +> ioctl.</P +><P +>A driver may support any (or none) of three clipping +methods:<P +></P +><OL +TYPE="1" +><LI +><P +>Chroma-keying displays the overlaid image only where +pixels in the primary graphics surface assume a certain color.</P +></LI +><LI +><P +>A bitmap can be specified where each bit corresponds +to a pixel in the overlaid image. When the bit is set, the +corresponding video pixel is displayed, otherwise a pixel of the +graphics surface.</P +></LI +><LI +><P +>A list of clipping rectangles can be specified. In +these regions <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>no</I +></SPAN +> video is displayed, so the +graphics surface can be seen here.</P +></LI +></OL +></P +><P +>When simultaneous capturing and overlay is supported and +the hardware prohibits different image and frame buffer formats, the +format requested first takes precedence. The attempt to capture +(<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +>) or overlay (<A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +></A +>) may fail with an +<SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code or return accordingly modified parameters..</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4092" +>4.2.4. Overlay Window</A +></H3 +><P +>The overlaid image is determined by cropping and overlay +window parameters. The former select an area of the video picture to +capture, the latter how images are overlaid and clipped. Cropping +initialization at minimum requires to reset the parameters to +defaults. An example is given in <A +HREF="#CROP" +>Section 1.10</A +>.</P +><P +>The overlay window is described by a struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +>. It +defines the size of the image, its position over the graphics surface +and the clipping to be applied. To get the current parameters applications +set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> to +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +> and call the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> ioctl. The driver fills the +<CODE +CLASS="STRUCTNAME" +>v4l2_window</CODE +> substructure named +<CODE +CLASS="STRUCTFIELD" +>win</CODE +>. Retrieving a previously programmed +clipping list or bitmap is not possible.</P +><P +>To program the overlay window applications set the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> to +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +>, initialize the +<CODE +CLASS="STRUCTFIELD" +>win</CODE +> substructure and call the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl. The driver adjusts the parameters against +hardware limits and returns the actual parameters as +<CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +> does. Like +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +>, the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +></A +> ioctl can be +used to learn about driver capabilities without actually changing +driver state. Unlike <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> this also works +after the overlay has been enabled.</P +><P +>The scaling factor of the overlaid image is implied by the +width and height given in struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +> and the size of the cropping +rectangle. For more information see <A +HREF="#CROP" +>Section 1.10</A +>.</P +><P +>When simultaneous capturing and overlay is supported and +the hardware prohibits different image and window sizes, the size +requested first takes precedence. The attempt to capture or overlay as +well (<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +>) may fail with an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code or return accordingly +modified parameters.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-WINDOW" +></A +><P +><B +>Table 4-1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_window</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>w</CODE +></TD +><TD +>Size and position of the window relative to the +top, left corner of the frame buffer defined with <A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +></A +>. The +window can extend the frame buffer width and height, the +<CODE +CLASS="STRUCTFIELD" +>x</CODE +> and <CODE +CLASS="STRUCTFIELD" +>y</CODE +> +coordinates can be negative, and it can lie completely outside the +frame buffer. The driver clips the window accordingly, or if that is +not possible, modifies its size and/or position.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>field</CODE +></TD +><TD +>Applications set this field to determine which +video field shall be overlaid, typically one of +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_ANY</CODE +> (0), +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_INTERLACED</CODE +>. Drivers may have to choose +a different field order and return the actual setting here.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>chromakey</CODE +></TD +><TD +>When chroma-keying has been negotiated with +<A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +></A +> applications set this field to the desired host order +RGB32 value for the chroma key. [host order? alpha channel?]</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> *</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>clips</CODE +></TD +><TD +>When chroma-keying has <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> +been negotiated and <A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +></A +> indicated this capability, +applications can set this field to point to the first in a list of +clipping rectangles.</TD +></TR +><TR +><TD +COLSPAN="3" +>Like the window coordinates +<CODE +CLASS="STRUCTFIELD" +>w</CODE +>, clipping rectangles are defined relative +to the top, left corner of the frame buffer. However clipping +rectangles must not extend the frame buffer width and height, and they +must not overlap. If possible applications should merge adjacent +rectangles. Whether this must create x-y or y-x bands, or the order of +rectangles, is not defined. When clip lists are not supported the +driver ignores this field. Its contents after calling <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> +are undefined.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>clipcount</CODE +></TD +><TD +>When the application set the +<CODE +CLASS="STRUCTFIELD" +>clips</CODE +> field, this field must contain the +number of clipping rectangles in the list. When clip lists are not +supported the driver ignores this field, its contents after calling +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> are undefined. When clip lists are +supported but no clipping is desired this field must be set to +zero.</TD +></TR +><TR +><TD +>void *</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>bitmap</CODE +></TD +><TD +>When chroma-keying has +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> been negotiated and <A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +></A +> indicated +this capability, applications can set this field to point to a +clipping bit mask.</TD +></TR +><TR +><TD +COLSPAN="3" +><P +>It must be of the same size +as the window, <CODE +CLASS="STRUCTFIELD" +>w.width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>w.height</CODE +>. Each bit corresponds to a pixel +in the overlaid image, which is displayed only when the bit is +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>set</I +></SPAN +>. Pixel coordinates translate to bits like: +<PRE +CLASS="PROGRAMLISTING" +>((__u8 *) <CODE +CLASS="STRUCTFIELD" +>bitmap</CODE +>)[<CODE +CLASS="STRUCTFIELD" +>w.width</CODE +> * y + x / 8] & (1 << (x & 7))</PRE +></P +><P +>where <CODE +CLASS="STRUCTFIELD" +>0</CODE +> ≤ x < +<CODE +CLASS="STRUCTFIELD" +>w.width</CODE +> and <CODE +CLASS="STRUCTFIELD" +>0</CODE +> ≤ +y <<CODE +CLASS="STRUCTFIELD" +>w.height</CODE +>.<SUP +>a</SUP +></P +><P +>When a clipping +bit mask is not supported the driver ignores this field, its contents +after calling <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> are undefined. When a bit mask is supported +but no clipping is desired this field must be set to +<CODE +CLASS="CONSTANT" +>NULL</CODE +>.</P +><P +>Applications need not create a +clip list or bit mask. When they pass both, or despite negotiating +chroma-keying, the results are undefined. Regardless of the chosen +method, the clipping abilities of the hardware may be limited in +quantity or quality. The results when these limits are exceeded are +undefined.<SUP +>b</SUP +></P +></TD +></TR +></TBODY +><TR +><TD +COLSPAN="3" +>Notes:<BR><A +NAME="FTN.AEN4203" +>a. </A +>Should we require + <CODE +CLASS="STRUCTFIELD" +>w.width</CODE +> to be a multiple of + eight?<BR><A +NAME="FTN.AEN4211" +>b. </A +>When the image is written into frame buffer +memory it will be undesirable if the driver clips out less pixels +than expected, because the application and graphics system are not +aware these regions need to be refreshed. The driver should clip out +more pixels or not write the image at all.<BR></TD +></TR +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CLIP" +></A +><P +><B +>Table 4-2. struct <CODE +CLASS="STRUCTNAME" +>v4l2_clip</CODE +><A +NAME="AEN4216" +HREF="#FTN.AEN4216" +><SPAN +CLASS="footnote" +>[22]</SPAN +></A +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>c</CODE +></TD +><TD +>Coordinates of the clipping rectangle, relative to +the top, left corner of the frame buffer. Only window pixels +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>outside</I +></SPAN +> all clipping rectangles are +displayed.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> *</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>next</CODE +></TD +><TD +>Pointer to the next clipping rectangle in the list, +NULL when this is the last rectangle.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-RECT" +></A +><P +><B +>Table 4-3. struct <CODE +CLASS="STRUCTNAME" +>v4l2_rect</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>left</CODE +></TD +><TD +>Horizontal offset of the top, left corner of the +rectangle, in pixels.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>top</CODE +></TD +><TD +>Vertical offset of the top, left corner of the +rectangle, in pixels. Offsets increase to the right and down.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>width</CODE +></TD +><TD +>Width of the rectangle, in pixels.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>height</CODE +></TD +><TD +>Height of the rectangle, in pixels. Width and +height cannot be negative, the fields are signed for hysterical +reasons. </TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4266" +>4.2.5. Enabling Overlay</A +></H3 +><P +>To start or stop the frame buffer overlay applications call +the <A +HREF="#VIDIOC-OVERLAY" +><CODE +CLASS="CONSTANT" +>VIDIOC_OVERLAY</CODE +></A +> ioctl.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="OUTPUT" +>4.3. Video Output Interface</A +></H2 +><P +>Video output devices encode stills or image sequences as +analog video signal. With this interface applications can +control the encoding process and move images from user space to +the driver.</P +><P +>Conventionally V4L2 video output devices are accessed through +character device special files named <TT +CLASS="FILENAME" +>/dev/vout</TT +> and +<TT +CLASS="FILENAME" +>/dev/vout0</TT +> to <TT +CLASS="FILENAME" +>/dev/voutN</TT +>. No +minor numbers were recommended yet. <TT +CLASS="FILENAME" +>/dev/vout</TT +> is +typically a symbolic link to the preferred video output device.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4279" +>4.3.1. Querying Capabilities</A +></H3 +><P +>Devices supporting the video output interface set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OUTPUT</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +>. As secondary device functions they +may also support the <A +HREF="#RAW-VBI" +>raw VBI output</A +> +(<CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_OUTPUT</CODE +>) interface. At least one of +the read/write or streaming I/O methods must be supported. Modulators +and audio outputs are optional.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4289" +>4.3.2. Supplemental Functions</A +></H3 +><P +>Video output devices shall support <A +HREF="#AUDIO" +>audio output</A +>, <A +HREF="#TUNER" +>modulator</A +>, <A +HREF="#CONTROL" +>controls</A +>, +<A +HREF="#CROP" +>cropping and scaling</A +> and <A +HREF="#STREAMING-PAR" +>streaming parameter</A +> ioctls as needed. +The <A +HREF="#VIDEO" +>video output</A +> and <A +HREF="#STANDARD" +>video standard</A +> ioctls must be supported by +all video output devices.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4299" +>4.3.3. Image Format Negotiation</A +></H3 +><P +>The output is determined by cropping and image format +parameters. The former select an area of the video picture where the +image will appear, 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 <CODE +CLASS="FUNCTION" +>open()</CODE +> time to permit Unix tool chains, +programming a device and then writing to 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="#CROP" +>Section 1.10</A +>.</P +><P +>To query the current image format applications set the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> to +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +> and call the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> ioctl with a pointer to this structure. Drivers fill +the struct <A +HREF="#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="#V4L2-FORMAT" +>v4l2_format</A +> as above and +initialize all fields of the struct <A +HREF="#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="#VIDIOC-G-FMT" +><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="#VIDIOC-G-FMT" +><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="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> are discussed in <A +HREF="#PIXFMT" +>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 +output 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" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4341" +>4.3.4. Writing Images</A +></H3 +><P +>A video output device may support the <A +HREF="#RW" +>write() function</A +> and/or streaming (<A +HREF="#MMAP" +>memory mapping</A +> or <A +HREF="#USERP" +>user pointer</A +>) I/O. See <A +HREF="#IO" +>Chapter 3</A +> for details.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="CODEC" +>4.4. Codec Interface</A +></H2 +><DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Suspended: </B +>This interface has been be suspended from the V4L2 API +implemented in Linux 2.6 until we have more experience with codec +device interfaces.</P +></BLOCKQUOTE +></DIV +><P +>A V4L2 codec can compress, decompress, transform, or +otherwise convert video data from one format into another format, in +memory. Applications send data to be converted to the driver through +the <CODE +CLASS="FUNCTION" +>write()</CODE +> call, and receive the converted data +through the <CODE +CLASS="FUNCTION" +>read()</CODE +> call. For efficiency, a driver +may also support streaming I/O.</P +><P +>[to do]</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="EFFECT" +>4.5. Effect Devices Interface</A +></H2 +><DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Suspended: </B +>This interface has been be suspended from the V4L2 API +implemented in Linux 2.6 until we have more experience with effect +device interfaces.</P +></BLOCKQUOTE +></DIV +><P +>A V4L2 video effect device can do image effects, +filtering, or combine two or more images or image streams. For example +video transitions or wipes. Applications send data to be processed and +receive the result data either with <CODE +CLASS="FUNCTION" +>read()</CODE +> and +<CODE +CLASS="FUNCTION" +>write()</CODE +> functions, or through the streaming I/O +mechanism.</P +><P +>[to do]</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="RAW-VBI" +>4.6. Raw VBI Data Interface</A +></H2 +><P +>VBI is an abbreviation of "Vertical Blanking Interval", a gap +in the sequence of lines of an analog video signal. During VBI +no picture information is transmitted, allowing some time while the +electron beam of a cathode ray tube TV returns to the top of the +screen. Using an oscilloscope you will find here the vertical +synchronization pulses and short data packages ASK +modulated<A +NAME="AEN4369" +HREF="#FTN.AEN4369" +><SPAN +CLASS="footnote" +>[23]</SPAN +></A +> +onto the video signal. These are transmissions of services such as +Teletext or Closed Caption.</P +><P +>Subject of this interface type is raw VBI data, as sampled off +a video signal, or to be added to a signal for output. +The data format is similar to uncompressed video images, a number of +lines times a number of samples per line, we call this a VBI image.</P +><P +>Conventionally V4L2 VBI devices are accessed through character +device special files named <TT +CLASS="FILENAME" +>/dev/vbi</TT +> and +<TT +CLASS="FILENAME" +>/dev/vbi0</TT +> to <TT +CLASS="FILENAME" +>/dev/vbi15</TT +> with +major number 81 and minor numbers 224 to 239. +<TT +CLASS="FILENAME" +>/dev/vbi</TT +> is typically a symbolic link to the +preferred VBI device. This convention applies to both input and output +devices.</P +><P +>To address the problems of finding related video and VBI +devices VBI capturing is also available as device function under +<TT +CLASS="FILENAME" +>/dev/video</TT +>, VBI output under +<TT +CLASS="FILENAME" +>/dev/vout</TT +>. To capture raw VBI data from these +devices applications must call the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl. Accessed as +<TT +CLASS="FILENAME" +>/dev/vbi</TT +>, raw VBI capturing or output is +the default device function.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4383" +>4.6.1. Querying Capabilities</A +></H3 +><P +>Devices supporting the raw VBI capturing or output API set +the <CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_CAPTURE</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_OUTPUT</CODE +> flags, respectively, in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +>. At least one of the +read/write, streaming or asynchronous I/O methods must be +supported. VBI devices may or may not have a tuner or modulator.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4392" +>4.6.2. Supplemental Functions</A +></H3 +><P +>VBI devices shall support <A +HREF="#VIDEO" +>video +input or output</A +>, <A +HREF="#TUNER" +>tuner or +modulator</A +>, and <A +HREF="#CONTROL" +>controls</A +> ioctls +as needed. The <A +HREF="#STANDARD" +>video standard</A +> ioctls provide +information vital to program a VBI device, therefore must be +supported.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4399" +>4.6.3. Raw VBI Format Negotiation</A +></H3 +><P +>Raw VBI sampling abilities can vary, in particular the +sampling frequency. To properly interpret the data V4L2 specifies an +ioctl to query the sampling parameters. Moreover, to allow for some +flexibility applications can also suggest different parameters.</P +><P +>As usual these parameters are <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> +reset at <CODE +CLASS="FUNCTION" +>open()</CODE +> 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 should always ensure they really +get what they want, requesting reasonable parameters and then checking +if the actual parameters are suitable.</P +><P +>To query the current raw VBI capture parameters +applications set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> to <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_CAPTURE</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_OUTPUT</CODE +>, and call the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> ioctl with a pointer to this structure. Drivers fill +the struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> <CODE +CLASS="STRUCTFIELD" +>vbi</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="#V4L2-FORMAT" +>v4l2_format</A +> as above and +initialize all fields of the struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_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="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl with a pointer to this structure. Drivers return +an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code only when the given parameters are ambiguous, otherwise +they modify the parameters according to the hardware capabilites and +return the actual parameters. When the driver allocates resources at +this point, it may return an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code to indicate the returned +parameters are valid but the required resources are currently not +available. That may happen for instance when the video and VBI areas +to capture would overlap, or when the driver supports multiple opens +and another process already requested VBI capturing or output. Anyway, +applications must expect other resource allocation points which may +return <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +>, at the <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> ioctl +and the first read(), write() and select() call.</P +><P +>VBI 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 +CLASS="TABLE" +><A +NAME="V4L2-VBI-FORMAT" +></A +><P +><B +>Table 4-4. struct <CODE +CLASS="STRUCTNAME" +>v4l2_vbi_format</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>sampling_rate</CODE +></TD +><TD +>Samples per second, i. e. unit 1 Hz.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>offset</CODE +></TD +><TD +><P +>Horizontal offset of the VBI image, +relative to the leading edge of the line synchronization pulse and +counted in samples: The first sample in the VBI image will be located +<CODE +CLASS="STRUCTFIELD" +>offset</CODE +> / +<CODE +CLASS="STRUCTFIELD" +>sampling_rate</CODE +> seconds following the leading +edge. See also <A +HREF="#VBI-HSYNC" +>Figure 4-1</A +>.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>samples_per_line</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>sample_format</CODE +></TD +><TD +><P +>Defines the sample format as in <A +HREF="#PIXFMT" +>Chapter 2</A +>, a four-character-code.<SUP +>a</SUP +> Usually this is +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +>, i. e. each sample +consists of 8 bits with lower values oriented towards the black level. +Do not assume any other correlation of values with the signal level. +For example, the MSB does not necessarily indicate if the signal is +'high' or 'low' because 128 may not be the mean value of the +signal. Drivers shall not convert the sample format by software.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>start</CODE +>[2]</TD +><TD +>This is the scanning system line number +associated with the first line of the VBI image, of the first and the +second field respectively. See <A +HREF="#VBI-525" +>Figure 4-2</A +> and +<A +HREF="#VBI-625" +>Figure 4-3</A +> for valid values. VBI input drivers can +return start values 0 if the hardware cannot reliable identify +scanning lines, VBI acquisition may not require this +information.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>count</CODE +>[2]</TD +><TD +>The number of lines in the first and second +field image, respectively.</TD +></TR +><TR +><TD +COLSPAN="3" +><P +>Drivers should be as +flexibility as possible. For example, it may be possible to extend or +move the VBI capture window down to the picture area, implementing a +'full field mode' to capture data service transmissions embedded in +the picture.</P +><P +>An application can set the first or second +<CODE +CLASS="STRUCTFIELD" +>count</CODE +> value to zero if no data is required +from the respective field; <CODE +CLASS="STRUCTFIELD" +>count</CODE +>[1] if the +scanning system is progressive, i. e. not interlaced. The +corresponding start value shall be ignored by the application and +driver. Anyway, drivers may not support single field capturing and +return both count values non-zero.</P +><P +>Both +<CODE +CLASS="STRUCTFIELD" +>count</CODE +> values set to zero, or line numbers +outside the bounds depicted in <A +HREF="#VBI-525" +>Figure 4-2</A +> and <A +HREF="#VBI-625" +>Figure 4-3</A +>, or a field image covering +lines of two fields, are invalid and shall not be returned by the +driver.</P +><P +>To initialize the <CODE +CLASS="STRUCTFIELD" +>start</CODE +> +and <CODE +CLASS="STRUCTFIELD" +>count</CODE +> fields, applications must first +determine the current video standard selection. The <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> or +the <CODE +CLASS="STRUCTFIELD" +>framelines</CODE +> field of struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> can +be evaluated for this purpose.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>flags</CODE +></TD +><TD +>See <A +HREF="#VBIFMT-FLAGS" +>Table 4-5</A +> below. Currently +only drivers set flags, applications must set this field to +zero.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[2]</TD +><TD +>This array is reserved for future extensions. +Drivers and applications must set it to zero.</TD +></TR +></TBODY +><TR +><TD +COLSPAN="3" +>Notes:<BR><A +NAME="FTN.AEN4470" +>a. </A +>A few devices may be unable to +sample VBI data at all but can extend the video capture window to the +VBI region.<BR></TD +></TR +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="VBIFMT-FLAGS" +></A +><P +><B +>Table 4-5. Raw VBI Format Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_VBI_UNSYNC</CODE +></TD +><TD +>0x0001</TD +><TD +><P +>This flag indicates hardware which does not +properly distinguish between fields. Normally the VBI image stores the +first field (lower scanning line numbers) first in memory. This may be +a top or bottom field depending on the video standard. When this flag +is set the first or second field may be stored first, however the +fields are still in correct temporal order with the older field first +in memory.<SUP +>a</SUP +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_VBI_INTERLACED</CODE +></TD +><TD +>0x0002</TD +><TD +>By default the two field images will be passed +sequentially; all lines of the first field followed by all lines of +the second field (compare <A +HREF="#FIELD-ORDER" +>Section 3.6</A +> +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_SEQ_TB</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_SEQ_BT</CODE +>, whether the top or bottom +field is first in memory depends on the video standard). When this +flag is set, the two fields are interlaced (cf. +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_INTERLACED</CODE +>). The first line of the +first field followed by the first line of the second field, then the +two second lines, and so on. Such a layout may be necessary when the +hardware has been programmed to capture or output interlaced video +images and is unable to separate the fields for VBI capturing at +the same time. For simplicity setting this flag implies that both +<CODE +CLASS="STRUCTFIELD" +>count</CODE +> values are equal and non-zero.</TD +></TR +></TBODY +><TR +><TD +COLSPAN="3" +>Notes:<BR><A +NAME="FTN.AEN4526" +>a. </A +>Most VBI services transmit on both fields, but +some have different semantics depending on the field number. These +cannot be reliable decoded or encoded when +<CODE +CLASS="CONSTANT" +>V4L2_VBI_UNSYNC</CODE +> is set.<BR></TD +></TR +></TABLE +></DIV +><DIV +CLASS="FIGURE" +><A +NAME="VBI-HSYNC" +></A +><P +><B +>Figure 4-1. Line synchronization</B +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="vbi_hsync.gif"></P +></DIV +></DIV +><DIV +CLASS="FIGURE" +><A +NAME="VBI-525" +></A +><P +><B +>Figure 4-2. ITU-R 525 line numbering (M/NTSC and M/PAL)</B +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="vbi_525.gif"><DIV +CLASS="CAPTION" +><P +>(1) For the purpose of this specification field 2 +starts in line 264 and not 263.5 because half line capturing is not +supported.</P +></DIV +></P +></DIV +></DIV +><DIV +CLASS="FIGURE" +><A +NAME="VBI-625" +></A +><P +><B +>Figure 4-3. ITU-R 625 line numbering</B +></P +><DIV +CLASS="MEDIAOBJECT" +><P +><IMG +SRC="vbi_625.gif"><DIV +CLASS="CAPTION" +><P +>(1) For the purpose of this specification field 2 +starts in line 314 and not 313.5 because half line capturing is not +supported.</P +></DIV +></P +></DIV +></DIV +><P +>Remember the VBI image format depends on the selected +video standard, therefore the application must choose a new standard or +query the current standard first. Attempts to read or write data ahead +of format negotiation, or after switching the video standard which may +invalidate the negotiated VBI parameters, should be refused by the +driver. A format change during active I/O is not permitted.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4571" +>4.6.4. Reading and writing VBI images</A +></H3 +><P +>To assure synchronization with the field number and easier +implementation, the smallest unit of data passed at a time is one +frame, consisting of two fields of VBI images immediately following in +memory.</P +><P +>The total size of a frame computes as follows:</P +><PRE +CLASS="PROGRAMLISTING" +>(<CODE +CLASS="STRUCTFIELD" +>count</CODE +>[0] + <CODE +CLASS="STRUCTFIELD" +>count</CODE +>[1]) * +<CODE +CLASS="STRUCTFIELD" +>samples_per_line</CODE +> * sample size in bytes</PRE +><P +>The sample size is most likely always one byte, +applications must check the <CODE +CLASS="STRUCTFIELD" +>sample_format</CODE +> +field though, to function properly with other drivers.</P +><P +>A VBI device may support <A +HREF="#RW" +>read/write</A +> and/or streaming (<A +HREF="#MMAP" +>memory mapping</A +> or <A +HREF="#USERP" +>user pointer</A +>) I/O. The latter bears the +possibility of synchronizing video and +VBI data by using buffer timestamps.</P +><P +>Remember the <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> ioctl and the first read(), +write() and select() call can be resource allocation points returning +an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code if the required hardware resources are temporarily +unavailable, for example the device is already in use by another +process.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="SLICED" +>4.7. Sliced VBI Data Interface</A +></H2 +><DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Proposal: </B +>This interface is not yet implemented in v4l2.</P +></BLOCKQUOTE +></DIV +><P +>Sliced VBI data is VBI data after demodulation by hardware +decoders. Kernel drivers shall not convert to or from raw VBI data by +software. The data is passed as short packets of fixed size covering +one scan line each. The number of packets per frame is variable.</P +><P +>Sliced VBI input and output devices are accessed through the +same character special files as raw VBI devices. Note the default +function of a <TT +CLASS="FILENAME" +>/dev/vbi</TT +> device is raw VBI +capturing or output. The sliced VBI function is only available after +calling the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4599" +>4.7.1. Querying Capabilities</A +></H3 +><P +>Devices supporting the sliced VBI capturing or output API +set the <CODE +CLASS="CONSTANT" +>V4L2_CAP_SLICED_VBI_CAPTURE</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_CAP_SLICED_VBI_OUTPUT</CODE +> flags in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +>. At least one of the read/write, +streaming or asynchronous I/O methods must be supported. VBI devices +may have a tuner or modulator.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4608" +>4.7.2. Supplemental Functions</A +></H3 +><P +>VBI devices shall support <A +HREF="#VIDEO" +>video +input or output</A +>, <A +HREF="#TUNER" +>tuner or +modulator</A +>, and <A +HREF="#CONTROL" +>controls</A +> ioctls +as needed. The <A +HREF="#STANDARD" +>video standard</A +> provide +information vital to program a VBI device, therefore must be +supported.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4615" +>4.7.3. Sliced VBI Format Negotiation</A +></H3 +><P +>To determine which data services are supported by the +hardware and which are desired by the application, the driver and application have to +negotiate the sliced VBI data format.</P +><P +>After setting the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> to <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</CODE +> +or <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</CODE +>, a +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> fills the struct <CODE +CLASS="STRUCTNAME" +>v4l2_sliced_vbi_format</CODE +> +<CODE +CLASS="STRUCTFIELD" +>sliced</CODE +> member of the +<CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> union of a struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +>.</P +><P +>Applications can request different parameters by +initializing or modifying the <CODE +CLASS="STRUCTFIELD" +>sliced</CODE +> member +and calling the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl with a pointer to the +<CODE +CLASS="STRUCTNAME" +>v4l2_format</CODE +> structure. <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>All fields +of struct <CODE +CLASS="STRUCTNAME" +>v4l2_vbi_format</CODE +> must be +initialized</I +></SPAN +>. Drivers return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code only when +the given parameters are ambiguous, otherwise they modify the +parameters according to the hardware capabilites. When the driver +allocates resources at this point, it may return an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code to +indicate the returned parameters are valid but the required resources +are currently not available. Applications must expect other resource +allocation points which may return <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> at the +<A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> ioctl and the first read(), write() and select() +call. Different file descriptors must be used to pass raw and sliced +VBI data simultaneously, if this is supported by the driver.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-SLICED-VBI-FORMAT" +></A +><P +><B +>Table 4-6. struct <CODE +CLASS="STRUCTNAME" +>v4l2_sliced_vbi_format</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>service_set</CODE +></TD +><TD +>A set of symbols defining which types of data +packets are passed. See <A +HREF="#SLICED-VBI-TYPES" +>Table 4-8</A +> for details.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>packet_size</CODE +></TD +><TD +><P +>The size of each type of packet is fixed, +however when different types of packets are exchanged between driver +and application their size can vary. This value defines the size of +the largest packet (struct <A +HREF="#V4L2-SLICED-DATA" +>v4l2_sliced_data</A +>) that will be +passed, smaller packets must be padded accordingly. When the +architecture requires special alignment of __u32 quantities the driver +shall round up <CODE +CLASS="STRUCTFIELD" +>packet_size </CODE +> as +necessary.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>io_size</CODE +></TD +><TD +>Maximum number of bytes passed by one <CODE +CLASS="FUNCTION" +>read()</CODE +> or +<CODE +CLASS="FUNCTION" +>write()</CODE +> call, and the buffer size in bytes for the <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> and +<A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl. Usually this will be +<CODE +CLASS="STRUCTFIELD" +>packet_size</CODE +> times the number of scan lines +potentially containing the data in question. On input, applications +should set this field to zero and accept the value proposed by the +driver.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +></TD +><TD +>Applications and drivers must set this field to +zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-SLICED-DATA" +></A +><P +><B +>Table 4-7. struct <CODE +CLASS="STRUCTNAME" +>v4l2_sliced_data</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>id</CODE +></TD +><TD +>One of the symbols in <A +HREF="#SLICED-VBI-TYPES" +>Table 4-8</A +> defining the type of data in this packet. A +value of zero indicates an empty packet with no payload, in this case +<CODE +CLASS="STRUCTFIELD" +>line</CODE +> and <CODE +CLASS="STRUCTFIELD" +>data</CODE +> +are undefined.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>line</CODE +></TD +><TD +>The scanning system line number this data has +been captured from, or shall be inserted at. See <A +HREF="#VBI-525" +>Figure 4-2</A +> +and <A +HREF="#VBI-625" +>Figure 4-3</A +> for valid values. Sliced VBI input drivers +can set the line number of all packets to <CODE +CLASS="CONSTANT" +>0</CODE +> if +the hardware cannot reliable identify scan lines.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>data</CODE +>[]</TD +><TD +>The packet payload. See <A +HREF="#SLICED-VBI-TYPES" +>Table 4-8</A +> for the contents and number of bytes passed +for each data type. The contents of padding bytes following up to +<CODE +CLASS="STRUCTFIELD" +>packet_size</CODE +> is undefined.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="SLICED-VBI-TYPES" +></A +><P +><B +>Table 4-8. Sliced VBI data formats</B +></P +><TABLE +BORDER="1" +WIDTH="100%" +CLASS="CALSTABLE" +><COL><COL><COL><COL><THEAD +><TR +><TH +>Symbol</TH +><TH +>Reference</TH +><TH +>Lines, usually</TH +><TH +>Payload</TH +></TR +></THEAD +><TBODY +><TR +><TD +>V4L2_SLICED_TELETEXT_B (Teletext System B)</TD +><TD +><A +HREF="#TELETEXT" +><ABBR +CLASS="ABBREV" +>TELETEXT</ABBR +></A +></TD +><TD +>PAL/SECAM line 6-22, 318-335</TD +><TD +>Last 42 of the 45 byte Teletext packet, that is +without clock run-in and framing code, lsb first transmitted.</TD +></TR +><TR +><TD +>V4L2_SLICED_VPS</TD +><TD +><A +HREF="#VPS" +><ABBR +CLASS="ABBREV" +>VPS</ABBR +></A +></TD +><TD +>PAL line 16</TD +><TD +>Byte number 3 to 15 according to Figure 9 of ETS +300 231, lsb first transmitted.</TD +></TR +><TR +><TD +>V4L2_SLICED_CAPTION_625</TD +><TD +><A +HREF="#EIA608" +><ABBR +CLASS="ABBREV" +>EIA608</ABBR +></A +></TD +><TD +>PAL line 22 (?)</TD +><TD +>First and second byte including parity bit, lsb +first transmitted.</TD +></TR +><TR +><TD +>V4L2_SLICED_WSS_625</TD +><TD +><A +HREF="#WSS" +><ABBR +CLASS="ABBREV" +>WSS</ABBR +></A +></TD +><TD +>PAL/SECAM line 23</TD +><TD +><PRE +CLASS="SCREEN" +>Byte 0 1 + msb lsb msb lsb +Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9</PRE +></TD +></TR +><TR +><TD +>V4L2_SLICED_CAPTION_525</TD +><TD +><A +HREF="#EIA608" +><ABBR +CLASS="ABBREV" +>EIA608</ABBR +></A +></TD +><TD +>NTSC line 21, 284</TD +><TD +>First and second byte including parity bit, lsb +first transmitted.</TD +></TR +><TR +><TD +>V4L2_SLICED_RESERVED</TD +><TD +> </TD +><TD +>undefined</TD +><TD +>undefined</TD +></TR +></TBODY +></TABLE +></DIV +><P +>Remember the VBI image format depends on the selected +video standard, therefore the application must choose a new standard or +query the current standard first. Attempts to read or write data ahead +of format negotiation, or after switching the video standard which may +invalidate the negotiated VBI parameters, should be refused by the +driver. A format change is not permitted during active i/o.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4760" +>4.7.4. Reading and writing sliced VBI data</A +></H3 +><P +>The smallest unit of data passed at a time is one sliced +data packet. Within the bounds of <CODE +CLASS="STRUCTFIELD" +>io_size</CODE +> +multiple packets can (and should) be passed, but no more than one +frame at a time (to keep the processing time low, for example from +reception to display of subtitles). Packets are always passed in +ascending line number order, without duplicate line numbers. If the +line numbers are unknown the driver must pass the packets in +transmitted order. Empty packets with <CODE +CLASS="STRUCTFIELD" +>id</CODE +> +set to zero can be inserted anywhere.</P +><P +>To assure synchronization and to distinguish from frame +dropping, when one frame does not contain any data in question one or +more empty packets must be passed. In streaming I/O mode one buffer of +<CODE +CLASS="STRUCTFIELD" +>io_size</CODE +> shall coincide with one video +frame. The <CODE +CLASS="STRUCTFIELD" +>id</CODE +> of unused packets must be +zero.</P +><P +>A sliced VBI device may support <A +HREF="#RW" +>read/write</A +> and/or streaming (<A +HREF="#MMAP" +>memory mapping</A +> or <A +HREF="#USERP" +>user pointer</A +>) I/O. The latter bears the +possibility of synchronizing video and VBI data by using buffer +timestamps.</P +><P +>Remember the <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> ioctl and the first read(), +write() and select() call can be resource allocation points returning +an <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code if the required hardware resources are temporarily +unavailable, for example the device is already in use by another +process.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="TTX" +>4.8. Teletext Interface</A +></H2 +><P +>This interface aims at devices receiving and demodulating +Teletext data [<A +HREF="#TELETEXT" +><ABBR +CLASS="ABBREV" +>TELETEXT</ABBR +></A +>], evaluating the +Teletext packages and storing formatted pages in cache memory. Such +devices are usually implemented as microcontrollers with serial +interface (I<SUP +>2</SUP +>C) and can be found on older +TV cards, dedicated Teletext decoding cards and home-brew devices +connected to the PC parallel port.</P +><P +>The Teletext API was designed by Martin Buck. It is defined in +the kernel header file <TT +CLASS="FILENAME" +>linux/videotext.h</TT +>, the +specification is available from <A +HREF="http://home.pages.de/~videotext/" +TARGET="_top" +>http://home.pages.de/~videotext/</A +>. (Videotext is the name of +the German public television Teletext service.) Conventional character +device file names are <TT +CLASS="FILENAME" +>/dev/vtx</TT +> and +<TT +CLASS="FILENAME" +>/dev/vttuner</TT +>, with device number 83, 0 and 83, 16 +respectively. A similar interface exists for the Philips SAA5249 +Teletext decoder [specification?] with character device file names +<TT +CLASS="FILENAME" +>/dev/tlkN</TT +>, device number 102, N.</P +><P +>Eventually the Teletext API was integrated into the V4L API +with character device file names <TT +CLASS="FILENAME" +>/dev/vtx0</TT +> to +<TT +CLASS="FILENAME" +>/dev/vtx31</TT +>, device major number 81, minor numbers +192 to 223. For reference the V4L Teletext API specification is +reproduced here in full: "Teletext interfaces talk the existing VTX +API." Teletext devices with major number 83 and 102 will be removed in +Linux 2.6.</P +><P +>There are no plans to replace the Teletext API or to integrate +it into V4L2. Please write to the Video4Linux mailing list: <A +HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" +TARGET="_top" +>https://listman.redhat.com/mailman/listinfo/video4linux-list</A +> +when the need arises.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="RADIO" +>4.9. Radio Interface</A +></H2 +><P +>This interface is intended for AM and FM (analog) radio +receivers.</P +><P +>Conventionally V4L2 radio devices are accessed through +character device special files named <TT +CLASS="FILENAME" +>/dev/radio</TT +> +and <TT +CLASS="FILENAME" +>/dev/radio0</TT +> to +<TT +CLASS="FILENAME" +>/dev/radio63</TT +> with major number 81 and minor +numbers 64 to 127.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4799" +>4.9.1. Querying Capabilities</A +></H3 +><P +>Devices supporting the radio interface set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_RADIO</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_CAP_TUNER</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> field of struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +returned by the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl. Other combinations of +capability flags are reserved for future extensions.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4808" +>4.9.2. Supplemental Functions</A +></H3 +><P +>Radio devices can support <A +HREF="#CONTROL" +>controls</A +>, and must support the <A +HREF="#TUNER" +>tuner</A +> ioctls.</P +><P +>They do not support the video input or output, audio input +or output, video standard, cropping and scaling, compression and +streaming parameter, or overlay ioctls. All other ioctls and I/O +methods are reserved for future extensions.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN4814" +>4.9.3. Programming</A +></H3 +><P +>Radio devices may have a couple audio controls (as discussed +in <A +HREF="#CONTROL" +>Section 1.8</A +>) such as a volume control, possibly custom +controls. Further all radio devices have one tuner (these are +discussed in <A +HREF="#TUNER" +>Section 1.6</A +>) with index number zero to select +the radio frequency and to determine if a monaural or FM stereo +program is received. Drivers switch automatically between AM and FM +depending on the selected frequency. The <A +HREF="#VIDIOC-G-TUNER" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_TUNER</CODE +></A +> ioctl +reports the supported frequency range.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="RDS" +>4.10. RDS Interface</A +></H2 +><P +>The Radio Data System transmits supplementary +information in binary format, for example the station name or travel +information, on a inaudible audio subcarrier of a radio program. This +interface aims at devices capable of receiving and decoding RDS +information.</P +><P +>The V4L API defines its RDS API as follows.</P +><P +>From radio devices supporting it, RDS data can be +read with the <CODE +CLASS="FUNCTION" +>read()</CODE +> function. The data is packed +in groups of three, as follows:<P +></P +><OL +TYPE="1" +><LI +><P +>First Octet Least Significant Byte of RDS +Block</P +></LI +><LI +><P +>Second Octet Most Significant Byte of RDS +Block</P +></LI +><LI +><P +>Third Octet Bit 7: Error bit. Indicates that an +uncorrectable error occurred during reception of this block. Bit 6: +Corrected bit. Indicates that an error was corrected for this data +block. Bits 5-3: Received Offset. Indicates the offset received by the +sync system. Bits 2-0: Offset Name. Indicates the offset applied to +this data.</P +></LI +></OL +></P +><P +>It was argued <SPAN +CLASS="COMMENT" +>video4linux-list@redhat.com +on 12 Nov 2002, subject "RDS/RBDS"</SPAN +> the RDS API should be +extended before integration into V4L2, no new API has been devised yet. +Please write to the Video4Linux mailing list for discussion: <A +HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" +TARGET="_top" +>https://listman.redhat.com/mailman/listinfo/video4linux-list</A +>. +Meanwhile no V4L2 driver should set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_RDS_CAPTURE</CODE +> capability flag.</P +></DIV +></DIV +><DIV +CLASS="REFERENCE" +><A +NAME="USER-FUNC" +></A +><DIV +CLASS="TITLEPAGE" +><H1 +CLASS="TITLE" +>I. Function Reference</H1 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="#FUNC-CLOSE" +>close</A +> -- Close a V4L2 device</DT +><DT +><A +HREF="#FUNC-IOCTL" +>ioctl</A +> -- Program a V4L2 device</DT +><DT +><A +HREF="#VIDIOC-CROPCAP" +>ioctl VIDIOC_CROPCAP</A +> -- Information about the video cropping and scaling abilities.</DT +><DT +><A +HREF="#VIDIOC-ENUMAUDIO" +>ioctl VIDIOC_ENUMAUDIO</A +> -- Enumerate audio inputs</DT +><DT +><A +HREF="#VIDIOC-ENUMAUDIOOUT" +>ioctl VIDIOC_ENUMAUDOUT</A +> -- Enumerate audio outputs</DT +><DT +><A +HREF="#VIDIOC-ENUM-FMT" +>ioctl VIDIOC_ENUM_FMT</A +> -- Enumerate image formats</DT +><DT +><A +HREF="#VIDIOC-ENUMINPUT" +>ioctl VIDIOC_ENUMINPUT</A +> -- Enumerate video inputs</DT +><DT +><A +HREF="#VIDIOC-ENUMOUTPUT" +>ioctl VIDIOC_ENUMOUTPUT</A +> -- Enumerate video outputs</DT +><DT +><A +HREF="#VIDIOC-ENUMSTD" +>ioctl VIDIOC_ENUMSTD</A +> -- Enumerate supported video standards</DT +><DT +><A +HREF="#VIDIOC-G-AUDIO" +>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</A +> -- Query or select the current audio input and its +attributes</DT +><DT +><A +HREF="#VIDIOC-G-AUDIOOUT" +>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</A +> -- Query or select the current audio output</DT +><DT +><A +HREF="#VIDIOC-G-COMP" +>ioctl VIDIOC_G_COMP, VIDIOC_S_COMP</A +> -- Get or set compression parameters</DT +><DT +><A +HREF="#VIDIOC-G-CROP" +>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</A +> -- Get or set the current cropping rectangle</DT +><DT +><A +HREF="#VIDIOC-G-CTRL" +>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</A +> -- Get or set the value of a control</DT +><DT +><A +HREF="#VIDIOC-G-FBUF" +>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</A +> -- Get or set frame buffer overlay parameters.</DT +><DT +><A +HREF="#VIDIOC-G-FMT" +>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</A +> -- Get or set the data format, try a format.</DT +><DT +><A +HREF="#VIDIOC-G-FREQUENCY" +>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</A +> -- Get or set tuner or modulator radio +frequency</DT +><DT +><A +HREF="#VIDIOC-G-INPUT" +>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</A +> -- Query or select the current video input</DT +><DT +><A +HREF="#VIDIOC-G-JPEGCOMP" +>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</A +> -- </DT +><DT +><A +HREF="#VIDIOC-G-MODULATOR" +>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</A +> -- Get or set modulator attributes</DT +><DT +><A +HREF="#VIDIOC-G-OUTPUT" +>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</A +> -- Query or select the current video output</DT +><DT +><A +HREF="#VIDIOC-G-PARM" +>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</A +> -- Get or set streaming parameters</DT +><DT +><A +HREF="#VIDIOC-G-PRIORITY" +>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</A +> -- Query or request the access priority associated with a +file descriptor</DT +><DT +><A +HREF="#VIDIOC-G-STD" +>ioctl VIDIOC_G_STD, VIDIOC_S_STD</A +> -- Query or select the video standard of the current input</DT +><DT +><A +HREF="#VIDIOC-G-TUNER" +>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</A +> -- Get or set tuner attributes</DT +><DT +><A +HREF="#VIDIOC-OVERLAY" +>ioctl VIDIOC_OVERLAY</A +> -- Start or stop video overlay</DT +><DT +><A +HREF="#VIDIOC-QBUF" +>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</A +> -- Exchange a buffer with the driver</DT +><DT +><A +HREF="#VIDIOC-QUERYBUF" +>ioctl VIDIOC_QUERYBUF</A +> -- Query the status of a buffer</DT +><DT +><A +HREF="#VIDIOC-QUERYCAP" +>ioctl VIDIOC_QUERYCAP</A +> -- Query device capabilities</DT +><DT +><A +HREF="#VIDIOC-QUERYCTRL" +>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</A +> -- Enumerate controls and menu control items</DT +><DT +><A +HREF="#VIDIOC-QUERYSTD" +>ioctl VIDIOC_QUERYSTD</A +> -- Sense the video standard received by the current input</DT +><DT +><A +HREF="#VIDIOC-REQBUFS" +>ioctl VIDIOC_REQBUFS</A +> -- Initiate Memory Mapping or User Pointer I/O</DT +><DT +><A +HREF="#VIDIOC-STREAMON" +>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</A +> -- Start or stop streaming I/O.</DT +><DT +><A +HREF="#FUNC-MMAP" +>mmap</A +> -- Map device memory into application address space</DT +><DT +><A +HREF="#FUNC-MUNMAP" +>munmap</A +> -- Unmap device memory</DT +><DT +><A +HREF="#FUNC-OPEN" +>open</A +> -- Open a V4L2 device</DT +><DT +><A +HREF="#FUNC-POLL" +>poll</A +> -- Wait for some event on a file descriptor</DT +><DT +><A +HREF="#FUNC-READ" +>read</A +> -- Read from a V4L2 device</DT +><DT +><A +HREF="#FUNC-SELECT" +>select</A +> -- Synchronous I/O multiplexing</DT +><DT +><A +HREF="#FUNC-WRITE" +>write</A +> -- Write to a V4L2 device</DT +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-CLOSE" +></A +>close</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN4841" +></A +><H2 +>Name</H2 +>close -- Close a V4L2 device</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN4844" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN4845" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <unistd.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int close</CODE +>(int fd);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4852" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4862" +></A +><H2 +>Description</H2 +><P +>Closes the device. Any I/O in progress is terminated and +resources associated with the file descriptor are freed. However data +format parameters, current input or output, control values or other +properties remain unchanged.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4865" +></A +><H2 +>Return Value</H2 +><P +>The function returns <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> on +success, <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> on failure and the +<VAR +CLASS="VARNAME" +>errno</VAR +> is set appropriately. Possible error +codes:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EBADF</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is not a valid open file +descriptor.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-IOCTL" +></A +>ioctl</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN4879" +></A +><H2 +>Name</H2 +>ioctl -- Program a V4L2 device</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN4882" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN4883" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <sys/ioctl.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, void *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4894" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>V4L2 ioctl request code as defined in the <A +HREF="#VIDEODEV" +>videodev.h</A +> header file, for example +VIDIOC_QUERYCAP.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +>Pointer to a function parameter, usually a structure.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4915" +></A +><H2 +>Description</H2 +><P +>The <CODE +CLASS="FUNCTION" +>ioctl()</CODE +> function is used to program +V4L2 devices. The argument <VAR +CLASS="PARAMETER" +>fd</VAR +> must be an open +file descriptor. An ioctl <VAR +CLASS="PARAMETER" +>request</VAR +> has encoded +in it whether the argument is an input, output or read/write +parameter, and the size of the argument <VAR +CLASS="PARAMETER" +>argp</VAR +> in +bytes. Macros and defines specifying V4L2 ioctl requests are located +in the <A +HREF="#VIDEODEV" +>videodev.h</A +> header file. +Applications should use their own copy, not include the version in the +kernel sources on the system they compile on. All V4L2 ioctl requests, +their respective function and parameters are specified in <A +HREF="#USER-FUNC" +>Reference I, <I +>Function Reference</I +></A +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4924" +></A +><H2 +>Return Value</H2 +><P +>On success the <CODE +CLASS="FUNCTION" +>ioctl()</CODE +> function returns +<SPAN +CLASS="RETURNVALUE" +>0</SPAN +> and does not reset the +<VAR +CLASS="VARNAME" +>errno</VAR +> variable. On failure +<SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> is returned, when the ioctl takes an +output or read/write parameter it remains unmodified, and the +<VAR +CLASS="VARNAME" +>errno</VAR +> variable is set appropriately. See below for +possible error codes. Generic errors like <SPAN +CLASS="ERRORCODE" +>EBADF</SPAN +> +or <SPAN +CLASS="ERRORCODE" +>EFAULT</SPAN +> are not listed in the sections +discussing individual ioctl requests.</P +><P +>Note ioctls may return undefined error codes. Since errors +may have side effects such as a driver reset applications should +abort on unexpected errors.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EBADF</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is not a valid open file +descriptor.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The property cannot be changed right now. Typically +this error code is returned when I/O is in progress or the driver +supports multiple opens and another process locked the property.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EFAULT</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>argp</VAR +> references an inaccessible +memory area.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENOTTY</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is not associated with a +character special device.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The <VAR +CLASS="PARAMETER" +>request</VAR +> or the data pointed +to by <VAR +CLASS="PARAMETER" +>argp</VAR +> is not valid. This is a very common +error code, see the individual ioctl requests listed in <A +HREF="#USER-FUNC" +>Reference I, <I +>Function Reference</I +></A +> for actual causes.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENOMEM</SPAN +></DT +><DD +><P +>Insufficient memory to complete the request.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ERANGE</SPAN +></DT +><DD +><P +>The application attempted to set a control with the +<A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +> ioctl to a value which is out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-CROPCAP" +></A +>ioctl VIDIOC_CROPCAP</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN4980" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_CROPCAP -- Information about the video cropping and scaling abilities.</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN4983" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN4984" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_cropcap +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN4994" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_CROPCAP</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5014" +></A +><H2 +>Description</H2 +><P +>Applications use this function to query the cropping +limits, the pixel aspect of images and to calculate scale factors. +They set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a v4l2_cropcap +structure to the respective buffer (stream) type and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +> ioctl with a pointer to this +structure. Drivers fill the rest of the structure. The results are +constant except when switching the video standard. Remember this +switch can occur implicit when switching the video input or +output.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CROPCAP" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_cropcap</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the data stream, set by the application. +Only these types are valid here: +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +>, and custom (driver +defined) types with code <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> +and higher.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-RECT-CROP" +>v4l2_rect</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>bounds</CODE +></TD +><TD +>Defines the window within capturing or output is +possible, this may exclude for example the horizontal and vertical +blanking areas. The cropping rectangle cannot exceed these limits. +Width and height are defined in pixels, the driver writer is free to +choose origin and units of the coordinate system in the analog +domain.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-RECT-CROP" +>v4l2_rect</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>defrect</CODE +></TD +><TD +>Default cropping rectangle, it shall cover the +"whole picture". Assuming pixel aspect 1/1 this could be for example a +640 × 480 rectangle for NTSC, a +768 × 576 rectangle for PAL and SECAM centered over +the active picture area. The same co-ordinate system as for + <CODE +CLASS="STRUCTFIELD" +>bounds</CODE +> is used.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>pixelaspect</CODE +></TD +><TD +><P +>This is the pixel aspect (y / x) when no +scaling is applied, the ratio of the actual sampling +frequency and the frequency required to get square +pixels.</P +><P +>When cropping coordinates refer to square pixels, +the driver sets <CODE +CLASS="STRUCTFIELD" +>pixelaspect</CODE +> to 1/1. Other +common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled +according to [<A +HREF="#ITU601" +><ABBR +CLASS="ABBREV" +>ITU601</ABBR +></A +>].</P +></TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-RECT-CROP" +></A +><P +><B +>Table 2. struct <CODE +CLASS="STRUCTNAME" +>v4l2_rect</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>left</CODE +></TD +><TD +>Horizontal offset of the top, left corner of the +rectangle, in pixels.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>top</CODE +></TD +><TD +>Vertical offset of the top, left corner of the +rectangle, in pixels.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>width</CODE +></TD +><TD +>Width of the rectangle, in pixels.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>height</CODE +></TD +><TD +>Height of the rectangle, in pixels. Width +and height cannot be negative, the fields are signed for +hysterical reasons. <P +CLASS="COMMENT" +>video4linux-list@redhat.com +on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5"</P +></TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5091" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is +invalid or the ioctl is not supported. This is not permitted for +video capture, output and overlay devices, which must support +<CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +>.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-ENUMAUDIO" +></A +>ioctl VIDIOC_ENUMAUDIO</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5107" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_ENUMAUDIO -- Enumerate audio inputs</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5110" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5111" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_audio *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5121" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_ENUMAUDIO</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5141" +></A +><H2 +>Description</H2 +><P +>To query the attributes of an audio input applications +initialize the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field and zero out the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> +and call the <CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDIO</CODE +> ioctl with a pointer +to this structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all audio +inputs applications shall begin at index zero, incrementing by one +until the driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><P +>See <A +HREF="#VIDIOC-G-AUDIO" +>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</A +> for a description of +struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5153" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The number of the audio input is out of bounds, or +there are no audio inputs at all and this ioctl is not +supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-ENUMAUDIOOUT" +></A +>ioctl VIDIOC_ENUMAUDOUT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5166" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_ENUMAUDOUT -- Enumerate audio outputs</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5169" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5170" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_audioout *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5180" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_ENUMAUDOUT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5200" +></A +><H2 +>Description</H2 +><P +>To query the attributes of an audio output applications +initialize the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field and zero out the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +> and +call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDOUT</CODE +> ioctl with a pointer +to this structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all audio +outputs applications shall begin at index zero, incrementing by one +until the driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><P +>Note connectors on a TV card to loop back the received audio +signal to a sound card are not audio outputs in this sense.</P +><P +>See <A +HREF="#VIDIOC-G-AUDIOOUT" +>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</A +> for a description of +struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5213" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The number of the audio output is out of bounds, or +there are no audio outputs at all and this ioctl is not +supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-ENUM-FMT" +></A +>ioctl VIDIOC_ENUM_FMT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5226" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_ENUM_FMT -- Enumerate image formats</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5229" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5230" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_fmtdesc +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5240" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_ENUM_FMT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5260" +></A +><H2 +>Description</H2 +><P +>To enumerate image formats applications initialize the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> and <CODE +CLASS="STRUCTFIELD" +>index</CODE +> +field of struct <A +HREF="#V4L2-FMTDESC" +>v4l2_fmtdesc</A +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_ENUM_FMT</CODE +> ioctl with a pointer to this +structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code. All formats are enumerable by beginning at index zero and +incrementing by one until <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> is +returned.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-FMTDESC" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_fmtdesc</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Number of the format in the enumeration, set by +the application. This is in no way related to the <CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +> field.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the data stream, set by the application. +Only these types are valid here: +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +>, and custom (driver +defined) types with code <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> +and higher.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>flags</CODE +></TD +><TD +>See <A +HREF="#FMTDESC-FLAGS" +>Table 2</A +></TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>description</CODE +>[32]</TD +><TD +>Description of the format, a NUL-terminated ASCII +string. This information is intended for the user, for example: "YUV +4:2:2".</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +></TD +><TD +>The image format identifier. This is a +four character code as computed by the v4l2_fourcc() +macro:</TD +></TR +><TR +><TD +COLSPAN="3" +><P +><PRE +CLASS="PROGRAMLISTING" +>#define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))</PRE +></P +><P +>Several image formats are already +defined by this specification in <A +HREF="#PIXFMT" +>Chapter 2</A +>. Note these +codes are not the same as those used in the Windows world.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers must set +the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="FMTDESC-FLAGS" +></A +><P +><B +>Table 2. Image Format Description Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_COMPRESSED</CODE +></TD +><TD +>0x0001</TD +><TD +>This is a compressed format.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5334" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-FMTDESC" +>v4l2_fmtdesc</A +> <CODE +CLASS="STRUCTFIELD" +>type</CODE +> +is not supported or the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> is out of +bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-ENUMINPUT" +></A +>ioctl VIDIOC_ENUMINPUT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5350" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_ENUMINPUT -- Enumerate video inputs</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5353" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5354" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_input +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5364" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_ENUMINPUT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5384" +></A +><H2 +>Description</H2 +><P +>To query the attributes of a video input applications +initialize the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field of struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> +and call the <CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +> ioctl with a +pointer to this structure. Drivers fill the rest of the structure or +return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all +inputs applications shall begin at index zero, incrementing by one +until the driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-INPUT" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_input</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Identifies the input, set by the +application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the video input, a NUL-terminated ASCII +string, for example: "Vin (Composite 2)". This information is intended +for the user, preferably the connector label on the device itself.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the input, see <A +HREF="#INPUT-TYPE" +>Table 2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>audioset</CODE +></TD +><TD +>Video inputs combine with zero or more audio +inputs. For example one composite video connectors may exist, but two +audio connectors. On the other hand, video from a tuner will likely +combine only with audio from the same tuner. Devices with N audio +inputs number them 0 … N-1 with N ≤ 32. Each bit position of +<CODE +CLASS="STRUCTFIELD" +>audioset</CODE +> represents one audio input. For +details on audio inputs and how to switch see <A +HREF="#AUDIO" +>Section 1.5</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>tuner</CODE +></TD +><TD +>Capture devices can have zero or more tuners (RF +demodulators). When the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is set to +<CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_TUNER</CODE +> this is an RF connector and +this field identifies the tuner. It corresponds to +struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> field <CODE +CLASS="STRUCTFIELD" +>index</CODE +>. For details on +tuners see <A +HREF="#TUNER" +>Section 1.6</A +>.</TD +></TR +><TR +><TD +><A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>std</CODE +></TD +><TD +>Every video input supports one or more different +video standards. This field is a set of all supported standards. For +details on video standards and how to switch see <A +HREF="#STANDARD" +>Section 1.7</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>status</CODE +></TD +><TD +>This field provides status information about the +input. See <A +HREF="#INPUT-STATUS" +>Table 3</A +> for flags. +<CODE +CLASS="STRUCTFIELD" +>status</CODE +> is only valid when this is the +current input.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers must set +the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="INPUT-TYPE" +></A +><P +><B +>Table 2. Input Types</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_TUNER</CODE +></TD +><TD +>1</TD +><TD +>This input uses a tuner (RF demodulator).</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_CAMERA</CODE +></TD +><TD +>2</TD +><TD +>Analog baseband input, for example CVBS / +Composite Video, S-Video, RGB.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="INPUT-STATUS" +></A +><P +><B +>Table 3. Input Status Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="33%" +TITLE="C1"><COL +WIDTH="33%" +ALIGN="CENTER" +TITLE="C2"><COL +WIDTH="33%" +TITLE="C3"><TBODY +><TR +><TD +COLSPAN="3" +ALIGN="LEFT" +>General</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_POWER</CODE +></TD +><TD +>0x00000001</TD +><TD +>Attached device is off.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_SIGNAL</CODE +></TD +><TD +>0x00000002</TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_COLOR</CODE +></TD +><TD +>0x00000004</TD +><TD +> </TD +></TR +><TR +><TD +COLSPAN="3" +ALIGN="LEFT" +>Analog Video</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_H_LOCK</CODE +></TD +><TD +>0x00000100</TD +><TD +>No horizontal sync lock.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_COLOR_KILL</CODE +></TD +><TD +>0x00000200</TD +><TD +>The color killer is a circuit that shuts off the +color decoding when it cannot find the color burst. This flag +indicates if the color killer is <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>enabled</I +></SPAN +>, while +<CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_COLOR</CODE +> is set when no color is +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>detected</I +></SPAN +>.</TD +></TR +><TR +><TD +COLSPAN="3" +ALIGN="LEFT" +>Digital Video</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_SYNC</CODE +></TD +><TD +>0x00010000</TD +><TD +>No synchronization lock.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_EQU</CODE +></TD +><TD +>0x00020000</TD +><TD +>No equalizer lock.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_CARRIER</CODE +></TD +><TD +>0x00040000</TD +><TD +>Carrier recovery failed.</TD +></TR +><TR +><TD +COLSPAN="3" +ALIGN="LEFT" +>VCR and Set-Top Box</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_MACROVISION</CODE +></TD +><TD +>0x01000000</TD +><TD +>Macrovision is an analog copy protection system +mangling the video signal to confuse video recorders. When this +flag is set Macrovision protection has been detected.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_NO_ACCESS</CODE +></TD +><TD +>0x02000000</TD +><TD +>Conditional access denied.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_IN_ST_VTR</CODE +></TD +><TD +>0x04000000</TD +><TD +>VTR time constant. [?]</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5545" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> is +out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-ENUMOUTPUT" +></A +>ioctl VIDIOC_ENUMOUTPUT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5560" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_ENUMOUTPUT -- Enumerate video outputs</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5563" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5564" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_output *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5574" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_ENUMOUTPUT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5594" +></A +><H2 +>Description</H2 +><P +>To query the attributes of a video outputs applications +initialize the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field of struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> +and call the <CODE +CLASS="CONSTANT" +>VIDIOC_ENUMOUTPUT</CODE +> ioctl with a +pointer to this structure. Drivers fill the rest of the structure or +return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all +outputs applications shall begin at index zero, incrementing by one +until the driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-OUTPUT" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_output</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Identifies the output, set by the +application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the video output, a NUL-terminated ASCII +string, for example: "Vout". This information is intended for the +user, preferably the connector label on the device itself.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the output, see <A +HREF="#OUTPUT-TYPE" +>Table 2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>audioset</CODE +></TD +><TD +>Video outputs combine with zero or more audio +outputs. For example one composite video connectors may exist, but two +audio connectors. On the other hand, video to a modulator will likely +combine only with audio to the same modulator. Devices with N audio +outputs number them 0 … N-1 with N ≤ 32. Each bit position of +<CODE +CLASS="STRUCTFIELD" +>audioset</CODE +> represents one audio output. For +details on audio outputs and how to switch see <A +HREF="#AUDIO" +>Section 1.5</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>modulator</CODE +></TD +><TD +>Output devices can have zero or more RF modulators. +When the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_OUTPUT_TYPE_MODULATOR</CODE +> this is an RF +connector and this field identifies the modulator. It corresponds to +struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> field <CODE +CLASS="STRUCTFIELD" +>index</CODE +>. For details +on modulators see <A +HREF="#TUNER" +>Section 1.6</A +>.</TD +></TR +><TR +><TD +><A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>std</CODE +></TD +><TD +>Every video output supports one or more different +video standards. This field is a set of all supported standards. For +details on video standards and how to switch see <A +HREF="#STANDARD" +>Section 1.7</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers must set +the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="OUTPUT-TYPE" +></A +><P +><B +>Table 2. Output Type</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_OUTPUT_TYPE_MODULATOR</CODE +></TD +><TD +>1</TD +><TD +>This output is an analog TV modulator.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_OUTPUT_TYPE_ANALOG</CODE +></TD +><TD +>2</TD +><TD +>Analog baseband output, for example Composite / +CVBS, S-Video, RGB.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</CODE +></TD +><TD +>3</TD +><TD +>[?]</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5679" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> +is out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-ENUMSTD" +></A +>ioctl VIDIOC_ENUMSTD</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5694" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_ENUMSTD -- Enumerate supported video standards</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5697" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5698" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_standard *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5708" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_ENUMSTD</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5728" +></A +><H2 +>Description</H2 +><P +>To query the attributes of a video standard, +especially a custom (driver defined) one, applications initialize the +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field of struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +> ioctl with a pointer to this +structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all standards +applications shall begin at index zero, incrementing by one until the +driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>. Drivers may enumerate a +different set of standards after switching the video input or +output.<A +NAME="AEN5736" +HREF="#FTN.AEN5736" +><SPAN +CLASS="footnote" +>[24]</SPAN +></A +></P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-STANDARD" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_standard</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Number of the video standard, set by the +application.</TD +></TR +><TR +><TD +><A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>id</CODE +></TD +><TD +>The bits in this field identify the standard as +one of the common standards listed in <A +HREF="#V4L2-STD-ID" +>Table 3</A +>, +or if bits 32 to 63 are set as custom standards. Multiple bits can be +set if the hardware does not distinguish between these standards, +however separate indices do not indicate the opposite. The +<CODE +CLASS="STRUCTFIELD" +>id</CODE +> must be unique. No other enumerated +<CODE +CLASS="STRUCTNAME" +>v4l2_standard</CODE +> structure, for this input or +output anyway, can contain the same set of bits.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[24]</TD +><TD +>Name of the standard, a NUL-terminated ASCII +string, for example: "PAL-B/G", "NTSC Japan". This information is +intended for the user.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>frameperiod</CODE +></TD +><TD +>The frame period (not field period) is numerator +/ denominator. For example M/NTSC has a frame period of 1001 / +30000 seconds.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>framelines</CODE +></TD +><TD +>Total lines per frame including blanking, +e. g. 625 for B/PAL.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers must set +the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-FRACT" +></A +><P +><B +>Table 2. struct <CODE +CLASS="STRUCTNAME" +>v4l2_fract</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>numerator</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>denominator</CODE +></TD +><TD +> </TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-STD-ID" +></A +><P +><B +>Table 3. typedef <CODE +CLASS="STRUCTNAME" +>v4l2_std_id</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u64</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>v4l2_std_id</CODE +></TD +><TD +>This type is a set, each bit representing +another video standard as listed below and in <A +HREF="#VIDEO-STANDARDS" +>Table 4</A +>.</TD +></TR +><TR +><TD +COLSPAN="3" +><P +><CODE +CLASS="CONSTANT" +>V4L2_STD_PAL_60</CODE +> is a +hybrid standard with 525 lines, 60 Hz refresh rate, but PAL +color modulation. Some PAL video recorders can play back NTSC tapes in this +mode for display on 50/60 Hz agnostic PAL TVs.</P +><P +><CODE +CLASS="CONSTANT" +>V4L2_STD_ATSC_8_VSB</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_STD_ATSC_16_VSB</CODE +> are the U.S. terrestrial +digital TV standards. The present V4L2 API makes no provisions for +digital TV reception, so no driver will report these standards +yet. See also the Linux DVB API at +<A +HREF="http://linuxtv.org" +TARGET="_top" +>http://linuxtv.org</A +>.</P +><P +>Bit +32 to 63 are reserved for custom (driver defined) video +standards.</P +></TD +></TR +></TBODY +></TABLE +></DIV +><P +><PRE +CLASS="PROGRAMLISTING" +>#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) +#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) +#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) +#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) +#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) +#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) +#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) +#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) + +#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) +#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) +#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) +#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) + +#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) +#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) + +#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) +#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) +#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) +#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) +#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) +#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) +#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) + +/* ATSC/HDTV */ +#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) +#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) + +#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ + V4L2_STD_PAL_B1 |\ + V4L2_STD_PAL_G) +#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ + V4L2_STD_PAL_D1 |\ + V4L2_STD_PAL_K) +#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ + V4L2_STD_PAL_DK |\ + V4L2_STD_PAL_H |\ + V4L2_STD_PAL_I) +#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ + V4L2_STD_NTSC_M_JP) +#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ + V4L2_STD_SECAM_D |\ + V4L2_STD_SECAM_G |\ + V4L2_STD_SECAM_H |\ + V4L2_STD_SECAM_K |\ + V4L2_STD_SECAM_K1 |\ + V4L2_STD_SECAM_L) + +#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ + V4L2_STD_PAL_60 |\ + V4L2_STD_NTSC) +#define V4L2_STD_625_50 (V4L2_STD_PAL |\ + V4L2_STD_PAL_N |\ + V4L2_STD_PAL_Nc |\ + V4L2_STD_SECAM) + +#define V4L2_STD_UNKNOWN 0 +#define V4L2_STD_ALL (V4L2_STD_525_60 |\ + V4L2_STD_625_50)</PRE +></P +><DIV +CLASS="TABLE" +><A +NAME="VIDEO-STANDARDS" +></A +><P +><B +>Table 4. Video Standards (based on [<A +HREF="#ITU470" +><ABBR +CLASS="ABBREV" +>ITU470</ABBR +></A +>])</B +></P +><TABLE +BORDER="1" +RULES="all" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="12%" +ALIGN="LEFT" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="12%" +TITLE="C3"><COL +WIDTH="12%" +TITLE="C4"><COL +WIDTH="12%" +TITLE="C5"><COL><COL +WIDTH="12%" +TITLE="C7"><COL><COL +WIDTH="12%" +TITLE="C9"><COL><COL><COL +WIDTH="12%" +TITLE="C12"><THEAD +><TR +><TH +>Characteristics</TH +><TH +><P +>M/NTSC<SUP +>a</SUP +></P +></TH +><TH +>M/PAL</TH +><TH +><P +>N/PAL<SUP +>b</SUP +></P +></TH +><TH +ALIGN="CENTER" +>B, B1, G/PAL</TH +><TH +ALIGN="CENTER" +>D, D1, K/PAL</TH +><TH +ALIGN="CENTER" +>H/PAL</TH +><TH +ALIGN="CENTER" +>I/PAL</TH +><TH +ALIGN="CENTER" +>B, G/SECAM</TH +><TH +ALIGN="CENTER" +>D, K/SECAM</TH +><TH +ALIGN="CENTER" +>K1/SECAM</TH +><TH +ALIGN="CENTER" +>L/SECAM</TH +></TR +></THEAD +><TBODY +><TR +><TD +>Frame lines</TD +><TD +COLSPAN="2" +ALIGN="CENTER" +>525</TD +><TD +COLSPAN="9" +ALIGN="CENTER" +>625</TD +></TR +><TR +><TD +>Frame period (s)</TD +><TD +COLSPAN="2" +ALIGN="CENTER" +>1001/30000</TD +><TD +COLSPAN="9" +ALIGN="CENTER" +>1/25</TD +></TR +><TR +><TD +>Chrominance sub-carrier frequency (Hz)</TD +><TD +>3579545 ± 10</TD +><TD +>3579611.49 ± 10</TD +><TD +>4433618.75 ± 5 (3582056.25 +± 5)</TD +><TD +COLSPAN="3" +ALIGN="CENTER" +>4433618.75 ± 5</TD +><TD +>4433618.75 ± 1</TD +><TD +COLSPAN="4" +ALIGN="CENTER" +>f<SUB +>OR</SUB +> = +4406250 ± 2000, f<SUB +>OB</SUB +> = 4250000 +± 2000</TD +></TR +><TR +><TD +>Nominal radio-frequency channel bandwidth +(MHz)</TD +><TD +>6</TD +><TD +>6</TD +><TD +>6</TD +><TD +>B: 7; B1, G: 8</TD +><TD +>8</TD +><TD +>8</TD +><TD +>8</TD +><TD +>8</TD +><TD +>8</TD +><TD +>8</TD +><TD +>8</TD +></TR +><TR +><TD +>Sound carrier relative to vision carrier +(MHz)</TD +><TD +>+ 4.5</TD +><TD +>+ 4.5</TD +><TD +>+ 4.5</TD +><TD +><P +>+ 5.5 ± 0.001 +<SUP +>c</SUP +> <SUP +>d</SUP +> <SUP +>e</SUP +> <SUP +>f</SUP +></P +></TD +><TD +>+ 6.5 ± 0.001</TD +><TD +>+ 5.5</TD +><TD +>+ 5.9996 ± 0.0005</TD +><TD +>+ 5.5 ± 0.001</TD +><TD +>+ 6.5 ± 0.001</TD +><TD +>+ 6.5</TD +><TD +><P +>+ 6.5 <SUP +>g</SUP +></P +></TD +></TR +></TBODY +><TR +><TD +COLSPAN="12" +>Notes:<BR><A +NAME="FTN.AEN5849" +>a. </A +>Japan uses a standard +similar to M/NTSC +(V4L2_STD_NTSC_M_JP).<BR><A +NAME="FTN.AEN5854" +>b. </A +> The values in +brackets apply to the combination N/PAL a.k.a. +N<SUB +>C</SUB +> used in Argentina +(V4L2_STD_PAL_Nc).<BR><A +NAME="FTN.AEN5904" +>c. </A +>In the Federal Republic of Germany, Austria, Italy, +the Netherlands, Slovakia and Switzerland a system of two sound +carriers is used, the frequency of the second carrier being +242.1875 kHz above the frequency of the first sound carrier. For +stereophonic sound transmissions a similar system is used in +Australia.<BR><A +NAME="FTN.AEN5906" +>d. </A +>New Zealand uses a sound +carrier displaced 5.4996 ± 0.0005 MHz from the vision +carrier.<BR><A +NAME="FTN.AEN5908" +>e. </A +>In Denmark, Finland, New +Zealand, Sweden and Spain a system of two sound carriers is used. In +Iceland, Norway and Poland the same system is being introduced. The +second carrier is 5.85 MHz above the vision carrier and is DQPSK +modulated with 728 kbit/s sound and data multiplex. (NICAM +system)<BR><A +NAME="FTN.AEN5910" +>f. </A +>In the United Kingdom, a +system of two sound carriers is used. The second sound carrier is +6.552 MHz above the vision carrier and is DQPSK modulated with a +728 kbit/s sound and data multiplex able to carry two sound +channels. (NICAM system)<BR><A +NAME="FTN.AEN5920" +>g. </A +>In France, a +digital carrier 5.85 MHz away from the vision carrier may be used in +addition to the main sound carrier. It is modulated in differentially +encoded QPSK with a 728 kbit/s sound and data multiplexer capable of +carrying two sound channels. (NICAM +system)<BR></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5922" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> +is out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-AUDIO" +></A +>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN5939" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_AUDIO, ioctl VIDIOC_S_AUDIO -- Query or select the current audio input and its +attributes</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN5943" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5944" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_audio *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN5954" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_audio *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5964" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN5984" +></A +><H2 +>Description</H2 +><P +>To query the current audio input applications zero out the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> +and call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +> ioctl with a pointer +to this structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the device has no audio inputs, or none which combine +with the current video input.</P +><P +>Audio inputs have one writable property, the audio mode. To +select the current audio input <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>and</I +></SPAN +> change the +audio mode, applications initialize the +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> and <CODE +CLASS="STRUCTFIELD" +>mode</CODE +> +fields, and the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a +<CODE +CLASS="STRUCTNAME" +>v4l2_audio</CODE +> structure and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDIO</CODE +> ioctl. Drivers may switch to a +different audio mode if the request cannot be satisfied. However, this +is a write-only ioctl, it does not return the actual new audio +mode.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-AUDIO" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_audio</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Identifies the audio input, set by the +driver or application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the audio input, a NUL-terminated ASCII +string, for example: "Line In". This information is intended for the +user, preferably the connector label on the device itself.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +>Audio capability flags, see <A +HREF="#AUDIO-CAPABILITY" +>Table 2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>mode</CODE +></TD +><TD +>Audio mode set by drivers and applications (on + <CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDIO</CODE +> ioctl), see <A +HREF="#AUDIO-MODE" +>Table 3</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[2]</TD +><TD +>Reserved for future extensions. Drivers and +applications must set the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="AUDIO-CAPABILITY" +></A +><P +><B +>Table 2. Audio Capability Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_AUDCAP_STEREO</CODE +></TD +><TD +>0x00001</TD +><TD +>This is a stereo input. The flag is intended to +automatically disable stereo recording etc. when the signal is always +monaural. The API provides no means to detect if stereo is +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>received</I +></SPAN +>, unless the audio input belongs to a +tuner.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_AUDCAP_AVL</CODE +></TD +><TD +>0x00002</TD +><TD +>Automatic Volume Level mode is supported.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="AUDIO-MODE" +></A +><P +><B +>Table 3. Audio Modes</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_AUDMODE_AVL</CODE +></TD +><TD +>0x00001</TD +><TD +>AVL mode is on.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6067" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>No audio inputs combine with the current video input, +or the number of the selected audio input is out of bounds or it does +not combine, or there are no audio inputs at all and the ioctl is not +supported.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>I/O is in progress, the input cannot be +switched.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-AUDIOOUT" +></A +>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6087" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_AUDOUT, ioctl VIDIOC_S_AUDOUT -- Query or select the current audio output</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6091" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6092" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_audioout *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6102" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_audioout *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6112" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6132" +></A +><H2 +>Description</H2 +><P +>To query the current audio output applications zero out the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +> and +call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDOUT</CODE +> ioctl with a pointer +to this structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the device has no audio inputs, or none which combine +with the current video output.</P +><P +>Audio outputs have no writable properties. Nevertheless, to +select the current audio output applications can initialize the +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field and +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array (which in the future may +contain writable properties) of a +<CODE +CLASS="STRUCTNAME" +>v4l2_audioout</CODE +> structure and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDOUT</CODE +> ioctl. Drivers switch to the +requested output or return the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of +bounds. This is a write-only ioctl, it does not return the current +audio output attributes as <CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDOUT</CODE +> +does.</P +><P +>Note connectors on a TV card to loop back the received audio +signal to a sound card are not audio outputs in this sense.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-AUDIOOUT" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_audioout</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Identifies the audio output, set by the +driver or application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the audio output, a NUL-terminated ASCII +string, for example: "Line Out". This information is intended for the +user, preferably the connector label on the device itself.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +>Audio capability flags, none defined yet. Drivers +must set this field to zero.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>mode</CODE +></TD +><TD +>Audio mode, none defined yet. Drivers and +applications (on <CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDOUT</CODE +>) must set this +field to zero.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[2]</TD +><TD +>Reserved for future extensions. Drivers and +applications must set the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6182" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>No audio outputs combine with the current video +output, or the number of the selected audio output is out of bounds or +it does not combine, or there are no audio outputs at all and the +ioctl is not supported.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>I/O is in progress, the output cannot be +switched.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-COMP" +></A +>ioctl VIDIOC_G_COMP, VIDIOC_S_COMP</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6202" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_COMP, ioctl VIDIOC_S_COMP -- Get or set compression parameters</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6206" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6207" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, v4l2_compression *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6217" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_COMP, VIDIOC_S_COMP</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6237" +></A +><H2 +>Description</H2 +><P +>[to do]</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-COMPRESSION" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_compression</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>quality</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>keyframerate</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>pframerate</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[5]</TD +><TD +> </TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6269" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>This ioctl is not supported</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-CROP" +></A +>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6284" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_CROP, ioctl VIDIOC_S_CROP -- Get or set the current cropping rectangle</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6288" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6289" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_crop *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6299" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_crop *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6309" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_CROP, VIDIOC_S_CROP</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6329" +></A +><H2 +>Description</H2 +><P +>To query the cropping rectangle size and position +applications set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a +<CODE +CLASS="STRUCTNAME" +>v4l2_crop</CODE +> structure to the respective buffer +(stream) type and call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +> ioctl +with a pointer to this structure. The driver fills the rest of the +structure or returns the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code if cropping is not supported.</P +><P +>To change the cropping rectangle applications initialize the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> and struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> substructure named +<CODE +CLASS="STRUCTFIELD" +>c</CODE +> of a v4l2_crop structure and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +> ioctl with a pointer to this +structure.</P +><P +>The driver first adjusts the requested dimensions against +hardware limits, i. e. the bounds given by the capture/output window, +and it rounds to the closest possible values of horizontal and +vertical offset, width and height. In particular the driver must round +the vertical offset of the cropping rectangle to frame lines modulo +two, such that the field order cannot be confused.</P +><P +>Second the driver adjusts the image size (the opposite +rectangle of the scaling process, source or target depending on the +data direction) to the closest size possible while maintaining the +current horizontal and vertical scaling factor.</P +><P +>Finally the driver programs the hardware with the actual +cropping and image parameters. <CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +> is a +write-only ioctl, it does not return the actual parameters. To query +them applications must call <CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +> and +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +>. When the parameters are unsuitable the application may +modify the cropping or image parameters and repeat the cycle until +satisfactory parameters have been negotiated.</P +><P +>When cropping is not supported then no parameters are +changed and <CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +> returns the +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CROP" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_crop</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the data stream, set by the application. +Only these types are valid here: <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +>, and custom (driver +defined) types with code <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> +and higher.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>c</CODE +></TD +><TD +>Cropping rectangle. The same co-ordinate system as +for struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> <CODE +CLASS="STRUCTFIELD" +>bounds</CODE +> is used.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6378" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>Cropping is not supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-CTRL" +></A +>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6393" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_CTRL, ioctl VIDIOC_S_CTRL -- Get or set the value of a control</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6397" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6398" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_control +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6408" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_CTRL, VIDIOC_S_CTRL</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6428" +></A +><H2 +>Description</H2 +><P +>To get the current value of a control applications +initialize the <CODE +CLASS="STRUCTFIELD" +>id</CODE +> field of a struct +<CODE +CLASS="STRUCTNAME" +>v4l2_control</CODE +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +> ioctl with a pointer to this +structure. To change the value of a control applications initialize +the <CODE +CLASS="STRUCTFIELD" +>id</CODE +> and <CODE +CLASS="STRUCTFIELD" +>value</CODE +> +fields of a struct <CODE +CLASS="STRUCTNAME" +>v4l2_control</CODE +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +> ioctl.</P +><P +>When the <CODE +CLASS="STRUCTFIELD" +>id</CODE +> is invalid drivers +return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code. When the <CODE +CLASS="STRUCTFIELD" +>value</CODE +> is out +of bounds drivers can choose to take the closest valid value or return +an <SPAN +CLASS="ERRORCODE" +>ERANGE</SPAN +> error code, whatever seems more appropriate. However, +<CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +> is a write-only ioctl, it does not +return the actual new value.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CONTROL" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_control</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>id</CODE +></TD +><TD +>Identifies the control, set by the +application.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>value</CODE +></TD +><TD +>New value or current value.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6463" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +> <CODE +CLASS="STRUCTFIELD" +>id</CODE +> is +invalid.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ERANGE</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +> <CODE +CLASS="STRUCTFIELD" +>value</CODE +> +is out of bounds.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The control is temporarily not changeable, possibly +because another applications took over control of the device function +this control belongs to.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-FBUF" +></A +>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6492" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_FBUF, ioctl VIDIOC_S_FBUF -- Get or set frame buffer overlay parameters.</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6496" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6497" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_framebuffer *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6507" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_framebuffer *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6517" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_FBUF, VIDIOC_S_FBUF</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6537" +></A +><H2 +>Description</H2 +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +> ioctl are used to get and set the +frame buffer parameters for <A +HREF="#OVERLAY" +>video overlay</A +>.</P +><P +>To get the current parameters applications call the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +> ioctl with a pointer to a +<CODE +CLASS="STRUCTNAME" +>v4l2_framebuffer</CODE +> structure, the driver fills +all fields of the structure or returns the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when overlay is +not supported. To set the parameters applications initialize the +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field, +<CODE +CLASS="STRUCTFIELD" +>base</CODE +> unless the overlay is of +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +> type, and the +struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> <CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> substructure. The driver +accordingly prepares for overlay or returns an error code.</P +><P +>When the driver does <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> support +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +>, i. e. it will +write into video memory, the <CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +> ioctl +is a privileged function and only the superuser can change the frame +buffer parameters.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-FRAMEBUFFER" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_framebuffer</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="50%" +TITLE="C1"><COL><COL><COL +WIDTH="50%" +TITLE="C4"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +> </TD +><TD +>Overlay capability flags set by the driver, see +<A +HREF="#FRAMEBUFFER-CAP" +>Table 2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>flags</CODE +></TD +><TD +> </TD +><TD +>Overlay control flags set by application and +driver, see <A +HREF="#FRAMEBUFFER-FLAGS" +>Table 3</A +></TD +></TR +><TR +><TD +>void *</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>base</CODE +></TD +><TD +> </TD +><TD +><P +>Physical base address of the frame buffer, +the address of the pixel at coordinates (0; 0) in the frame buffer. +This field is not used when <CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +> sets +the <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> field.<SUP +>a</SUP +></P +></TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>fmt</CODE +></TD +><TD +> </TD +><TD +>Physical layout of the frame buffer. The +<CODE +CLASS="STRUCTNAME" +>v4l2_pix_format</CODE +> structure is defined in <A +HREF="#PIXFMT" +>Chapter 2</A +>, for clarification the fields and expected values +are listed below.</TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>width</CODE +></TD +><TD +>Width of the frame buffer in pixels.</TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>height</CODE +></TD +><TD +>Height of the frame buffer in pixels. When the +driver <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>clears</I +></SPAN +> +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +>, the visible portion +of the frame buffer can be smaller than width and height.</TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +></TD +><TD +>The pixel format of the graphics surface, set by +the application. Usually this is an RGB format (for example RGB 5:6:5) +but YUV formats are also permitted. The behavior of the driver when +requesting a compressed format is undefined. See <A +HREF="#PIXFMT" +>Chapter 2</A +> for information on pixel formats. This field is not +used when the driver sets +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +>.</TD +></TR +><TR +><TD +> </TD +><TD +>enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>field</CODE +></TD +><TD +>Ignored. The field order is selected with the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl using struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +>.</TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +></TD +><TD +>Distance in bytes between the leftmost pixels in two +adjacent lines.</TD +></TR +><TR +><TD +COLSPAN="4" +><P +>Both applications and drivers +can set this field to request padding bytes at the end of each line. +Drivers however may ignore the value requested by the application, +returning <CODE +CLASS="STRUCTFIELD" +>width</CODE +> times bytes per pixel or a +larger value required by the hardware. That implies applications can +just set this field to zero to get a reasonable +default.</P +><P +>Video hardware may access padding bytes, +therefore they must reside in accessible memory. Consider cases where +padding bytes after the last line of an image cross a system page +boundary. Input devices may write padding bytes, the value is +undefined. Output devices ignore the contents of padding +bytes.</P +><P +>When the image format is planar the +<CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +> value applies to the largest +plane and is divided by the same factor as the +<CODE +CLASS="STRUCTFIELD" +>width</CODE +> field for any smaller planes. For +example the Cb and Cr planes of a YUV 4:2:0 image have half as many +padding bytes following each line as the Y plane. To avoid ambiguities +drivers must return a <CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +> value +rounded up to a multiple of the scale factor.</P +><P +>This +field is not used when the driver sets +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +>.</P +></TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>sizeimage</CODE +></TD +><TD +><P +>Applications must initialize this field. +Together with <CODE +CLASS="STRUCTFIELD" +>base</CODE +> it defines the frame +buffer memory accessible by the driver.</P +><P +>The field is not +used when the driver sets +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +>.</P +></TD +></TR +><TR +><TD +> </TD +><TD +>enum <A +HREF="#V4L2-COLORSPACE" +>v4l2_colorspace</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>colorspace</CODE +></TD +><TD +>This information supplements the +<CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +> and must be set by the driver, +see <A +HREF="#COLORSPACES" +>Section 2.2</A +>.</TD +></TR +><TR +><TD +> </TD +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>priv</CODE +></TD +><TD +>Reserved for additional information about custom +(driver defined) formats. When not used drivers and applications must +set this field to zero.</TD +></TR +></TBODY +><TR +><TD +COLSPAN="4" +>Notes:<BR><A +NAME="FTN.AEN6588" +>a. </A +>A +physical base address may not suit all platforms. GK notes in theory +we should pass something like PCI device + memory region + offset +instead. If you encounter problems please discuss on the Video4Linux +mailing list: <A +HREF="https://listman.redhat.com/mailman/listinfo/video4linux-list" +TARGET="_top" +>https://listman.redhat.com/mailman/listinfo/video4linux-list</A +>.<BR></TD +></TR +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="FRAMEBUFFER-CAP" +></A +><P +><B +>Table 2. Frame Buffer Capability Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +></TD +><TD +>0x0001</TD +><TD +>The video is overlaid externally onto the +video signal of the graphics card.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_CHROMAKEY</CODE +></TD +><TD +>0x0002</TD +><TD +>The device supports clipping by chroma-keying the +image into the display.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_LIST_CLIPPING</CODE +></TD +><TD +>0x0004</TD +><TD +>The device supports clipping using a list of clip +rectangles.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_BITMAP_CLIPPING</CODE +></TD +><TD +>0x0008</TD +><TD +>The device supports clipping using a bit mask.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="FRAMEBUFFER-FLAGS" +></A +><P +><B +>Table 3. Frame Buffer Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_FLAG_PRIMARY</CODE +></TD +><TD +>0x0001</TD +><TD +>The frame buffer is the primary graphics surface. +In other words, the overlay is destructive, the video hardware will +write the image into visible graphics memory as opposed to merely +displaying the image in place of the original display contents.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_FLAG_OVERLAY</CODE +></TD +><TD +>0x0002</TD +><TD +>The frame buffer is an overlay surface the same +size as the capture. [?]</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_FLAG_CHROMAKEY</CODE +></TD +><TD +>0x0004</TD +><TD +>Use chromakey (when +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_CHROMAKEY</CODE +> indicates this +capability). The other clipping methods are negotiated with the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl, see also <A +HREF="#OVERLAY" +>Section 4.2</A +>.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6729" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EACCES</SPAN +></DT +><DD +><P +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +> can only be called +by a privileged user.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The frame buffer parameters cannot be changed at this +time because overlay is already enabled, or capturing is enabled +and the hardware cannot capture and overlay simultaneously.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The ioctl is not supported or the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +> parameters are unsuitable.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-FMT" +></A +>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6756" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_FMT, ioctl VIDIOC_S_FMT, ioctl VIDIOC_TRY_FMT -- Get or set the data format, try a format.</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6761" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6762" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_format +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6772" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6792" +></A +><H2 +>Description</H2 +><P +>These ioctls are used to negotiate the format of data +(typically image format) exchanged between driver and +application.</P +><P +>To query the current parameters applications set the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a struct +<CODE +CLASS="STRUCTNAME" +>v4l2_format</CODE +> to the respective buffer (stream) +type. For example video capture devices use +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +>. When the application +calls the <CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +> ioctl with a pointer to +this structure the driver fills the respective member of the +<CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> union. In case of video capture devices +that is the struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> <CODE +CLASS="STRUCTFIELD" +>pix</CODE +> member. +When the requested buffer type is not supported drivers return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><P +>To change the current format parameters applications +initialize the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field and all +fields of the respective <CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> +union member. For details see the documentation of the various devices +types in <A +HREF="#DEVICES" +>Chapter 4</A +>. Good practice is to query the +current parameters first, and to +modify only those parameters not suitable for the application. When +the application calls the <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> ioctl +with a pointer to a <CODE +CLASS="STRUCTNAME" +>v4l2_format</CODE +> structure +the driver checks +and adjusts the parameters against hardware abilities. Drivers +should not return an error code unless the input is ambiguous, this is +a mechanism to fathom device capabilities and to approach parameters +acceptable for both the application and driver. On success the driver +may program the hardware, allocate resources and generally prepare for +data exchange. +Finally the <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> ioctl returns the +current format parameters as <CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +> does. +Very simple, inflexible devices may even ignore all input and always +return the default parameters. However all V4L2 devices exchanging +data with the application must implement the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> ioctl. When the requested buffer +type is not supported drivers return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code on a +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> attempt. When I/O is already in +progress or the resource is not available for other reasons drivers +return the <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +> ioctl is equivalent +to <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> with one exception: it does not +change driver state. It can also be called at any time, never +returning <SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +>. This function is provided to +negotiate parameters, to learn about hardware limitations, without +disabling I/O or possibly time consuming hardware preparations. +Although strongly recommended drivers are not required to implement +this ioctl.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-FORMAT" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_format</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="25%" +TITLE="C3"><COL +WIDTH="25%" +TITLE="C4"><TBODY +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +> </TD +><TD +>Type of the data stream, see <A +HREF="#V4L2-BUF-TYPE" +>Table 3-2</A +>.</TD +></TR +><TR +><TD +>union</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>fmt</CODE +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +> </TD +><TD +>struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>pix</CODE +></TD +><TD +>Definition of an image format, see <A +HREF="#PIXFMT" +>Chapter 2</A +>, used by video capture and output +devices.</TD +></TR +><TR +><TD +> </TD +><TD +>struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>win</CODE +></TD +><TD +>Definition of an overlaid image, see <A +HREF="#OVERLAY" +>Section 4.2</A +>, used by video overlay devices.</TD +></TR +><TR +><TD +> </TD +><TD +>struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>vbi</CODE +></TD +><TD +>Raw VBI capture or output parameters. This is +discussed in more detail in <A +HREF="#RAW-VBI" +>Section 4.6</A +>. Used by raw VBI +capture and output devices.</TD +></TR +><TR +><TD +> </TD +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>raw_data</CODE +>[200]</TD +><TD +>Place holder for future extensions and custom +(driver defined) formats with <CODE +CLASS="STRUCTFIELD" +>type</CODE +> +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> and higher.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6874" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The data format cannot be changed at this +time, for example because I/O is already in progress.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> <CODE +CLASS="STRUCTFIELD" +>type</CODE +> +field is invalid, the requested buffer type not supported, or +<CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +> was called and is not +supported with this buffer type.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-FREQUENCY" +></A +>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN6897" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_FREQUENCY, ioctl VIDIOC_S_FREQUENCY -- Get or set tuner or modulator radio +frequency</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN6901" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6902" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_frequency +*argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN6912" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_frequency +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6922" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN6942" +></A +><H2 +>Description</H2 +><P +>To get the current tuner or modulator radio frequency +applications set the <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> field of a +struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +> to the respective tuner or modulator number (only +input devices have tuners, only output devices have modulators), zero +out the <CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array and +call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_FREQUENCY</CODE +> ioctl with a pointer +to this structure. The driver stores the current frequency in the +<CODE +CLASS="STRUCTFIELD" +>frequency</CODE +> field.</P +><P +>To change the current tuner or modulator radio frequency +applications initialize the <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>frequency</CODE +> fields, and the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +> and +call the <CODE +CLASS="CONSTANT" +>VIDIOC_S_FREQUENCY</CODE +> ioctl with a pointer +to this structure. When the requested frequency is not possible the +driver assumes the closest possible value. However, +<CODE +CLASS="CONSTANT" +>VIDIOC_S_FREQUENCY</CODE +> is a write-only ioctl, it does +not return the actual new frequency.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-FREQUENCY" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_frequency</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>tuner</CODE +></TD +><TD +>The tuner or modulator index number. This is the +same value as in the struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> +field and the struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field, or +the struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> <CODE +CLASS="STRUCTFIELD" +>modulator</CODE +> field and the +struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-TUNER-TYPE" +>v4l2_tuner_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>The tuner type. This is the same value as in the +struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field. The field is not +applicable to modulators, i. e. ignored by drivers.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>frequency</CODE +></TD +><TD +>Tuning frequency in units of 62.5 kHz, or if the +struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> or struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> <CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> flag +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> is set, in units of 62.5 +Hz.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[8];</TD +><TD +>Reserved for future extensions. Drivers and + applications must set the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7001" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> field is out of +bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-INPUT" +></A +>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7017" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_INPUT, ioctl VIDIOC_S_INPUT -- Query or select the current video input</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7021" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7022" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, int *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7032" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_INPUT, VIDIOC_S_INPUT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7052" +></A +><H2 +>Description</H2 +><P +>To query the current video input applications call the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +> ioctl with a pointer to an integer +where the driver stores the number of the input, as in the +struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field. This ioctl will +fail only when there are no video inputs, returning +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><P +>To select a video input applications store the number of the +desired input in an integer and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_INPUT</CODE +> ioctl with a pointer to this +integer. Side effects are possible. For example inputs may support +different video standards, so the driver may implicitly switch the +current standard. It is good practice to select an input before +querying or negotiating any other parameters.</P +><P +>Information about video inputs is available using the +<A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +> ioctl.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7064" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The number of the video input is out of bounds, or +there are no video inputs at all and this ioctl is not +supported.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>I/O is in progress, the input cannot be +switched.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-JPEGCOMP" +></A +>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7084" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_JPEGCOMP, ioctl VIDIOC_S_JPEGCOMP -- </DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7088" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7089" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, v4l2_jpegcompression *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7099" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const v4l2_jpegcompression *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7109" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7129" +></A +><H2 +>Description</H2 +><P +>[to do]</P +><P +>Ronald Bultje elaborates:</P +><P +>APP is some application-specific information. The +application can set it itself, and it'll be stored in the JPEG-encoded +fields (e.g. interlacing information for in an AVI or so). COM is the +same, but it's comments, like 'encoded by me' or so.</P +><P +>jpeg_markers describes whether the huffman tables, +quantization tables and the restart interval information (all +JPEG-specific stuff) should be stored in the JPEG-encoded fields. +These define how the JPEG field is encoded. If you omit them, +applications assume you've used standard encoding. You usually do want +to add them.</P +><P +CLASS="COMMENT" +>NB VIDIOC_S_JPEGCOMP is w/o.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-JPEGCOMPRESSION" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_jpegcompression</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>int</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>quality</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>int</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>APPn</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>int</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>APP_len</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>char</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>APP_data</CODE +>[60]</TD +><TD +> </TD +></TR +><TR +><TD +>int</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>COM_len</CODE +></TD +><TD +> </TD +></TR +><TR +><TD +>char</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>COM_data</CODE +>[60]</TD +><TD +> </TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>jpeg_markers</CODE +></TD +><TD +>See <A +HREF="#JPEG-MARKERS" +>Table 2</A +>.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="JPEG-MARKERS" +></A +><P +><B +>Table 2. JPEG Markers Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_JPEG_MARKER_DHT</CODE +></TD +><TD +>(1<<3)</TD +><TD +>Define Huffman Tables</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_JPEG_MARKER_DQT</CODE +></TD +><TD +>(1<<4)</TD +><TD +>Define Quantization Tables</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_JPEG_MARKER_DRI</CODE +></TD +><TD +>(1<<5)</TD +><TD +>Define Restart Interval</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_JPEG_MARKER_COM</CODE +></TD +><TD +>(1<<6)</TD +><TD +>Comment segment</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_JPEG_MARKER_APP</CODE +></TD +><TD +>(1<<7)</TD +><TD +>App segment, driver will always use APP0</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7214" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>This ioctl is not supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-MODULATOR" +></A +>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7229" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_MODULATOR, ioctl VIDIOC_S_MODULATOR -- Get or set modulator attributes</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7233" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7234" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_modulator +*argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7244" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_modulator +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7254" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7274" +></A +><H2 +>Description</H2 +><P +>To query the attributes of a modulator applications initialize +the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field and zero out the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> and +call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_MODULATOR</CODE +> ioctl with a pointer +to this structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all modulators +applications shall begin at index zero, incrementing by one until the +driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><P +>Modulators have two writable properties, an audio +modulation set and the radio frequency. To change the modulated audio +subprograms, applications initialize the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> and <CODE +CLASS="STRUCTFIELD" +>txsubchans</CODE +> fields and the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_MODULATOR</CODE +> ioctl. Drivers may choose a +different audio modulation if the request cannot be satisfied. However +this is a write-only ioctl, it does not return the actual audio +modulation selected.</P +><P +>To change the radio frequency the <A +HREF="#VIDIOC-G-FREQUENCY" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FREQUENCY</CODE +></A +> ioctl +is available.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-MODULATOR" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_modulator</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Identifies the modulator, set by the +application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the modulator, a NUL-terminated ASCII +string. This information is intended for the user.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +>Modulator capability flags. No flags are defined +for this field, the tuner flags in struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> +are used accordingly. The audio flags indicate the ability +to encode audio subprograms. They will <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> +change for example with the current video standard.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>rangelow</CODE +></TD +><TD +>The lowest tunable frequency in units of 62.5 +KHz, or if the <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> flag +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> is set, in units of 62.5 +Hz.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>rangehigh</CODE +></TD +><TD +>The highest tunable frequency in units of 62.5 +KHz, or if the <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> flag +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> is set, in units of 62.5 +Hz.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>txsubchans</CODE +></TD +><TD +>With this field applications can determine how +audio sub-carriers shall be modulated. It contains a set of flags as +defined in <A +HREF="#MODULATOR-TXSUBCHANS" +>Table 2</A +>. Note the tuner +<CODE +CLASS="STRUCTFIELD" +>rxsubchans</CODE +> flags are reused, but the +semantics are different. Video output devices are assumed to have an +analog or PCM audio input with 1-3 channels. The +<CODE +CLASS="STRUCTFIELD" +>txsubchans</CODE +> flags select one or more +channels for modulation, together with some audio subprogram +indicator, for example a stereo pilot tone.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers and +applications must set the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="MODULATOR-TXSUBCHANS" +></A +><P +><B +>Table 2. Modulator Audio Transmission Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO</CODE +></TD +><TD +>0x0001</TD +><TD +>Modulate channel 1 as mono audio, when the input +has more channels, a down-mix of channel 1 and 2. This flag does not +combine with <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG1</CODE +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +></TD +><TD +>0x0002</TD +><TD +>Modulate channel 1 and 2 as left and right +channel of a stereo audio signal. When the input has only one channel +or two channels and <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_SAP</CODE +> is also +set, channel 1 is encoded as left and right channel. This flag does +not combine with <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO </CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG1</CODE +>. When the driver does not +support stereo audio it shall fall back to mono.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG1</CODE +></TD +><TD +>0x0008</TD +><TD +>Modulate channel 1 and 2 as primary and secondary +language of a bilingual audio signal. When the input has only one +channel it is used for both languages. It is not possible to encode +the primary or secondary language only. This flag does not combine +with <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO </CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +>. If the hardware does not +support the respective audio matrix, or the current video standard +does not permit bilingual audio the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_MODULATOR</CODE +> ioctl shall return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code +and the driver shall fall back to mono or stereo mode. +<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG2</CODE +></TD +><TD +>0x0004</TD +><TD +>Same effect as +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG1</CODE +>. +<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_SAP</CODE +></TD +><TD +>0x0004</TD +><TD +>When combined with <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO</CODE +> the first channel is encoded as mono audio, the last +channel as Second Audio Program. When the input has only one channel +it is used for both audio tracks. When the input has three channels +the mono track is a down-mix of channel 1 and 2. When combined with +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO </CODE +> channel 1 and 2 are +encoded as left and right stereo audio, channel 3 as Second Audio +Program. When the input has only two channels, the first is encoded as +left and right channel and the second as SAP. When the input has only +one channel it is used for all audio tracks. It is not possible to +encode a Second Audio Program only. This flag must combine with +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +>. If the hardware does not +support the respective audio matrix, or the current video standard +does not permit SAP the <CODE +CLASS="CONSTANT" +> VIDIOC_S_MODULATOR</CODE +> ioctl +shall return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code and driver shall fall back to mono or stereo +mode.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7396" +></A +><H2 +>Return Value</H2 +><P +>On success 0 is returned, on error -1 and +<VAR +CLASS="VARNAME" +>errno</VAR +> is set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> is out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-OUTPUT" +></A +>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7411" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_OUTPUT, ioctl VIDIOC_S_OUTPUT -- Query or select the current video output</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7415" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7416" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, int *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7426" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7446" +></A +><H2 +>Description</H2 +><P +>To query the current video output applications call the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_OUTPUT</CODE +> ioctl with a pointer to an integer +where the driver stores the number of the output, as in the +struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> field. This ioctl +will fail only when there are no video outputs, returning the +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><P +>To select a video output applications store the number of the +desired output in an integer and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_OUTPUT</CODE +> ioctl with a pointer to this integer. +Side effects are possible. For example outputs may support different +video standards, so the driver may implicitly switch the current +standard. It is good practice to select an output before querying or +negotiating any other parameters.</P +><P +>Information about video outputs is available using the +<A +HREF="#VIDIOC-ENUMOUTPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMOUTPUT</CODE +></A +> ioctl.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7458" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The number of the video output is out of bounds, or +there are no video outputs at all and this ioctl is not +supported.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>I/O is in progress, the output cannot be +switched.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-PARM" +></A +>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7478" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_PARM, ioctl VIDIOC_S_PARM -- Get or set streaming parameters</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7482" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7483" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, v4l2_streamparm *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7493" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_PARM, VIDIOC_S_PARM</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7513" +></A +><H2 +>Description</H2 +><P +>[to do]</P +><P +><CODE +CLASS="CONSTANT" +>VIDIOC_S_PARM</CODE +> is a write-only ioctl, + it does not return the actual parameters.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-STREAMPARM" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_streamparm</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="50%" +TITLE="C1"><COL><COL><TBODY +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +> </TD +><TD +>The buffer (stream) type, same as struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +>, set by the application.</TD +></TR +><TR +><TD +>union</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>parm</CODE +></TD +><TD +> </TD +><TD +> </TD +></TR +><TR +><TD +> </TD +><TD +>struct <A +HREF="#V4L2-CAPTUREPARM" +>v4l2_captureparm</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capture</CODE +></TD +><TD +>Parameters for capture devices, used when +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +>.</TD +></TR +><TR +><TD +> </TD +><TD +>struct <A +HREF="#V4L2-OUTPUTPARM" +>v4l2_outputparm</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>output</CODE +></TD +><TD +>Parameters for output devices, used when +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +>.</TD +></TR +><TR +><TD +> </TD +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>raw_data</CODE +>[200]</TD +><TD +>A place holder for future extensions and custom +(driver defined) buffer types <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> and +higher.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CAPTUREPARM" +></A +><P +><B +>Table 2. struct <CODE +CLASS="STRUCTNAME" +>v4l2_captureparm</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +>See <A +HREF="#PARM-CAPS" +>Table 4</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capturemode</CODE +></TD +><TD +>Set by drivers and applications, see <A +HREF="#PARM-FLAGS" +>Table 5</A +>.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>timeperframe</CODE +></TD +><TD +><P +>This is is the desired period between +successive frames captured by the driver, expressed in 0.1 µs +units. The field is intended to skip frames on the driver side, saving +I/O bandwidth.</P +><P +>Applications store here the desired frame +period, drivers return the actual frame period, which must be greater +or equal to the nominal frame period determined by the current video +standard (struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> <CODE +CLASS="STRUCTFIELD" +>frameperiod</CODE +> +field). Changing the video standard (also implicitly by switching the +video input) may reset this parameter to the nominal frame period. To +reset manually applications can just set this field to +zero.</P +><P +>Drivers support this function only when they set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_TIMEPERFRAME</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> field.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>extendedmode</CODE +></TD +><TD +>Custom (driver specific) streaming parameters. When +unused, applications and drivers must set this field to zero. +Applications using this field should check the driver name and +version, see <A +HREF="#QUERYCAP" +>Section 1.2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>readbuffers</CODE +></TD +><TD +>Applications set this field to the desired number + of buffers used internally by the driver in <A +HREF="#FUNC-READ" +><CODE +CLASS="FUNCTION" +>read()</CODE +></A +> + mode. Drivers return the actual number of buffers. When an application requests + zero buffers, drivers should just return the current + setting rather than the minimum or an error code. For + details see <A +HREF="#RW" +>Section 3.1</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers and +applications must set the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-OUTPUTPARM" +></A +><P +><B +>Table 3. struct <CODE +CLASS="STRUCTNAME" +>v4l2_outputparm</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +>See <A +HREF="#PARM-CAPS" +>Table 4</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>outputmode</CODE +></TD +><TD +>Set by drivers and applications, see <A +HREF="#PARM-FLAGS" +>Table 5</A +>.</TD +></TR +><TR +><TD +>struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>timeperframe</CODE +></TD +><TD +>This is is the desired period between +successive frames output by the driver, expressed in 0.1 µs +units.</TD +></TR +><TR +><TD +COLSPAN="3" +><P +>The field is intended to +repeat frames on the driver side in <A +HREF="#FUNC-WRITE" +><CODE +CLASS="FUNCTION" +>write()</CODE +></A +> mode (in streaming +mode timestamps can be used to throttle the output), saving I/O +bandwidth.</P +><P +>Applications store here the desired frame +period, drivers return the actual frame period, which must be greater +or equal to the nominal frame period determined by the current video +standard (struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> <CODE +CLASS="STRUCTFIELD" +>frameperiod</CODE +> +field). Changing the video standard (also implicitly by switching the +video output) may reset this parameter to the nominal frame period. To +reset manually applications can just set this field to +zero.</P +><P +>Drivers support this function only when they set the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_TIMEPERFRAME</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> field.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>extendedmode</CODE +></TD +><TD +>Custom (driver specific) streaming parameters. When +unused, applications and drivers must set this field to zero. +Applications using this field should check the driver name and +version, see <A +HREF="#QUERYCAP" +>Section 1.2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>writebuffers</CODE +></TD +><TD +>Applications set this field to the desired number +of buffers used internally by the driver in +<CODE +CLASS="FUNCTION" +>write()</CODE +> mode. Drivers return the actual number of +buffers. When an application requests zero buffers, drivers should +just return the current setting rather than the minimum or an error +code. For details see <A +HREF="#RW" +>Section 3.1</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers and +applications must set the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="PARM-CAPS" +></A +><P +><B +>Table 4. Streaming Parameters Capabilites</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_TIMEPERFRAME</CODE +></TD +><TD +>0x1000</TD +><TD +>The frame skipping/repeating controlled by the +<CODE +CLASS="STRUCTFIELD" +>timeperframe</CODE +> field is supported.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="PARM-FLAGS" +></A +><P +><B +>Table 5. Capture Parameters Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_MODE_HIGHQUALITY</CODE +></TD +><TD +>0x0001</TD +><TD +><P +>High quality imaging mode. High quality mode +is intended for still imaging applications. The idea is to get the +best possible image quality that the hardware can deliver. It is not +defined how the driver writer may achieve that; it will depend on the +hardware and the ingenuity of the driver writer. High quality mode is +a different mode from the the regular motion video capture modes. In +high quality mode:<P +></P +><UL +><LI +><P +>The driver may be able to capture higher +resolutions than for motion capture.</P +></LI +><LI +><P +>The driver may support fewer pixel formats +than motion capture (e.g. true color).</P +></LI +><LI +><P +>The driver may capture and arithmetically +combine multiple successive fields or frames to remove color edge +artifacts and reduce the noise in the video data.</P +></LI +><LI +><P +>The driver may capture images in slices like +a scanner in order to handle larger format images than would otherwise +be possible. </P +></LI +><LI +><P +>An image capture operation may be +significantly slower than motion capture. </P +></LI +><LI +><P +>Moving objects in the image might have +excessive motion blur. </P +></LI +><LI +><P +>Capture might only work through the +<CODE +CLASS="FUNCTION" +>read()</CODE +> call.</P +></LI +></UL +></P +></TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7719" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>This ioctl is not supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-PRIORITY" +></A +>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7734" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_PRIORITY, ioctl VIDIOC_S_PRIORITY -- Query or request the access priority associated with a +file descriptor</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7738" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7739" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, enum v4l2_priority *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7749" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const enum v4l2_priority *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7759" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +>Pointer to an enum v4l2_priority type.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7779" +></A +><H2 +>Description</H2 +><P +>To query the current access priority +applications call the <CODE +CLASS="CONSTANT" +>VIDIOC_G_PRIORITY</CODE +> ioctl +with a pointer to an enum v4l2_priority variable where the driver stores +the current priority.</P +><P +>To request an access priority applications store the +desired priority in an enum v4l2_priority variable and call +<CODE +CLASS="CONSTANT" +>VIDIOC_S_PRIORITY</CODE +> ioctl with a pointer to this +variable.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-PRIORITY" +></A +><P +><B +>Table 1. enum v4l2_priority</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PRIORITY_UNSET</CODE +></TD +><TD +>0</TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PRIORITY_BACKGROUND</CODE +></TD +><TD +>1</TD +><TD +>Lowest priority, usually applications running in +background, for example monitoring VBI transmissions. A proxy +application running in user space will be necessary if multiple +applications want to read from a device at this priority.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PRIORITY_INTERACTIVE</CODE +></TD +><TD +>2</TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PRIORITY_DEFAULT</CODE +></TD +><TD +>2</TD +><TD +>Medium priority, usually applications started and +interactively controlled by the user. For example TV viewers, Teletext +browsers, or just "panel" applications to change the channel or video +controls. This is the default priority unless an application requests +another.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PRIORITY_RECORD</CODE +></TD +><TD +>3</TD +><TD +>Highest priority. Only one file descriptor can have +this priority, it blocks any other fd from changing device properties. +Usually applications which must not be interrupted, like video +recording.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7818" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The requested priority value is invalid, or the +driver does not support access priorities.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>Another application already requested higher +priority.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-STD" +></A +>ioctl VIDIOC_G_STD, VIDIOC_S_STD</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7838" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_STD, ioctl VIDIOC_S_STD -- Query or select the video standard of the current input</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7842" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7843" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, v4l2_std_id +*argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7853" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const v4l2_std_id +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7863" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_STD, VIDIOC_S_STD</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7883" +></A +><H2 +>Description</H2 +><P +>To query and select the current video standard applications +use the <CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +> and <CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +> ioctls which take a pointer to a +<A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> type as argument. <CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +> can +return a single flag or a set of flags as in struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> field +<CODE +CLASS="STRUCTFIELD" +>id</CODE +>. The flags must be unambiguous such +that they appear in only one enumerated <CODE +CLASS="STRUCTNAME" +>v4l2_standard</CODE +> structure.</P +><P +><CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +> accepts one or more +flags, being a write-only ioctl it does not return the actual new standard as +<CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +> does. When no flags are given or +the current input does not support the requested standard the driver +returns an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code. When the standard set is ambiguous drivers may +return <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> or choose any of the requested +standards.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7898" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>This ioctl is not supported, or the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +> parameter was unsuitable.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-G-TUNER" +></A +>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN7914" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_G_TUNER, ioctl VIDIOC_S_TUNER -- Get or set tuner attributes</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN7918" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7919" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_tuner +*argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN7929" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const struct v4l2_tuner +*argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7939" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_G_TUNER, VIDIOC_S_TUNER</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN7959" +></A +><H2 +>Description</H2 +><P +>To query the attributes of a tuner applications initialize the +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field and zero out the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array of a struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_TUNER</CODE +> ioctl with a pointer to this +structure. Drivers fill the rest of the structure or return an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the index is out of bounds. To enumerate all tuners +applications shall begin at index zero, incrementing by one until the +driver returns <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>.</P +><P +>Tuners have two writable properties, the audio mode and +the radio frequency. To switch the audio mode, applications initialize +the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>audmode</CODE +> fields and the +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> array and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_S_TUNER</CODE +> ioctl. This will +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> change the currently selected tuner, +which is determined by the current video input. Drivers may choose a +different audio mode if the request cannot be satisfied. Since this +is a write-only ioctl it does not return the actual audio mode +selected.</P +><P +>To change the radio frequency the <A +HREF="#VIDIOC-G-FREQUENCY" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FREQUENCY</CODE +></A +> ioctl +is available.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-TUNER" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_tuner</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Identifies the tuner, set by the +application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +><P +>Name of the tuner, a NUL-terminated ASCII +string. This information is intended for the user.<SUP +>a</SUP +></P +></TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-TUNER-TYPE" +>v4l2_tuner_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the tuner, see <A +HREF="#V4L2-TUNER-TYPE" +>Table 2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capability</CODE +></TD +><TD +><P +>Tuner capability flags, see <A +HREF="#TUNER-CAPABILITY" +>Table 3</A +>. Audio flags indicate +the ability to decode audio subprograms. They will +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not</I +></SPAN +> change for example with the current video +standard.</P +><P +>When the structure refers to a radio tuner only +the <CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_STEREO</CODE +> flags can be +set.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>rangelow</CODE +></TD +><TD +>The lowest tunable frequency in units of 62.5 +KHz, or if the <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> flag +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> is set, in units of 62.5 +Hz.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>rangehigh</CODE +></TD +><TD +>The highest tunable frequency in units of 62.5 +KHz, or if the <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> flag +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> is set, in units of 62.5 +Hz.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>rxsubchans</CODE +></TD +><TD +><P +>Some tuners can report the audio subprograms +received by analyzing audio carriers, pilot tones or other indicators. +The <CODE +CLASS="STRUCTFIELD" +>rxsubchans</CODE +> field contains flags defined +in <A +HREF="#TUNER-RXSUBCHANS" +>Table 4</A +>, which are set by the driver to +indicate the audio subprograms the hardware <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>may</I +></SPAN +> +currently receive.</P +></TD +></TR +><TR +><TD +COLSPAN="3" +><P +>Only those flags can be set +here which are also set in the <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> +field. When the detection is inconclusive the flags of all possible +audio subprograms must be set. When the driver cannot detect the audio +subprograms at all, this field must contain the same audio flags as +<CODE +CLASS="STRUCTFIELD" +>capability </CODE +>.<SUP +>b</SUP +></P +><P +>For example when two audio +channels are detected but the hardware cannot distinguish between +stereo and bilingual mode all the +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG1</CODE +>, and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG2</CODE +> flags may be set.</P +><P +>When the structure refers to a radio tuner only the +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +> flag can be +set.</P +><P +>The field is valid only when this is the tuner of the +current video input or a radio tuner.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>audmode</CODE +></TD +><TD +><P +>The selected audio mode, see <A +HREF="#TUNER-AUDMODE" +>Table 5</A +> for valid values. The audio mode +does not affect audio subprogram detection, and it does not change +automatically. See <A +HREF="#TUNER-MATRIX" +>Table 6</A +> for possible results +when the selected and received audio programs do not +match.</P +><P +>When the structure refers to a radio tuner only the +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_MONO</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_STEREO</CODE +> are valid +values.</P +><P +>Currently this is the only field of struct +<CODE +CLASS="STRUCTNAME" +>v4l2_tuner</CODE +> applications can change.</P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>signal</CODE +></TD +><TD +>The signal strength if known, supposedly ranging +from 0 to 65535. Higher values indicate a better signal.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>afc</CODE +></TD +><TD +>Automatic frequency control: When the +<CODE +CLASS="STRUCTFIELD" +>afc</CODE +> value is negative, the frequency is too +low, when positive too high. [need example what to do when it never +settles at zero, i. e. range is what?]</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers and +applications must set the array to zero.</TD +></TR +></TBODY +><TR +><TD +COLSPAN="3" +>Notes:<BR><A +NAME="FTN.AEN7997" +>a. </A +>Video inputs already have a name, the purpose +of this field is not quite clear.<BR><A +NAME="FTN.AEN8045" +>b. </A +>Purpose of +<CODE +CLASS="STRUCTFIELD" +>rxsubchans</CODE +> is to eliminate choice, i. e. +those audio subprograms the driver knows for sure are not received +right now.<BR></TD +></TR +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-TUNER-TYPE" +></A +><P +><B +>Table 2. enum v4l2_tuner_type</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_RADIO</CODE +></TD +><TD +>1</TD +><TD +> </TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_ANALOG_TV</CODE +></TD +><TD +>2</TD +><TD +> </TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="TUNER-CAPABILITY" +></A +><P +><B +>Table 3. Tuner and Modulator Capability Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +></TD +><TD +>0x0001</TD +><TD +>When set frequencies are expressed in units of +62.5 Hz, otherwise in units of 62.5 kHz.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_NORM</CODE +></TD +><TD +>0x0002</TD +><TD +>This is a multi-standard tuner; the video +standard can or must be switched. (B/G PAL tuners for example are +typically not considered multi-standard because the video standard is +automatically selected depending on the frequency band.) The supported +video standards are reported in the respective struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> field +<CODE +CLASS="STRUCTFIELD" +>std</CODE +>. For details on video standards and how +to switch see <A +HREF="#STANDARD" +>Section 1.7</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_STEREO</CODE +></TD +><TD +>0x0010</TD +><TD +>Stereo audio reception is supported.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LANG1</CODE +></TD +><TD +>0x0040</TD +><TD +>Reception of a primary language (of two) is +supported.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LANG2</CODE +></TD +><TD +>0x0020</TD +><TD +>Reception of a secondary language is +supported.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_SAP</CODE +></TD +><TD +>0x0020</TD +><TD +><P +>Reception of the Secondary Audio Program +(typically a secondary language of the current program) is supported. +Note the <CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LANG2</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_SAP</CODE +> flags are synonyms. <SUP +>a</SUP +></P +></TD +></TR +></TBODY +><TR +><TD +COLSPAN="3" +>Notes:<BR><A +NAME="FTN.TUNER-AUDIO-CAP" +>a. </A +>The LANG1/LANG2 +nomenclature refers to audio systems transmitting different languages +monaural on two audio subcarriers ("bilingual mode"), otherwise the +left and right stereo channel. Similar the NICAM digital audio system +with two audio channels, transmitted on a second audio subcarrier +while the main AM/FM audio carrier provides mono or primary language +audio for older TV sets. SAP is a feature of the U.S. BTSC audio +system, which consists of up to three audio subcarriers. Unlike LANG2 +SAP is a separate mono audio track besides the primary mono or stereo +audio track.<BR>The <CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_SAP</CODE +> +capability flag applies when the tuner supports the M/NTSC video +standard. <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_SAP</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_SAP</CODE +> apply when the M/NTSC video +standard is currently selected.<BR></TD +></TR +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="TUNER-RXSUBCHANS" +></A +><P +><B +>Table 4. Tuner Audio Reception Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_MONO</CODE +></TD +><TD +>0x0001</TD +><TD +>The tuner receives a mono audio signal.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +></TD +><TD +>0x0002</TD +><TD +>The tuner receives a stereo audio signal.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG1</CODE +></TD +><TD +>0x0008</TD +><TD +>The tuner receives the primary language of a +bilingual audio signal. This flag is not supposed to be set when the +tuner receives Mono + SAP or Stereo + SAP audio.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG2</CODE +></TD +><TD +>0x0004</TD +><TD +>The tuner receives the secondary language of a +bilingual audio signal.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_SAP</CODE +></TD +><TD +>0x0004</TD +><TD +>The tuner receives a Second Audio Program. Note +the <CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_LANG2</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_SAP</CODE +> flags are +synonyms.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="TUNER-AUDMODE" +></A +><P +><B +>Table 5. Tuner Audio Modes</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_MONO</CODE +></TD +><TD +>0</TD +><TD +>Play mono audio. When the tuner receives a stereo +signal this a down-mix of the left and right channel. When the tuner +receives a bilingual or SAP signal this mode selects the primary +language.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_STEREO</CODE +></TD +><TD +>1</TD +><TD +>Play stereo audio. When the tuner receives +bilingual audio it may play different languages on the left and right +channel or the primary language on both channels. When it receives no +stereo signal or does not support stereo reception the driver shall +fall back to mono mode.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_LANG1</CODE +></TD +><TD +>3</TD +><TD +>Play the primary language, mono or +stereo.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_LANG2</CODE +></TD +><TD +>2</TD +><TD +>Play the secondary language, mono. When the tuner +receives no bilingual audio or SAP, or their reception is not +supported the driver shall fall back to mono or stereo mode.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_SAP</CODE +></TD +><TD +>2</TD +><TD +>Play the Second Audio Program. When the tuner +receives no bilingual audio or SAP, or their reception is not +supported the driver shall fall back to mono or stereo mode. Note the +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_LANG2</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_MODE_SAP</CODE +> identifiers are +synonyms.<A +HREF="#FTN.TUNER-AUDIO-CAP" +><SPAN +CLASS="footnote" +>[a]</SPAN +></A +></TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="TUNER-MATRIX" +></A +><P +><B +>Table 6. Tuner Audio Matrix</B +></P +><TABLE +BORDER="1" +FRAME="border" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="33%" +ALIGN="LEFT"><COL +WIDTH="33%" +TITLE="C2"><COL><COL><COL +WIDTH="33%" +TITLE="C5"><THEAD +><TR +><TH +> </TH +><TH +COLSPAN="4" +ALIGN="CENTER" +>Selected</TH +></TR +><TR +><TH +>Received</TH +><TH +>Mono</TH +><TH +>Stereo</TH +><TH +>Language 1</TH +><TH +>Language 2 / SAP</TH +></TR +></THEAD +><TBODY +><TR +><TD +>Mono</TD +><TD +>Mono</TD +><TD +>Mono/Mono</TD +><TD +>Mono</TD +><TD +>Mono</TD +></TR +><TR +><TD +>Stereo</TD +><TD +>L+R</TD +><TD +>L/R</TD +><TD +>Undefined: L/L or L+R Mono or +L/R Stereo</TD +><TD +>Undefined: R/R or L+R Mono or +L/R Stereo</TD +></TR +><TR +><TD +>Mono/Stereo + SAP (BTSC only)</TD +><TD +>-</TD +><TD +>-</TD +><TD +>Main audio program, mono or stereo</TD +><TD +>SAP Mono</TD +></TR +><TR +><TD +>Bilingual (two carrier systems only)</TD +><TD +>Language 1</TD +><TD +>Undefined: Lang1/Lang1 or Lang1/Lang2</TD +><TD +>Language 1 Mono</TD +><TD +>Language 2 Mono</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8271" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> <CODE +CLASS="STRUCTFIELD" +>index</CODE +> is +out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-OVERLAY" +></A +>ioctl VIDIOC_OVERLAY</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8288" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_OVERLAY -- Start or stop video overlay</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN8291" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN8292" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const int *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8302" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_OVERLAY</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8322" +></A +><H2 +>Description</H2 +><P +>This ioctl is part of the <A +HREF="#OVERLAY" +>video + overlay</A +> I/O method. Applications call + <CODE +CLASS="CONSTANT" +>VIDIOC_OVERLAY</CODE +> to start or stop the + overlay. It takes a pointer to an integer which must be set to + zero by the application to stop overlay, to one to start.</P +><P +>Drivers do not support <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> or +<A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +> with <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8333" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>Video overlay is not supported, or the +parameters have not been set up. See <A +HREF="#OVERLAY" +>Section 4.2</A +> for the necessary steps.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-QBUF" +></A +>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8349" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_QBUF, ioctl VIDIOC_DQBUF -- Exchange a buffer with the driver</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN8353" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN8354" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_buffer *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8364" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_QBUF, VIDIOC_DQBUF</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8384" +></A +><H2 +>Description</H2 +><P +>Applications call the <CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +> ioctl +to enqueue an empty (capturing) or filled (output) buffer in the +driver's incoming queue. The semantics depend on the selected I/O +method.</P +><P +>To enqueue a <A +HREF="#MMAP" +>memory mapped</A +> +buffer applications set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a +struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> to the same buffer type as previously struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> and struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +>, the <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> +field to <CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +> and the +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field. Valid index numbers range from +zero to the number of buffers allocated with <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> +(struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> <CODE +CLASS="STRUCTFIELD" +>count</CODE +>) minus one. The +contents of the struct <CODE +CLASS="STRUCTNAME" +>v4l2_buffer</CODE +> returned +by a <A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +> ioctl will do as well. When the buffer is +intended for output (<CODE +CLASS="STRUCTFIELD" +>type</CODE +> is +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_OUTPUT</CODE +>) applications must also +initialize the <CODE +CLASS="STRUCTFIELD" +>bytesused</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +> fields. See <A +HREF="#BUFFER" +>Section 3.5</A +> for details. When +<CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +> is called with a pointer to this +structure the driver sets the +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_MAPPED</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_QUEUED</CODE +> flags and clears the +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_DONE</CODE +> flag in the +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field, or it returns an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><P +>To enqueue a <A +HREF="#USERP" +>user pointer</A +> +buffer applications set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field of a +struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> to the same buffer type as previously struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> and struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +>, the <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> +field to <CODE +CLASS="CONSTANT" +>V4L2_MEMORY_USERPTR</CODE +> and the +<CODE +CLASS="STRUCTFIELD" +>m.userptr</CODE +> field to the address of the +buffer and <CODE +CLASS="STRUCTFIELD" +>length</CODE +> to its size. When the +buffer is intended for output additional fields must be set as above. +When <CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +> is called with a pointer to this +structure the driver sets the <CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_QUEUED</CODE +> +flag and clears the <CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_MAPPED</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_DONE</CODE +> flags in the +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field, or it returns an error code. +This ioctl locks the memory pages of the buffer in physical memory, +they cannot be swapped out to disk. Buffers remain locked until +dequeued, until the <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +> or <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl are +called, or until the device is closed.</P +><P +>Applications call the <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> +ioctl to dequeue a filled (capturing) or displayed (output) buffer +from the driver's outgoing queue. They just set the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> and <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> +fields of a struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> as above, when <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> +is called with a pointer to this structure the driver fills the +remaining fields or returns an error code.</P +><P +>By default <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> blocks when no +buffer is in the outgoing queue. When the +<CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag was given to the <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> +function, <CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> returns immediately +with an <SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +> error code when no buffer is available.</P +><P +>The <CODE +CLASS="STRUCTNAME" +>v4l2_buffer</CODE +> structure is +specified in <A +HREF="#BUFFER" +>Section 3.5</A +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8456" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +></DT +><DD +><P +>Non-blocking I/O has been selected using +<CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> and no buffer was in the outgoing +queue.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The buffer <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is not +supported, or the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> is out of bounds, +or no buffers have been allocated yet, or the +<CODE +CLASS="STRUCTFIELD" +>userptr</CODE +> or +<CODE +CLASS="STRUCTFIELD" +>length</CODE +> are invalid.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENOMEM</SPAN +></DT +><DD +><P +>Insufficient memory to enqueue a user pointer buffer.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EIO</SPAN +></DT +><DD +><P +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> failed due to an +internal error. Can also indicate temporary problems like signal +loss. Note the driver might dequeue an (empty) buffer despite +returning an error, or even stop capturing.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-QUERYBUF" +></A +>ioctl VIDIOC_QUERYBUF</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8490" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_QUERYBUF -- Query the status of a buffer</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN8493" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN8494" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_buffer *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8504" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_QUERYBUF</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8524" +></A +><H2 +>Description</H2 +><P +>This ioctl is part of the <A +HREF="#MMAP" +>memory +mapping</A +> I/O method. It can be used to query the status of a +buffer at any time after buffers have been allocated with the +<A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl.</P +><P +>Applications set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field + of a struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> to the same buffer type as previously +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> <CODE +CLASS="STRUCTFIELD" +>type</CODE +> and struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +>, and the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> + field. Valid index numbers range from zero +to the number of buffers allocated with <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> + (struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> <CODE +CLASS="STRUCTFIELD" +>count</CODE +>) minus one. +After calling <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +> with a pointer to + this structure drivers return an error code or fill the rest of +the structure.</P +><P +>In the <CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field the +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_MAPPED</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_QUEUED</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_DONE</CODE +> flags will be valid. The +<CODE +CLASS="STRUCTFIELD" +>memory</CODE +> field will be set to +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +>, the <CODE +CLASS="STRUCTFIELD" +>m.offset</CODE +> +contains the offset of the buffer from the start of the device memory, +the <CODE +CLASS="STRUCTFIELD" +>length</CODE +> field its size. The driver may +or may not set the remaining fields and flags, they are meaningless in +this context.</P +><P +>The <CODE +CLASS="STRUCTNAME" +>v4l2_buffer</CODE +> structure is + specified in <A +HREF="#BUFFER" +>Section 3.5</A +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8555" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The buffer <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is not +supported, or the <CODE +CLASS="STRUCTFIELD" +>index</CODE +> is out of bounds.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-QUERYCAP" +></A +>ioctl VIDIOC_QUERYCAP</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8570" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_QUERYCAP -- Query device capabilities</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN8573" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN8574" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_capability *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8584" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_QUERYCAP</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8604" +></A +><H2 +>Description</H2 +><P +>All V4L2 devices support the +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +> ioctl. It is used to identify +kernel devices compatible with this specification and to obtain +information about individual hardware capabilities. The ioctl takes a +pointer to a struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> which is filled by the driver. When the +driver is not compatible with this specification the ioctl returns the +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CAPABILITY" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_capability</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>driver</CODE +>[16]</TD +><TD +><P +>Name of the driver, a unique NUL-terminated +ASCII string. For example: "bttv". Driver specific applications shall +use this information to verify the driver identity. It is also useful +to work around known bugs, or to print the driver name and version in +an error report to aid debugging. The driver version is stored in the +<CODE +CLASS="STRUCTFIELD" +>version</CODE +> field. [do we need a registry?]For +example: "bttv". Driver specific applications shall use this +information to verify the driver identity. It is also useful to work +around known bugs, or to print the driver name and version in an error +report to aid debugging. The driver version is stored in the +<CODE +CLASS="STRUCTFIELD" +>version</CODE +> field. [Do we need a +registry?]</P +><P +>Note storing strings in fixed sized arrays is +bad practice but unavoidable here. Drivers and applications should take +precautions to never read or write beyond the array end and to +properly terminate the strings.</P +></TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>card</CODE +>[32]</TD +><TD +>Name of the device, a NUL-terminated ASCII +string. For example: "Yoyodyne TV/FM". Remember that one driver may +support different brands or models of video hardware. This information +can be used to build a menu of available devices for a device-select +user interface. Since drivers may support multiple installed devices +this name should be combined with the +<CODE +CLASS="STRUCTFIELD" +>bus_info</CODE +> string to avoid +ambiguities.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>bus_info</CODE +>[32]</TD +><TD +>Location of the device in the system, a +NUL-terminated ASCII string. For example: "PCI Slot 4". This +information is intended for the user, to distinguish multiple +identical devices. If no such information is available the field may +simply count the devices controlled by the driver, or contain the +empty string (<CODE +CLASS="STRUCTFIELD" +>bus_info</CODE +>[0] = 0). [pci_dev->slot_name example].</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>version</CODE +></TD +><TD +><P +>Version number of the driver. Together with +the <CODE +CLASS="STRUCTFIELD" +>driver</CODE +> field this identifies a +particular driver. The version number is formatted using the +<CODE +CLASS="CONSTANT" +>KERNEL_VERSION()</CODE +> macro:</P +></TD +></TR +><TR +><TD +COLSPAN="3" +><P +><PRE +CLASS="PROGRAMLISTING" +>#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) + +__u32 version = KERNEL_VERSION(0, 8, 1); + +printf ("Version: %u.%u.%u\n", + (version >> 16) & 0xFF, + (version >> 8) & 0xFF, + version & 0xFF);</PRE +></P +></TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +></TD +><TD +>Device capabilities, see <A +HREF="#DEVICE-CAPABILITIES" +>Table 2</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[4]</TD +><TD +>Reserved for future extensions. Drivers must set +this array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="DEVICE-CAPABILITIES" +></A +><P +><B +>Table 2. Device Capabilities Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_CAPTURE</CODE +></TD +><TD +>0x00000001</TD +><TD +>The device supports the <A +HREF="#CAPTURE" +>video capture</A +> interface.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OUTPUT</CODE +></TD +><TD +>0x00000002</TD +><TD +>The device supports the <A +HREF="#OUTPUT" +>video output</A +> interface.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OVERLAY</CODE +></TD +><TD +>0x00000004</TD +><TD +>The device supports the <A +HREF="#OVERLAY" +>video overlay</A +> interface. Overlay typically +stores captured images directly in the video memory of a graphics +card, with support for clipping.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_CAPTURE</CODE +></TD +><TD +>0x00000010</TD +><TD +>The device supports the VBI capture interface, see +<A +HREF="#RAW-VBI" +>Section 4.6</A +>, <A +HREF="#SLICED" +>Section 4.7</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_OUTPUT</CODE +></TD +><TD +>0x00000020</TD +><TD +>The device supports the VBI output interface, +see <A +HREF="#RAW-VBI" +>Section 4.6</A +>, <A +HREF="#SLICED" +>Section 4.7</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_RDS_CAPTURE</CODE +></TD +><TD +>0x00000100</TD +><TD +>[to be defined]</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_TUNER</CODE +></TD +><TD +>0x00010000</TD +><TD +>The device has some sort of tuner or modulator to +receive or emit RF-modulated video signals. For more information see +<A +HREF="#TUNER" +>Section 1.6</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_AUDIO</CODE +></TD +><TD +>0x00020000</TD +><TD +>The device has audio inputs or outputs. For more +information see <A +HREF="#AUDIO" +>Section 1.5</A +>. It may or may not support PCM +sampling or output, this function must be implemented as ALSA or OSS +PCM interface.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_READWRITE</CODE +></TD +><TD +>0x01000000</TD +><TD +>The device supports the <A +HREF="#RW" +>read() +and/or write()</A +> I/O methods.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_ASYNCIO</CODE +></TD +><TD +>0x02000000</TD +><TD +>The device supports the <A +HREF="#ASYNC" +>asynchronous</A +> I/O methods.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_STREAMING</CODE +></TD +><TD +>0x04000000</TD +><TD +>The device supports the <A +HREF="#MMAP" +>streaming</A +> I/O method.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8738" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The kernel device is not compatible with this +specification.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-QUERYCTRL" +></A +>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8753" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_QUERYCTRL, ioctl VIDIOC_QUERYMENU -- Enumerate controls and menu control items</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN8757" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN8758" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_queryctrl *argp);</CODE +></P +><P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN8768" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_querymenu *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8778" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8798" +></A +><H2 +>Description</H2 +><P +>To query the attributes of a control applications set the +<CODE +CLASS="STRUCTFIELD" +>id</CODE +> field of a struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +> ioctl with a pointer to this +structure. The driver fills the rest of the structure or returns an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the <CODE +CLASS="STRUCTFIELD" +>id</CODE +> is invalid.</P +><P +>It is possible to enumerate controls by calling +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +> with successive +<CODE +CLASS="STRUCTFIELD" +>id</CODE +> values starting from +<CODE +CLASS="CONSTANT" +>V4L2_CID_BASE</CODE +> up to and exclusive +<CODE +CLASS="CONSTANT" +>V4L2_CID_BASE_LASTP1</CODE +>, or starting from +<CODE +CLASS="CONSTANT" +>V4L2_CID_PRIVATE_BASE</CODE +> until the driver returns +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +>. When the +<CODE +CLASS="CONSTANT" +>V4L2_CTRL_FLAG_DISABLED</CODE +> flag is set in the +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field, this control is permanently +disabled and should be ignored by the application.<A +NAME="AEN8815" +HREF="#FTN.AEN8815" +><SPAN +CLASS="footnote" +>[25]</SPAN +></A +></P +><P +>Additional information is required for menu controls, the +name of menu items. To query them applications set the +<CODE +CLASS="STRUCTFIELD" +>id</CODE +> and <CODE +CLASS="STRUCTFIELD" +>index</CODE +> +fields of struct <A +HREF="#V4L2-QUERYMENU" +>v4l2_querymenu</A +> and call the +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYMENU</CODE +> ioctl with a pointer to this +structure. The driver fills the rest of the structure or returns an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code when the <CODE +CLASS="STRUCTFIELD" +>id</CODE +> or +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> is invalid. Menu items are enumerated +by calling <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYMENU</CODE +> with successive +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> values from struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> +<CODE +CLASS="STRUCTFIELD" +>minimum</CODE +> (0) to +<CODE +CLASS="STRUCTFIELD" +>maximum</CODE +>, inclusive.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-QUERYCTRL" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_queryctrl</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>id</CODE +></TD +><TD +>Identifies the control, set by the application. +See <A +HREF="#CONTROL-ID" +>Table 1-1</A +> for predefined IDs.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-CTRL-TYPE" +>v4l2_ctrl_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of control, see <A +HREF="#V4L2-CTRL-TYPE" +>Table 3</A +>.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the control, a NUL-terminated ASCII +string. This information is intended for the user.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>minimum</CODE +></TD +><TD +>Minimum value, inclusive. This field is mostly +useful to define a lower bound for integer controls. Note the value is +signed.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>maximum</CODE +></TD +><TD +>Maximum value, inclusive. Note the value is +signed.</TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>step</CODE +></TD +><TD +><P +>Generally drivers should not scale hardware +control values. It may be necessary for example when the +<CODE +CLASS="STRUCTFIELD" +>name</CODE +> or <CODE +CLASS="STRUCTFIELD" +>id</CODE +> imply +a particular unit and the hardware actually accepts only multiples of +said unit. If so, drivers must take care values are properly rounded +when scaling, such that errors will not accumulate on repeated +read-write cycles.</P +><P +>This field reports the smallest change +of an integer control actually affecting hardware. Often the +information is needed when the user can change controls by keyboard or +GUI buttons, rather than a slider. When for example a hardware +register accepts values 0-511 and the driver reports 0-65535, step +should be 128.</P +><P +>Note although signed, the step value is +supposed to be always positive.</P +></TD +></TR +><TR +><TD +>__s32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>default_value</CODE +></TD +><TD +>The default value of the control. Drivers reset +controls only when the driver is loaded, not later, in particular not +when the <CODE +CLASS="FUNCTION" +>open()</CODE +> is called.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>flags</CODE +></TD +><TD +>Control flags, see <A +HREF="#CONTROL-FLAGS" +>Table 4</A +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[2]</TD +><TD +>Reserved for future extensions. Drivers must set +the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-QUERYMENU" +></A +><P +><B +>Table 2. struct <CODE +CLASS="STRUCTNAME" +>v4l2_querymenu</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>id</CODE +></TD +><TD +>Identifies the control, set by the application +from the respective struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> +<CODE +CLASS="STRUCTFIELD" +>id</CODE +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>index</CODE +></TD +><TD +>Index of the menu item, starting at zero, set by + the application.</TD +></TR +><TR +><TD +>__u8</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>name</CODE +>[32]</TD +><TD +>Name of the menu item, a NUL-terminated ASCII +string. This information is intended for the user.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +></TD +><TD +>Reserved for future extensions. Drivers must set +the array to zero.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="V4L2-CTRL-TYPE" +></A +><P +><B +>Table 3. enum v4l2_ctrl_type</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="30%"><COL +WIDTH="5%" +ALIGN="CENTER"><COL +WIDTH="5%" +ALIGN="CENTER"><COL +WIDTH="5%" +ALIGN="CENTER"><COL +WIDTH="55%"><THEAD +><TR +><TH +>Type</TH +><TH +><CODE +CLASS="STRUCTFIELD" +>minimum</CODE +></TH +><TH +><CODE +CLASS="STRUCTFIELD" +>step</CODE +></TH +><TH +><CODE +CLASS="STRUCTFIELD" +>maximum</CODE +></TH +><TH +>Description</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_TYPE_INTEGER</CODE +></TD +><TD +>low value</TD +><TD +>increment (positive) [__u32?]</TD +><TD +>high value</TD +><TD +>An integer-valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values which are actually different on the hardware.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_TYPE_BOOLEAN</CODE +></TD +><TD +>0</TD +><TD +>1</TD +><TD +>1</TD +><TD +>A boolean-valued control. Zero corresponds to +"disabled", and one means "enabled".</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_TYPE_MENU</CODE +></TD +><TD +>0</TD +><TD +>1</TD +><TD +>N-1</TD +><TD +>The control has a menu of N choices. The names of +the menu items can be enumerated with the +<CODE +CLASS="CONSTANT" +>VIDIOC_QUERYMENU</CODE +> ioctl.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_TYPE_BUTTON</CODE +></TD +><TD +>0</TD +><TD +>0</TD +><TD +>0</TD +><TD +>A control which performs an action when set. +Drivers must ignore the value passed with +<CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +> and return an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code on a +<CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +> attempt.</TD +></TR +></TBODY +></TABLE +></DIV +><DIV +CLASS="TABLE" +><A +NAME="CONTROL-FLAGS" +></A +><P +><B +>Table 4. Control Flags</B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="38%" +TITLE="C1"><COL +WIDTH="12%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_FLAG_DISABLED</CODE +></TD +><TD +>0x0001</TD +><TD +>This control is permanently disabled and should be ignored by the application. An attempt to change +this control results in an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_FLAG_GRABBED</CODE +></TD +><TD +>0x0002</TD +><TD +>This control is temporarily unchangeable, for +example because another application took over control of the +respective resource. Such controls may be displayed specially in a +user interface. An attempt to change a "grabbed" control results in an +<SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +> error code.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN8997" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> <CODE +CLASS="STRUCTFIELD" +>id</CODE +> +is invalid. The struct <A +HREF="#V4L2-QUERYMENU" +>v4l2_querymenu</A +> <CODE +CLASS="STRUCTFIELD" +>id</CODE +> or +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> is invalid.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-QUERYSTD" +></A +>ioctl VIDIOC_QUERYSTD</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9015" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_QUERYSTD -- Sense the video standard received by the current input</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9018" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9019" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, v4l2_std_id *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9029" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_QUERYSTD</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9049" +></A +><H2 +>Description</H2 +><P +>The hardware may be able to detect the current video +standard automatically. To do so, applications call <CODE +CLASS="CONSTANT" +>VIDIOC_QUERYSTD</CODE +> with a pointer to a <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> type. The +driver stores here a set of candidates, this can be a single flag or a +set of supported standards if for example the hardware can only +distinguish between 50 and 60 Hz systems. When detection is not +possible or fails, the set must contain all standards supported by the +current video input or output.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9054" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>This ioctl is not supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-REQBUFS" +></A +>ioctl VIDIOC_REQBUFS</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9067" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_REQBUFS -- Initiate Memory Mapping or User Pointer I/O</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9070" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9071" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, struct v4l2_requestbuffers *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9081" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_REQBUFS</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9101" +></A +><H2 +>Description</H2 +><P +>This ioctl is used to initiate <A +HREF="#MMAP" +>memory +mapped</A +> or <A +HREF="#USERP" +>user pointer</A +> +I/O. Memory mapped buffers are located in device memory and must be +allocated with this ioctl before they can be mapped into the +application's address space. User buffers are allocated by +applications themselves, and this ioctl is merely used to switch the +driver into user pointer I/O mode.</P +><P +>To allocate device buffers applications initialize three +fields of a <CODE +CLASS="STRUCTNAME" +>v4l2_requestbuffers</CODE +> structure. +They set the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field to the respective +stream or buffer type, the <CODE +CLASS="STRUCTFIELD" +>count</CODE +> field to +the desired number of buffers, and <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> +must be set to <CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +>. When the ioctl +is called with a pointer to this structure the driver attempts to +allocate the requested number of buffers and stores the actual number +allocated in the <CODE +CLASS="STRUCTFIELD" +>count</CODE +> field. It can be +smaller than the number requested, even zero, when the driver runs out +of free memory. A larger number is possible when the driver requires +more buffers to function correctly.<A +NAME="AEN9113" +HREF="#FTN.AEN9113" +><SPAN +CLASS="footnote" +>[26]</SPAN +></A +> When memory mapping I/O is not supported the ioctl +returns an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><P +>Applications can call <CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +> +again to change the number of buffers, however this cannot succeed +when any buffers are still mapped. A <CODE +CLASS="STRUCTFIELD" +>count</CODE +> +value of zero frees all buffers, after aborting or finishing any DMA +in progress, an implicit <A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +>. </P +><P +>To negotiate user pointer I/O, applications initialize only +the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field and set +<CODE +CLASS="STRUCTFIELD" +>memory</CODE +> to +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_USERPTR</CODE +>. When the ioctl is called +with a pointer to this structure the driver prepares for user pointer +I/O, when this I/O method is not supported the ioctl returns an +<SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L2-REQUESTBUFFERS" +></A +><P +><B +>Table 1. struct <CODE +CLASS="STRUCTNAME" +>v4l2_requestbuffers</CODE +></B +></P +><TABLE +BORDER="0" +FRAME="void" +WIDTH="100%" +CLASS="CALSTABLE" +><COL +WIDTH="25%" +TITLE="C1"><COL +WIDTH="25%" +TITLE="C2"><COL +WIDTH="50%" +TITLE="C3"><TBODY +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>count</CODE +></TD +><TD +>The number of buffers requested or granted. This +field is only used when <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> is set to +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +>.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>type</CODE +></TD +><TD +>Type of the stream or buffers, this is the same +as the struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> <CODE +CLASS="STRUCTFIELD" +>type</CODE +> field. See <A +HREF="#V4L2-BUF-TYPE" +>Table 3-2</A +> for valid values.</TD +></TR +><TR +><TD +>enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +></TD +><TD +><CODE +CLASS="STRUCTFIELD" +>memory</CODE +></TD +><TD +>Applications set this field to +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_MMAP</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_MEMORY_USERPTR</CODE +>.</TD +></TR +><TR +><TD +>__u32</TD +><TD +><CODE +CLASS="STRUCTFIELD" +>reserved</CODE +>[32]</TD +><TD +>A place holder for future extensions and custom +(driver defined) buffer types <CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +> and +higher.</TD +></TR +></TBODY +></TABLE +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9165" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The driver supports multiple opens and I/O is already +in progress, or reallocation of buffers was attempted although one or +more are still mapped.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The buffer type (<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field) or the +requested I/O method (<CODE +CLASS="STRUCTFIELD" +>memory</CODE +>) is not +supported.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="VIDIOC-STREAMON" +></A +>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9187" +></A +><H2 +>Name</H2 +>ioctl VIDIOC_STREAMON, ioctl VIDIOC_STREAMOFF -- Start or stop streaming I/O.</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9191" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9192" +></A +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int ioctl</CODE +>(int fd, int request, const int *argp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9202" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>request</VAR +></DT +><DD +><P +>VIDIOC_STREAMON, VIDIOC_STREAMOFF</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>argp</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9222" +></A +><H2 +>Description</H2 +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> ioctl start and stop the capture +or output process during streaming (<A +HREF="#MMAP" +>memory +mapping</A +> or <A +HREF="#USERP" +>user pointer</A +>) I/O.</P +><P +>Specifically the capture hardware is disabled and no input +buffers are filled (if there are any empty buffers in the incoming +queue) until <CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +> has been called. +Accordingly the output hardware is disabled, no video signal is +produced until <CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +> has been called. +The ioctl will succeed only when at least one output buffer is in the +incoming queue.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> ioctl, apart of +aborting or finishing any DMA in progress, unlocks any user pointer +buffers locked in physical memory, and it removes all buffers from the +incoming and outgoing queues. That means all images captured but not +dequeued yet will be lost, likewise all images enqueued for output but +not transmitted yet. I/O returns to the same state as after calling +<A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> and can be restarted accordingly.</P +><P +>Both ioctls take a pointer to an integer, the desired buffer or +stream type. This is the same as struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +>.</P +><P +>Note applications can be preempted for unknown periods right +before or after the <CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +> or +<CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +> calls, there is no notion of +starting or stopping "now". Buffer timestamps can be used to +synchronize with other events.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9242" +></A +><H2 +>Return Value</H2 +><P +>On success <SPAN +CLASS="RETURNVALUE" +>0</SPAN +> is returned, on +error <SPAN +CLASS="RETURNVALUE" +>-1</SPAN +> and <VAR +CLASS="VARNAME" +>errno</VAR +> is +set appropriately:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>Streaming I/O is not supported, the buffer +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> is not supported, or no buffers have +been allocated (memory mapping) or enqueued (output) yet.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-MMAP" +></A +>mmap</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9256" +></A +><H2 +>Name</H2 +>mmap -- Map device memory into application address space</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9259" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9260" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <unistd.h> +#include <sys/mman.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>void *mmap</CODE +>(void *start, size_t length, int prot, int flags, int fd, off_t offset);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9277" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>start</VAR +></DT +><DD +><P +>Map the buffer to this address in the +application's address space. When the <CODE +CLASS="CONSTANT" +>MAP_FIXED</CODE +> +flag is specified, <VAR +CLASS="PARAMETER" +>start</VAR +> must be a multiple of the +pagesize and mmap will fail when the specified address +cannot be used. Use of this option is discouraged; applications should +just specify a <CODE +CLASS="CONSTANT" +>NULL</CODE +> pointer here.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>length</VAR +></DT +><DD +><P +>Length of the memory area to map. This must be the +same value as returned by the driver in the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +<CODE +CLASS="STRUCTFIELD" +>length</CODE +> field.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>prot</VAR +></DT +><DD +><P +>The <VAR +CLASS="PARAMETER" +>prot</VAR +> argument describes the +desired memory protection. It must be set to +<CODE +CLASS="CONSTANT" +>PROT_READ</CODE +> | <CODE +CLASS="CONSTANT" +>PROT_WRITE</CODE +>, +indicating pages may be read and written. This is a technicality +independent of the +device type and direction of data exchange. Note device memory +accesses may incur a performance penalty. It can happen when writing +to capture buffers, when reading from output buffers, or always. When +the application intends to modify buffers, other I/O methods may be +more efficient.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>flags</VAR +></DT +><DD +><P +>The <VAR +CLASS="PARAMETER" +>flags</VAR +> parameter +specifies the type of the mapped object, mapping options and whether +modifications made to the mapped copy of the page are private to the +process or are to be shared with other references.</P +><P +><CODE +CLASS="CONSTANT" +>MAP_FIXED</CODE +> requests that the +driver selects no other address than the one specified. If the +specified address cannot be used, mmap will fail. If +<CODE +CLASS="CONSTANT" +>MAP_FIXED</CODE +> is specified, +<VAR +CLASS="PARAMETER" +>start</VAR +> must be a multiple of the pagesize. Use +of this option is discouraged.</P +><P +>One of the <CODE +CLASS="CONSTANT" +>MAP_SHARED</CODE +> or +<CODE +CLASS="CONSTANT" +>MAP_PRIVATE</CODE +> flags must be set. +<CODE +CLASS="CONSTANT" +>MAP_SHARED</CODE +> allows to share this mapping with all +other processes that map this object. <CODE +CLASS="CONSTANT" +>MAP_PRIVATE</CODE +> +requests copy-on-write semantics. We recommend to set +<CODE +CLASS="CONSTANT" +>MAP_SHARED</CODE +>. The <CODE +CLASS="CONSTANT" +>MAP_PRIVATE</CODE +>, +<CODE +CLASS="CONSTANT" +>MAP_DENYWRITE</CODE +>, +<CODE +CLASS="CONSTANT" +>MAP_EXECUTABLE</CODE +> and <CODE +CLASS="CONSTANT" +>MAP_ANON</CODE +> +flags should not be set.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>offset</VAR +></DT +><DD +><P +>Offset of the buffer in device memory. This must be the +same value as returned by the driver in the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +<CODE +CLASS="STRUCTFIELD" +>m</CODE +> union <CODE +CLASS="STRUCTFIELD" +>offset</CODE +> field.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9338" +></A +><H2 +>Description</H2 +><P +>The <CODE +CLASS="FUNCTION" +>mmap()</CODE +> function asks to map +<VAR +CLASS="PARAMETER" +>length</VAR +> bytes starting at +<VAR +CLASS="PARAMETER" +>offset</VAR +> in the memory of the device specified by +<VAR +CLASS="PARAMETER" +>fd</VAR +> into the application address space, +preferably at address <VAR +CLASS="PARAMETER" +>start</VAR +>. This latter +address is a hint only, and is usually specified as 0.</P +><P +>Suitable length and offset parameters are queried with the +<A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +> ioctl. Buffers must be allocated with the +<A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl before they can be queried.</P +><P +>To unmap buffers the <A +HREF="#FUNC-MUNMAP" +><CODE +CLASS="FUNCTION" +>munmap()</CODE +></A +> function is used.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9354" +></A +><H2 +>Return Value</H2 +><P +>On success, <CODE +CLASS="FUNCTION" +>mmap()</CODE +> returns a pointer to +the mapped buffer. On error, <CODE +CLASS="CONSTANT" +>MAP_FAILED</CODE +> (-1) is +returned, and <VAR +CLASS="VARNAME" +>errno</VAR +> is set appropriately. Possible +error codes:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EBADF</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is not a valid file +descriptor.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EACCESS</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is +not open for reading and writing.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The <VAR +CLASS="PARAMETER" +>start</VAR +> or +<VAR +CLASS="PARAMETER" +>length</VAR +> or <VAR +CLASS="PARAMETER" +>offset</VAR +> are not +suitable. (E.g., they are too large, or not aligned on a +<CODE +CLASS="CONSTANT" +>PAGESIZE</CODE +> boundary.) Or no buffers have been +allocated with the <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENOMEM</SPAN +></DT +><DD +><P +>No memory is available.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-MUNMAP" +></A +>munmap</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9390" +></A +><H2 +>Name</H2 +>munmap -- Unmap device memory</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9393" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9394" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <unistd.h> +#include <sys/mman.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int munmap</CODE +>(void *start, size_t length);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9403" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>start</VAR +></DT +><DD +><P +>Address of the mapped buffer as returned by the +<A +HREF="#FUNC-MMAP" +><CODE +CLASS="FUNCTION" +>mmap()</CODE +></A +> function.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>length</VAR +></DT +><DD +><P +>Length of the mapped buffer. This must be the same +value as given to <CODE +CLASS="FUNCTION" +>mmap()</CODE +> and returned by the +driver in the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> <CODE +CLASS="STRUCTFIELD" +>length</CODE +> +field.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9421" +></A +><H2 +>Description</H2 +><P +>Unmaps a previously with the <A +HREF="#FUNC-MMAP" +><CODE +CLASS="FUNCTION" +>mmap()</CODE +></A +> function mapped +buffer and frees it, if possible. </P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9426" +></A +><H2 +>Return Value</H2 +><P +>On success <CODE +CLASS="FUNCTION" +>munmap()</CODE +> returns 0, on +failure -1, and errno is set.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The <VAR +CLASS="PARAMETER" +>start</VAR +> or +<VAR +CLASS="PARAMETER" +>length</VAR +> is incorrect, or no buffers have been +mapped yet.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-OPEN" +></A +>open</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9439" +></A +><H2 +>Name</H2 +>open -- Open a V4L2 device</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9442" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9443" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <fcntl.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int open</CODE +>(const char *device_name, int flags);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9452" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>device_name</VAR +></DT +><DD +><P +>Device to be opened.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>flags</VAR +></DT +><DD +><P +>Open flags. Access mode must be +<CODE +CLASS="CONSTANT" +>O_RDWR</CODE +>. This is just a technicality, input devices +still support only reading and output devices only writing.</P +><P +>When the <CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag is +given, the read() function and the <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl will return +the <SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +> error code when no data is available or no buffer is in the driver +outgoing queue, otherwise these functions block until data becomes +available. All V4L2 drivers exchanging data with applications must +support the <CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag.</P +><P +>Other flags have no effect.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9473" +></A +><H2 +>Description</H2 +><P +>To open a V4L2 device applications call +<CODE +CLASS="FUNCTION" +>open()</CODE +> with the desired device name. This +function has no side effects; all data format parameters, current +input or output, control values or other properties remain unchanged. +At the first <CODE +CLASS="FUNCTION" +>open()</CODE +> call after loading the driver +they will be reset to default values, drivers are never in an +undefined state.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9478" +></A +><H2 +>Return Value</H2 +><P +>On success <CODE +CLASS="FUNCTION" +>open</CODE +> returns the new +file descriptor. On error -1 is returned, and <VAR +CLASS="VARNAME" +>errno</VAR +> +is set appropriately. Possible error codes:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EACCES</SPAN +></DT +><DD +><P +>The caller has no permission to access the +device.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The driver does not support multiple opens and the +device is already in use.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENXIO</SPAN +></DT +><DD +><P +>No device corresponding to this device special file +exists.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENOMEM</SPAN +></DT +><DD +><P +>Insufficient kernel memory was available.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EMFILE</SPAN +></DT +><DD +><P +>The process already has the maximum number of +files open.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>ENFILE</SPAN +></DT +><DD +><P +>The limit on the total number of files open on the +system has been reached.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-POLL" +></A +>poll</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9515" +></A +><H2 +>Name</H2 +>poll -- Wait for some event on a file descriptor</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9518" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9519" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <sys/poll.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int poll</CODE +>(struct pollfd *ufds, unsigned int nfds, int timeout);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9530" +></A +><H2 +>Description</H2 +><P +>All drivers implementing the <CODE +CLASS="FUNCTION" +>read()</CODE +> +or <CODE +CLASS="FUNCTION" +>write()</CODE +> function or streaming I/O must also support the +<CODE +CLASS="FUNCTION" +>poll()</CODE +> function. See the +<CODE +CLASS="FUNCTION" +>poll()</CODE +> manual page for details.</P +></DIV +><H1 +><A +NAME="FUNC-READ" +></A +>read</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9538" +></A +><H2 +>Name</H2 +>read -- Read from a V4L2 device</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9541" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9542" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <unistd.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>ssize_t read</CODE +>(int fd, void *buf, size_t count);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9553" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>buf</VAR +></DT +><DD +><P +></P +></DD +><DT +><VAR +CLASS="PARAMETER" +>count</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9573" +></A +><H2 +>Description</H2 +><P +><CODE +CLASS="FUNCTION" +>read()</CODE +> attempts to read up to +<VAR +CLASS="PARAMETER" +>count</VAR +> bytes from file descriptor +<VAR +CLASS="PARAMETER" +>fd</VAR +> into the buffer starting at +<VAR +CLASS="PARAMETER" +>buf</VAR +>. The layout of the data in the buffer is +discussed in the respective device interface section, see ##. If <VAR +CLASS="PARAMETER" +>count</VAR +> is zero, +<CODE +CLASS="FUNCTION" +>read()</CODE +> returns zero and has no other results. If +<VAR +CLASS="PARAMETER" +>count</VAR +> is greater than +<CODE +CLASS="CONSTANT" +>SSIZE_MAX</CODE +>, the result is unspecified. Regardless +of the <VAR +CLASS="PARAMETER" +>count</VAR +> value each +<CODE +CLASS="FUNCTION" +>read()</CODE +> call will provide at most one frame (two +fields) worth of data.</P +><P +>By default <CODE +CLASS="FUNCTION" +>read()</CODE +> blocks until data +becomes available. When the <CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag was +given to the <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> function it +returns immediately with an <SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +> error code when no data is available. The +<A +HREF="#FUNC-SELECT" +><CODE +CLASS="FUNCTION" +>select()</CODE +></A +> or <A +HREF="#FUNC-POLL" +><CODE +CLASS="FUNCTION" +>poll()</CODE +></A +> functions +can always be used to suspend execution until data becomes available. All +drivers supporting the <CODE +CLASS="FUNCTION" +>read()</CODE +> function must also +support <CODE +CLASS="FUNCTION" +>select()</CODE +> and +<CODE +CLASS="FUNCTION" +>poll()</CODE +>.</P +><P +>Drivers can implement read functionality in different +ways, using a single or multiple buffers and discarding the oldest or +newest frames once the internal buffers are filled.</P +><P +><CODE +CLASS="FUNCTION" +>read()</CODE +> never returns a "snapshot" of a +buffer being filled. Using a single buffer the driver will stop +capturing when the application starts reading the buffer until the +read is finished. Thus only the period of the vertical blanking +interval is available for reading, or the capture rate must fall below +the nominal frame rate of the video standard.</P +><P +>The behavior of +<CODE +CLASS="FUNCTION" +>read()</CODE +> when called during the active picture +period or the vertical blanking separating the top and bottom field +depends on the discarding policy. A driver discarding the oldest +frames keeps capturing into an internal buffer, continuously +overwriting the previously, not read frame, and returns the frame +being received at the time of the <CODE +CLASS="FUNCTION" +>read()</CODE +> call as +soon as it is complete.</P +><P +>A driver discarding the newest frames stops capturing until +the next <CODE +CLASS="FUNCTION" +>read()</CODE +> call. The frame being received at +<CODE +CLASS="FUNCTION" +>read()</CODE +> time is discarded, returning the following +frame instead. Again this implies a reduction of the capture rate to +one half or less of the nominal frame rate. An example of this model +is the video read mode of the "bttv" driver, initiating a DMA to user +memory when <CODE +CLASS="FUNCTION" +>read()</CODE +> is called and returning when +the DMA finished.</P +><P +>In the multiple buffer model drivers maintain a ring of +internal buffers, automatically advancing to the next free buffer. +This allows continuous capturing when the application can empty the +buffers fast enough. Again, the behavior when the driver runs out of +free buffers depends on the discarding policy.</P +><P +>Applications can get and set the number of buffers used +internally by the driver with the streaming parameter ioctls, see +##streaming-par. They +are optional, however. The discarding policy is not reported and +cannot be changed. For minimum requirements see the respective device +interface section in ##.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9611" +></A +><H2 +>Return Value</H2 +><P +>On success, the number of bytes read is returned. +It is not an error if this number is smaller than the number of bytes +requested, or the amount of data required for one frame. This may +happen for example because <CODE +CLASS="FUNCTION" +>read()</CODE +> was interrupted +by a signal. On error, -1 is returned, and <VAR +CLASS="VARNAME" +>errno</VAR +> +is set appropriately. In this case the next read will start at the +beginning of a new frame. Possible error codes:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +></DT +><DD +><P +>Non-blocking I/O has been selected using +O_NONBLOCK and no data was immediately available for reading.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBADF</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is not a valid file +descriptor or is not open for reading, or the process already has the +maximum number of files open.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The driver does not support multiple read streams and the +device is already in use.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EFAULT</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>buf</VAR +> is outside your +accessible address space.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINTR</SPAN +></DT +><DD +><P +>The call was interrupted by a signal before any +data was read.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EIO</SPAN +></DT +><DD +><P +>I/O error. This indicates some hardware problem or a +failure to communicate with a remote device (USB camera etc.).</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The <CODE +CLASS="FUNCTION" +>read()</CODE +> function is not +supported by this driver, not on this device, or generally not on this +type of device.</P +></DD +></DL +></DIV +></DIV +><H1 +><A +NAME="FUNC-SELECT" +></A +>select</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9656" +></A +><H2 +>Name</H2 +>select -- Synchronous I/O multiplexing</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9659" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9660" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <sys/time.h> +#include <sys/types.h> +#include <unistd.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int select</CODE +>(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9675" +></A +><H2 +>Description</H2 +><P +>All drivers implementing the <CODE +CLASS="FUNCTION" +>read()</CODE +> +or <CODE +CLASS="FUNCTION" +>write()</CODE +> function or streaming I/O must also support the +<CODE +CLASS="FUNCTION" +>select()</CODE +> function. See the +<CODE +CLASS="FUNCTION" +>select()</CODE +> manual page for details.</P +></DIV +><H1 +><A +NAME="FUNC-WRITE" +></A +>write</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN9683" +></A +><H2 +>Name</H2 +>write -- Write to a V4L2 device</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN9686" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN9687" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <unistd.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>ssize_t write</CODE +>(int fd, void *buf, size_t count);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9698" +></A +><H2 +>Arguments</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><VAR +CLASS="PARAMETER" +>fd</VAR +></DT +><DD +><P +>File descriptor returned by <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +>.</P +></DD +><DT +><VAR +CLASS="PARAMETER" +>buf</VAR +></DT +><DD +><P +></P +></DD +><DT +><VAR +CLASS="PARAMETER" +>count</VAR +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9718" +></A +><H2 +>Description</H2 +><P +><CODE +CLASS="FUNCTION" +>write()</CODE +> +writes up to <VAR +CLASS="PARAMETER" +>count</VAR +> bytes to the device referenced by + the file descriptor <VAR +CLASS="PARAMETER" +>fd</VAR +> from the buffer +starting at <VAR +CLASS="PARAMETER" +>buf</VAR +>. +If <VAR +CLASS="PARAMETER" +>count</VAR +> is zero, 0 will be returned without +causing any other effect. [implementation tbd]</P +><P +>When the application does not provide more data in time, the +previous frame is displayed again.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN9727" +></A +><H2 +>Return Value</H2 +><P +>On success, the number of bytes written are returned. +Zero indicates nothing was written. [tbd] On error, -1 is +returned, and <VAR +CLASS="VARNAME" +>errno</VAR +> is set appropriately. In this +case the next write will start at the beginning of a new frame. +Possible error codes:</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +></DT +><DD +><P +>Non-blocking I/O has been selected using +O_NONBLOCK and no buffer space was available to write the data +immediately. [tbd]</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBADF</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>fd</VAR +> is not a valid file +descriptor or is not open for writing.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EBUSY</SPAN +></DT +><DD +><P +>The driver does not support multiple write streams and the +device is already in use.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EFAULT</SPAN +></DT +><DD +><P +><VAR +CLASS="PARAMETER" +>buf</VAR +> is outside your +accessible address space.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINTR</SPAN +></DT +><DD +><P +>The call was interrupted by a signal before any +data was written.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EIO</SPAN +></DT +><DD +><P +>I/O error. This indicates some hardware problem.</P +></DD +><DT +><SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +></DT +><DD +><P +>The <CODE +CLASS="FUNCTION" +>write()</CODE +> function is not +supported by this driver, not on this device, or generally not on this +type of device.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="DRIVER" +></A +>Chapter 5. Driver Interface</H1 +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="FOO" +>5.1. to do</A +></H2 +><DIV +CLASS="SECTION" +><H3 +CLASS="SECTION" +><A +NAME="AEN9774" +>5.1.1. to do</A +></H3 +><P +>to do</P +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="COMPAT" +></A +>Chapter 6. History</H1 +><P +>The following chapters document the evolution of the V4L2 API, +errata or extensions. They shall also aid application and driver +writers porting their software to later versions of V4L2.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="DIFF-V4L" +>6.1. Differences between V4L and V4L2</A +></H2 +><P +>The Video For Linux API was first introduced in Linux 2.1 to +unify and replace various TV and radio device related interfaces, +developped independently by driver writers in prior years. Starting +with Linux 2.5 the much improved V4L2 API replaces the V4L API, +although existing drivers will continue to support V4L in the future, +either directly or through the V4L2 compatibility layer. For a +transition period not all drivers will support the V4L2 API.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN9783" +>6.1.1. Opening and Closing Devices</A +></H3 +><P +>For compatibility reasons the character device file names +recommended for V4L2 video capture, overlay, radio, teletext and raw +vbi capture devices did not change from those used by V4L. They are +listed in <A +HREF="#DEVICES" +>Chapter 4</A +> and below in <A +HREF="#V4L-DEV" +>Table 6-1</A +>.</P +><P +>The V4L "videodev" module automatically assigns minor +numbers to drivers in load order, depending on the registered device +type. We recommend V4L2 drivers by default register devices with the +same numbers, but in principle the system administrator can assign +arbitrary minor numbers using driver module options. The major device +number remains 81.</P +><DIV +CLASS="TABLE" +><A +NAME="V4L-DEV" +></A +><P +><B +>Table 6-1. V4L Device Types, Names and Numbers</B +></P +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><COL><THEAD +><TR +><TH +>Device Type</TH +><TH +>File Name</TH +><TH +>Minor Numbers</TH +></TR +></THEAD +><TBODY +><TR +><TD +>Video capture and overlay</TD +><TD +><P +><TT +CLASS="FILENAME" +>/dev/video</TT +> and +<TT +CLASS="FILENAME" +>/dev/bttv0</TT +><SUP +>a</SUP +>, <TT +CLASS="FILENAME" +>/dev/video0</TT +> to +<TT +CLASS="FILENAME" +>/dev/video63</TT +></P +></TD +><TD +>0-63</TD +></TR +><TR +><TD +>Radio receiver</TD +><TD +><P +><TT +CLASS="FILENAME" +>/dev/radio</TT +><SUP +>b</SUP +>, <TT +CLASS="FILENAME" +>/dev/radio0</TT +> to +<TT +CLASS="FILENAME" +>/dev/radio63</TT +></P +></TD +><TD +>64-127</TD +></TR +><TR +><TD +>Teletext decoder</TD +><TD +><P +><TT +CLASS="FILENAME" +>/dev/vtx</TT +>, +<TT +CLASS="FILENAME" +>/dev/vtx0</TT +> to +<TT +CLASS="FILENAME" +>/dev/vtx31</TT +></P +></TD +><TD +>192-223</TD +></TR +><TR +><TD +>Raw VBI capture</TD +><TD +><P +><TT +CLASS="FILENAME" +>/dev/vbi</TT +>, +<TT +CLASS="FILENAME" +>/dev/vbi0</TT +> to +<TT +CLASS="FILENAME" +>/dev/vbi15</TT +></P +></TD +><TD +><P +>224-239<SUP +>c</SUP +></P +></TD +></TR +></TBODY +><TR +><TD +COLSPAN="3" +>Notes:<BR><A +NAME="FTN.AEN9804" +>a. </A +>According to Documentation/devices.txt these +should be symbolic links to <TT +CLASS="FILENAME" +>/dev/video0</TT +>. Note the original bttv interface is not compatible with V4L or V4L2.<BR><A +NAME="FTN.AEN9815" +>b. </A +>According to +<TT +CLASS="FILENAME" +>Documentation/devices.txt</TT +> a symbolic link to +<TT +CLASS="FILENAME" +>/dev/radio0</TT +>.<BR><A +NAME="FTN.AEN9839" +>c. </A +>The range used to be 224-255. More device +types may be added in the future, so you should expect more range +splitting in the future.<BR></TD +></TR +></TABLE +></DIV +><P +>V4L prohibits (or used to) multiple opens. V4L2 drivers +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>may</I +></SPAN +> support multiple opens, see <A +HREF="#OPEN" +>Section 1.1</A +> for details and consequences.</P +><P +>V4L drivers respond to V4L2 ioctls with the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code. The +V4L2 "videodev" module backward compatibility layer can translate V4L +ioctl requests to their V4L2 counterpart, however a V4L2 driver +usually needs more preparation to become fully V4L compatible. This is +covered in more detail in <A +HREF="#DRIVER" +>Chapter 5</A +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN9847" +>6.1.2. Querying Capabilities</A +></H3 +><P +>The V4L <CODE +CLASS="CONSTANT" +>VIDIOCGCAP</CODE +> ioctl is + equivalent to V4L2's <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>name</CODE +> field in struct +<CODE +CLASS="STRUCTNAME" +>video_capability</CODE +> became +<CODE +CLASS="STRUCTFIELD" +>card</CODE +> in struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +>, +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> was replaced by +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +>. Note V4L2 does not +distinguish between device types like this, better think of +basic video input, video output and radio devices supporting a set +of related functions like video capturing, video overlay and VBI +capturing. See <A +HREF="#OPEN" +>Section 1.1</A +> for an introduction.<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN9861" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><COL><THEAD +><TR +><TH +>struct <CODE +CLASS="STRUCTNAME" +>video_capability</CODE +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +></TH +><TH +>struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +<CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> flags</TH +><TH +>Purpose</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_CAPTURE</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_CAPTURE</CODE +></TD +><TD +>The <A +HREF="#CAPTURE" +>video +capture</A +> interface is supported.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_TUNER</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_TUNER</CODE +></TD +><TD +>The device has a <A +HREF="#TUNER" +>tuner or +modulator</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_TELETEXT</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_CAPTURE</CODE +></TD +><TD +>The <A +HREF="#RAW-VBI" +>raw VBI +capture</A +> interface is supported.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_OVERLAY</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OVERLAY</CODE +></TD +><TD +>The <A +HREF="#OVERLAY" +>video overlay</A +> +interface is supported.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_CHROMAKEY</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_CHROMAKEY</CODE +> in +field <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> of +struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +></TD +><TD +>Whether chromakey overlay is supported. For +more information on overlay see +<A +HREF="#OVERLAY" +>Section 4.2</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_CLIPPING</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_LIST_CLIPPING</CODE +> +and <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_BITMAP_CLIPPING</CODE +> in field +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> of struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +></TD +><TD +>Whether clipping the overlaid image is +supported, see <A +HREF="#OVERLAY" +>Section 4.2</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_FRAMERAM</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_EXTERNOVERLAY</CODE +> +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>not set</I +></SPAN +> in field +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> of struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +></TD +><TD +>Whether overlay overwrites frame buffer memory, +see <A +HREF="#OVERLAY" +>Section 4.2</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_SCALES</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +>This flag indicates if the hardware can scale +images. The V4L2 API implies the scale factor by setting the cropping +dimensions and image size with the <A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +></A +> and <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> +ioctl, respectively. The driver returns the closest sizes possible. +For more information on cropping and scaling see <A +HREF="#CROP" +>Section 1.10</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_MONOCHROME</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +>Applications can enumerate the supported image +formats with the <A +HREF="#VIDIOC-ENUM-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUM_FMT</CODE +></A +> ioctl to determine if the device +supports grey scale capturing only. For more information on image +formats see <A +HREF="#PIXFMT" +>Chapter 2</A +>.</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VID_TYPE_SUBCAPTURE</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +>Applications can call the <A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +></A +> ioctl +to determine if the device supports capturing a subsection of the full +picture ("cropping" in V4L2). If not, the ioctl returns the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code. +For more information on cropping and scaling see <A +HREF="#CROP" +>Section 1.10</A +>.</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +><P +>The <CODE +CLASS="STRUCTFIELD" +>audios</CODE +> field was replaced +by <CODE +CLASS="STRUCTFIELD" +>capabilities</CODE +> flag +<CODE +CLASS="CONSTANT" +>V4L2_CAP_AUDIO</CODE +>, indicating +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>if</I +></SPAN +> the device has any audio inputs or outputs. To +determine their number applications can enumerate audio inputs with +the <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +></A +> ioctl. The audio ioctls are described in <A +HREF="#AUDIO" +>Section 1.5</A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>maxwidth</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>maxheight</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>minwidth</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>minheight</CODE +> fields were removed. Calling the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> or <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +></A +> ioctl with the desired dimensions +returns the closest size possible, taking into account the current +video standard, cropping and scaling.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN9977" +>6.1.3. Video Sources</A +></H3 +><P +>V4L provides the <CODE +CLASS="CONSTANT" +>VIDIOCGCHAN</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSCHAN</CODE +> ioctl using struct +<CODE +CLASS="STRUCTNAME" +>video_channel</CODE +> to enumerate +the video inputs of a V4L device. The equivalent V4L2 ioctls +are <A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +>, <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_INPUT</CODE +></A +> and <A +HREF="#VIDIOC-G-INPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_INPUT</CODE +></A +> +using struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> as discussed in <A +HREF="#VIDEO" +>Section 1.4</A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>channel</CODE +> field counting +inputs was renamed to <CODE +CLASS="STRUCTFIELD" +>index</CODE +>, the video +input types were renamed: <DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN9994" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>struct <CODE +CLASS="STRUCTNAME" +>video_channel</CODE +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +></TH +><TH +>struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> +<CODE +CLASS="STRUCTFIELD" +>type</CODE +></TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_TYPE_TV</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_TUNER</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_TYPE_CAMERA</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_CAMERA</CODE +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +><P +>Unlike the <CODE +CLASS="STRUCTFIELD" +>tuners</CODE +> field +expressing the number of tuners of this input, V4L2 assumes each +video input is associated with at most one tuner. On the contrary a +tuner can have more than one input, i.e. RF connectors, and a device +can have multiple tuners. The index of the tuner associated with the +input, if any, is stored in field <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> of +struct <CODE +CLASS="STRUCTNAME" +>v4l2_input</CODE +>. Enumeration of tuners is +discussed in <A +HREF="#TUNER" +>Section 1.6</A +>.</P +><P +>The redundant <CODE +CLASS="CONSTANT" +>VIDEO_VC_TUNER</CODE +> flag was +dropped. Video inputs associated with a tuner are of type +<CODE +CLASS="CONSTANT" +>V4L2_INPUT_TYPE_TUNER</CODE +>. The +<CODE +CLASS="CONSTANT" +>VIDEO_VC_AUDIO</CODE +> flag was replaced by the +<CODE +CLASS="STRUCTFIELD" +>audioset</CODE +> field. V4L2 considers devices with +up to 32 audio inputs. Each set bit in the +<CODE +CLASS="STRUCTFIELD" +>audioset</CODE +> field represents one audio input +this video input combines with. For information about audio inputs and +how to switch see <A +HREF="#AUDIO" +>Section 1.5</A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>norm</CODE +> field describing the +supported video standards was replaced by +<CODE +CLASS="STRUCTFIELD" +>std</CODE +>. The V4L specification mentions a flag +<CODE +CLASS="CONSTANT" +>VIDEO_VC_NORM</CODE +> indicating whether the standard can +be changed. This flag was a later addition together with the +<CODE +CLASS="STRUCTFIELD" +>norm</CODE +> field and has been removed in the +meantime. V4L2 has a similar, albeit more comprehensive approach +to video standards, see <A +HREF="#STANDARD" +>Section 1.7</A +> for more +information.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10033" +>6.1.4. Tuning</A +></H3 +><P +>The V4L <CODE +CLASS="CONSTANT" +>VIDIOCGTUNER</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSTUNER</CODE +> ioctl and struct +<CODE +CLASS="STRUCTNAME" +>video_tuner</CODE +> can be used to enumerate the +tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are +<A +HREF="#VIDIOC-G-TUNER" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_TUNER</CODE +></A +> and <A +HREF="#VIDIOC-G-TUNER" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_TUNER</CODE +></A +> using struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +>. Tuners are +covered in <A +HREF="#TUNER" +>Section 1.6</A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> field counting tuners +was renamed to <CODE +CLASS="STRUCTFIELD" +>index</CODE +>. The fields +<CODE +CLASS="STRUCTFIELD" +>name</CODE +>, <CODE +CLASS="STRUCTFIELD" +>rangelow</CODE +> +and <CODE +CLASS="STRUCTFIELD" +>rangehigh</CODE +> remained unchanged.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDEO_TUNER_PAL</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDEO_TUNER_NTSC</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDEO_TUNER_SECAM</CODE +> flags indicating the supported +video standards were dropped. This information is now contained in the +associated struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +>. No replacement exists for the +<CODE +CLASS="CONSTANT" +>VIDEO_TUNER_NORM</CODE +> flag indicating whether the +video standard can be switched. The <CODE +CLASS="STRUCTFIELD" +>mode</CODE +> +field to select a different video standard was replaced by a whole new +set of ioctls and structures described in <A +HREF="#STANDARD" +>Section 1.7</A +>. +Due to its ubiquity it should be mentioned the BTTV driver supports +several standards in addition to the regular +<CODE +CLASS="CONSTANT" +>VIDEO_MODE_PAL</CODE +> (0), +<CODE +CLASS="CONSTANT" +>VIDEO_MODE_NTSC</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDEO_MODE_SECAM</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDEO_MODE_AUTO</CODE +> (3). Namely N/PAL Argentina, +M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDEO_TUNER_STEREO_ON</CODE +> flag +indicating stereo reception became +<CODE +CLASS="CONSTANT" +>V4L2_TUNER_SUB_STEREO</CODE +> in field +<CODE +CLASS="STRUCTFIELD" +>rxsubchans</CODE +>. This field also permits the +detection of monaural and bilingual audio, see the definition of +struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> for details. Presently no replacement exists for the +<CODE +CLASS="CONSTANT" +>VIDEO_TUNER_RDS_ON</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDEO_TUNER_MBS_ON</CODE +> flags.</P +><P +> The <CODE +CLASS="CONSTANT" +>VIDEO_TUNER_LOW</CODE +> flag was renamed +to <CODE +CLASS="CONSTANT" +>V4L2_TUNER_CAP_LOW</CODE +> in the struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> field.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOCGFREQ</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSFREQ</CODE +> ioctl to change the tuner frequency +where renamed to <A +HREF="#VIDIOC-G-FREQUENCY" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FREQUENCY</CODE +></A +> and <A +HREF="#VIDIOC-G-FREQUENCY" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FREQUENCY</CODE +></A +>. They +take a pointer to a struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +> instead of an unsigned long +integer.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="V4L-IMAGE-PROPERTIES" +>6.1.5. Image Properties</A +></H3 +><P +>V4L2 has no equivalent of the +<CODE +CLASS="CONSTANT" +>VIDIOCGPICT</CODE +> and <CODE +CLASS="CONSTANT" +>VIDIOCSPICT</CODE +> +ioctl and struct <CODE +CLASS="STRUCTNAME" +>video_picture</CODE +>. The following +fields where replaced by V4L2 controls accessible with the +<A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +>, <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +></A +> and <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +> ioctls:<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10095" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>struct <CODE +CLASS="STRUCTNAME" +>video_picture</CODE +></TH +><TH +>V4L2 Control ID</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>brightness</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_BRIGHTNESS</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>hue</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_HUE</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>colour</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_SATURATION</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>contrast</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_CONTRAST</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>whiteness</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_WHITENESS</CODE +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +><P +>The V4L picture controls are assumed to range from 0 to +65535 with no particular reset value. The V4L2 API permits arbitrary +limits and defaults which can be queried with the <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +> +ioctl. For general information about controls see <A +HREF="#CONTROL" +>Section 1.8</A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>depth</CODE +> (average number of +bits per pixel) of a video image is implied by the selected image +format. V4L2 does not explicitely provide such information assuming +applications recognizing the format are aware of the image depth and +others need not know. The <CODE +CLASS="STRUCTFIELD" +>palette</CODE +> field +moved into the struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +>:<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10136" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>struct <CODE +CLASS="STRUCTNAME" +>video_picture</CODE +> +<CODE +CLASS="STRUCTFIELD" +>palette</CODE +></TH +><TH +>struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> +<CODE +CLASS="STRUCTFIELD" +>pixfmt</CODE +></TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_GREY</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-GREY" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_HI240</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-RESERVED" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_HI240</CODE +></A +><SUP +>a</SUP +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RGB565</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-RGB" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB565</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RGB555</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-RGB" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB555</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RGB24</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-RGB" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR24</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RGB32</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-RGB" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR32</CODE +></A +><SUP +>b</SUP +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV422</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-YUYV" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +></A +></P +></TD +></TR +><TR +><TD +><P +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUYV</CODE +><SUP +>c</SUP +></P +></TD +><TD +><P +><A +HREF="#PIXFMT-YUYV" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUYV</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_UYVY</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-UYVY" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_UYVY</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV420</CODE +></TD +><TD +>None</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV411</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-Y41P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +></A +><SUP +>d</SUP +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RAW</CODE +></TD +><TD +><P +>None<SUP +>e</SUP +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV422P</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-YUV422P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV422P</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV411P</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-YUV411P" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +></A +><SUP +>f</SUP +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV420P</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-YVU420" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU420</CODE +></A +></P +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV410P</CODE +></TD +><TD +><P +><A +HREF="#PIXFMT-YVU410" +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YVU410</CODE +></A +></P +></TD +></TR +></TBODY +><TR +><TD +COLSPAN="2" +>Notes:<BR><A +NAME="FTN.AEN10161" +>a. </A +>This is a custom format used by the BTTV +driver, not one of the V4L2 standard formats.<BR><A +NAME="FTN.AEN10191" +>b. </A +>Presumably all V4L RGB formats are +little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue +swapped variants. For details see <A +HREF="#PIXFMT-RGB" +>Section 2.3</A +>.<BR><A +NAME="FTN.AEN10205" +>c. </A +><CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUV422</CODE +> +and <CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_YUYV</CODE +> are the same formats. Some +V4L drivers respond to one, some to the other.<BR><A +NAME="FTN.AEN10231" +>d. </A +>Not to be confused with +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_YUV411P</CODE +>, which is a planar +format.<BR><A +NAME="FTN.AEN10239" +>e. </A +>V4L explains this +as: "RAW capture (BT848)"<BR><A +NAME="FTN.AEN10255" +>f. </A +>Not to be confused with +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_Y41P</CODE +>, which is a packed +format.<BR></TD +></TR +></TABLE +><P +></P +></DIV +></P +><P +>V4L2 image formats are defined in <A +HREF="#PIXFMT" +>Chapter 2</A +>. The image format can be selected with the +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10276" +>6.1.6. Audio</A +></H3 +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOCGAUDIO</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSAUDIO</CODE +> ioctl and struct +<CODE +CLASS="STRUCTNAME" +>video_audio</CODE +> are used to enumerate the +audio inputs of a V4L device. The equivalent V4L2 ioctls are +<A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +></A +> and <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_AUDIO</CODE +></A +> using struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> as +discussed in <A +HREF="#AUDIO" +>Section 1.5</A +>.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>audio</CODE +> "channel number" +field counting audio inputs was renamed to +<CODE +CLASS="STRUCTFIELD" +>index</CODE +>.</P +><P +>On <CODE +CLASS="CONSTANT" +>VIDIOCSAUDIO</CODE +> the +<CODE +CLASS="STRUCTFIELD" +>mode</CODE +> field selects <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>one</I +></SPAN +> +of the <CODE +CLASS="CONSTANT" +>VIDEO_SOUND_MONO</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDEO_SOUND_STEREO</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDEO_SOUND_LANG1</CODE +> or +<CODE +CLASS="CONSTANT" +>VIDEO_SOUND_LANG2</CODE +> audio demodulation modes. When +the current audio standard is BTSC +<CODE +CLASS="CONSTANT" +>VIDEO_SOUND_LANG2</CODE +> refers to SAP and +<CODE +CLASS="CONSTANT" +>VIDEO_SOUND_LANG1</CODE +> is meaningless. Also +undocumented in the V4L specification, there is no way to query the +selected mode. On <CODE +CLASS="CONSTANT" +>VIDIOCGAUDIO</CODE +> the driver returns +the <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>actually received</I +></SPAN +> audio programmes in this +field. In the V4L2 API this information is stored in the struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> +<CODE +CLASS="STRUCTFIELD" +>rxsubchans</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>audmode</CODE +> fields, respectively. See <A +HREF="#TUNER" +>Section 1.6</A +> for more information on tuners. Related to audio +modes struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> also reports if this is a mono or stereo +input, regardless if the source is a tuner.</P +><P +>The following fields where replaced by V4L2 controls +accessible with the <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +>, <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CTRL</CODE +></A +> and +<A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +> ioctls:<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10315" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>struct +<CODE +CLASS="STRUCTNAME" +>video_audio</CODE +></TH +><TH +>V4L2 Control ID</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>volume</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_VOLUME</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>bass</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_BASS</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>treble</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_TREBLE</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="STRUCTFIELD" +>balance</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_BALANCE</CODE +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +><P +>To determine which of these controls are supported by a +driver V4L provides the <CODE +CLASS="STRUCTFIELD" +>flags</CODE +> +<CODE +CLASS="CONSTANT" +>VIDEO_AUDIO_VOLUME</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDEO_AUDIO_BASS</CODE +>, +<CODE +CLASS="CONSTANT" +>VIDEO_AUDIO_TREBLE</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDEO_AUDIO_BALANCE</CODE +>. In the V4L2 API the +<A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +> ioctl reports if the respective control is +supported. Accordingly the <CODE +CLASS="CONSTANT" +>VIDEO_AUDIO_MUTABLE</CODE +> +and <CODE +CLASS="CONSTANT" +>VIDEO_AUDIO_MUTE</CODE +> flags where replaced by the +boolean <CODE +CLASS="CONSTANT" +>V4L2_CID_AUDIO_MUTE</CODE +> control.</P +><P +>All V4L2 controls have a <CODE +CLASS="STRUCTFIELD" +>step</CODE +> +attribute replacing the struct <CODE +CLASS="STRUCTNAME" +>video_audio</CODE +> +<CODE +CLASS="STRUCTFIELD" +>step</CODE +> field. The V4L audio controls are +assumed to range from 0 to 65535 with no particular reset value. The +V4L2 API permits arbitrary limits and defaults which can be queried +with the <A +HREF="#VIDIOC-QUERYCTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCTRL</CODE +></A +> ioctl. For general information about +controls see <A +HREF="#CONTROL" +>Section 1.8</A +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10361" +>6.1.7. Frame Buffer Overlay</A +></H3 +><P +>The V4L2 ioctls equivalent to +<CODE +CLASS="CONSTANT" +>VIDIOCGFBUF</CODE +> and <CODE +CLASS="CONSTANT" +>VIDIOCSFBUF</CODE +> +are <A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FBUF</CODE +></A +> and <A +HREF="#VIDIOC-G-FBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FBUF</CODE +></A +>. The +<CODE +CLASS="STRUCTFIELD" +>base</CODE +> field of struct +<CODE +CLASS="STRUCTNAME" +>video_buffer</CODE +> remained unchanged, except V4L2 +using a flag to indicate non-destructive overlay instead of a +<CODE +CLASS="CONSTANT" +>NULL</CODE +> pointer. All other fields moved into the +struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> substructure <CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> of +struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +>. The <CODE +CLASS="STRUCTFIELD" +>depth</CODE +> field was +replaced by <CODE +CLASS="STRUCTFIELD" +>pixelformat</CODE +>. A conversion table +is available in the <A +HREF="#PIXFMT-RGB" +>Section 2.3</A +>.</P +><P +>Instead of the special ioctls +<CODE +CLASS="CONSTANT" +>VIDIOCGWIN</CODE +> and <CODE +CLASS="CONSTANT" +>VIDIOCSWIN</CODE +> +V4L2 uses the general-purpose data format negotiation ioctls +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> and <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +>. They take a pointer to a +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> as argument, here the struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +> named +<CODE +CLASS="STRUCTFIELD" +>win</CODE +> of its <CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> +union is used.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>x</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>y</CODE +>, <CODE +CLASS="STRUCTFIELD" +>width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>height</CODE +> fields of struct +<CODE +CLASS="STRUCTNAME" +>video_window</CODE +> moved into struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> +substructure <CODE +CLASS="STRUCTFIELD" +>w</CODE +> of struct +<CODE +CLASS="STRUCTNAME" +>v4l2_window</CODE +>. The +<CODE +CLASS="STRUCTFIELD" +>chromakey</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>clips</CODE +>, and +<CODE +CLASS="STRUCTFIELD" +>clipcount</CODE +> fields remained unchanged. Struct +<CODE +CLASS="STRUCTNAME" +>video_clip</CODE +> was renamed to struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +>, also +containing a struct <CODE +CLASS="STRUCTNAME" +>v4l2_rect</CODE +>, but the +semantics are still the same.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDEO_WINDOW_INTERLACE</CODE +> flag was +dropped, instead applications must set the +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> field to +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_ANY</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_INTERLACED</CODE +>. The +<CODE +CLASS="CONSTANT" +>VIDEO_WINDOW_CHROMAKEY</CODE +> flag moved into +struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +>, renamed to +<CODE +CLASS="CONSTANT" +>V4L2_FBUF_FLAG_CHROMAKEY</CODE +>.</P +><P +>In V4L, storing a bitmap pointer in +<CODE +CLASS="STRUCTFIELD" +>clips</CODE +> and setting +<CODE +CLASS="STRUCTFIELD" +>clipcount</CODE +> to +<CODE +CLASS="CONSTANT" +>VIDEO_CLIP_BITMAP</CODE +> (-1) requests bitmap +clipping, using a fixed size bitmap of 1024 × 625 bits. Struct +<CODE +CLASS="STRUCTNAME" +>v4l2_window</CODE +> has a separate +<CODE +CLASS="STRUCTFIELD" +>bitmap</CODE +> pointer field for this purpose and +the bitmap size is determined by <CODE +CLASS="STRUCTFIELD" +>w.width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>w.height</CODE +>.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOCCAPTURE</CODE +> ioctl to enable or +disable overlay was renamed to <A +HREF="#VIDIOC-OVERLAY" +><CODE +CLASS="CONSTANT" +>VIDIOC_OVERLAY</CODE +></A +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10425" +>6.1.8. Cropping</A +></H3 +><P +>To capture only a subsection of the full picture V4L +provides the <CODE +CLASS="CONSTANT" +>VIDIOCGCAPTURE</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSCAPTURE</CODE +> ioctl using struct +<CODE +CLASS="STRUCTNAME" +>video_capture</CODE +>. The equivalent V4L2 ioctls are +<A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_CROP</CODE +></A +> and <A +HREF="#VIDIOC-G-CROP" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CROP</CODE +></A +> using struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +>, and the related +<A +HREF="#VIDIOC-CROPCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +></A +> ioctl. This is a rather complex matter, see +<A +HREF="#CROP" +>Section 1.10</A +> for details.</P +><P +>The <CODE +CLASS="STRUCTFIELD" +>x</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>y</CODE +>, <CODE +CLASS="STRUCTFIELD" +>width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>height</CODE +> fields moved into struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> +substructure <CODE +CLASS="STRUCTFIELD" +>c</CODE +> of struct +<CODE +CLASS="STRUCTNAME" +>v4l2_crop</CODE +>. The +<CODE +CLASS="STRUCTFIELD" +>decimation</CODE +> field was dropped. The scaling factor is +implied by the size of the cropping rectangle and the size of the +captured or overlaid image.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDEO_CAPTURE_ODD</CODE +> +and <CODE +CLASS="CONSTANT" +>VIDEO_CAPTURE_EVEN</CODE +> flags to capture only the +odd or even field, respectively, were replaced by +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +> in the field named +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> of struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> and +struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +>. These structures are used to determine the capture or +overlay format with the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10458" +>6.1.9. Reading Images, Memory Mapping</A +></H3 +><DIV +CLASS="SECTION" +><H4 +CLASS="SECTION" +><A +NAME="AEN10460" +>6.1.9.1. Capturing using the read method</A +></H4 +><P +>There is no essential difference between reading images +from a V4L or V4L2 device using the <A +HREF="#FUNC-READ" +><CODE +CLASS="FUNCTION" +>read()</CODE +></A +> function. Supporting +this method is optional for V4L2 devices. Whether the function is +available can be determined with the <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl. All V4L2 +devices exchanging data with applications must support the +<A +HREF="#FUNC-SELECT" +><CODE +CLASS="FUNCTION" +>select()</CODE +></A +> and <A +HREF="#FUNC-POLL" +><CODE +CLASS="FUNCTION" +>poll()</CODE +></A +> function.</P +><P +>To select an image format and size, V4L provides the +<CODE +CLASS="CONSTANT" +>VIDIOCSPICT</CODE +> and <CODE +CLASS="CONSTANT" +>VIDIOCSWIN</CODE +> +ioctls. V4L2 uses the general-purpose data format negotiation ioctls +<A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +></A +> and <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +>. They take a pointer to a +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> as argument, here the struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> named +<CODE +CLASS="STRUCTFIELD" +>pix</CODE +> of its <CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> +union is used.</P +><P +>For more information about the V4L2 read interface see +<A +HREF="#RW" +>Section 3.1</A +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H4 +CLASS="SECTION" +><A +NAME="AEN10484" +>6.1.9.2. Capturing using memory mapping</A +></H4 +><P +>Applications can read from V4L devices by mapping +buffers in device memory, or more often just buffers allocated in +DMA-able system memory, into their address space. This avoids the data +copy overhead of the read method. V4L2 supports memory mapping as +well, with a few differences.</P +><DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10487" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>V4L</TH +><TH +>V4L2</TH +></TR +></THEAD +><TBODY +><TR +><TD +> </TD +><TD +>The image format must be selected before +buffers are allocated, with the <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +> ioctl. When no format +is selected the driver may use the last, possibly by another +application requested format.</TD +></TR +><TR +><TD +><P +>Applications cannot change the number of +buffers allocated. The number is built into the driver, unless it +has a module option to change the number when the driver module is +loaded.</P +></TD +><TD +><P +>The <A +HREF="#VIDIOC-REQBUFS" +><CODE +CLASS="CONSTANT" +>VIDIOC_REQBUFS</CODE +></A +> ioctl allocates the +desired number of buffers, this is a required step in the initialization +sequence.</P +></TD +></TR +><TR +><TD +><P +>Drivers map all buffers as one contiguous range + of memory. The <CODE +CLASS="CONSTANT" +>VIDIOCGMBUF</CODE +> ioctl is + available to query the number of buffers, the offset of + each buffer from the start of the virtual file, and the +overall amount of memory used, which can be used as arguments to the + <A +HREF="#FUNC-MMAP" +><CODE +CLASS="FUNCTION" +>mmap()</CODE +></A +> function.</P +></TD +><TD +><P +>Buffers are individually mapped. The offset and size of each buffer can be determined with the <A +HREF="#VIDIOC-QUERYBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYBUF</CODE +></A +> ioctl.</P +></TD +></TR +><TR +><TD +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOCMCAPTURE</CODE +> +ioctl prepares a buffer for capturing. It also determines the image +format for this buffer. The ioctl returns immediately, eventually with +an <SPAN +CLASS="ERRORCODE" +>EAGAIN</SPAN +> error code if no video signal had been detected. When the driver +supports more than one buffer applications can call the ioctl multiple +times and thus have multiple outstanding capture +requests.</P +><P +>The <CODE +CLASS="CONSTANT" +>VIDIOCSYNC</CODE +> ioctl +suspends execution until a particular buffer has been +filled.</P +></TD +><TD +><P +>Drivers maintain an incoming and outgoing +queue. <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> enqueues any empty buffer into the incoming +queue. Filled buffers are dequeued from the outgoing queue with the +<A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl. To wait until filled buffers become available this +function, <A +HREF="#FUNC-SELECT" +><CODE +CLASS="FUNCTION" +>select()</CODE +></A +> or <A +HREF="#FUNC-POLL" +><CODE +CLASS="FUNCTION" +>poll()</CODE +></A +> can be used. The +<A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMON</CODE +></A +> ioctl must be called once after enqueuing one or +more buffers to start capturing. Its counterpart +<A +HREF="#VIDIOC-STREAMON" +><CODE +CLASS="CONSTANT" +>VIDIOC_STREAMOFF</CODE +></A +> stops capturing and dequeues all buffers from both +queues. Applications can query the signal status, if known, with the +<A +HREF="#VIDIOC-ENUMINPUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMINPUT</CODE +></A +> ioctl.</P +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +><P +>For a more in-depth discussion of memory mapping and +examples, see <A +HREF="#MMAP" +>Section 3.2</A +>.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10541" +>6.1.10. Reading Raw VBI Data</A +></H3 +><P +>Originally the V4L API did not specify a raw VBI capture +interface, merely the device file <TT +CLASS="FILENAME" +>/dev/vbi</TT +> was +reserved for this purpose. The only driver supporting this interface +was the BTTV driver, de-facto defining the V4L VBI interface. Reading +from the device yields a raw VBI image with the following +parameters:<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10545" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +></TH +><TH +>V4L, BTTV driver</TH +></TR +></THEAD +><TBODY +><TR +><TD +>sampling_rate</TD +><TD +>28636363 Hz NTSC (precisely all 525-line +standards); 35468950 Hz PAL and SECAM (625-line)</TD +></TR +><TR +><TD +>offset</TD +><TD +>?</TD +></TR +><TR +><TD +>samples_per_line</TD +><TD +>2048</TD +></TR +><TR +><TD +>sample_format</TD +><TD +>V4L2_PIX_FMT_GREY. The last four bytes +(machine endianess integer) contain a frame counter.</TD +></TR +><TR +><TD +>start[]</TD +><TD +>10, 273 NTSC; 22, 335 PAL and SECAM</TD +></TR +><TR +><TD +>count[]</TD +><TD +><P +>16, 16<SUP +>a</SUP +></P +></TD +></TR +><TR +><TD +>flags</TD +><TD +>0</TD +></TR +></TBODY +><TR +><TD +COLSPAN="2" +>Notes:<BR><A +NAME="FTN.AEN10572" +>a. </A +>Old driver +versions used different values, eventually the custom +<CODE +CLASS="CONSTANT" +>BTTV_VBISIZE</CODE +> ioctl was added to query the +correct values.<BR></TD +></TR +></TABLE +><P +></P +></DIV +></P +><P +>Undocumented in the V4L specification, in Linux 2.3 the +<CODE +CLASS="CONSTANT" +>VIDIOCGVBIFMT</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSVBIFMT</CODE +> ioctls using struct +<CODE +CLASS="STRUCTNAME" +>vbi_format</CODE +> were added to determine the VBI +image parameters. These ioctls are only partially compatible with the +V4L2 VBI interface specified in <A +HREF="#RAW-VBI" +>Section 4.6</A +>.</P +><P +>An <CODE +CLASS="STRUCTFIELD" +>offset</CODE +> field does not +exist, <CODE +CLASS="STRUCTFIELD" +>sample_format</CODE +> is supposed to be +<CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RAW</CODE +>, here equivalent to +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +>. The remaining fields are +probably equivalent to struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +>.</P +><P +>Apparently only the Zoran (ZR 36120) driver implements +these ioctls. The semantics differ from those specified for V4L2 in two +ways. The parameters are reset on <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> and +<CODE +CLASS="CONSTANT" +>VIDIOCSVBIFMT</CODE +> always returns the <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code if the +parameters are invalid.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10594" +>6.1.11. Miscellaneous</A +></H3 +><P +>V4L2 has no equivalent of the +<CODE +CLASS="CONSTANT" +>VIDIOCGUNIT</CODE +> ioctl. Applications can find the VBI +device associated with a video capture device (or vice versa) by +reopening the device and requesting VBI data. For details see +<A +HREF="#OPEN" +>Section 1.1</A +>.</P +><P +>Presently no replacement exists for + <CODE +CLASS="CONSTANT" +>VIDIOCKEY</CODE +>, the V4L functions +regarding MPEG compression and decompression, and microcode +programming. Drivers may implement the respective V4L ioctls for +these purposes.</P +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="HIST-V4L2" +>6.2. History of the V4L2 API</A +></H2 +><P +>Soon after the V4L API was added to the kernel it was +criticised as too inflexible. In August 1998 Bill Dirks proposed a +number of improvements and began work on documentation, example +drivers and applications. With the help of other volunteers this +eventually became the V4L2 API, not just an extension but a +replacement for the V4L API. However it took another four years and +two stable kernel releases until the new API was finally accepted for +inclusion into the kernel in its present form.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10604" +>6.2.1. Early Versions</A +></H3 +><P +>1998-08-20: First version.</P +><P +>1998-08-27: select() function was introduced.</P +><P +>1998-09-10: New video standard interface.</P +><P +>1998-09-18: The VIDIOC_NONCAP ioctl was replaced by the O_TRUNC open() +flag (with synonym O_NONCAP/O_NOIO) to indicate a non-capturing open. The +VIDEO_STD_XXX identifiers are now ordinals rather than bits, and +video_std_construct helper function takes id and transmission as +arguments.</P +><P +>1998-09-28: Revamped video standard. Made video controls individually +enumerable.</P +><P +>1998-10-02: Removed id from video_standard, renamed color subcarrier +fields. Renamed VIDIOC_QUERYSTD to VIDIOC_ENUMSTD and VIDIOC_G_INPUT +to VIDIOC_ENUMINPUT. Added preliminary /proc/videodev file. First +draft of CODEC driver API spec.</P +><P +>1998-11-08: Updating for many minor changes to the V4L2 spec. Most +symbols have been renamed. Some material changes to +v4l2_capability.</P +><P +>1998-11-12 bugfix: some of the VIDIOC_* symbols were not constructed +with the right macros, which could lead to errors on what should have +been valid ioctl() calls.</P +><P +>1998-11-14: V4L2_PIX_FMT_RGB24 changed to V4L2_PIX_FMT_BGR24. Same for +RGB32. Audio UI controls moved to VIDIOC_S_CTRL system and assigned +V4L2_CID_AUDIO_* symbols. Removed V4L2_MAJOR from videodev.h since it +is only used at one place in videodev. Added YUV422 and YUV411 planar +formats.</P +><P +>1998-11-28: Changed a few ioctl symbols. Added stuff for codec and +video output devices.</P +><P +>1999-01-14: Added raw VBI interface.</P +><P +>1999-01-19: Removed VIDIOC_NEXTBUF ioctl.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10618" +>6.2.2. V4L2 Version 0.16 1999-01-31</A +></H3 +><P +>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF +are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added +digital zoom (cropping) controls.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10621" +>6.2.3. V4L2 Version 0.18 1999-03-16</A +></H3 +><P +>Added a v4l to V4L2 ioctl compatibility layer to +videodev.c. Driver writers, this changes how you implement your ioctl +handler. See the Driver Writer's Guide. Added some more control id +codes.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10624" +>6.2.4. V4L2 Version 0.19 1999-06-05</A +></H3 +><P +>1999-03-18: Fill in the category and catname fields of +v4l2_queryctrl objects before passing them to the driver. Required a +minor change to the VIDIOC_QUERYCTRL handlers in the sample +drivers.</P +><P +>1999-03-31: Better compatibility for v4l memory capture +ioctls. Requires changes to drivers to fully support new compatibility +features, see Driver Writer's Guide and v4l2cap.c. Added new control +IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, +and _YUV411P to _YUV411P.</P +><P +>1999-04-04: Added a few more control IDs.</P +><P +>1999-04-07: Added the button control type.</P +><P +>1999-05-02: Fixed a typo in videodev.h, and added the +V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</P +><P +>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing +a malfunction of this ioctl.</P +><P +>1999-06-05: Changed the value of +V4L2_CID_WHITENESS.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10633" +>6.2.5. V4L2 Version 0.20 1999-09-10</A +></H3 +><P +>Version 0.20 introduced a number of changes not backward +compatible with 0.19 and earlier. The purpose was to simplify the API, +while at the same time make it more extensible, and follow common +Linux driver API conventions.</P +><P +></P +><OL +TYPE="1" +><LI +><P +>Fixed typos in some V4L2_FMT_FLAG symbols. Changed +struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> to be compatible with v4l. (1999-08-30)</P +></LI +><LI +><P +>Added V4L2_TUNER_SUB_LANG1. (1999-09-05)</P +></LI +><LI +><P +>All ioctl() commands that took an integer argument +before, will now take a pointer to an integer. Where it makes sense, +the driver will return the actual value used in the integer pointed to +by the argument. This is a common convention, and also makes certain +things easier in libv4l2 and other system code when the parameter to +ioctl() is always a pointer. The ioctl commands affected are: +VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, +VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example, where +before you might have had code like: <PRE +CLASS="PROGRAMLISTING" +>err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);</PRE +> that becomes <PRE +CLASS="PROGRAMLISTING" +>int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);</PRE +> + </P +></LI +><LI +><P +>All the different set-format ioctl() commands are +swept into a single set-format command whose parameter consists of an +integer value indicating the type of format, followed by the format +data. The same for the get-format commands, of course. This will +simplify the API by eliminating several ioctl codes and also make it +possible to add additional kinds of data streams, or driver-private +kinds of streams without having to add more set-format ioctls. The +parameter to VIDIOC_S_FMT is as follows. The first field is a +V4L2_BUF_TYPE_XXX value that indicates which stream the set-format is +for, and implicitly, what type of format data. After that is a union +of the different format structures. More can be added later without +breaking backward compatibility. Nonstandard driver-private formats +can be used by casting raw_data.</P +><P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> { + __u32 type; + union { + struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> pix; + struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> vbi; + ... and so on ... + __u8 raw_data[200]; + } fmt; +}; + </PRE +></P +><P +>For a get-format, the application fills in the type +field, and the driver fills in the rest. What was before the image +format structure, struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +>, becomes struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +>. These +ioctls become obsolete: VIDIOC_S_INFMT, VIDIOC_G_INFMT, +VIDIOC_S_OUTFMT, VIDIOC_G_OUTFMT, VIDIOC_S_VBIFMT +VIDIOC_G_VBIFMT.</P +></LI +><LI +><P +>Similar to item 2, VIDIOC_G/S_PARM and +VIDIOC_G/S_OUTPARM are merged, along with the corresponding 'get' +functions. A type field will indicate which stream the parameters are +for, set to a V4L2_BUF_TYPE_* value.</P +><P +><PRE +CLASS="PROGRAMLISTING" +>struct <A +HREF="#V4L2-STREAMPARM" +>v4l2_streamparm</A +> { + __u32 type; + union { + struct <A +HREF="#V4L2-CAPTUREPARM" +>v4l2_captureparm</A +> capture; + struct <A +HREF="#V4L2-OUTPUTPARM" +>v4l2_outputparm</A +> output; + __u8 raw_data[200]; + } parm; +}; + </PRE +></P +><P +>These ioctls become obsolete: VIDIOC_G_OUTPARM, +VIDIOC_S_OUTPARM.</P +></LI +><LI +><P +>The way controls are enumerated is simplified. +Simultaneously, two new control flags are introduced and the existing +flag is dropped. Also, the catname field is dropped in favor of a +group name. To enumerate controls call VIDIOC_QUERYCTRL with +successive id's starting from V4L2_CID_BASE or V4L2_CID_PRIVATE_BASE +and stop when the driver returns the EINVAL error code. Controls that +are not supported on the hardware are marked with the +V4L2_CTRL_FLAG_DISABLED flag.</P +><P +>Additionally, controls that are temporarily +unavailable, or that can only be controlled from another file +descriptor are marked with the V4L2_CTRL_FLAG_GRABBED flag. Usually, a +control that is GRABBED, but not DISABLED can be read, but changed. +The group name indicates a possibly narrower classification than the +category. In other words, there may be multiple groups within a +category. Controls within a group would typically be drawn within a +group box. Controls in different categories might have a greater +separation, or even be in separate windows.</P +></LI +><LI +><P +>The v4l2_buffer timestamp field is changed to a 64-bit +integer, and holds the time of the frame based on the system time, in +1 nanosecond units. Additionally, timestamps will be in absolute +system time, not starting from zero at the beginning of a stream as it +is now. The data type name for timestamps is stamp_t, defined as a +signed 64-bit integer. Output devices should not send a buffer out +until the time in the timestamp field has arrived. I would like to +follow SGI's lead, and adopt a multimedia timestamping system like +their UST (Unadjusted System Time). See +http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is +no longer valid.] UST uses timestamps that are 64-bit signed integers +(not struct timeval's) and given in nanosecond units. The UST clock +starts at zero when the system is booted and runs continuously and +uniformly. It takes a little over 292 years for UST to overflow. There +is no way to set the UST clock. The regular Linux time-of-day clock +can be changed periodically, which would cause errors if it were being +used for timestamping a multimedia stream. A real UST style clock will +require some support in the kernel that is not there yet. But in +anticipation, I will change the timestamp field to a 64-bit integer, +and I will change the v4l2_masterclock_gettime() function (used only +by drivers) to return a 64-bit integer.</P +></LI +><LI +><P +>The sequence field is added to the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +>. The +sequence field indicates which frame this is in the sequence-- 0, 1, +2, 3, 4, etc. Set by capturing devices. Ignored by output devices. If +a capture driver drops a frame, the sequence number of that frame is +skipped. A break in the sequence will indicate to the application +which frame was dropped.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10672" +>6.2.6. V4L2 Version 0.20 incremental changes</A +></H3 +><P +>1999-12-23: In struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> field +<CODE +CLASS="STRUCTFIELD" +>reserved1</CODE +> became <CODE +CLASS="STRUCTFIELD" +>offset</CODE +>. +Previously <CODE +CLASS="STRUCTFIELD" +>reserved1</CODE +> was required to always read +zero.</P +><P +>2000-01-13: Added V4L2_FMT_FLAG_NOT_INTERLACED.</P +><P +>2000-07-31: Included linux/poll.h in videodev.h for compatibility with +the original videodev.h.</P +><P +>2000-11-20: Added V4L2_TYPE_VBI_OUTPUT. Added V4L2_PIX_FMT_Y41P.</P +><P +>2000-11-25: Added V4L2_TYPE_VBI_INPUT.</P +><P +>2000-12-04: Fixed a couple typos in symbol names.</P +><P +>2001-01-18: Fixed a namespace conflict (the fourcc macro changed to +v4l2_fourcc).</P +><P +>2001-01-25: Fixed a possible driver-level compatibility problem +between the original 2.4.0 videodev.h and the videodev.h that comes +with videodevX. If you were using an earlier version of videodevX on +2.4.0, then you should recompile your v4l and V4L2 drivers to be +safe.</P +><P +>2001-01-26: videodevX: Fixed a possible kernel-level incompatibility +between the videodevX videodev.h and the 2.2.x videodev.h that had the +devfs patches applied. videodev: Changed fourcc to v4l2_fourcc to +avoid namespace pollution. Some other cleanup.</P +><P +>2001-03-02: Certain v4l ioctls that really pass data both ways, but +whose types are read-only, did not work correctly through the backward +compatibility layer. [Solution?]</P +><P +>2001-04-13: Added big endian 16-bit RGB formats.</P +><P +>2001-09-17: Added new YUV formats. Added VIDIOC_G_FREQUENCY and +VIDIOC_S_FREQUENCY. (The VIDIOC_G/S_FREQ ioctls did not take multiple +tuners into account.)</P +><P +>2000-09-18: Added V4L2_BUF_TYPE_VBI. Raw VBI VIDIOC_G_FMT and +VIDIOC_S_FMT may fail if field <CODE +CLASS="STRUCTFIELD" +>type</CODE +> is not +V4L2_BUF_TYPE_VBI. Changed the ambiguous phrase "rising edge" to "leading +edge" in the definition of struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> field +<CODE +CLASS="STRUCTFIELD" +>offset</CODE +>.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10694" +>6.2.7. V4L2 Version 0.20 2000-11-23</A +></H3 +><P +>A number of changes were made to the raw VBI +interface.</P +><P +></P +><OL +TYPE="1" +><LI +><P +>Added figures clarifying the line numbering scheme. +The description of <CODE +CLASS="STRUCTFIELD" +>start</CODE +>[0] and +<CODE +CLASS="STRUCTFIELD" +>start</CODE +>[1] as base 0 offset has been dropped. +Rationale: a) The previous definition was unclear. b) The +<CODE +CLASS="STRUCTFIELD" +>start</CODE +>[] values are not an offset into anything, +as a means of identifying scanning lines it can only be +counterproductive to deviate from common numbering conventions. +Compatibility: Add one to the start values. Applications depending on +the previous semantics of start values may not function +correctly.</P +></LI +><LI +><P +>The restriction "count[0] > 0 and count[1] > 0" has +been relaxed to "(count[0] + count[1]) > 0". Rationale: Drivers +allocating resources at scanning line granularity and first field only +data services. The comment that both 'count' values will usually be +equal is misleading and pointless and has been removed. Compatibility: +Drivers may return EINVAL, applications depending on the previous +restriction may not function correctly.</P +></LI +><LI +><P +>Restored description of the driver option to return +negative start values. Existed in the initial revision of this +document, not traceable why it disappeared in later versions. +Compatibility: Applications depending on the returned start values +being positive may not function correctly. Clarification on the use of +EBUSY and EINVAL in VIDIOC_S_FMT ioctl. Added EBUSY paragraph to +section. Added description of reserved2, previously mentioned only in +videodev.h.</P +></LI +><LI +><P +>Added V4L2_TYPE_VBI_INPUT and V4L2_TYPE_VBI_OUTPUT +here and in videodev.h. The first is an alias for the older +V4L2_TYPE_VBI, the latter was missing in videodev.h.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10709" +>6.2.8. V4L2 Version 0.20 2002-07-25</A +></H3 +><P +>Added sliced VBI interface proposal.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN10712" +>6.2.9. V4L2 in Linux 2.5.46, 2002-10</A +></H3 +><P +>Around October-November 2002, prior to an announced +feature freeze of Linux 2.5, the API was revised, drawing from +experience with V4L2 0.20. This unnamed version was finally merged +into Linux 2.5.46.</P +><P +></P +><OL +TYPE="1" +><LI +><P +>As specified in <A +HREF="#RELATED" +>Section 1.1.2</A +> drivers +must make related device functions available under all minor device +numbers.</P +></LI +><LI +><P +>The <A +HREF="#FUNC-OPEN" +><CODE +CLASS="FUNCTION" +>open()</CODE +></A +> function requires access mode +<CODE +CLASS="CONSTANT" +>O_RDWR</CODE +> regardless of device type. All V4L2 +drivers exchanging data with applications must support the +<CODE +CLASS="CONSTANT" +>O_NONBLOCK</CODE +> flag. The <CODE +CLASS="CONSTANT" +>O_NOIO</CODE +> +flag (alias of meaningless <CODE +CLASS="CONSTANT" +>O_TRUNC</CODE +>) to indicate +accesses without data exchange (panel applications) was +dropped. Drivers must assume panel mode until the application attempts +to initiate data exchange, see <A +HREF="#OPEN" +>Section 1.1</A +>.</P +></LI +><LI +><P +>The struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> changed dramatically. Note that +also the size of the structure changed, which is encoded in the ioctl +request code, thus older V4L2 devices will respond with an <SPAN +CLASS="ERRORCODE" +>EINVAL</SPAN +> error code to +the new <A +HREF="#VIDIOC-QUERYCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYCAP</CODE +></A +> ioctl.</P +><P +>There are new fields to identify the driver, a new (as +of yet unspecified) device function +<CODE +CLASS="CONSTANT" +>V4L2_CAP_RDS_CAPTURE</CODE +>, the +<CODE +CLASS="CONSTANT" +>V4L2_CAP_AUDIO</CODE +> flag indicates if the device has +any audio connectors, another I/O capability +<CODE +CLASS="CONSTANT" +>V4L2_CAP_ASYNCIO</CODE +> can be flagged. Field +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> became a set in response to the change +above and was merged with <CODE +CLASS="STRUCTFIELD" +>flags</CODE +>. +<CODE +CLASS="CONSTANT" +>V4L2_FLAG_TUNER</CODE +> was renamed to +<CODE +CLASS="CONSTANT" +>V4L2_CAP_TUNER</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_CAP_VIDEO_OVERLAY</CODE +> replaced +<CODE +CLASS="CONSTANT" +>V4L2_FLAG_PREVIEW</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_CAPTURE</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_CAP_VBI_OUTPUT</CODE +> replaced +<CODE +CLASS="CONSTANT" +>V4L2_FLAG_DATA_SERVICE</CODE +>. +<CODE +CLASS="CONSTANT" +>V4L2_FLAG_READ</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_FLAG_WRITE</CODE +> merged to +<CODE +CLASS="CONSTANT" +>V4L2_CAP_READWRITE</CODE +>.</P +><P +>Redundant fields +<CODE +CLASS="STRUCTFIELD" +>inputs</CODE +>, <CODE +CLASS="STRUCTFIELD" +>outputs</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>audios</CODE +> were removed, these can be +determined as described in <A +HREF="#VIDEO" +>Section 1.4</A +> and <A +HREF="#AUDIO" +>Section 1.5</A +>.</P +><P +>The somewhat volatile and therefore +barely useful fields <CODE +CLASS="STRUCTFIELD" +>maxwidth</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>maxheight</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>minwidth</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>minheight</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>maxframerate</CODE +> were removed, this information +is available as described in <A +HREF="#FORMAT" +>Section 1.9</A +> and +<A +HREF="#STANDARD" +>Section 1.7</A +>.</P +><P +><CODE +CLASS="CONSTANT" +>V4L2_FLAG_SELECT</CODE +> +was removed, this function is considered important enough that all +V4L2 drivers exchanging data with applications must support +<CODE +CLASS="FUNCTION" +>select()</CODE +>. The redundant flag +<CODE +CLASS="CONSTANT" +>V4L2_FLAG_MONOCHROME</CODE +> was removed, this +information is available as described in <A +HREF="#FORMAT" +>Section 1.9</A +>.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> the + <CODE +CLASS="STRUCTFIELD" +>assoc_audio</CODE +> field and the +<CODE +CLASS="STRUCTFIELD" +>capability</CODE +> field and its only + flag <CODE +CLASS="CONSTANT" +>V4L2_INPUT_CAP_AUDIO</CODE +> was replaced + by the new <CODE +CLASS="STRUCTFIELD" +>audioset</CODE +> + field. Instead of linking one video input to one audio input + this field reports all audio inputs this video input + combines with.</P +><P +>New fields are <CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> +(reversing the former link from tuners to video inputs), +<CODE +CLASS="STRUCTFIELD" +>std</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>status</CODE +>.</P +><P +>Accordingly struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> lost its + <CODE +CLASS="STRUCTFIELD" +>capability</CODE +> and + <CODE +CLASS="STRUCTFIELD" +>assoc_audio</CODE +> fields, + <CODE +CLASS="STRUCTFIELD" +>audioset</CODE +>, + <CODE +CLASS="STRUCTFIELD" +>modulator</CODE +> and + <CODE +CLASS="STRUCTFIELD" +>std</CODE +> where added.</P +></LI +><LI +><P +>The struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> field +<CODE +CLASS="STRUCTFIELD" +>audio</CODE +> was renamed to +<CODE +CLASS="STRUCTFIELD" +>index</CODE +>, consistent with other structures. +Capability flag <CODE +CLASS="CONSTANT" +>V4L2_AUDCAP_STEREO</CODE +> was added to +indicated if this is a stereo input. +<CODE +CLASS="CONSTANT" +>V4L2_AUDCAP_EFFECTS</CODE +> and the corresponding +<CODE +CLASS="CONSTANT" +>V4L2_AUDMODE</CODE +> flags where removed, this can be +easily implemented using controls. (However the same applies to AVL +which is still there.)</P +><P +>The struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +> field +<CODE +CLASS="STRUCTFIELD" +>audio</CODE +> was renamed to +<CODE +CLASS="STRUCTFIELD" +>index</CODE +>.</P +></LI +><LI +><P +>The struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> +<CODE +CLASS="STRUCTFIELD" +>input</CODE +> field was replaced by an +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field, permitting devices with +multiple tuners. The link between video inputs and tuners is now +reversed, inputs point to the tuner they are on. The +<CODE +CLASS="STRUCTFIELD" +>std</CODE +> substructure became a +simple set (more about this below) and moved into struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +>. A +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field was added.</P +><P +>Accordingly in struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> the +<CODE +CLASS="STRUCTFIELD" +>output</CODE +> was replaced by an +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field.</P +><P +>In struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +> the +<CODE +CLASS="STRUCTFIELD" +>port</CODE +> field was replaced by a +<CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> field containing the respective tuner +or modulator index number. A tuner <CODE +CLASS="STRUCTFIELD" +>type</CODE +> +field was added and the <CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> field +became larger for future extensions (satellite tuners in +particular).</P +></LI +><LI +><P +>The idea of completely transparent video standards was +dropped. Experience showed that applications must be able to work with +video standards beyond presenting the user a menu. To this end V4L2 +returned to defined standards as <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +>, replacing references +to standards throughout the API. For details see <A +HREF="#STANDARD" +>Section 1.7</A +>. <A +HREF="#VIDIOC-G-STD" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +></A +> and <A +HREF="#VIDIOC-G-STD" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +></A +> +now take a pointer to this type as argument. <A +HREF="#VIDIOC-QUERYSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_QUERYSTD</CODE +></A +> was +added to autodetect the received standard. In struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> an +<CODE +CLASS="STRUCTFIELD" +>index</CODE +> field was added for <A +HREF="#VIDIOC-ENUMSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +></A +>. +A <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> field named <CODE +CLASS="STRUCTFIELD" +>id</CODE +> was added as +machine readable identifier, also replacing the +<CODE +CLASS="STRUCTFIELD" +>transmission</CODE +> field. +<CODE +CLASS="STRUCTFIELD" +>framerate</CODE +>, which is misleading, was renamed +to <CODE +CLASS="STRUCTFIELD" +>frameperiod</CODE +>. The now obsolete +<CODE +CLASS="STRUCTFIELD" +>colorstandard</CODE +> information, originally +needed to distguish between variations of standards, were +removed.</P +><P +>Struct <CODE +CLASS="STRUCTNAME" +>v4l2_enumstd</CODE +> ceased to +be. <A +HREF="#VIDIOC-ENUMSTD" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMSTD</CODE +></A +> now takes a pointer to a struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> +directly. The information which standards are supported by a +particular video input or output moved into struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> and +struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> fields named <CODE +CLASS="STRUCTFIELD" +>std</CODE +>, +respectively.</P +></LI +><LI +><P +>The struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> fields +<CODE +CLASS="STRUCTFIELD" +>category</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>group</CODE +> did not catch on and/or were not +implemented as expected and therefore removed.</P +></LI +><LI +><P +>The <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +></A +> ioctl was added to negotiate data +formats as with <A +HREF="#VIDIOC-G-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +></A +>, but without the overhead of +programming the hardware and regardless of I/O in progress.</P +><P +>In struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> the <CODE +CLASS="STRUCTFIELD" +>fmt</CODE +> + union was extended to contain struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +>. As a result + all data format negotiation is now possible with + <CODE +CLASS="CONSTANT" +>VIDIOC_G_FMT</CODE +>, + <CODE +CLASS="CONSTANT" +>VIDIOC_S_FMT</CODE +> and + <CODE +CLASS="CONSTANT" +>VIDIOC_TRY_FMT</CODE +>; the + <CODE +CLASS="CONSTANT" +>VIDIOC_G_WIN</CODE +>, + <CODE +CLASS="CONSTANT" +>VIDIOC_S_WIN</CODE +> and ioctl to prepare for + overlay were removed. The <CODE +CLASS="STRUCTFIELD" +>type</CODE +> + field changed to type enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> and the buffer type + names changed as follows.<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10867" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>Old defines</TH +><TH +>enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +></TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_CAPTURE</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_CODECIN</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>Preliminary omitted</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_CODECOUT</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>Preliminary omitted</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_EFFECTSIN</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>Preliminary omitted</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_EFFECTSIN2</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>Preliminary omitted</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_EFFECTSOUT</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>Preliminary omitted</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEOOUT</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_CAPTURE</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VBI_OUTPUT</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE_BASE</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_PRIVATE</CODE +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-FMTDESC" +>v4l2_fmtdesc</A +> a enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> field named +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> was added as in struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +>. As a +result the <CODE +CLASS="CONSTANT" +>VIDIOC_ENUM_FBUFFMT</CODE +> ioctl is no longer +needed and was removed. These calls can be replaced by +<A +HREF="#VIDIOC-ENUM-FMT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUM_FMT</CODE +></A +> with type +<CODE +CLASS="CONSTANT" +>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE +>.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> the +<CODE +CLASS="STRUCTFIELD" +>depth</CODE +> was removed, assuming applications +recognizing the format are aware of the image depth and others need +not know. The same rationale lead to the removal of the +<CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_COMPRESSED</CODE +> flag. The +<CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_SWCONVECOMPRESSED</CODE +> flag was removed +because drivers are not supposed to convert image formats in kernel +space. The <CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_BYTESPERLINE</CODE +> flag was +redundant, applications can set the +<CODE +CLASS="STRUCTFIELD" +>bytesperline</CODE +> field to zero to get a +reasonable default. Since also the remaining flags were replaced, the +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field itself was removed.</P +><P +>The interlace flags were replaced by a enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +> +value in a newly added <CODE +CLASS="STRUCTFIELD" +>field</CODE +> field.<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN10952" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>Old flag</TH +><TH +>enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +></TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_NOT_INTERLACED</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>?</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_INTERLACED</CODE +> += <CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_COMBINED</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_INTERLACED</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_TOPFIELD</CODE +> += <CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_ODDFIELD</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_TOP</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_BOTFIELD</CODE +> += <CODE +CLASS="CONSTANT" +>V4L2_FMT_FLAG_EVENFIELD</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_BOTTOM</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_SEQ_TB</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_SEQ_BT</CODE +></TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>-</CODE +></TD +><TD +><CODE +CLASS="CONSTANT" +>V4L2_FIELD_ALTERNATE</CODE +></TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +></P +><P +>The color space flags were replaced by a +enum <A +HREF="#V4L2-COLORSPACE" +>v4l2_colorspace</A +> value in a newly added +<CODE +CLASS="STRUCTFIELD" +>colorspace</CODE +> field, where one of +<CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_SMPTE170M</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_BT878</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_470_SYSTEM_M</CODE +> or +<CODE +CLASS="CONSTANT" +>V4L2_COLORSPACE_470_SYSTEM_BG</CODE +> replaces +<CODE +CLASS="CONSTANT" +>V4L2_FMT_CS_601YUV</CODE +>.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> the +<CODE +CLASS="STRUCTFIELD" +>type</CODE +> field was properly typed as +enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +>. Buffer types changed as mentioned above. A new +<CODE +CLASS="STRUCTFIELD" +>memory</CODE +> field of type enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +> was +added to distinguish between mapping methods using buffers allocated +by the driver or the application. See <A +HREF="#IO" +>Chapter 3</A +> for +details.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> the <CODE +CLASS="STRUCTFIELD" +>type</CODE +> +field was properly typed as enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +>. Buffer types changed as +mentioned above. A <CODE +CLASS="STRUCTFIELD" +>field</CODE +> field of type +enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +> was added to indicate if a buffer contains a top or +bottom field, the field flags were removed. Realizing the efforts to +introduce an unadjusted system time clock failed, the +<CODE +CLASS="STRUCTFIELD" +>timestamp</CODE +> field changed back from type +stamp_t, an unsigned 64 bit integer expressing time in nanoseconds, to +struct <CODE +CLASS="STRUCTNAME" +>timeval</CODE +>. With the addition of a second +memory mapping method the <CODE +CLASS="STRUCTFIELD" +>offset</CODE +> field +moved into union <CODE +CLASS="STRUCTFIELD" +>m</CODE +>, and a new +<CODE +CLASS="STRUCTFIELD" +>memory</CODE +> field of type enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +> was +added to distinguish between mapping methods. See <A +HREF="#IO" +>Chapter 3</A +> +for details.</P +><P +>The <CODE +CLASS="CONSTANT" +>V4L2_BUF_REQ_CONTIG</CODE +> +flag was used by the V4L compatibility layer, after changes to this +code it was no longer needed. The +<CODE +CLASS="CONSTANT" +>V4L2_BUF_ATTR_DEVICEMEM</CODE +> flag would indicate if +the buffer was indeed allocated in device memory rather than DMA-able +system memory. It was barely useful and so has been removed.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +> the +<CODE +CLASS="STRUCTFIELD" +>base[3]</CODE +> array anticipating double- and +triple-buffering in off-screen video memory, however without defining + a synchronization mechanism, was replaced by a single + pointer. The <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_SCALEUP</CODE +> and + <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_SCALEDOWN</CODE +> flags were + removed. Applications can determine this capability more + accurately using the new cropping and scaling interface. The + <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_CLIPPING</CODE +> flag was + replaced by <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_LIST_CLIPPING</CODE +> + and <CODE +CLASS="CONSTANT" +>V4L2_FBUF_CAP_BITMAP_CLIPPING</CODE +>.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> the <CODE +CLASS="STRUCTFIELD" +>x</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>y</CODE +>, <CODE +CLASS="STRUCTFIELD" +>width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>height</CODE +> field moved into a +<CODE +CLASS="STRUCTFIELD" +>c</CODE +> substructure of type struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +>. The +<CODE +CLASS="STRUCTFIELD" +>x</CODE +> and <CODE +CLASS="STRUCTFIELD" +>y</CODE +> field +were renamed to <CODE +CLASS="STRUCTFIELD" +>left</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>top</CODE +>, i. e. offsets to a context dependent +origin.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +> the <CODE +CLASS="STRUCTFIELD" +>x</CODE +>, +<CODE +CLASS="STRUCTFIELD" +>y</CODE +>, <CODE +CLASS="STRUCTFIELD" +>width</CODE +> and +<CODE +CLASS="STRUCTFIELD" +>height</CODE +> field moved into a +<CODE +CLASS="STRUCTFIELD" +>w</CODE +> substructure as above. A +<CODE +CLASS="STRUCTFIELD" +>field</CODE +> field of type %v4l2-field; was added +to distinguish between field and frame (interlaced) overlay.</P +></LI +><LI +><P +>The digital zoom interface, including struct +<CODE +CLASS="STRUCTNAME" +>v4l2_zoomcap</CODE +>, struct +<CODE +CLASS="STRUCTNAME" +>v4l2_zoom</CODE +>, +<CODE +CLASS="CONSTANT" +>V4L2_ZOOM_NONCAP</CODE +> and +<CODE +CLASS="CONSTANT" +>V4L2_ZOOM_WHILESTREAMING</CODE +> was replaced by a new +cropping and scaling interface. The previously unused struct +<CODE +CLASS="STRUCTNAME" +>v4l2_cropcap</CODE +> and +<CODE +CLASS="STRUCTNAME" +>v4l2_crop</CODE +> where redefined for this purpose. +See <A +HREF="#CROP" +>Section 1.10</A +> for details.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> the +<CODE +CLASS="STRUCTFIELD" +>SAMPLE_FORMAT</CODE +> field now contains a +four-character-code as used to identify video image formats. +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_GREY</CODE +> replaces the +<CODE +CLASS="CONSTANT" +>V4L2_VBI_SF_UBYTE</CODE +> define. The +<CODE +CLASS="STRUCTFIELD" +>reserved</CODE +> field was extended.</P +></LI +><LI +><P +>In struct <A +HREF="#V4L2-CAPTUREPARM" +>v4l2_captureparm</A +> the type of the +<CODE +CLASS="STRUCTFIELD" +>timeperframe</CODE +> field changed from unsigned +long to struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +>. A new field +<CODE +CLASS="STRUCTFIELD" +>readbuffers</CODE +> was added to control the driver +behaviour in read I/O mode.</P +><P +>According changes were made to +struct <A +HREF="#V4L2-OUTPUTPARM" +>v4l2_outputparm</A +>.</P +></LI +><LI +><P +>The struct <CODE +CLASS="STRUCTNAME" +>v4l2_performance</CODE +> +and <CODE +CLASS="CONSTANT" +>VIDIOC_G_PERF</CODE +> ioctl were dropped. Except when +using the <A +HREF="#RW" +>read/write I/O method</A +>, which is +limited anyway, this information is already available to the +application.</P +></LI +><LI +><P +>The example transformation from RGB to YCbCr color +space in the old V4L2 documentation was inaccurate, this has been +corrected in <A +HREF="#PIXFMT" +>Chapter 2</A +>.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11094" +>6.2.10. V4L2 2003-06-19</A +></H3 +><P +></P +><OL +TYPE="1" +><LI +><P +>A new capability flag +<CODE +CLASS="CONSTANT" +>V4L2_CAP_RADIO</CODE +> was added for radio devices. Prior +to this change radio devices would identify soley by having exactly one +tuner whose type field reads <CODE +CLASS="CONSTANT" +>V4L2_TUNER_RADIO</CODE +>.</P +></LI +><LI +><P +>An optional priority mechanism was added, see <A +HREF="#APP-PRI" +>Section 1.3</A +> for details.</P +></LI +><LI +><P +>The audio input and output interface was found to be +incomplete.</P +><P +>Previously the <CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +> +ioctl would enumerate the available audio inputs. An ioctl to +determine the current audio input, if more than one combines with the +current video input, did not exist. So +<CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +> was renamed to +<CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO_OLD</CODE +>, this ioctl will be removed in +the future. The <A +HREF="#VIDIOC-ENUMAUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDIO</CODE +></A +> ioctl was added to enumerate +audio inputs, while <A +HREF="#VIDIOC-G-AUDIO" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +></A +> now reports the current audio +input.</P +><P +>The same changes were made to <A +HREF="#VIDIOC-G-AUDIOOUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDOUT</CODE +></A +> and +<A +HREF="#VIDIOC-ENUMAUDIOOUT" +><CODE +CLASS="CONSTANT" +>VIDIOC_ENUMAUDOUT</CODE +></A +>.</P +><P +>Until further the "videodev" module will automatically +translate to the new versions, drivers and applications must be updated +when they are recompiled.</P +></LI +><LI +><P +>The <A +HREF="#VIDIOC-OVERLAY" +><CODE +CLASS="CONSTANT" +>VIDIOC_OVERLAY</CODE +></A +> ioctl was incorrectly defined with +read-write parameter. It was changed to write-only, while the read-write +version was renamed to <CODE +CLASS="CONSTANT" +>VIDIOC_OVERLAY_OLD</CODE +>. This +function will be removed in the future. Until further the "videodev" +module will automatically translate to the new version, so drivers +must be recompiled, but not applications.</P +></LI +><LI +><P +><A +HREF="#OVERLAY" +>Section 4.2</A +> incorrectly stated that +clipping rectangles define regions where the video can be seen. +Correct is that clipping rectangles define regions where +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>no</I +></SPAN +> video shall be displayed and so the graphics +surface can be seen.</P +></LI +><LI +><P +>The <A +HREF="#VIDIOC-G-PARM" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_PARM</CODE +></A +> and <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +> were defined +with write-only parameter, inconsistent with other ioctls modifying +their argument. They were changed to read-write, while a +<CODE +CLASS="CONSTANT" +>_OLD</CODE +> suffix was added to the write-only version. +These functions will be removed in the future. Drivers, and +applications assuming a constant parameter, need an update.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11136" +>6.2.11. V4L2 2003-11-05</A +></H3 +><P +></P +><OL +TYPE="1" +><LI +><P +>In <A +HREF="#PIXFMT-RGB" +>Section 2.3</A +> the following pixel +formats were incorrectly transferred from Bill Dirks' V4L2 +specification. Descriptions refer to bytes in memory, in ascending +address order.<DIV +CLASS="INFORMALTABLE" +><P +></P +><A +NAME="AEN11142" +></A +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><COL><COL><COL><THEAD +><TR +><TH +>Symbol</TH +><TH +>In this document prior to revision 0.5</TH +><TH +>Correct</TH +></TR +></THEAD +><TBODY +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB24</CODE +></TD +><TD +>B, G, R</TD +><TD +>R, G, B</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR24</CODE +></TD +><TD +>R, G, B</TD +><TD +>B, G, R</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_RGB32</CODE +></TD +><TD +>B, G, R, X</TD +><TD +>R, G, B, X</TD +></TR +><TR +><TD +><CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR32</CODE +></TD +><TD +>R, G, B, X</TD +><TD +>B, G, R, X</TD +></TR +></TBODY +></TABLE +><P +></P +></DIV +> The +<CODE +CLASS="CONSTANT" +>V4L2_PIX_FMT_BGR24</CODE +> example was always +correct.</P +><P +>In <A +HREF="#V4L-IMAGE-PROPERTIES" +>Section 6.1.5</A +> the mapping of +<CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RGB24</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDEO_PALETTE_RGB32</CODE +> to V4L2 pixel formats was accordingly corrected.</P +></LI +><LI +><P +>Unrelated to the fixes above, drivers may still interpret some V4L2 RGB pixel formats differently. These issues have yet to be addressed, for details see <A +HREF="#PIXFMT-RGB" +>Section 2.3</A +>.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11178" +>6.2.12. V4L2 in Linux 2.6.6, 2004-05-09</A +></H3 +><P +></P +><OL +TYPE="1" +><LI +><P +>The <A +HREF="#VIDIOC-CROPCAP" +><CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP</CODE +></A +> ioctl was incorrectly defined with +read-only parameter. It was changed to read-write, while the read-only +version was renamed to <CODE +CLASS="CONSTANT" +>VIDIOC_CROPCAP_OLD</CODE +>. This +function will be removed in the future.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11186" +>6.2.13. V4L2 in Linux 2.6.8</A +></H3 +><P +></P +><OL +TYPE="1" +><LI +><P +>A new field <CODE +CLASS="STRUCTFIELD" +>input</CODE +> (former +<CODE +CLASS="STRUCTFIELD" +>reserved[0]</CODE +>) was added to the +struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> structure. It must be enabled with the new +<CODE +CLASS="CONSTANT" +>V4L2_BUF_FLAG_INPUT</CODE +> flag. The +<CODE +CLASS="STRUCTFIELD" +>flags</CODE +> field is no longer read-only.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11196" +>6.2.14. V4L2 spec erratum 2004-08-01</A +></H3 +><P +></P +><OL +TYPE="1" +><LI +><P +>The return value of the +<A +HREF="#FUNC-OPEN" +>open</A +> function was incorrect.</P +></LI +><LI +><P +>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</P +></LI +><LI +><P +>In the current audio input example the +<CODE +CLASS="CONSTANT" +>VIDIOC_G_AUDIO</CODE +> ioctl took the wrong +argument.</P +></LI +><LI +><P +>The <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> and <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +></A +> ioctl did not +mention the struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> <CODE +CLASS="STRUCTFIELD" +>memory</CODE +> field, it +was also missing from examples. Added description of the +<CODE +CLASS="CONSTANT" +>VIDIOC_DQBUF</CODE +> <CODE +CLASS="CONSTANT" +>EIO</CODE +> error.</P +></LI +></OL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="OTHER" +>6.3. Relation of V4L2 to other Linux multimedia APIs</A +></H2 +><DIV +CLASS="SECTION" +><H3 +CLASS="SECTION" +><A +NAME="XVIDEO" +>6.3.1. X Video Extension</A +></H3 +><P +>The X Video Extension (abbreviated XVideo or just Xv) is +an extension of the X Window system, implemented for example by the +XFree86 project. Its scope is similar to V4L2, an API to video capture +and output devices for X clients. Xv allows applications to display +live video in a window, send window contents to a TV output, and +capture or output still images in XPixmaps<A +NAME="AEN11222" +HREF="#FTN.AEN11222" +><SPAN +CLASS="footnote" +>[27]</SPAN +></A +>. With their implementation XFree86 makes the +extension available across many operating systems and +architectures.</P +><P +>Because the driver is embedded into the X server Xv has a +number of advantages over the V4L2 <A +HREF="#OVERLAY" +>video +overlay interface</A +>. The driver can easily determine the overlay +target, i. e. visible graphics memory or off-screen buffers for +non-destructive overlay. It can program the RAMDAC for overlay, +scaling or color-keying, or the clipping functions of the video +capture hardware, always in sync with drawing operations or windows +moving or changing their stacking order.</P +><P +>To combine the advantages of Xv and V4L a special Xv +driver exists in XFree86, just programming any overlay capable +Video4Linux device it finds. To enable it +<TT +CLASS="FILENAME" +>/etc/X11/XF86Config</TT +> must contain these lines:</P +><P +><PRE +CLASS="SCREEN" +>Section "Module" + Load "v4l" +EndSection</PRE +></P +><P +>As of XFree86 4.2 this driver still supports only V4L +ioctls, however it should work just fine with all V4L2 devices through +the V4L2 backward-compatibility layer. Since V4L2 permits multiple +opens it is possible (if supported by the V4L2 driver) to capture +video while an X client requested video overlay. Restrictions of +simultaneous capturing and overlay mentioned in <A +HREF="#OVERLAY" +>Section 4.2</A +> apply.</P +><P +>Only marginally related to V4L2, XFree86 extended Xv to +support hardware YUV to RGB conversion and scaling for faster video +playback, and added an interface to MPEG-2 decoding hardware. This +can be used to improve displaying captured images.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11233" +>6.3.2. Digital Video</A +></H3 +><P +>V4L2 does not, at this time and possibly never, support +digital terrestrial, cable or satellite broadcast. A separate project +aiming at digital receivers exists. You can find its homepage at +<A +HREF="http://linuxtv.org" +TARGET="_top" +>http://linuxtv.org</A +>. This group +found the requirements sufficiently different from analog television +to choose independent development of their interfaces.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN11237" +>6.3.3. Audio Interfaces</A +></H3 +><P +>[to do - OSS/ALSA]</P +></DIV +></DIV +></DIV +><DIV +CLASS="APPENDIX" +><HR><H1 +><A +NAME="VIDEODEV" +></A +>Appendix A. Video For Linux Two Header File</H1 +><PRE +CLASS="PROGRAMLISTING" +>#ifndef __LINUX_VIDEODEV2_H +#define __LINUX_VIDEODEV2_H +/* + * Video for Linux Two + * + * Header file for v4l or V4L2 drivers and applications, for + * Linux kernels 2.2.x or 2.4.x. + * + * See http://bytesex.org/v4l/ for API specs and other + * v4l2 documentation. + * + * Author: Bill Dirks <bdirks@pacbell.net> + * Justin Schoeman + * et al. + */ +#ifdef __KERNEL__ +#include <linux/time.h> /* need struct timeval */ +#endif + +/* + * M I S C E L L A N E O U S + */ + +/* Four-character-code (FOURCC) */ +#define v4l2_fourcc(a,b,c,d)\ + (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) + +/* + * E N U M S + */ +enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +> { + V4L2_FIELD_ANY = 0, /* driver can choose from none, + top, bottom, interlaced + depending on whatever it thinks + is approximate ... */ + V4L2_FIELD_NONE = 1, /* this device has no fields ... */ + V4L2_FIELD_TOP = 2, /* top field only */ + V4L2_FIELD_BOTTOM = 3, /* bottom field only */ + V4L2_FIELD_INTERLACED = 4, /* both fields interlaced */ + V4L2_FIELD_SEQ_TB = 5, /* both fields sequential into one + buffer, top-bottom order */ + V4L2_FIELD_SEQ_BT = 6, /* same as above + bottom-top order */ + V4L2_FIELD_ALTERNATE = 7, /* both fields alternating into + separate buffers */ +}; +#define V4L2_FIELD_HAS_TOP(field) \ + ((field) == V4L2_FIELD_TOP ||\ + (field) == V4L2_FIELD_INTERLACED ||\ + (field) == V4L2_FIELD_SEQ_TB ||\ + (field) == V4L2_FIELD_SEQ_BT) +#define V4L2_FIELD_HAS_BOTTOM(field) \ + ((field) == V4L2_FIELD_BOTTOM ||\ + (field) == V4L2_FIELD_INTERLACED ||\ + (field) == V4L2_FIELD_SEQ_TB ||\ + (field) == V4L2_FIELD_SEQ_BT) +#define V4L2_FIELD_HAS_BOTH(field) \ + ((field) == V4L2_FIELD_INTERLACED ||\ + (field) == V4L2_FIELD_SEQ_TB ||\ + (field) == V4L2_FIELD_SEQ_BT) + +enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> { + V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, + V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, + V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, + V4L2_BUF_TYPE_VBI_CAPTURE = 4, + V4L2_BUF_TYPE_VBI_OUTPUT = 5, + V4L2_BUF_TYPE_PRIVATE = 0x80, +}; + +enum <A +HREF="#V4L2-CTRL-TYPE" +>v4l2_ctrl_type</A +> { + V4L2_CTRL_TYPE_INTEGER = 1, + V4L2_CTRL_TYPE_BOOLEAN = 2, + V4L2_CTRL_TYPE_MENU = 3, + V4L2_CTRL_TYPE_BUTTON = 4, +}; + +enum <A +HREF="#V4L2-TUNER-TYPE" +>v4l2_tuner_type</A +> { + V4L2_TUNER_RADIO = 1, + V4L2_TUNER_ANALOG_TV = 2, +}; + +enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +> { + V4L2_MEMORY_MMAP = 1, + V4L2_MEMORY_USERPTR = 2, + V4L2_MEMORY_OVERLAY = 3, +}; + +/* see also http://vektor.theorem.ca/graphics/ycbcr/ */ +enum <A +HREF="#V4L2-COLORSPACE" +>v4l2_colorspace</A +> { + /* ITU-R 601 -- broadcast NTSC/PAL */ + V4L2_COLORSPACE_SMPTE170M = 1, + + /* 1125-Line (US) HDTV */ + V4L2_COLORSPACE_SMPTE240M = 2, + + /* HD and modern captures. */ + V4L2_COLORSPACE_REC709 = 3, + + /* broken BT878 extents (601, luma range 16-253 instead of 16-235) */ + V4L2_COLORSPACE_BT878 = 4, + + /* These should be useful. Assume 601 extents. */ + V4L2_COLORSPACE_470_SYSTEM_M = 5, + V4L2_COLORSPACE_470_SYSTEM_BG = 6, + + /* I know there will be cameras that send this. So, this is + * unspecified chromaticities and full 0-255 on each of the + * Y'CbCr components + */ + V4L2_COLORSPACE_JPEG = 7, + + /* For RGB colourspaces, this is probably a good start. */ + V4L2_COLORSPACE_SRGB = 8, +}; + +enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> { + V4L2_PRIORITY_UNSET = 0, /* not initialized */ + V4L2_PRIORITY_BACKGROUND = 1, + V4L2_PRIORITY_INTERACTIVE = 2, + V4L2_PRIORITY_RECORD = 3, + V4L2_PRIORITY_DEFAULT = V4L2_PRIORITY_INTERACTIVE, +}; + +struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> { + __s32 left; + __s32 top; + __s32 width; + __s32 height; +}; + +struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +> { + __u32 numerator; + __u32 denominator; +}; + +/* + * D R I V E R C A P A B I L I T I E S + */ +struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> +{ + __u8 driver[16]; /* i.e. "bttv" */ + __u8 card[32]; /* i.e. "Hauppauge WinTV" */ + __u8 bus_info[32]; /* "PCI:" + pci_name(pci_dev) */ + __u32 version; /* should use KERNEL_VERSION() */ + __u32 capabilities; /* Device capabilities */ + __u32 reserved[4]; +}; + +/* Values for 'capabilities' field */ +#define V4L2_CAP_VIDEO_CAPTURE 0x00000001 /* Is a video capture device */ +#define V4L2_CAP_VIDEO_OUTPUT 0x00000002 /* Is a video output device */ +#define V4L2_CAP_VIDEO_OVERLAY 0x00000004 /* Can do video overlay */ +#define V4L2_CAP_VBI_CAPTURE 0x00000010 /* Is a VBI capture device */ +#define V4L2_CAP_VBI_OUTPUT 0x00000020 /* Is a VBI output device */ +#define V4L2_CAP_RDS_CAPTURE 0x00000100 /* RDS data capture */ + +#define V4L2_CAP_TUNER 0x00010000 /* has a tuner */ +#define V4L2_CAP_AUDIO 0x00020000 /* has audio support */ +#define V4L2_CAP_RADIO 0x00040000 /* is a radio device */ + +#define V4L2_CAP_READWRITE 0x01000000 /* read/write systemcalls */ +#define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */ +#define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */ + +/* + * V I D E O I M A G E F O R M A T + */ + +struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> +{ + __u32 width; + __u32 height; + __u32 pixelformat; + enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +> field; + __u32 bytesperline; /* for padding, zero if unused */ + __u32 sizeimage; + enum <A +HREF="#V4L2-COLORSPACE" +>v4l2_colorspace</A +> colorspace; + __u32 priv; /* private data, depends on pixelformat */ +}; + +/* Pixel format FOURCC depth Description */ +#define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R','G','B','1') /* 8 RGB-3-3-2 */ +#define V4L2_PIX_FMT_RGB555 v4l2_fourcc('R','G','B','O') /* 16 RGB-5-5-5 */ +#define V4L2_PIX_FMT_RGB565 v4l2_fourcc('R','G','B','P') /* 16 RGB-5-6-5 */ +#define V4L2_PIX_FMT_RGB555X v4l2_fourcc('R','G','B','Q') /* 16 RGB-5-5-5 BE */ +#define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R','G','B','R') /* 16 RGB-5-6-5 BE */ +#define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B','G','R','3') /* 24 BGR-8-8-8 */ +#define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R','G','B','3') /* 24 RGB-8-8-8 */ +#define V4L2_PIX_FMT_BGR32 v4l2_fourcc('B','G','R','4') /* 32 BGR-8-8-8-8 */ +#define V4L2_PIX_FMT_RGB32 v4l2_fourcc('R','G','B','4') /* 32 RGB-8-8-8-8 */ +#define V4L2_PIX_FMT_GREY v4l2_fourcc('G','R','E','Y') /* 8 Greyscale */ +#define V4L2_PIX_FMT_YVU410 v4l2_fourcc('Y','V','U','9') /* 9 YVU 4:1:0 */ +#define V4L2_PIX_FMT_YVU420 v4l2_fourcc('Y','V','1','2') /* 12 YVU 4:2:0 */ +#define V4L2_PIX_FMT_YUYV v4l2_fourcc('Y','U','Y','V') /* 16 YUV 4:2:2 */ +#define V4L2_PIX_FMT_UYVY v4l2_fourcc('U','Y','V','Y') /* 16 YUV 4:2:2 */ +#define V4L2_PIX_FMT_YUV422P v4l2_fourcc('4','2','2','P') /* 16 YVU422 planar */ +#define V4L2_PIX_FMT_YUV411P v4l2_fourcc('4','1','1','P') /* 16 YVU411 planar */ +#define V4L2_PIX_FMT_Y41P v4l2_fourcc('Y','4','1','P') /* 12 YUV 4:1:1 */ + +/* two planes -- one Y, one Cr + Cb interleaved */ +#define V4L2_PIX_FMT_NV12 v4l2_fourcc('N','V','1','2') /* 12 Y/CbCr 4:2:0 */ +#define V4L2_PIX_FMT_NV21 v4l2_fourcc('N','V','2','1') /* 12 Y/CrCb 4:2:0 */ + +/* The following formats are not defined in the V4L2 specification */ +#define V4L2_PIX_FMT_YUV410 v4l2_fourcc('Y','U','V','9') /* 9 YUV 4:1:0 */ +#define V4L2_PIX_FMT_YUV420 v4l2_fourcc('Y','U','1','2') /* 12 YUV 4:2:0 */ +#define V4L2_PIX_FMT_YYUV v4l2_fourcc('Y','Y','U','V') /* 16 YUV 4:2:2 */ +#define V4L2_PIX_FMT_HI240 v4l2_fourcc('H','I','2','4') /* 8 8-bit color */ + +/* compressed formats */ +#define V4L2_PIX_FMT_MJPEG v4l2_fourcc('M','J','P','G') /* Motion-JPEG */ +#define V4L2_PIX_FMT_JPEG v4l2_fourcc('J','P','E','G') /* JFIF JPEG */ +#define V4L2_PIX_FMT_DV v4l2_fourcc('d','v','s','d') /* 1394 */ +#define V4L2_PIX_FMT_MPEG v4l2_fourcc('M','P','E','G') /* MPEG */ + +/* Vendor-specific formats */ +#define V4L2_PIX_FMT_WNVA v4l2_fourcc('W','N','V','A') /* Winnov hw compress */ + +/* + * F O R M A T E N U M E R A T I O N + */ +struct <A +HREF="#V4L2-FMTDESC" +>v4l2_fmtdesc</A +> +{ + __u32 index; /* Format number */ + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; /* buffer type */ + __u32 flags; + __u8 description[32]; /* Description string */ + __u32 pixelformat; /* Format fourcc */ + __u32 reserved[4]; +}; + +#define V4L2_FMT_FLAG_COMPRESSED 0x0001 + + +/* + * T I M E C O D E + */ +struct <A +HREF="#V4L2-TIMECODE" +>v4l2_timecode</A +> +{ + __u32 type; + __u32 flags; + __u8 frames; + __u8 seconds; + __u8 minutes; + __u8 hours; + __u8 userbits[4]; +}; + +/* Type */ +#define V4L2_TC_TYPE_24FPS 1 +#define V4L2_TC_TYPE_25FPS 2 +#define V4L2_TC_TYPE_30FPS 3 +#define V4L2_TC_TYPE_50FPS 4 +#define V4L2_TC_TYPE_60FPS 5 + +/* Flags */ +#define V4L2_TC_FLAG_DROPFRAME 0x0001 /* "drop-frame" mode */ +#define V4L2_TC_FLAG_COLORFRAME 0x0002 +#define V4L2_TC_USERBITS_field 0x000C +#define V4L2_TC_USERBITS_USERDEFINED 0x0000 +#define V4L2_TC_USERBITS_8BITCHARS 0x0008 +/* The above is based on SMPTE timecodes */ + + +/* + * C O M P R E S S I O N P A R A M E T E R S + */ +#if 0 +/* ### generic compression settings don't work, there is too much + * ### codec-specific stuff. Maybe reuse that for MPEG codec settings + * ### later ... */ +struct <A +HREF="#V4L2-COMPRESSION" +>v4l2_compression</A +> +{ + __u32 quality; + __u32 keyframerate; + __u32 pframerate; + __u32 reserved[5]; + +/* what we'll need for MPEG, extracted from some postings on + the v4l list (Gert Vervoort, PlasmaJohn). + +system stream: + - type: elementary stream(ES), packatised elementary stream(s) (PES) + program stream(PS), transport stream(TS) + - system bitrate + - PS packet size (DVD: 2048 bytes, VCD: 2324 bytes) + - TS video PID + - TS audio PID + - TS PCR PID + - TS system information tables (PAT, PMT, CAT, NIT and SIT) + - (MPEG-1 systems stream vs. MPEG-2 program stream (TS not supported + by MPEG-1 systems) + +audio: + - type: MPEG (+Layer I,II,III), AC-3, LPCM + - bitrate + - sampling frequency (DVD: 48 Khz, VCD: 44.1 KHz, 32 kHz) + - Trick Modes? (ff, rew) + - Copyright + - Inverse Telecine + +video: + - picturesize (SIF, 1/2 D1, 2/3 D1, D1) and PAL/NTSC norm can be set + through excisting V4L2 controls + - noise reduction, parameters encoder specific? + - MPEG video version: MPEG-1, MPEG-2 + - GOP (Group Of Pictures) definition: + - N: number of frames per GOP + - M: distance between reference (I,P) frames + - open/closed GOP + - quantiser matrix: inter Q matrix (64 bytes) and intra Q matrix (64 bytes) + - quantiser scale: linear or logarithmic + - scanning: alternate or zigzag + - bitrate mode: CBR (constant bitrate) or VBR (variable bitrate). + - target video bitrate for CBR + - target video bitrate for VBR + - maximum video bitrate for VBR - min. quantiser value for VBR + - max. quantiser value for VBR + - adaptive quantisation value + - return the number of bytes per GOP or bitrate for bitrate monitoring + +*/ +}; +#endif + +struct <A +HREF="#V4L2-JPEGCOMPRESSION" +>v4l2_jpegcompression</A +> +{ + int quality; + + int APPn; /* Number of APP segment to be written, + * must be 0..15 */ + int APP_len; /* Length of data in JPEG APPn segment */ + char APP_data[60]; /* Data in the JPEG APPn segment. */ + + int COM_len; /* Length of data in JPEG COM segment */ + char COM_data[60]; /* Data in JPEG COM segment */ + + __u32 jpeg_markers; /* Which markers should go into the JPEG + * output. Unless you exactly know what + * you do, leave them untouched. + * Inluding less markers will make the + * resulting code smaller, but there will + * be fewer aplications which can read it. + * The presence of the APP and COM marker + * is influenced by APP_len and COM_len + * ONLY, not by this property! */ + +#define V4L2_JPEG_MARKER_DHT (1<<3) /* Define Huffman Tables */ +#define V4L2_JPEG_MARKER_DQT (1<<4) /* Define Quantization Tables */ +#define V4L2_JPEG_MARKER_DRI (1<<5) /* Define Restart Interval */ +#define V4L2_JPEG_MARKER_COM (1<<6) /* Comment segment */ +#define V4L2_JPEG_MARKER_APP (1<<7) /* App segment, driver will + * allways use APP0 */ +}; + + +/* + * M E M O R Y - M A P P I N G B U F F E R S + */ +struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> +{ + __u32 count; + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +> memory; + __u32 reserved[2]; +}; + +struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> +{ + __u32 index; + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + __u32 bytesused; + __u32 flags; + enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +> field; + struct timeval timestamp; + struct <A +HREF="#V4L2-TIMECODE" +>v4l2_timecode</A +> timecode; + __u32 sequence; + + /* memory location */ + enum <A +HREF="#V4L2-MEMORY" +>v4l2_memory</A +> memory; + union { + __u32 offset; + unsigned long userptr; + } m; + __u32 length; + __u32 input; + __u32 reserved; +}; + +/* Flags for 'flags' field */ +#define V4L2_BUF_FLAG_MAPPED 0x0001 /* Buffer is mapped (flag) */ +#define V4L2_BUF_FLAG_QUEUED 0x0002 /* Buffer is queued for processing */ +#define V4L2_BUF_FLAG_DONE 0x0004 /* Buffer is ready */ +#define V4L2_BUF_FLAG_KEYFRAME 0x0008 /* Image is a keyframe (I-frame) */ +#define V4L2_BUF_FLAG_PFRAME 0x0010 /* Image is a P-frame */ +#define V4L2_BUF_FLAG_BFRAME 0x0020 /* Image is a B-frame */ +#define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */ +#define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */ + +/* + * O V E R L A Y P R E V I E W + */ +struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +> +{ + __u32 capability; + __u32 flags; +/* FIXME: in theory we should pass something like PCI device + memory + * region + offset instead of some physical address */ + void* base; + struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> fmt; +}; +/* Flags for the 'capability' field. Read only */ +#define V4L2_FBUF_CAP_EXTERNOVERLAY 0x0001 +#define V4L2_FBUF_CAP_CHROMAKEY 0x0002 +#define V4L2_FBUF_CAP_LIST_CLIPPING 0x0004 +#define V4L2_FBUF_CAP_BITMAP_CLIPPING 0x0008 +/* Flags for the 'flags' field. */ +#define V4L2_FBUF_FLAG_PRIMARY 0x0001 +#define V4L2_FBUF_FLAG_OVERLAY 0x0002 +#define V4L2_FBUF_FLAG_CHROMAKEY 0x0004 + +struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> +{ + struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> c; + struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> *next; +}; + +struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +> +{ + struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> w; + enum <A +HREF="#V4L2-FIELD" +>v4l2_field</A +> field; + __u32 chromakey; + struct <A +HREF="#V4L2-CLIP" +>v4l2_clip</A +> *clips; + __u32 clipcount; + void *bitmap; +}; + + +/* + * C A P T U R E P A R A M E T E R S + */ +struct <A +HREF="#V4L2-CAPTUREPARM" +>v4l2_captureparm</A +> +{ + __u32 capability; /* Supported modes */ + __u32 capturemode; /* Current mode */ + struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +> timeperframe; /* Time per frame in .1us units */ + __u32 extendedmode; /* Driver-specific extensions */ + __u32 readbuffers; /* # of buffers for read */ + __u32 reserved[4]; +}; +/* Flags for 'capability' and 'capturemode' fields */ +#define V4L2_MODE_HIGHQUALITY 0x0001 /* High quality imaging mode */ +#define V4L2_CAP_TIMEPERFRAME 0x1000 /* timeperframe field is supported */ + +struct <A +HREF="#V4L2-OUTPUTPARM" +>v4l2_outputparm</A +> +{ + __u32 capability; /* Supported modes */ + __u32 outputmode; /* Current mode */ + struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +> timeperframe; /* Time per frame in seconds */ + __u32 extendedmode; /* Driver-specific extensions */ + __u32 writebuffers; /* # of buffers for write */ + __u32 reserved[4]; +}; + +/* + * I N P U T I M A G E C R O P P I N G + */ + +struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> { + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> bounds; + struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> defrect; + struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +> pixelaspect; +}; + +struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +> { + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + struct <A +HREF="#V4L2-RECT" +>v4l2_rect</A +> c; +}; + +/* + * A N A L O G V I D E O S T A N D A R D + */ + +typedef __u64 v4l2_std_id; + +/* one bit for each */ +#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) +#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) +#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) +#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) +#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) +#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) +#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) +#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) + +#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) +#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) +#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) +#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) + +#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) +#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) + +#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) +#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) +#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) +#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) +#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) +#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) +#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) + +/* ATSC/HDTV */ +#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) +#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) + +/* some common needed stuff */ +#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ + V4L2_STD_PAL_B1 |\ + V4L2_STD_PAL_G) +#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ + V4L2_STD_PAL_D1 |\ + V4L2_STD_PAL_K) +#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ + V4L2_STD_PAL_DK |\ + V4L2_STD_PAL_H |\ + V4L2_STD_PAL_I) +#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ + V4L2_STD_NTSC_M_JP) +#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ + V4L2_STD_SECAM_D |\ + V4L2_STD_SECAM_G |\ + V4L2_STD_SECAM_H |\ + V4L2_STD_SECAM_K |\ + V4L2_STD_SECAM_K1 |\ + V4L2_STD_SECAM_L) + +#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ + V4L2_STD_PAL_60 |\ + V4L2_STD_NTSC) +#define V4L2_STD_625_50 (V4L2_STD_PAL |\ + V4L2_STD_PAL_N |\ + V4L2_STD_PAL_Nc |\ + V4L2_STD_SECAM) + +#define V4L2_STD_UNKNOWN 0 +#define V4L2_STD_ALL (V4L2_STD_525_60 |\ + V4L2_STD_625_50) + +struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> +{ + __u32 index; + v4l2_std_id id; + __u8 name[24]; + struct <A +HREF="#V4L2-FRACT" +>v4l2_fract</A +> frameperiod; /* Frames, not fields */ + __u32 framelines; + __u32 reserved[4]; +}; + + +/* + * V I D E O I N P U T S + */ +struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> +{ + __u32 index; /* Which input */ + __u8 name[32]; /* Label */ + __u32 type; /* Type of input */ + __u32 audioset; /* Associated audios (bitfield) */ + __u32 tuner; /* Associated tuner */ + v4l2_std_id std; + __u32 status; + __u32 reserved[4]; +}; +/* Values for the 'type' field */ +#define V4L2_INPUT_TYPE_TUNER 1 +#define V4L2_INPUT_TYPE_CAMERA 2 + +/* field 'status' - general */ +#define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */ +#define V4L2_IN_ST_NO_SIGNAL 0x00000002 +#define V4L2_IN_ST_NO_COLOR 0x00000004 + +/* field 'status' - analog */ +#define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */ +#define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */ + +/* field 'status' - digital */ +#define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */ +#define V4L2_IN_ST_NO_EQU 0x00020000 /* No equalizer lock */ +#define V4L2_IN_ST_NO_CARRIER 0x00040000 /* Carrier recovery failed */ + +/* field 'status' - VCR and set-top box */ +#define V4L2_IN_ST_MACROVISION 0x01000000 /* Macrovision detected */ +#define V4L2_IN_ST_NO_ACCESS 0x02000000 /* Conditional access denied */ +#define V4L2_IN_ST_VTR 0x04000000 /* VTR time constant */ + +/* + * V I D E O O U T P U T S + */ +struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> +{ + __u32 index; /* Which output */ + __u8 name[32]; /* Label */ + __u32 type; /* Type of output */ + __u32 audioset; /* Associated audios (bitfield) */ + __u32 modulator; /* Associated modulator */ + v4l2_std_id std; + __u32 reserved[4]; +}; +/* Values for the 'type' field */ +#define V4L2_OUTPUT_TYPE_MODULATOR 1 +#define V4L2_OUTPUT_TYPE_ANALOG 2 +#define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY 3 + +/* + * C O N T R O L S + */ +struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +> +{ + __u32 id; + __s32 value; +}; + +/* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */ +struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +> +{ + __u32 id; + enum <A +HREF="#V4L2-CTRL-TYPE" +>v4l2_ctrl_type</A +> type; + __u8 name[32]; /* Whatever */ + __s32 minimum; /* Note signedness */ + __s32 maximum; + __s32 step; + __s32 default_value; + __u32 flags; + __u32 reserved[2]; +}; + +/* Used in the VIDIOC_QUERYMENU ioctl for querying menu items */ +struct <A +HREF="#V4L2-QUERYMENU" +>v4l2_querymenu</A +> +{ + __u32 id; + __u32 index; + __u8 name[32]; /* Whatever */ + __u32 reserved; +}; + +/* Control flags */ +#define V4L2_CTRL_FLAG_DISABLED 0x0001 +#define V4L2_CTRL_FLAG_GRABBED 0x0002 + +/* Control IDs defined by V4L2 */ +#define V4L2_CID_BASE 0x00980900 +/* IDs reserved for driver specific controls */ +#define V4L2_CID_PRIVATE_BASE 0x08000000 + +#define V4L2_CID_BRIGHTNESS (V4L2_CID_BASE+0) +#define V4L2_CID_CONTRAST (V4L2_CID_BASE+1) +#define V4L2_CID_SATURATION (V4L2_CID_BASE+2) +#define V4L2_CID_HUE (V4L2_CID_BASE+3) +#define V4L2_CID_AUDIO_VOLUME (V4L2_CID_BASE+5) +#define V4L2_CID_AUDIO_BALANCE (V4L2_CID_BASE+6) +#define V4L2_CID_AUDIO_BASS (V4L2_CID_BASE+7) +#define V4L2_CID_AUDIO_TREBLE (V4L2_CID_BASE+8) +#define V4L2_CID_AUDIO_MUTE (V4L2_CID_BASE+9) +#define V4L2_CID_AUDIO_LOUDNESS (V4L2_CID_BASE+10) +#define V4L2_CID_BLACK_LEVEL (V4L2_CID_BASE+11) +#define V4L2_CID_AUTO_WHITE_BALANCE (V4L2_CID_BASE+12) +#define V4L2_CID_DO_WHITE_BALANCE (V4L2_CID_BASE+13) +#define V4L2_CID_RED_BALANCE (V4L2_CID_BASE+14) +#define V4L2_CID_BLUE_BALANCE (V4L2_CID_BASE+15) +#define V4L2_CID_GAMMA (V4L2_CID_BASE+16) +#define V4L2_CID_WHITENESS (V4L2_CID_GAMMA) /* ? Not sure */ +#define V4L2_CID_EXPOSURE (V4L2_CID_BASE+17) +#define V4L2_CID_AUTOGAIN (V4L2_CID_BASE+18) +#define V4L2_CID_GAIN (V4L2_CID_BASE+19) +#define V4L2_CID_HFLIP (V4L2_CID_BASE+20) +#define V4L2_CID_VFLIP (V4L2_CID_BASE+21) +#define V4L2_CID_HCENTER (V4L2_CID_BASE+22) +#define V4L2_CID_VCENTER (V4L2_CID_BASE+23) +#define V4L2_CID_LASTP1 (V4L2_CID_BASE+24) /* last CID + 1 */ + +/* + * T U N I N G + */ +struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +> +{ + __u32 index; + __u8 name[32]; + enum <A +HREF="#V4L2-TUNER-TYPE" +>v4l2_tuner_type</A +> type; + __u32 capability; + __u32 rangelow; + __u32 rangehigh; + __u32 rxsubchans; + __u32 audmode; + __s32 signal; + __s32 afc; + __u32 reserved[4]; +}; + +struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +> +{ + __u32 index; + __u8 name[32]; + __u32 capability; + __u32 rangelow; + __u32 rangehigh; + __u32 txsubchans; + __u32 reserved[4]; +}; + +/* Flags for the 'capability' field */ +#define V4L2_TUNER_CAP_LOW 0x0001 +#define V4L2_TUNER_CAP_NORM 0x0002 +#define V4L2_TUNER_CAP_STEREO 0x0010 +#define V4L2_TUNER_CAP_LANG2 0x0020 +#define V4L2_TUNER_CAP_SAP 0x0020 +#define V4L2_TUNER_CAP_LANG1 0x0040 + +/* Flags for the 'rxsubchans' field */ +#define V4L2_TUNER_SUB_MONO 0x0001 +#define V4L2_TUNER_SUB_STEREO 0x0002 +#define V4L2_TUNER_SUB_LANG2 0x0004 +#define V4L2_TUNER_SUB_SAP 0x0004 +#define V4L2_TUNER_SUB_LANG1 0x0008 + +/* Values for the 'audmode' field */ +#define V4L2_TUNER_MODE_MONO 0x0000 +#define V4L2_TUNER_MODE_STEREO 0x0001 +#define V4L2_TUNER_MODE_LANG2 0x0002 +#define V4L2_TUNER_MODE_SAP 0x0002 +#define V4L2_TUNER_MODE_LANG1 0x0003 + +struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +> +{ + __u32 tuner; + enum <A +HREF="#V4L2-TUNER-TYPE" +>v4l2_tuner_type</A +> type; + __u32 frequency; + __u32 reserved[8]; +}; + +/* + * A U D I O + */ +struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> +{ + __u32 index; + __u8 name[32]; + __u32 capability; + __u32 mode; + __u32 reserved[2]; +}; +/* Flags for the 'capability' field */ +#define V4L2_AUDCAP_STEREO 0x00001 +#define V4L2_AUDCAP_AVL 0x00002 + +/* Flags for the 'mode' field */ +#define V4L2_AUDMODE_AVL 0x00001 + +struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +> +{ + __u32 index; + __u8 name[32]; + __u32 capability; + __u32 mode; + __u32 reserved[2]; +}; + +/* + * D A T A S E R V I C E S ( V B I ) + * + * Data services API by Michael Schimek + */ + +struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> +{ + __u32 sampling_rate; /* in 1 Hz */ + __u32 offset; + __u32 samples_per_line; + __u32 sample_format; /* V4L2_PIX_FMT_* */ + __s32 start[2]; + __u32 count[2]; + __u32 flags; /* V4L2_VBI_* */ + __u32 reserved[2]; /* must be zero */ +}; + +/* VBI flags */ +#define V4L2_VBI_UNSYNC (1<< 0) +#define V4L2_VBI_INTERLACED (1<< 1) + + +/* + * A G G R E G A T E S T R U C T U R E S + */ + +/* Stream data format + */ +struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> +{ + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + union + { + struct <A +HREF="#V4L2-PIX-FORMAT" +>v4l2_pix_format</A +> pix; // V4L2_BUF_TYPE_VIDEO_CAPTURE + struct <A +HREF="#V4L2-WINDOW" +>v4l2_window</A +> win; // V4L2_BUF_TYPE_VIDEO_OVERLAY + struct <A +HREF="#V4L2-VBI-FORMAT" +>v4l2_vbi_format</A +> vbi; // V4L2_BUF_TYPE_VBI_CAPTURE + __u8 raw_data[200]; // user-defined + } fmt; +}; + + +/* Stream type-dependent parameters + */ +struct <A +HREF="#V4L2-STREAMPARM" +>v4l2_streamparm</A +> +{ + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + union + { + struct <A +HREF="#V4L2-CAPTUREPARM" +>v4l2_captureparm</A +> capture; + struct <A +HREF="#V4L2-OUTPUTPARM" +>v4l2_outputparm</A +> output; + __u8 raw_data[200]; /* user-defined */ + } parm; +}; + + + +/* + * I O C T L C O D E S F O R V I D E O D E V I C E S + * + */ +#define VIDIOC_QUERYCAP _IOR ('V', 0, struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +>) +#define VIDIOC_RESERVED _IO ('V', 1) +#define VIDIOC_ENUM_FMT _IOWR ('V', 2, struct <A +HREF="#V4L2-FMTDESC" +>v4l2_fmtdesc</A +>) +#define VIDIOC_G_FMT _IOWR ('V', 4, struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +>) +#define VIDIOC_S_FMT _IOWR ('V', 5, struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +>) +#if 0 +#define VIDIOC_G_COMP _IOR ('V', 6, struct <A +HREF="#V4L2-COMPRESSION" +>v4l2_compression</A +>) +#define VIDIOC_S_COMP _IOW ('V', 7, struct <A +HREF="#V4L2-COMPRESSION" +>v4l2_compression</A +>) +#endif +#define VIDIOC_REQBUFS _IOWR ('V', 8, struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +>) +#define VIDIOC_QUERYBUF _IOWR ('V', 9, struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +>) +#define VIDIOC_G_FBUF _IOR ('V', 10, struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +>) +#define VIDIOC_S_FBUF _IOW ('V', 11, struct <A +HREF="#V4L2-FRAMEBUFFER" +>v4l2_framebuffer</A +>) +#define VIDIOC_OVERLAY _IOW ('V', 14, int) +#define VIDIOC_QBUF _IOWR ('V', 15, struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +>) +#define VIDIOC_DQBUF _IOWR ('V', 17, struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +>) +#define VIDIOC_STREAMON _IOW ('V', 18, int) +#define VIDIOC_STREAMOFF _IOW ('V', 19, int) +#define VIDIOC_G_PARM _IOWR ('V', 21, struct <A +HREF="#V4L2-STREAMPARM" +>v4l2_streamparm</A +>) +#define VIDIOC_S_PARM _IOWR ('V', 22, struct <A +HREF="#V4L2-STREAMPARM" +>v4l2_streamparm</A +>) +#define VIDIOC_G_STD _IOR ('V', 23, v4l2_std_id) +#define VIDIOC_S_STD _IOW ('V', 24, v4l2_std_id) +#define VIDIOC_ENUMSTD _IOWR ('V', 25, struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +>) +#define VIDIOC_ENUMINPUT _IOWR ('V', 26, struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +>) +#define VIDIOC_G_CTRL _IOWR ('V', 27, struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +>) +#define VIDIOC_S_CTRL _IOWR ('V', 28, struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +>) +#define VIDIOC_G_TUNER _IOWR ('V', 29, struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +>) +#define VIDIOC_S_TUNER _IOW ('V', 30, struct <A +HREF="#V4L2-TUNER" +>v4l2_tuner</A +>) +#define VIDIOC_G_AUDIO _IOR ('V', 33, struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +>) +#define VIDIOC_S_AUDIO _IOW ('V', 34, struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +>) +#define VIDIOC_QUERYCTRL _IOWR ('V', 36, struct <A +HREF="#V4L2-QUERYCTRL" +>v4l2_queryctrl</A +>) +#define VIDIOC_QUERYMENU _IOWR ('V', 37, struct <A +HREF="#V4L2-QUERYMENU" +>v4l2_querymenu</A +>) +#define VIDIOC_G_INPUT _IOR ('V', 38, int) +#define VIDIOC_S_INPUT _IOWR ('V', 39, int) +#define VIDIOC_G_OUTPUT _IOR ('V', 46, int) +#define VIDIOC_S_OUTPUT _IOWR ('V', 47, int) +#define VIDIOC_ENUMOUTPUT _IOWR ('V', 48, struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +>) +#define VIDIOC_G_AUDOUT _IOR ('V', 49, struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +>) +#define VIDIOC_S_AUDOUT _IOW ('V', 50, struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +>) +#define VIDIOC_G_MODULATOR _IOWR ('V', 54, struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +>) +#define VIDIOC_S_MODULATOR _IOW ('V', 55, struct <A +HREF="#V4L2-MODULATOR" +>v4l2_modulator</A +>) +#define VIDIOC_G_FREQUENCY _IOWR ('V', 56, struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +>) +#define VIDIOC_S_FREQUENCY _IOW ('V', 57, struct <A +HREF="#V4L2-FREQUENCY" +>v4l2_frequency</A +>) +#define VIDIOC_CROPCAP _IOWR ('V', 58, struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +>) +#define VIDIOC_G_CROP _IOWR ('V', 59, struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +>) +#define VIDIOC_S_CROP _IOW ('V', 60, struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +>) +#define VIDIOC_G_JPEGCOMP _IOR ('V', 61, struct <A +HREF="#V4L2-JPEGCOMPRESSION" +>v4l2_jpegcompression</A +>) +#define VIDIOC_S_JPEGCOMP _IOW ('V', 62, struct <A +HREF="#V4L2-JPEGCOMPRESSION" +>v4l2_jpegcompression</A +>) +#define VIDIOC_QUERYSTD _IOR ('V', 63, v4l2_std_id) +#define VIDIOC_TRY_FMT _IOWR ('V', 64, struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +>) +#define VIDIOC_ENUMAUDIO _IOWR ('V', 65, struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +>) +#define VIDIOC_ENUMAUDOUT _IOWR ('V', 66, struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +>) +#define VIDIOC_G_PRIORITY _IOR ('V', 67, enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +>) +#define VIDIOC_S_PRIORITY _IOW ('V', 68, enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +>) + +/* for compatibility, will go away some day */ +#define VIDIOC_OVERLAY_OLD _IOWR ('V', 14, int) +#define VIDIOC_S_PARM_OLD _IOW ('V', 22, struct <A +HREF="#V4L2-STREAMPARM" +>v4l2_streamparm</A +>) +#define VIDIOC_S_CTRL_OLD _IOW ('V', 28, struct <A +HREF="#V4L2-CONTROL" +>v4l2_control</A +>) +#define VIDIOC_G_AUDIO_OLD _IOWR ('V', 33, struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +>) +#define VIDIOC_G_AUDOUT_OLD _IOWR ('V', 49, struct <A +HREF="#V4L2-AUDIOOUT" +>v4l2_audioout</A +>) +#define VIDIOC_CROPCAP_OLD _IOR ('V', 58, struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +>) + +#define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */ + + +#ifdef __KERNEL__ +/* + * + * V 4 L 2 D R I V E R H E L P E R A P I + * + * Some commonly needed functions for drivers (v4l2-common.o module) + */ +#include <linux/fs.h> + +/* Video standard functions */ +extern unsigned int v4l2_video_std_fps(struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> *vs); +extern int v4l2_video_std_construct(struct <A +HREF="#V4L2-STANDARD" +>v4l2_standard</A +> *vs, + int id, char *name); + +/* prority handling */ +struct v4l2_prio_state { + atomic_t prios[4]; +}; +int v4l2_prio_init(struct v4l2_prio_state *global); +int v4l2_prio_change(struct v4l2_prio_state *global, enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> *local, + enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> new); +int v4l2_prio_open(struct v4l2_prio_state *global, enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> *local); +int v4l2_prio_close(struct v4l2_prio_state *global, enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> *local); +enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> v4l2_prio_max(struct v4l2_prio_state *global); +int v4l2_prio_check(struct v4l2_prio_state *global, enum <A +HREF="#V4L2-PRIORITY" +>v4l2_priority</A +> *local); + +/* names for fancy debug output */ +extern char *v4l2_field_names[]; +extern char *v4l2_type_names[]; +extern char *v4l2_ioctl_names[]; + +/* Compatibility layer interface -- v4l1-compat module */ +typedef int (*v4l2_kioctl)(struct inode *inode, struct file *file, + unsigned int cmd, void *arg); +int v4l_compat_translate_ioctl(struct inode *inode, struct file *file, + int cmd, void *arg, v4l2_kioctl driver_ioctl); + +#endif /* __KERNEL__ */ +#endif /* __LINUX_VIDEODEV2_H */ + +/* + * Local variables: + * c-basic-offset: 8 + * End: + */</PRE +></DIV +><DIV +CLASS="APPENDIX" +><HR><H1 +><A +NAME="CAPTURE-EXAMPLE" +></A +>Appendix B. Video Capture Example</H1 +><PRE +CLASS="PROGRAMLISTING" +>/* + * V4L2 video capture example + */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <assert.h> + +#include <getopt.h> /* getopt_long() */ + +#include <fcntl.h> /* low-level i/o */ +#include <unistd.h> +#include <errno.h> +#include <sys/stat.h> +#include <sys/types.h> +#include <sys/time.h> +#include <sys/mman.h> +#include <sys/ioctl.h> + +#include <asm/types.h> /* for videodev2.h */ + +#include <linux/videodev2.h> + +#define CLEAR(x) memset (&(x), 0, sizeof (x)) + +typedef enum { + IO_METHOD_READ, + IO_METHOD_MMAP, + IO_METHOD_USERPTR, +} io_method; + +struct buffer { + void * start; + size_t length; +}; + +static char * dev_name = NULL; +static io_method io = IO_METHOD_MMAP; +static int fd = -1; +struct buffer * buffers = NULL; +static unsigned int n_buffers = 0; + +static void +errno_exit (const char * s) +{ + fprintf (stderr, "%s error %d, %s\n", + s, errno, strerror (errno)); + + exit (EXIT_FAILURE); +} + +static int +xioctl (int fd, + int request, + void * arg) +{ + int r; + + do r = ioctl (fd, request, arg); + while (-1 == r && EINTR == errno); + + return r; +} + +static void +process_image (const void * p) +{ + fputc ('.', stdout); + fflush (stdout); +} + +static int +read_frame (void) +{ + struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> buf; + unsigned int i; + + switch (io) { + case IO_METHOD_READ: + if (-1 == read (fd, buffers[0].start, buffers[0].length)) { + switch (errno) { + case EAGAIN: + return 0; + + case EIO: + /* Could ignore EIO, see spec. */ + + /* fall through */ + + default: + errno_exit ("read"); + } + } + + process_image (buffers[0].start); + + break; + + case IO_METHOD_MMAP: + CLEAR (buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + + if (-1 == xioctl (fd, VIDIOC_DQBUF, &buf)) { + switch (errno) { + case EAGAIN: + return 0; + + case EIO: + /* Could ignore EIO, see spec. */ + + /* fall through */ + + default: + errno_exit ("VIDIOC_DQBUF"); + } + } + + assert (buf.index < n_buffers); + + process_image (buffers[buf.index].start); + + if (-1 == xioctl (fd, VIDIOC_QBUF, &buf)) + errno_exit ("VIDIOC_QBUF"); + + break; + + case IO_METHOD_USERPTR: + CLEAR (buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_USERPTR; + + if (-1 == xioctl (fd, VIDIOC_DQBUF, &buf)) { + switch (errno) { + case EAGAIN: + return 0; + + case EIO: + /* Could ignore EIO, see spec. */ + + /* fall through */ + + default: + errno_exit ("VIDIOC_DQBUF"); + } + } + + for (i = 0; i < n_buffers; ++i) + if (buf.m.userptr == (unsigned long) buffers[i].start + && buf.length == buffers[i].length) + break; + + assert (i < n_buffers); + + process_image ((void *) buf.m.userptr); + + if (-1 == xioctl (fd, VIDIOC_QBUF, &buf)) + errno_exit ("VIDIOC_QBUF"); + + break; + } + + return 1; +} + +static void +mainloop (void) +{ + unsigned int count; + + count = 100; + + while (count-- > 0) { + for (;;) { + fd_set fds; + struct timeval tv; + int r; + + FD_ZERO (&fds); + FD_SET (fd, &fds); + + /* Timeout. */ + tv.tv_sec = 2; + tv.tv_usec = 0; + + r = select (fd + 1, &fds, NULL, NULL, &tv); + + if (-1 == r) { + if (EINTR == errno) + continue; + + errno_exit ("select"); + } + + if (0 == r) { + fprintf (stderr, "select timeout\n"); + exit (EXIT_FAILURE); + } + + if (read_frame ()) + break; + + /* EAGAIN - continue select loop. */ + } + } +} + +static void +stop_capturing (void) +{ + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + + switch (io) { + case IO_METHOD_READ: + /* Nothing to do. */ + break; + + case IO_METHOD_MMAP: + case IO_METHOD_USERPTR: + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == xioctl (fd, VIDIOC_STREAMOFF, &type)) + errno_exit ("VIDIOC_STREAMOFF"); + + break; + } +} + +static void +start_capturing (void) +{ + unsigned int i; + enum <A +HREF="#V4L2-BUF-TYPE" +>v4l2_buf_type</A +> type; + + switch (io) { + case IO_METHOD_READ: + /* Nothing to do. */ + break; + + case IO_METHOD_MMAP: + for (i = 0; i < n_buffers; ++i) { + struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> buf; + + CLEAR (buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + buf.index = i; + + if (-1 == xioctl (fd, VIDIOC_QBUF, &buf)) + errno_exit ("VIDIOC_QBUF"); + } + + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == xioctl (fd, VIDIOC_STREAMON, &type)) + errno_exit ("VIDIOC_STREAMON"); + + break; + + case IO_METHOD_USERPTR: + for (i = 0; i < n_buffers; ++i) { + struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> buf; + + CLEAR (buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_USERPTR; + buf.m.userptr = (unsigned long) buffers[i].start; + buf.length = buffers[i].length; + + if (-1 == xioctl (fd, VIDIOC_QBUF, &buf)) + errno_exit ("VIDIOC_QBUF"); + } + + + type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == xioctl (fd, VIDIOC_STREAMON, &type)) + errno_exit ("VIDIOC_STREAMON"); + + break; + } +} + +static void +uninit_device (void) +{ + unsigned int i; + + switch (io) { + case IO_METHOD_READ: + free (buffers[0].start); + break; + + case IO_METHOD_MMAP: + for (i = 0; i < n_buffers; ++i) + if (-1 == munmap (buffers[i].start, buffers[i].length)) + errno_exit ("munmap"); + break; + + case IO_METHOD_USERPTR: + for (i = 0; i < n_buffers; ++i) + free (buffers[i].start); + break; + } + + free (buffers); +} + +static void +init_read (unsigned int buffer_size) +{ + buffers = calloc (1, sizeof (*buffers)); + + if (!buffers) { + fprintf (stderr, "Out of memory\n"); + exit (EXIT_FAILURE); + } + + buffers[0].length = buffer_size; + buffers[0].start = malloc (buffer_size); + + if (!buffers[0].start) { + fprintf (stderr, "Out of memory\n"); + exit (EXIT_FAILURE); + } +} + +static void +init_mmap (void) +{ + struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> req; + + CLEAR (req); + + req.count = 4; + req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + req.memory = V4L2_MEMORY_MMAP; + + if (-1 == xioctl (fd, VIDIOC_REQBUFS, &req)) { + if (EINVAL == errno) { + fprintf (stderr, "%s does not support " + "memory mapping\n", dev_name); + exit (EXIT_FAILURE); + } else { + errno_exit ("VIDIOC_REQBUFS"); + } + } + + if (req.count < 2) { + fprintf (stderr, "Insufficient buffer memory on %s\n", + dev_name); + exit (EXIT_FAILURE); + } + + buffers = calloc (req.count, sizeof (*buffers)); + + if (!buffers) { + fprintf (stderr, "Out of memory\n"); + exit (EXIT_FAILURE); + } + + for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { + struct <A +HREF="#V4L2-BUFFER" +>v4l2_buffer</A +> buf; + + CLEAR (buf); + + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_MMAP; + buf.index = n_buffers; + + if (-1 == xioctl (fd, VIDIOC_QUERYBUF, &buf)) + errno_exit ("VIDIOC_QUERYBUF"); + + buffers[n_buffers].length = buf.length; + buffers[n_buffers].start = + mmap (NULL /* start anywhere */, + buf.length, + PROT_READ | PROT_WRITE /* required */, + MAP_SHARED /* recommended */, + fd, buf.m.offset); + + if (MAP_FAILED == buffers[n_buffers].start) + errno_exit ("mmap"); + } +} + +static void +init_userp (unsigned int buffer_size) +{ + struct <A +HREF="#V4L2-REQUESTBUFFERS" +>v4l2_requestbuffers</A +> req; + + CLEAR (req); + + req.count = 4; + req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + req.memory = V4L2_MEMORY_USERPTR; + + if (-1 == xioctl (fd, VIDIOC_REQBUFS, &req)) { + if (EINVAL == errno) { + fprintf (stderr, "%s does not support " + "user pointer i/o\n", dev_name); + exit (EXIT_FAILURE); + } else { + errno_exit ("VIDIOC_REQBUFS"); + } + } + + buffers = calloc (4, sizeof (*buffers)); + + if (!buffers) { + fprintf (stderr, "Out of memory\n"); + exit (EXIT_FAILURE); + } + + for (n_buffers = 0; n_buffers < 4; ++n_buffers) { + buffers[n_buffers].length = buffer_size; + buffers[n_buffers].start = malloc (buffer_size); + + if (!buffers[n_buffers].start) { + fprintf (stderr, "Out of memory\n"); + exit (EXIT_FAILURE); + } + } +} + +static void +init_device (void) +{ + struct <A +HREF="#V4L2-CAPABILITY" +>v4l2_capability</A +> cap; + struct <A +HREF="#V4L2-CROPCAP" +>v4l2_cropcap</A +> cropcap; + struct <A +HREF="#V4L2-CROP" +>v4l2_crop</A +> crop; + struct <A +HREF="#V4L2-FORMAT" +>v4l2_format</A +> fmt; + unsigned int min; + + if (-1 == xioctl (fd, VIDIOC_QUERYCAP, &cap)) { + if (EINVAL == errno) { + fprintf (stderr, "%s is no V4L2 device\n", + dev_name); + exit (EXIT_FAILURE); + } else { + errno_exit ("VIDIOC_QUERYCAP"); + } + } + + if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { + fprintf (stderr, "%s is no video capture device\n", + dev_name); + exit (EXIT_FAILURE); + } + + switch (io) { + case IO_METHOD_READ: + if (!(cap.capabilities & V4L2_CAP_READWRITE)) { + fprintf (stderr, "%s does not support read i/o\n", + dev_name); + exit (EXIT_FAILURE); + } + + break; + + case IO_METHOD_MMAP: + case IO_METHOD_USERPTR: + if (!(cap.capabilities & V4L2_CAP_STREAMING)) { + fprintf (stderr, "%s does not support streaming i/o\n", + dev_name); + exit (EXIT_FAILURE); + } + + break; + } + + /* Select video input, video standard and tune here. */ + + cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == xioctl (fd, VIDIOC_CROPCAP, &cropcap)) { + /* Errors ignored. */ + } + + crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + crop.c = cropcap.defrect; /* reset to default */ + + if (-1 == xioctl (fd, VIDIOC_S_CROP, &crop)) { + switch (errno) { + case EINVAL: + /* Cropping not supported. */ + break; + default: + /* Errors ignored. */ + break; + } + } + + CLEAR (fmt); + + fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + fmt.fmt.pix.width = 640; + fmt.fmt.pix.height = 480; + fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; + fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; + + if (-1 == xioctl (fd, VIDIOC_S_FMT, &fmt)) + errno_exit ("VIDIOC_S_FMT"); + + /* Note VIDIOC_S_FMT may change width and height. */ + + /* Buggy driver paranoia. */ + min = fmt.fmt.pix.width * 2; + if (fmt.fmt.pix.bytesperline < min) + fmt.fmt.pix.bytesperline = min; + min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; + if (fmt.fmt.pix.sizeimage < min) + fmt.fmt.pix.sizeimage = min; + + switch (io) { + case IO_METHOD_READ: + init_read (fmt.fmt.pix.sizeimage); + break; + + case IO_METHOD_MMAP: + init_mmap (); + break; + + case IO_METHOD_USERPTR: + init_userp (fmt.fmt.pix.sizeimage); + break; + } +} + +static void +close_device (void) +{ + if (-1 == close (fd)) + errno_exit ("close"); + + fd = -1; +} + +static void +open_device (void) +{ + struct stat st; + + if (-1 == stat (dev_name, &st)) { + fprintf (stderr, "Cannot identify '%s': %d, %s\n", + dev_name, errno, strerror (errno)); + exit (EXIT_FAILURE); + } + + if (!S_ISCHR (st.st_mode)) { + fprintf (stderr, "%s is no device\n", dev_name); + exit (EXIT_FAILURE); + } + + fd = open (dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); + + if (-1 == fd) { + fprintf (stderr, "Cannot open '%s': %d, %s\n", + dev_name, errno, strerror (errno)); + exit (EXIT_FAILURE); + } +} + +static void +usage (FILE * fp, + int argc, + char ** argv) +{ + fprintf (fp, + "Usage: %s [options]\n\n" + "Options:\n" + "-d | --device name Video device name [/dev/video]\n" + "-h | --help Print this message\n" + "-m | --mmap Use memory mapped buffers\n" + "-r | --read Use read() calls\n" + "-u | --userp Use application allocated buffers\n" + "", + argv[0]); +} + +static const char short_options [] = "d:hmru"; + +static const struct option +long_options [] = { + { "device", required_argument, NULL, 'd' }, + { "help", no_argument, NULL, 'h' }, + { "mmap", no_argument, NULL, 'm' }, + { "read", no_argument, NULL, 'r' }, + { "userp", no_argument, NULL, 'u' }, + { 0, 0, 0, 0 } +}; + +int +main (int argc, + char ** argv) +{ + dev_name = "/dev/video"; + + for (;;) { + int index; + int c; + + c = getopt_long (argc, argv, + short_options, long_options, + &index); + + if (-1 == c) + break; + + switch (c) { + case 0: /* getopt_long() flag */ + break; + + case 'd': + dev_name = optarg; + break; + + case 'h': + usage (stdout, argc, argv); + exit (EXIT_SUCCESS); + + case 'm': + io = IO_METHOD_MMAP; + break; + + case 'r': + io = IO_METHOD_READ; + break; + + case 'u': + io = IO_METHOD_USERPTR; + break; + + default: + usage (stderr, argc, argv); + exit (EXIT_FAILURE); + } + } + + open_device (); + + init_device (); + + start_capturing (); + + mainloop (); + + stop_capturing (); + + uninit_device (); + + close_device (); + + exit (EXIT_SUCCESS); + + return 0; +}</PRE +></DIV +><DIV +CLASS="APPENDIX" +><HR><H1 +><A +NAME="FDL" +></A +>Appendix C. GNU Free Documentation License</H1 +><DIV +CLASS="SECT1" +><H2 +CLASS="SECT1" +><A +NAME="FDL-PREAMBLE" +>C.1. 0. PREAMBLE</A +></H2 +><P +> The purpose of this License is to make a manual, textbook, or + other written document <SPAN +CLASS="QUOTE" +>"free"</SPAN +> in the sense of + freedom: to assure everyone the effective freedom to copy and + redistribute it, with or without modifying it, either + commercially or noncommercially. Secondarily, this License + preserves for the author and publisher a way to get credit for + their work, while not being considered responsible for + modifications made by others. + </P +><P +> This License is a kind of <SPAN +CLASS="QUOTE" +>"copyleft"</SPAN +>, which means + that derivative works of the document must themselves be free in + the same sense. It complements the GNU General Public License, + which is a copyleft license designed for free software. + </P +><P +> We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same + freedoms that the software does. But this License is not limited + to software manuals; it can be used for any textual work, + regardless of subject matter or whether it is published as a + printed book. We recommend this License principally for works + whose purpose is instruction or reference. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION1" +>C.2. 1. APPLICABILITY AND DEFINITIONS</A +></H2 +><P +> This License applies to any manual or other work that contains a + notice placed by the copyright holder saying it can be + distributed under the terms of this License. The + <SPAN +CLASS="QUOTE" +>"Document"</SPAN +>, below, refers to any such manual or + work. Any member of the public is a licensee, and is addressed + as <SPAN +CLASS="QUOTE" +>"you"</SPAN +>. + </P +><P +> A <SPAN +CLASS="QUOTE" +>"Modified Version"</SPAN +> of the Document means any work + containing the Document or a portion of it, either copied + verbatim, or with modifications and/or translated into another + language. + </P +><P +> A <SPAN +CLASS="QUOTE" +>"Secondary Section"</SPAN +> is a named appendix or a + front-matter section of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> that deals exclusively + with the relationship of the publishers or authors of the + Document to the Document's overall subject (or to related + matters) and contains nothing that could fall directly within + that overall subject. (For example, if the Document is in part a + textbook of mathematics, a Secondary Section may not explain any + mathematics.) The relationship could be a matter of historical + connection with the subject or with related matters, or of + legal, commercial, philosophical, ethical or political position + regarding them. + </P +><P +> The <SPAN +CLASS="QUOTE" +>"Invariant Sections"</SPAN +> are certain <A +HREF="#FDL-SECONDARY" +> Secondary Sections</A +> whose titles + are designated, as being those of Invariant Sections, in the + notice that says that the <A +HREF="#FDL-DOCUMENT" +>Document</A +> is released under this + License. + </P +><P +> The <SPAN +CLASS="QUOTE" +>"Cover Texts"</SPAN +> are certain short passages of + text that are listed, as Front-Cover Texts or Back-Cover Texts, + in the notice that says that the <A +HREF="#FDL-DOCUMENT" +>Document</A +> is released under this + License. + </P +><P +> A <SPAN +CLASS="QUOTE" +>"Transparent"</SPAN +> copy of the <A +HREF="#FDL-DOCUMENT" +> Document</A +> means a machine-readable + copy, represented in a format whose specification is available + to the general public, whose contents can be viewed and edited + directly and straightforwardly with generic text editors or (for + images composed of pixels) generic paint programs or (for + drawings) some widely available drawing editor, and that is + suitable for input to text formatters or for automatic + translation to a variety of formats suitable for input to text + formatters. A copy made in an otherwise Transparent file format + whose markup has been designed to thwart or discourage + subsequent modification by readers is not Transparent. A copy + that is not <SPAN +CLASS="QUOTE" +>"Transparent"</SPAN +> is called + <SPAN +CLASS="QUOTE" +>"Opaque"</SPAN +>. + </P +><P +> Examples of suitable formats for Transparent copies include + plain ASCII without markup, Texinfo input format, LaTeX input + format, SGML or XML using a publicly available DTD, and + standard-conforming simple HTML designed for human + modification. Opaque formats include PostScript, PDF, + proprietary formats that can be read and edited only by + proprietary word processors, SGML or XML for which the DTD + and/or processing tools are not generally available, and the + machine-generated HTML produced by some word processors for + output purposes only. + </P +><P +> The <SPAN +CLASS="QUOTE" +>"Title Page"</SPAN +> means, for a printed book, the + title page itself, plus such following pages as are needed to + hold, legibly, the material this License requires to appear in + the title page. For works in formats which do not have any title + page as such, <SPAN +CLASS="QUOTE" +>"Title Page"</SPAN +> means the text near the + most prominent appearance of the work's title, preceding the + beginning of the body of the text. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION2" +>C.3. 2. VERBATIM COPYING</A +></H2 +><P +> You may copy and distribute the <A +HREF="#FDL-DOCUMENT" +>Document</A +> in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that + you add no other conditions whatsoever to those of this + License. You may not use technical measures to obstruct or + control the reading or further copying of the copies you make or + distribute. However, you may accept compensation in exchange for + copies. If you distribute a large enough number of copies you + must also follow the conditions in <A +HREF="#FDL-SECTION3" +>section 3</A +>. + </P +><P +> You may also lend copies, under the same conditions stated + above, and you may publicly display copies. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION3" +>C.4. 3. COPYING IN QUANTITY</A +></H2 +><P +> If you publish printed copies of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> numbering more than 100, + and the Document's license notice requires <A +HREF="#FDL-COVER-TEXTS" +>Cover Texts</A +>, you must enclose + the copies in covers that carry, clearly and legibly, all these + Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also + clearly and legibly identify you as the publisher of these + copies. The front cover must present the full title with all + words of the title equally prominent and visible. You may add + other material on the covers in addition. Copying with changes + limited to the covers, as long as they preserve the title of the + <A +HREF="#FDL-DOCUMENT" +>Document</A +> and satisfy these + conditions, can be treated as verbatim copying in other + respects. + </P +><P +> If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + </P +><P +> If you publish or distribute <A +HREF="#FDL-TRANSPARENT" +>Opaque</A +> copies of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> numbering more than 100, + you must either include a machine-readable <A +HREF="#FDL-TRANSPARENT" +>Transparent</A +> copy along with + each Opaque copy, or state in or with each Opaque copy a + publicly-accessible computer-network location containing a + complete Transparent copy of the Document, free of added + material, which the general network-using public has access to + download anonymously at no charge using public-standard network + protocols. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly + or through your agents or retailers) of that edition to the + public. + </P +><P +> It is requested, but not required, that you contact the authors + of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> well before + redistributing any large number of copies, to give them a chance + to provide you with an updated version of the Document. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION4" +>C.5. 4. MODIFICATIONS</A +></H2 +><P +> You may copy and distribute a <A +HREF="#FDL-MODIFIED" +>Modified Version</A +> of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> under the conditions of + sections <A +HREF="#FDL-SECTION2" +>2</A +> and <A +HREF="#FDL-SECTION3" +>3</A +> above, provided that you release + the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version + to whoever possesses a copy of it. In addition, you must do + these things in the Modified Version: + </P +><P +></P +><UL +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>A. </B +> Use in the <A +HREF="#FDL-TITLE-PAGE" +>Title + Page</A +> (and on the covers, if any) a title distinct + from that of the <A +HREF="#FDL-DOCUMENT" +>Document</A +>, and from those of + previous versions (which should, if there were any, be + listed in the History section of the Document). You may + use the same title as a previous version if the original + publisher of that version gives permission. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>B. </B +> List on the <A +HREF="#FDL-TITLE-PAGE" +>Title + Page</A +>, as authors, one or more persons or entities + responsible for authorship of the modifications in the + <A +HREF="#FDL-MODIFIED" +>Modified Version</A +>, + together with at least five of the principal authors of + the <A +HREF="#FDL-DOCUMENT" +>Document</A +> (all of + its principal authors, if it has less than five). + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>C. </B +> State on the <A +HREF="#FDL-TITLE-PAGE" +>Title + Page</A +> the name of the publisher of the <A +HREF="#FDL-MODIFIED" +>Modified Version</A +>, as the + publisher. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>D. </B +> Preserve all the copyright notices of the <A +HREF="#FDL-DOCUMENT" +>Document</A +>. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>E. </B +> Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>F. </B +> Include, immediately after the copyright notices, a + license notice giving the public permission to use the + <A +HREF="#FDL-MODIFIED" +>Modified Version</A +> under + the terms of this License, in the form shown in the + Addendum below. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>G. </B +> Preserve in that license notice the full lists of <A +HREF="#FDL-INVARIANT" +> Invariant Sections</A +> and + required <A +HREF="#FDL-COVER-TEXTS" +>Cover + Texts</A +> given in the <A +HREF="#FDL-DOCUMENT" +>Document's</A +> license notice. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>H. </B +> Include an unaltered copy of this License. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>I. </B +> Preserve the section entitled <SPAN +CLASS="QUOTE" +>"History"</SPAN +>, and + its title, and add to it an item stating at least the + title, year, new authors, and publisher of the <A +HREF="#FDL-MODIFIED" +>Modified Version </A +>as given on + the <A +HREF="#FDL-TITLE-PAGE" +>Title Page</A +>. If + there is no section entitled <SPAN +CLASS="QUOTE" +>"History"</SPAN +> in the + <A +HREF="#FDL-DOCUMENT" +>Document</A +>, create one + stating the title, year, authors, and publisher of the + Document as given on its Title Page, then add an item + describing the Modified Version as stated in the previous + sentence. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>J. </B +> Preserve the network location, if any, given in the <A +HREF="#FDL-DOCUMENT" +>Document</A +> for public access + to a <A +HREF="#FDL-TRANSPARENT" +>Transparent</A +> + copy of the Document, and likewise the network locations + given in the Document for previous versions it was based + on. These may be placed in the <SPAN +CLASS="QUOTE" +>"History"</SPAN +> + section. You may omit a network location for a work that + was published at least four years before the Document + itself, or if the original publisher of the version it + refers to gives permission. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>K. </B +> In any section entitled <SPAN +CLASS="QUOTE" +>"Acknowledgements"</SPAN +> or + <SPAN +CLASS="QUOTE" +>"Dedications"</SPAN +>, preserve the section's title, + and preserve in the section all the substance and tone of + each of the contributor acknowledgements and/or + dedications given therein. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>L. </B +> Preserve all the <A +HREF="#FDL-INVARIANT" +>Invariant + Sections</A +> of the <A +HREF="#FDL-DOCUMENT" +>Document</A +>, unaltered in their + text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>M. </B +> Delete any section entitled + <SPAN +CLASS="QUOTE" +>"Endorsements"</SPAN +>. Such a section may not be + included in the <A +HREF="#FDL-MODIFIED" +>Modified + Version</A +>. + </P +></DIV +></LI +><LI +STYLE="list-style-type: opencircle" +><DIV +CLASS="FORMALPARA" +><P +><B +>N. </B +> Do not retitle any existing section as + <SPAN +CLASS="QUOTE" +>"Endorsements"</SPAN +> or to conflict in title with + any <A +HREF="#FDL-INVARIANT" +>Invariant + Section</A +>. + </P +></DIV +></LI +></UL +><P +> If the <A +HREF="#FDL-MODIFIED" +>Modified Version</A +> + includes new front-matter sections or appendices that qualify as + <A +HREF="#FDL-SECONDARY" +>Secondary Sections</A +> and + contain no material copied from the Document, you may at your + option designate some or all of these sections as invariant. To + do this, add their titles to the list of <A +HREF="#FDL-INVARIANT" +>Invariant Sections</A +> in the + Modified Version's license notice. These titles must be + distinct from any other section titles. + </P +><P +> You may add a section entitled <SPAN +CLASS="QUOTE" +>"Endorsements"</SPAN +>, + provided it contains nothing but endorsements of your <A +HREF="#FDL-MODIFIED" +>Modified Version</A +> by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + </P +><P +> You may add a passage of up to five words as a <A +HREF="#FDL-COVER-TEXTS" +>Front-Cover Text</A +>, and a passage + of up to 25 words as a <A +HREF="#FDL-COVER-TEXTS" +>Back-Cover Text</A +>, to the end of + the list of <A +HREF="#FDL-COVER-TEXTS" +>Cover Texts</A +> + in the <A +HREF="#FDL-MODIFIED" +>Modified Version</A +>. + Only one passage of Front-Cover Text and one of Back-Cover Text + may be added by (or through arrangements made by) any one + entity. If the <A +HREF="#FDL-DOCUMENT" +>Document</A +> + already includes a cover text for the same cover, previously + added by you or by arrangement made by the same entity you are + acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + </P +><P +> The author(s) and publisher(s) of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> do not by this License + give permission to use their names for publicity for or to + assert or imply endorsement of any <A +HREF="#FDL-MODIFIED" +>Modified Version </A +>. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION5" +>C.6. 5. COMBINING DOCUMENTS</A +></H2 +><P +> You may combine the <A +HREF="#FDL-DOCUMENT" +>Document</A +> + with other documents released under this License, under the + terms defined in <A +HREF="#FDL-SECTION4" +>section 4</A +> + above for modified versions, provided that you include in the + combination all of the <A +HREF="#FDL-INVARIANT" +>Invariant + Sections</A +> of all of the original documents, unmodified, + and list them all as Invariant Sections of your combined work in + its license notice. + </P +><P +> The combined work need only contain one copy of this License, + and multiple identical <A +HREF="#FDL-INVARIANT" +>Invariant + Sections</A +> may be replaced with a single copy. If there are + multiple Invariant Sections with the same name but different + contents, make the title of each such section unique by adding + at the end of it, in parentheses, the name of the original + author or publisher of that section if known, or else a unique + number. Make the same adjustment to the section titles in the + list of Invariant Sections in the license notice of the combined + work. + </P +><P +> In the combination, you must combine any sections entitled + <SPAN +CLASS="QUOTE" +>"History"</SPAN +> in the various original documents, + forming one section entitled <SPAN +CLASS="QUOTE" +>"History"</SPAN +>; likewise + combine any sections entitled <SPAN +CLASS="QUOTE" +>"Acknowledgements"</SPAN +>, + and any sections entitled <SPAN +CLASS="QUOTE" +>"Dedications"</SPAN +>. You must + delete all sections entitled <SPAN +CLASS="QUOTE" +>"Endorsements."</SPAN +> + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION6" +>C.7. 6. COLLECTIONS OF DOCUMENTS</A +></H2 +><P +> You may make a collection consisting of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> and other documents + released under this License, and replace the individual copies + of this License in the various documents with a single copy that + is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + </P +><P +> You may extract a single document from such a collection, and + dispbibute it individually under this License, provided you + insert a copy of this License into the extracted document, and + follow this License in all other respects regarding verbatim + copying of that document. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION7" +>C.8. 7. AGGREGATION WITH INDEPENDENT WORKS</A +></H2 +><P +> A compilation of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> or its derivatives with + other separate and independent documents or works, in or on a + volume of a storage or distribution medium, does not as a whole + count as a <A +HREF="#FDL-MODIFIED" +>Modified Version</A +> + of the Document, provided no compilation copyright is claimed + for the compilation. Such a compilation is called an + <SPAN +CLASS="QUOTE" +>"aggregate"</SPAN +>, and this License does not apply to the + other self-contained works thus compiled with the Document , on + account of their being thus compiled, if they are not themselves + derivative works of the Document. If the <A +HREF="#FDL-COVER-TEXTS" +>Cover Text</A +> requirement of <A +HREF="#FDL-SECTION3" +>section 3</A +> is applicable to these + copies of the Document, then if the Document is less than one + quarter of the entire aggregate, the Document's Cover Texts may + be placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION8" +>C.9. 8. TRANSLATION</A +></H2 +><P +> Translation is considered a kind of modification, so you may + distribute translations of the <A +HREF="#FDL-DOCUMENT" +>Document</A +> under the terms of <A +HREF="#FDL-SECTION4" +>section 4</A +>. Replacing <A +HREF="#FDL-INVARIANT" +> Invariant Sections</A +> with + translations requires special permission from their copyright + holders, but you may include translations of some or all + Invariant Sections in addition to the original versions of these + Invariant Sections. You may include a translation of this + License provided that you also include the original English + version of this License. In case of a disagreement between the + translation and the original English version of this License, + the original English version will prevail. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION9" +>C.10. 9. TERMINATION</A +></H2 +><P +> You may not copy, modify, sublicense, or distribute the <A +HREF="#FDL-DOCUMENT" +>Document</A +> except as expressly + provided for under this License. Any other attempt to copy, + modify, sublicense or distribute the Document is void, and will + automatically terminate your rights under this License. However, + parties who have received copies, or rights, from you under this + License will not have their licenses terminated so long as such + parties remain in full compliance. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-SECTION10" +>C.11. 10. FUTURE REVISIONS OF THIS LICENSE</A +></H2 +><P +> The <A +HREF="http://www.gnu.org/fsf/fsf.html" +TARGET="_top" +>Free Software + Foundation</A +> may publish new, revised versions of the GNU + Free Documentation License from time to time. Such new versions + will be similar in spirit to the present version, but may differ + in detail to address new problems or concerns. See <A +HREF="http://www.gnu.org/copyleft" +TARGET="_top" +>http://www.gnu.org/copyleft/</A +>. + </P +><P +> Each version of the License is given a distinguishing version + number. If the <A +HREF="#FDL-DOCUMENT" +>Document</A +> + specifies that a particular numbered version of this License + <SPAN +CLASS="QUOTE" +>"or any later version"</SPAN +> applies to it, you have the + option of following the terms and conditions either of that + specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by + the Free Software Foundation. + </P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="FDL-USING" +>C.12. Addendum</A +></H2 +><P +> To use this License in a document you have written, include a copy of + the License in the document and put the following copyright and + license notices just after the title page: + </P +><A +NAME="AEN11607" +></A +><BLOCKQUOTE +CLASS="BLOCKQUOTE" +><P +> Copyright © YEAR YOUR NAME. + </P +><P +> Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.1 or any later version published by the + Free Software Foundation; with the <A +HREF="#FDL-INVARIANT" +>Invariant Sections</A +> being LIST + THEIR TITLES, with the <A +HREF="#FDL-COVER-TEXTS" +>Front-Cover Texts</A +> being LIST, + and with the <A +HREF="#FDL-COVER-TEXTS" +>Back-Cover + Texts</A +> being LIST. A copy of the license is included in + the section entitled <SPAN +CLASS="QUOTE" +>"GNU Free Documentation + License"</SPAN +>. + </P +></BLOCKQUOTE +><P +> If you have no <A +HREF="#FDL-INVARIANT" +>Invariant + Sections</A +>, write <SPAN +CLASS="QUOTE" +>"with no Invariant Sections"</SPAN +> + instead of saying which ones are invariant. If you have no + <A +HREF="#FDL-COVER-TEXTS" +>Front-Cover Texts</A +>, write + <SPAN +CLASS="QUOTE" +>"no Front-Cover Texts"</SPAN +> instead of + <SPAN +CLASS="QUOTE" +>"Front-Cover Texts being LIST"</SPAN +>; likewise for <A +HREF="#FDL-COVER-TEXTS" +>Back-Cover Texts</A +>. + </P +><P +> If your document contains nontrivial examples of program code, + we recommend releasing these examples in parallel under your + choice of free software license, such as the <A +HREF="http://www.gnu.org/copyleft/gpl.html" +TARGET="_top" +> GNU General Public + License</A +>, to permit their use in free software. + </P +></DIV +></DIV +><A +NAME="AEN11623" +></A +><HR><H1 +><A +NAME="AEN11623" +></A +>Bibliography</H1 +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="EIA608" +></A +><P +>[EIA608] Electronic Industries Alliance (<A +HREF="http://www.eia.org" +TARGET="_top" +>http://www.eia.org</A +>), <I +>EIA 608 "Recommended Practice for Line 21 Data +Service"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="ITU470" +></A +><P +>[ITU470] International Telecommunication Union (<A +HREF="http://www.itu.ch" +TARGET="_top" +>http://www.itu.ch</A +>), <I +>ITU-R Recommendation BT.470-6 "Conventional Television +Systems"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="ITU601" +></A +><P +>[ITU601] International Telecommunication Union (<A +HREF="http://www.itu.ch" +TARGET="_top" +>http://www.itu.ch</A +>), <I +>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters +of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect +Ratios"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="ITU709" +></A +><P +>[ITU709] International Telecommunication Union (<A +HREF="http://www.itu.ch" +TARGET="_top" +>http://www.itu.ch</A +>), <I +>ITU-R Recommendation BT.709-5 "Parameter values for the +HDTV standards for production and international programme +exchange"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="JFIF" +></A +><P +>[JFIF] Independent JPEG Group (<A +HREF="http://www.ijg.org" +TARGET="_top" +>http://www.ijg.org</A +>), <I +>JPEG File Interchange Format</I +><I +>: </I +><I +>Version 1.02</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="SMPTE12M" +></A +><P +>[SMPTE12M] Society of Motion Picture and Television Engineers +(<A +HREF="http://www.smpte.org" +TARGET="_top" +>http://www.smpte.org</A +>), <I +>SMPTE 12M-1999 "Television, Audio and Film - Time and +Control Code"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="SMPTE170M" +></A +><P +>[SMPTE170M] Society of Motion Picture and Television Engineers +(<A +HREF="http://www.smpte.org" +TARGET="_top" +>http://www.smpte.org</A +>), <I +>SMPTE 170M-1999 "Television - Composite Analog Video +Signal - NTSC for Studio Applications"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="SMPTE240M" +></A +><P +>[SMPTE240M] Society of Motion Picture and Television Engineers +(<A +HREF="http://www.smpte.org" +TARGET="_top" +>http://www.smpte.org</A +>), <I +>SMPTE 240M-1999 "Television - Signal Parameters - +1125-Line High-Definition Production"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="TELETEXT" +></A +><P +>[TELETEXT] European Telecommunication Standards Institute +(<A +HREF="http://www.etsi.org" +TARGET="_top" +>http://www.etsi.org</A +>), <I +>ETS 300 706 "Enhanced Teletext specification"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="V4L" +></A +><P +>[V4L] <SPAN +CLASS="AUTHOR" +>Alan Cox</SPAN +>, <I +>Video4Linux API Specification</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +><DIV +CLASS="ABSTRACT" +><P +>This file is part of the Linux kernel sources under +<TT +CLASS="FILENAME" +>Documentation/video4linux</TT +>.</P +></DIV +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="V4LPROG" +></A +><P +>[V4LPROG] <SPAN +CLASS="AUTHOR" +>Alan Cox</SPAN +>, <I +>Video4Linux Programming (a.k.a. The Video4Linux +Book)</I +>, 2000.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +><DIV +CLASS="ABSTRACT" +><P +>About V4L <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>driver</I +></SPAN +> programming. This +book is part of the Linux kernel DocBook documentation, for example at +<A +HREF="http://kernelnewbies.org/documents/" +TARGET="_top" +>http://kernelnewbies.org/documents/</A +>. SGML sources are included +in the kernel sources.</P +></DIV +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="VPS" +></A +><P +>[VPS] European Telecommunication Standards Institute +(<A +HREF="http://www.etsi.org" +TARGET="_top" +>http://www.etsi.org</A +>), <I +>ETS 300 231 "Specification of the domestic video +Programme Delivery Control system (PDC)"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +><DIV +CLASS="BIBLIOENTRY" +><A +NAME="WSS" +></A +><P +>[WSS] International Telecommunication Union (<A +HREF="http://www.itu.ch" +TARGET="_top" +>http://www.itu.ch</A +>), European +Telecommunication Standards Institute (<A +HREF="http://www.etsi.org" +TARGET="_top" +>http://www.etsi.org</A +>), <I +>ITU-R Recommendation BT.1119, EN 300 294 "625-line +television Wide Screen Signalling (WSS)"</I +>.</P +><DIV +CLASS="BIBLIOENTRYBLOCK" +STYLE="margin-left: 0.5in" +></DIV +></DIV +></DIV +><H3 +CLASS="FOOTNOTES" +>Notes</H3 +><TABLE +BORDER="0" +CLASS="FOOTNOTES" +WIDTH="100%" +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN104" +HREF="#AEN104" +><SPAN +CLASS="footnote" +>[1]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Access permissions are associated with character +device special files, we must ensure device numbers cannot change with +load order. To this end minor numbers are no longer automatically assigned +by the "videodev" module as in V4L but requested by the driver. The defaults +will suffice for most people, unless two drivers are used which compete for +the same minor numbers.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN107" +HREF="#AEN107" +><SPAN +CLASS="footnote" +>[2]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>In earlier versions of the V4L2 API the module options +where named after the device special file with a "unit_" prefix, expressing +the minor number itself, not an offset. Rationale for this change is unknown. +Lastly the naming and semantics are just a convention among driver writers, +the point to note is that minor numbers are not supposed to be hardcoded +into drivers.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN135" +HREF="#AEN135" +><SPAN +CLASS="footnote" +>[3]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Given a device file name one cannot reliable find +related devices. For once names are arbitrary, they can be chosen +freely by the system administrator. Also when there are multiple +devices and only some support VBI capturing, say, +<TT +CLASS="FILENAME" +>/dev/video2</TT +> is not necessarily related to +<TT +CLASS="FILENAME" +>/dev/vbi2</TT +>. We already noted finding devices by +name or minor number is unreliable, accordingly useful is the ioctl +offered by V4L to query the minor numbers of related devices.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN166" +HREF="#AEN166" +><SPAN +CLASS="footnote" +>[4]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Drivers could recognize the +<CODE +CLASS="CONSTANT" +>O_EXCL</CODE +> open flag. Presently this is not required, +so application cannot know if it really works.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN245" +HREF="#AEN245" +><SPAN +CLASS="footnote" +>[5]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Actually struct <A +HREF="#V4L2-AUDIO" +>v4l2_audio</A +> ought to have a +<CODE +CLASS="STRUCTFIELD" +>tuner</CODE +> field like struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +>, not only +making the API more consistent but also permitting radio devices with +multiple tuners.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN363" +HREF="#AEN363" +><SPAN +CLASS="footnote" +>[6]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Some users are already confused by technical terms PAL, +NTSC and SECAM. There is no point asking them to distinguish between +B, G, D, or K when the software or hardware can do that +automatically.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN375" +HREF="#AEN375" +><SPAN +CLASS="footnote" +>[7]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>An alternative to the current scheme is to use pointers +to indices as arguments of <CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +> and +<CODE +CLASS="CONSTANT" +>VIDIOC_S_STD</CODE +>, the struct <A +HREF="#V4L2-INPUT" +>v4l2_input</A +> and +struct <A +HREF="#V4L2-OUTPUT" +>v4l2_output</A +> <CODE +CLASS="STRUCTFIELD" +>std</CODE +> field would be a set of +indices like <CODE +CLASS="STRUCTFIELD" +>audioset</CODE +>.</P +><P +>Indices are consistent with the rest of the API +and identify the standard unambiguously. In the present scheme of +things an enumerated standard is looked up by <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +>. Now the +standards supported by the inputs of a device can overlap. Just +assume the tuner and composite input in the example above both +exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests +a choice which does not exist. We cannot merge or omit sets, because +applications would be unable to find the standards reported by +<CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +>. That leaves separate enumerations +for each input. Also selecting a standard by <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +> can be +ambiguous. Advantage of this method is that applications need not +identify the standard indirectly, after enumerating.</P +><P +>So in +summary, the lookup itself is unavoidable. The difference is only +whether the lookup is necessary to find an enumerated standard or to +switch to a standard by <A +HREF="#V4L2-STD-ID" +>v4l2_std_id</A +>.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN407" +HREF="#AEN407" +><SPAN +CLASS="footnote" +>[8]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>See <A +HREF="#BUFFER" +>Section 3.5</A +> for a rationale. Probably +even USB cameras follow some well known video standard. It might have +been better to explicitly indicate elsewhere if a device cannot live +up to normal expectations, instead of this exception.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN451" +HREF="#AEN451" +><SPAN +CLASS="footnote" +>[9]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>It will be more convenient for applications if drivers +make use of the <CODE +CLASS="CONSTANT" +>V4L2_CTRL_FLAG_DISABLED</CODE +> flag, but +that was never required.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN454" +HREF="#AEN454" +><SPAN +CLASS="footnote" +>[10]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Applications could call an ioctl to request events. +After another process called <A +HREF="#VIDIOC-G-CTRL" +><CODE +CLASS="CONSTANT" +>VIDIOC_S_CTRL</CODE +></A +> or another ioctl changing +shared properties the <CODE +CLASS="FUNCTION" +>select()</CODE +> function would +indicate readability until any ioctl (querying the properties) is +called.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN692" +HREF="#AEN692" +><SPAN +CLASS="footnote" +>[11]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Enumerating formats an application has no a-priori +knowledge of (otherwise it could explicitely ask for them and need not +enumerate) seems useless, but there are applications serving as proxy +between drivers and the actual video applications for which this is +useful.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN714" +HREF="#AEN714" +><SPAN +CLASS="footnote" +>[12]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>It may be desirable to refer to the cropping area in +terms of sampling frequency and scanning system lines, but in order to +support a wide range of hardware we better make as few assumptions as +possible.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3273" +HREF="#AEN3273" +><SPAN +CLASS="footnote" +>[13]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>It would be desirable if applications could depend on +drivers supporting all I/O interfaces, but as much as the complex +memory mapping I/O can be inadequate for some devices we have no +reason to require this interface, which is most useful for simple +applications capturing still images.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3279" +HREF="#AEN3279" +><SPAN +CLASS="footnote" +>[14]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>At the driver level <CODE +CLASS="FUNCTION" +>select()</CODE +> and +<CODE +CLASS="FUNCTION" +>poll()</CODE +> are the same, and +<CODE +CLASS="FUNCTION" +>select()</CODE +> is too important to be optional.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3296" +HREF="#AEN3296" +><SPAN +CLASS="footnote" +>[15]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>One could use one file descriptor and set the buffer +type field accordingly when calling <A +HREF="#VIDIOC-QBUF" +><CODE +CLASS="CONSTANT" +>VIDIOC_QBUF</CODE +></A +> etc., but it makes +the <CODE +CLASS="FUNCTION" +>select()</CODE +> function ambiguous. We also like the +clean approach of one file descriptor per logical stream. Video +overlay for example is also a logical stream, although the CPU is not +needed for continuous operation.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3329" +HREF="#AEN3329" +><SPAN +CLASS="footnote" +>[16]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Random enqueue order permits applications processing +images out of order (such as video codecs) to return buffers earlier, +reducing the probability of data loss. Random fill order allows +drivers to reuse buffers on a LIFO-basis, taking advantage of caches +holding scatter-gather lists and the like.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3371" +HREF="#AEN3371" +><SPAN +CLASS="footnote" +>[17]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>At the driver level <CODE +CLASS="FUNCTION" +>select()</CODE +> and +<CODE +CLASS="FUNCTION" +>poll()</CODE +> are the same, and +<CODE +CLASS="FUNCTION" +>select()</CODE +> is too important to be optional. The +rest should be evident.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3402" +HREF="#AEN3402" +><SPAN +CLASS="footnote" +>[18]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>We expect that frequently used buffers are typically not +swapped out. Anyway, the process of swapping, locking or generating +scatter-gather lists may be time consuming. The delay can be masked by +the depth of the incoming buffer queue, and perhaps by maintaining +caches assuming a buffer will be soon enqueued again. On the other +hand, to optimize memory usage drivers can limit the number of buffers +locked in advance and recycle the most recently used buffers first. Of +course, the pages of empty buffers in the incoming queue need not be +saved to disk. Output buffers must be saved on the incoming and +outgoing queue because an application may share them with other +processes.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3438" +HREF="#AEN3438" +><SPAN +CLASS="footnote" +>[19]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>At the driver level <CODE +CLASS="FUNCTION" +>select()</CODE +> and +<CODE +CLASS="FUNCTION" +>poll()</CODE +> are the same, and +<CODE +CLASS="FUNCTION" +>select()</CODE +> is too important to be optional. The +rest should be evident.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN3460" +HREF="#AEN3460" +><SPAN +CLASS="footnote" +>[20]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>Since no other Linux multimedia +API supports unadjusted time it would be foolish to introduce here. We +must use a universally supported clock to synchronize different media, +hence time of day.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN4042" +HREF="#AEN4042" +><SPAN +CLASS="footnote" +>[21]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>A common application of two file descriptors is the +XFree86 <A +HREF="#XVIDEO" +>Xv/V4L</A +> interface driver and +a V4L2 application. While the X server controls video overlay, the +application can take advantage of memory mapping and DMA.</P +><P +>In the opinion of the designers of this API, no driver +writer taking the efforts to support simultaneous capturing and +overlay will restrict this ability by requiring a single file +descriptor, as in V4L and earlier versions of V4L2. Making this +optional means applications depending on two file descriptors need +backup routines to be compatible with all drivers, which is +considerable more work than using two fds in applications which do +not. Also two fd's fit the general concept of one file descriptor for +each logical stream. Hence as a complexity trade-off drivers +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>must</I +></SPAN +> support two file descriptors and +<SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>may</I +></SPAN +> support single fd operation.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN4216" +HREF="#AEN4216" +><SPAN +CLASS="footnote" +>[22]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>The X Window system defines "regions" which are +vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 - +x1 and height = y2 - y1, so one cannot pass X11 clip lists +directly.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN4369" +HREF="#AEN4369" +><SPAN +CLASS="footnote" +>[23]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>ASK: Amplitude-Shift Keying. A high signal +level represents a '1' bit, a low level a '0' bit.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN5736" +HREF="#AEN5736" +><SPAN +CLASS="footnote" +>[24]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>The supported standards may overlap and we need an +unambiguous set to find the current standard returned by +<CODE +CLASS="CONSTANT" +>VIDIOC_G_STD</CODE +>.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN8815" +HREF="#AEN8815" +><SPAN +CLASS="footnote" +>[25]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +><CODE +CLASS="CONSTANT" +>V4L2_CTRL_FLAG_DISABLED</CODE +> was intended +for two purposes: Drivers can skip predefined controls not supported +by the hardware (although returning EINVAL would do as well), or +disable predefined and custom controls after hardware detection +without the trouble of reordering control arrays and indices.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN9113" +HREF="#AEN9113" +><SPAN +CLASS="footnote" +>[26]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>For example video output requires at least two buffers, +one displayed and one filled by the application.</P +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="5%" +><A +NAME="FTN.AEN11222" +HREF="#AEN11222" +><SPAN +CLASS="footnote" +>[27]</SPAN +></A +></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +WIDTH="95%" +><P +>This is not implemented in XFree86.</P +></TD +></TR +></TABLE +></BODY +></HTML +>
\ No newline at end of file diff --git a/v4l/ChangeLog b/v4l/ChangeLog index 96d7f5ea0..d90d195a2 100644 --- a/v4l/ChangeLog +++ b/v4l/ChangeLog @@ -1,3 +1,10 @@ +2005-06-06 05:05 mchehab + * doc/V4L2_API.html: + - Included V4L2 API from http://v4l2spec.bytesex.org + + *doc/V4L1_API.html + - Include Obsoleted V4L API from doc on kernel-2.6.12-rc5-mm2 + 2005-06-06 04:52 mchehab * tuner-core.c: - temporary debug log removed. @@ -1179,7 +1186,7 @@ saa7134-reg.h, saa7134-ts.c, saa7134-tvaudio.c, saa7134-vbi.c, saa7134-video.c, saa7134.h, video-buf.c, video-buf.h: - - added a bunch of $Id: ChangeLog,v 1.23 2005/06/06 04:59:29 mchehab Exp $ tags. + - added a bunch of $Id: ChangeLog,v 1.24 2005/06/06 05:06:27 mchehab Exp $ tags. 2004-09-15 17:35 kraxel |