Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <title>Video Output Overlay Interface</title> |
2 | <subtitle>Also known as On-Screen Display (OSD)</subtitle> | |
3 | ||
4 | <note> | |
5 | <title>Experimental</title> | |
6 | ||
7 | <para>This is an <link linkend="experimental">experimental</link> | |
8 | interface and may change in the future.</para> | |
9 | </note> | |
10 | ||
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> | |
15 | ||
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> | |
21 | ||
22 | <section> | |
23 | <title>Querying Capabilities</title> | |
24 | ||
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> | |
30 | </section> | |
31 | ||
32 | <section> | |
33 | <title>Framebuffer</title> | |
34 | ||
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> | |
49 | ||
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> | |
55 | ||
56 | <example> | |
57 | <title>Finding a framebuffer device for OSD</title> | |
58 | ||
59 | <programlisting> | |
60 | #include <linux/fb.h> | |
61 | ||
62 | &v4l2-framebuffer; fbuf; | |
63 | unsigned int i; | |
64 | int fb_fd; | |
65 | ||
66 | if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) { | |
67 | perror ("VIDIOC_G_FBUF"); | |
68 | exit (EXIT_FAILURE); | |
69 | } | |
70 | ||
71 | for (i = 0; i > 30; ++i) { | |
72 | char dev_name[16]; | |
73 | struct fb_fix_screeninfo si; | |
74 | ||
75 | snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i); | |
76 | ||
77 | fb_fd = open (dev_name, O_RDWR); | |
78 | if (-1 == fb_fd) { | |
79 | switch (errno) { | |
80 | case ENOENT: /* no such file */ | |
81 | case ENXIO: /* no driver */ | |
82 | continue; | |
83 | ||
84 | default: | |
85 | perror ("open"); | |
86 | exit (EXIT_FAILURE); | |
87 | } | |
88 | } | |
89 | ||
90 | if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) { | |
91 | if (si.smem_start == (unsigned long) fbuf.base) | |
92 | break; | |
93 | } else { | |
94 | /* Apparently not a framebuffer device. */ | |
95 | } | |
96 | ||
97 | close (fb_fd); | |
98 | fb_fd = -1; | |
99 | } | |
100 | ||
101 | /* fb_fd is the file descriptor of the framebuffer device | |
102 | for the video output overlay, or -1 if no device was found. */ | |
103 | </programlisting> | |
104 | </example> | |
105 | </section> | |
106 | ||
107 | <section> | |
108 | <title>Overlay Window and Scaling</title> | |
109 | ||
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> | |
117 | ||
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> | |
127 | ||
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> | |
139 | ||
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> | |
148 | </section> | |
149 | ||
150 | <section> | |
151 | <title>Enabling Overlay</title> | |
152 | ||
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> | |
156 | </section> |