• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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.&nbsp;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&nbsp;<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] &amp; (1 &lt;&lt; (x &amp; 7))</PRE
682></P
683><P
684>where <CODE
685CLASS="STRUCTFIELD"
686>0</CODE
687> &le; x &lt;
688<CODE
689CLASS="STRUCTFIELD"
690>w.width</CODE
691> and <CODE
692CLASS="STRUCTFIELD"
693>0</CODE
694> &le;
695y &lt;<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&nbsp;<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&nbsp;<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