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

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