Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_FBUF: |
5377d91f MH |
4 | |
5 | ********************************** | |
6 | ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF | |
7 | ********************************** | |
8 | ||
9 | *man VIDIOC_G_FBUF(2)* | |
10 | ||
11 | VIDIOC_S_FBUF | |
12 | Get or set frame buffer overlay parameters | |
13 | ||
14 | ||
15 | Synopsis | |
16 | ======== | |
17 | ||
18 | .. c:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp ) | |
19 | ||
20 | .. c:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp ) | |
21 | ||
22 | Arguments | |
23 | ========= | |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <func-open>`. | |
27 | ||
28 | ``request`` | |
29 | VIDIOC_G_FBUF, VIDIOC_S_FBUF | |
30 | ||
31 | ``argp`` | |
32 | ||
33 | ||
34 | Description | |
35 | =========== | |
36 | ||
4e03cb76 | 37 | Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl |
5377d91f MH |
38 | to get and set the framebuffer parameters for a |
39 | :ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>` | |
40 | (OSD). The type of overlay is implied by the device type (capture or | |
41 | output device) and can be determined with the | |
7347081e | 42 | :ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN`` |
5377d91f MH |
43 | device must not support both kinds of overlay. |
44 | ||
45 | The V4L2 API distinguishes destructive and non-destructive overlays. A | |
46 | destructive overlay copies captured video images into the video memory | |
47 | of a graphics card. A non-destructive overlay blends video images into a | |
48 | VGA signal or graphics into a video signal. *Video Output Overlays* are | |
49 | always non-destructive. | |
50 | ||
4e03cb76 | 51 | To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` |
5377d91f MH |
52 | ioctl with a pointer to a :c:type:`struct v4l2_framebuffer` |
53 | structure. The driver fills all fields of the structure or returns an | |
54 | EINVAL error code when overlays are not supported. | |
55 | ||
56 | To set the parameters for a *Video Output Overlay*, applications must | |
57 | initialize the ``flags`` field of a struct | |
58 | :c:type:`struct v4l2_framebuffer`. Since the framebuffer is | |
59 | implemented on the TV card all other parameters are determined by the | |
2212ff25 | 60 | driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to |
5377d91f | 61 | this structure, the driver prepares for the overlay and returns the |
4e03cb76 | 62 | framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error |
5377d91f MH |
63 | code. |
64 | ||
65 | To set the parameters for a *non-destructive Video Overlay*, | |
66 | applications must initialize the ``flags`` field, the ``fmt`` | |
2212ff25 | 67 | substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for |
4e03cb76 | 68 | the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` |
5377d91f MH |
69 | does, or it returns an error code. |
70 | ||
71 | For a *destructive Video Overlay* applications must additionally provide | |
72 | a ``base`` address. Setting up a DMA to a random memory location can | |
73 | jeopardize the system security, its stability or even damage the | |
74 | hardware, therefore only the superuser can set the parameters for a | |
75 | destructive video overlay. | |
76 | ||
77 | ||
78 | .. _v4l2-framebuffer: | |
79 | ||
80 | .. flat-table:: struct v4l2_framebuffer | |
81 | :header-rows: 0 | |
82 | :stub-columns: 0 | |
83 | :widths: 1 1 1 2 | |
84 | ||
85 | ||
86 | - .. row 1 | |
87 | ||
88 | - __u32 | |
89 | ||
90 | - ``capability`` | |
91 | ||
92 | - | |
93 | - Overlay capability flags set by the driver, see | |
94 | :ref:`framebuffer-cap`. | |
95 | ||
96 | - .. row 2 | |
97 | ||
98 | - __u32 | |
99 | ||
100 | - ``flags`` | |
101 | ||
102 | - | |
103 | - Overlay control flags set by application and driver, see | |
104 | :ref:`framebuffer-flags` | |
105 | ||
106 | - .. row 3 | |
107 | ||
108 | - void * | |
109 | ||
110 | - ``base`` | |
111 | ||
112 | - | |
113 | - Physical base address of the framebuffer, that is the address of | |
114 | the pixel in the top left corner of the framebuffer. [1]_ | |
115 | ||
116 | - .. row 4 | |
117 | ||
118 | - | |
119 | - | |
120 | - | |
121 | - This field is irrelevant to *non-destructive Video Overlays*. For | |
122 | *destructive Video Overlays* applications must provide a base | |
123 | address. The driver may accept only base addresses which are a | |
124 | multiple of two, four or eight bytes. For *Video Output Overlays* | |
125 | the driver must return a valid base address, so applications can | |
126 | find the corresponding Linux framebuffer device (see | |
127 | :ref:`osd`). | |
128 | ||
129 | - .. row 5 | |
130 | ||
131 | - struct | |
132 | ||
133 | - ``fmt`` | |
134 | ||
135 | - | |
136 | - Layout of the frame buffer. | |
137 | ||
138 | - .. row 6 | |
139 | ||
140 | - | |
141 | - __u32 | |
142 | ||
143 | - ``width`` | |
144 | ||
145 | - Width of the frame buffer in pixels. | |
146 | ||
147 | - .. row 7 | |
148 | ||
149 | - | |
150 | - __u32 | |
151 | ||
152 | - ``height`` | |
153 | ||
154 | - Height of the frame buffer in pixels. | |
155 | ||
156 | - .. row 8 | |
157 | ||
158 | - | |
159 | - __u32 | |
160 | ||
161 | - ``pixelformat`` | |
162 | ||
163 | - The pixel format of the framebuffer. | |
164 | ||
165 | - .. row 9 | |
166 | ||
167 | - | |
168 | - | |
169 | - | |
170 | - For *non-destructive Video Overlays* this field only defines a | |
171 | format for the struct :ref:`v4l2_window <v4l2-window>` | |
172 | ``chromakey`` field. | |
173 | ||
174 | - .. row 10 | |
175 | ||
176 | - | |
177 | - | |
178 | - | |
179 | - For *destructive Video Overlays* applications must initialize this | |
180 | field. For *Video Output Overlays* the driver must return a valid | |
181 | format. | |
182 | ||
183 | - .. row 11 | |
184 | ||
185 | - | |
186 | - | |
187 | - | |
188 | - Usually this is an RGB format (for example | |
189 | :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV | |
190 | formats (only packed YUV formats when chroma keying is used, not | |
191 | including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the | |
192 | ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of | |
193 | the driver when an application requests a compressed format is | |
194 | undefined. See :ref:`pixfmt` for information on pixel formats. | |
195 | ||
196 | - .. row 12 | |
197 | ||
198 | - | |
199 | - enum :ref:`v4l2_field <v4l2-field>` | |
200 | ||
201 | - ``field`` | |
202 | ||
203 | - Drivers and applications shall ignore this field. If applicable, | |
204 | the field order is selected with the | |
af4a4d0d | 205 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field`` |
5377d91f MH |
206 | field of struct :ref:`v4l2_window <v4l2-window>`. |
207 | ||
208 | - .. row 13 | |
209 | ||
210 | - | |
211 | - __u32 | |
212 | ||
213 | - ``bytesperline`` | |
214 | ||
215 | - Distance in bytes between the leftmost pixels in two adjacent | |
216 | lines. | |
217 | ||
218 | - .. row 14 | |
219 | ||
220 | - :cspan:`3` | |
221 | ||
222 | This field is irrelevant to *non-destructive Video Overlays*. | |
223 | ||
224 | For *destructive Video Overlays* both applications and drivers can | |
225 | set this field to request padding bytes at the end of each line. | |
226 | Drivers however may ignore the requested value, returning | |
227 | ``width`` times bytes-per-pixel or a larger value required by the | |
228 | hardware. That implies applications can just set this field to | |
229 | zero to get a reasonable default. | |
230 | ||
231 | For *Video Output Overlays* the driver must return a valid value. | |
232 | ||
233 | Video hardware may access padding bytes, therefore they must | |
234 | reside in accessible memory. Consider for example the case where | |
235 | padding bytes after the last line of an image cross a system page | |
236 | boundary. Capture devices may write padding bytes, the value is | |
237 | undefined. Output devices ignore the contents of padding bytes. | |
238 | ||
239 | When the image format is planar the ``bytesperline`` value applies | |
240 | to the first plane and is divided by the same factor as the | |
241 | ``width`` field for the other planes. For example the Cb and Cr | |
242 | planes of a YUV 4:2:0 image have half as many padding bytes | |
243 | following each line as the Y plane. To avoid ambiguities drivers | |
244 | must return a ``bytesperline`` value rounded up to a multiple of | |
245 | the scale factor. | |
246 | ||
247 | - .. row 15 | |
248 | ||
249 | - | |
250 | - __u32 | |
251 | ||
252 | - ``sizeimage`` | |
253 | ||
254 | - This field is irrelevant to *non-destructive Video Overlays*. For | |
255 | *destructive Video Overlays* applications must initialize this | |
256 | field. For *Video Output Overlays* the driver must return a valid | |
257 | format. | |
258 | ||
259 | Together with ``base`` it defines the framebuffer memory | |
260 | accessible by the driver. | |
261 | ||
262 | - .. row 16 | |
263 | ||
264 | - | |
265 | - enum :ref:`v4l2_colorspace <v4l2-colorspace>` | |
266 | ||
267 | - ``colorspace`` | |
268 | ||
269 | - This information supplements the ``pixelformat`` and must be set | |
270 | by the driver, see :ref:`colorspaces`. | |
271 | ||
272 | - .. row 17 | |
273 | ||
274 | - | |
275 | - __u32 | |
276 | ||
277 | - ``priv`` | |
278 | ||
279 | - Reserved. Drivers and applications must set this field to zero. | |
280 | ||
281 | ||
282 | ||
283 | .. _framebuffer-cap: | |
284 | ||
285 | .. flat-table:: Frame Buffer Capability Flags | |
286 | :header-rows: 0 | |
287 | :stub-columns: 0 | |
288 | :widths: 3 1 4 | |
289 | ||
290 | ||
291 | - .. row 1 | |
292 | ||
293 | - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` | |
294 | ||
295 | - 0x0001 | |
296 | ||
297 | - The device is capable of non-destructive overlays. When the driver | |
298 | clears this flag, only destructive overlays are supported. There | |
299 | are no drivers yet which support both destructive and | |
300 | non-destructive overlays. Video Output Overlays are in practice | |
301 | always non-destructive. | |
302 | ||
303 | - .. row 2 | |
304 | ||
305 | - ``V4L2_FBUF_CAP_CHROMAKEY`` | |
306 | ||
307 | - 0x0002 | |
308 | ||
309 | - The device supports clipping by chroma-keying the images. That is, | |
310 | image pixels replace pixels in the VGA or video signal only where | |
311 | the latter assume a certain color. Chroma-keying makes no sense | |
312 | for destructive overlays. | |
313 | ||
314 | - .. row 3 | |
315 | ||
316 | - ``V4L2_FBUF_CAP_LIST_CLIPPING`` | |
317 | ||
318 | - 0x0004 | |
319 | ||
320 | - The device supports clipping using a list of clip rectangles. | |
321 | ||
322 | - .. row 4 | |
323 | ||
324 | - ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` | |
325 | ||
326 | - 0x0008 | |
327 | ||
328 | - The device supports clipping using a bit mask. | |
329 | ||
330 | - .. row 5 | |
331 | ||
332 | - ``V4L2_FBUF_CAP_LOCAL_ALPHA`` | |
333 | ||
334 | - 0x0010 | |
335 | ||
336 | - The device supports clipping/blending using the alpha channel of | |
337 | the framebuffer or VGA signal. Alpha blending makes no sense for | |
338 | destructive overlays. | |
339 | ||
340 | - .. row 6 | |
341 | ||
342 | - ``V4L2_FBUF_CAP_GLOBAL_ALPHA`` | |
343 | ||
344 | - 0x0020 | |
345 | ||
346 | - The device supports alpha blending using a global alpha value. | |
347 | Alpha blending makes no sense for destructive overlays. | |
348 | ||
349 | - .. row 7 | |
350 | ||
351 | - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA`` | |
352 | ||
353 | - 0x0040 | |
354 | ||
355 | - The device supports clipping/blending using the inverted alpha | |
356 | channel of the framebuffer or VGA signal. Alpha blending makes no | |
357 | sense for destructive overlays. | |
358 | ||
359 | - .. row 8 | |
360 | ||
361 | - ``V4L2_FBUF_CAP_SRC_CHROMAKEY`` | |
362 | ||
363 | - 0x0080 | |
364 | ||
365 | - The device supports Source Chroma-keying. Video pixels with the | |
366 | chroma-key colors are replaced by framebuffer pixels, which is | |
367 | exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` | |
368 | ||
369 | ||
370 | ||
371 | .. _framebuffer-flags: | |
372 | ||
373 | .. flat-table:: Frame Buffer Flags | |
374 | :header-rows: 0 | |
375 | :stub-columns: 0 | |
376 | :widths: 3 1 4 | |
377 | ||
378 | ||
379 | - .. row 1 | |
380 | ||
381 | - ``V4L2_FBUF_FLAG_PRIMARY`` | |
382 | ||
383 | - 0x0001 | |
384 | ||
385 | - The framebuffer is the primary graphics surface. In other words, | |
386 | the overlay is destructive. This flag is typically set by any | |
387 | driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY`` | |
388 | capability and it is cleared otherwise. | |
389 | ||
390 | - .. row 2 | |
391 | ||
392 | - ``V4L2_FBUF_FLAG_OVERLAY`` | |
393 | ||
394 | - 0x0002 | |
395 | ||
396 | - If this flag is set for a video capture device, then the driver | |
397 | will set the initial overlay size to cover the full framebuffer | |
398 | size, otherwise the existing overlay size (as set by | |
af4a4d0d | 399 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one |
5377d91f MH |
400 | video capture driver (bttv) supports this flag. The use of this |
401 | flag for capture devices is deprecated. There is no way to detect | |
402 | which drivers support this flag, so the only reliable method of | |
403 | setting the overlay size is through | |
af4a4d0d | 404 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a |
5377d91f MH |
405 | video output device, then the video output overlay window is |
406 | relative to the top-left corner of the framebuffer and restricted | |
407 | to the size of the framebuffer. If it is cleared, then the video | |
408 | output overlay window is relative to the video output display. | |
409 | ||
410 | - .. row 3 | |
411 | ||
412 | - ``V4L2_FBUF_FLAG_CHROMAKEY`` | |
413 | ||
414 | - 0x0004 | |
415 | ||
416 | - Use chroma-keying. The chroma-key color is determined by the | |
417 | ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>` | |
af4a4d0d | 418 | and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
5377d91f MH |
419 | ioctl, see :ref:`overlay` and :ref:`osd`. |
420 | ||
421 | - .. row 4 | |
422 | ||
423 | - :cspan:`2` There are no flags to enable clipping using a list of | |
424 | clip rectangles or a bitmap. These methods are negotiated with the | |
af4a4d0d | 425 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` |
5377d91f MH |
426 | and :ref:`osd`. |
427 | ||
428 | - .. row 5 | |
429 | ||
430 | - ``V4L2_FBUF_FLAG_LOCAL_ALPHA`` | |
431 | ||
432 | - 0x0008 | |
433 | ||
434 | - Use the alpha channel of the framebuffer to clip or blend | |
435 | framebuffer pixels with video images. The blend function is: | |
436 | output = framebuffer pixel * alpha + video pixel * (1 - alpha). | |
437 | The actual alpha depth depends on the framebuffer pixel format. | |
438 | ||
439 | - .. row 6 | |
440 | ||
441 | - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA`` | |
442 | ||
443 | - 0x0010 | |
444 | ||
445 | - Use a global alpha value to blend the framebuffer with video | |
446 | images. The blend function is: output = (framebuffer pixel * alpha | |
447 | + video pixel * (255 - alpha)) / 255. The alpha value is | |
448 | determined by the ``global_alpha`` field of struct | |
449 | :ref:`v4l2_window <v4l2-window>` and negotiated with the | |
af4a4d0d | 450 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` |
5377d91f MH |
451 | and :ref:`osd`. |
452 | ||
453 | - .. row 7 | |
454 | ||
455 | - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA`` | |
456 | ||
457 | - 0x0020 | |
458 | ||
459 | - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the | |
460 | framebuffer to clip or blend framebuffer pixels with video images, | |
461 | but with an inverted alpha value. The blend function is: output = | |
462 | framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual | |
463 | alpha depth depends on the framebuffer pixel format. | |
464 | ||
465 | - .. row 8 | |
466 | ||
467 | - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY`` | |
468 | ||
469 | - 0x0040 | |
470 | ||
471 | - Use source chroma-keying. The source chroma-key color is | |
472 | determined by the ``chromakey`` field of struct | |
473 | :ref:`v4l2_window <v4l2-window>` and negotiated with the | |
af4a4d0d | 474 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay` |
5377d91f MH |
475 | and :ref:`osd`. Both chroma-keying are mutual exclusive to each |
476 | other, so same ``chromakey`` field of struct | |
477 | :ref:`v4l2_window <v4l2-window>` is being used. | |
478 | ||
479 | ||
480 | ||
481 | Return Value | |
482 | ============ | |
483 | ||
484 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
485 | appropriately. The generic error codes are described at the | |
486 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
487 | ||
488 | EPERM | |
2212ff25 | 489 | :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to |
5377d91f MH |
490 | negotiate the parameters for a destructive overlay. |
491 | ||
492 | EINVAL | |
2212ff25 | 493 | The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. |
5377d91f MH |
494 | |
495 | .. [1] | |
496 | A physical base address may not suit all platforms. GK notes in | |
497 | theory we should pass something like PCI device + memory region + | |
498 | offset instead. If you encounter problems please discuss on the | |
499 | linux-media mailing list: | |
500 | `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. | |
501 | ||
502 | ||
503 | .. ------------------------------------------------------------------------------ | |
504 | .. This file was automatically converted from DocBook-XML with the dbxml | |
505 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
506 | .. from the linux kernel, refer to: | |
507 | .. | |
508 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
509 | .. ------------------------------------------------------------------------------ |