Documentation/media/uapi/v4l/vidioc-g-fbuf.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_G_FBUF:
  11
  12 **********************************
  13 ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
  14 **********************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
  26     :name: VIDIOC_G_FBUF
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp )
  29     :name: VIDIOC_S_FBUF
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_framebuffer`.
  40
  41
  42 Description
  43 ===========
  44
  45 Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
  46 to get and set the framebuffer parameters for a
  47 :ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
  48 (OSD). The type of overlay is implied by the device type (capture or
  49 output device) and can be determined with the
  50 :ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
  51 device must not support both kinds of overlay.
  52
  53 The V4L2 API distinguishes destructive and non-destructive overlays. A
  54 destructive overlay copies captured video images into the video memory
  55 of a graphics card. A non-destructive overlay blends video images into a
  56 VGA signal or graphics into a video signal. *Video Output Overlays* are
  57 always non-destructive.
  58
  59 To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
  60 ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
  61 structure. The driver fills all fields of the structure or returns an
  62 EINVAL error code when overlays are not supported.
  63
  64 To set the parameters for a *Video Output Overlay*, applications must
  65 initialize the ``flags`` field of a struct
  66 struct :c:type:`v4l2_framebuffer`. Since the framebuffer is
  67 implemented on the TV card all other parameters are determined by the
  68 driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
  69 this structure, the driver prepares for the overlay and returns the
  70 framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
  71 code.
  72
  73 To set the parameters for a *non-destructive Video Overlay*,
  74 applications must initialize the ``flags`` field, the ``fmt``
  75 substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
  76 the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
  77 does, or it returns an error code.
  78
  79 For a *destructive Video Overlay* applications must additionally provide
  80 a ``base`` address. Setting up a DMA to a random memory location can
  81 jeopardize the system security, its stability or even damage the
  82 hardware, therefore only the superuser can set the parameters for a
  83 destructive video overlay.
  84
  85
  86 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  87
  88 .. c:type:: v4l2_framebuffer
  89
  90 .. cssclass:: longtable
  91
  92 .. flat-table:: struct v4l2_framebuffer
  93     :header-rows:  0
  94     :stub-columns: 0
  95     :widths:       1 1 1 2
  96
  97     * - __u32
  98       - ``capability``
  99       -
 100       - Overlay capability flags set by the driver, see
 101         :ref:`framebuffer-cap`.
 102     * - __u32
 103       - ``flags``
 104       -
 105       - Overlay control flags set by application and driver, see
 106         :ref:`framebuffer-flags`
 107     * - void *
 108       - ``base``
 109       -
 110       - Physical base address of the framebuffer, that is the address of
 111         the pixel in the top left corner of the framebuffer. [#f1]_
 112     * -
 113       -
 114       -
 115       - This field is irrelevant to *non-destructive Video Overlays*. For
 116         *destructive Video Overlays* applications must provide a base
 117         address. The driver may accept only base addresses which are a
 118         multiple of two, four or eight bytes. For *Video Output Overlays*
 119         the driver must return a valid base address, so applications can
 120         find the corresponding Linux framebuffer device (see
 121         :ref:`osd`).
 122     * - struct
 123       - ``fmt``
 124       -
 125       - Layout of the frame buffer.
 126     * -
 127       - __u32
 128       - ``width``
 129       - Width of the frame buffer in pixels.
 130     * -
 131       - __u32
 132       - ``height``
 133       - Height of the frame buffer in pixels.
 134     * -
 135       - __u32
 136       - ``pixelformat``
 137       - The pixel format of the framebuffer.
 138     * -
 139       -
 140       -
 141       - For *non-destructive Video Overlays* this field only defines a
 142         format for the struct :c:type:`v4l2_window`
 143         ``chromakey`` field.
 144     * -
 145       -
 146       -
 147       - For *destructive Video Overlays* applications must initialize this
 148         field. For *Video Output Overlays* the driver must return a valid
 149         format.
 150     * -
 151       -
 152       -
 153       - Usually this is an RGB format (for example
 154         :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
 155         formats (only packed YUV formats when chroma keying is used, not
 156         including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
 157         ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
 158         the driver when an application requests a compressed format is
 159         undefined. See :ref:`pixfmt` for information on pixel formats.
 160     * -
 161       - enum :c:type:`v4l2_field`
 162       - ``field``
 163       - Drivers and applications shall ignore this field. If applicable,
 164         the field order is selected with the
 165         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
 166         field of struct :c:type:`v4l2_window`.
 167     * -
 168       - __u32
 169       - ``bytesperline``
 170       - Distance in bytes between the leftmost pixels in two adjacent
 171         lines.
 172     * - :cspan:`3`
 173
 174         This field is irrelevant to *non-destructive Video Overlays*.
 175
 176         For *destructive Video Overlays* both applications and drivers can
 177         set this field to request padding bytes at the end of each line.
 178         Drivers however may ignore the requested value, returning
 179         ``width`` times bytes-per-pixel or a larger value required by the
 180         hardware. That implies applications can just set this field to
 181         zero to get a reasonable default.
 182
 183         For *Video Output Overlays* the driver must return a valid value.
 184
 185         Video hardware may access padding bytes, therefore they must
 186         reside in accessible memory. Consider for example the case where
 187         padding bytes after the last line of an image cross a system page
 188         boundary. Capture devices may write padding bytes, the value is
 189         undefined. Output devices ignore the contents of padding bytes.
 190
 191         When the image format is planar the ``bytesperline`` value applies
 192         to the first plane and is divided by the same factor as the
 193         ``width`` field for the other planes. For example the Cb and Cr
 194         planes of a YUV 4:2:0 image have half as many padding bytes
 195         following each line as the Y plane. To avoid ambiguities drivers
 196         must return a ``bytesperline`` value rounded up to a multiple of
 197         the scale factor.
 198     * -
 199       - __u32
 200       - ``sizeimage``
 201       - This field is irrelevant to *non-destructive Video Overlays*. For
 202         *destructive Video Overlays* applications must initialize this
 203         field. For *Video Output Overlays* the driver must return a valid
 204         format.
 205
 206         Together with ``base`` it defines the framebuffer memory
 207         accessible by the driver.
 208     * -
 209       - enum :c:type:`v4l2_colorspace`
 210       - ``colorspace``
 211       - This information supplements the ``pixelformat`` and must be set
 212         by the driver, see :ref:`colorspaces`.
 213     * -
 214       - __u32
 215       - ``priv``
 216       - Reserved. Drivers and applications must set this field to zero.
 217
 218
 219 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 220
 221 .. _framebuffer-cap:
 222
 223 .. flat-table:: Frame Buffer Capability Flags
 224     :header-rows:  0
 225     :stub-columns: 0
 226     :widths:       3 1 4
 227
 228     * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
 229       - 0x0001
 230       - The device is capable of non-destructive overlays. When the driver
 231         clears this flag, only destructive overlays are supported. There
 232         are no drivers yet which support both destructive and
 233         non-destructive overlays. Video Output Overlays are in practice
 234         always non-destructive.
 235     * - ``V4L2_FBUF_CAP_CHROMAKEY``
 236       - 0x0002
 237       - The device supports clipping by chroma-keying the images. That is,
 238         image pixels replace pixels in the VGA or video signal only where
 239         the latter assume a certain color. Chroma-keying makes no sense
 240         for destructive overlays.
 241     * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
 242       - 0x0004
 243       - The device supports clipping using a list of clip rectangles.
 244     * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
 245       - 0x0008
 246       - The device supports clipping using a bit mask.
 247     * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
 248       - 0x0010
 249       - The device supports clipping/blending using the alpha channel of
 250         the framebuffer or VGA signal. Alpha blending makes no sense for
 251         destructive overlays.
 252     * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
 253       - 0x0020
 254       - The device supports alpha blending using a global alpha value.
 255         Alpha blending makes no sense for destructive overlays.
 256     * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
 257       - 0x0040
 258       - The device supports clipping/blending using the inverted alpha
 259         channel of the framebuffer or VGA signal. Alpha blending makes no
 260         sense for destructive overlays.
 261     * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
 262       - 0x0080
 263       - The device supports Source Chroma-keying. Video pixels with the
 264         chroma-key colors are replaced by framebuffer pixels, which is
 265         exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
 266
 267
 268 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 269
 270 .. _framebuffer-flags:
 271
 272 .. cssclass:: longtable
 273
 274 .. flat-table:: Frame Buffer Flags
 275     :header-rows:  0
 276     :stub-columns: 0
 277     :widths:       3 1 4
 278
 279     * - ``V4L2_FBUF_FLAG_PRIMARY``
 280       - 0x0001
 281       - The framebuffer is the primary graphics surface. In other words,
 282         the overlay is destructive. This flag is typically set by any
 283         driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
 284         capability and it is cleared otherwise.
 285     * - ``V4L2_FBUF_FLAG_OVERLAY``
 286       - 0x0002
 287       - If this flag is set for a video capture device, then the driver
 288         will set the initial overlay size to cover the full framebuffer
 289         size, otherwise the existing overlay size (as set by
 290         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
 291         video capture driver (bttv) supports this flag. The use of this
 292         flag for capture devices is deprecated. There is no way to detect
 293         which drivers support this flag, so the only reliable method of
 294         setting the overlay size is through
 295         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
 296         video output device, then the video output overlay window is
 297         relative to the top-left corner of the framebuffer and restricted
 298         to the size of the framebuffer. If it is cleared, then the video
 299         output overlay window is relative to the video output display.
 300     * - ``V4L2_FBUF_FLAG_CHROMAKEY``
 301       - 0x0004
 302       - Use chroma-keying. The chroma-key color is determined by the
 303         ``chromakey`` field of struct :c:type:`v4l2_window`
 304         and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
 305         ioctl, see :ref:`overlay` and :ref:`osd`.
 306     * - :cspan:`2` There are no flags to enable clipping using a list of
 307         clip rectangles or a bitmap. These methods are negotiated with the
 308         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 309         and :ref:`osd`.
 310     * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
 311       - 0x0008
 312       - Use the alpha channel of the framebuffer to clip or blend
 313         framebuffer pixels with video images. The blend function is:
 314         output = framebuffer pixel * alpha + video pixel * (1 - alpha).
 315         The actual alpha depth depends on the framebuffer pixel format.
 316     * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
 317       - 0x0010
 318       - Use a global alpha value to blend the framebuffer with video
 319         images. The blend function is: output = (framebuffer pixel * alpha
 320         + video pixel * (255 - alpha)) / 255. The alpha value is
 321         determined by the ``global_alpha`` field of struct
 322         :c:type:`v4l2_window` and negotiated with the
 323         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 324         and :ref:`osd`.
 325     * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
 326       - 0x0020
 327       - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
 328         framebuffer to clip or blend framebuffer pixels with video images,
 329         but with an inverted alpha value. The blend function is: output =
 330         framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
 331         alpha depth depends on the framebuffer pixel format.
 332     * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
 333       - 0x0040
 334       - Use source chroma-keying. The source chroma-key color is
 335         determined by the ``chromakey`` field of struct
 336         :c:type:`v4l2_window` and negotiated with the
 337         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 338         and :ref:`osd`. Both chroma-keying are mutual exclusive to each
 339         other, so same ``chromakey`` field of struct
 340         :c:type:`v4l2_window` is being used.
 341
 342
 343 Return Value
 344 ============
 345
 346 On success 0 is returned, on error -1 and the ``errno`` variable is set
 347 appropriately. The generic error codes are described at the
 348 :ref:`Generic Error Codes <gen-errors>` chapter.
 349
 350 EPERM
 351     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
 352     negotiate the parameters for a destructive overlay.
 353
 354 EINVAL
 355     The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
 356
 357 .. [#f1]
 358    A physical base address may not suit all platforms. GK notes in
 359    theory we should pass something like PCI device + memory region +
 360    offset instead. If you encounter problems please discuss on the
 361    linux-media mailing list:
 362    `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.