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/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _osd: 11 12****************************** 13Video Output Overlay Interface 14****************************** 15 16**Also known as On-Screen Display (OSD)** 17 18Some video output devices can overlay a framebuffer image onto the 19outgoing video signal. Applications can set up such an overlay using 20this interface, which borrows structures and ioctls of the 21:ref:`Video Overlay <overlay>` interface. 22 23The OSD function is accessible through the same character special file 24as 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 33Querying Capabilities 34===================== 35 36Devices supporting the *Video Output Overlay* interface set the 37``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of 38struct :c:type:`v4l2_capability` returned by the 39:ref:`VIDIOC_QUERYCAP` ioctl. 40 41 42Framebuffer 43=========== 44 45Contrary to the *Video Overlay* interface the framebuffer is normally 46implemented on the TV card and not the graphics card. On Linux it is 47accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device, 48applications can find the corresponding framebuffer device by calling 49the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst 50other information, the physical address of the framebuffer in the 51``base`` field of struct :c:type:`v4l2_framebuffer`. 52The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same 53address in the ``smem_start`` field of struct 54:c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` 55ioctl and struct :c:type:`fb_fix_screeninfo` are defined in 56the ``linux/fb.h`` header file. 57 58The width and height of the framebuffer depends on the current video 59standard. 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 63Example: 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 113Overlay Window and Scaling 114========================== 115 116The overlay is controlled by source and target rectangles. The source 117rectangle selects a subsection of the framebuffer image to be overlaid, 118the target rectangle an area in the outgoing video signal where the 119image will appear. Drivers may or may not support scaling, and arbitrary 120sizes 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 124A struct :c:type:`v4l2_window` defines the size of the 125source rectangle, its position in the framebuffer and the 126clipping/blending method to be used for the overlay. To get the current 127parameters 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 131struct :c:type:`v4l2_window` substructure named ``win``. It is not 132possible to retrieve a previously programmed clipping list or bitmap. 133 134To program the source rectangle applications set the ``type`` field of a 135struct :c:type:`v4l2_format` to 136``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win`` 137substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. 138The driver adjusts the parameters against hardware limits and returns 139the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, 140the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn 141about 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 144A struct :c:type:`v4l2_crop` defines the size and position 145of the target rectangle. The scaling factor of the overlay is implied by 146the width and height given in struct :c:type:`v4l2_window` 147and 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 150direction of the data flow. For more information see :ref:`crop`. 151 152 153Enabling Overlay 154================ 155 156There is no V4L2 ioctl to enable or disable the overlay, however the 157framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl. 158