diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/dev-osd.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/dev-osd.xml | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml new file mode 100644 index 00000000..479d9433 --- /dev/null +++ b/Documentation/DocBook/media/v4l/dev-osd.xml @@ -0,0 +1,156 @@ + <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> |