Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <refentry id="vidioc-g-fmt"> |
2 | <refmeta> | |
3 | <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, | |
4 | VIDIOC_TRY_FMT</refentrytitle> | |
5 | &manvol; | |
6 | </refmeta> | |
7 | ||
8 | <refnamediv> | |
9 | <refname>VIDIOC_G_FMT</refname> | |
10 | <refname>VIDIOC_S_FMT</refname> | |
11 | <refname>VIDIOC_TRY_FMT</refname> | |
12 | <refpurpose>Get or set the data format, try a format</refpurpose> | |
13 | </refnamediv> | |
14 | ||
15 | <refsynopsisdiv> | |
16 | <funcsynopsis> | |
17 | <funcprototype> | |
18 | <funcdef>int <function>ioctl</function></funcdef> | |
19 | <paramdef>int <parameter>fd</parameter></paramdef> | |
20 | <paramdef>int <parameter>request</parameter></paramdef> | |
21 | <paramdef>struct v4l2_format | |
22 | *<parameter>argp</parameter></paramdef> | |
23 | </funcprototype> | |
24 | </funcsynopsis> | |
25 | </refsynopsisdiv> | |
26 | ||
27 | <refsect1> | |
28 | <title>Arguments</title> | |
29 | ||
30 | <variablelist> | |
31 | <varlistentry> | |
32 | <term><parameter>fd</parameter></term> | |
33 | <listitem> | |
34 | <para>&fd;</para> | |
35 | </listitem> | |
36 | </varlistentry> | |
37 | <varlistentry> | |
38 | <term><parameter>request</parameter></term> | |
39 | <listitem> | |
40 | <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para> | |
41 | </listitem> | |
42 | </varlistentry> | |
43 | <varlistentry> | |
44 | <term><parameter>argp</parameter></term> | |
45 | <listitem> | |
46 | <para></para> | |
47 | </listitem> | |
48 | </varlistentry> | |
49 | </variablelist> | |
50 | </refsect1> | |
51 | ||
52 | <refsect1> | |
53 | <title>Description</title> | |
54 | ||
55 | <para>These ioctls are used to negotiate the format of data | |
56 | (typically image format) exchanged between driver and | |
57 | application.</para> | |
58 | ||
59 | <para>To query the current parameters applications set the | |
60 | <structfield>type</structfield> field of a struct | |
61 | <structname>v4l2_format</structname> to the respective buffer (stream) | |
62 | type. For example video capture devices use | |
63 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application | |
64 | calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to | |
65 | this structure the driver fills the respective member of the | |
66 | <structfield>fmt</structfield> union. In case of video capture devices | |
67 | that is the &v4l2-pix-format; <structfield>pix</structfield> member. | |
68 | When the requested buffer type is not supported drivers return an | |
69 | &EINVAL;.</para> | |
70 | ||
71 | <para>To change the current format parameters applications | |
72 | initialize the <structfield>type</structfield> field and all | |
73 | fields of the respective <structfield>fmt</structfield> | |
74 | union member. For details see the documentation of the various devices | |
75 | types in <xref linkend="devices" />. Good practice is to query the | |
76 | current parameters first, and to | |
77 | modify only those parameters not suitable for the application. When | |
78 | the application calls the <constant>VIDIOC_S_FMT</constant> ioctl | |
79 | with a pointer to a <structname>v4l2_format</structname> structure | |
80 | the driver checks | |
81 | and adjusts the parameters against hardware abilities. Drivers | |
82 | should not return an error code unless the input is ambiguous, this is | |
83 | a mechanism to fathom device capabilities and to approach parameters | |
84 | acceptable for both the application and driver. On success the driver | |
85 | may program the hardware, allocate resources and generally prepare for | |
86 | data exchange. | |
87 | Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the | |
88 | current format parameters as <constant>VIDIOC_G_FMT</constant> does. | |
89 | Very simple, inflexible devices may even ignore all input and always | |
90 | return the default parameters. However all V4L2 devices exchanging | |
91 | data with the application must implement the | |
92 | <constant>VIDIOC_G_FMT</constant> and | |
93 | <constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer | |
94 | type is not supported drivers return an &EINVAL; on a | |
95 | <constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in | |
96 | progress or the resource is not available for other reasons drivers | |
97 | return the &EBUSY;.</para> | |
98 | ||
99 | <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent | |
100 | to <constant>VIDIOC_S_FMT</constant> with one exception: it does not | |
101 | change driver state. It can also be called at any time, never | |
102 | returning <errorcode>EBUSY</errorcode>. This function is provided to | |
103 | negotiate parameters, to learn about hardware limitations, without | |
104 | disabling I/O or possibly time consuming hardware preparations. | |
105 | Although strongly recommended drivers are not required to implement | |
106 | this ioctl.</para> | |
107 | ||
108 | <table pgwide="1" frame="none" id="v4l2-format"> | |
109 | <title>struct <structname>v4l2_format</structname></title> | |
110 | <tgroup cols="4"> | |
111 | <colspec colname="c1" /> | |
112 | <colspec colname="c2" /> | |
113 | <colspec colname="c3" /> | |
114 | <colspec colname="c4" /> | |
115 | <tbody valign="top"> | |
116 | <row> | |
117 | <entry>&v4l2-buf-type;</entry> | |
118 | <entry><structfield>type</structfield></entry> | |
119 | <entry></entry> | |
120 | <entry>Type of the data stream, see <xref | |
121 | linkend="v4l2-buf-type" />.</entry> | |
122 | </row> | |
123 | <row> | |
124 | <entry>union</entry> | |
125 | <entry><structfield>fmt</structfield></entry> | |
126 | </row> | |
127 | <row> | |
128 | <entry></entry> | |
129 | <entry>&v4l2-pix-format;</entry> | |
130 | <entry><structfield>pix</structfield></entry> | |
131 | <entry>Definition of an image format, see <xref | |
132 | linkend="pixfmt" />, used by video capture and output | |
133 | devices.</entry> | |
134 | </row> | |
135 | <row> | |
136 | <entry></entry> | |
137 | <entry>&v4l2-window;</entry> | |
138 | <entry><structfield>win</structfield></entry> | |
139 | <entry>Definition of an overlaid image, see <xref | |
140 | linkend="overlay" />, used by video overlay devices.</entry> | |
141 | </row> | |
142 | <row> | |
143 | <entry></entry> | |
144 | <entry>&v4l2-vbi-format;</entry> | |
145 | <entry><structfield>vbi</structfield></entry> | |
146 | <entry>Raw VBI capture or output parameters. This is | |
147 | discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI | |
148 | capture and output devices.</entry> | |
149 | </row> | |
150 | <row> | |
151 | <entry></entry> | |
152 | <entry>&v4l2-sliced-vbi-format;</entry> | |
153 | <entry><structfield>sliced</structfield></entry> | |
154 | <entry>Sliced VBI capture or output parameters. See | |
155 | <xref linkend="sliced" /> for details. Used by sliced VBI | |
156 | capture and output devices.</entry> | |
157 | </row> | |
158 | <row> | |
159 | <entry></entry> | |
160 | <entry>__u8</entry> | |
161 | <entry><structfield>raw_data</structfield>[200]</entry> | |
162 | <entry>Place holder for future extensions and custom | |
163 | (driver defined) formats with <structfield>type</structfield> | |
164 | <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> | |
165 | </row> | |
166 | </tbody> | |
167 | </tgroup> | |
168 | </table> | |
169 | </refsect1> | |
170 | ||
171 | <refsect1> | |
172 | &return-value; | |
173 | ||
174 | <variablelist> | |
175 | <varlistentry> | |
176 | <term><errorcode>EBUSY</errorcode></term> | |
177 | <listitem> | |
178 | <para>The data format cannot be changed at this | |
179 | time, for example because I/O is already in progress.</para> | |
180 | </listitem> | |
181 | </varlistentry> | |
182 | <varlistentry> | |
183 | <term><errorcode>EINVAL</errorcode></term> | |
184 | <listitem> | |
185 | <para>The &v4l2-format; <structfield>type</structfield> | |
186 | field is invalid, the requested buffer type not supported, or | |
187 | <constant>VIDIOC_TRY_FMT</constant> was called and is not | |
188 | supported with this buffer type.</para> | |
189 | </listitem> | |
190 | </varlistentry> | |
191 | </variablelist> | |
192 | </refsect1> | |
193 | </refentry> | |
194 | ||
195 | <!-- | |
196 | Local Variables: | |
197 | mode: sgml | |
198 | sgml-parent-document: "v4l2.sgml" | |
199 | indent-tabs-mode: nil | |
200 | End: | |
201 | --> |