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