Documentation/media/uapi/v4l/dev-overlay.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _overlay:
   4
   5 ***********************
   6 Video Overlay Interface
   7 ***********************
   8
   9 **Also known as Framebuffer Overlay or Previewing.**
  10
  11 Video overlay devices have the ability to genlock (TV-)video into the
  12 (VGA-)video signal of a graphics card, or to store captured images
  13 directly in video memory of a graphics card, typically with clipping.
  14 This can be considerable more efficient than capturing images and
  15 displaying them by other means. In the old days when only nuclear power
  16 plants needed cooling towers this used to be the only way to put live
  17 video into a window.
  18
  19 Video overlay devices are accessed through the same character special
  20 files as :ref:`video capture <capture>` devices.
  21
  22 .. note:: The default function of a ``/dev/video`` device is video
  23    capturing. The overlay function is only available after calling
  24    the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
  25
  26 The driver may support simultaneous overlay and capturing using the
  27 read/write and streaming I/O methods. If so, operation at the nominal
  28 frame rate of the video standard is not guaranteed. Frames may be
  29 directed away from overlay to capture, or one field may be used for
  30 overlay and the other for capture if the capture parameters permit this.
  31
  32 Applications should use different file descriptors for capturing and
  33 overlay. This must be supported by all drivers capable of simultaneous
  34 capturing and overlay. Optionally these drivers may also permit
  35 capturing and overlay with a single file descriptor for compatibility
  36 with V4L and earlier versions of V4L2. [#f1]_
  37
  38
  39 Querying Capabilities
  40 =====================
  41
  42 Devices supporting the video overlay interface set the
  43 ``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
  44 :ref:`v4l2_capability <v4l2-capability>` returned by the
  45 :ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
  46 method specified below must be supported. Tuners and audio inputs are
  47 optional.
  48
  49
  50 Supplemental Functions
  51 ======================
  52
  53 Video overlay devices shall support :ref:`audio input <audio>`,
  54 :ref:`tuner`, :ref:`controls <control>`,
  55 :ref:`cropping and scaling <crop>` and
  56 :ref:`streaming parameter <streaming-par>` ioctls as needed. The
  57 :ref:`video input <video>` and :ref:`video standard <standard>`
  58 ioctls must be supported by all video overlay devices.
  59
  60
  61 Setup
  62 =====
  63
  64 Before overlay can commence applications must program the driver with
  65 frame buffer parameters, namely the address and size of the frame buffer
  66 and the image format, for example RGB 5:6:5. The
  67 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
  68 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and
  69 set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is
  70 privileged because it allows to set up DMA into physical memory,
  71 bypassing the memory protection mechanisms of the kernel. Only the
  72 superuser can change the frame buffer address and size. Users are not
  73 supposed to run TV applications as root or with SUID bit set. A small
  74 helper application with suitable privileges should query the graphics
  75 system and program the V4L2 driver at the appropriate time.
  76
  77 Some devices add the video overlay to the output signal of the graphics
  78 card. In this case the frame buffer is not modified by the video device,
  79 and the frame buffer address and pixel format are not needed by the
  80 driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application
  81 can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
  82 ioctl.
  83
  84 A driver may support any (or none) of five clipping/blending methods:
  85
  86 1. Chroma-keying displays the overlaid image only where pixels in the
  87    primary graphics surface assume a certain color.
  88
  89 2. A bitmap can be specified where each bit corresponds to a pixel in
  90    the overlaid image. When the bit is set, the corresponding video
  91    pixel is displayed, otherwise a pixel of the graphics surface.
  92
  93 3. A list of clipping rectangles can be specified. In these regions *no*
  94    video is displayed, so the graphics surface can be seen here.
  95
  96 4. The framebuffer has an alpha channel that can be used to clip or
  97    blend the framebuffer with the video.
  98
  99 5. A global alpha value can be specified to blend the framebuffer
 100    contents with video images.
 101
 102 When simultaneous capturing and overlay is supported and the hardware
 103 prohibits different image and frame buffer formats, the format requested
 104 first takes precedence. The attempt to capture
 105 (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay
 106 (:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error
 107 code or return accordingly modified parameters..
 108
 109
 110 Overlay Window
 111 ==============
 112
 113 The overlaid image is determined by cropping and overlay window
 114 parameters. The former select an area of the video picture to capture,
 115 the latter how images are overlaid and clipped. Cropping initialization
 116 at minimum requires to reset the parameters to defaults. An example is
 117 given in :ref:`crop`.
 118
 119 The overlay window is described by a struct
 120 :ref:`v4l2_window <v4l2-window>`. It defines the size of the image,
 121 its position over the graphics surface and the clipping to be applied.
 122 To get the current parameters applications set the ``type`` field of a
 123 struct :ref:`v4l2_format <v4l2-format>` to
 124 ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
 125 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
 126 :ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
 127 possible to retrieve a previously programmed clipping list or bitmap.
 128
 129 To program the overlay window applications set the ``type`` field of a
 130 struct :ref:`v4l2_format <v4l2-format>` to
 131 ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
 132 call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver
 133 adjusts the parameters against hardware limits and returns the actual
 134 parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the
 135 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
 136 about driver capabilities without actually changing driver state. Unlike
 137 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
 138
 139 The scaling factor of the overlaid image is implied by the width and
 140 height given in struct :ref:`v4l2_window <v4l2-window>` and the size
 141 of the cropping rectangle. For more information see :ref:`crop`.
 142
 143 When simultaneous capturing and overlay is supported and the hardware
 144 prohibits different image and window sizes, the size requested first
 145 takes precedence. The attempt to capture or overlay as well
 146 (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error
 147 code or return accordingly modified parameters.
 148
 149
 150 .. _v4l2-window:
 151
 152 struct v4l2_window
 153 ------------------
 154
 155 ``struct v4l2_rect w``
 156     Size and position of the window relative to the top, left corner of
 157     the frame buffer defined with
 158     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the
 159     frame buffer width and height, the ``x`` and ``y`` coordinates can
 160     be negative, and it can lie completely outside the frame buffer. The
 161     driver clips the window accordingly, or if that is not possible,
 162     modifies its size and/or position.
 163
 164 ``enum v4l2_field field``
 165     Applications set this field to determine which video field shall be
 166     overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
 167     ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
 168     ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
 169     field order and return the actual setting here.
 170
 171 ``__u32 chromakey``
 172     When chroma-keying has been negotiated with
 173     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field
 174     to the desired pixel value for the chroma key. The format is the
 175     same as the pixel format of the framebuffer (struct
 176     :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat``
 177     field), with bytes in host order. E. g. for
 178     :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
 179     be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.
 180
 181 ``struct v4l2_clip * clips``
 182     When chroma-keying has *not* been negotiated and
 183     :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
 184     applications can set this field to point to an array of clipping
 185     rectangles.
 186
 187     Like the window coordinates w, clipping rectangles are defined
 188     relative to the top, left corner of the frame buffer. However
 189     clipping rectangles must not extend the frame buffer width and
 190     height, and they must not overlap. If possible applications
 191     should merge adjacent rectangles. Whether this must create
 192     x-y or y-x bands, or the order of rectangles, is not defined. When
 193     clip lists are not supported the driver ignores this field. Its
 194     contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
 195     are undefined.
 196
 197 ``__u32 clipcount``
 198     When the application set the ``clips`` field, this field must
 199     contain the number of clipping rectangles in the list. When clip
 200     lists are not supported the driver ignores this field, its contents
 201     after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are
 202     supported but no clipping is desired this field must be set to zero.
 203
 204 ``void * bitmap``
 205     When chroma-keying has *not* been negotiated and
 206     :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
 207     applications can set this field to point to a clipping bit mask.
 208
 209 It must be of the same size as the window, ``w.width`` and ``w.height``.
 210 Each bit corresponds to a pixel in the overlaid image, which is
 211 displayed only when the bit is *set*. Pixel coordinates translate to
 212 bits like:
 213
 214
 215 .. code-block:: c
 216
 217     ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
 218
 219 where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_
 220
 221 When a clipping bit mask is not supported the driver ignores this field,
 222 its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
 223 undefined. When a bit mask is supported but no clipping is desired this
 224 field must be set to ``NULL``.
 225
 226 Applications need not create a clip list or bit mask. When they pass
 227 both, or despite negotiating chroma-keying, the results are undefined.
 228 Regardless of the chosen method, the clipping abilities of the hardware
 229 may be limited in quantity or quality. The results when these limits are
 230 exceeded are undefined. [#f3]_
 231
 232 ``__u8 global_alpha``
 233     The global alpha value used to blend the framebuffer with video
 234     images, if global alpha blending has been negotiated
 235     (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
 236     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
 237     :ref:`framebuffer-flags`).
 238
 239     .. note:: This field was added in Linux 2.6.23, extending the
 240        structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
 241        ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>`
 242        parent structure with padding bytes at the end, are not affected.
 243
 244
 245 .. _v4l2-clip:
 246
 247 struct v4l2_clip [#f4]_
 248 -----------------------
 249
 250 ``struct v4l2_rect c``
 251     Coordinates of the clipping rectangle, relative to the top, left
 252     corner of the frame buffer. Only window pixels *outside* all
 253     clipping rectangles are displayed.
 254
 255 ``struct v4l2_clip * next``
 256     Pointer to the next clipping rectangle, ``NULL`` when this is the last
 257     rectangle. Drivers ignore this field, it cannot be used to pass a
 258     linked list of clipping rectangles.
 259
 260
 261 .. _v4l2-rect:
 262
 263 struct v4l2_rect
 264 ----------------
 265
 266 ``__s32 left``
 267     Horizontal offset of the top, left corner of the rectangle, in
 268     pixels.
 269
 270 ``__s32 top``
 271     Vertical offset of the top, left corner of the rectangle, in pixels.
 272     Offsets increase to the right and down.
 273
 274 ``__u32 width``
 275     Width of the rectangle, in pixels.
 276
 277 ``__u32 height``
 278     Height of the rectangle, in pixels.
 279
 280
 281 Enabling Overlay
 282 ================
 283
 284 To start or stop the frame buffer overlay applications call the
 285 :ref:`VIDIOC_OVERLAY` ioctl.
 286
 287 .. [#f1]
 288    A common application of two file descriptors is the XFree86
 289    :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.
 290    While the X server controls video overlay, the application can take
 291    advantage of memory mapping and DMA.
 292
 293    In the opinion of the designers of this API, no driver writer taking
 294    the efforts to support simultaneous capturing and overlay will
 295    restrict this ability by requiring a single file descriptor, as in
 296    V4L and earlier versions of V4L2. Making this optional means
 297    applications depending on two file descriptors need backup routines
 298    to be compatible with all drivers, which is considerable more work
 299    than using two fds in applications which do not. Also two fd's fit
 300    the general concept of one file descriptor for each logical stream.
 301    Hence as a complexity trade-off drivers *must* support two file
 302    descriptors and *may* support single fd operation.
 303
 304 .. [#f2]
 305    Should we require ``w.width`` to be a multiple of eight?
 306
 307 .. [#f3]
 308    When the image is written into frame buffer memory it will be
 309    undesirable if the driver clips out less pixels than expected,
 310    because the application and graphics system are not aware these
 311    regions need to be refreshed. The driver should clip out more pixels
 312    or not write the image at all.
 313
 314 .. [#f4]
 315    The X Window system defines "regions" which are vectors of ``struct
 316    BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and
 317    ``height = y2 - y1``, so one cannot pass X11 clip lists directly.