aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
diff options
context:
space:
mode:
authorSakari Ailus <sakari.ailus@iki.fi>2011-12-12 16:17:25 -0500
committerMauro Carvalho Chehab <mchehab@redhat.com>2012-04-10 16:11:27 -0400
commit955f645aea04f3130d39c7889e2c5bd7f6d638a3 (patch)
treea1f722a529b28c43293af376466718c78fec90fb /Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
parent59ef29cc86afb3a22b2ba96a1c276d332639fc30 (diff)
[media] v4l: Add subdev selections documentation
Add documentation for V4L2 subdev selection API. This changes also experimental V4L2 subdev API so that scaling now works through selection API only. Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml')
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml228
1 files changed, 228 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
new file mode 100644
index 000000000000..208e9f0da3f3
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
@@ -0,0 +1,228 @@
1<refentry id="vidioc-subdev-g-selection">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_G_SELECTION</refname>
9 <refname>VIDIOC_SUBDEV_S_SELECTION</refname>
10 <refpurpose>Get or set selection rectangles 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_selection *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <note>
53 <title>Experimental</title>
54 <para>This is an <link linkend="experimental">experimental</link>
55 interface and may change in the future.</para>
56 </note>
57
58 <para>The selections are used to configure various image
59 processing functionality performed by the subdevs which affect the
60 image size. This currently includes cropping, scaling and
61 composition.</para>
62
63 <para>The selection API replaces <link
64 linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All
65 the function of the crop API, and more, are supported by the
66 selections API.</para>
67
68 <para>See <xref linkend="subdev"></xref> for
69 more information on how each selection target affects the image
70 processing pipeline inside the subdevice.</para>
71
72 <section>
73 <title>Types of selection targets</title>
74
75 <para>There are two types of selection targets: actual and bounds.
76 The ACTUAL targets are the targets which configure the hardware.
77 The BOUNDS target will return a rectangle that contain all
78 possible ACTUAL rectangles.</para>
79 </section>
80
81 <section>
82 <title>Discovering supported features</title>
83
84 <para>To discover which targets are supported, the user can
85 perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them.
86 Any unsupported target will return
87 <constant>EINVAL</constant>.</para>
88 </section>
89
90 <table pgwide="1" frame="none" id="v4l2-subdev-selection-targets">
91 <title>V4L2 subdev selection targets</title>
92 <tgroup cols="3">
93 &cs-def;
94 <tbody valign="top">
95 <row>
96 <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL</constant></entry>
97 <entry>0x0000</entry>
98 <entry>Actual crop. Defines the cropping
99 performed by the processing step.</entry>
100 </row>
101 <row>
102 <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS</constant></entry>
103 <entry>0x0002</entry>
104 <entry>Bounds of the crop rectangle.</entry>
105 </row>
106 <row>
107 <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL</constant></entry>
108 <entry>0x0100</entry>
109 <entry>Actual compose rectangle. Used to configure scaling
110 on sink pads and composition on source pads.</entry>
111 </row>
112 <row>
113 <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
114 <entry>0x0102</entry>
115 <entry>Bounds of the compose rectangle.</entry>
116 </row>
117 </tbody>
118 </tgroup>
119 </table>
120
121 <table pgwide="1" frame="none" id="v4l2-subdev-selection-flags">
122 <title>V4L2 subdev selection flags</title>
123 <tgroup cols="3">
124 &cs-def;
125 <tbody valign="top">
126 <row>
127 <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry>
128 <entry>(1 &lt;&lt; 0)</entry> <entry>Suggest the driver it
129 should choose greater or equal rectangle (in size) than
130 was requested. Albeit the driver may choose a lesser size,
131 it will only do so due to hardware limitations. Without
132 this flag (and
133 <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant>) the
134 behaviour is to choose the closest possible
135 rectangle.</entry>
136 </row>
137 <row>
138 <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry>
139 <entry>(1 &lt;&lt; 1)</entry> <entry>Suggest the driver it
140 should choose lesser or equal rectangle (in size) than was
141 requested. Albeit the driver may choose a greater size, it
142 will only do so due to hardware limitations.</entry>
143 </row>
144 <row>
145 <entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry>
146 <entry>(1 &lt;&lt; 2)</entry>
147 <entry>The configuration should not be propagated to any
148 further processing steps. If this flag is not given, the
149 configuration is propagated inside the subdevice to all
150 further processing steps.</entry>
151 </row>
152 </tbody>
153 </tgroup>
154 </table>
155
156 <table pgwide="1" frame="none" id="v4l2-subdev-selection">
157 <title>struct <structname>v4l2_subdev_selection</structname></title>
158 <tgroup cols="3">
159 &cs-str;
160 <tbody valign="top">
161 <row>
162 <entry>__u32</entry>
163 <entry><structfield>which</structfield></entry>
164 <entry>Active or try selection, from
165 &v4l2-subdev-format-whence;.</entry>
166 </row>
167 <row>
168 <entry>__u32</entry>
169 <entry><structfield>pad</structfield></entry>
170 <entry>Pad number as reported by the media framework.</entry>
171 </row>
172 <row>
173 <entry>__u32</entry>
174 <entry><structfield>target</structfield></entry>
175 <entry>Target selection rectangle. See
176 <xref linkend="v4l2-subdev-selection-targets">.</xref>.</entry>
177 </row>
178 <row>
179 <entry>__u32</entry>
180 <entry><structfield>flags</structfield></entry>
181 <entry>Flags. See
182 <xref linkend="v4l2-subdev-selection-flags">.</xref></entry>
183 </row>
184 <row>
185 <entry>&v4l2-rect;</entry>
186 <entry><structfield>rect</structfield></entry>
187 <entry>Selection rectangle, in pixels.</entry>
188 </row>
189 <row>
190 <entry>__u32</entry>
191 <entry><structfield>reserved</structfield>[8]</entry>
192 <entry>Reserved for future extensions. Applications and drivers must
193 set the array to zero.</entry>
194 </row>
195 </tbody>
196 </tgroup>
197 </table>
198
199 </refsect1>
200
201 <refsect1>
202 &return-value;
203
204 <variablelist>
205 <varlistentry>
206 <term><errorcode>EBUSY</errorcode></term>
207 <listitem>
208 <para>The selection rectangle can't be changed because the
209 pad is currently busy. This can be caused, for instance, by
210 an active video stream on the pad. The ioctl must not be
211 retried without performing another action to fix the problem
212 first. Only returned by
213 <constant>VIDIOC_SUBDEV_S_SELECTION</constant></para>
214 </listitem>
215 </varlistentry>
216 <varlistentry>
217 <term><errorcode>EINVAL</errorcode></term>
218 <listitem>
219 <para>The &v4l2-subdev-selection;
220 <structfield>pad</structfield> references a non-existing
221 pad, the <structfield>which</structfield> field references a
222 non-existing format, or the selection target is not
223 supported on the given subdev pad.</para>
224 </listitem>
225 </varlistentry>
226 </variablelist>
227 </refsect1>
228</refentry>
generated by cgit v1.2.2 (git 2.25.0) at 2024-10-11 21:26:02 -0400