summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst
blob: d182d9f5a50dfc7a9cf09310ac882da501fa0377 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_G_FBUF:

**********************************
ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
**********************************

Name
====

VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp )

.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp )


Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_G_FBUF, VIDIOC_S_FBUF

``argp``


Description
===========

Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
to get and set the framebuffer parameters for a
:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
(OSD). The type of overlay is implied by the device type (capture or
output device) and can be determined with the
:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
device must not support both kinds of overlay.

The V4L2 API distinguishes destructive and non-destructive overlays. A
destructive overlay copies captured video images into the video memory
of a graphics card. A non-destructive overlay blends video images into a
VGA signal or graphics into a video signal. *Video Output Overlays* are
always non-destructive.

To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
ioctl with a pointer to a :ref:`struct v4l2_framebuffer <v4l2-framebuffer>`
structure. The driver fills all fields of the structure or returns an
EINVAL error code when overlays are not supported.

To set the parameters for a *Video Output Overlay*, applications must
initialize the ``flags`` field of a struct
:ref:`struct v4l2_framebuffer <v4l2-framebuffer>`. Since the framebuffer is
implemented on the TV card all other parameters are determined by the
driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
this structure, the driver prepares for the overlay and returns the
framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
code.

To set the parameters for a *non-destructive Video Overlay*,
applications must initialize the ``flags`` field, the ``fmt``
substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
does, or it returns an error code.

For a *destructive Video Overlay* applications must additionally provide
a ``base`` address. Setting up a DMA to a random memory location can
jeopardize the system security, its stability or even damage the
hardware, therefore only the superuser can set the parameters for a
destructive video overlay.


.. _v4l2-framebuffer:

