332 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_G_FBUF:5 6**********************************7ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF8**********************************9 10Name11====12 13VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters14 15Synopsis16========17 18.. c:macro:: VIDIOC_G_FBUF19 20``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)``21 22.. c:macro:: VIDIOC_S_FBUF23 24``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_framebuffer`.34 35Description36===========37 38Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl39to get and set the framebuffer parameters for a40:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`41(OSD). The type of overlay is implied by the device type (capture or42output device) and can be determined with the43: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. A47destructive overlay copies captured video images into the video memory48of a graphics card. A non-destructive overlay blends video images into a49VGA signal or graphics into a video signal. *Video Output Overlays* are50always non-destructive.51 52Destructive overlay support has been removed: with modern GPUs and CPUs53this 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 an58EINVAL error code when overlays are not supported.59 60To set the parameters for a *Video Output Overlay*, applications must61initialize the ``flags`` field of a struct62:c:type:`v4l2_framebuffer`. Since the framebuffer is63implemented on the TV card all other parameters are determined by the64driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to65this structure, the driver prepares for the overlay and returns the66framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error67code.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 for72the 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_framebuffer78 79.. cssclass:: longtable80 81.. flat-table:: struct v4l2_framebuffer82 :header-rows: 083 :stub-columns: 084 :widths: 1 1 1 285 86 * - __u3287 - ``capability``88 -89 - Overlay capability flags set by the driver, see90 :ref:`framebuffer-cap`.91 * - __u3292 - ``flags``93 -94 - Overlay control flags set by application and driver, see95 :ref:`framebuffer-flags`96 * - void *97 - ``base``98 -99 - Physical base address of the framebuffer, that is the address of100 the pixel in the top left corner of the framebuffer.101 For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` this field is no longer supported102 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 can105 find the corresponding Linux framebuffer device (see106 :ref:`osd`). For *Video Capture Overlays* this field will always be107 NULL.108 * - struct109 - ``fmt``110 -111 - Layout of the frame buffer.112 * -113 - __u32114 - ``width``115 - Width of the frame buffer in pixels.116 * -117 - __u32118 - ``height``119 - Height of the frame buffer in pixels.120 * -121 - __u32122 - ``pixelformat``123 - The pixel format of the framebuffer.124 * -125 -126 -127 - For *non-destructive Video Overlays* this field only defines a128 format for the struct :c:type:`v4l2_window`129 ``chromakey`` field.130 * -131 -132 -133 - For *Video Output Overlays* the driver must return a valid134 format.135 * -136 -137 -138 - Usually this is an RGB format (for example139 :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV140 formats (only packed YUV formats when chroma keying is used, not141 including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the142 ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of143 the driver when an application requests a compressed format is144 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 the150 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``151 field of struct :c:type:`v4l2_window`.152 * -153 - __u32154 - ``bytesperline``155 - Distance in bytes between the leftmost pixels in two adjacent156 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 must164 reside in accessible memory. Consider for example the case where165 padding bytes after the last line of an image cross a system page166 boundary. Capture devices may write padding bytes, the value is167 undefined. Output devices ignore the contents of padding bytes.168 169 When the image format is planar the ``bytesperline`` value applies170 to the first plane and is divided by the same factor as the171 ``width`` field for the other planes. For example the Cb and Cr172 planes of a YUV 4:2:0 image have half as many padding bytes173 following each line as the Y plane. To avoid ambiguities drivers174 must return a ``bytesperline`` value rounded up to a multiple of175 the scale factor.176 * -177 - __u32178 - ``sizeimage``179 - This field is irrelevant to *non-destructive Video Overlays*.180 For *Video Output Overlays* the driver must return a valid181 format.182 183 Together with ``base`` it defines the framebuffer memory184 accessible by the driver.185 * -186 - enum :c:type:`v4l2_colorspace`187 - ``colorspace``188 - This information supplements the ``pixelformat`` and must be set189 by the driver, see :ref:`colorspaces`.190 * -191 - __u32192 - ``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 Flags200 :header-rows: 0201 :stub-columns: 0202 :widths: 3 1 4203 204 * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``205 - 0x0001206 - The device is capable of non-destructive overlays. When the driver207 clears this flag, only destructive overlays are supported. There208 are no drivers yet which support both destructive and209 non-destructive overlays. Video Output Overlays are in practice210 always non-destructive.211 * - ``V4L2_FBUF_CAP_CHROMAKEY``212 - 0x0002213 - The device supports clipping by chroma-keying the images. That is,214 image pixels replace pixels in the VGA or video signal only where215 the latter assume a certain color. Chroma-keying makes no sense216 for destructive overlays.217 * - ``V4L2_FBUF_CAP_LIST_CLIPPING``218 - 0x0004219 - 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 - 0x0008223 - The device supports clipping using a bit mask.224 Note that this is no longer supported.225 * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``226 - 0x0010227 - The device supports clipping/blending using the alpha channel of228 the framebuffer or VGA signal. Alpha blending makes no sense for229 destructive overlays.230 * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``231 - 0x0020232 - 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 - 0x0040236 - The device supports clipping/blending using the inverted alpha237 channel of the framebuffer or VGA signal. Alpha blending makes no238 sense for destructive overlays.239 * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``240 - 0x0080241 - The device supports Source Chroma-keying. Video pixels with the242 chroma-key colors are replaced by framebuffer pixels, which is243 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:: longtable250 251.. flat-table:: Frame Buffer Flags252 :header-rows: 0253 :stub-columns: 0254 :widths: 3 1 4255 256 * - ``V4L2_FBUF_FLAG_PRIMARY``257 - 0x0001258 - The framebuffer is the primary graphics surface. In other words,259 the overlay is destructive. This flag is typically set by any260 driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``261 capability and it is cleared otherwise.262 * - ``V4L2_FBUF_FLAG_OVERLAY``263 - 0x0002264 - If this flag is set for a video capture device, then the driver265 will set the initial overlay size to cover the full framebuffer266 size, otherwise the existing overlay size (as set by267 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one268 video capture driver (bttv) supports this flag. The use of this269 flag for capture devices is deprecated. There is no way to detect270 which drivers support this flag, so the only reliable method of271 setting the overlay size is through272 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a273 video output device, then the video output overlay window is274 relative to the top-left corner of the framebuffer and restricted275 to the size of the framebuffer. If it is cleared, then the video276 output overlay window is relative to the video output display.277 * - ``V4L2_FBUF_FLAG_CHROMAKEY``278 - 0x0004279 - Use chroma-keying. The chroma-key color is determined by the280 ``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 of284 clip rectangles or a bitmap. These methods are negotiated with the285 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`286 and :ref:`osd`.287 * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``288 - 0x0008289 - Use the alpha channel of the framebuffer to clip or blend290 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 - 0x0010295 - Use a global alpha value to blend the framebuffer with video296 images. The blend function is: output = (framebuffer pixel * alpha297 + video pixel * (255 - alpha)) / 255. The alpha value is298 determined by the ``global_alpha`` field of struct299 :c:type:`v4l2_window` and negotiated with the300 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`301 and :ref:`osd`.302 * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``303 - 0x0020304 - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the305 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 actual308 alpha depth depends on the framebuffer pixel format.309 * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``310 - 0x0040311 - Use source chroma-keying. The source chroma-key color is312 determined by the ``chromakey`` field of struct313 :c:type:`v4l2_window` and negotiated with the314 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`315 and :ref:`osd`. Both chroma-keying are mutual exclusive to each316 other, so same ``chromakey`` field of struct317 :c:type:`v4l2_window` is being used.318 319Return Value320============321 322On success 0 is returned, on error -1 and the ``errno`` variable is set323appropriately. The generic error codes are described at the324:ref:`Generic Error Codes <gen-errors>` chapter.325 326EPERM327 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to328 negotiate the parameters for a destructive overlay.329 330EINVAL331 The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.332