1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_G_FBUF:
5
6 **********************************
7 ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
8 **********************************
9
10 Name
11 ====
12
13 VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set fra
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_G_FBUF
19
20 ``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2
21
22 .. c:macro:: VIDIOC_S_FBUF
23
24 ``int ioctl(int fd, VIDIOC_S_FBUF, const struc
25
26 Arguments
27 =========
28
29 ``fd``
30 File descriptor returned by :c:func:`open(
31
32 ``argp``
33 Pointer to struct :c:type:`v4l2_framebuffe
34
35 Description
36 ===========
37
38 Applications can use the :ref:`VIDIOC_G_FBUF <
39 to get and set the framebuffer parameters for
40 :ref:`Video Overlay <overlay>` or :ref:`Video
41 (OSD). The type of overlay is implied by the d
42 output device) and can be determined with the
43 :ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/video
44 device must not support both kinds of overlay.
45
46 The V4L2 API distinguishes destructive and non
47 destructive overlay copies captured video imag
48 of a graphics card. A non-destructive overlay
49 VGA signal or graphics into a video signal. *V
50 always non-destructive.
51
52 Destructive overlay support has been removed:
53 this is no longer needed, and it was always a
54
55 To get the current parameters applications cal
56 ioctl with a pointer to a struct :c:type:`v4l2
57 structure. The driver fills all fields of the
58 EINVAL error code when overlays are not suppor
59
60 To set the parameters for a *Video Output Over
61 initialize the ``flags`` field of a struct
62 :c:type:`v4l2_framebuffer`. Since the framebuf
63 implemented on the TV card all other parameter
64 driver. When an application calls :ref:`VIDIOC
65 this structure, the driver prepares for the ov
66 framebuffer parameters as :ref:`VIDIOC_G_FBUF
67 code.
68
69 To set the parameters for a *Video Capture Ove
70 applications must initialize the ``flags`` fie
71 substructure, and call :ref:`VIDIOC_S_FBUF <VI
72 the overlay and returns the framebuffer parame
73 does, or it returns an error code.
74
75 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm
76
77 .. c:type:: v4l2_framebuffer
78
79 .. cssclass:: longtable
80
81 .. flat-table:: struct v4l2_framebuffer
82 :header-rows: 0
83 :stub-columns: 0
84 :widths: 1 1 1 2
85
86 * - __u32
87 - ``capability``
88 -
89 - Overlay capability flags set by the dr
90 :ref:`framebuffer-cap`.
91 * - __u32
92 - ``flags``
93 -
94 - Overlay control flags set by applicati
95 :ref:`framebuffer-flags`
96 * - void *
97 - ``base``
98 -
99 - Physical base address of the framebuff
100 the pixel in the top left corner of th
101 For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF
102 and the kernel will always set this to
103 For *Video Output Overlays*
104 the driver will return a valid base ad
105 find the corresponding Linux framebuff
106 :ref:`osd`). For *Video Capture Overla
107 NULL.
108 * - struct
109 - ``fmt``
110 -
111 - Layout of the frame buffer.
112 * -
113 - __u32
114 - ``width``
115 - Width of the frame buffer in pixels.
116 * -
117 - __u32
118 - ``height``
119 - Height of the frame buffer in pixels.
120 * -
121 - __u32
122 - ``pixelformat``
123 - The pixel format of the framebuffer.
124 * -
125 -
126 -
127 - For *non-destructive Video Overlays* t
128 format for the struct :c:type:`v4l2_wi
129 ``chromakey`` field.
130 * -
131 -
132 -
133 - For *Video Output Overlays* the driver
134 format.
135 * -
136 -
137 -
138 - Usually this is an RGB format (for exa
139 :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FM
140 formats (only packed YUV formats when
141 including ``V4L2_PIX_FMT_YUYV`` and ``
142 ``V4L2_PIX_FMT_PAL8`` format are also
143 the driver when an application request
144 undefined. See :ref:`pixfmt` for infor
145 * -
146 - enum :c:type:`v4l2_field`
147 - ``field``
148 - Drivers and applications shall ignore
149 the field order is selected with the
150 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioc
151 field of struct :c:type:`v4l2_window`.
152 * -
153 - __u32
154 - ``bytesperline``
155 - Distance in bytes between the leftmost
156 lines.
157 * - :cspan:`3`
158
159 This field is irrelevant to *non-destr
160
161 For *Video Output Overlays* the driver
162
163 Video hardware may access padding byte
164 reside in accessible memory. Consider
165 padding bytes after the last line of a
166 boundary. Capture devices may write pa
167 undefined. Output devices ignore the c
168
169 When the image format is planar the ``
170 to the first plane and is divided by t
171 ``width`` field for the other planes.
172 planes of a YUV 4:2:0 image have half
173 following each line as the Y plane. To
174 must return a ``bytesperline`` value r
175 the scale factor.
176 * -
177 - __u32
178 - ``sizeimage``
179 - This field is irrelevant to *non-destr
180 For *Video Output Overlays* the driver
181 format.
182
183 Together with ``base`` it defines the
184 accessible by the driver.
185 * -
186 - enum :c:type:`v4l2_colorspace`
187 - ``colorspace``
188 - This information supplements the ``pix
189 by the driver, see :ref:`colorspaces`.
190 * -
191 - __u32
192 - ``priv``
193 - Reserved. Drivers and applications mus
194
195 .. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm
196
197 .. _framebuffer-cap:
198
199 .. flat-table:: Frame Buffer Capability Flags
200 :header-rows: 0
201 :stub-columns: 0
202 :widths: 3 1 4
203
204 * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
205 - 0x0001
206 - The device is capable of non-destructi
207 clears this flag, only destructive ove
208 are no drivers yet which support both
209 non-destructive overlays. Video Output
210 always non-destructive.
211 * - ``V4L2_FBUF_CAP_CHROMAKEY``
212 - 0x0002
213 - The device supports clipping by chroma
214 image pixels replace pixels in the VGA
215 the latter assume a certain color. Chr
216 for destructive overlays.
217 * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
218 - 0x0004
219 - The device supports clipping using a l
220 Note that this is no longer supported.
221 * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
222 - 0x0008
223 - The device supports clipping using a b
224 Note that this is no longer supported.
225 * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
226 - 0x0010
227 - The device supports clipping/blending
228 the framebuffer or VGA signal. Alpha b
229 destructive overlays.
230 * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
231 - 0x0020
232 - The device supports alpha blending usi
233 Alpha blending makes no sense for dest
234 * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
235 - 0x0040
236 - The device supports clipping/blending
237 channel of the framebuffer or VGA sign
238 sense for destructive overlays.
239 * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
240 - 0x0080
241 - The device supports Source Chroma-keyi
242 chroma-key colors are replaced by fram
243 exactly opposite of ``V4L2_FBUF_CAP_CH
244
245 .. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm
246
247 .. _framebuffer-flags:
248
249 .. cssclass:: longtable
250
251 .. flat-table:: Frame Buffer Flags
252 :header-rows: 0
253 :stub-columns: 0
254 :widths: 3 1 4
255
256 * - ``V4L2_FBUF_FLAG_PRIMARY``
257 - 0x0001
258 - The framebuffer is the primary graphic
259 the overlay is destructive. This flag
260 driver that doesn't have the ``V4L2_FB
261 capability and it is cleared otherwise
262 * - ``V4L2_FBUF_FLAG_OVERLAY``
263 - 0x0002
264 - If this flag is set for a video captur
265 will set the initial overlay size to c
266 size, otherwise the existing overlay s
267 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) wi
268 video capture driver (bttv) supports t
269 flag for capture devices is deprecated
270 which drivers support this flag, so th
271 setting the overlay size is through
272 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If
273 video output device, then the video ou
274 relative to the top-left corner of the
275 to the size of the framebuffer. If it
276 output overlay window is relative to t
277 * - ``V4L2_FBUF_FLAG_CHROMAKEY``
278 - 0x0004
279 - Use chroma-keying. The chroma-key colo
280 ``chromakey`` field of struct :c:type:
281 and negotiated with the :ref:`VIDIOC_S
282 ioctl, see :ref:`overlay` and :ref:`os
283 * - :cspan:`2` There are no flags to enabl
284 clip rectangles or a bitmap. These met
285 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioc
286 and :ref:`osd`.
287 * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
288 - 0x0008
289 - Use the alpha channel of the framebuff
290 framebuffer pixels with video images.
291 output = framebuffer pixel * alpha + v
292 The actual alpha depth depends on the
293 * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
294 - 0x0010
295 - Use a global alpha value to blend the
296 images. The blend function is: output
297 + video pixel * (255 - alpha)) / 255.
298 determined by the ``global_alpha`` fie
299 :c:type:`v4l2_window` and negotiated w
300 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioc
301 and :ref:`osd`.
302 * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
303 - 0x0020
304 - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, u
305 framebuffer to clip or blend framebuff
306 but with an inverted alpha value. The
307 framebuffer pixel * (1 - alpha) + vide
308 alpha depth depends on the framebuffer
309 * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
310 - 0x0040
311 - Use source chroma-keying. The source c
312 determined by the ``chromakey`` field
313 :c:type:`v4l2_window` and negotiated w
314 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioc
315 and :ref:`osd`. Both chroma-keying are
316 other, so same ``chromakey`` field of
317 :c:type:`v4l2_window` is being used.
318
319 Return Value
320 ============
321
322 On success 0 is returned, on error -1 and the
323 appropriately. The generic error codes are des
324 :ref:`Generic Error Codes <gen-errors>` chapte
325
326 EPERM
327 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can o
328 negotiate the parameters for a destructive
329
330 EINVAL
331 The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` p
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.