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