About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-g-fbuf.xml




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:02 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.