1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _overlay: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab*********************** 654f38fcaSMauro Carvalho ChehabVideo Overlay Interface 754f38fcaSMauro Carvalho Chehab*********************** 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho Chehab**Also known as Framebuffer Overlay or Previewing.** 1054f38fcaSMauro Carvalho Chehab 1154f38fcaSMauro Carvalho ChehabVideo overlay devices have the ability to genlock (TV-)video into the 1254f38fcaSMauro Carvalho Chehab(VGA-)video signal of a graphics card, or to store captured images 1354f38fcaSMauro Carvalho Chehabdirectly in video memory of a graphics card, typically with clipping. 1454f38fcaSMauro Carvalho ChehabThis can be considerable more efficient than capturing images and 1554f38fcaSMauro Carvalho Chehabdisplaying them by other means. In the old days when only nuclear power 1654f38fcaSMauro Carvalho Chehabplants needed cooling towers this used to be the only way to put live 1754f38fcaSMauro Carvalho Chehabvideo into a window. 1854f38fcaSMauro Carvalho Chehab 1954f38fcaSMauro Carvalho ChehabVideo overlay devices are accessed through the same character special 2054f38fcaSMauro Carvalho Chehabfiles as :ref:`video capture <capture>` devices. 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho Chehab.. note:: 2354f38fcaSMauro Carvalho Chehab 2454f38fcaSMauro Carvalho Chehab The default function of a ``/dev/video`` device is video 2554f38fcaSMauro Carvalho Chehab capturing. The overlay function is only available after calling 2654f38fcaSMauro Carvalho Chehab the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho ChehabThe driver may support simultaneous overlay and capturing using the 2954f38fcaSMauro Carvalho Chehabread/write and streaming I/O methods. If so, operation at the nominal 3054f38fcaSMauro Carvalho Chehabframe rate of the video standard is not guaranteed. Frames may be 3154f38fcaSMauro Carvalho Chehabdirected away from overlay to capture, or one field may be used for 3254f38fcaSMauro Carvalho Chehaboverlay and the other for capture if the capture parameters permit this. 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho ChehabApplications should use different file descriptors for capturing and 3554f38fcaSMauro Carvalho Chehaboverlay. This must be supported by all drivers capable of simultaneous 3654f38fcaSMauro Carvalho Chehabcapturing and overlay. Optionally these drivers may also permit 3754f38fcaSMauro Carvalho Chehabcapturing and overlay with a single file descriptor for compatibility 3854f38fcaSMauro Carvalho Chehabwith V4L and earlier versions of V4L2. [#f1]_ 3954f38fcaSMauro Carvalho Chehab 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabQuerying Capabilities 4254f38fcaSMauro Carvalho Chehab===================== 4354f38fcaSMauro Carvalho Chehab 4454f38fcaSMauro Carvalho ChehabDevices supporting the video overlay interface set the 4554f38fcaSMauro Carvalho Chehab``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct 4654f38fcaSMauro Carvalho Chehab:c:type:`v4l2_capability` returned by the 4754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O 4854f38fcaSMauro Carvalho Chehabmethod specified below must be supported. Tuners and audio inputs are 4954f38fcaSMauro Carvalho Chehaboptional. 5054f38fcaSMauro Carvalho Chehab 5154f38fcaSMauro Carvalho Chehab 5254f38fcaSMauro Carvalho ChehabSupplemental Functions 5354f38fcaSMauro Carvalho Chehab====================== 5454f38fcaSMauro Carvalho Chehab 5554f38fcaSMauro Carvalho ChehabVideo overlay devices shall support :ref:`audio input <audio>`, 5654f38fcaSMauro Carvalho Chehab:ref:`tuner`, :ref:`controls <control>`, 5754f38fcaSMauro Carvalho Chehab:ref:`cropping and scaling <crop>` and 5854f38fcaSMauro Carvalho Chehab:ref:`streaming parameter <streaming-par>` ioctls as needed. The 5954f38fcaSMauro Carvalho Chehab:ref:`video input <video>` and :ref:`video standard <standard>` 6054f38fcaSMauro Carvalho Chehabioctls must be supported by all video overlay devices. 6154f38fcaSMauro Carvalho Chehab 6254f38fcaSMauro Carvalho Chehab 6354f38fcaSMauro Carvalho ChehabSetup 6454f38fcaSMauro Carvalho Chehab===== 6554f38fcaSMauro Carvalho Chehab 6654f38fcaSMauro Carvalho ChehabBefore overlay can commence applications must program the driver with 6754f38fcaSMauro Carvalho Chehabframe buffer parameters, namely the address and size of the frame buffer 6854f38fcaSMauro Carvalho Chehaband the image format, for example RGB 5:6:5. The 6954f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and 7054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and 7154f38fcaSMauro Carvalho Chehabset these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is 7254f38fcaSMauro Carvalho Chehabprivileged because it allows to set up DMA into physical memory, 7354f38fcaSMauro Carvalho Chehabbypassing the memory protection mechanisms of the kernel. Only the 7454f38fcaSMauro Carvalho Chehabsuperuser can change the frame buffer address and size. Users are not 7554f38fcaSMauro Carvalho Chehabsupposed to run TV applications as root or with SUID bit set. A small 7654f38fcaSMauro Carvalho Chehabhelper application with suitable privileges should query the graphics 7754f38fcaSMauro Carvalho Chehabsystem and program the V4L2 driver at the appropriate time. 7854f38fcaSMauro Carvalho Chehab 7954f38fcaSMauro Carvalho ChehabSome devices add the video overlay to the output signal of the graphics 8054f38fcaSMauro Carvalho Chehabcard. In this case the frame buffer is not modified by the video device, 8154f38fcaSMauro Carvalho Chehaband the frame buffer address and pixel format are not needed by the 8254f38fcaSMauro Carvalho Chehabdriver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application 8354f38fcaSMauro Carvalho Chehabcan check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 8454f38fcaSMauro Carvalho Chehabioctl. 8554f38fcaSMauro Carvalho Chehab 8654f38fcaSMauro Carvalho ChehabA driver may support any (or none) of five clipping/blending methods: 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab1. Chroma-keying displays the overlaid image only where pixels in the 8954f38fcaSMauro Carvalho Chehab primary graphics surface assume a certain color. 9054f38fcaSMauro Carvalho Chehab 9154f38fcaSMauro Carvalho Chehab2. A bitmap can be specified where each bit corresponds to a pixel in 9254f38fcaSMauro Carvalho Chehab the overlaid image. When the bit is set, the corresponding video 9354f38fcaSMauro Carvalho Chehab pixel is displayed, otherwise a pixel of the graphics surface. 9454f38fcaSMauro Carvalho Chehab 9554f38fcaSMauro Carvalho Chehab3. A list of clipping rectangles can be specified. In these regions *no* 9654f38fcaSMauro Carvalho Chehab video is displayed, so the graphics surface can be seen here. 9754f38fcaSMauro Carvalho Chehab 9854f38fcaSMauro Carvalho Chehab4. The framebuffer has an alpha channel that can be used to clip or 9954f38fcaSMauro Carvalho Chehab blend the framebuffer with the video. 10054f38fcaSMauro Carvalho Chehab 10154f38fcaSMauro Carvalho Chehab5. A global alpha value can be specified to blend the framebuffer 10254f38fcaSMauro Carvalho Chehab contents with video images. 10354f38fcaSMauro Carvalho Chehab 10454f38fcaSMauro Carvalho ChehabWhen simultaneous capturing and overlay is supported and the hardware 10554f38fcaSMauro Carvalho Chehabprohibits different image and frame buffer formats, the format requested 10654f38fcaSMauro Carvalho Chehabfirst takes precedence. The attempt to capture 10754f38fcaSMauro Carvalho Chehab(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay 10854f38fcaSMauro Carvalho Chehab(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error 10954f38fcaSMauro Carvalho Chehabcode or return accordingly modified parameters.. 11054f38fcaSMauro Carvalho Chehab 11154f38fcaSMauro Carvalho Chehab 11254f38fcaSMauro Carvalho ChehabOverlay Window 11354f38fcaSMauro Carvalho Chehab============== 11454f38fcaSMauro Carvalho Chehab 11554f38fcaSMauro Carvalho ChehabThe overlaid image is determined by cropping and overlay window 11654f38fcaSMauro Carvalho Chehabparameters. The former select an area of the video picture to capture, 11754f38fcaSMauro Carvalho Chehabthe latter how images are overlaid and clipped. Cropping initialization 11854f38fcaSMauro Carvalho Chehabat minimum requires to reset the parameters to defaults. An example is 11954f38fcaSMauro Carvalho Chehabgiven in :ref:`crop`. 12054f38fcaSMauro Carvalho Chehab 12154f38fcaSMauro Carvalho ChehabThe overlay window is described by a struct 12254f38fcaSMauro Carvalho Chehab:c:type:`v4l2_window`. It defines the size of the image, 12354f38fcaSMauro Carvalho Chehabits position over the graphics surface and the clipping to be applied. 12454f38fcaSMauro Carvalho ChehabTo get the current parameters applications set the ``type`` field of a 12554f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_format` to 12654f38fcaSMauro Carvalho Chehab``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the 12754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the 12854f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_window` substructure named ``win``. It is not 12954f38fcaSMauro Carvalho Chehabpossible to retrieve a previously programmed clipping list or bitmap. 13054f38fcaSMauro Carvalho Chehab 13154f38fcaSMauro Carvalho ChehabTo program the overlay window applications set the ``type`` field of a 13254f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_format` to 13354f38fcaSMauro Carvalho Chehab``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and 13454f38fcaSMauro Carvalho Chehabcall the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver 13554f38fcaSMauro Carvalho Chehabadjusts the parameters against hardware limits and returns the actual 13654f38fcaSMauro Carvalho Chehabparameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the 13754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn 13854f38fcaSMauro Carvalho Chehababout driver capabilities without actually changing driver state. Unlike 13954f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled. 14054f38fcaSMauro Carvalho Chehab 14154f38fcaSMauro Carvalho ChehabThe scaling factor of the overlaid image is implied by the width and 14254f38fcaSMauro Carvalho Chehabheight given in struct :c:type:`v4l2_window` and the size 14354f38fcaSMauro Carvalho Chehabof the cropping rectangle. For more information see :ref:`crop`. 14454f38fcaSMauro Carvalho Chehab 14554f38fcaSMauro Carvalho ChehabWhen simultaneous capturing and overlay is supported and the hardware 14654f38fcaSMauro Carvalho Chehabprohibits different image and window sizes, the size requested first 14754f38fcaSMauro Carvalho Chehabtakes precedence. The attempt to capture or overlay as well 14854f38fcaSMauro Carvalho Chehab(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error 14954f38fcaSMauro Carvalho Chehabcode or return accordingly modified parameters. 15054f38fcaSMauro Carvalho Chehab 15154f38fcaSMauro Carvalho Chehab 15254f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_window 15354f38fcaSMauro Carvalho Chehab 15454f38fcaSMauro Carvalho Chehabstruct v4l2_window 15554f38fcaSMauro Carvalho Chehab------------------ 15654f38fcaSMauro Carvalho Chehab 15754f38fcaSMauro Carvalho Chehab``struct v4l2_rect w`` 15854f38fcaSMauro Carvalho Chehab Size and position of the window relative to the top, left corner of 15954f38fcaSMauro Carvalho Chehab the frame buffer defined with 16054f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the 16154f38fcaSMauro Carvalho Chehab frame buffer width and height, the ``x`` and ``y`` coordinates can 16254f38fcaSMauro Carvalho Chehab be negative, and it can lie completely outside the frame buffer. The 16354f38fcaSMauro Carvalho Chehab driver clips the window accordingly, or if that is not possible, 16454f38fcaSMauro Carvalho Chehab modifies its size and/or position. 16554f38fcaSMauro Carvalho Chehab 16654f38fcaSMauro Carvalho Chehab``enum v4l2_field field`` 16754f38fcaSMauro Carvalho Chehab Applications set this field to determine which video field shall be 16854f38fcaSMauro Carvalho Chehab overlaid, typically one of ``V4L2_FIELD_ANY`` (0), 16954f38fcaSMauro Carvalho Chehab ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or 17054f38fcaSMauro Carvalho Chehab ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different 17154f38fcaSMauro Carvalho Chehab field order and return the actual setting here. 17254f38fcaSMauro Carvalho Chehab 17354f38fcaSMauro Carvalho Chehab``__u32 chromakey`` 17454f38fcaSMauro Carvalho Chehab When chroma-keying has been negotiated with 17554f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field 17654f38fcaSMauro Carvalho Chehab to the desired pixel value for the chroma key. The format is the 17754f38fcaSMauro Carvalho Chehab same as the pixel format of the framebuffer (struct 17854f38fcaSMauro Carvalho Chehab :c:type:`v4l2_framebuffer` ``fmt.pixelformat`` 17954f38fcaSMauro Carvalho Chehab field), with bytes in host order. E. g. for 18054f38fcaSMauro Carvalho Chehab :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should 18154f38fcaSMauro Carvalho Chehab be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host. 18254f38fcaSMauro Carvalho Chehab 18354f38fcaSMauro Carvalho Chehab``struct v4l2_clip * clips`` 18454f38fcaSMauro Carvalho Chehab When chroma-keying has *not* been negotiated and 18554f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, 18654f38fcaSMauro Carvalho Chehab applications can set this field to point to an array of clipping 18754f38fcaSMauro Carvalho Chehab rectangles. 18854f38fcaSMauro Carvalho Chehab 18954f38fcaSMauro Carvalho Chehab Like the window coordinates w, clipping rectangles are defined 19054f38fcaSMauro Carvalho Chehab relative to the top, left corner of the frame buffer. However 19154f38fcaSMauro Carvalho Chehab clipping rectangles must not extend the frame buffer width and 19254f38fcaSMauro Carvalho Chehab height, and they must not overlap. If possible applications 19354f38fcaSMauro Carvalho Chehab should merge adjacent rectangles. Whether this must create 19454f38fcaSMauro Carvalho Chehab x-y or y-x bands, or the order of rectangles, is not defined. When 19554f38fcaSMauro Carvalho Chehab clip lists are not supported the driver ignores this field. Its 19654f38fcaSMauro Carvalho Chehab contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 19754f38fcaSMauro Carvalho Chehab are undefined. 19854f38fcaSMauro Carvalho Chehab 19954f38fcaSMauro Carvalho Chehab``__u32 clipcount`` 20054f38fcaSMauro Carvalho Chehab When the application set the ``clips`` field, this field must 20154f38fcaSMauro Carvalho Chehab contain the number of clipping rectangles in the list. When clip 20254f38fcaSMauro Carvalho Chehab lists are not supported the driver ignores this field, its contents 20354f38fcaSMauro Carvalho Chehab after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are 20454f38fcaSMauro Carvalho Chehab supported but no clipping is desired this field must be set to zero. 20554f38fcaSMauro Carvalho Chehab 20654f38fcaSMauro Carvalho Chehab``void * bitmap`` 20754f38fcaSMauro Carvalho Chehab When chroma-keying has *not* been negotiated and 20854f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, 20954f38fcaSMauro Carvalho Chehab applications can set this field to point to a clipping bit mask. 21054f38fcaSMauro Carvalho Chehab 21154f38fcaSMauro Carvalho ChehabIt must be of the same size as the window, ``w.width`` and ``w.height``. 21254f38fcaSMauro Carvalho ChehabEach bit corresponds to a pixel in the overlaid image, which is 21354f38fcaSMauro Carvalho Chehabdisplayed only when the bit is *set*. Pixel coordinates translate to 21454f38fcaSMauro Carvalho Chehabbits like: 21554f38fcaSMauro Carvalho Chehab 21654f38fcaSMauro Carvalho Chehab 21754f38fcaSMauro Carvalho Chehab.. code-block:: c 21854f38fcaSMauro Carvalho Chehab 21954f38fcaSMauro Carvalho Chehab ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7)) 22054f38fcaSMauro Carvalho Chehab 22154f38fcaSMauro Carvalho Chehabwhere ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_ 22254f38fcaSMauro Carvalho Chehab 22354f38fcaSMauro Carvalho ChehabWhen a clipping bit mask is not supported the driver ignores this field, 22454f38fcaSMauro Carvalho Chehabits contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are 22554f38fcaSMauro Carvalho Chehabundefined. When a bit mask is supported but no clipping is desired this 22654f38fcaSMauro Carvalho Chehabfield must be set to ``NULL``. 22754f38fcaSMauro Carvalho Chehab 22854f38fcaSMauro Carvalho ChehabApplications need not create a clip list or bit mask. When they pass 22954f38fcaSMauro Carvalho Chehabboth, or despite negotiating chroma-keying, the results are undefined. 23054f38fcaSMauro Carvalho ChehabRegardless of the chosen method, the clipping abilities of the hardware 23154f38fcaSMauro Carvalho Chehabmay be limited in quantity or quality. The results when these limits are 23254f38fcaSMauro Carvalho Chehabexceeded are undefined. [#f3]_ 23354f38fcaSMauro Carvalho Chehab 23454f38fcaSMauro Carvalho Chehab``__u8 global_alpha`` 23554f38fcaSMauro Carvalho Chehab The global alpha value used to blend the framebuffer with video 23654f38fcaSMauro Carvalho Chehab images, if global alpha blending has been negotiated 23754f38fcaSMauro Carvalho Chehab (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see 23854f38fcaSMauro Carvalho Chehab :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`, 23954f38fcaSMauro Carvalho Chehab :ref:`framebuffer-flags`). 24054f38fcaSMauro Carvalho Chehab 24154f38fcaSMauro Carvalho Chehab.. note:: 24254f38fcaSMauro Carvalho Chehab 24354f38fcaSMauro Carvalho Chehab This field was added in Linux 2.6.23, extending the 24454f38fcaSMauro Carvalho Chehab structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>` 24554f38fcaSMauro Carvalho Chehab ioctls, which take a pointer to a :c:type:`v4l2_format` 24654f38fcaSMauro Carvalho Chehab parent structure with padding bytes at the end, are not affected. 24754f38fcaSMauro Carvalho Chehab 24854f38fcaSMauro Carvalho Chehab 24954f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_clip 25054f38fcaSMauro Carvalho Chehab 25154f38fcaSMauro Carvalho Chehabstruct v4l2_clip [#f4]_ 25254f38fcaSMauro Carvalho Chehab----------------------- 25354f38fcaSMauro Carvalho Chehab 25454f38fcaSMauro Carvalho Chehab``struct v4l2_rect c`` 25554f38fcaSMauro Carvalho Chehab Coordinates of the clipping rectangle, relative to the top, left 25654f38fcaSMauro Carvalho Chehab corner of the frame buffer. Only window pixels *outside* all 25754f38fcaSMauro Carvalho Chehab clipping rectangles are displayed. 25854f38fcaSMauro Carvalho Chehab 25954f38fcaSMauro Carvalho Chehab``struct v4l2_clip * next`` 26054f38fcaSMauro Carvalho Chehab Pointer to the next clipping rectangle, ``NULL`` when this is the last 26154f38fcaSMauro Carvalho Chehab rectangle. Drivers ignore this field, it cannot be used to pass a 26254f38fcaSMauro Carvalho Chehab linked list of clipping rectangles. 26354f38fcaSMauro Carvalho Chehab 26454f38fcaSMauro Carvalho Chehab 26554f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_rect 26654f38fcaSMauro Carvalho Chehab 26754f38fcaSMauro Carvalho Chehabstruct v4l2_rect 26854f38fcaSMauro Carvalho Chehab---------------- 26954f38fcaSMauro Carvalho Chehab 27054f38fcaSMauro Carvalho Chehab``__s32 left`` 27154f38fcaSMauro Carvalho Chehab Horizontal offset of the top, left corner of the rectangle, in 27254f38fcaSMauro Carvalho Chehab pixels. 27354f38fcaSMauro Carvalho Chehab 27454f38fcaSMauro Carvalho Chehab``__s32 top`` 27554f38fcaSMauro Carvalho Chehab Vertical offset of the top, left corner of the rectangle, in pixels. 27654f38fcaSMauro Carvalho Chehab Offsets increase to the right and down. 27754f38fcaSMauro Carvalho Chehab 27854f38fcaSMauro Carvalho Chehab``__u32 width`` 27954f38fcaSMauro Carvalho Chehab Width of the rectangle, in pixels. 28054f38fcaSMauro Carvalho Chehab 28154f38fcaSMauro Carvalho Chehab``__u32 height`` 28254f38fcaSMauro Carvalho Chehab Height of the rectangle, in pixels. 28354f38fcaSMauro Carvalho Chehab 28454f38fcaSMauro Carvalho Chehab 28554f38fcaSMauro Carvalho ChehabEnabling Overlay 28654f38fcaSMauro Carvalho Chehab================ 28754f38fcaSMauro Carvalho Chehab 28854f38fcaSMauro Carvalho ChehabTo start or stop the frame buffer overlay applications call the 28954f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_OVERLAY` ioctl. 29054f38fcaSMauro Carvalho Chehab 29154f38fcaSMauro Carvalho Chehab.. [#f1] 29254f38fcaSMauro Carvalho Chehab A common application of two file descriptors is the XFree86 29354f38fcaSMauro Carvalho Chehab :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. 29454f38fcaSMauro Carvalho Chehab While the X server controls video overlay, the application can take 29554f38fcaSMauro Carvalho Chehab advantage of memory mapping and DMA. 29654f38fcaSMauro Carvalho Chehab 29754f38fcaSMauro Carvalho Chehab In the opinion of the designers of this API, no driver writer taking 29854f38fcaSMauro Carvalho Chehab the efforts to support simultaneous capturing and overlay will 29954f38fcaSMauro Carvalho Chehab restrict this ability by requiring a single file descriptor, as in 30054f38fcaSMauro Carvalho Chehab V4L and earlier versions of V4L2. Making this optional means 30154f38fcaSMauro Carvalho Chehab applications depending on two file descriptors need backup routines 30254f38fcaSMauro Carvalho Chehab to be compatible with all drivers, which is considerable more work 30354f38fcaSMauro Carvalho Chehab than using two fds in applications which do not. Also two fd's fit 30454f38fcaSMauro Carvalho Chehab the general concept of one file descriptor for each logical stream. 30554f38fcaSMauro Carvalho Chehab Hence as a complexity trade-off drivers *must* support two file 30654f38fcaSMauro Carvalho Chehab descriptors and *may* support single fd operation. 30754f38fcaSMauro Carvalho Chehab 30854f38fcaSMauro Carvalho Chehab.. [#f2] 30954f38fcaSMauro Carvalho Chehab Should we require ``w.width`` to be a multiple of eight? 31054f38fcaSMauro Carvalho Chehab 31154f38fcaSMauro Carvalho Chehab.. [#f3] 31254f38fcaSMauro Carvalho Chehab When the image is written into frame buffer memory it will be 31354f38fcaSMauro Carvalho Chehab undesirable if the driver clips out less pixels than expected, 31454f38fcaSMauro Carvalho Chehab because the application and graphics system are not aware these 31554f38fcaSMauro Carvalho Chehab regions need to be refreshed. The driver should clip out more pixels 31654f38fcaSMauro Carvalho Chehab or not write the image at all. 31754f38fcaSMauro Carvalho Chehab 31854f38fcaSMauro Carvalho Chehab.. [#f4] 31954f38fcaSMauro Carvalho Chehab The X Window system defines "regions" which are vectors of ``struct 32054f38fcaSMauro Carvalho Chehab BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and 32154f38fcaSMauro Carvalho Chehab ``height = y2 - y1``, so one cannot pass X11 clip lists directly. 322