About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / dev-osd.xml


Based on kernel version 4.7.2. Page generated on 2016-08-22 22:44 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog