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