123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164 |
- <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:
- -->
|