0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _osd:
0004
0005 ******************************
0006 Video Output Overlay Interface
0007 ******************************
0008
0009 **Also known as On-Screen Display (OSD)**
0010
0011 Some video output devices can overlay a framebuffer image onto the
0012 outgoing video signal. Applications can set up such an overlay using
0013 this interface, which borrows structures and ioctls of the
0014 :ref:`Video Overlay <overlay>` interface.
0015
0016 The OSD function is accessible through the same character special file
0017 as the :ref:`Video Output <capture>` function.
0018
0019 .. note::
0020
0021 The default function of such a ``/dev/video`` device is video
0022 capturing or output. The OSD function is only available after calling
0023 the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
0024
0025
0026 Querying Capabilities
0027 =====================
0028
0029 Devices supporting the *Video Output Overlay* interface set the
0030 ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
0031 struct :c:type:`v4l2_capability` returned by the
0032 :ref:`VIDIOC_QUERYCAP` ioctl.
0033
0034
0035 Framebuffer
0036 ===========
0037
0038 Contrary to the *Video Overlay* interface the framebuffer is normally
0039 implemented on the TV card and not the graphics card. On Linux it is
0040 accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
0041 applications can find the corresponding framebuffer device by calling
0042 the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst
0043 other information, the physical address of the framebuffer in the
0044 ``base`` field of struct :c:type:`v4l2_framebuffer`.
0045 The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
0046 address in the ``smem_start`` field of struct
0047 :c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
0048 ioctl and struct :c:type:`fb_fix_screeninfo` are defined in
0049 the ``linux/fb.h`` header file.
0050
0051 The width and height of the framebuffer depends on the current video
0052 standard. A V4L2 driver may reject attempts to change the video standard
0053 (or any other ioctl which would imply a framebuffer size change) with an
0054 ``EBUSY`` error code until all applications closed the framebuffer device.
0055
0056 Example: Finding a framebuffer device for OSD
0057 ---------------------------------------------
0058
0059 .. code-block:: c
0060
0061 #include <linux/fb.h>
0062
0063 struct v4l2_framebuffer fbuf;
0064 unsigned int i;
0065 int fb_fd;
0066
0067 if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
0068 perror("VIDIOC_G_FBUF");
0069 exit(EXIT_FAILURE);
0070 }
0071
0072 for (i = 0; i < 30; i++) {
0073 char dev_name[16];
0074 struct fb_fix_screeninfo si;
0075
0076 snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
0077
0078 fb_fd = open(dev_name, O_RDWR);
0079 if (-1 == fb_fd) {
0080 switch (errno) {
0081 case ENOENT: /* no such file */
0082 case ENXIO: /* no driver */
0083 continue;
0084
0085 default:
0086 perror("open");
0087 exit(EXIT_FAILURE);
0088 }
0089 }
0090
0091 if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
0092 if (si.smem_start == (unsigned long)fbuf.base)
0093 break;
0094 } else {
0095 /* Apparently not a framebuffer device. */
0096 }
0097
0098 close(fb_fd);
0099 fb_fd = -1;
0100 }
0101
0102 /* fb_fd is the file descriptor of the framebuffer device
0103 for the video output overlay, or -1 if no device was found. */
0104
0105
0106 Overlay Window and Scaling
0107 ==========================
0108
0109 The overlay is controlled by source and target rectangles. The source
0110 rectangle selects a subsection of the framebuffer image to be overlaid,
0111 the target rectangle an area in the outgoing video signal where the
0112 image will appear. Drivers may or may not support scaling, and arbitrary
0113 sizes and positions of these rectangles. Further drivers may support any
0114 (or none) of the clipping/blending methods defined for the
0115 :ref:`Video Overlay <overlay>` interface.
0116
0117 A struct :c:type:`v4l2_window` defines the size of the
0118 source rectangle, its position in the framebuffer and the
0119 clipping/blending method to be used for the overlay. To get the current
0120 parameters applications set the ``type`` field of a struct
0121 :c:type:`v4l2_format` to
0122 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
0123 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
0124 struct :c:type:`v4l2_window` substructure named ``win``. It is not
0125 possible to retrieve a previously programmed clipping list or bitmap.
0126
0127 To program the source rectangle applications set the ``type`` field of a
0128 struct :c:type:`v4l2_format` to
0129 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
0130 substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
0131 The driver adjusts the parameters against hardware limits and returns
0132 the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
0133 the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
0134 about driver capabilities without actually changing driver state. Unlike
0135 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
0136
0137 A struct :c:type:`v4l2_crop` defines the size and position
0138 of the target rectangle. The scaling factor of the overlay is implied by
0139 the width and height given in struct :c:type:`v4l2_window`
0140 and struct :c:type:`v4l2_crop`. The cropping API applies to
0141 *Video Output* and *Video Output Overlay* devices in the same way as to
0142 *Video Capture* and *Video Overlay* devices, merely reversing the
0143 direction of the data flow. For more information see :ref:`crop`.
0144
0145
0146 Enabling Overlay
0147 ================
0148
0149 There is no V4L2 ioctl to enable or disable the overlay, however the
0150 framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
