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 <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 <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 <linux/fb.h> 234 235struct <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, &fbuf)) { 243 perror ("VIDIOC_G_FBUF"); 244 exit (EXIT_FAILURE); 245} 246 247for (i = 0; i < 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, &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 <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 <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 <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 <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 <A 386HREF="x6570.htm#V4L2-WINDOW" 387>v4l2_window</A 388> and struct <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