1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_G_FBUF: 4 5********************************** 6ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF 7********************************** 8 9Name 10==== 11 12VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters 13 14 15Synopsis 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 25Arguments 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 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 52To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 53ioctl with a pointer to a struct :c:type:`v4l2_framebuffer` 54structure. The driver fills all fields of the structure or returns an 55EINVAL error code when overlays are not supported. 56 57To set the parameters for a *Video Output Overlay*, applications must 58initialize the ``flags`` field of a struct 59:c:type:`v4l2_framebuffer`. Since the framebuffer is 60implemented on the TV card all other parameters are determined by the 61driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to 62this structure, the driver prepares for the overlay and returns the 63framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error 64code. 65 66To set the parameters for a *non-destructive Video Overlay*, 67applications must initialize the ``flags`` field, the ``fmt`` 68substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for 69the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 70does, or it returns an error code. 71 72For a *destructive Video Overlay* applications must additionally provide 73a ``base`` address. Setting up a DMA to a random memory location can 74jeopardize the system security, its stability or even damage the 75hardware, therefore only the superuser can set the parameters for a 76destructive 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 336Return Value 337============ 338 339On success 0 is returned, on error -1 and the ``errno`` variable is set 340appropriately. The generic error codes are described at the 341:ref:`Generic Error Codes <gen-errors>` chapter. 342 343EPERM 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 347EINVAL 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>`__. 356