1.. Permission is granted to copy, distribute and/or modify this 2.. document under the terms of the GNU Free Documentation License, 3.. Version 1.1 or any later version published by the Free Software 4.. Foundation, with no Invariant Sections, no Front-Cover Texts 5.. and no Back-Cover Texts. A copy of the license is included at 6.. Documentation/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _VIDIOC_G_FBUF: 11 12********************************** 13ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF 14********************************** 15 16Name 17==== 18 19VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters 20 21 22Synopsis 23======== 24 25.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp ) 26 :name: VIDIOC_G_FBUF 27 28.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp ) 29 :name: VIDIOC_S_FBUF 30 31 32Arguments 33========= 34 35``fd`` 36 File descriptor returned by :ref:`open() <func-open>`. 37 38``argp`` 39 Pointer to struct :c:type:`v4l2_framebuffer`. 40 41 42Description 43=========== 44 45Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl 46to get and set the framebuffer parameters for a 47:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>` 48(OSD). The type of overlay is implied by the device type (capture or 49output device) and can be determined with the 50:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN`` 51device must not support both kinds of overlay. 52 53The V4L2 API distinguishes destructive and non-destructive overlays. A 54destructive overlay copies captured video images into the video memory 55of a graphics card. A non-destructive overlay blends video images into a 56VGA signal or graphics into a video signal. *Video Output Overlays* are 57always non-destructive. 58 59To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 60ioctl with a pointer to a struct :c:type:`v4l2_framebuffer` 61structure. The driver fills all fields of the structure or returns an 62EINVAL error code when overlays are not supported. 63 64To set the parameters for a *Video Output Overlay*, applications must 65initialize the ``flags`` field of a struct 66:c:type:`v4l2_framebuffer`. Since the framebuffer is 67implemented on the TV card all other parameters are determined by the 68driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to 69this structure, the driver prepares for the overlay and returns the 70framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error 71code. 72 73To set the parameters for a *non-destructive Video Overlay*, 74applications must initialize the ``flags`` field, the ``fmt`` 75substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for 76the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` 77does, or it returns an error code. 78 79For a *destructive Video Overlay* applications must additionally provide 80a ``base`` address. Setting up a DMA to a random memory location can 81jeopardize the system security, its stability or even damage the 82hardware, therefore only the superuser can set the parameters for a 83destructive video overlay. 84 85 86.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| 87 88.. c:type:: v4l2_framebuffer 89 90.. cssclass:: longtable 91 92.. flat-table:: struct v4l2_framebuffer 93 :header-rows: 0 94 :stub-columns: 0 95 :widths: 1 1 1 2 96 97 * - __u32 98 - ``capability`` 99 - 100 - Overlay capability flags set by the driver, see 101 :ref:`framebuffer-cap`. 102 * - __u32 103 - ``flags`` 104 - 105 - Overlay control flags set by application and driver, see 106 :ref:`framebuffer-flags` 107 * - void * 108 - ``base`` 109 - 110 - Physical base address of the framebuffer, that is the address of 111 the pixel in the top left corner of the framebuffer. [#f1]_ 112 * - 113 - 114 - 115 - This field is irrelevant to *non-destructive Video Overlays*. For 116 *destructive Video Overlays* applications must provide a base 117 address. The driver may accept only base addresses which are a 118 multiple of two, four or eight bytes. For *Video Output Overlays* 119 the driver must return a valid base address, so applications can 120 find the corresponding Linux framebuffer device (see 121 :ref:`osd`). 122 * - struct 123 - ``fmt`` 124 - 125 - Layout of the frame buffer. 126 * - 127 - __u32 128 - ``width`` 129 - Width of the frame buffer in pixels. 130 * - 131 - __u32 132 - ``height`` 133 - Height of the frame buffer in pixels. 134 * - 135 - __u32 136 - ``pixelformat`` 137 - The pixel format of the framebuffer. 138 * - 139 - 140 - 141 - For *non-destructive Video Overlays* this field only defines a 142 format for the struct :c:type:`v4l2_window` 143 ``chromakey`` field. 144 * - 145 - 146 - 147 - For *destructive Video Overlays* applications must initialize this 148 field. For *Video Output Overlays* the driver must return a valid 149 format. 150 * - 151 - 152 - 153 - Usually this is an RGB format (for example 154 :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV 155 formats (only packed YUV formats when chroma keying is used, not 156 including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the 157 ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of 158 the driver when an application requests a compressed format is 159 undefined. See :ref:`pixfmt` for information on pixel formats. 160 * - 161 - enum :c:type:`v4l2_field` 162 - ``field`` 163 - Drivers and applications shall ignore this field. If applicable, 164 the field order is selected with the 165 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field`` 166 field of struct :c:type:`v4l2_window`. 167 * - 168 - __u32 169 - ``bytesperline`` 170 - Distance in bytes between the leftmost pixels in two adjacent 171 lines. 172 * - :cspan:`3` 173 174 This field is irrelevant to *non-destructive Video Overlays*. 175 176 For *destructive Video Overlays* both applications and drivers can 177 set this field to request padding bytes at the end of each line. 178 Drivers however may ignore the requested value, returning 179 ``width`` times bytes-per-pixel or a larger value required by the 180 hardware. That implies applications can just set this field to 181 zero to get a reasonable default. 182 183 For *Video Output Overlays* the driver must return a valid value. 184 185 Video hardware may access padding bytes, therefore they must 186 reside in accessible memory. Consider for example the case where 187 padding bytes after the last line of an image cross a system page 188 boundary. Capture devices may write padding bytes, the value is 189 undefined. Output devices ignore the contents of padding bytes. 190 191 When the image format is planar the ``bytesperline`` value applies 192 to the first plane and is divided by the same factor as the 193 ``width`` field for the other planes. For example the Cb and Cr 194 planes of a YUV 4:2:0 image have half as many padding bytes 195 following each line as the Y plane. To avoid ambiguities drivers 196 must return a ``bytesperline`` value rounded up to a multiple of 197 the scale factor. 198 * - 199 - __u32 200 - ``sizeimage`` 201 - This field is irrelevant to *non-destructive Video Overlays*. For 202 *destructive Video Overlays* applications must initialize this 203 field. For *Video Output Overlays* the driver must return a valid 204 format. 205 206 Together with ``base`` it defines the framebuffer memory 207 accessible by the driver. 208 * - 209 - enum :c:type:`v4l2_colorspace` 210 - ``colorspace`` 211 - This information supplements the ``pixelformat`` and must be set 212 by the driver, see :ref:`colorspaces`. 213 * - 214 - __u32 215 - ``priv`` 216 - Reserved. Drivers and applications must set this field to zero. 217 218 219.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 220 221.. _framebuffer-cap: 222 223.. flat-table:: Frame Buffer Capability Flags 224 :header-rows: 0 225 :stub-columns: 0 226 :widths: 3 1 4 227 228 * - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` 229 - 0x0001 230 - The device is capable of non-destructive overlays. When the driver 231 clears this flag, only destructive overlays are supported. There 232 are no drivers yet which support both destructive and 233 non-destructive overlays. Video Output Overlays are in practice 234 always non-destructive. 235 * - ``V4L2_FBUF_CAP_CHROMAKEY`` 236 - 0x0002 237 - The device supports clipping by chroma-keying the images. That is, 238 image pixels replace pixels in the VGA or video signal only where 239 the latter assume a certain color. Chroma-keying makes no sense 240 for destructive overlays. 241 * - ``V4L2_FBUF_CAP_LIST_CLIPPING`` 242 - 0x0004 243 - The device supports clipping using a list of clip rectangles. 244 * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` 245 - 0x0008 246 - The device supports clipping using a bit mask. 247 * - ``V4L2_FBUF_CAP_LOCAL_ALPHA`` 248 - 0x0010 249 - The device supports clipping/blending using the alpha channel of 250 the framebuffer or VGA signal. Alpha blending makes no sense for 251 destructive overlays. 252 * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA`` 253 - 0x0020 254 - The device supports alpha blending using a global alpha value. 255 Alpha blending makes no sense for destructive overlays. 256 * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA`` 257 - 0x0040 258 - The device supports clipping/blending using the inverted alpha 259 channel of the framebuffer or VGA signal. Alpha blending makes no 260 sense for destructive overlays. 261 * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY`` 262 - 0x0080 263 - The device supports Source Chroma-keying. Video pixels with the 264 chroma-key colors are replaced by framebuffer pixels, which is 265 exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` 266 267 268.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 269 270.. _framebuffer-flags: 271 272.. cssclass:: longtable 273 274.. flat-table:: Frame Buffer Flags 275 :header-rows: 0 276 :stub-columns: 0 277 :widths: 3 1 4 278 279 * - ``V4L2_FBUF_FLAG_PRIMARY`` 280 - 0x0001 281 - The framebuffer is the primary graphics surface. In other words, 282 the overlay is destructive. This flag is typically set by any 283 driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY`` 284 capability and it is cleared otherwise. 285 * - ``V4L2_FBUF_FLAG_OVERLAY`` 286 - 0x0002 287 - If this flag is set for a video capture device, then the driver 288 will set the initial overlay size to cover the full framebuffer 289 size, otherwise the existing overlay size (as set by 290 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one 291 video capture driver (bttv) supports this flag. The use of this 292 flag for capture devices is deprecated. There is no way to detect 293 which drivers support this flag, so the only reliable method of 294 setting the overlay size is through 295 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a 296 video output device, then the video output overlay window is 297 relative to the top-left corner of the framebuffer and restricted 298 to the size of the framebuffer. If it is cleared, then the video 299 output overlay window is relative to the video output display. 300 * - ``V4L2_FBUF_FLAG_CHROMAKEY`` 301 - 0x0004 302 - Use chroma-keying. The chroma-key color is determined by the 303 ``chromakey`` field of struct :c:type:`v4l2_window` 304 and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 305 ioctl, see :ref:`overlay` and :ref:`osd`. 306 * - :cspan:`2` There are no flags to enable clipping using a list of 307 clip rectangles or a bitmap. These methods are negotiated with the 308 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` 309 and :ref:`osd`. 310 * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA`` 311 - 0x0008 312 - Use the alpha channel of the framebuffer to clip or blend 313 framebuffer pixels with video images. The blend function is: 314 output = framebuffer pixel * alpha + video pixel * (1 - alpha). 315 The actual alpha depth depends on the framebuffer pixel format. 316 * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA`` 317 - 0x0010 318 - Use a global alpha value to blend the framebuffer with video 319 images. The blend function is: output = (framebuffer pixel * alpha 320 + video pixel * (255 - alpha)) / 255. The alpha value is 321 determined by the ``global_alpha`` field of struct 322 :c:type:`v4l2_window` and negotiated with the 323 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` 324 and :ref:`osd`. 325 * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA`` 326 - 0x0020 327 - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the 328 framebuffer to clip or blend framebuffer pixels with video images, 329 but with an inverted alpha value. The blend function is: output = 330 framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual 331 alpha depth depends on the framebuffer pixel format. 332 * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY`` 333 - 0x0040 334 - Use source chroma-keying. The source chroma-key color is 335 determined by the ``chromakey`` field of struct 336 :c:type:`v4l2_window` and negotiated with the 337 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` 338 and :ref:`osd`. Both chroma-keying are mutual exclusive to each 339 other, so same ``chromakey`` field of struct 340 :c:type:`v4l2_window` is being used. 341 342 343Return Value 344============ 345 346On success 0 is returned, on error -1 and the ``errno`` variable is set 347appropriately. The generic error codes are described at the 348:ref:`Generic Error Codes <gen-errors>` chapter. 349 350EPERM 351 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to 352 negotiate the parameters for a destructive overlay. 353 354EINVAL 355 The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. 356 357.. [#f1] 358 A physical base address may not suit all platforms. GK notes in 359 theory we should pass something like PCI device + memory region + 360 offset instead. If you encounter problems please discuss on the 361 linux-media mailing list: 362 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. 363