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     Pointer to struct :c:type:`v4l2_framebuffer`.
  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 struct :c:type:`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 struct :c:type:`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 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
  80
  81 .. c:type:: v4l2_framebuffer
  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     * - __u32
  91       - ``capability``
  92       -
  93       - Overlay capability flags set by the driver, see
  94         :ref:`framebuffer-cap`.
  95     * - __u32
  96       - ``flags``
  97       -
  98       - Overlay control flags set by application and driver, see
  99         :ref:`framebuffer-flags`
 100     * - void *
 101       - ``base``
 102       -
 103       - Physical base address of the framebuffer, that is the address of
 104         the pixel in the top left corner of the framebuffer. [#f1]_
 105     * -
 106       -
 107       -
 108       - This field is irrelevant to *non-destructive Video Overlays*. For
 109         *destructive Video Overlays* applications must provide a base
 110         address. The driver may accept only base addresses which are a
 111         multiple of two, four or eight bytes. For *Video Output Overlays*
 112         the driver must return a valid base address, so applications can
 113         find the corresponding Linux framebuffer device (see
 114         :ref:`osd`).
 115     * - struct
 116       - ``fmt``
 117       -
 118       - Layout of the frame buffer.
 119     * -
 120       - __u32
 121       - ``width``
 122       - Width of the frame buffer in pixels.
 123     * -
 124       - __u32
 125       - ``height``
 126       - Height of the frame buffer in pixels.
 127     * -
 128       - __u32
 129       - ``pixelformat``
 130       - The pixel format of the framebuffer.
 131     * -
 132       -
 133       -
 134       - For *non-destructive Video Overlays* this field only defines a
 135         format for the struct :c:type:`v4l2_window`
 136         ``chromakey`` field.
 137     * -
 138       -
 139       -
 140       - For *destructive Video Overlays* applications must initialize this
 141         field. For *Video Output Overlays* the driver must return a valid
 142         format.
 143     * -
 144       -
 145       -
 146       - Usually this is an RGB format (for example
 147         :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
 148         formats (only packed YUV formats when chroma keying is used, not
 149         including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
 150         ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
 151         the driver when an application requests a compressed format is
 152         undefined. See :ref:`pixfmt` for information on pixel formats.
 153     * -
 154       - enum :c:type:`v4l2_field`
 155       - ``field``
 156       - Drivers and applications shall ignore this field. If applicable,
 157         the field order is selected with the
 158         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
 159         field of struct :c:type:`v4l2_window`.
 160     * -
 161       - __u32
 162       - ``bytesperline``
 163       - Distance in bytes between the leftmost pixels in two adjacent
 164         lines.
 165     * - :cspan:`3`
 166
 167         This field is irrelevant to *non-destructive Video Overlays*.
 168
 169         For *destructive Video Overlays* both applications and drivers can
 170         set this field to request padding bytes at the end of each line.
 171         Drivers however may ignore the requested value, returning
 172         ``width`` times bytes-per-pixel or a larger value required by the
 173         hardware. That implies applications can just set this field to
 174         zero to get a reasonable default.
 175
 176         For *Video Output Overlays* the driver must return a valid value.
 177
 178         Video hardware may access padding bytes, therefore they must
 179         reside in accessible memory. Consider for example the case where
 180         padding bytes after the last line of an image cross a system page
 181         boundary. Capture devices may write padding bytes, the value is
 182         undefined. Output devices ignore the contents of padding bytes.
 183
 184         When the image format is planar the ``bytesperline`` value applies
 185         to the first plane and is divided by the same factor as the
 186         ``width`` field for the other planes. For example the Cb and Cr
 187         planes of a YUV 4:2:0 image have half as many padding bytes
 188         following each line as the Y plane. To avoid ambiguities drivers
 189         must return a ``bytesperline`` value rounded up to a multiple of
 190         the scale factor.
 191     * -
 192       - __u32
 193       - ``sizeimage``
 194       - This field is irrelevant to *non-destructive Video Overlays*. For
 195         *destructive Video Overlays* applications must initialize this
 196         field. For *Video Output Overlays* the driver must return a valid
 197         format.
 198
 199         Together with ``base`` it defines the framebuffer memory
 200         accessible by the driver.
 201     * -
 202       - enum :c:type:`v4l2_colorspace`
 203       - ``colorspace``
 204       - This information supplements the ``pixelformat`` and must be set
 205         by the driver, see :ref:`colorspaces`.
 206     * -
 207       - __u32
 208       - ``priv``
 209       - Reserved. Drivers and applications must set this field to zero.
 210
 211
 212 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 213
 214 .. _framebuffer-cap:
 215
 216 .. flat-table:: Frame Buffer Capability Flags
 217     :header-rows:  0
 218     :stub-columns: 0
 219     :widths:       3 1 4
 220
 221     * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
 222       - 0x0001
 223       - The device is capable of non-destructive overlays. When the driver
 224         clears this flag, only destructive overlays are supported. There
 225         are no drivers yet which support both destructive and
 226         non-destructive overlays. Video Output Overlays are in practice
 227         always non-destructive.
 228     * - ``V4L2_FBUF_CAP_CHROMAKEY``
 229       - 0x0002
 230       - The device supports clipping by chroma-keying the images. That is,
 231         image pixels replace pixels in the VGA or video signal only where
 232         the latter assume a certain color. Chroma-keying makes no sense
 233         for destructive overlays.
 234     * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
 235       - 0x0004
 236       - The device supports clipping using a list of clip rectangles.
 237     * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
 238       - 0x0008
 239       - The device supports clipping using a bit mask.
 240     * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
 241       - 0x0010
 242       - The device supports clipping/blending using the alpha channel of
 243         the framebuffer or VGA signal. Alpha blending makes no sense for
 244         destructive overlays.
 245     * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
 246       - 0x0020
 247       - The device supports alpha blending using a global alpha value.
 248         Alpha blending makes no sense for destructive overlays.
 249     * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
 250       - 0x0040
 251       - The device supports clipping/blending using the inverted alpha
 252         channel of the framebuffer or VGA signal. Alpha blending makes no
 253         sense for destructive overlays.
 254     * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
 255       - 0x0080
 256       - The device supports Source Chroma-keying. Video pixels with the
 257         chroma-key colors are replaced by framebuffer pixels, which is
 258         exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
 259
 260
 261 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 262
 263 .. _framebuffer-flags:
 264
 265 .. cssclass:: longtable
 266
 267 .. flat-table:: Frame Buffer Flags
 268     :header-rows:  0
 269     :stub-columns: 0
 270     :widths:       3 1 4
 271
 272     * - ``V4L2_FBUF_FLAG_PRIMARY``
 273       - 0x0001
 274       - The framebuffer is the primary graphics surface. In other words,
 275         the overlay is destructive. This flag is typically set by any
 276         driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
 277         capability and it is cleared otherwise.
 278     * - ``V4L2_FBUF_FLAG_OVERLAY``
 279       - 0x0002
 280       - If this flag is set for a video capture device, then the driver
 281         will set the initial overlay size to cover the full framebuffer
 282         size, otherwise the existing overlay size (as set by
 283         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
 284         video capture driver (bttv) supports this flag. The use of this
 285         flag for capture devices is deprecated. There is no way to detect
 286         which drivers support this flag, so the only reliable method of
 287         setting the overlay size is through
 288         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
 289         video output device, then the video output overlay window is
 290         relative to the top-left corner of the framebuffer and restricted
 291         to the size of the framebuffer. If it is cleared, then the video
 292         output overlay window is relative to the video output display.
 293     * - ``V4L2_FBUF_FLAG_CHROMAKEY``
 294       - 0x0004
 295       - Use chroma-keying. The chroma-key color is determined by the
 296         ``chromakey`` field of struct :c:type:`v4l2_window`
 297         and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
 298         ioctl, see :ref:`overlay` and :ref:`osd`.
 299     * - :cspan:`2` There are no flags to enable clipping using a list of
 300         clip rectangles or a bitmap. These methods are negotiated with the
 301         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 302         and :ref:`osd`.
 303     * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
 304       - 0x0008
 305       - Use the alpha channel of the framebuffer to clip or blend
 306         framebuffer pixels with video images. The blend function is:
 307         output = framebuffer pixel * alpha + video pixel * (1 - alpha).
 308         The actual alpha depth depends on the framebuffer pixel format.
 309     * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
 310       - 0x0010
 311       - Use a global alpha value to blend the framebuffer with video
 312         images. The blend function is: output = (framebuffer pixel * alpha
 313         + video pixel * (255 - alpha)) / 255. The alpha value is
 314         determined by the ``global_alpha`` field of struct
 315         :c:type:`v4l2_window` and negotiated with the
 316         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 317         and :ref:`osd`.
 318     * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
 319       - 0x0020
 320       - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
 321         framebuffer to clip or blend framebuffer pixels with video images,
 322         but with an inverted alpha value. The blend function is: output =
 323         framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
 324         alpha depth depends on the framebuffer pixel format.
 325     * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
 326       - 0x0040
 327       - Use source chroma-keying. The source chroma-key color is
 328         determined by the ``chromakey`` field of struct
 329         :c:type:`v4l2_window` and negotiated with the
 330         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 331         and :ref:`osd`. Both chroma-keying are mutual exclusive to each
 332         other, so same ``chromakey`` field of struct
 333         :c:type:`v4l2_window` is being used.
 334
 335
 336 Return Value
 337 ============
 338
 339 On success 0 is returned, on error -1 and the ``errno`` variable is set
 340 appropriately. The generic error codes are described at the
 341 :ref:`Generic Error Codes <gen-errors>` chapter.
 342
 343 EPERM
 344     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
 345     negotiate the parameters for a destructive overlay.
 346
 347 EINVAL
 348     The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
 349
 350 .. [#f1]
 351    A physical base address may not suit all platforms. GK notes in
 352    theory we should pass something like PCI device + memory region +
 353    offset instead. If you encounter problems please discuss on the
 354    linux-media mailing list:
 355    `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.