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