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