aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/selection-api.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l/selection-api.xml')
-rw-r--r--Documentation/DocBook/media/v4l/selection-api.xml34
1 files changed, 17 insertions, 17 deletions
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
index b299e4779354..e7ed5077834d 100644
--- a/Documentation/DocBook/media/v4l/selection-api.xml
+++ b/Documentation/DocBook/media/v4l/selection-api.xml
@@ -53,11 +53,11 @@ cropping and composing rectangles have the same size.</para>
53 </mediaobject> 53 </mediaobject>
54 </figure> 54 </figure>
55 55
56For complete list of the available selection targets see table <xref
57linkend="v4l2-sel-target"/>
58
59 </section> 56 </section>
60 57
58 See <xref linkend="v4l2-selection-targets" /> for more
59 information.
60
61 <section> 61 <section>
62 62
63 <title>Configuration</title> 63 <title>Configuration</title>
@@ -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
@@ -91,7 +91,7 @@ top/left corner at position <constant> (0,0) </constant>. The rectangle's
91coordinates are expressed in pixels.</para> 91coordinates are expressed in pixels.</para>
92 92
93<para>The top left corner, width and height of the source rectangle, that is 93<para>The top left corner, width and height of the source rectangle, that is
94the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP_ACTIVE 94the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP
95</constant> target. It uses the same coordinate system as <constant> 95</constant> target. It uses the same coordinate system as <constant>
96V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie 96V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie
97completely inside the capture boundaries. The driver may further adjust the 97completely inside the capture boundaries. The driver may further adjust the
@@ -111,13 +111,13 @@ height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>.
111</para> 111</para>
112 112
113<para>The part of a buffer into which the image is inserted by the hardware is 113<para>The part of a buffer into which the image is inserted by the hardware is
114controlled by the <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. 114controlled by the <constant> V4L2_SEL_TGT_COMPOSE </constant> target.
115The rectangle's coordinates are also expressed in the same coordinate system as 115The rectangle's coordinates are also expressed in the same coordinate system as
116the bounds rectangle. The composing rectangle must lie completely inside bounds 116the 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
@@ -125,7 +125,7 @@ bounding rectangle.</para>
125 125
126<para>The part of a buffer that is modified by the hardware is given by 126<para>The part of a buffer that is modified by the hardware is given by
127<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels 127<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels
128defined using <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> plus all 128defined using <constant> V4L2_SEL_TGT_COMPOSE </constant> plus all
129padding data modified by hardware during insertion process. All pixels outside 129padding data modified by hardware during insertion process. All pixels outside
130this rectangle <emphasis>must not</emphasis> be changed by the hardware. The 130this rectangle <emphasis>must not</emphasis> be changed by the hardware. The
131content of pixels that lie inside the padded area but outside active area is 131content of pixels that lie inside the padded area but outside active area is
@@ -153,7 +153,7 @@ specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para>
153 153
154<para>The top left corner, width and height of the source rectangle, that is 154<para>The top left corner, width and height of the source rectangle, that is
155the area from which image date are processed by the hardware, is given by the 155the area from which image date are processed by the hardware, is given by the
156<constant> V4L2_SEL_TGT_CROP_ACTIVE </constant>. Its coordinates are expressed 156<constant> V4L2_SEL_TGT_CROP </constant>. Its coordinates are expressed
157in in the same coordinate system as the bounds rectangle. The active cropping 157in in the same coordinate system as the bounds rectangle. The active cropping
158area must lie completely inside the crop boundaries and the driver may further 158area must lie completely inside the crop boundaries and the driver may further
159adjust the requested size and/or position according to hardware 159adjust the requested size and/or position according to hardware
@@ -165,7 +165,7 @@ bounding rectangle.</para>
165 165
166<para>The part of a video signal or graphics display where the image is 166<para>The part of a video signal or graphics display where the image is
167inserted by the hardware is controlled by <constant> 167inserted by the hardware is controlled by <constant>
168V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. The rectangle's coordinates 168V4L2_SEL_TGT_COMPOSE </constant> target. The rectangle's coordinates
169are expressed in pixels. The composing rectangle must lie completely inside the 169are expressed in pixels. The composing rectangle must lie completely inside the
170bounds rectangle. The driver must adjust the area to fit to the bounding 170bounds rectangle. The driver must adjust the area to fit to the bounding
171limits. Moreover, the driver can perform other adjustments according to 171limits. Moreover, the driver can perform other adjustments according to
@@ -184,7 +184,7 @@ such a padded area is driver-dependent feature not covered by this document.
184Driver developers are encouraged to keep padded rectangle equal to active one. 184Driver developers are encouraged to keep padded rectangle equal to active one.
185The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED 185The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED
186</constant> identifier. It must contain all pixels from the <constant> 186</constant> identifier. It must contain all pixels from the <constant>
187V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.</para> 187V4L2_SEL_TGT_COMPOSE </constant> target.</para>
188 188
189 </section> 189 </section>
190 190
@@ -193,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.</para>
193 <title>Scaling control</title> 193 <title>Scaling control</title>
194 194
195<para>An application can detect if scaling is performed by comparing the width 195<para>An application can detect if scaling is performed by comparing the width
196and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP_ACTIVE 196and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP
197</constant> and <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> targets. If 197</constant> and <constant> V4L2_SEL_TGT_COMPOSE </constant> targets. If
198these are not equal then the scaling is applied. The application can compute 198these are not equal then the scaling is applied. The application can compute
199the scaling ratios using these values.</para> 199the scaling ratios using these values.</para>
200 200
@@ -252,7 +252,7 @@ area)</para>
252 ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;sel); 252 ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;sel);
253 if (ret) 253 if (ret)
254 exit(-1); 254 exit(-1);
255 sel.target = V4L2_SEL_TGT_CROP_ACTIVE; 255 sel.target = V4L2_SEL_TGT_CROP;
256 ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel); 256 ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel);
257 if (ret) 257 if (ret)
258 exit(-1); 258 exit(-1);
@@ -281,7 +281,7 @@ area)</para>
281 r.left = sel.r.width / 4; 281 r.left = sel.r.width / 4;
282 r.top = sel.r.height / 4; 282 r.top = sel.r.height / 4;
283 sel.r = r; 283 sel.r = r;
284 sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE; 284 sel.target = V4L2_SEL_TGT_COMPOSE;
285 sel.flags = V4L2_SEL_FLAG_LE; 285 sel.flags = V4L2_SEL_FLAG_LE;
286 ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel); 286 ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel);
287 if (ret) 287 if (ret)
@@ -298,11 +298,11 @@ V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para>
298 298
299 &v4l2-selection; compose = { 299 &v4l2-selection; compose = {
300 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, 300 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
301 .target = V4L2_SEL_TGT_COMPOSE_ACTIVE, 301 .target = V4L2_SEL_TGT_COMPOSE,
302 }; 302 };
303 &v4l2-selection; crop = { 303 &v4l2-selection; crop = {
304 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, 304 .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
305 .target = V4L2_SEL_TGT_CROP_ACTIVE, 305 .target = V4L2_SEL_TGT_CROP,
306 }; 306 };
307 double hscale, vscale; 307 double hscale, vscale;
308 308