1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Video Output Overlay Interface</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="devices.html" title="Chapter 4. Interfaces"><link rel="prev" href="output.html" title="Video Output Interface"><link rel="next" href="codec.html" title="Codec Interface"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Video Output Overlay Interface</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="output.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Interfaces</th><td width="20%" align="right"> <a accesskey="n" href="codec.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="osd"></a>Video Output Overlay Interface</h2></div><div><h3 class="subtitle">Also known as On-Screen Display (OSD)</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="osd.html#idp1105326132">Querying Capabilities</a></span></dt><dt><span class="section"><a href="osd.html#idp1105338860">Framebuffer</a></span></dt><dt><span class="section"><a href="osd.html#idp1105406836">Overlay Window and Scaling</a></span></dt><dt><span class="section"><a href="osd.html#idp1105416860">Enabling Overlay</a></span></dt></dl></div><p>Some video output devices can overlay a framebuffer image onto 2the outgoing video signal. Applications can set up such an overlay 3using this interface, which borrows structures and ioctls of the <a class="link" href="overlay.html" title="Video Overlay Interface">Video Overlay</a> interface.</p><p>The OSD function is accessible through the same character 4special file as the <a class="link" href="devices.html#capture" title="Video Capture Interface">Video Output</a> function. 5Note the default function of such a <code class="filename">/dev/video</code> device 6is video capturing or output. The OSD function is only available after 7calling the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105326132"></a>Querying Capabilities</h3></div></div></div><p>Devices supporting the <em class="wordasword">Video Output 8Overlay</em> interface set the 9<code class="constant">V4L2_CAP_VIDEO_OUTPUT_OVERLAY</code> flag in the 10<em class="structfield"><code>capabilities</code></em> field of struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a> 11returned by the <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a> ioctl.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105338860"></a>Framebuffer</h3></div></div></div><p>Contrary to the <em class="wordasword">Video Overlay</em> 12interface the framebuffer is normally implemented on the TV card and 13not the graphics card. On Linux it is accessible as a framebuffer 14device (<code class="filename">/dev/fbN</code>). Given a V4L2 device, 15applications can find the corresponding framebuffer device by calling 16the <a class="link" href="vidioc-g-fbuf.html" title="ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF"><code class="constant">VIDIOC_G_FBUF</code></a> ioctl. It returns, amongst other information, the 17physical address of the framebuffer in the 18<em class="structfield"><code>base</code></em> field of struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a>. The 19framebuffer device ioctl <code class="constant">FBIOGET_FSCREENINFO</code> 20returns the same address in the <em class="structfield"><code>smem_start</code></em> 21field of struct <span class="structname">fb_fix_screeninfo</span>. The 22<code class="constant">FBIOGET_FSCREENINFO</code> ioctl and struct 23<span class="structname">fb_fix_screeninfo</span> are defined in the 24<code class="filename">linux/fb.h</code> header file.</p><p>The width and height of the framebuffer depends on the 25current video standard. A V4L2 driver may reject attempts to change 26the video standard (or any other ioctl which would imply a framebuffer 27size change) with an <span class="errorcode">EBUSY</span> error code until all applications closed the 28framebuffer device.</p><div class="example"><a name="idp1105403988"></a><p class="title"><b>Example 4.1. Finding a framebuffer device for OSD</b></p><div class="example-contents"><pre class="programlisting"> 29#include <linux/fb.h> 30 31struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a> fbuf; 32unsigned int i; 33int fb_fd; 34 35if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) { 36 perror("VIDIOC_G_FBUF"); 37 exit(EXIT_FAILURE); 38} 39 40for (i = 0; i < 30; i++) { 41 char dev_name[16]; 42 struct fb_fix_screeninfo si; 43 44 snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i); 45 46 fb_fd = open(dev_name, O_RDWR); 47 if (-1 == fb_fd) { 48 switch (errno) { 49 case ENOENT: /* no such file */ 50 case ENXIO: /* no driver */ 51 continue; 52 53 default: 54 perror("open"); 55 exit(EXIT_FAILURE); 56 } 57 } 58 59 if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) { 60 if (si.smem_start == (unsigned long)fbuf.base) 61 break; 62 } else { 63 /* Apparently not a framebuffer device. */ 64 } 65 66 close(fb_fd); 67 fb_fd = -1; 68} 69 70/* fb_fd is the file descriptor of the framebuffer device 71 for the video output overlay, or -1 if no device was found. */ 72</pre></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105406836"></a>Overlay Window and Scaling</h3></div></div></div><p>The overlay is controlled by source and target rectangles. 73The source rectangle selects a subsection of the framebuffer image to 74be overlaid, the target rectangle an area in the outgoing video signal 75where the image will appear. Drivers may or may not support scaling, 76and arbitrary sizes and positions of these rectangles. Further drivers 77may support any (or none) of the clipping/blending methods defined for 78the <a class="link" href="overlay.html" title="Video Overlay Interface">Video Overlay</a> interface.</p><p>A struct <a class="link" href="overlay.html#v4l2-window" title="Table 4.1. struct v4l2_window">v4l2_window</a> defines the size of the source rectangle, 79its position in the framebuffer and the clipping/blending method to be 80used for the overlay. To get the current parameters applications set 81the <em class="structfield"><code>type</code></em> field of a struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> to 82<code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</code> and call the 83<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> ioctl. The driver fills the 84<span class="structname">v4l2_window</span> substructure named 85<em class="structfield"><code>win</code></em>. It is not possible to retrieve a 86previously programmed clipping list or bitmap.</p><p>To program the source rectangle applications set the 87<em class="structfield"><code>type</code></em> field of a struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> to 88<code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</code>, initialize 89the <em class="structfield"><code>win</code></em> substructure and call the 90<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl. The driver adjusts the parameters against 91hardware limits and returns the actual parameters as 92<code class="constant">VIDIOC_G_FMT</code> does. Like 93<code class="constant">VIDIOC_S_FMT</code>, the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_TRY_FMT</code></a> ioctl can be 94used to learn about driver capabilities without actually changing 95driver state. Unlike <code class="constant">VIDIOC_S_FMT</code> this also works 96after the overlay has been enabled.</p><p>A struct <a class="link" href="vidioc-g-crop.html#v4l2-crop" title="Table A.55. struct v4l2_crop">v4l2_crop</a> defines the size and position of the target 97rectangle. The scaling factor of the overlay is implied by the width 98and height given in struct <a class="link" href="overlay.html#v4l2-window" title="Table 4.1. struct v4l2_window">v4l2_window</a> and struct <a class="link" href="vidioc-g-crop.html#v4l2-crop" title="Table A.55. struct v4l2_crop">v4l2_crop</a>. The cropping API 99applies to <em class="wordasword">Video Output</em> and <em class="wordasword">Video 100Output Overlay</em> devices in the same way as to 101<em class="wordasword">Video Capture</em> and <em class="wordasword">Video 102Overlay</em> devices, merely reversing the direction of the 103data flow. For more information see <a class="xref" href="crop.html" title="Image Cropping, Insertion and Scaling">the section called “Image Cropping, Insertion and Scaling”</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105416860"></a>Enabling Overlay</h3></div></div></div><p>There is no V4L2 ioctl to enable or disable the overlay, 104however the framebuffer interface of the driver may support the 105<code class="constant">FBIOBLANK</code> ioctl.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="output.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="devices.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="codec.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Video Output Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Codec Interface</td></tr></table></div></body></html> 106