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