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