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/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
12 **********************************
13 ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
14 **********************************
19 VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
25 .. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
28 .. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp )
36 File descriptor returned by :ref:`open() <func-open>`.
39 Pointer to struct :c:type:`v4l2_framebuffer`.
45 Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
46 to 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
49 output device) and can be determined with the
50 :ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
51 device must not support both kinds of overlay.
53 The V4L2 API distinguishes destructive and non-destructive overlays. A
54 destructive overlay copies captured video images into the video memory
55 of a graphics card. A non-destructive overlay blends video images into a
56 VGA signal or graphics into a video signal. *Video Output Overlays* are
57 always non-destructive.
59 To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
60 ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
61 structure. The driver fills all fields of the structure or returns an
62 EINVAL error code when overlays are not supported.
64 To set the parameters for a *Video Output Overlay*, applications must
65 initialize the ``flags`` field of a struct
66 struct :c:type:`v4l2_framebuffer`. Since the framebuffer is
67 implemented on the TV card all other parameters are determined by the
68 driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
69 this structure, the driver prepares for the overlay and returns the
70 framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
73 To set the parameters for a *non-destructive Video Overlay*,
74 applications must initialize the ``flags`` field, the ``fmt``
75 substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
76 the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
77 does, or it returns an error code.
79 For a *destructive Video Overlay* applications must additionally provide
80 a ``base`` address. Setting up a DMA to a random memory location can
81 jeopardize the system security, its stability or even damage the
82 hardware, therefore only the superuser can set the parameters for a
83 destructive video overlay.
86 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
88 .. c:type:: v4l2_framebuffer
90 .. cssclass:: longtable
92 .. flat-table:: struct v4l2_framebuffer
100 - Overlay capability flags set by the driver, see
101 :ref:`framebuffer-cap`.
105 - Overlay control flags set by application and driver, see
106 :ref:`framebuffer-flags`
110 - Physical base address of the framebuffer, that is the address of
111 the pixel in the top left corner of the framebuffer. [#f1]_
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
125 - Layout of the frame buffer.
129 - Width of the frame buffer in pixels.
133 - Height of the frame buffer in pixels.
137 - The pixel format of the framebuffer.
141 - For *non-destructive Video Overlays* this field only defines a
142 format for the struct :c:type:`v4l2_window`
147 - For *destructive Video Overlays* applications must initialize this
148 field. For *Video Output Overlays* the driver must return a valid
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.
161 - enum :c:type:`v4l2_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`.
170 - Distance in bytes between the leftmost pixels in two adjacent
174 This field is irrelevant to *non-destructive Video Overlays*.
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.
183 For *Video Output Overlays* the driver must return a valid value.
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.
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
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
206 Together with ``base`` it defines the framebuffer memory
207 accessible by the driver.
209 - enum :c:type:`v4l2_colorspace`
211 - This information supplements the ``pixelformat`` and must be set
212 by the driver, see :ref:`colorspaces`.
216 - Reserved. Drivers and applications must set this field to zero.
219 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
223 .. flat-table:: Frame Buffer Capability Flags
228 * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
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``
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``
243 - The device supports clipping using a list of clip rectangles.
244 * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
246 - The device supports clipping using a bit mask.
247 * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
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``
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``
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``
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``
268 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
270 .. _framebuffer-flags:
272 .. cssclass:: longtable
274 .. flat-table:: Frame Buffer Flags
279 * - ``V4L2_FBUF_FLAG_PRIMARY``
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``
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``
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`
310 * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
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``
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`
325 * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
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``
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.
346 On success 0 is returned, on error -1 and the ``errno`` variable is set
347 appropriately. The generic error codes are described at the
348 :ref:`Generic Error Codes <gen-errors>` chapter.
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.
355 The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
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>`__.