Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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> |
| 157 | |
| 158 | <!-- |
| 159 | Local Variables: |
| 160 | mode: sgml |
| 161 | sgml-parent-document: "v4l2.sgml" |
| 162 | indent-tabs-mode: nil |
| 163 | End: |
| 164 | --> |