Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_G_FBUF:
   5
   6 **********************************
   7 ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
   8 **********************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_G_FBUF
  19
  20 ``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)``
  21
  22 .. c:macro:: VIDIOC_S_FBUF
  23
  24 ``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)``
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open()`.
  31
  32 ``argp``
  33     Pointer to struct :c:type:`v4l2_framebuffer`.
  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 Destructive overlay support has been removed: with modern GPUs and CPUs
  53 this is no longer needed, and it was always a very dangerous feature.
  54
  55 To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
  56 ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
  57 structure. The driver fills all fields of the structure or returns an
  58 EINVAL error code when overlays are not supported.
  59
  60 To set the parameters for a *Video Output Overlay*, applications must
  61 initialize the ``flags`` field of a struct
  62 :c:type:`v4l2_framebuffer`. Since the framebuffer is
  63 implemented on the TV card all other parameters are determined by the
  64 driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
  65 this structure, the driver prepares for the overlay and returns the
  66 framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
  67 code.
  68
  69 To set the parameters for a *Video Capture Overlay*
  70 applications must initialize the ``flags`` field, the ``fmt``
  71 substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
  72 the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
  73 does, or it returns an error code.
  74
  75 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|
  76
  77 .. c:type:: v4l2_framebuffer
  78
  79 .. cssclass:: longtable
  80
  81 .. flat-table:: struct v4l2_framebuffer
  82     :header-rows:  0
  83     :stub-columns: 0
  84     :widths:       1 1 1 2
  85
  86     * - __u32
  87       - ``capability``
  88       -
  89       - Overlay capability flags set by the driver, see
  90         :ref:`framebuffer-cap`.
  91     * - __u32
  92       - ``flags``
  93       -
  94       - Overlay control flags set by application and driver, see
  95         :ref:`framebuffer-flags`
  96     * - void *
  97       - ``base``
  98       -
  99       - Physical base address of the framebuffer, that is the address of
 100         the pixel in the top left corner of the framebuffer.
 101         For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` this field is no longer supported
 102         and the kernel will always set this to NULL.
 103         For *Video Output Overlays*
 104         the driver will return a valid base address, so applications can
 105         find the corresponding Linux framebuffer device (see
 106         :ref:`osd`). For *Video Capture Overlays* this field will always be
 107         NULL.
 108     * - struct
 109       - ``fmt``
 110       -
 111       - Layout of the frame buffer.
 112     * -
 113       - __u32
 114       - ``width``
 115       - Width of the frame buffer in pixels.
 116     * -
 117       - __u32
 118       - ``height``
 119       - Height of the frame buffer in pixels.
 120     * -
 121       - __u32
 122       - ``pixelformat``
 123       - The pixel format of the framebuffer.
 124     * -
 125       -
 126       -
 127       - For *non-destructive Video Overlays* this field only defines a
 128         format for the struct :c:type:`v4l2_window`
 129         ``chromakey`` field.
 130     * -
 131       -
 132       -
 133       - For *Video Output Overlays* the driver must return a valid
 134         format.
 135     * -
 136       -
 137       -
 138       - Usually this is an RGB format (for example
 139         :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
 140         formats (only packed YUV formats when chroma keying is used, not
 141         including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
 142         ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
 143         the driver when an application requests a compressed format is
 144         undefined. See :ref:`pixfmt` for information on pixel formats.
 145     * -
 146       - enum :c:type:`v4l2_field`
 147       - ``field``
 148       - Drivers and applications shall ignore this field. If applicable,
 149         the field order is selected with the
 150         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
 151         field of struct :c:type:`v4l2_window`.
 152     * -
 153       - __u32
 154       - ``bytesperline``
 155       - Distance in bytes between the leftmost pixels in two adjacent
 156         lines.
 157     * - :cspan:`3`
 158
 159         This field is irrelevant to *non-destructive Video Overlays*.
 160
 161         For *Video Output Overlays* the driver must return a valid value.
 162
 163         Video hardware may access padding bytes, therefore they must
 164         reside in accessible memory. Consider for example the case where
 165         padding bytes after the last line of an image cross a system page
 166         boundary. Capture devices may write padding bytes, the value is
 167         undefined. Output devices ignore the contents of padding bytes.
 168
 169         When the image format is planar the ``bytesperline`` value applies
 170         to the first plane and is divided by the same factor as the
 171         ``width`` field for the other planes. For example the Cb and Cr
 172         planes of a YUV 4:2:0 image have half as many padding bytes
 173         following each line as the Y plane. To avoid ambiguities drivers
 174         must return a ``bytesperline`` value rounded up to a multiple of
 175         the scale factor.
 176     * -
 177       - __u32
 178       - ``sizeimage``
 179       - This field is irrelevant to *non-destructive Video Overlays*.
 180         For *Video Output Overlays* the driver must return a valid
 181         format.
 182
 183         Together with ``base`` it defines the framebuffer memory
 184         accessible by the driver.
 185     * -
 186       - enum :c:type:`v4l2_colorspace`
 187       - ``colorspace``
 188       - This information supplements the ``pixelformat`` and must be set
 189         by the driver, see :ref:`colorspaces`.
 190     * -
 191       - __u32
 192       - ``priv``
 193       - Reserved. Drivers and applications must set this field to zero.
 194
 195 .. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}|
 196
 197 .. _framebuffer-cap:
 198
 199 .. flat-table:: Frame Buffer Capability Flags
 200     :header-rows:  0
 201     :stub-columns: 0
 202     :widths:       3 1 4
 203
 204     * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
 205       - 0x0001
 206       - The device is capable of non-destructive overlays. When the driver
 207         clears this flag, only destructive overlays are supported. There
 208         are no drivers yet which support both destructive and
 209         non-destructive overlays. Video Output Overlays are in practice
 210         always non-destructive.
 211     * - ``V4L2_FBUF_CAP_CHROMAKEY``
 212       - 0x0002
 213       - The device supports clipping by chroma-keying the images. That is,
 214         image pixels replace pixels in the VGA or video signal only where
 215         the latter assume a certain color. Chroma-keying makes no sense
 216         for destructive overlays.
 217     * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
 218       - 0x0004
 219       - The device supports clipping using a list of clip rectangles.
 220         Note that this is no longer supported.
 221     * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
 222       - 0x0008
 223       - The device supports clipping using a bit mask.
 224         Note that this is no longer supported.
 225     * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
 226       - 0x0010
 227       - The device supports clipping/blending using the alpha channel of
 228         the framebuffer or VGA signal. Alpha blending makes no sense for
 229         destructive overlays.
 230     * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
 231       - 0x0020
 232       - The device supports alpha blending using a global alpha value.
 233         Alpha blending makes no sense for destructive overlays.
 234     * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
 235       - 0x0040
 236       - The device supports clipping/blending using the inverted alpha
 237         channel of the framebuffer or VGA signal. Alpha blending makes no
 238         sense for destructive overlays.
 239     * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
 240       - 0x0080
 241       - The device supports Source Chroma-keying. Video pixels with the
 242         chroma-key colors are replaced by framebuffer pixels, which is
 243         exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
 244
 245 .. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}|
 246
 247 .. _framebuffer-flags:
 248
 249 .. cssclass:: longtable
 250
 251 .. flat-table:: Frame Buffer Flags
 252     :header-rows:  0
 253     :stub-columns: 0
 254     :widths:       3 1 4
 255
 256     * - ``V4L2_FBUF_FLAG_PRIMARY``
 257       - 0x0001
 258       - The framebuffer is the primary graphics surface. In other words,
 259         the overlay is destructive. This flag is typically set by any
 260         driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
 261         capability and it is cleared otherwise.
 262     * - ``V4L2_FBUF_FLAG_OVERLAY``
 263       - 0x0002
 264       - If this flag is set for a video capture device, then the driver
 265         will set the initial overlay size to cover the full framebuffer
 266         size, otherwise the existing overlay size (as set by
 267         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
 268         video capture driver (bttv) supports this flag. The use of this
 269         flag for capture devices is deprecated. There is no way to detect
 270         which drivers support this flag, so the only reliable method of
 271         setting the overlay size is through
 272         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
 273         video output device, then the video output overlay window is
 274         relative to the top-left corner of the framebuffer and restricted
 275         to the size of the framebuffer. If it is cleared, then the video
 276         output overlay window is relative to the video output display.
 277     * - ``V4L2_FBUF_FLAG_CHROMAKEY``
 278       - 0x0004
 279       - Use chroma-keying. The chroma-key color is determined by the
 280         ``chromakey`` field of struct :c:type:`v4l2_window`
 281         and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
 282         ioctl, see :ref:`overlay` and :ref:`osd`.
 283     * - :cspan:`2` There are no flags to enable clipping using a list of
 284         clip rectangles or a bitmap. These methods are negotiated with the
 285         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 286         and :ref:`osd`.
 287     * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
 288       - 0x0008
 289       - Use the alpha channel of the framebuffer to clip or blend
 290         framebuffer pixels with video images. The blend function is:
 291         output = framebuffer pixel * alpha + video pixel * (1 - alpha).
 292         The actual alpha depth depends on the framebuffer pixel format.
 293     * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
 294       - 0x0010
 295       - Use a global alpha value to blend the framebuffer with video
 296         images. The blend function is: output = (framebuffer pixel * alpha
 297         + video pixel * (255 - alpha)) / 255. The alpha value is
 298         determined by the ``global_alpha`` field of struct
 299         :c:type:`v4l2_window` and negotiated with the
 300         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 301         and :ref:`osd`.
 302     * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
 303       - 0x0020
 304       - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
 305         framebuffer to clip or blend framebuffer pixels with video images,
 306         but with an inverted alpha value. The blend function is: output =
 307         framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
 308         alpha depth depends on the framebuffer pixel format.
 309     * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
 310       - 0x0040
 311       - Use source chroma-keying. The source chroma-key color is
 312         determined by the ``chromakey`` field of struct
 313         :c:type:`v4l2_window` and negotiated with the
 314         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
 315         and :ref:`osd`. Both chroma-keying are mutual exclusive to each
 316         other, so same ``chromakey`` field of struct
 317         :c:type:`v4l2_window` is being used.
 318
 319 Return Value
 320 ============
 321
 322 On success 0 is returned, on error -1 and the ``errno`` variable is set
 323 appropriately. The generic error codes are described at the
 324 :ref:`Generic Error Codes <gen-errors>` chapter.
 325
 326 EPERM
 327     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
 328     negotiate the parameters for a destructive overlay.
 329
 330 EINVAL
 331     The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.