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