diff options
author | Mauro Carvalho Chehab <mchehab@brturbo.com.br> | 2005-06-28 23:45:28 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-06-29 00:20:37 -0400 |
commit | 6623e6205e36c310367009f3b01f5cbe7cc0005d (patch) | |
tree | 780e94f1426c1a4368f819f7e5656a075cc39b71 /Documentation/video4linux/API.html | |
parent | 115d6f3fd25991f2a7de1ff4d758086209b1ed12 (diff) |
[PATCH] V4L: documentation changes - mostly new cards included
New cards included.
V4L1 api renamed. Message included informing it is obsoleted by V4L2 API.
V4L2 api included.
Mark all 7135 cards as 7133.
Signed-off-by: Luc Saillard <luc@saillard.org>.
Signed-off-by: Nickolay V Shmyrev <nshmyrev@yandex.ru>
Signed-off-by: Hermann Pitton <hermann.pitton@onlinehome.de>
Signed-off-by: Michael Krufky <mkrufky@m1k.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@brturbo.com.br>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation/video4linux/API.html')
-rw-r--r-- | Documentation/video4linux/API.html | 415 |
1 files changed, 16 insertions, 399 deletions
diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html index 4b3d8f640a4a..441407b12a9f 100644 --- a/Documentation/video4linux/API.html +++ b/Documentation/video4linux/API.html | |||
@@ -1,399 +1,16 @@ | |||
1 | <HTML><HEAD> | 1 | <TITLE>V4L API</TITLE> |
2 | <TITLE>Video4Linux Kernel API Reference v0.1:19990430</TITLE> | 2 | <H1>Video For Linux APIs</H1> |
3 | </HEAD> | 3 | <table border=0> |
4 | <! Revision History: > | 4 | <tr> |
5 | <! 4/30/1999 - Fred Gleason (fredg@wava.com)> | 5 | <td> |
6 | <! Documented extensions for the Radio Data System (RDS) extensions > | 6 | <A HREF=http://www.linuxtv.org/downloads/video4linux/API/V4L1_API.html> |
7 | <BODY bgcolor="#ffffff"> | 7 | V4L original API</a> |
8 | <H3>Devices</H3> | 8 | </td><td> |
9 | Video4Linux provides the following sets of device files. These live on the | 9 | Obsoleted by V4L2 API |
10 | character device formerly known as "/dev/bttv". /dev/bttv should be a | 10 | </td></tr><tr><td> |
11 | symlink to /dev/video0 for most people. | 11 | <A HREF=http://www.linuxtv.org/downloads/video4linux/API/V4L2_API.html> |
12 | <P> | 12 | V4L2 API</a> |
13 | <TABLE> | 13 | </td><td> |
14 | <TR><TH>Device Name</TH><TH>Minor Range</TH><TH>Function</TH> | 14 | Should be used for new projects |
15 | <TR><TD>/dev/video</TD><TD>0-63</TD><TD>Video Capture Interface</TD> | 15 | </td></tr> |
16 | <TR><TD>/dev/radio</TD><TD>64-127</TD><TD>AM/FM Radio Devices</TD> | 16 | </table> |
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> | ||