• 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>Video Output Interface</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="UP"
13TITLE="Interfaces"
14HREF="c6488.htm"><LINK
15REL="PREVIOUS"
16TITLE="Video Overlay Interface"
17HREF="x6570.htm"><LINK
18REL="NEXT"
19TITLE="Video Output Overlay Interface"
20HREF="x6909.htm"></HEAD
21><BODY
22CLASS="SECTION"
23BGCOLOR="#FFFFFF"
24TEXT="#000000"
25LINK="#0000FF"
26VLINK="#840084"
27ALINK="#0000FF"
28><DIV
29CLASS="NAVHEADER"
30><TABLE
31SUMMARY="Header navigation table"
32WIDTH="100%"
33BORDER="0"
34CELLPADDING="0"
35CELLSPACING="0"
36><TR
37><TH
38COLSPAN="3"
39ALIGN="center"
40>Video for Linux Two API Specification: Revision 0.24</TH
41></TR
42><TR
43><TD
44WIDTH="10%"
45ALIGN="left"
46VALIGN="bottom"
47><A
48HREF="x6570.htm"
49ACCESSKEY="P"
50>Prev</A
51></TD
52><TD
53WIDTH="80%"
54ALIGN="center"
55VALIGN="bottom"
56>Chapter 4. Interfaces</TD
57><TD
58WIDTH="10%"
59ALIGN="right"
60VALIGN="bottom"
61><A
62HREF="x6909.htm"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><DIV
72CLASS="SECTION"
73><H1
74CLASS="SECTION"
75><A
76NAME="OUTPUT"
77>4.3. Video Output Interface</A
78></H1
79><P
80>Video output devices encode stills or image sequences as
81analog video signal. With this interface applications can
82control the encoding process and move images from user space to
83the driver.</P
84><P
85>Conventionally V4L2 video output devices are accessed through
86character device special files named <TT
87CLASS="FILENAME"
88>/dev/video</TT
89>
90and <TT
91CLASS="FILENAME"
92>/dev/video0</TT
93> to
94<TT
95CLASS="FILENAME"
96>/dev/video63</TT
97> with major number 81 and minor
98numbers 0 to 63. <TT
99CLASS="FILENAME"
100>/dev/video</TT
101> is typically a
102symbolic link to the preferred video device. Note the same device
103files are used for video capture devices.</P
104><DIV
105CLASS="SECTION"
106><H2
107CLASS="SECTION"
108><A
109NAME="AEN6839"
110>4.3.1. Querying Capabilities</A
111></H2
112><P
113>Devices supporting the video output interface set the
114<CODE
115CLASS="CONSTANT"
116>V4L2_CAP_VIDEO_OUTPUT</CODE
117> flag in the
118<CODE
119CLASS="STRUCTFIELD"
120>capabilities</CODE
121> field of struct&nbsp;<A
122HREF="r13105.htm#V4L2-CAPABILITY"
123>v4l2_capability</A
124>
125returned by the <A
126HREF="r13105.htm"
127><CODE
128CLASS="CONSTANT"
129>VIDIOC_QUERYCAP</CODE
130></A
131> ioctl. As secondary device functions
132they may also support the <A
133HREF="x7013.htm"
134>raw VBI
135output</A
136> (<CODE
137CLASS="CONSTANT"
138>V4L2_CAP_VBI_OUTPUT</CODE
139>) interface. At
140least one of the read/write or streaming I/O methods must be
141supported. Modulators and audio outputs are optional.</P
142></DIV
143><DIV
144CLASS="SECTION"
145><H2
146CLASS="SECTION"
147><A
148NAME="AEN6849"
149>4.3.2. Supplemental Functions</A
150></H2
151><P
152>Video output devices shall support <A
153HREF="x341.htm"
154>audio output</A
155>, <A
156HREF="x394.htm"
157>modulator</A
158>, <A
159HREF="x542.htm"
160>controls</A
161>,
162<A
163HREF="x1904.htm"
164>cropping and scaling</A
165> and <A
166HREF="x2009.htm"
167>streaming parameter</A
168> ioctls as needed.
169The <A
170HREF="x309.htm"
171>video output</A
172> and <A
173HREF="x448.htm"
174>video standard</A
175> ioctls must be supported by
176all video output devices.</P
177></DIV
178><DIV
179CLASS="SECTION"
180><H2
181CLASS="SECTION"
182><A
183NAME="AEN6859"
184>4.3.3. Image Format Negotiation</A
185></H2
186><P
187>The output is determined by cropping and image format
188parameters. The former select an area of the video picture where the
189image will appear, the latter how images are stored in memory, i.&nbsp;e. in
190RGB or YUV format, the number of bits per pixel or width and height.
191Together they also define how images are scaled in the process.</P
192><P
193>As usual these parameters are <SPAN
194CLASS="emphasis"
195><I
196CLASS="EMPHASIS"
197>not</I
198></SPAN
199> reset
200at <A
201HREF="r14090.htm"
202><CODE
203CLASS="FUNCTION"
204>open()</CODE
205></A
206> time to permit Unix tool chains, programming a device
207and then writing to it as if it was a plain file. Well written V4L2
208applications ensure they really get what they want, including cropping
209and scaling.</P
210><P
211>Cropping initialization at minimum requires to reset the
212parameters to defaults. An example is given in <A
213HREF="x1904.htm"
214>Section 1.11</A
215>.</P
216><P
217>To query the current image format applications set the
218<CODE
219CLASS="STRUCTFIELD"
220>type</CODE
221> field of a struct&nbsp;<A
222HREF="r10944.htm#V4L2-FORMAT"
223>v4l2_format</A
224> to
225<CODE
226CLASS="CONSTANT"
227>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
228> and call the
229<A
230HREF="r10944.htm"
231><CODE
232CLASS="CONSTANT"
233>VIDIOC_G_FMT</CODE
234></A
235> ioctl with a pointer to this structure. Drivers fill
236the struct&nbsp;<A
237HREF="c2030.htm#V4L2-PIX-FORMAT"
238>v4l2_pix_format</A
239> <CODE
240CLASS="STRUCTFIELD"
241>pix</CODE
242> member of the
243<CODE
244CLASS="STRUCTFIELD"
245>fmt</CODE
246> union.</P
247><P
248>To request different parameters applications set the
249<CODE
250CLASS="STRUCTFIELD"
251>type</CODE
252> field of a struct&nbsp;<A
253HREF="r10944.htm#V4L2-FORMAT"
254>v4l2_format</A
255> as above and
256initialize all fields of the struct&nbsp;<A
257HREF="c2030.htm#V4L2-PIX-FORMAT"
258>v4l2_pix_format</A
259>
260<CODE
261CLASS="STRUCTFIELD"
262>vbi</CODE
263> member of the
264<CODE
265CLASS="STRUCTFIELD"
266>fmt</CODE
267> union, or better just modify the
268results of <CODE
269CLASS="CONSTANT"
270>VIDIOC_G_FMT</CODE
271>, and call the
272<A
273HREF="r10944.htm"
274><CODE
275CLASS="CONSTANT"
276>VIDIOC_S_FMT</CODE
277></A
278> ioctl with a pointer to this structure. Drivers may
279adjust the parameters and finally return the actual parameters as
280<CODE
281CLASS="CONSTANT"
282>VIDIOC_G_FMT</CODE
283> does.</P
284><P
285>Like <CODE
286CLASS="CONSTANT"
287>VIDIOC_S_FMT</CODE
288> the
289<A
290HREF="r10944.htm"
291><CODE
292CLASS="CONSTANT"
293>VIDIOC_TRY_FMT</CODE
294></A
295> ioctl can be used to learn about hardware limitations
296without disabling I/O or possibly time consuming hardware
297preparations.</P
298><P
299>The contents of struct&nbsp;<A
300HREF="c2030.htm#V4L2-PIX-FORMAT"
301>v4l2_pix_format</A
302> are discussed in <A
303HREF="c2030.htm"
304>Chapter 2</A
305>. See also the specification of the
306<CODE
307CLASS="CONSTANT"
308>VIDIOC_G_FMT</CODE
309>, <CODE
310CLASS="CONSTANT"
311>VIDIOC_S_FMT</CODE
312>
313and <CODE
314CLASS="CONSTANT"
315>VIDIOC_TRY_FMT</CODE
316> ioctls for details. Video
317output devices must implement both the
318<CODE
319CLASS="CONSTANT"
320>VIDIOC_G_FMT</CODE
321> and
322<CODE
323CLASS="CONSTANT"
324>VIDIOC_S_FMT</CODE
325> ioctl, even if
326<CODE
327CLASS="CONSTANT"
328>VIDIOC_S_FMT</CODE
329> ignores all requests and always
330returns default parameters as <CODE
331CLASS="CONSTANT"
332>VIDIOC_G_FMT</CODE
333> does.
334<CODE
335CLASS="CONSTANT"
336>VIDIOC_TRY_FMT</CODE
337> is optional.</P
338></DIV
339><DIV
340CLASS="SECTION"
341><H2
342CLASS="SECTION"
343><A
344NAME="AEN6902"
345>4.3.4. Writing Images</A
346></H2
347><P
348>A video output device may support the <A
349HREF="c5742.htm#RW"
350>write() function</A
351> and/or streaming (<A
352HREF="x5791.htm"
353>memory mapping</A
354> or <A
355HREF="x5884.htm"
356>user pointer</A
357>) I/O. See <A
358HREF="c5742.htm"
359>Chapter 3</A
360> for details.</P
361></DIV
362></DIV
363><DIV
364CLASS="NAVFOOTER"
365><HR
366ALIGN="LEFT"
367WIDTH="100%"><TABLE
368SUMMARY="Footer navigation table"
369WIDTH="100%"
370BORDER="0"
371CELLPADDING="0"
372CELLSPACING="0"
373><TR
374><TD
375WIDTH="33%"
376ALIGN="left"
377VALIGN="top"
378><A
379HREF="x6570.htm"
380ACCESSKEY="P"
381>Prev</A
382></TD
383><TD
384WIDTH="34%"
385ALIGN="center"
386VALIGN="top"
387><A
388HREF="book1.htm"
389ACCESSKEY="H"
390>Home</A
391></TD
392><TD
393WIDTH="33%"
394ALIGN="right"
395VALIGN="top"
396><A
397HREF="x6909.htm"
398ACCESSKEY="N"
399>Next</A
400></TD
401></TR
402><TR
403><TD
404WIDTH="33%"
405ALIGN="left"
406VALIGN="top"
407>Video Overlay Interface</TD
408><TD
409WIDTH="34%"
410ALIGN="center"
411VALIGN="top"
412><A
413HREF="c6488.htm"
414ACCESSKEY="U"
415>Up</A
416></TD
417><TD
418WIDTH="33%"
419ALIGN="right"
420VALIGN="top"
421>Video Output Overlay Interface</TD
422></TR
423></TABLE
424></DIV
425></BODY
426></HTML
427>
428