aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorSakari Ailus <sakari.ailus@iki.fi>2012-06-13 15:01:10 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2012-07-06 19:20:18 -0400
commit9fe75aac380bb0399756a14d14f29346a020a647 (patch)
tree425b2448e0b04fb63784c541d980edf24287b35c /Documentation/DocBook
parent563df3d0bc2ca103e5ddb76c8b7b3386ed2da0d6 (diff)
[media] v4l: Unify selection flags documentation
As for the selection targets, the selection flags are now the same on V4L2 and V4L2 subdev interfaces. Also document them so. Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi> Acked-by: Sylwester Nawrocki <s.nawrocki@samsung.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/media/v4l/dev-subdev.xml6
-rw-r--r--Documentation/DocBook/media/v4l/selection-api.xml6
-rw-r--r--Documentation/DocBook/media/v4l/selections-common.xml226
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-selection.xml27
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml39
5 files changed, 159 insertions, 145 deletions
diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml
index afeb196adce5..a3d9dd093268 100644
--- a/Documentation/DocBook/media/v4l/dev-subdev.xml
+++ b/Documentation/DocBook/media/v4l/dev-subdev.xml
@@ -323,10 +323,10 @@
323 <para>The drivers should always use the closest possible 323 <para>The drivers should always use the closest possible
324 rectangle the user requests on all selection targets, unless 324 rectangle the user requests on all selection targets, unless
325 specifically told otherwise. 325 specifically told otherwise.
326 <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant> and 326 <constant>V4L2_SEL_FLAG_GE</constant> and
327 <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant> flags may be 327 <constant>V4L2_SEL_FLAG_LE</constant> flags may be
328 used to round the image size either up or down. <xref 328 used to round the image size either up or down. <xref
329 linkend="v4l2-subdev-selection-flags"></xref></para> 329 linkend="v4l2-selection-flags" /></para>
330 </section> 330 </section>
331 331
332 <section> 332 <section>
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
index 24dec10259d2..e7ed5077834d 100644
--- a/Documentation/DocBook/media/v4l/selection-api.xml
+++ b/Documentation/DocBook/media/v4l/selection-api.xml
@@ -55,7 +55,7 @@ cropping and composing rectangles have the same size.</para>
55 55
56 </section> 56 </section>
57 57
58 See <xref linkend="v4l2-selection-targets-table" /> for more 58 See <xref linkend="v4l2-selection-targets" /> for more
59 information. 59 information.
60 60
61 <section> 61 <section>
@@ -74,7 +74,7 @@ cropping/composing rectangles may have to be aligned, and both the source and
74the sink may have arbitrary upper and lower size limits. Therefore, as usual, 74the sink may have arbitrary upper and lower size limits. Therefore, as usual,
75drivers are expected to adjust the requested parameters and return the actual 75drivers are expected to adjust the requested parameters and return the actual
76values selected. An application can control the rounding behaviour using <link 76values selected. An application can control the rounding behaviour using <link
77linkend="v4l2-sel-flags"> constraint flags </link>.</para> 77linkend="v4l2-selection-flags"> constraint flags </link>.</para>
78 78
79 <section> 79 <section>
80 80
@@ -117,7 +117,7 @@ the bounds rectangle. The composing rectangle must lie completely inside bounds
117rectangle. The driver must adjust the composing rectangle to fit to the 117rectangle. The driver must adjust the composing rectangle to fit to the
118bounding limits. Moreover, the driver can perform other adjustments according 118bounding limits. Moreover, the driver can perform other adjustments according
119to hardware limitations. The application can control rounding behaviour using 119to hardware limitations. The application can control rounding behaviour using
120<link linkend="v4l2-sel-flags"> constraint flags </link>.</para> 120<link linkend="v4l2-selection-flags"> constraint flags </link>.</para>
121 121
122<para>For capture devices the default composing rectangle is queried using 122<para>For capture devices the default composing rectangle is queried using
123<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the 123<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the
diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml
index 6728688d28df..b6618709ee7a 100644
--- a/Documentation/DocBook/media/v4l/selections-common.xml
+++ b/Documentation/DocBook/media/v4l/selections-common.xml
@@ -1,6 +1,6 @@
1<section id="v4l2-selections-common"> 1<section id="v4l2-selections-common">
2 2
3 <title>Selection targets</title> 3 <title>Common selection definitions</title>
4 4
5 <para>While the <link linkend="selection-api">V4L2 selection 5 <para>While the <link linkend="selection-api">V4L2 selection
6 API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev 6 API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev
@@ -10,83 +10,155 @@
10 sub-device's pad. On the V4L2 interface the selection rectangles 10 sub-device's pad. On the V4L2 interface the selection rectangles
11 refer to the in-memory pixel format.</para> 11 refer to the in-memory pixel format.</para>
12 12
13 <para>The precise meaning of the selection targets may thus be 13 <para>This section defines the common definitions of the
14 affected on which of the two interfaces they are used.</para> 14 selection interfaces on the two APIs.</para>
15 15
16 <table pgwide="1" frame="none" id="v4l2-selection-targets-table"> 16 <section id="v4l2-selection-targets">
17 <title>Selection target definitions</title> 17
18 <tgroup cols="5"> 18 <title>Selection targets</title>
19 <colspec colname="c1" /> 19
20 <colspec colname="c2" /> 20 <para>The precise meaning of the selection targets may be
21 <colspec colname="c3" /> 21 dependent on which of the two interfaces they are used.</para>
22 <colspec colname="c4" /> 22
23 <colspec colname="c5" /> 23 <table pgwide="1" frame="none" id="v4l2-selection-targets-table">
24 &cs-def; 24 <title>Selection target definitions</title>
25 <thead> 25 <tgroup cols="5">
26 <row rowsep="1"> 26 <colspec colname="c1" />
27 <entry align="left">Target name</entry> 27 <colspec colname="c2" />
28 <entry align="left">id</entry> 28 <colspec colname="c3" />
29 <entry align="left">Definition</entry> 29 <colspec colname="c4" />
30 <entry align="left">Valid for V4L2</entry> 30 <colspec colname="c5" />
31 <entry align="left">Valid for V4L2 subdev</entry> 31 &cs-def;
32 </row> 32 <thead>
33 </thead> 33 <row rowsep="1">
34 <tbody valign="top"> 34 <entry align="left">Target name</entry>
35 <row> 35 <entry align="left">id</entry>
36 <entry><constant>V4L2_SEL_TGT_CROP</constant></entry> 36 <entry align="left">Definition</entry>
37 <entry>0x0000</entry> 37 <entry align="left">Valid for V4L2</entry>
38 <entry>Crop rectangle. Defines the cropped area.</entry> 38 <entry align="left">Valid for V4L2 subdev</entry>
39 <entry>Yes</entry> 39 </row>
40 <entry>Yes</entry> 40 </thead>
41 </row> 41 <tbody valign="top">
42 <row> 42 <row>
43 <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry> 43 <entry><constant>V4L2_SEL_TGT_CROP</constant></entry>
44 <entry>0x0001</entry> 44 <entry>0x0000</entry>
45 <entry>Suggested cropping rectangle that covers the "whole picture".</entry> 45 <entry>Crop rectangle. Defines the cropped area.</entry>
46 <entry>Yes</entry> 46 <entry>Yes</entry>
47 <entry>No</entry> 47 <entry>Yes</entry>
48 </row> 48 </row>
49 <row> 49 <row>
50 <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry> 50 <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry>
51 <entry>0x0002</entry> 51 <entry>0x0001</entry>
52 <entry>Bounds of the crop rectangle. All valid crop 52 <entry>Suggested cropping rectangle that covers the "whole picture".</entry>
53 rectangles fit inside the crop bounds rectangle. 53 <entry>Yes</entry>
54 </entry> 54 <entry>No</entry>
55 <entry>Yes</entry> 55 </row>
56 <entry>Yes</entry> 56 <row>
57 </row> 57 <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry>
58 <row> 58 <entry>0x0002</entry>
59 <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> 59 <entry>Bounds of the crop rectangle. All valid crop
60 <entry>0x0100</entry> 60 rectangles fit inside the crop bounds rectangle.
61 <entry>Compose rectangle. Used to configure scaling 61 </entry>
62 and composition.</entry> 62 <entry>Yes</entry>
63 <entry>Yes</entry> 63 <entry>Yes</entry>
64 <entry>Yes</entry> 64 </row>
65 </row> 65 <row>
66 <row> 66 <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry>
67 <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry> 67 <entry>0x0100</entry>
68 <entry>0x0101</entry> 68 <entry>Compose rectangle. Used to configure scaling
69 <entry>Suggested composition rectangle that covers the "whole picture".</entry> 69 and composition.</entry>
70 <entry>Yes</entry> 70 <entry>Yes</entry>
71 <entry>No</entry> 71 <entry>Yes</entry>
72 </row> 72 </row>
73 <row> 73 <row>
74 <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry> 74 <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry>
75 <entry>0x0102</entry> 75 <entry>0x0101</entry>
76 <entry>Bounds of the compose rectangle. All valid compose 76 <entry>Suggested composition rectangle that covers the "whole picture".</entry>
77 rectangles fit inside the compose bounds rectangle.</entry> 77 <entry>Yes</entry>
78 <entry>Yes</entry> 78 <entry>No</entry>
79 <entry>Yes</entry> 79 </row>
80 </row> 80 <row>
81 <row> 81 <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
82 <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry> 82 <entry>0x0102</entry>
83 <entry>0x0103</entry> 83 <entry>Bounds of the compose rectangle. All valid compose
84 <entry>The active area and all padding pixels that are inserted or 84 rectangles fit inside the compose bounds rectangle.</entry>
85 <entry>Yes</entry>
86 <entry>Yes</entry>
87 </row>
88 <row>
89 <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry>
90 <entry>0x0103</entry>
91 <entry>The active area and all padding pixels that are inserted or
85 modified by hardware.</entry> 92 modified by hardware.</entry>
86 <entry>Yes</entry> 93 <entry>Yes</entry>
87 <entry>No</entry> 94 <entry>No</entry>
95 </row>
96 </tbody>
97 </tgroup>
98 </table>
99
100 </section>
101
102 <section id="v4l2-selection-flags">
103
104 <title>Selection flags</title>
105
106 <table pgwide="1" frame="none" id="v4l2-selection-flags-table">
107 <title>Selection flag definitions</title>
108 <tgroup cols="5">
109 <colspec colname="c1" />
110 <colspec colname="c2" />
111 <colspec colname="c3" />
112 <colspec colname="c4" />
113 <colspec colname="c5" />
114 &cs-def;
115 <thead>
116 <row rowsep="1">
117 <entry align="left">Flag name</entry>
118 <entry align="left">id</entry>
119 <entry align="left">Definition</entry>
120 <entry align="left">Valid for V4L2</entry>
121 <entry align="left">Valid for V4L2 subdev</entry>
88 </row> 122 </row>
89 </tbody> 123 </thead>
90 </tgroup> 124 <tbody valign="top">
91 </table> 125 <row>
126 <entry><constant>V4L2_SEL_FLAG_GE</constant></entry>
127 <entry>(1 &lt;&lt; 0)</entry>
128 <entry>Suggest the driver it should choose greater or
129 equal rectangle (in size) than was requested. Albeit the
130 driver may choose a lesser size, it will only do so due to
131 hardware limitations. Without this flag (and
132 <constant>V4L2_SEL_FLAG_LE</constant>) the
133 behaviour is to choose the closest possible
134 rectangle.</entry>
135 <entry>Yes</entry>
136 <entry>Yes</entry>
137 </row>
138 <row>
139 <entry><constant>V4L2_SEL_FLAG_LE</constant></entry>
140 <entry>(1 &lt;&lt; 1)</entry>
141 <entry>Suggest the driver it
142 should choose lesser or equal rectangle (in size) than was
143 requested. Albeit the driver may choose a greater size, it
144 will only do so due to hardware limitations.</entry>
145 <entry>Yes</entry>
146 <entry>Yes</entry>
147 </row>
148 <row>
149 <entry><constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant></entry>
150 <entry>(1 &lt;&lt; 2)</entry>
151 <entry>The configuration should not be propagated to any
152 further processing steps. If this flag is not given, the
153 configuration is propagated inside the subdevice to all
154 further processing steps.</entry>
155 <entry>No</entry>
156 <entry>Yes</entry>
157 </row>
158 </tbody>
159 </tgroup>
160 </table>
161
162 </section>
163
92</section> 164</section>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
index c6f83257ecee..f76d8a6d9b92 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
@@ -154,32 +154,9 @@ exist no rectangle </emphasis> that satisfies the constraints.</para>
154 154
155 </refsect1> 155 </refsect1>
156 156
157 <para>Selection targets are documented in <xref 157 <para>Selection targets and flags are documented in <xref
158 linkend="v4l2-selections-common"/>.</para> 158 linkend="v4l2-selections-common"/>.</para>
159 159
160 <refsect1>
161 <table frame="none" pgwide="1" id="v4l2-sel-flags">
162 <title>Selection constraint flags</title>
163 <tgroup cols="3">
164 &cs-def;
165 <tbody valign="top">
166 <row>
167 <entry><constant>V4L2_SEL_FLAG_GE</constant></entry>
168 <entry>0x00000001</entry>
169 <entry>Indicates that the adjusted rectangle must contain the original
170 &v4l2-selection; <structfield>r</structfield> rectangle.</entry>
171 </row>
172 <row>
173 <entry><constant>V4L2_SEL_FLAG_LE</constant></entry>
174 <entry>0x00000002</entry>
175 <entry>Indicates that the adjusted rectangle must be inside the original
176 &v4l2-rect; <structfield>r</structfield> rectangle.</entry>
177 </row>
178 </tbody>
179 </tgroup>
180 </table>
181 </refsect1>
182
183 <section> 160 <section>
184 <figure id="sel-const-adjust"> 161 <figure id="sel-const-adjust">
185 <title>Size adjustments with constraint flags.</title> 162 <title>Size adjustments with constraint flags.</title>
@@ -216,7 +193,7 @@ exist no rectangle </emphasis> that satisfies the constraints.</para>
216 <entry>__u32</entry> 193 <entry>__u32</entry>
217 <entry><structfield>flags</structfield></entry> 194 <entry><structfield>flags</structfield></entry>
218 <entry>Flags controlling the selection rectangle adjustments, refer to 195 <entry>Flags controlling the selection rectangle adjustments, refer to
219 <link linkend="v4l2-sel-flags">selection flags</link>.</entry> 196 <link linkend="v4l2-selection-flags">selection flags</link>.</entry>
220 </row> 197 </row>
221 <row> 198 <row>
222 <entry>&v4l2-rect;</entry> 199 <entry>&v4l2-rect;</entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
index ace147806e48..f33cc814a01d 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
@@ -87,44 +87,9 @@
87 <constant>EINVAL</constant>.</para> 87 <constant>EINVAL</constant>.</para>
88 </section> 88 </section>
89 89
90 <para>Selection targets are documented in <xref 90 <para>Selection targets and flags are documented in <xref
91 linkend="v4l2-selections-common"/>.</para> 91 linkend="v4l2-selections-common"/>.</para>
92 92
93 <table pgwide="1" frame="none" id="v4l2-subdev-selection-flags">
94 <title>V4L2 subdev selection flags</title>
95 <tgroup cols="3">
96 &cs-def;
97 <tbody valign="top">
98 <row>
99 <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry>
100 <entry>(1 &lt;&lt; 0)</entry> <entry>Suggest the driver it
101 should choose greater or equal rectangle (in size) than
102 was requested. Albeit the driver may choose a lesser size,
103 it will only do so due to hardware limitations. Without
104 this flag (and
105 <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant>) the
106 behaviour is to choose the closest possible
107 rectangle.</entry>
108 </row>
109 <row>
110 <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry>
111 <entry>(1 &lt;&lt; 1)</entry> <entry>Suggest the driver it
112 should choose lesser or equal rectangle (in size) than was
113 requested. Albeit the driver may choose a greater size, it
114 will only do so due to hardware limitations.</entry>
115 </row>
116 <row>
117 <entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry>
118 <entry>(1 &lt;&lt; 2)</entry>
119 <entry>The configuration should not be propagated to any
120 further processing steps. If this flag is not given, the
121 configuration is propagated inside the subdevice to all
122 further processing steps.</entry>
123 </row>
124 </tbody>
125 </tgroup>
126 </table>
127
128 <table pgwide="1" frame="none" id="v4l2-subdev-selection"> 93 <table pgwide="1" frame="none" id="v4l2-subdev-selection">
129 <title>struct <structname>v4l2_subdev_selection</structname></title> 94 <title>struct <structname>v4l2_subdev_selection</structname></title>
130 <tgroup cols="3"> 95 <tgroup cols="3">
@@ -151,7 +116,7 @@
151 <entry>__u32</entry> 116 <entry>__u32</entry>
152 <entry><structfield>flags</structfield></entry> 117 <entry><structfield>flags</structfield></entry>
153 <entry>Flags. See 118 <entry>Flags. See
154 <xref linkend="v4l2-subdev-selection-flags">.</xref></entry> 119 <xref linkend="v4l2-selection-flags" />.</entry>
155 </row> 120 </row>
156 <row> 121 <row>
157 <entry>&v4l2-rect;</entry> 122 <entry>&v4l2-rect;</entry>
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-02 02:24:18 -0400