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