aboutsummaryrefslogtreecommitdiff
path: root/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
blob: 93817f33703305beae49acafa52b1bceb0613dd2 (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
<refentry id="vidioc-g-fbuf">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_G_FBUF</refname>
    <refname>VIDIOC_S_FBUF</refname>
    <refpurpose>Get or set frame buffer overlay parameters</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Arguments</title>

    <variablelist>
      <varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	  <para>&fd;</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	  <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and
<constant>VIDIOC_S_FBUF</constant> ioctl to get and set the
framebuffer parameters for a <link linkend="overlay">Video
Overlay</link> or <link linkend="osd">Video Output Overlay</link>
(OSD). The type of overlay is implied by the device type (capture or
output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl.
One <filename>/dev/videoN</filename> device must not support both
kinds of overlay.</para>

    <para>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.
<wordasword>Video Output Overlays</wordasword> are always
non-destructive.</para>

    <para>To get the current parameters applications call the
<constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a
<structname>v4l2_framebuffer</structname> structure. The driver fills
all fields of the structure or returns an &EINVAL; when overlays are
not supported.</para>

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

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

    <para>For a <wordasword>destructive Video Overlay</wordasword>
applications must additionally provide a
<structfield>base</structfield> 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.</para>

    <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.-->

    <table pgwide="1" frame="none" id="v4l2-framebuffer">
      <title>struct <structname>v4l2_framebuffer</structname></title>
      <tgroup cols="4">
	&cs-ustr;
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>capability</structfield></entry>
	    <entry></entry>
	    <entry>Overlay capability flags set by the driver, see
<xref linkend="framebuffer-cap" />.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>flags</structfield></entry>
	    <entry></entry>
	    <entry>Overlay control flags set by application and
driver, see <xref linkend="framebuffer-flags" /></entry>
	  </row>
	  <row>
	    <entry>void *</entry>
	    <entry><structfield>base</structfield></entry>
	    <entry></entry>
	    <entry>Physical base address of the framebuffer,
that is the address of the pixel in the top left corner of the
framebuffer.<footnote><para>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: &v4l-ml;.</para></footnote></entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>This field is irrelevant to
<wordasword>non-destructive Video Overlays</wordasword>. For
<wordasword>destructive Video Overlays</wordasword> applications must
provide a base address. The driver may accept only base addresses
which are a multiple of two, four or eight bytes. For
<wordasword>Video Output Overlays</wordasword> the driver must return
a valid base address, so applications can find the corresponding Linux
framebuffer device (see <xref linkend="osd" />).</entry>
	  </row>
	  <row>
	    <entry>&v4l2-pix-format;</entry>
	    <entry><structfield>fmt</structfield></entry>
	    <entry></entry>
	    <entry>Layout of the frame buffer. The
<structname>v4l2_pix_format</structname> structure is defined in <xref
linkend="pixfmt" />, for clarification the fields and acceptable values
	    are listed below:</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>width</structfield></entry>
	    <entry>Width of the frame buffer in pixels.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>height</structfield></entry>
	    <entry>Height of the frame buffer in pixels.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>pixelformat</structfield></entry>
	    <entry>The pixel format of the
framebuffer.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>For <wordasword>non-destructive Video
Overlays</wordasword> this field only defines a format for the
&v4l2-window; <structfield>chromakey</structfield> field.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>For <wordasword>destructive Video
Overlays</wordasword> applications must initialize this field. For
<wordasword>Video Output Overlays</wordasword> the driver must return
a valid format.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Usually this is an RGB format (for example
<link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>)
but YUV formats (only packed YUV formats when chroma keying is used,
not including <constant>V4L2_PIX_FMT_YUYV</constant> and
<constant>V4L2_PIX_FMT_UYVY</constant>) and the
<constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The
behavior of the driver when an application requests a compressed
format is undefined. See <xref linkend="pixfmt" /> for information on
pixel formats.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>&v4l2-field;</entry>
	    <entry><structfield>field</structfield></entry>
	    <entry>Drivers and applications shall ignore this field.
If applicable, the field order is selected with the &VIDIOC-S-FMT;
ioctl, using the <structfield>field</structfield> field of
&v4l2-window;.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>bytesperline</structfield></entry>
	    <entry>Distance in bytes between the leftmost pixels in
two adjacent lines.</entry>
	  </row>
	  <row>
	    <entry spanname="hspan"><para>This field is irrelevant to
<wordasword>non-destructive Video
Overlays</wordasword>.</para><para>For <wordasword>destructive Video
Overlays</wordasword> 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 <structfield>width</structfield>
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.</para><para>For <wordasword>Video Output
Overlays</wordasword> the driver must return a valid
value.</para><para>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.</para><para>When the image format is planar the
<structfield>bytesperline</structfield> value applies to the largest
plane and is divided by the same factor as the
<structfield>width</structfield> field for any smaller 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 <structfield>bytesperline</structfield> value
rounded up to a multiple of the scale factor.</para></entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>sizeimage</structfield></entry>
	    <entry><para>This field is irrelevant to
<wordasword>non-destructive Video Overlays</wordasword>. For
<wordasword>destructive Video Overlays</wordasword> applications must
initialize this field. For <wordasword>Video Output
Overlays</wordasword> the driver must return a valid
format.</para><para>Together with <structfield>base</structfield> it
defines the framebuffer memory accessible by the
driver.</para></entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>&v4l2-colorspace;</entry>
	    <entry><structfield>colorspace</structfield></entry>
	    <entry>This information supplements the
<structfield>pixelformat</structfield> and must be set by the driver,
see <xref linkend="colorspaces" />.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>priv</structfield></entry>
	    <entry>Reserved for additional information about custom
(driver defined) formats. When not used drivers and applications must
set this field to zero.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="framebuffer-cap">
      <title>Frame Buffer Capability Flags</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry>
	    <entry>0x0001</entry>
	    <entry>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.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
	    <entry>0x0002</entry>
	    <entry>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.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry>
	    <entry>0x0004</entry>
	    <entry>The device supports clipping using a list of clip
rectangles.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry>
	    <entry>0x0008</entry>
	    <entry>The device supports clipping using a bit mask.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry>
	    <entry>0x0010</entry>
	    <entry>The device supports clipping/blending using the
alpha channel of the framebuffer or VGA signal. Alpha blending makes
no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry>
	    <entry>0x0020</entry>
	    <entry>The device supports alpha blending using a global
alpha value. Alpha blending makes no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry>
	    <entry>0x0040</entry>
	    <entry>The device supports clipping/blending using the
inverted alpha channel of the framebuffer or VGA signal. Alpha
blending makes no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry>
	    <entry>0x0080</entry>
	    <entry>The device supports Source Chroma-keying. Video pixels
with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of
<constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="framebuffer-flags">
      <title>Frame Buffer Flags</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
	    <entry>0x0001</entry>
	    <entry>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 <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
capability and it is cleared otherwise.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
	    <entry>0x0002</entry>
	    <entry>The frame buffer is an overlay surface the same
size as the capture. [?]</entry>
	  </row>
	  <row>
	    <entry spanname="hspan">The purpose of
<constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear.
Most drivers seem to ignore this flag. For compatibility with the
<wordasword>bttv</wordasword> driver applications should set the
<constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
	    <entry>0x0004</entry>
	    <entry>Use chroma-keying. The chroma-key color is
determined by the <structfield>chromakey</structfield> field of
&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
		linkend="overlay" />
and
	    <xref linkend="osd" />.</entry>
	  </row>
	  <row>
	    <entry spanname="hspan">There are no flags to enable
clipping using a list of clip rectangles or a bitmap. These methods
are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
		linkend="overlay" /> and <xref linkend="osd" />.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
	    <entry>0x0008</entry>
	    <entry>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.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
	    <entry>0x0010</entry>
	    <entry>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 <structfield>global_alpha</structfield> field of
&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
		linkend="overlay" />
and <xref linkend="osd" />.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
	    <entry>0x0020</entry>
	    <entry>Like
<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, 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.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry>
	    <entry>0x0040</entry>
	    <entry>Use source chroma-keying. The source chroma-key color is
determined by the <structfield>chromakey</structfield> field of
&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
linkend="overlay" /> and <xref linkend="osd" />.
Both chroma-keying are mutual exclusive to each other, so same
<structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EPERM</errorcode></term>
	<listitem>
	  <para><constant>VIDIOC_S_FBUF</constant> can only be called
by a privileged user to negotiate the parameters for a destructive
overlay.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>