aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml')
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml180
1 files changed, 180 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml
new file mode 100644
index 000000000000..f367c570c530
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml
@@ -0,0 +1,180 @@
1<refentry id="vidioc-subdev-g-fmt">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_G_FMT</refname>
9 <refname>VIDIOC_SUBDEV_S_FMT</refname>
10 <refpurpose>Get or set the data format on a subdev pad</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_subdev_format *<parameter>argp</parameter>
20 </paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 </refsynopsisdiv>
24
25 <refsect1>
26 <title>Arguments</title>
27
28 <variablelist>
29 <varlistentry>
30 <term><parameter>fd</parameter></term>
31 <listitem>
32 <para>&fd;</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <note>
54 <title>Experimental</title>
55 <para>This is an <link linkend="experimental">experimental</link>
56 interface and may change in the future.</para>
57 </note>
58
59 <para>These ioctls are used to negotiate the frame format at specific
60 subdev pads in the image pipeline.</para>
61
62 <para>To retrieve the current format applications set the
63 <structfield>pad</structfield> field of a &v4l2-subdev-format; to the
64 desired pad number as reported by the media API and the
65 <structfield>which</structfield> field to
66 <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. When they call the
67 <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl with a pointer to this
68 structure the driver fills the members of the <structfield>format</structfield>
69 field.</para>
70
71 <para>To change the current format applications set both the
72 <structfield>pad</structfield> and <structfield>which</structfield> fields
73 and all members of the <structfield>format</structfield> field. When they
74 call the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl with a pointer to this
75 structure the driver verifies the requested format, adjusts it based on the
76 hardware capabilities and configures the device. Upon return the
77 &v4l2-subdev-format; contains the current format as would be returned by a
78 <constant>VIDIOC_SUBDEV_G_FMT</constant> call.</para>
79
80 <para>Applications can query the device capabilities by setting the
81 <structfield>which</structfield> to
82 <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' formats are not
83 applied to the device by the driver, but are changed exactly as active
84 formats and stored in the sub-device file handle. Two applications querying
85 the same sub-device would thus not interact with each other.</para>
86
87 <para>For instance, to try a format at the output pad of a sub-device,
88 applications would first set the try format at the sub-device input with the
89 <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl. They would then either
90 retrieve the default format at the output pad with the
91 <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl, or set the desired output
92 pad format with the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl and check
93 the returned value.</para>
94
95 <para>Try formats do not depend on active formats, but can depend on the
96 current links configuration or sub-device controls value. For instance, a
97 low-pass noise filter might crop pixels at the frame boundaries, modifying
98 its output frame size.</para>
99
100 <para>Drivers must not return an error solely because the requested format
101 doesn't match the device capabilities. They must instead modify the format
102 to match what the hardware can provide. The modified format should be as
103 close as possible to the original request.</para>
104
105 <table pgwide="1" frame="none" id="v4l2-subdev-format">
106 <title>struct <structname>v4l2_subdev_format</structname></title>
107 <tgroup cols="3">
108 &cs-str;
109 <tbody valign="top">
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>pad</structfield></entry>
113 <entry>Pad number as reported by the media controller API.</entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>which</structfield></entry>
118 <entry>Format to modified, from &v4l2-subdev-format-whence;.</entry>
119 </row>
120 <row>
121 <entry>&v4l2-mbus-framefmt;</entry>
122 <entry><structfield>format</structfield></entry>
123 <entry>Definition of an image format, see <xref
124 linkend="v4l2-mbus-framefmt" /> for details.</entry>
125 </row>
126 <row>
127 <entry>__u32</entry>
128 <entry><structfield>reserved</structfield>[8]</entry>
129 <entry>Reserved for future extensions. Applications and drivers must
130 set the array to zero.</entry>
131 </row>
132 </tbody>
133 </tgroup>
134 </table>
135
136 <table pgwide="1" frame="none" id="v4l2-subdev-format-whence">
137 <title>enum <structname>v4l2_subdev_format_whence</structname></title>
138 <tgroup cols="3">
139 &cs-def;
140 <tbody valign="top">
141 <row>
142 <entry>V4L2_SUBDEV_FORMAT_TRY</entry>
143 <entry>0</entry>
144 <entry>Try formats, used for querying device capabilities.</entry>
145 </row>
146 <row>
147 <entry>V4L2_SUBDEV_FORMAT_ACTIVE</entry>
148 <entry>1</entry>
149 <entry>Active formats, applied to the hardware.</entry>
150 </row>
151 </tbody>
152 </tgroup>
153 </table>
154 </refsect1>
155
156 <refsect1>
157 &return-value;
158
159 <variablelist>
160 <varlistentry>
161 <term><errorcode>EBUSY</errorcode></term>
162 <listitem>
163 <para>The format can't be changed because the pad is currently busy.
164 This can be caused, for instance, by an active video stream on the
165 pad. The ioctl must not be retried without performing another action
166 to fix the problem first. Only returned by
167 <constant>VIDIOC_SUBDEV_S_FMT</constant></para>
168 </listitem>
169 </varlistentry>
170 <varlistentry>
171 <term><errorcode>EINVAL</errorcode></term>
172 <listitem>
173 <para>The &v4l2-subdev-format; <structfield>pad</structfield>
174 references a non-existing pad, or the <structfield>which</structfield>
175 field references a non-existing format.</para>
176 </listitem>
177 </varlistentry>
178 </variablelist>
179 </refsect1>
180</refentry>
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-24 22:50:49 -0500