1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_G_FBUF: 5 6********************************** 7ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF 8********************************** 9 10Name 11==== 12 13VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters 14 15Synopsis 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 26Arguments 27========= 28 29``fd`` 30 File descriptor returned by :c:func:`open()`. 31 32``argp`` 33 Pointer to struct :c:type:`v4l2_framebuffer`. 34 35Description 36=========== 37 38Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl 39to 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 42output device) and can be determined with the 43:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN`` 44device must not support both kinds of overlay. 45 46The V4L2 API distinguishes destructive and non-destructive overlays. A 47destructive overlay copies captured video images into the video memory 48of a graphics card. A non-destructive overlay blends video images into a 49VGA signal or graphics into a video signal. *Video Output Overlays* are 50always non-destructive. 51 52Destructive overlay support has been removed: with modern GPUs and CPUs 53this is no longer needed, and it was always a very dangerous feature. 54 55To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 56ioctl with a pointer to a struct :c:type:`v4l2_framebuffer` 57structure. The driver fills all fields of the structure or returns an 58EINVAL error code when overlays are not supported. 59 60To set the parameters for a *Video Output Overlay*, applications must 61initialize the ``flags`` field of a struct 62:c:type:`v4l2_framebuffer`. Since the framebuffer is 63implemented on the TV card all other parameters are determined by the 64driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to 65this structure, the driver prepares for the overlay and returns the 66framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error 67code. 68 69To set the parameters for a *Video Capture Overlay* 70applications must initialize the ``flags`` field, the ``fmt`` 71substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for 72the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 73does, 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 319Return Value 320============ 321 322On success 0 is returned, on error -1 and the ``errno`` variable is set 323appropriately. The generic error codes are described at the 324:ref:`Generic Error Codes <gen-errors>` chapter. 325 326EPERM 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 330EINVAL 331 The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. 332