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   <para>Some video output devices can overlay a framebuffer image onto
   5 the outgoing video signal. Applications can set up such an overlay
   6 using this interface, which borrows structures and ioctls of the <link
   7 linkend="overlay">Video Overlay</link> interface.</para>
   8
   9   <para>The OSD function is accessible through the same character
  10 special file as the <link linkend="capture">Video Output</link> function.
  11 Note the default function of such a <filename>/dev/video</filename> device
  12 is video capturing or output. The OSD function is only available after
  13 calling the &VIDIOC-S-FMT; ioctl.</para>
  14
  15   <section>
  16     <title>Querying Capabilities</title>
  17
  18     <para>Devices supporting the <wordasword>Video Output
  19 Overlay</wordasword> interface set the
  20 <constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
  21 <structfield>capabilities</structfield> field of &v4l2-capability;
  22 returned by the &VIDIOC-QUERYCAP; ioctl.</para>
  23   </section>
  24
  25   <section>
  26     <title>Framebuffer</title>
  27
  28     <para>Contrary to the <wordasword>Video Overlay</wordasword>
  29 interface the framebuffer is normally implemented on the TV card and
  30 not the graphics card. On Linux it is accessible as a framebuffer
  31 device (<filename>/dev/fbN</filename>). Given a V4L2 device,
  32 applications can find the corresponding framebuffer device by calling
  33 the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
  34 physical address of the framebuffer in the
  35 <structfield>base</structfield> field of &v4l2-framebuffer;. The
  36 framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
  37 returns the same address in the <structfield>smem_start</structfield>
  38 field of struct <structname>fb_fix_screeninfo</structname>. The
  39 <constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
  40 <structname>fb_fix_screeninfo</structname> are defined in the
  41 <filename>linux/fb.h</filename> header file.</para>
  42
  43     <para>The width and height of the framebuffer depends on the
  44 current video standard. A V4L2 driver may reject attempts to change
  45 the video standard (or any other ioctl which would imply a framebuffer
  46 size change) with an &EBUSY; until all applications closed the
  47 framebuffer device.</para>
  48
  49     <example>
  50       <title>Finding a framebuffer device for OSD</title>
  51
  52       <programlisting>
  53 #include &lt;linux/fb.h&gt;
  54
  55 &v4l2-framebuffer; fbuf;
  56 unsigned int i;
  57 int fb_fd;
  58
  59 if (-1 == ioctl(fd, VIDIOC_G_FBUF, &amp;fbuf)) {
  60         perror("VIDIOC_G_FBUF");
  61         exit(EXIT_FAILURE);
  62 }
  63
  64 for (i = 0; i &lt; 30; i++) {
  65         char dev_name[16];
  66         struct fb_fix_screeninfo si;
  67
  68         snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
  69
  70         fb_fd = open(dev_name, O_RDWR);
  71         if (-1 == fb_fd) {
  72                 switch (errno) {
  73                 case ENOENT: /* no such file */
  74                 case ENXIO:  /* no driver */
  75                         continue;
  76
  77                 default:
  78                         perror("open");
  79                         exit(EXIT_FAILURE);
  80                 }
  81         }
  82
  83         if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
  84                 if (si.smem_start == (unsigned long)fbuf.base)
  85                         break;
  86         } else {
  87                 /* Apparently not a framebuffer device. */
  88         }
  89
  90         close(fb_fd);
  91         fb_fd = -1;
  92 }
  93
  94 /* fb_fd is the file descriptor of the framebuffer device
  95    for the video output overlay, or -1 if no device was found. */
  96 </programlisting>
  97     </example>
  98   </section>
  99
 100   <section>
 101     <title>Overlay Window and Scaling</title>
 102
 103     <para>The overlay is controlled by source and target rectangles.
 104 The source rectangle selects a subsection of the framebuffer image to
 105 be overlaid, the target rectangle an area in the outgoing video signal
 106 where the image will appear. Drivers may or may not support scaling,
 107 and arbitrary sizes and positions of these rectangles. Further drivers
 108 may support any (or none) of the clipping/blending methods defined for
 109 the <link linkend="overlay">Video Overlay</link> interface.</para>
 110
 111     <para>A &v4l2-window; defines the size of the source rectangle,
 112 its position in the framebuffer and the clipping/blending method to be
 113 used for the overlay. To get the current parameters applications set
 114 the <structfield>type</structfield> field of a &v4l2-format; to
 115 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
 116 &VIDIOC-G-FMT; ioctl. The driver fills the
 117 <structname>v4l2_window</structname> substructure named
 118 <structfield>win</structfield>. It is not possible to retrieve a
 119 previously programmed clipping list or bitmap.</para>
 120
 121     <para>To program the source rectangle applications set the
 122 <structfield>type</structfield> field of a &v4l2-format; to
 123 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
 124 the <structfield>win</structfield> substructure and call the
 125 &VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
 126 hardware limits and returns the actual parameters as
 127 <constant>VIDIOC_G_FMT</constant> does. Like
 128 <constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
 129 used to learn about driver capabilities without actually changing
 130 driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
 131 after the overlay has been enabled.</para>
 132
 133     <para>A &v4l2-crop; defines the size and position of the target
 134 rectangle. The scaling factor of the overlay is implied by the width
 135 and height given in &v4l2-window; and &v4l2-crop;. The cropping API
 136 applies to <wordasword>Video Output</wordasword> and <wordasword>Video
 137 Output Overlay</wordasword> devices in the same way as to
 138 <wordasword>Video Capture</wordasword> and <wordasword>Video
 139 Overlay</wordasword> devices, merely reversing the direction of the
 140 data flow. For more information see <xref linkend="crop" />.</para>
 141   </section>
 142
 143   <section>
 144     <title>Enabling Overlay</title>
 145
 146     <para>There is no V4L2 ioctl to enable or disable the overlay,
 147 however the framebuffer interface of the driver may support the
 148 <constant>FBIOBLANK</constant> ioctl.</para>
 149   </section>