| 1 |
1275 |
phoenix |
<HTML><HEAD>
|
| 2 |
|
|
<TITLE>Video4Linux Kernel API Reference v0.1:19990430</TITLE>
|
| 3 |
|
|
</HEAD>
|
| 4 |
|
|
<! Revision History: >
|
| 5 |
|
|
<! 4/30/1999 - Fred Gleason (fredg@wava.com)>
|
| 6 |
|
|
<! Documented extensions for the Radio Data System (RDS) extensions >
|
| 7 |
|
|
<BODY bgcolor="#ffffff">
|
| 8 |
|
|
<H3>Devices</H3>
|
| 9 |
|
|
Video4Linux provides the following sets of device files. These live on the
|
| 10 |
|
|
character device formerly known as "/dev/bttv". /dev/bttv should be a
|
| 11 |
|
|
symlink to /dev/video0 for most people.
|
| 12 |
|
|
<P>
|
| 13 |
|
|
<TABLE>
|
| 14 |
|
|
<TR><TH>Device Name</TH><TH>Minor Range</TH><TH>Function</TH>
|
| 15 |
|
|
<TR><TD>/dev/video</TD><TD>0-63</TD><TD>Video Capture Interface</TD>
|
| 16 |
|
|
<TR><TD>/dev/radio</TD><TD>64-127</TD><TD>AM/FM Radio Devices</TD>
|
| 17 |
|
|
<TR><TD>/dev/vtx</TD><TD>192-223</TD><TD>Teletext Interface Chips</TD>
|
| 18 |
|
|
<TR><TD>/dev/vbi</TD><TD>224-239</TD><TD>Raw VBI Data (Intercast/teletext)</TD>
|
| 19 |
|
|
</TABLE>
|
| 20 |
|
|
<P>
|
| 21 |
|
|
Video4Linux programs open and scan the devices to find what they are looking
|
| 22 |
|
|
for. Capability queries define what each interface supports. The
|
| 23 |
|
|
described API is only defined for video capture cards. The relevant subset
|
| 24 |
|
|
applies to radio cards. Teletext interfaces talk the existing VTX API.
|
| 25 |
|
|
<P>
|
| 26 |
|
|
<H3>Capability Query Ioctl</H3>
|
| 27 |
|
|
The <B>VIDIOCGCAP</B> ioctl call is used to obtain the capability
|
| 28 |
|
|
information for a video device. The <b>struct video_capability</b> object
|
| 29 |
|
|
passed to the ioctl is completed and returned. It contains the following
|
| 30 |
|
|
information
|
| 31 |
|
|
<P>
|
| 32 |
|
|
<TABLE>
|
| 33 |
|
|
<TR><TD><b>name[32]</b><TD>Canonical name for this interface</TD>
|
| 34 |
|
|
<TR><TD><b>type</b><TD>Type of interface</TD>
|
| 35 |
|
|
<TR><TD><b>channels</b><TD>Number of radio/tv channels if appropriate</TD>
|
| 36 |
|
|
<TR><TD><b>audios</b><TD>Number of audio devices if appropriate</TD>
|
| 37 |
|
|
<TR><TD><b>maxwidth</b><TD>Maximum capture width in pixels</TD>
|
| 38 |
|
|
<TR><TD><b>maxheight</b><TD>Maximum capture height in pixels</TD>
|
| 39 |
|
|
<TR><TD><b>minwidth</b><TD>Minimum capture width in pixels</TD>
|
| 40 |
|
|
<TR><TD><b>minheight</b><TD>Minimum capture height in pixels</TD>
|
| 41 |
|
|
</TABLE>
|
| 42 |
|
|
<P>
|
| 43 |
|
|
The type field lists the capability flags for the device. These are
|
| 44 |
|
|
as follows
|
| 45 |
|
|
<P>
|
| 46 |
|
|
<TABLE>
|
| 47 |
|
|
<TR><TH>Name</TH><TH>Description</TH>
|
| 48 |
|
|
<TR><TD><b>VID_TYPE_CAPTURE</b><TD>Can capture to memory</TD>
|
| 49 |
|
|
<TR><TD><b>VID_TYPE_TUNER</b><TD>Has a tuner of some form</TD>
|
| 50 |
|
|
<TR><TD><b>VID_TYPE_TELETEXT</b><TD>Has teletext capability</TD>
|
| 51 |
|
|
<TR><TD><b>VID_TYPE_OVERLAY</b><TD>Can overlay its image onto the frame buffer</TD>
|
| 52 |
|
|
<TR><TD><b>VID_TYPE_CHROMAKEY</b><TD>Overlay is Chromakeyed</TD>
|
| 53 |
|
|
<TR><TD><b>VID_TYPE_CLIPPING</b><TD>Overlay clipping is supported</TD>
|
| 54 |
|
|
<TR><TD><b>VID_TYPE_FRAMERAM</b><TD>Overlay overwrites frame buffer memory</TD>
|
| 55 |
|
|
<TR><TD><b>VID_TYPE_SCALES</b><TD>The hardware supports image scaling</TD>
|
| 56 |
|
|
<TR><TD><b>VID_TYPE_MONOCHROME</b><TD>Image capture is grey scale only</TD>
|
| 57 |
|
|
<TR><TD><b>VID_TYPE_SUBCAPTURE</b><TD>Capture can be of only part of the image</TD>
|
| 58 |
|
|
</TABLE>
|
| 59 |
|
|
<P>
|
| 60 |
|
|
The minimum and maximum sizes listed for a capture device do not imply all
|
| 61 |
|
|
that all height/width ratios or sizes within the range are possible. A
|
| 62 |
|
|
request to set a size will be honoured by the largest available capture
|
| 63 |
|
|
size whose capture is no large than the requested rectangle in either
|
| 64 |
|
|
direction. For example the quickcam has 3 fixed settings.
|
| 65 |
|
|
<P>
|
| 66 |
|
|
<H3>Frame Buffer</H3>
|
| 67 |
|
|
Capture cards that drop data directly onto the frame buffer must be told the
|
| 68 |
|
|
base address of the frame buffer, its size and organisation. This is a
|
| 69 |
|
|
privileged ioctl and one that eventually X itself should set.
|
| 70 |
|
|
<P>
|
| 71 |
|
|
The <b>VIDIOCSFBUF</b> ioctl sets the frame buffer parameters for a capture
|
| 72 |
|
|
card. If the card does not do direct writes to the frame buffer then this
|
| 73 |
|
|
ioctl will be unsupported. The <b>VIDIOCGFBUF</b> ioctl returns the
|
| 74 |
|
|
currently used parameters. The structure used in both cases is a
|
| 75 |
|
|
<b>struct video_buffer</b>.
|
| 76 |
|
|
<P>
|
| 77 |
|
|
<TABLE>
|
| 78 |
|
|
<TR><TD><b>void *base</b></TD><TD>Base physical address of the buffer</TD>
|
| 79 |
|
|
<TR><TD><b>int height</b></TD><TD>Height of the frame buffer</TD>
|
| 80 |
|
|
<TR><TD><b>int width</b></TD><TD>Width of the frame buffer</TD>
|
| 81 |
|
|
<TR><TD><b>int depth</b></TD><TD>Depth of the frame buffer</TD>
|
| 82 |
|
|
<TR><TD><b>int bytesperline</b></TD><TD>Number of bytes of memory between the start of two adjacent lines</TD>
|
| 83 |
|
|
</TABLE>
|
| 84 |
|
|
<P>
|
| 85 |
|
|
Note that these values reflect the physical layout of the frame buffer.
|
| 86 |
|
|
The visible area may be smaller. In fact under XFree86 this is commonly the
|
| 87 |
|
|
case. XFree86 DGA can provide the parameters required to set up this ioctl.
|
| 88 |
|
|
Setting the base address to NULL indicates there is no physical frame buffer
|
| 89 |
|
|
access.
|
| 90 |
|
|
<P>
|
| 91 |
|
|
<H3>Capture Windows</H3>
|
| 92 |
|
|
The capture area is described by a <b>struct video_window</b>. This defines
|
| 93 |
|
|
a capture area and the clipping information if relevant. The
|
| 94 |
|
|
<b>VIDIOCGWIN</b> ioctl recovers the current settings and the
|
| 95 |
|
|
<b>VIDIOCSWIN</b> sets new values. A successful call to <b>VIDIOCSWIN</b>
|
| 96 |
|
|
indicates that a suitable set of parameters have been chosen. They do not
|
| 97 |
|
|
indicate that exactly what was requested was granted. The program should
|
| 98 |
|
|
call <b>VIDIOCGWIN</b> to check if the nearest match was suitable. The
|
| 99 |
|
|
<b>struct video_window</b> contains the following fields.
|
| 100 |
|
|
<P>
|
| 101 |
|
|
<TABLE>
|
| 102 |
|
|
<TR><TD><b>x</b><TD>The X co-ordinate specified in X windows format.</TD>
|
| 103 |
|
|
<TR><TD><b>y</b><TD>The Y co-ordinate specified in X windows format.</TD>
|
| 104 |
|
|
<TR><TD><b>width</b><TD>The width of the image capture.</TD>
|
| 105 |
|
|
<TR><TD><b>height</b><TD>The height of the image capture.</TD>
|
| 106 |
|
|
<TR><TD><b>chromakey</b><TD>A host order RGB32 value for the chroma key.</TD>
|
| 107 |
|
|
<TR><TD><b>flags</b><TD>Additional capture flags.</TD>
|
| 108 |
|
|
<TR><TD><b>clips</b><TD>A list of clipping rectangles. <em>(Set only)</em></TD>
|
| 109 |
|
|
<TR><TD><b>clipcount</b><TD>The number of clipping rectangles. <em>(Set only)</em></TD>
|
| 110 |
|
|
</TABLE>
|
| 111 |
|
|
<P>
|
| 112 |
|
|
Clipping rectangles are passed as an array. Each clip consists of the following
|
| 113 |
|
|
fields available to the user.
|
| 114 |
|
|
<P>
|
| 115 |
|
|
<TABLE>
|
| 116 |
|
|
<TR><TD><b>x</b></TD><TD>X co-ordinate of rectangle to skip</TD>
|
| 117 |
|
|
<TR><TD><b>y</b></TD><TD>Y co-ordinate of rectangle to skip</TD>
|
| 118 |
|
|
<TR><TD><b>width</b></TD><TD>Width of rectangle to skip</TD>
|
| 119 |
|
|
<TR><TD><b>height</b></TD><TD>Height of rectangle to skip</TD>
|
| 120 |
|
|
</TABLE>
|
| 121 |
|
|
<P>
|
| 122 |
|
|
Merely setting the window does not enable capturing. Overlay capturing
|
| 123 |
|
|
(i.e. PCI-PCI transfer to the frame buffer of the video card)
|
| 124 |
|
|
is activated by passing the <b>VIDIOCCAPTURE</b> ioctl a value of 1, and
|
| 125 |
|
|
disabled by passing it a value of 0.
|
| 126 |
|
|
<P>
|
| 127 |
|
|
Some capture devices can capture a subfield of the image they actually see.
|
| 128 |
|
|
This is indicated when VIDEO_TYPE_SUBCAPTURE is defined.
|
| 129 |
|
|
The video_capture describes the time and special subfields to capture.
|
| 130 |
|
|
The video_capture structure contains the following fields.
|
| 131 |
|
|
<P>
|
| 132 |
|
|
<TABLE>
|
| 133 |
|
|
<TR><TD><b>x</b></TD><TD>X co-ordinate of source rectangle to grab</TD>
|
| 134 |
|
|
<TR><TD><b>y</b></TD><TD>Y co-ordinate of source rectangle to grab</TD>
|
| 135 |
|
|
<TR><TD><b>width</b></TD><TD>Width of source rectangle to grab</TD>
|
| 136 |
|
|
<TR><TD><b>height</b></TD><TD>Height of source rectangle to grab</TD>
|
| 137 |
|
|
<TR><TD><b>decimation</b></TD><TD>Decimation to apply</TD>
|
| 138 |
|
|
<TR><TD><b>flags</b></TD><TD>Flag settings for grabbing</TD>
|
| 139 |
|
|
</TABLE>
|
| 140 |
|
|
The available flags are
|
| 141 |
|
|
<P>
|
| 142 |
|
|
<TABLE>
|
| 143 |
|
|
<TR><TH>Name</TH><TH>Description</TH>
|
| 144 |
|
|
<TR><TD><b>VIDEO_CAPTURE_ODD</b><TD>Capture only odd frames</TD>
|
| 145 |
|
|
<TR><TD><b>VIDEO_CAPTURE_EVEN</b><TD>Capture only even frames</TD>
|
| 146 |
|
|
</TABLE>
|
| 147 |
|
|
<P>
|
| 148 |
|
|
<H3>Video Sources</H3>
|
| 149 |
|
|
Each video4linux video or audio device captures from one or more
|
| 150 |
|
|
source <b>channels</b>. Each channel can be queries with the
|
| 151 |
|
|
<b>VDIOCGCHAN</b> ioctl call. Before invoking this function the caller
|
| 152 |
|
|
must set the channel field to the channel that is being queried. On return
|
| 153 |
|
|
the <b>struct video_channel</b> is filled in with information about the
|
| 154 |
|
|
nature of the channel itself.
|
| 155 |
|
|
<P>
|
| 156 |
|
|
The <b>VIDIOCSCHAN</b> ioctl takes an integer argument and switches the
|
| 157 |
|
|
capture to this input. It is not defined whether parameters such as colour
|
| 158 |
|
|
settings or tuning are maintained across a channel switch. The caller should
|
| 159 |
|
|
maintain settings as desired for each channel. (This is reasonable as
|
| 160 |
|
|
different video inputs may have different properties).
|
| 161 |
|
|
<P>
|
| 162 |
|
|
The <b>struct video_channel</b> consists of the following
|
| 163 |
|
|
<P>
|
| 164 |
|
|
<TABLE>
|
| 165 |
|
|
<TR><TD><b>channel</b></TD><TD>The channel number</TD>
|
| 166 |
|
|
<TR><TD><b>name</b></TD><TD>The input name - preferably reflecting the label
|
| 167 |
|
|
on the card input itself</TD>
|
| 168 |
|
|
<TR><TD><b>tuners</b></TD><TD>Number of tuners for this input</TD>
|
| 169 |
|
|
<TR><TD><b>flags</b></TD><TD>Properties the tuner has</TD>
|
| 170 |
|
|
<TR><TD><b>type</b></TD><TD>Input type (if known)</TD>
|
| 171 |
|
|
<TR><TD><b>norm</b><TD>The norm for this channel</TD>
|
| 172 |
|
|
</TABLE>
|
| 173 |
|
|
<P>
|
| 174 |
|
|
The flags defined are
|
| 175 |
|
|
<P>
|
| 176 |
|
|
<TABLE>
|
| 177 |
|
|
<TR><TD><b>VIDEO_VC_TUNER</b><TD>Channel has tuners.</TD>
|
| 178 |
|
|
<TR><TD><b>VIDEO_VC_AUDIO</b><TD>Channel has audio.</TD>
|
| 179 |
|
|
<TR><TD><b>VIDEO_VC_NORM</b><TD>Channel has norm setting.</TD>
|
| 180 |
|
|
</TABLE>
|
| 181 |
|
|
<P>
|
| 182 |
|
|
The types defined are
|
| 183 |
|
|
<P>
|
| 184 |
|
|
<TABLE>
|
| 185 |
|
|
<TR><TD><b>VIDEO_TYPE_TV</b><TD>The input is a TV input.</TD>
|
| 186 |
|
|
<TR><TD><b>VIDEO_TYPE_CAMERA</b><TD>The input is a camera.</TD>
|
| 187 |
|
|
</TABLE>
|
| 188 |
|
|
<P>
|
| 189 |
|
|
<H3>Image Properties</H3>
|
| 190 |
|
|
The image properties of the picture can be queried with the <b>VIDIOCGPICT</b>
|
| 191 |
|
|
ioctl which fills in a <b>struct video_picture</b>. The <b>VIDIOCSPICT</b>
|
| 192 |
|
|
ioctl allows values to be changed. All values except for the palette type
|
| 193 |
|
|
are scaled between 0-65535.
|
| 194 |
|
|
<P>
|
| 195 |
|
|
The <b>struct video_picture</b> consists of the following fields
|
| 196 |
|
|
<P>
|
| 197 |
|
|
<TABLE>
|
| 198 |
|
|
<TR><TD><b>brightness</b><TD>Picture brightness</TD>
|
| 199 |
|
|
<TR><TD><b>hue</b><TD>Picture hue (colour only)</TD>
|
| 200 |
|
|
<TR><TD><b>colour</b><TD>Picture colour (colour only)</TD>
|
| 201 |
|
|
<TR><TD><b>contrast</b><TD>Picture contrast</TD>
|
| 202 |
|
|
<TR><TD><b>whiteness</b><TD>The whiteness (greyscale only)</TD>
|
| 203 |
|
|
<TR><TD><b>depth</b><TD>The capture depth (may need to match the frame buffer depth)</TD>
|
| 204 |
|
|
<TR><TD><b>palette</b><TD>Reports the palette that should be used for this image</TD>
|
| 205 |
|
|
</TABLE>
|
| 206 |
|
|
<P>
|
| 207 |
|
|
The following palettes are defined
|
| 208 |
|
|
<P>
|
| 209 |
|
|
<TABLE>
|
| 210 |
|
|
<TR><TD><b>VIDEO_PALETTE_GREY</b><TD>Linear intensity grey scale (255 is brightest).</TD>
|
| 211 |
|
|
<TR><TD><b>VIDEO_PALETTE_HI240</b><TD>The BT848 8bit colour cube.</TD>
|
| 212 |
|
|
<TR><TD><b>VIDEO_PALETTE_RGB565</b><TD>RGB565 packed into 16 bit words.</TD>
|
| 213 |
|
|
<TR><TD><b>VIDEO_PALETTE_RGB555</b><TD>RGV555 packed into 16 bit words, top bit undefined.</TD>
|
| 214 |
|
|
<TR><TD><b>VIDEO_PALETTE_RGB24</b><TD>RGB888 packed into 24bit words.</TD>
|
| 215 |
|
|
<TR><TD><b>VIDEO_PALETTE_RGB32</b><TD>RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined.</TD>
|
| 216 |
|
|
<TR><TD><b>VIDEO_PALETTE_YUV422</b><TD>Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V</TD>
|
| 217 |
|
|
<TR><TD><b>VIDEO_PALETTE_YUYV</b><TD>Describe me</TD>
|
| 218 |
|
|
<TR><TD><b>VIDEO_PALETTE_UYVY</b><TD>Describe me</TD>
|
| 219 |
|
|
<TR><TD><b>VIDEO_PALETTE_YUV420</b><TD>YUV420 capture</TD>
|
| 220 |
|
|
<TR><TD><b>VIDEO_PALETTE_YUV411</b><TD>YUV411 capture</TD>
|
| 221 |
|
|
<TR><TD><b>VIDEO_PALETTE_RAW</b><TD>RAW capture (BT848)</TD>
|
| 222 |
|
|
<TR><TD><b>VIDEO_PALETTE_YUV422P</b><TD>YUV 4:2:2 Planar</TD>
|
| 223 |
|
|
<TR><TD><b>VIDEO_PALETTE_YUV411P</b><TD>YUV 4:1:1 Planar</TD>
|
| 224 |
|
|
</TABLE>
|
| 225 |
|
|
<P>
|
| 226 |
|
|
<H3>Tuning</H3>
|
| 227 |
|
|
Each video input channel can have one or more tuners associated with it. Many
|
| 228 |
|
|
devices will not have tuners. TV cards and radio cards will have one or more
|
| 229 |
|
|
tuners attached.
|
| 230 |
|
|
<P>
|
| 231 |
|
|
Tuners are described by a <b>struct video_tuner</b> which can be obtained by
|
| 232 |
|
|
the <b>VIDIOCGTUNER</b> ioctl. Fill in the tuner number in the structure
|
| 233 |
|
|
then pass the structure to the ioctl to have the data filled in. The
|
| 234 |
|
|
tuner can be switched using <b>VIDIOCSTUNER</b> which takes an integer argument
|
| 235 |
|
|
giving the tuner to use. A struct tuner has the following fields
|
| 236 |
|
|
<P>
|
| 237 |
|
|
<TABLE>
|
| 238 |
|
|
<TR><TD><b>tuner</b><TD>Number of the tuner</TD>
|
| 239 |
|
|
<TR><TD><b>name</b><TD>Canonical name for this tuner (eg FM/AM/TV)</TD>
|
| 240 |
|
|
<TR><TD><b>rangelow</b><TD>Lowest tunable frequency</TD>
|
| 241 |
|
|
<TR><TD><b>rangehigh</b><TD>Highest tunable frequency</TD>
|
| 242 |
|
|
<TR><TD><b>flags</b><TD>Flags describing the tuner</TD>
|
| 243 |
|
|
<TR><TD><b>mode</b><TD>The video signal mode if relevant</TD>
|
| 244 |
|
|
<TR><TD><b>signal</b><TD>Signal strength if known - between 0-65535</TD>
|
| 245 |
|
|
</TABLE>
|
| 246 |
|
|
<P>
|
| 247 |
|
|
The following flags exist
|
| 248 |
|
|
<P>
|
| 249 |
|
|
<TABLE>
|
| 250 |
|
|
<TR><TD><b>VIDEO_TUNER_PAL</b><TD>PAL tuning is supported</TD>
|
| 251 |
|
|
<TR><TD><b>VIDEO_TUNER_NTSC</b><TD>NTSC tuning is supported</TD>
|
| 252 |
|
|
<TR><TD><b>VIDEO_TUNER_SECAM</b><TD>SECAM tuning is supported</TD>
|
| 253 |
|
|
<TR><TD><b>VIDEO_TUNER_LOW</b><TD>Frequency is in a lower range</TD>
|
| 254 |
|
|
<TR><TD><b>VIDEO_TUNER_NORM</b><TD>The norm for this tuner is settable</TD>
|
| 255 |
|
|
<TR><TD><b>VIDEO_TUNER_STEREO_ON</b><TD>The tuner is seeing stereo audio</TD>
|
| 256 |
|
|
<TR><TD><b>VIDEO_TUNER_RDS_ON</b><TD>The tuner is seeing a RDS datastream</TD>
|
| 257 |
|
|
<TR><TD><b>VIDEO_TUNER_MBS_ON</b><TD>The tuner is seeing a MBS datastream</TD>
|
| 258 |
|
|
</TABLE>
|
| 259 |
|
|
<P>
|
| 260 |
|
|
The following modes are defined
|
| 261 |
|
|
<P>
|
| 262 |
|
|
<TABLE>
|
| 263 |
|
|
<TR><TD><b>VIDEO_MODE_PAL</b><TD>The tuner is in PAL mode</TD>
|
| 264 |
|
|
<TR><TD><b>VIDEO_MODE_NTSC</b><TD>The tuner is in NTSC mode</TD>
|
| 265 |
|
|
<TR><TD><b>VIDEO_MODE_SECAM</b><TD>The tuner is in SECAM mode</TD>
|
| 266 |
|
|
<TR><TD><b>VIDEO_MODE_AUTO</b><TD>The tuner auto switches, or mode does not apply</TD>
|
| 267 |
|
|
</TABLE>
|
| 268 |
|
|
<P>
|
| 269 |
|
|
Tuning frequencies are an unsigned 32bit value in 1/16th MHz or if the
|
| 270 |
|
|
<b>VIDEO_TUNER_LOW</b> flag is set they are in 1/16th KHz. The current
|
| 271 |
|
|
frequency is obtained as an unsigned long via the <b>VIDIOCGFREQ</b> ioctl and
|
| 272 |
|
|
set by the <b>VIDIOCSFREQ</b> ioctl.
|
| 273 |
|
|
<P>
|
| 274 |
|
|
<H3>Audio</H3>
|
| 275 |
|
|
TV and Radio devices have one or more audio inputs that may be selected.
|
| 276 |
|
|
The audio properties are queried by passing a <b>struct video_audio</b> to <b>VIDIOCGAUDIO</b> ioctl. The
|
| 277 |
|
|
<b>VIDIOCSAUDIO</b> ioctl sets audio properties.
|
| 278 |
|
|
<P>
|
| 279 |
|
|
The structure contains the following fields
|
| 280 |
|
|
<P>
|
| 281 |
|
|
<TABLE>
|
| 282 |
|
|
<TR><TD><b>audio</b><TD>The channel number</TD>
|
| 283 |
|
|
<TR><TD><b>volume</b><TD>The volume level</TD>
|
| 284 |
|
|
<TR><TD><b>bass</b><TD>The bass level</TD>
|
| 285 |
|
|
<TR><TD><b>treble</b><TD>The treble level</TD>
|
| 286 |
|
|
<TR><TD><b>flags</b><TD>Flags describing the audio channel</TD>
|
| 287 |
|
|
<TR><TD><b>name</b><TD>Canonical name for the audio input</TD>
|
| 288 |
|
|
<TR><TD><b>mode</b><TD>The mode the audio input is in</TD>
|
| 289 |
|
|
<TR><TD><b>balance</b><TD>The left/right balance</TD>
|
| 290 |
|
|
<TR><TD><b>step</b><TD>Actual step used by the hardware</TD>
|
| 291 |
|
|
</TABLE>
|
| 292 |
|
|
<P>
|
| 293 |
|
|
The following flags are defined
|
| 294 |
|
|
<P>
|
| 295 |
|
|
<TABLE>
|
| 296 |
|
|
<TR><TD><b>VIDEO_AUDIO_MUTE</b><TD>The audio is muted</TD>
|
| 297 |
|
|
<TR><TD><b>VIDEO_AUDIO_MUTABLE</b><TD>Audio muting is supported</TD>
|
| 298 |
|
|
<TR><TD><b>VIDEO_AUDIO_VOLUME</b><TD>The volume is controllable</TD>
|
| 299 |
|
|
<TR><TD><b>VIDEO_AUDIO_BASS</b><TD>The bass is controllable</TD>
|
| 300 |
|
|
<TR><TD><b>VIDEO_AUDIO_TREBLE</b><TD>The treble is controllable</TD>
|
| 301 |
|
|
<TR><TD><b>VIDEO_AUDIO_BALANCE</b><TD>The balance is controllable</TD>
|
| 302 |
|
|
</TABLE>
|
| 303 |
|
|
<P>
|
| 304 |
|
|
The following decoding modes are defined
|
| 305 |
|
|
<P>
|
| 306 |
|
|
<TABLE>
|
| 307 |
|
|
<TR><TD><b>VIDEO_SOUND_MONO</b><TD>Mono signal</TD>
|
| 308 |
|
|
<TR><TD><b>VIDEO_SOUND_STEREO</b><TD>Stereo signal (NICAM for TV)</TD>
|
| 309 |
|
|
<TR><TD><b>VIDEO_SOUND_LANG1</b><TD>European TV alternate language 1</TD>
|
| 310 |
|
|
<TR><TD><b>VIDEO_SOUND_LANG2</b><TD>European TV alternate language 2</TD>
|
| 311 |
|
|
</TABLE>
|
| 312 |
|
|
<P>
|
| 313 |
|
|
<H3>Reading Images</H3>
|
| 314 |
|
|
Each call to the <b>read</b> syscall returns the next available image
|
| 315 |
|
|
from the device. It is up to the caller to set format and size (using
|
| 316 |
|
|
the VIDIOCSPICT and VIDIOCSWIN ioctls) and then to pass a suitable
|
| 317 |
|
|
size buffer and length to the function. Not all devices will support
|
| 318 |
|
|
read operations.
|
| 319 |
|
|
<P>
|
| 320 |
|
|
A second way to handle image capture is via the mmap interface if supported.
|
| 321 |
|
|
To use the mmap interface a user first sets the desired image size and depth
|
| 322 |
|
|
properties. Next the VIDIOCGMBUF ioctl is issued. This reports the size
|
| 323 |
|
|
of buffer to mmap and the offset within the buffer for each frame. The
|
| 324 |
|
|
number of frames supported is device dependent and may only be one.
|
| 325 |
|
|
<P>
|
| 326 |
|
|
The video_mbuf structure contains the following fields
|
| 327 |
|
|
<P>
|
| 328 |
|
|
<TABLE>
|
| 329 |
|
|
<TR><TD><b>size</b><TD>The number of bytes to map</TD>
|
| 330 |
|
|
<TR><TD><b>frames</b><TD>The number of frames</TD>
|
| 331 |
|
|
<TR><TD><b>offsets</b><TD>The offset of each frame</TD>
|
| 332 |
|
|
</TABLE>
|
| 333 |
|
|
<P>
|
| 334 |
|
|
Once the mmap has been made the VIDIOCMCAPTURE ioctl starts the
|
| 335 |
|
|
capture to a frame using the format and image size specified in the
|
| 336 |
|
|
video_mmap (which should match or be below the initial query size).
|
| 337 |
|
|
When the VIDIOCMCAPTURE ioctl returns the frame is <em>not</em>
|
| 338 |
|
|
captured yet, the driver just instructed the hardware to start the
|
| 339 |
|
|
capture. The application has to use the VIDIOCSYNC ioctl to wait
|
| 340 |
|
|
until the capture of a frame is finished. VIDIOCSYNC takes the frame
|
| 341 |
|
|
number you want to wait for as argument.
|
| 342 |
|
|
<p>
|
| 343 |
|
|
It is allowed to call VIDIOCMCAPTURE multiple times (with different
|
| 344 |
|
|
frame numbers in video_mmap->frame of course) and thus have multiple
|
| 345 |
|
|
outstanding capture requests. A simple way do to double-buffering
|
| 346 |
|
|
using this feature looks like this:
|
| 347 |
|
|
<pre>
|
| 348 |
|
|
/* setup everything */
|
| 349 |
|
|
VIDIOCMCAPTURE(0)
|
| 350 |
|
|
while (whatever) {
|
| 351 |
|
|
VIDIOCMCAPTURE(1)
|
| 352 |
|
|
VIDIOCSYNC(0)
|
| 353 |
|
|
/* process frame 0 while the hardware captures frame 1 */
|
| 354 |
|
|
VIDIOCMCAPTURE(0)
|
| 355 |
|
|
VIDIOCSYNC(1)
|
| 356 |
|
|
/* process frame 1 while the hardware captures frame 0 */
|
| 357 |
|
|
}
|
| 358 |
|
|
</pre>
|
| 359 |
|
|
Note that you are <em>not</em> limited to only two frames. The API
|
| 360 |
|
|
allows up to 32 frames, the VIDIOCGMBUF ioctl returns the number of
|
| 361 |
|
|
frames the driver granted. Thus it is possible to build deeper queues
|
| 362 |
|
|
to avoid loosing frames on load peaks.
|
| 363 |
|
|
<p>
|
| 364 |
|
|
While capturing to memory the driver will make a "best effort" attempt
|
| 365 |
|
|
to capture to screen as well if requested. This normally means all
|
| 366 |
|
|
frames that "miss" memory mapped capture will go to the display.
|
| 367 |
|
|
<P>
|
| 368 |
|
|
A final ioctl exists to allow a device to obtain related devices if a
|
| 369 |
|
|
driver has multiple components (for example video0 may not be associated
|
| 370 |
|
|
with vbi0 which would cause an intercast display program to make a bad
|
| 371 |
|
|
mistake). The VIDIOCGUNIT ioctl reports the unit numbers of the associated
|
| 372 |
|
|
devices if any exist. The video_unit structure has the following fields.
|
| 373 |
|
|
<P>
|
| 374 |
|
|
<TABLE>
|
| 375 |
|
|
<TR><TD><b>video</b><TD>Video capture device</TD>
|
| 376 |
|
|
<TR><TD><b>vbi</b><TD>VBI capture device</TD>
|
| 377 |
|
|
<TR><TD><b>radio</b><TD>Radio device</TD>
|
| 378 |
|
|
<TR><TD><b>audio</b><TD>Audio mixer</TD>
|
| 379 |
|
|
<TR><TD><b>teletext</b><TD>Teletext device</TD>
|
| 380 |
|
|
</TABLE>
|
| 381 |
|
|
<P>
|
| 382 |
|
|
<H3>RDS Datastreams</H3>
|
| 383 |
|
|
For radio devices that support it, it is possible to receive Radio Data
|
| 384 |
|
|
System (RDS) data by means of a read() on the device. The data is packed in
|
| 385 |
|
|
groups of three, as follows:
|
| 386 |
|
|
<TABLE>
|
| 387 |
|
|
<TR><TD>First Octet</TD><TD>Least Significant Byte of RDS Block</TD></TR>
|
| 388 |
|
|
<TR><TD>Second Octet</TD><TD>Most Significant Byte of RDS Block
|
| 389 |
|
|
<TR><TD>Third Octet</TD><TD>Bit 7:</TD><TD>Error bit. Indicates that
|
| 390 |
|
|
an uncorrectable error occurred during reception of this block.</TD></TR>
|
| 391 |
|
|
<TR><TD> </TD><TD>Bit 6:</TD><TD>Corrected bit. Indicates that
|
| 392 |
|
|
an error was corrected for this data block.</TD></TR>
|
| 393 |
|
|
<TR><TD> </TD><TD>Bits 5-3:</TD><TD>Received Offset. Indicates the
|
| 394 |
|
|
offset received by the sync system.</TD></TR>
|
| 395 |
|
|
<TR><TD> </TD><TD>Bits 2-0:</TD><TD>Offset Name. Indicates the
|
| 396 |
|
|
offset applied to this data.</TD></TR>
|
| 397 |
|
|
</TABLE>
|
| 398 |
|
|
</BODY>
|
| 399 |
|
|
</HTML>
|
