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

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