1 <title>Video Output Overlay Interface</title> 2 <subtitle>Also known as On-Screen Display (OSD)</subtitle> 3 4 <note> 5 <title>Experimental</title> 6 7 <para>This is an <link linkend="experimental">experimental</link> 8interface and may change in the future.</para> 9 </note> 10 11 <para>Some video output devices can overlay a framebuffer image onto 12the outgoing video signal. Applications can set up such an overlay 13using this interface, which borrows structures and ioctls of the <link 14linkend="overlay">Video Overlay</link> interface.</para> 15 16 <para>The OSD function is accessible through the same character 17special file as the <link linkend="capture">Video Output</link> function. 18Note the default function of such a <filename>/dev/video</filename> device 19is video capturing or output. The OSD function is only available after 20calling the &VIDIOC-S-FMT; ioctl.</para> 21 22 <section> 23 <title>Querying Capabilities</title> 24 25 <para>Devices supporting the <wordasword>Video Output 26Overlay</wordasword> interface set the 27<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the 28<structfield>capabilities</structfield> field of &v4l2-capability; 29returned by the &VIDIOC-QUERYCAP; ioctl.</para> 30 </section> 31 32 <section> 33 <title>Framebuffer</title> 34 35 <para>Contrary to the <wordasword>Video Overlay</wordasword> 36interface the framebuffer is normally implemented on the TV card and 37not the graphics card. On Linux it is accessible as a framebuffer 38device (<filename>/dev/fbN</filename>). Given a V4L2 device, 39applications can find the corresponding framebuffer device by calling 40the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the 41physical address of the framebuffer in the 42<structfield>base</structfield> field of &v4l2-framebuffer;. The 43framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant> 44returns the same address in the <structfield>smem_start</structfield> 45field of struct <structname>fb_fix_screeninfo</structname>. The 46<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct 47<structname>fb_fix_screeninfo</structname> are defined in the 48<filename>linux/fb.h</filename> header file.</para> 49 50 <para>The width and height of the framebuffer depends on the 51current video standard. A V4L2 driver may reject attempts to change 52the video standard (or any other ioctl which would imply a framebuffer 53size change) with an &EBUSY; until all applications closed the 54framebuffer device.</para> 55 56 <example> 57 <title>Finding a framebuffer device for OSD</title> 58 59 <programlisting> 60#include <linux/fb.h> 61 62&v4l2-framebuffer; fbuf; 63unsigned int i; 64int fb_fd; 65 66if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) { 67 perror ("VIDIOC_G_FBUF"); 68 exit (EXIT_FAILURE); 69} 70 71for (i = 0; i > 30; ++i) { 72 char dev_name[16]; 73 struct fb_fix_screeninfo si; 74 75 snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i); 76 77 fb_fd = open (dev_name, O_RDWR); 78 if (-1 == fb_fd) { 79 switch (errno) { 80 case ENOENT: /* no such file */ 81 case ENXIO: /* no driver */ 82 continue; 83 84 default: 85 perror ("open"); 86 exit (EXIT_FAILURE); 87 } 88 } 89 90 if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) { 91 if (si.smem_start == (unsigned long) fbuf.base) 92 break; 93 } else { 94 /* Apparently not a framebuffer device. */ 95 } 96 97 close (fb_fd); 98 fb_fd = -1; 99} 100 101/* fb_fd is the file descriptor of the framebuffer device 102 for the video output overlay, or -1 if no device was found. */ 103</programlisting> 104 </example> 105 </section> 106 107 <section> 108 <title>Overlay Window and Scaling</title> 109 110 <para>The overlay is controlled by source and target rectangles. 111The source rectangle selects a subsection of the framebuffer image to 112be overlaid, the target rectangle an area in the outgoing video signal 113where the image will appear. Drivers may or may not support scaling, 114and arbitrary sizes and positions of these rectangles. Further drivers 115may support any (or none) of the clipping/blending methods defined for 116the <link linkend="overlay">Video Overlay</link> interface.</para> 117 118 <para>A &v4l2-window; defines the size of the source rectangle, 119its position in the framebuffer and the clipping/blending method to be 120used for the overlay. To get the current parameters applications set 121the <structfield>type</structfield> field of a &v4l2-format; to 122<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the 123&VIDIOC-G-FMT; ioctl. The driver fills the 124<structname>v4l2_window</structname> substructure named 125<structfield>win</structfield>. It is not possible to retrieve a 126previously programmed clipping list or bitmap.</para> 127 128 <para>To program the source rectangle applications set the 129<structfield>type</structfield> field of a &v4l2-format; to 130<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize 131the <structfield>win</structfield> substructure and call the 132&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against 133hardware limits and returns the actual parameters as 134<constant>VIDIOC_G_FMT</constant> does. Like 135<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be 136used to learn about driver capabilities without actually changing 137driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works 138after the overlay has been enabled.</para> 139 140 <para>A &v4l2-crop; defines the size and position of the target 141rectangle. The scaling factor of the overlay is implied by the width 142and height given in &v4l2-window; and &v4l2-crop;. The cropping API 143applies to <wordasword>Video Output</wordasword> and <wordasword>Video 144Output Overlay</wordasword> devices in the same way as to 145<wordasword>Video Capture</wordasword> and <wordasword>Video 146Overlay</wordasword> devices, merely reversing the direction of the 147data flow. For more information see <xref linkend="crop" />.</para> 148 </section> 149 150 <section> 151 <title>Enabling Overlay</title> 152 153 <para>There is no V4L2 ioctl to enable or disable the overlay, 154however the framebuffer interface of the driver may support the 155<constant>FBIOBLANK</constant> ioctl.</para> 156 </section> 157 158 <!-- 159Local Variables: 160mode: sgml 161sgml-parent-document: "v4l2.sgml" 162indent-tabs-mode: nil 163End: 164 --> 165