• 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 Overlay 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 Output Interface"
17HREF="x6831.htm"><LINK
18REL="NEXT"
19TITLE="Codec Interface"
20HREF="x6991.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="x6831.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="x6991.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="OSD"
77>4.4. Video Output Overlay Interface</A
78></H1
79><FONT
80COLOR="RED"
81>Also known as On-Screen Display (OSD)</FONT
82><DIV
83CLASS="NOTE"
84><BLOCKQUOTE
85CLASS="NOTE"
86><P
87><B
88>Experimental: </B
89>This is an <A
90HREF="x16453.htm"
91>experimental</A
92>
93interface and may change in the future.</P
94></BLOCKQUOTE
95></DIV
96><P
97>Some video output devices can overlay a framebuffer image onto
98the outgoing video signal. Applications can set up such an overlay
99using this interface, which borrows structures and ioctls of the <A
100HREF="x6570.htm"
101>Video Overlay</A
102> interface.</P
103><P
104>The OSD function is accessible through the same character
105special file as the <A
106HREF="c6488.htm#CAPTURE"
107>Video Output</A
108> function.
109Note the default function of such a <TT
110CLASS="FILENAME"
111>/dev/video</TT
112> device
113is video capturing or output. The OSD function is only available after
114calling the <A
115HREF="r10944.htm"
116><CODE
117CLASS="CONSTANT"
118>VIDIOC_S_FMT</CODE
119></A
120> ioctl.</P
121><DIV
122CLASS="SECTION"
123><H2
124CLASS="SECTION"
125><A
126NAME="AEN6923"
127>4.4.1. Querying Capabilities</A
128></H2
129><P
130>Devices supporting the <I
131CLASS="WORDASWORD"
132>Video Output
133Overlay</I
134> interface set the
135<CODE
136CLASS="CONSTANT"
137>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</CODE
138> flag in the
139<CODE
140CLASS="STRUCTFIELD"
141>capabilities</CODE
142> field of struct&nbsp;<A
143HREF="r13105.htm#V4L2-CAPABILITY"
144>v4l2_capability</A
145>
146returned by the <A
147HREF="r13105.htm"
148><CODE
149CLASS="CONSTANT"
150>VIDIOC_QUERYCAP</CODE
151></A
152> ioctl.</P
153></DIV
154><DIV
155CLASS="SECTION"
156><H2
157CLASS="SECTION"
158><A
159NAME="AEN6932"
160>4.4.2. Framebuffer</A
161></H2
162><P
163>Contrary to the <I
164CLASS="WORDASWORD"
165>Video Overlay</I
166>
167interface the framebuffer is normally implemented on the TV card and
168not the graphics card. On Linux it is accessible as a framebuffer
169device (<TT
170CLASS="FILENAME"
171>/dev/fbN</TT
172>). Given a V4L2 device,
173applications can find the corresponding framebuffer device by calling
174the <A
175HREF="r10595.htm"
176><CODE
177CLASS="CONSTANT"
178>VIDIOC_G_FBUF</CODE
179></A
180> ioctl. It returns, amongst other information, the
181physical address of the framebuffer in the
182<CODE
183CLASS="STRUCTFIELD"
184>base</CODE
185> field of struct&nbsp;<A
186HREF="r10595.htm#V4L2-FRAMEBUFFER"
187>v4l2_framebuffer</A
188>. The
189framebuffer device ioctl <CODE
190CLASS="CONSTANT"
191>FBIOGET_FSCREENINFO</CODE
192>
193returns the same address in the <CODE
194CLASS="STRUCTFIELD"
195>smem_start</CODE
196>
197field of struct <CODE
198CLASS="STRUCTNAME"
199>fb_fix_screeninfo</CODE
200>. The
201<CODE
202CLASS="CONSTANT"
203>FBIOGET_FSCREENINFO</CODE
204> ioctl and struct
205<CODE
206CLASS="STRUCTNAME"
207>fb_fix_screeninfo</CODE
208> are defined in the
209<TT
210CLASS="FILENAME"
211>linux/fb.h</TT
212> header file.</P
213><P
214>The width and height of the framebuffer depends on the
215current video standard. A V4L2 driver may reject attempts to change
216the video standard (or any other ioctl which would imply a framebuffer
217size change) with an <SPAN
218CLASS="ERRORCODE"
219>EBUSY</SPAN
220> error code until all applications closed the
221framebuffer device.</P
222><DIV
223CLASS="EXAMPLE"
224><A
225NAME="AEN6949"
226></A
227><P
228><B
229>Example 4-1. Finding a framebuffer device for OSD</B
230></P
231><PRE
232CLASS="PROGRAMLISTING"
233>#include &lt;linux/fb.h&gt;
234
235struct&nbsp;<A
236HREF="r10595.htm#V4L2-FRAMEBUFFER"
237>v4l2_framebuffer</A
238> fbuf;
239unsigned int i;
240int fb_fd;
241
242if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
243        perror ("VIDIOC_G_FBUF");
244        exit (EXIT_FAILURE);
245}
246
247for (i = 0; i &#60; 30; ++i) {
248        char dev_name[16];
249        struct fb_fix_screeninfo si;
250
251        snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);
252
253        fb_fd = open (dev_name, O_RDWR);
254        if (-1 == fb_fd) {
255                switch (errno) {
256                case ENOENT: /* no such file */
257                case ENXIO:  /* no driver */
258                        continue;
259
260                default:
261                        perror ("open");
262                        exit (EXIT_FAILURE);
263                }
264        }
265
266        if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
267                if (si.smem_start == (unsigned long) fbuf.base)
268                        break;
269        } else {
270                /* Apparently not a framebuffer device. */
271        }
272
273        close (fb_fd);
274        fb_fd = -1;
275}
276
277/* fb_fd is the file descriptor of the framebuffer device
278   for the video output overlay, or -1 if no device was found. */</PRE
279></DIV
280></DIV
281><DIV
282CLASS="SECTION"
283><H2
284CLASS="SECTION"
285><A
286NAME="AEN6953"
287>4.4.3. Overlay Window and Scaling</A
288></H2
289><P
290>The overlay is controlled by source and target rectangles.
291The source rectangle selects a subsection of the framebuffer image to
292be overlaid, the target rectangle an area in the outgoing video signal
293where the image will appear. Drivers may or may not support scaling,
294and arbitrary sizes and positions of these rectangles. Further drivers
295may support any (or none) of the clipping/blending methods defined for
296the <A
297HREF="x6570.htm"
298>Video Overlay</A
299> interface.</P
300><P
301>A struct&nbsp;<A
302HREF="x6570.htm#V4L2-WINDOW"
303>v4l2_window</A
304> defines the size of the source rectangle,
305its position in the framebuffer and the clipping/blending method to be
306used for the overlay. To get the current parameters applications set
307the <CODE
308CLASS="STRUCTFIELD"
309>type</CODE
310> field of a struct&nbsp;<A
311HREF="r10944.htm#V4L2-FORMAT"
312>v4l2_format</A
313> to
314<CODE
315CLASS="CONSTANT"
316>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</CODE
317> and call the
318<A
319HREF="r10944.htm"
320><CODE
321CLASS="CONSTANT"
322>VIDIOC_G_FMT</CODE
323></A
324> ioctl. The driver fills the
325<CODE
326CLASS="STRUCTNAME"
327>v4l2_window</CODE
328> substructure named
329<CODE
330CLASS="STRUCTFIELD"
331>win</CODE
332>. It is not possible to retrieve a
333previously programmed clipping list or bitmap.</P
334><P
335>To program the source rectangle applications set the
336<CODE
337CLASS="STRUCTFIELD"
338>type</CODE
339> field of a struct&nbsp;<A
340HREF="r10944.htm#V4L2-FORMAT"
341>v4l2_format</A
342> to
343<CODE
344CLASS="CONSTANT"
345>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</CODE
346>, initialize
347the <CODE
348CLASS="STRUCTFIELD"
349>win</CODE
350> substructure and call the
351<A
352HREF="r10944.htm"
353><CODE
354CLASS="CONSTANT"
355>VIDIOC_S_FMT</CODE
356></A
357> ioctl. The driver adjusts the parameters against
358hardware limits and returns the actual parameters as
359<CODE
360CLASS="CONSTANT"
361>VIDIOC_G_FMT</CODE
362> does. Like
363<CODE
364CLASS="CONSTANT"
365>VIDIOC_S_FMT</CODE
366>, the <A
367HREF="r10944.htm"
368><CODE
369CLASS="CONSTANT"
370>VIDIOC_TRY_FMT</CODE
371></A
372> ioctl can be
373used to learn about driver capabilities without actually changing
374driver state. Unlike <CODE
375CLASS="CONSTANT"
376>VIDIOC_S_FMT</CODE
377> this also works
378after the overlay has been enabled.</P
379><P
380>A struct&nbsp;<A
381HREF="r9994.htm#V4L2-CROP"
382>v4l2_crop</A
383> defines the size and position of the target
384rectangle. The scaling factor of the overlay is implied by the width
385and height given in struct&nbsp;<A
386HREF="x6570.htm#V4L2-WINDOW"
387>v4l2_window</A
388> and struct&nbsp;<A
389HREF="r9994.htm#V4L2-CROP"
390>v4l2_crop</A
391>. The cropping API
392applies to <I
393CLASS="WORDASWORD"
394>Video Output</I
395> and <I
396CLASS="WORDASWORD"
397>Video
398Output Overlay</I
399> devices in the same way as to
400<I
401CLASS="WORDASWORD"
402>Video Capture</I
403> and <I
404CLASS="WORDASWORD"
405>Video
406Overlay</I
407> devices, merely reversing the direction of the
408data flow. For more information see <A
409HREF="x1904.htm"
410>Section 1.11</A
411>.</P
412></DIV
413><DIV
414CLASS="SECTION"
415><H2
416CLASS="SECTION"
417><A
418NAME="AEN6987"
419>4.4.4. Enabling Overlay</A
420></H2
421><P
422>There is no V4L2 ioctl to enable or disable the overlay,
423however the framebuffer interface of the driver may support the
424<CODE
425CLASS="CONSTANT"
426>FBIOBLANK</CODE
427> ioctl.</P
428></DIV
429></DIV
430><DIV
431CLASS="NAVFOOTER"
432><HR
433ALIGN="LEFT"
434WIDTH="100%"><TABLE
435SUMMARY="Footer navigation table"
436WIDTH="100%"
437BORDER="0"
438CELLPADDING="0"
439CELLSPACING="0"
440><TR
441><TD
442WIDTH="33%"
443ALIGN="left"
444VALIGN="top"
445><A
446HREF="x6831.htm"
447ACCESSKEY="P"
448>Prev</A
449></TD
450><TD
451WIDTH="34%"
452ALIGN="center"
453VALIGN="top"
454><A
455HREF="book1.htm"
456ACCESSKEY="H"
457>Home</A
458></TD
459><TD
460WIDTH="33%"
461ALIGN="right"
462VALIGN="top"
463><A
464HREF="x6991.htm"
465ACCESSKEY="N"
466>Next</A
467></TD
468></TR
469><TR
470><TD
471WIDTH="33%"
472ALIGN="left"
473VALIGN="top"
474>Video Output Interface</TD
475><TD
476WIDTH="34%"
477ALIGN="center"
478VALIGN="top"
479><A
480HREF="c6488.htm"
481ACCESSKEY="U"
482>Up</A
483></TD
484><TD
485WIDTH="33%"
486ALIGN="right"
487VALIGN="top"
488>Codec Interface</TD
489></TR
490></TABLE
491></DIV
492></BODY
493></HTML
494>
495