165 lines
6.0 KiB
XML
165 lines
6.0 KiB
XML
<title>Video Output Overlay Interface</title>
|
|
<subtitle>Also known as On-Screen Display (OSD)</subtitle>
|
|
|
|
<note>
|
|
<title>Experimental</title>
|
|
|
|
<para>This is an <link linkend="experimental">experimental</link>
|
|
interface and may change in the future.</para>
|
|
</note>
|
|
|
|
<para>Some video output devices can overlay a framebuffer image onto
|
|
the outgoing video signal. Applications can set up such an overlay
|
|
using this interface, which borrows structures and ioctls of the <link
|
|
linkend="overlay">Video Overlay</link> interface.</para>
|
|
|
|
<para>The OSD function is accessible through the same character
|
|
special file as the <link linkend="capture">Video Output</link> function.
|
|
Note the default function of such a <filename>/dev/video</filename> device
|
|
is video capturing or output. The OSD function is only available after
|
|
calling the &VIDIOC-S-FMT; ioctl.</para>
|
|
|
|
<section>
|
|
<title>Querying Capabilities</title>
|
|
|
|
<para>Devices supporting the <wordasword>Video Output
|
|
Overlay</wordasword> interface set the
|
|
<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
|
|
<structfield>capabilities</structfield> field of &v4l2-capability;
|
|
returned by the &VIDIOC-QUERYCAP; ioctl.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Framebuffer</title>
|
|
|
|
<para>Contrary to the <wordasword>Video Overlay</wordasword>
|
|
interface the framebuffer is normally implemented on the TV card and
|
|
not the graphics card. On Linux it is accessible as a framebuffer
|
|
device (<filename>/dev/fbN</filename>). Given a V4L2 device,
|
|
applications can find the corresponding framebuffer device by calling
|
|
the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
|
|
physical address of the framebuffer in the
|
|
<structfield>base</structfield> field of &v4l2-framebuffer;. The
|
|
framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
|
|
returns the same address in the <structfield>smem_start</structfield>
|
|
field of struct <structname>fb_fix_screeninfo</structname>. The
|
|
<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
|
|
<structname>fb_fix_screeninfo</structname> are defined in the
|
|
<filename>linux/fb.h</filename> header file.</para>
|
|
|
|
<para>The width and height of the framebuffer depends on the
|
|
current video standard. A V4L2 driver may reject attempts to change
|
|
the video standard (or any other ioctl which would imply a framebuffer
|
|
size change) with an &EBUSY; until all applications closed the
|
|
framebuffer device.</para>
|
|
|
|
<example>
|
|
<title>Finding a framebuffer device for OSD</title>
|
|
|
|
<programlisting>
|
|
#include <linux/fb.h>
|
|
|
|
&v4l2-framebuffer; fbuf;
|
|
unsigned int i;
|
|
int fb_fd;
|
|
|
|
if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) {
|
|
perror ("VIDIOC_G_FBUF");
|
|
exit (EXIT_FAILURE);
|
|
}
|
|
|
|
for (i = 0; i > 30; ++i) {
|
|
char dev_name[16];
|
|
struct fb_fix_screeninfo si;
|
|
|
|
snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);
|
|
|
|
fb_fd = open (dev_name, O_RDWR);
|
|
if (-1 == fb_fd) {
|
|
switch (errno) {
|
|
case ENOENT: /* no such file */
|
|
case ENXIO: /* no driver */
|
|
continue;
|
|
|
|
default:
|
|
perror ("open");
|
|
exit (EXIT_FAILURE);
|
|
}
|
|
}
|
|
|
|
if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) {
|
|
if (si.smem_start == (unsigned long) fbuf.base)
|
|
break;
|
|
} else {
|
|
/* Apparently not a framebuffer device. */
|
|
}
|
|
|
|
close (fb_fd);
|
|
fb_fd = -1;
|
|
}
|
|
|
|
/* fb_fd is the file descriptor of the framebuffer device
|
|
for the video output overlay, or -1 if no device was found. */
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Overlay Window and Scaling</title>
|
|
|
|
<para>The overlay is controlled by source and target rectangles.
|
|
The source rectangle selects a subsection of the framebuffer image to
|
|
be overlaid, the target rectangle an area in the outgoing video signal
|
|
where the image will appear. Drivers may or may not support scaling,
|
|
and arbitrary sizes and positions of these rectangles. Further drivers
|
|
may support any (or none) of the clipping/blending methods defined for
|
|
the <link linkend="overlay">Video Overlay</link> interface.</para>
|
|
|
|
<para>A &v4l2-window; defines the size of the source rectangle,
|
|
its position in the framebuffer and the clipping/blending method to be
|
|
used for the overlay. To get the current parameters applications set
|
|
the <structfield>type</structfield> field of a &v4l2-format; to
|
|
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
|
|
&VIDIOC-G-FMT; ioctl. The driver fills the
|
|
<structname>v4l2_window</structname> substructure named
|
|
<structfield>win</structfield>. It is not possible to retrieve a
|
|
previously programmed clipping list or bitmap.</para>
|
|
|
|
<para>To program the source rectangle applications set the
|
|
<structfield>type</structfield> field of a &v4l2-format; to
|
|
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
|
|
the <structfield>win</structfield> substructure and call the
|
|
&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
|
|
hardware limits and returns the actual parameters as
|
|
<constant>VIDIOC_G_FMT</constant> does. Like
|
|
<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
|
|
used to learn about driver capabilities without actually changing
|
|
driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
|
|
after the overlay has been enabled.</para>
|
|
|
|
<para>A &v4l2-crop; defines the size and position of the target
|
|
rectangle. The scaling factor of the overlay is implied by the width
|
|
and height given in &v4l2-window; and &v4l2-crop;. The cropping API
|
|
applies to <wordasword>Video Output</wordasword> and <wordasword>Video
|
|
Output Overlay</wordasword> devices in the same way as to
|
|
<wordasword>Video Capture</wordasword> and <wordasword>Video
|
|
Overlay</wordasword> devices, merely reversing the direction of the
|
|
data flow. For more information see <xref linkend="crop" />.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Enabling Overlay</title>
|
|
|
|
<para>There is no V4L2 ioctl to enable or disable the overlay,
|
|
however the framebuffer interface of the driver may support the
|
|
<constant>FBIOBLANK</constant> ioctl.</para>
|
|
</section>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-parent-document: "v4l2.sgml"
|
|
indent-tabs-mode: nil
|
|
End:
|
|
-->
|