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

   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 &lt;linux/fb.h&gt;
  61
  62 &v4l2-framebuffer; fbuf;
  63 unsigned int i;
  64 int fb_fd;
  65
  66 if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
  67         perror ("VIDIOC_G_FBUF");
  68         exit (EXIT_FAILURE);
  69 }
  70
  71 for (i = 0; i &gt; 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, &amp;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   -->