.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _overlay: *********************** Video Overlay Interface *********************** **Also known as Framebuffer Overlay or Previewing.** Video overlay devices have the ability to genlock (TV-)video into the (VGA-)video signal of a graphics card, or to store captured images directly in video memory of a graphics card, typically with clipping. This can be considerable more efficient than capturing images and displaying them by other means. In the old days when only nuclear power plants needed cooling towers this used to be the only way to put live video into a window. Video overlay devices are accessed through the same character special files as :ref:`video capture ` devices. .. note:: The default function of a ``/dev/video`` device is video capturing. The overlay function is only available after calling the :ref:`VIDIOC_S_FMT ` ioctl. The driver may support simultaneous overlay and capturing using the read/write and streaming I/O methods. If so, operation at the nominal frame rate of the video standard is not guaranteed. Frames may be directed away from overlay to capture, or one field may be used for overlay and the other for capture if the capture parameters permit this. Applications should use different file descriptors for capturing and overlay. This must be supported by all drivers capable of simultaneous capturing and overlay. Optionally these drivers may also permit capturing and overlay with a single file descriptor for compatibility with V4L and earlier versions of V4L2. [#f1]_ A common application of two file descriptors is the X11 :ref:`Xv/V4L ` interface driver and a V4L2 application. While the X server controls video overlay, the application can take advantage of memory mapping and DMA. Querying Capabilities ===================== Devices supporting the video overlay interface set the ``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O method specified below must be supported. Tuners and audio inputs are optional. Supplemental Functions ====================== Video overlay devices shall support :ref:`audio input