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