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