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 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="Interfaces" 17HREF="c6488.htm"><LINK 18REL="NEXT" 19TITLE="Video Output Interface" 20HREF="x6831.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="c6488.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="x6831.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="OVERLAY" 77>4.2. Video Overlay Interface</A 78></H1 79><FONT 80COLOR="RED" 81>Also known as Framebuffer Overlay or Previewing</FONT 82><P 83>Video overlay devices have the ability to genlock (TV-)video 84into the (VGA-)video signal of a graphics card, or to store captured 85images directly in video memory of a graphics card, typically with 86clipping. This can be considerable more efficient than capturing 87images and displaying them by other means. In the old days when only 88nuclear power plants needed cooling towers this used to be the only 89way to put live video into a window.</P 90><P 91>Video overlay devices are accessed through the same character 92special files as <A 93HREF="c6488.htm#CAPTURE" 94>video capture</A 95> devices. 96Note the default function of a <TT 97CLASS="FILENAME" 98>/dev/video</TT 99> device 100is video capturing. The overlay function is only available after 101calling the <A 102HREF="r10944.htm" 103><CODE 104CLASS="CONSTANT" 105>VIDIOC_S_FMT</CODE 106></A 107> ioctl.</P 108><P 109>The driver may support simultaneous overlay and capturing 110using the read/write and streaming I/O methods. If so, operation at 111the nominal frame rate of the video standard is not guaranteed. Frames 112may be directed away from overlay to capture, or one field may be used 113for overlay and the other for capture if the capture parameters permit 114this.</P 115><P 116>Applications should use different file descriptors for 117capturing and overlay. This must be supported by all drivers capable 118of simultaneous capturing and overlay. Optionally these drivers may 119also permit capturing and overlay with a single file descriptor for 120compatibility with V4L and earlier versions of V4L2.<A 121NAME="AEN6581" 122HREF="x6570.htm#FTN.AEN6581" 123><SPAN 124CLASS="footnote" 125>[1]</SPAN 126></A 127></P 128><DIV 129CLASS="SECTION" 130><H2 131CLASS="SECTION" 132><A 133NAME="AEN6587" 134>4.2.1. Querying Capabilities</A 135></H2 136><P 137>Devices supporting the video overlay interface set the 138<CODE 139CLASS="CONSTANT" 140>V4L2_CAP_VIDEO_OVERLAY</CODE 141> flag in the 142<CODE 143CLASS="STRUCTFIELD" 144>capabilities</CODE 145> field of struct <A 146HREF="r13105.htm#V4L2-CAPABILITY" 147>v4l2_capability</A 148> 149returned by the <A 150HREF="r13105.htm" 151><CODE 152CLASS="CONSTANT" 153>VIDIOC_QUERYCAP</CODE 154></A 155> ioctl. The overlay I/O method specified 156below must be supported. Tuners and audio inputs are optional.</P 157></DIV 158><DIV 159CLASS="SECTION" 160><H2 161CLASS="SECTION" 162><A 163NAME="AEN6595" 164>4.2.2. Supplemental Functions</A 165></H2 166><P 167>Video overlay devices shall support <A 168HREF="x341.htm" 169>audio input</A 170>, <A 171HREF="x394.htm" 172>tuner</A 173>, <A 174HREF="x542.htm" 175>controls</A 176>, 177<A 178HREF="x1904.htm" 179>cropping and scaling</A 180> and <A 181HREF="x2009.htm" 182>streaming parameter</A 183> ioctls as needed. 184The <A 185HREF="x309.htm" 186>video input</A 187> and <A 188HREF="x448.htm" 189>video standard</A 190> ioctls must be supported by 191all video overlay devices.</P 192></DIV 193><DIV 194CLASS="SECTION" 195><H2 196CLASS="SECTION" 197><A 198NAME="AEN6605" 199>4.2.3. Setup</A 200></H2 201><P 202>Before overlay can commence applications must program the 203driver with frame buffer parameters, namely the address and size of 204the frame buffer and the image format, for example RGB 5:6:5. The 205<A 206HREF="r10595.htm" 207><CODE 208CLASS="CONSTANT" 209>VIDIOC_G_FBUF</CODE 210></A 211> and <A 212HREF="r10595.htm" 213><CODE 214CLASS="CONSTANT" 215>VIDIOC_S_FBUF</CODE 216></A 217> ioctls are available to get 218and set these parameters, respectively. The 219<CODE 220CLASS="CONSTANT" 221>VIDIOC_S_FBUF</CODE 222> ioctl is privileged because it 223allows to set up DMA into physical memory, bypassing the memory 224protection mechanisms of the kernel. Only the superuser can change the 225frame buffer address and size. Users are not supposed to run TV 226applications as root or with SUID bit set. A small helper application 227with suitable privileges should query the graphics system and program 228the V4L2 driver at the appropriate time.</P 229><P 230>Some devices add the video overlay to the output signal 231of the graphics card. In this case the frame buffer is not modified by 232the video device, and the frame buffer address and pixel format are 233not needed by the driver. The <CODE 234CLASS="CONSTANT" 235>VIDIOC_S_FBUF</CODE 236> ioctl 237is not privileged. An application can check for this type of device by 238calling the <CODE 239CLASS="CONSTANT" 240>VIDIOC_G_FBUF</CODE 241> ioctl.</P 242><P 243>A driver may support any (or none) of five clipping/blending 244methods:<P 245></P 246><OL 247TYPE="1" 248><LI 249><P 250>Chroma-keying displays the overlaid image only where 251pixels in the primary graphics surface assume a certain color.</P 252></LI 253><LI 254><P 255>A bitmap can be specified where each bit corresponds 256to a pixel in the overlaid image. When the bit is set, the 257corresponding video pixel is displayed, otherwise a pixel of the 258graphics surface.</P 259></LI 260><LI 261><P 262>A list of clipping rectangles can be specified. In 263these regions <SPAN 264CLASS="emphasis" 265><I 266CLASS="EMPHASIS" 267>no</I 268></SPAN 269> video is displayed, so the 270graphics surface can be seen here.</P 271></LI 272><LI 273><P 274>The framebuffer has an alpha channel that can be used 275to clip or blend the framebuffer with the video.</P 276></LI 277><LI 278><P 279>A global alpha value can be specified to blend the 280framebuffer contents with video images.</P 281></LI 282></OL 283></P 284><P 285>When simultaneous capturing and overlay is supported and 286the hardware prohibits different image and frame buffer formats, the 287format requested first takes precedence. The attempt to capture 288(<A 289HREF="r10944.htm" 290><CODE 291CLASS="CONSTANT" 292>VIDIOC_S_FMT</CODE 293></A 294>) or overlay (<A 295HREF="r10595.htm" 296><CODE 297CLASS="CONSTANT" 298>VIDIOC_S_FBUF</CODE 299></A 300>) may fail with an 301<SPAN 302CLASS="ERRORCODE" 303>EBUSY</SPAN 304> error code or return accordingly modified parameters..</P 305></DIV 306><DIV 307CLASS="SECTION" 308><H2 309CLASS="SECTION" 310><A 311NAME="AEN6635" 312>4.2.4. Overlay Window</A 313></H2 314><P 315>The overlaid image is determined by cropping and overlay 316window parameters. The former select an area of the video picture to 317capture, the latter how images are overlaid and clipped. Cropping 318initialization at minimum requires to reset the parameters to 319defaults. An example is given in <A 320HREF="x1904.htm" 321>Section 1.11</A 322>.</P 323><P 324>The overlay window is described by a struct <A 325HREF="x6570.htm#V4L2-WINDOW" 326>v4l2_window</A 327>. It 328defines the size of the image, its position over the graphics surface 329and the clipping to be applied. To get the current parameters 330applications set the <CODE 331CLASS="STRUCTFIELD" 332>type</CODE 333> field of a 334struct <A 335HREF="r10944.htm#V4L2-FORMAT" 336>v4l2_format</A 337> to <CODE 338CLASS="CONSTANT" 339>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE 340> and 341call the <A 342HREF="r10944.htm" 343><CODE 344CLASS="CONSTANT" 345>VIDIOC_G_FMT</CODE 346></A 347> ioctl. The driver fills the 348<CODE 349CLASS="STRUCTNAME" 350>v4l2_window</CODE 351> substructure named 352<CODE 353CLASS="STRUCTFIELD" 354>win</CODE 355>. It is not possible to retrieve a 356previously programmed clipping list or bitmap.</P 357><P 358>To program the overlay window applications set the 359<CODE 360CLASS="STRUCTFIELD" 361>type</CODE 362> field of a struct <A 363HREF="r10944.htm#V4L2-FORMAT" 364>v4l2_format</A 365> to 366<CODE 367CLASS="CONSTANT" 368>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE 369>, initialize the 370<CODE 371CLASS="STRUCTFIELD" 372>win</CODE 373> substructure and call the 374<A 375HREF="r10944.htm" 376><CODE 377CLASS="CONSTANT" 378>VIDIOC_S_FMT</CODE 379></A 380> ioctl. The driver adjusts the parameters against 381hardware limits and returns the actual parameters as 382<CODE 383CLASS="CONSTANT" 384>VIDIOC_G_FMT</CODE 385> does. Like 386<CODE 387CLASS="CONSTANT" 388>VIDIOC_S_FMT</CODE 389>, the <A 390HREF="r10944.htm" 391><CODE 392CLASS="CONSTANT" 393>VIDIOC_TRY_FMT</CODE 394></A 395> ioctl can be 396used to learn about driver capabilities without actually changing 397driver state. Unlike <CODE 398CLASS="CONSTANT" 399>VIDIOC_S_FMT</CODE 400> this also works 401after the overlay has been enabled.</P 402><P 403>The scaling factor of the overlaid image is implied by the 404width and height given in struct <A 405HREF="x6570.htm#V4L2-WINDOW" 406>v4l2_window</A 407> and the size of the cropping 408rectangle. For more information see <A 409HREF="x1904.htm" 410>Section 1.11</A 411>.</P 412><P 413>When simultaneous capturing and overlay is supported and 414the hardware prohibits different image and window sizes, the size 415requested first takes precedence. The attempt to capture or overlay as 416well (<A 417HREF="r10944.htm" 418><CODE 419CLASS="CONSTANT" 420>VIDIOC_S_FMT</CODE 421></A 422>) may fail with an <SPAN 423CLASS="ERRORCODE" 424>EBUSY</SPAN 425> error code or return accordingly 426modified parameters.</P 427><DIV 428CLASS="TABLE" 429><A 430NAME="V4L2-WINDOW" 431></A 432><P 433><B 434>Table 4-1. struct <CODE 435CLASS="STRUCTNAME" 436>v4l2_window</CODE 437></B 438></P 439><TABLE 440BORDER="0" 441FRAME="void" 442WIDTH="100%" 443CLASS="CALSTABLE" 444><COL 445WIDTH="25%" 446TITLE="C1"><COL 447WIDTH="25%" 448TITLE="C2"><COL 449WIDTH="50%" 450TITLE="C3"><TBODY 451VALIGN="TOP" 452><TR 453><TD 454>struct <A 455HREF="x6570.htm#V4L2-RECT" 456>v4l2_rect</A 457></TD 458><TD 459><CODE 460CLASS="STRUCTFIELD" 461>w</CODE 462></TD 463><TD 464>Size and position of the window relative to the 465top, left corner of the frame buffer defined with <A 466HREF="r10595.htm" 467><CODE 468CLASS="CONSTANT" 469>VIDIOC_S_FBUF</CODE 470></A 471>. The 472window can extend the frame buffer width and height, the 473<CODE 474CLASS="STRUCTFIELD" 475>x</CODE 476> and <CODE 477CLASS="STRUCTFIELD" 478>y</CODE 479> 480coordinates can be negative, and it can lie completely outside the 481frame buffer. The driver clips the window accordingly, or if that is 482not possible, modifies its size and/or position.</TD 483></TR 484><TR 485><TD 486>enum <A 487HREF="x6386.htm#V4L2-FIELD" 488>v4l2_field</A 489></TD 490><TD 491><CODE 492CLASS="STRUCTFIELD" 493>field</CODE 494></TD 495><TD 496>Applications set this field to determine which 497video field shall be overlaid, typically one of 498<CODE 499CLASS="CONSTANT" 500>V4L2_FIELD_ANY</CODE 501> (0), 502<CODE 503CLASS="CONSTANT" 504>V4L2_FIELD_TOP</CODE 505>, 506<CODE 507CLASS="CONSTANT" 508>V4L2_FIELD_BOTTOM</CODE 509> or 510<CODE 511CLASS="CONSTANT" 512>V4L2_FIELD_INTERLACED</CODE 513>. Drivers may have to choose 514a different field order and return the actual setting here.</TD 515></TR 516><TR 517><TD 518>__u32</TD 519><TD 520><CODE 521CLASS="STRUCTFIELD" 522>chromakey</CODE 523></TD 524><TD 525>When chroma-keying has been negotiated with 526<A 527HREF="r10595.htm" 528><CODE 529CLASS="CONSTANT" 530>VIDIOC_S_FBUF</CODE 531></A 532> applications set this field to the desired pixel value 533for the chroma key. The format is the same as the pixel format of the 534framebuffer (struct <A 535HREF="r10595.htm#V4L2-FRAMEBUFFER" 536>v4l2_framebuffer</A 537> 538<CODE 539CLASS="STRUCTFIELD" 540>fmt.pixelformat</CODE 541> field), with bytes in host 542order. E. g. for <A 543HREF="r2492.htm#V4L2-PIX-FMT-BGR32" 544><CODE 545CLASS="CONSTANT" 546>V4L2_PIX_FMT_BGR24</CODE 547></A 548> 549the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big 550endian host.</TD 551></TR 552><TR 553><TD 554>struct <A 555HREF="x6570.htm#V4L2-CLIP" 556>v4l2_clip</A 557> *</TD 558><TD 559><CODE 560CLASS="STRUCTFIELD" 561>clips</CODE 562></TD 563><TD 564>When chroma-keying has <SPAN 565CLASS="emphasis" 566><I 567CLASS="EMPHASIS" 568>not</I 569></SPAN 570> 571been negotiated and <A 572HREF="r10595.htm" 573><CODE 574CLASS="CONSTANT" 575>VIDIOC_G_FBUF</CODE 576></A 577> indicated this capability, 578applications can set this field to point to an array of 579clipping rectangles.</TD 580></TR 581><TR 582><TD 583COLSPAN="3" 584>Like the window coordinates 585<CODE 586CLASS="STRUCTFIELD" 587>w</CODE 588>, clipping rectangles are defined relative 589to the top, left corner of the frame buffer. However clipping 590rectangles must not extend the frame buffer width and height, and they 591must not overlap. If possible applications should merge adjacent 592rectangles. Whether this must create x-y or y-x bands, or the order of 593rectangles, is not defined. When clip lists are not supported the 594driver ignores this field. Its contents after calling <A 595HREF="r10944.htm" 596><CODE 597CLASS="CONSTANT" 598>VIDIOC_S_FMT</CODE 599></A 600> 601are undefined.</TD 602></TR 603><TR 604><TD 605>__u32</TD 606><TD 607><CODE 608CLASS="STRUCTFIELD" 609>clipcount</CODE 610></TD 611><TD 612>When the application set the 613<CODE 614CLASS="STRUCTFIELD" 615>clips</CODE 616> field, this field must contain the 617number of clipping rectangles in the list. When clip lists are not 618supported the driver ignores this field, its contents after calling 619<CODE 620CLASS="CONSTANT" 621>VIDIOC_S_FMT</CODE 622> are undefined. When clip lists are 623supported but no clipping is desired this field must be set to 624zero.</TD 625></TR 626><TR 627><TD 628>void *</TD 629><TD 630><CODE 631CLASS="STRUCTFIELD" 632>bitmap</CODE 633></TD 634><TD 635>When chroma-keying has 636<SPAN 637CLASS="emphasis" 638><I 639CLASS="EMPHASIS" 640>not</I 641></SPAN 642> been negotiated and <A 643HREF="r10595.htm" 644><CODE 645CLASS="CONSTANT" 646>VIDIOC_G_FBUF</CODE 647></A 648> indicated 649this capability, applications can set this field to point to a 650clipping bit mask.</TD 651></TR 652><TR 653><TD 654COLSPAN="3" 655><P 656>It must be of the same size 657as the window, <CODE 658CLASS="STRUCTFIELD" 659>w.width</CODE 660> and 661<CODE 662CLASS="STRUCTFIELD" 663>w.height</CODE 664>. Each bit corresponds to a pixel 665in the overlaid image, which is displayed only when the bit is 666<SPAN 667CLASS="emphasis" 668><I 669CLASS="EMPHASIS" 670>set</I 671></SPAN 672>. Pixel coordinates translate to bits like: 673<PRE 674CLASS="PROGRAMLISTING" 675>((__u8 *) <CODE 676CLASS="STRUCTFIELD" 677>bitmap</CODE 678>)[<CODE 679CLASS="STRUCTFIELD" 680>w.width</CODE 681> * y + x / 8] & (1 << (x & 7))</PRE 682></P 683><P 684>where <CODE 685CLASS="STRUCTFIELD" 686>0</CODE 687> ≤ x < 688<CODE 689CLASS="STRUCTFIELD" 690>w.width</CODE 691> and <CODE 692CLASS="STRUCTFIELD" 693>0</CODE 694> ≤ 695y <<CODE 696CLASS="STRUCTFIELD" 697>w.height</CODE 698>.<SUP 699>a</SUP 700></P 701><P 702>When a clipping 703bit mask is not supported the driver ignores this field, its contents 704after calling <A 705HREF="r10944.htm" 706><CODE 707CLASS="CONSTANT" 708>VIDIOC_S_FMT</CODE 709></A 710> are undefined. When a bit mask is supported 711but no clipping is desired this field must be set to 712<CODE 713CLASS="CONSTANT" 714>NULL</CODE 715>.</P 716><P 717>Applications need not create a 718clip list or bit mask. When they pass both, or despite negotiating 719chroma-keying, the results are undefined. Regardless of the chosen 720method, the clipping abilities of the hardware may be limited in 721quantity or quality. The results when these limits are exceeded are 722undefined.<SUP 723>b</SUP 724></P 725></TD 726></TR 727><TR 728><TD 729>__u8</TD 730><TD 731><CODE 732CLASS="STRUCTFIELD" 733>global_alpha</CODE 734></TD 735><TD 736><P 737>The global alpha value used to blend the 738framebuffer with video images, if global alpha blending has been 739negotiated (<CODE 740CLASS="CONSTANT" 741>V4L2_FBUF_FLAG_GLOBAL_ALPHA</CODE 742>, see 743<A 744HREF="r10595.htm" 745><CODE 746CLASS="CONSTANT" 747>VIDIOC_S_FBUF</CODE 748></A 749>, <A 750HREF="r10595.htm#FRAMEBUFFER-FLAGS" 751>Table 3</A 752>).</P 753><P 754>Note 755this field was added in Linux 2.6.23, extending the structure. However 756the <A 757HREF="r10944.htm" 758>VIDIOC_G/S/TRY_FMT</A 759> ioctls, 760which take a pointer to a <A 761HREF="r10944.htm#V4L2-FORMAT" 762>v4l2_format</A 763> parent structure with padding 764bytes at the end, are not affected.</P 765></TD 766></TR 767></TBODY 768><TR 769><TD 770COLSPAN="3" 771>Notes:<BR><A 772NAME="FTN.AEN6750" 773>a. </A 774>Should we require 775 <CODE 776CLASS="STRUCTFIELD" 777>w.width</CODE 778> to be a multiple of 779 eight?<BR><A 780NAME="FTN.AEN6758" 781>b. </A 782>When the image is written into frame buffer 783memory it will be undesirable if the driver clips out less pixels 784than expected, because the application and graphics system are not 785aware these regions need to be refreshed. The driver should clip out 786more pixels or not write the image at all.<BR></TD 787></TR 788></TABLE 789></DIV 790><DIV 791CLASS="TABLE" 792><A 793NAME="V4L2-CLIP" 794></A 795><P 796><B 797>Table 4-2. struct <CODE 798CLASS="STRUCTNAME" 799>v4l2_clip</CODE 800><A 801NAME="AEN6776" 802HREF="x6570.htm#FTN.AEN6776" 803><SPAN 804CLASS="footnote" 805>[2]</SPAN 806></A 807></B 808></P 809><TABLE 810BORDER="0" 811FRAME="void" 812WIDTH="100%" 813CLASS="CALSTABLE" 814><COL 815WIDTH="25%" 816TITLE="C1"><COL 817WIDTH="25%" 818TITLE="C2"><COL 819WIDTH="50%" 820TITLE="C3"><TBODY 821VALIGN="TOP" 822><TR 823><TD 824>struct <A 825HREF="x6570.htm#V4L2-RECT" 826>v4l2_rect</A 827></TD 828><TD 829><CODE 830CLASS="STRUCTFIELD" 831>c</CODE 832></TD 833><TD 834>Coordinates of the clipping rectangle, relative to 835the top, left corner of the frame buffer. Only window pixels 836<SPAN 837CLASS="emphasis" 838><I 839CLASS="EMPHASIS" 840>outside</I 841></SPAN 842> all clipping rectangles are 843displayed.</TD 844></TR 845><TR 846><TD 847>struct <A 848HREF="x6570.htm#V4L2-CLIP" 849>v4l2_clip</A 850> *</TD 851><TD 852><CODE 853CLASS="STRUCTFIELD" 854>next</CODE 855></TD 856><TD 857>Pointer to the next clipping rectangle, NULL when 858this is the last rectangle. Drivers ignore this field, it cannot be 859used to pass a linked list of clipping rectangles.</TD 860></TR 861></TBODY 862></TABLE 863></DIV 864><DIV 865CLASS="TABLE" 866><A 867NAME="V4L2-RECT" 868></A 869><P 870><B 871>Table 4-3. struct <CODE 872CLASS="STRUCTNAME" 873>v4l2_rect</CODE 874></B 875></P 876><TABLE 877BORDER="0" 878FRAME="void" 879WIDTH="100%" 880CLASS="CALSTABLE" 881><COL 882WIDTH="25%" 883TITLE="C1"><COL 884WIDTH="25%" 885TITLE="C2"><COL 886WIDTH="50%" 887TITLE="C3"><TBODY 888VALIGN="TOP" 889><TR 890><TD 891>__s32</TD 892><TD 893><CODE 894CLASS="STRUCTFIELD" 895>left</CODE 896></TD 897><TD 898>Horizontal offset of the top, left corner of the 899rectangle, in pixels.</TD 900></TR 901><TR 902><TD 903>__s32</TD 904><TD 905><CODE 906CLASS="STRUCTFIELD" 907>top</CODE 908></TD 909><TD 910>Vertical offset of the top, left corner of the 911rectangle, in pixels. Offsets increase to the right and down.</TD 912></TR 913><TR 914><TD 915>__s32</TD 916><TD 917><CODE 918CLASS="STRUCTFIELD" 919>width</CODE 920></TD 921><TD 922>Width of the rectangle, in pixels.</TD 923></TR 924><TR 925><TD 926>__s32</TD 927><TD 928><CODE 929CLASS="STRUCTFIELD" 930>height</CODE 931></TD 932><TD 933>Height of the rectangle, in pixels. Width and 934height cannot be negative, the fields are signed for hysterical 935reasons. </TD 936></TR 937></TBODY 938></TABLE 939></DIV 940></DIV 941><DIV 942CLASS="SECTION" 943><H2 944CLASS="SECTION" 945><A 946NAME="AEN6826" 947>4.2.5. Enabling Overlay</A 948></H2 949><P 950>To start or stop the frame buffer overlay applications call 951the <A 952HREF="r12816.htm" 953><CODE 954CLASS="CONSTANT" 955>VIDIOC_OVERLAY</CODE 956></A 957> ioctl.</P 958></DIV 959></DIV 960><H3 961CLASS="FOOTNOTES" 962>Notes</H3 963><TABLE 964BORDER="0" 965CLASS="FOOTNOTES" 966WIDTH="100%" 967><TR 968><TD 969ALIGN="LEFT" 970VALIGN="TOP" 971WIDTH="5%" 972><A 973NAME="FTN.AEN6581" 974HREF="x6570.htm#AEN6581" 975><SPAN 976CLASS="footnote" 977>[1]</SPAN 978></A 979></TD 980><TD 981ALIGN="LEFT" 982VALIGN="TOP" 983WIDTH="95%" 984><P 985>A common application of two file descriptors is the 986XFree86 <A 987HREF="x16430.htm#XVIDEO" 988>Xv/V4L</A 989> interface driver and 990a V4L2 application. While the X server controls video overlay, the 991application can take advantage of memory mapping and DMA.</P 992><P 993>In the opinion of the designers of this API, no driver 994writer taking the efforts to support simultaneous capturing and 995overlay will restrict this ability by requiring a single file 996descriptor, as in V4L and earlier versions of V4L2. Making this 997optional means applications depending on two file descriptors need 998backup routines to be compatible with all drivers, which is 999considerable more work than using two fds in applications which do 1000not. Also two fd's fit the general concept of one file descriptor for 1001each logical stream. Hence as a complexity trade-off drivers 1002<SPAN 1003CLASS="emphasis" 1004><I 1005CLASS="EMPHASIS" 1006>must</I 1007></SPAN 1008> support two file descriptors and 1009<SPAN 1010CLASS="emphasis" 1011><I 1012CLASS="EMPHASIS" 1013>may</I 1014></SPAN 1015> support single fd operation.</P 1016></TD 1017></TR 1018><TR 1019><TD 1020ALIGN="LEFT" 1021VALIGN="TOP" 1022WIDTH="5%" 1023><A 1024NAME="FTN.AEN6776" 1025HREF="x6570.htm#AEN6776" 1026><SPAN 1027CLASS="footnote" 1028>[2]</SPAN 1029></A 1030></TD 1031><TD 1032ALIGN="LEFT" 1033VALIGN="TOP" 1034WIDTH="95%" 1035><P 1036>The X Window system defines "regions" which are 1037vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 - 1038x1 and height = y2 - y1, so one cannot pass X11 clip lists 1039directly.</P 1040></TD 1041></TR 1042></TABLE 1043><DIV 1044CLASS="NAVFOOTER" 1045><HR 1046ALIGN="LEFT" 1047WIDTH="100%"><TABLE 1048SUMMARY="Footer navigation table" 1049WIDTH="100%" 1050BORDER="0" 1051CELLPADDING="0" 1052CELLSPACING="0" 1053><TR 1054><TD 1055WIDTH="33%" 1056ALIGN="left" 1057VALIGN="top" 1058><A 1059HREF="c6488.htm" 1060ACCESSKEY="P" 1061>Prev</A 1062></TD 1063><TD 1064WIDTH="34%" 1065ALIGN="center" 1066VALIGN="top" 1067><A 1068HREF="book1.htm" 1069ACCESSKEY="H" 1070>Home</A 1071></TD 1072><TD 1073WIDTH="33%" 1074ALIGN="right" 1075VALIGN="top" 1076><A 1077HREF="x6831.htm" 1078ACCESSKEY="N" 1079>Next</A 1080></TD 1081></TR 1082><TR 1083><TD 1084WIDTH="33%" 1085ALIGN="left" 1086VALIGN="top" 1087>Interfaces</TD 1088><TD 1089WIDTH="34%" 1090ALIGN="center" 1091VALIGN="top" 1092><A 1093HREF="c6488.htm" 1094ACCESSKEY="U" 1095>Up</A 1096></TD 1097><TD 1098WIDTH="33%" 1099ALIGN="right" 1100VALIGN="top" 1101>Video Output Interface</TD 1102></TR 1103></TABLE 1104></DIV 1105></BODY 1106></HTML 1107> 1108