• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2<HTML
3><HEAD
4><TITLE
5>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
6VIDIOC_TRY_FMT</TITLE
7><META
8NAME="GENERATOR"
9CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10REL="HOME"
11TITLE="Video for Linux Two API Specification"
12HREF="book1.htm"><LINK
13REL="UP"
14TITLE="Function Reference"
15HREF="r7624.htm"><LINK
16REL="PREVIOUS"
17TITLE="ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF"
18HREF="r10595.htm"><LINK
19REL="NEXT"
20TITLE="ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY"
21HREF="r11094.htm"></HEAD
22><BODY
23CLASS="REFENTRY"
24BGCOLOR="#FFFFFF"
25TEXT="#000000"
26LINK="#0000FF"
27VLINK="#840084"
28ALINK="#0000FF"
29><DIV
30CLASS="NAVHEADER"
31><TABLE
32SUMMARY="Header navigation table"
33WIDTH="100%"
34BORDER="0"
35CELLPADDING="0"
36CELLSPACING="0"
37><TR
38><TH
39COLSPAN="3"
40ALIGN="center"
41>Video for Linux Two API Specification: Revision 0.24</TH
42></TR
43><TR
44><TD
45WIDTH="10%"
46ALIGN="left"
47VALIGN="bottom"
48><A
49HREF="r10595.htm"
50ACCESSKEY="P"
51>Prev</A
52></TD
53><TD
54WIDTH="80%"
55ALIGN="center"
56VALIGN="bottom"
57></TD
58><TD
59WIDTH="10%"
60ALIGN="right"
61VALIGN="bottom"
62><A
63HREF="r11094.htm"
64ACCESSKEY="N"
65>Next</A
66></TD
67></TR
68></TABLE
69><HR
70ALIGN="LEFT"
71WIDTH="100%"></DIV
72><H1
73><A
74NAME="VIDIOC-G-FMT"
75></A
76>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
77VIDIOC_TRY_FMT</H1
78><DIV
79CLASS="REFNAMEDIV"
80><A
81NAME="AEN10948"
82></A
83><H2
84>Name</H2
85>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT&nbsp;--&nbsp;Get or set the data format, try a format</DIV
86><DIV
87CLASS="REFSYNOPSISDIV"
88><A
89NAME="AEN10953"
90></A
91><H2
92>Synopsis</H2
93><DIV
94CLASS="FUNCSYNOPSIS"
95><P
96></P
97><A
98NAME="AEN10954"
99></A
100><P
101><CODE
102><CODE
103CLASS="FUNCDEF"
104>int ioctl</CODE
105>(int fd, int request, struct v4l2_format
106*argp);</CODE
107></P
108><P
109></P
110></DIV
111></DIV
112><DIV
113CLASS="REFSECT1"
114><A
115NAME="AEN10964"
116></A
117><H2
118>Arguments</H2
119><P
120></P
121><DIV
122CLASS="VARIABLELIST"
123><DL
124><DT
125><CODE
126CLASS="PARAMETER"
127>fd</CODE
128></DT
129><DD
130><P
131>File descriptor returned by <A
132HREF="r14090.htm"
133><CODE
134CLASS="FUNCTION"
135>open()</CODE
136></A
137>.</P
138></DD
139><DT
140><CODE
141CLASS="PARAMETER"
142>request</CODE
143></DT
144><DD
145><P
146>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</P
147></DD
148><DT
149><CODE
150CLASS="PARAMETER"
151>argp</CODE
152></DT
153><DD
154><P
155></P
156></DD
157></DL
158></DIV
159></DIV
160><DIV
161CLASS="REFSECT1"
162><A
163NAME="AEN10984"
164></A
165><H2
166>Description</H2
167><P
168>These ioctls are used to negotiate the format of data
169(typically image format) exchanged between driver and
170application.</P
171><P
172>To query the current parameters applications set the
173<CODE
174CLASS="STRUCTFIELD"
175>type</CODE
176> field of a struct
177<CODE
178CLASS="STRUCTNAME"
179>v4l2_format</CODE
180> to the respective buffer (stream)
181type. For example video capture devices use
182<CODE
183CLASS="CONSTANT"
184>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
185>. When the application
186calls the <CODE
187CLASS="CONSTANT"
188>VIDIOC_G_FMT</CODE
189> ioctl with a pointer to
190this structure the driver fills the respective member of the
191<CODE
192CLASS="STRUCTFIELD"
193>fmt</CODE
194> union. In case of video capture devices
195that is the struct&nbsp;<A
196HREF="c2030.htm#V4L2-PIX-FORMAT"
197>v4l2_pix_format</A
198> <CODE
199CLASS="STRUCTFIELD"
200>pix</CODE
201> member.
202When the requested buffer type is not supported drivers return an
203<SPAN
204CLASS="ERRORCODE"
205>EINVAL</SPAN
206> error code.</P
207><P
208>To change the current format parameters applications
209initialize the <CODE
210CLASS="STRUCTFIELD"
211>type</CODE
212> field and all
213fields of the respective <CODE
214CLASS="STRUCTFIELD"
215>fmt</CODE
216>
217union member. For details see the documentation of the various devices
218types in <A
219HREF="c6488.htm"
220>Chapter 4</A
221>. Good practice is to query the
222current parameters first, and to
223modify only those parameters not suitable for the application. When
224the application calls the <CODE
225CLASS="CONSTANT"
226>VIDIOC_S_FMT</CODE
227> ioctl
228with a pointer to a <CODE
229CLASS="STRUCTNAME"
230>v4l2_format</CODE
231> structure
232the driver checks
233and adjusts the parameters against hardware abilities. Drivers
234should not return an error code unless the input is ambiguous, this is
235a mechanism to fathom device capabilities and to approach parameters
236acceptable for both the application and driver. On success the driver
237may program the hardware, allocate resources and generally prepare for
238data exchange.
239Finally the <CODE
240CLASS="CONSTANT"
241>VIDIOC_S_FMT</CODE
242> ioctl returns the
243current format parameters as <CODE
244CLASS="CONSTANT"
245>VIDIOC_G_FMT</CODE
246> does.
247Very simple, inflexible devices may even ignore all input and always
248return the default parameters. However all V4L2 devices exchanging
249data with the application must implement the
250<CODE
251CLASS="CONSTANT"
252>VIDIOC_G_FMT</CODE
253> and
254<CODE
255CLASS="CONSTANT"
256>VIDIOC_S_FMT</CODE
257> ioctl. When the requested buffer
258type is not supported drivers return an <SPAN
259CLASS="ERRORCODE"
260>EINVAL</SPAN
261> error code on a
262<CODE
263CLASS="CONSTANT"
264>VIDIOC_S_FMT</CODE
265> attempt. When I/O is already in
266progress or the resource is not available for other reasons drivers
267return the <SPAN
268CLASS="ERRORCODE"
269>EBUSY</SPAN
270> error code.</P
271><P
272>The <CODE
273CLASS="CONSTANT"
274>VIDIOC_TRY_FMT</CODE
275> ioctl is equivalent
276to <CODE
277CLASS="CONSTANT"
278>VIDIOC_S_FMT</CODE
279> with one exception: it does not
280change driver state. It can also be called at any time, never
281returning <SPAN
282CLASS="ERRORCODE"
283>EBUSY</SPAN
284>. This function is provided to
285negotiate parameters, to learn about hardware limitations, without
286disabling I/O or possibly time consuming hardware preparations.
287Although strongly recommended drivers are not required to implement
288this ioctl.</P
289><DIV
290CLASS="TABLE"
291><A
292NAME="V4L2-FORMAT"
293></A
294><P
295><B
296>Table 1. struct <CODE
297CLASS="STRUCTNAME"
298>v4l2_format</CODE
299></B
300></P
301><TABLE
302BORDER="0"
303FRAME="void"
304WIDTH="100%"
305CLASS="CALSTABLE"
306><COL
307WIDTH="25%"
308TITLE="C1"><COL
309WIDTH="25%"
310TITLE="C2"><COL
311WIDTH="25%"
312TITLE="C3"><COL
313WIDTH="25%"
314TITLE="C4"><TBODY
315VALIGN="TOP"
316><TR
317><TD
318>enum&nbsp;<A
319HREF="x5953.htm#V4L2-BUF-TYPE"
320>v4l2_buf_type</A
321></TD
322><TD
323><CODE
324CLASS="STRUCTFIELD"
325>type</CODE
326></TD
327><TD
328>&nbsp;</TD
329><TD
330>Type of the data stream, see <A
331HREF="x5953.htm#V4L2-BUF-TYPE"
332>Table 3-2</A
333>.</TD
334></TR
335><TR
336><TD
337>union</TD
338><TD
339><CODE
340CLASS="STRUCTFIELD"
341>fmt</CODE
342></TD
343><TD
344>&nbsp;</TD
345><TD
346>&nbsp;</TD
347></TR
348><TR
349><TD
350>&nbsp;</TD
351><TD
352>struct&nbsp;<A
353HREF="c2030.htm#V4L2-PIX-FORMAT"
354>v4l2_pix_format</A
355></TD
356><TD
357><CODE
358CLASS="STRUCTFIELD"
359>pix</CODE
360></TD
361><TD
362>Definition of an image format, see <A
363HREF="c2030.htm"
364>Chapter 2</A
365>, used by video capture and output
366devices.</TD
367></TR
368><TR
369><TD
370>&nbsp;</TD
371><TD
372>struct&nbsp;<A
373HREF="x6570.htm#V4L2-WINDOW"
374>v4l2_window</A
375></TD
376><TD
377><CODE
378CLASS="STRUCTFIELD"
379>win</CODE
380></TD
381><TD
382>Definition of an overlaid image, see <A
383HREF="x6570.htm"
384>Section 4.2</A
385>, used by video overlay devices.</TD
386></TR
387><TR
388><TD
389>&nbsp;</TD
390><TD
391>struct&nbsp;<A
392HREF="x7013.htm#V4L2-VBI-FORMAT"
393>v4l2_vbi_format</A
394></TD
395><TD
396><CODE
397CLASS="STRUCTFIELD"
398>vbi</CODE
399></TD
400><TD
401>Raw VBI capture or output parameters. This is
402discussed in more detail in <A
403HREF="x7013.htm"
404>Section 4.7</A
405>. Used by raw VBI
406capture and output devices.</TD
407></TR
408><TR
409><TD
410>&nbsp;</TD
411><TD
412>struct&nbsp;<A
413HREF="x7236.htm#V4L2-SLICED-VBI-FORMAT"
414>v4l2_sliced_vbi_format</A
415></TD
416><TD
417><CODE
418CLASS="STRUCTFIELD"
419>sliced</CODE
420></TD
421><TD
422>Sliced VBI capture or output parameters. See
423<A
424HREF="x7236.htm"
425>Section 4.8</A
426> for details. Used by sliced VBI
427capture and output devices.</TD
428></TR
429><TR
430><TD
431>&nbsp;</TD
432><TD
433>__u8</TD
434><TD
435><CODE
436CLASS="STRUCTFIELD"
437>raw_data</CODE
438>[200]</TD
439><TD
440>Place holder for future extensions and custom
441(driver defined) formats with <CODE
442CLASS="STRUCTFIELD"
443>type</CODE
444>
445<CODE
446CLASS="CONSTANT"
447>V4L2_BUF_TYPE_PRIVATE</CODE
448> and higher.</TD
449></TR
450></TBODY
451></TABLE
452></DIV
453></DIV
454><DIV
455CLASS="REFSECT1"
456><A
457NAME="AEN11074"
458></A
459><H2
460>Return Value</H2
461><P
462>On success <SPAN
463CLASS="RETURNVALUE"
464>0</SPAN
465> is returned, on error <SPAN
466CLASS="RETURNVALUE"
467>-1</SPAN
468> and the <CODE
469CLASS="VARNAME"
470>errno</CODE
471> variable is set appropriately:</P
472><P
473></P
474><DIV
475CLASS="VARIABLELIST"
476><DL
477><DT
478><SPAN
479CLASS="ERRORCODE"
480>EBUSY</SPAN
481></DT
482><DD
483><P
484>The data format cannot be changed at this
485time, for example because I/O is already in progress.</P
486></DD
487><DT
488><SPAN
489CLASS="ERRORCODE"
490>EINVAL</SPAN
491></DT
492><DD
493><P
494>The struct&nbsp;<A
495HREF="r10944.htm#V4L2-FORMAT"
496>v4l2_format</A
497> <CODE
498CLASS="STRUCTFIELD"
499>type</CODE
500>
501field is invalid, the requested buffer type not supported, or
502<CODE
503CLASS="CONSTANT"
504>VIDIOC_TRY_FMT</CODE
505> was called and is not
506supported with this buffer type.</P
507></DD
508></DL
509></DIV
510></DIV
511><DIV
512CLASS="NAVFOOTER"
513><HR
514ALIGN="LEFT"
515WIDTH="100%"><TABLE
516SUMMARY="Footer navigation table"
517WIDTH="100%"
518BORDER="0"
519CELLPADDING="0"
520CELLSPACING="0"
521><TR
522><TD
523WIDTH="33%"
524ALIGN="left"
525VALIGN="top"
526><A
527HREF="r10595.htm"
528ACCESSKEY="P"
529>Prev</A
530></TD
531><TD
532WIDTH="34%"
533ALIGN="center"
534VALIGN="top"
535><A
536HREF="book1.htm"
537ACCESSKEY="H"
538>Home</A
539></TD
540><TD
541WIDTH="33%"
542ALIGN="right"
543VALIGN="top"
544><A
545HREF="r11094.htm"
546ACCESSKEY="N"
547>Next</A
548></TD
549></TR
550><TR
551><TD
552WIDTH="33%"
553ALIGN="left"
554VALIGN="top"
555>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</TD
556><TD
557WIDTH="34%"
558ALIGN="center"
559VALIGN="top"
560><A
561HREF="r7624.htm"
562ACCESSKEY="U"
563>Up</A
564></TD
565><TD
566WIDTH="33%"
567ALIGN="right"
568VALIGN="top"
569>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</TD
570></TR
571></TABLE
572></DIV
573></BODY
574></HTML
575>
576