Documentation/media/uapi/v4l/dev-osd.rst

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