327 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _overlay:4 5***********************6Video Overlay Interface7***********************8 9**Also known as Framebuffer Overlay or Previewing.**10 11Video overlay devices have the ability to genlock (TV-)video into the12(VGA-)video signal of a graphics card, or to store captured images13directly in video memory of a graphics card, typically with clipping.14This can be considerable more efficient than capturing images and15displaying them by other means. In the old days when only nuclear power16plants needed cooling towers this used to be the only way to put live17video into a window.18 19Video overlay devices are accessed through the same character special20files as :ref:`video capture <capture>` devices.21 22.. note::23 24 The default function of a ``/dev/video`` device is video25 capturing. The overlay function is only available after calling26 the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.27 28The driver may support simultaneous overlay and capturing using the29read/write and streaming I/O methods. If so, operation at the nominal30frame rate of the video standard is not guaranteed. Frames may be31directed away from overlay to capture, or one field may be used for32overlay and the other for capture if the capture parameters permit this.33 34Applications should use different file descriptors for capturing and35overlay. This must be supported by all drivers capable of simultaneous36capturing and overlay. Optionally these drivers may also permit37capturing and overlay with a single file descriptor for compatibility38with V4L and earlier versions of V4L2. [#f1]_39 40A common application of two file descriptors is the X1141:ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.42While the X server controls video overlay, the application can take43advantage of memory mapping and DMA.44 45Querying Capabilities46=====================47 48Devices supporting the video overlay interface set the49``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct50:c:type:`v4l2_capability` returned by the51:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O52method specified below must be supported. Tuners and audio inputs are53optional.54 55 56Supplemental Functions57======================58 59Video overlay devices shall support :ref:`audio input <audio>`,60:ref:`tuner`, :ref:`controls <control>`,61:ref:`cropping and scaling <crop>` and62:ref:`streaming parameter <streaming-par>` ioctls as needed. The63:ref:`video input <video>` and :ref:`video standard <standard>`64ioctls must be supported by all video overlay devices.65 66 67Setup68=====69 70*Note: support for this has been removed.*71Before overlay can commence applications must program the driver with72frame buffer parameters, namely the address and size of the frame buffer73and the image format, for example RGB 5:6:5. The74:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and75:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and76set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is77privileged because it allows to set up DMA into physical memory,78bypassing the memory protection mechanisms of the kernel. Only the79superuser can change the frame buffer address and size. Users are not80supposed to run TV applications as root or with SUID bit set. A small81helper application with suitable privileges should query the graphics82system and program the V4L2 driver at the appropriate time.83 84Some devices add the video overlay to the output signal of the graphics85card. In this case the frame buffer is not modified by the video device,86and the frame buffer address and pixel format are not needed by the87driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application88can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`89ioctl.90 91A driver may support any (or none) of five clipping/blending methods:92 931. Chroma-keying displays the overlaid image only where pixels in the94 primary graphics surface assume a certain color.95 962. *Note: support for this has been removed.*97 A bitmap can be specified where each bit corresponds to a pixel in98 the overlaid image. When the bit is set, the corresponding video99 pixel is displayed, otherwise a pixel of the graphics surface.100 1013. *Note: support for this has been removed.*102 A list of clipping rectangles can be specified. In these regions *no*103 video is displayed, so the graphics surface can be seen here.104 1054. The framebuffer has an alpha channel that can be used to clip or106 blend the framebuffer with the video.107 1085. A global alpha value can be specified to blend the framebuffer109 contents with video images.110 111When simultaneous capturing and overlay is supported and the hardware112prohibits different image and frame buffer formats, the format requested113first takes precedence. The attempt to capture114(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay115(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error116code or return accordingly modified parameters..117 118 119Overlay Window120==============121 122The overlaid image is determined by cropping and overlay window123parameters. The former select an area of the video picture to capture,124the latter how images are overlaid and clipped. Cropping initialization125at minimum requires to reset the parameters to defaults. An example is126given in :ref:`crop`.127 128The overlay window is described by a struct129:c:type:`v4l2_window`. It defines the size of the image,130its position over the graphics surface and the clipping to be applied.131To get the current parameters applications set the ``type`` field of a132struct :c:type:`v4l2_format` to133``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the134:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the135struct :c:type:`v4l2_window` substructure named ``win``. It is not136possible to retrieve a previously programmed clipping list or bitmap.137 138To program the overlay window applications set the ``type`` field of a139struct :c:type:`v4l2_format` to140``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and141call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver142adjusts the parameters against hardware limits and returns the actual143parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the144:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn145about driver capabilities without actually changing driver state. Unlike146:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.147 148The scaling factor of the overlaid image is implied by the width and149height given in struct :c:type:`v4l2_window` and the size150of the cropping rectangle. For more information see :ref:`crop`.151 152When simultaneous capturing and overlay is supported and the hardware153prohibits different image and window sizes, the size requested first154takes precedence. The attempt to capture or overlay as well155(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error156code or return accordingly modified parameters.157 158 159.. c:type:: v4l2_window160 161struct v4l2_window162------------------163 164``struct v4l2_rect w``165 Size and position of the window relative to the top, left corner of166 the frame buffer defined with167 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the168 frame buffer width and height, the ``x`` and ``y`` coordinates can169 be negative, and it can lie completely outside the frame buffer. The170 driver clips the window accordingly, or if that is not possible,171 modifies its size and/or position.172 173``enum v4l2_field field``174 Applications set this field to determine which video field shall be175 overlaid, typically one of ``V4L2_FIELD_ANY`` (0),176 ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or177 ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different178 field order and return the actual setting here.179 180``__u32 chromakey``181 When chroma-keying has been negotiated with182 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field183 to the desired pixel value for the chroma key. The format is the184 same as the pixel format of the framebuffer (struct185 :c:type:`v4l2_framebuffer` ``fmt.pixelformat``186 field), with bytes in host order. E. g. for187 :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should188 be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.189 190``struct v4l2_clip * clips``191 *Note: support for this has been removed.*192 When chroma-keying has *not* been negotiated and193 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,194 applications can set this field to point to an array of clipping195 rectangles.196 197 Like the window coordinates w, clipping rectangles are defined198 relative to the top, left corner of the frame buffer. However199 clipping rectangles must not extend the frame buffer width and200 height, and they must not overlap. If possible applications201 should merge adjacent rectangles. Whether this must create202 x-y or y-x bands, or the order of rectangles, is not defined. When203 clip lists are not supported the driver ignores this field. Its204 contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`205 are undefined.206 207``__u32 clipcount``208 *Note: support for this has been removed.*209 When the application set the ``clips`` field, this field must210 contain the number of clipping rectangles in the list. When clip211 lists are not supported the driver ignores this field, its contents212 after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are213 supported but no clipping is desired this field must be set to zero.214 215``void * bitmap``216 *Note: support for this has been removed.*217 When chroma-keying has *not* been negotiated and218 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,219 applications can set this field to point to a clipping bit mask.220 221It must be of the same size as the window, ``w.width`` and ``w.height``.222Each bit corresponds to a pixel in the overlaid image, which is223displayed only when the bit is *set*. Pixel coordinates translate to224bits like:225 226 227.. code-block:: c228 229 ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))230 231where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_232 233When a clipping bit mask is not supported the driver ignores this field,234its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are235undefined. When a bit mask is supported but no clipping is desired this236field must be set to ``NULL``.237 238Applications need not create a clip list or bit mask. When they pass239both, or despite negotiating chroma-keying, the results are undefined.240Regardless of the chosen method, the clipping abilities of the hardware241may be limited in quantity or quality. The results when these limits are242exceeded are undefined. [#f3]_243 244``__u8 global_alpha``245 The global alpha value used to blend the framebuffer with video246 images, if global alpha blending has been negotiated247 (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see248 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,249 :ref:`framebuffer-flags`).250 251.. note::252 253 This field was added in Linux 2.6.23, extending the254 structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`255 ioctls, which take a pointer to a :c:type:`v4l2_format`256 parent structure with padding bytes at the end, are not affected.257 258 259.. c:type:: v4l2_clip260 261struct v4l2_clip [#f4]_262-----------------------263 264``struct v4l2_rect c``265 Coordinates of the clipping rectangle, relative to the top, left266 corner of the frame buffer. Only window pixels *outside* all267 clipping rectangles are displayed.268 269``struct v4l2_clip * next``270 Pointer to the next clipping rectangle, ``NULL`` when this is the last271 rectangle. Drivers ignore this field, it cannot be used to pass a272 linked list of clipping rectangles.273 274 275.. c:type:: v4l2_rect276 277struct v4l2_rect278----------------279 280``__s32 left``281 Horizontal offset of the top, left corner of the rectangle, in282 pixels.283 284``__s32 top``285 Vertical offset of the top, left corner of the rectangle, in pixels.286 Offsets increase to the right and down.287 288``__u32 width``289 Width of the rectangle, in pixels.290 291``__u32 height``292 Height of the rectangle, in pixels.293 294 295Enabling Overlay296================297 298To start or stop the frame buffer overlay applications call the299:ref:`VIDIOC_OVERLAY` ioctl.300 301.. [#f1]302 In the opinion of the designers of this API, no driver writer taking303 the efforts to support simultaneous capturing and overlay will304 restrict this ability by requiring a single file descriptor, as in305 V4L and earlier versions of V4L2. Making this optional means306 applications depending on two file descriptors need backup routines307 to be compatible with all drivers, which is considerable more work308 than using two fds in applications which do not. Also two fd's fit309 the general concept of one file descriptor for each logical stream.310 Hence as a complexity trade-off drivers *must* support two file311 descriptors and *may* support single fd operation.312 313.. [#f2]314 Should we require ``w.width`` to be a multiple of eight?315 316.. [#f3]317 When the image is written into frame buffer memory it will be318 undesirable if the driver clips out less pixels than expected,319 because the application and graphics system are not aware these320 regions need to be refreshed. The driver should clip out more pixels321 or not write the image at all.322 323.. [#f4]324 The X Window system defines "regions" which are vectors of ``struct325 BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and326 ``height = y2 - y1``, so one cannot pass X11 clip lists directly.327