.. flat-table:: struct v4l2_framebuffer
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 1 2


    -  .. row 1

       -  __u32

       -  ``capability``

       -
       -  Overlay capability flags set by the driver, see
	  :ref:`framebuffer-cap`.

    -  .. row 2

       -  __u32

       -  ``flags``

       -
       -  Overlay control flags set by application and driver, see
	  :ref:`framebuffer-flags`

    -  .. row 3

       -  void *

       -  ``base``

       -
       -  Physical base address of the framebuffer, that is the address of
	  the pixel in the top left corner of the framebuffer. [#f1]_

    -  .. row 4

       -
       -
       -
       -  This field is irrelevant to *non-destructive Video Overlays*. For
	  *destructive Video Overlays* applications must provide a base
	  address. The driver may accept only base addresses which are a
	  multiple of two, four or eight bytes. For *Video Output Overlays*
	  the driver must return a valid base address, so applications can
	  find the corresponding Linux framebuffer device (see
	  :ref:`osd`).

    -  .. row 5

       -  struct

       -  ``fmt``

       -
       -  Layout of the frame buffer.

    -  .. row 6

       -
       -  __u32

       -  ``width``

       -  Width of the frame buffer in pixels.

    -  .. row 7

       -
       -  __u32

       -  ``height``

       -  Height of the frame buffer in pixels.

    -  .. row 8

       -
       -  __u32

       -  ``pixelformat``

       -  The pixel format of the framebuffer.

    -  .. row 9

       -
       -
       -
       -  For *non-destructive Video Overlays* this field only defines a
	  format for the struct :ref:`v4l2_window <v4l2-window>`
	  ``chromakey`` field.

    -  .. row 10

       -
       -
       -
       -  For *destructive Video Overlays* applications must initialize this
	  field. For *Video Output Overlays* the driver must return a valid
	  format.

    -  .. row 11

       -
       -
       -
       -  Usually this is an RGB format (for example
	  :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
	  formats (only packed YUV formats when chroma keying is used, not
	  including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
	  ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
	  the driver when an application requests a compressed format is
	  undefined. See :ref:`pixfmt` for information on pixel formats.

    -  .. row 12

       -
       -  enum :ref:`v4l2_field <v4l2-field>`

       -  ``field``

       -  Drivers and applications shall ignore this field. If applicable,
	  the field order is selected with the
	  :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
	  field of struct :ref:`v4l2_window <v4l2-window>`.

    -  .. row 13

       -
       -  __u32

       -  ``bytesperline``

       -  Distance in bytes between the leftmost pixels in two adjacent
	  lines.

    -  .. row 14

       -  :cspan:`3`

	  This field is irrelevant to *non-destructive Video Overlays*.

	  For *destructive Video Overlays* both applications and drivers can
	  set this field to request padding bytes at the end of each line.
	  Drivers however may ignore the requested value, returning
	  ``width`` times bytes-per-pixel or a larger value required by the
	  hardware. That implies applications can just set this field to
	  zero to get a reasonable default.

	  For *Video Output Overlays* the driver must return a valid value.

	  Video hardware may access padding bytes, therefore they must
	  reside in accessible memory. Consider for example the case where
	  padding bytes after the last line of an image cross a system page
	  boundary. Capture devices may write padding bytes, the value is
	  undefined. Output devices ignore the contents of padding bytes.

	  When the image format is planar the ``bytesperline`` value applies
	  to the first plane and is divided by the same factor as the
	  ``width`` field for the other planes. For example the Cb and Cr
	  planes of a YUV 4:2:0 image have half as many padding bytes
	  following each line as the Y plane. To avoid ambiguities drivers
	  must return a ``bytesperline`` value rounded up to a multiple of
	  the scale factor.

    -  .. row 15

       -
       -  __u32

       -  ``sizeimage``

       -  This field is irrelevant to *non-destructive Video Overlays*. For
	  *destructive Video Overlays* applications must initialize this
	  field. For *Video Output Overlays* the driver must return a valid
	  format.

	  Together with ``base`` it defines the framebuffer memory
	  accessible by the driver.

    -  .. row 16

       -
       -  enum :ref:`v4l2_colorspace <v4l2-colorspace>`

       -  ``colorspace``

       -  This information supplements the ``pixelformat`` and must be set
	  by the driver, see :ref:`colorspaces`.

    -  .. row 17

       -
       -  __u32

       -  ``priv``

       -  Reserved. Drivers and applications must set this field to zero.



.. _framebuffer-cap:

.. flat-table:: Frame Buffer Capability Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_FBUF_CAP_EXTERNOVERLAY``

       -  0x0001

       -  The device is capable of non-destructive overlays. When the driver
	  clears this flag, only destructive overlays are supported. There
	  are no drivers yet which support both destructive and
	  non-destructive overlays. Video Output Overlays are in practice
	  always non-destructive.

    -  .. row 2

       -  ``V4L2_FBUF_CAP_CHROMAKEY``

       -  0x0002

       -  The device supports clipping by chroma-keying the images. That is,
	  image pixels replace pixels in the VGA or video signal only where
	  the latter assume a certain color. Chroma-keying makes no sense
	  for destructive overlays.

    -  .. row 3

       -  ``V4L2_FBUF_CAP_LIST_CLIPPING``

       -  0x0004

       -  The device supports clipping using a list of clip rectangles.

    -  .. row 4

       -  ``V4L2_FBUF_CAP_BITMAP_CLIPPING``

       -  0x0008

       -  The device supports clipping using a bit mask.

    -  .. row 5

       -  ``V4L2_FBUF_CAP_LOCAL_ALPHA``

       -  0x0010

       -  The device supports clipping/blending using the alpha channel of
	  the framebuffer or VGA signal. Alpha blending makes no sense for
	  destructive overlays.

    -  .. row 6

       -  ``V4L2_FBUF_CAP_GLOBAL_ALPHA``

       -  0x0020

       -  The device supports alpha blending using a global alpha value.
	  Alpha blending makes no sense for destructive overlays.

    -  .. row 7

       -  ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``

       -  0x0040

       -  The device supports clipping/blending using the inverted alpha
	  channel of the framebuffer or VGA signal. Alpha blending makes no
	  sense for destructive overlays.

    -  .. row 8

       -  ``V4L2_FBUF_CAP_SRC_CHROMAKEY``

       -  0x0080

       -  The device supports Source Chroma-keying. Video pixels with the
	  chroma-key colors are replaced by framebuffer pixels, which is
	  exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``



.. _framebuffer-flags:

.. flat-table:: Frame Buffer Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_FBUF_FLAG_PRIMARY``

       -  0x0001

       -  The framebuffer is the primary graphics surface. In other words,
	  the overlay is destructive. This flag is typically set by any
	  driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
	  capability and it is cleared otherwise.

    -  .. row 2

       -  ``V4L2_FBUF_FLAG_OVERLAY``

       -  0x0002

       -  If this flag is set for a video capture device, then the driver
	  will set the initial overlay size to cover the full framebuffer
	  size, otherwise the existing overlay size (as set by
	  :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
	  video capture driver (bttv) supports this flag. The use of this
	  flag for capture devices is deprecated. There is no way to detect
	  which drivers support this flag, so the only reliable method of
	  setting the overlay size is through
	  :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
	  video output device, then the video output overlay window is
	  relative to the top-left corner of the framebuffer and restricted
	  to the size of the framebuffer. If it is cleared, then the video
	  output overlay window is relative to the video output display.

    -  .. row 3

       -  ``V4L2_FBUF_FLAG_CHROMAKEY``

       -  0x0004

       -  Use chroma-keying. The chroma-key color is determined by the
	  ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>`
	  and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
	  ioctl, see :ref:`overlay` and :ref:`osd`.

    -  .. row 4

       -  :cspan:`2` There are no flags to enable clipping using a list of
	  clip rectangles or a bitmap. These methods are negotiated with the
	  :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
	  and :ref:`osd`.

    -  .. row 5

       -  ``V4L2_FBUF_FLAG_LOCAL_ALPHA``

       -  0x0008

       -  Use the alpha channel of the framebuffer to clip or blend
	  framebuffer pixels with video images. The blend function is:
	  output = framebuffer pixel * alpha + video pixel * (1 - alpha).
	  The actual alpha depth depends on the framebuffer pixel format.

    -  .. row 6

       -  ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``

       -  0x0010

       -  Use a global alpha value to blend the framebuffer with video
	  images. The blend function is: output = (framebuffer pixel * alpha
	  + video pixel * (255 - alpha)) / 255. The alpha value is
	  determined by the ``global_alpha`` field of struct
	  :ref:`v4l2_window <v4l2-window>` and negotiated with the
	  :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
	  and :ref:`osd`.

    -  .. row 7

       -  ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``

       -  0x0020

       -  Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
	  framebuffer to clip or blend framebuffer pixels with video images,
	  but with an inverted alpha value. The blend function is: output =
	  framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
	  alpha depth depends on the framebuffer pixel format.

    -  .. row 8

       -  ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``

       -  0x0040

       -  Use source chroma-keying. The source chroma-key color is
	  determined by the ``chromakey`` field of struct
	  :ref:`v4l2_window <v4l2-window>` and negotiated with the
	  :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
	  and :ref:`osd`. Both chroma-keying are mutual exclusive to each
	  other, so same ``chromakey`` field of struct
	  :ref:`v4l2_window <v4l2-window>` is being used.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EPERM
    :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
    negotiate the parameters for a destructive overlay.

EINVAL
    The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.

.. [#f1]
   A physical base address may not suit all platforms. GK notes in
   theory we should pass something like PCI device + memory region +
   offset instead. If you encounter problems please discuss on the
   linux-media mailing list:
   `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.