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