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
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.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
79
80.. c:type:: v4l2_framebuffer
81
82.. cssclass:: longtable
83
84.. flat-table:: struct v4l2_framebuffer
85    :header-rows:  0
86    :stub-columns: 0
87    :widths:       1 1 1 2
88
89    * - __u32
90      - ``capability``
91      -
92      - Overlay capability flags set by the driver, see
93	:ref:`framebuffer-cap`.
94    * - __u32
95      - ``flags``
96      -
97      - Overlay control flags set by application and driver, see
98	:ref:`framebuffer-flags`
99    * - void *
100      - ``base``
101      -
102      - Physical base address of the framebuffer, that is the address of
103	the pixel in the top left corner of the framebuffer. [#f1]_
104    * -
105      -
106      -
107      - This field is irrelevant to *non-destructive Video Overlays*. For
108	*destructive Video Overlays* applications must provide a base
109	address. The driver may accept only base addresses which are a
110	multiple of two, four or eight bytes. For *Video Output Overlays*
111	the driver must return a valid base address, so applications can
112	find the corresponding Linux framebuffer device (see
113	:ref:`osd`).
114    * - struct
115      - ``fmt``
116      -
117      - Layout of the frame buffer.
118    * -
119      - __u32
120      - ``width``
121      - Width of the frame buffer in pixels.
122    * -
123      - __u32
124      - ``height``
125      - Height of the frame buffer in pixels.
126    * -
127      - __u32
128      - ``pixelformat``
129      - The pixel format of the framebuffer.
130    * -
131      -
132      -
133      - For *non-destructive Video Overlays* this field only defines a
134	format for the struct :c:type:`v4l2_window`
135	``chromakey`` field.
136    * -
137      -
138      -
139      - For *destructive Video Overlays* applications must initialize this
140	field. For *Video Output Overlays* the driver must return a valid
141	format.
142    * -
143      -
144      -
145      - Usually this is an RGB format (for example
146	:ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
147	formats (only packed YUV formats when chroma keying is used, not
148	including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
149	``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
150	the driver when an application requests a compressed format is
151	undefined. See :ref:`pixfmt` for information on pixel formats.
152    * -
153      - enum :c:type:`v4l2_field`
154      - ``field``
155      - Drivers and applications shall ignore this field. If applicable,
156	the field order is selected with the
157	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
158	field of struct :c:type:`v4l2_window`.
159    * -
160      - __u32
161      - ``bytesperline``
162      - Distance in bytes between the leftmost pixels in two adjacent
163	lines.
164    * - :cspan:`3`
165
166	This field is irrelevant to *non-destructive Video Overlays*.
167
168	For *destructive Video Overlays* both applications and drivers can
169	set this field to request padding bytes at the end of each line.
170	Drivers however may ignore the requested value, returning
171	``width`` times bytes-per-pixel or a larger value required by the
172	hardware. That implies applications can just set this field to
173	zero to get a reasonable default.
174
175	For *Video Output Overlays* the driver must return a valid value.
176
177	Video hardware may access padding bytes, therefore they must
178	reside in accessible memory. Consider for example the case where
179	padding bytes after the last line of an image cross a system page
180	boundary. Capture devices may write padding bytes, the value is
181	undefined. Output devices ignore the contents of padding bytes.
182
183	When the image format is planar the ``bytesperline`` value applies
184	to the first plane and is divided by the same factor as the
185	``width`` field for the other planes. For example the Cb and Cr
186	planes of a YUV 4:2:0 image have half as many padding bytes
187	following each line as the Y plane. To avoid ambiguities drivers
188	must return a ``bytesperline`` value rounded up to a multiple of
189	the scale factor.
190    * -
191      - __u32
192      - ``sizeimage``
193      - This field is irrelevant to *non-destructive Video Overlays*. For
194	*destructive Video Overlays* applications must initialize this
195	field. For *Video Output Overlays* the driver must return a valid
196	format.
197
198	Together with ``base`` it defines the framebuffer memory
199	accessible by the driver.
200    * -
201      - enum :c:type:`v4l2_colorspace`
202      - ``colorspace``
203      - This information supplements the ``pixelformat`` and must be set
204	by the driver, see :ref:`colorspaces`.
205    * -
206      - __u32
207      - ``priv``
208      - Reserved. Drivers and applications must set this field to zero.
209
210.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
211
212.. _framebuffer-cap:
213
214.. flat-table:: Frame Buffer Capability Flags
215    :header-rows:  0
216    :stub-columns: 0
217    :widths:       3 1 4
218
219    * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
220      - 0x0001
221      - The device is capable of non-destructive overlays. When the driver
222	clears this flag, only destructive overlays are supported. There
223	are no drivers yet which support both destructive and
224	non-destructive overlays. Video Output Overlays are in practice
225	always non-destructive.
226    * - ``V4L2_FBUF_CAP_CHROMAKEY``
227      - 0x0002
228      - The device supports clipping by chroma-keying the images. That is,
229	image pixels replace pixels in the VGA or video signal only where
230	the latter assume a certain color. Chroma-keying makes no sense
231	for destructive overlays.
232    * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
233      - 0x0004
234      - The device supports clipping using a list of clip rectangles.
235    * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
236      - 0x0008
237      - The device supports clipping using a bit mask.
238    * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
239      - 0x0010
240      - The device supports clipping/blending using the alpha channel of
241	the framebuffer or VGA signal. Alpha blending makes no sense for
242	destructive overlays.
243    * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
244      - 0x0020
245      - The device supports alpha blending using a global alpha value.
246	Alpha blending makes no sense for destructive overlays.
247    * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
248      - 0x0040
249      - The device supports clipping/blending using the inverted alpha
250	channel of the framebuffer or VGA signal. Alpha blending makes no
251	sense for destructive overlays.
252    * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
253      - 0x0080
254      - The device supports Source Chroma-keying. Video pixels with the
255	chroma-key colors are replaced by framebuffer pixels, which is
256	exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
257
258.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
259
260.. _framebuffer-flags:
261
262.. cssclass:: longtable
263
264.. flat-table:: Frame Buffer Flags
265    :header-rows:  0
266    :stub-columns: 0
267    :widths:       3 1 4
268
269    * - ``V4L2_FBUF_FLAG_PRIMARY``
270      - 0x0001
271      - The framebuffer is the primary graphics surface. In other words,
272	the overlay is destructive. This flag is typically set by any
273	driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
274	capability and it is cleared otherwise.
275    * - ``V4L2_FBUF_FLAG_OVERLAY``
276      - 0x0002
277      - If this flag is set for a video capture device, then the driver
278	will set the initial overlay size to cover the full framebuffer
279	size, otherwise the existing overlay size (as set by
280	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
281	video capture driver (bttv) supports this flag. The use of this
282	flag for capture devices is deprecated. There is no way to detect
283	which drivers support this flag, so the only reliable method of
284	setting the overlay size is through
285	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
286	video output device, then the video output overlay window is
287	relative to the top-left corner of the framebuffer and restricted
288	to the size of the framebuffer. If it is cleared, then the video
289	output overlay window is relative to the video output display.
290    * - ``V4L2_FBUF_FLAG_CHROMAKEY``
291      - 0x0004
292      - Use chroma-keying. The chroma-key color is determined by the
293	``chromakey`` field of struct :c:type:`v4l2_window`
294	and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
295	ioctl, see :ref:`overlay` and :ref:`osd`.
296    * - :cspan:`2` There are no flags to enable clipping using a list of
297	clip rectangles or a bitmap. These methods are negotiated with the
298	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
299	and :ref:`osd`.
300    * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
301      - 0x0008
302      - Use the alpha channel of the framebuffer to clip or blend
303	framebuffer pixels with video images. The blend function is:
304	output = framebuffer pixel * alpha + video pixel * (1 - alpha).
305	The actual alpha depth depends on the framebuffer pixel format.
306    * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
307      - 0x0010
308      - Use a global alpha value to blend the framebuffer with video
309	images. The blend function is: output = (framebuffer pixel * alpha
310	+ video pixel * (255 - alpha)) / 255. The alpha value is
311	determined by the ``global_alpha`` field of struct
312	:c:type:`v4l2_window` and negotiated with the
313	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
314	and :ref:`osd`.
315    * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
316      - 0x0020
317      - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
318	framebuffer to clip or blend framebuffer pixels with video images,
319	but with an inverted alpha value. The blend function is: output =
320	framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
321	alpha depth depends on the framebuffer pixel format.
322    * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
323      - 0x0040
324      - Use source chroma-keying. The source chroma-key color is
325	determined by the ``chromakey`` field of struct
326	:c:type:`v4l2_window` and negotiated with the
327	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
328	and :ref:`osd`. Both chroma-keying are mutual exclusive to each
329	other, so same ``chromakey`` field of struct
330	:c:type:`v4l2_window` is being used.
331
332Return Value
333============
334
335On success 0 is returned, on error -1 and the ``errno`` variable is set
336appropriately. The generic error codes are described at the
337:ref:`Generic Error Codes <gen-errors>` chapter.
338
339EPERM
340    :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
341    negotiate the parameters for a destructive overlay.
342
343EINVAL
344    The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
345
346.. [#f1]
347   A physical base address may not suit all platforms. GK notes in
348   theory we should pass something like PCI device + memory region +
349   offset instead. If you encounter problems please discuss on the
350   linux-media mailing list:
351   `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
352