]>
Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <refentry id="vidioc-cropcap"> |
2 | <refmeta> | |
3 | <refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle> | |
4 | &manvol; | |
5 | </refmeta> | |
6 | ||
7 | <refnamediv> | |
8 | <refname>VIDIOC_CROPCAP</refname> | |
9 | <refpurpose>Information about the video cropping and scaling abilities</refpurpose> | |
10 | </refnamediv> | |
11 | ||
12 | <refsynopsisdiv> | |
13 | <funcsynopsis> | |
14 | <funcprototype> | |
15 | <funcdef>int <function>ioctl</function></funcdef> | |
16 | <paramdef>int <parameter>fd</parameter></paramdef> | |
17 | <paramdef>int <parameter>request</parameter></paramdef> | |
18 | <paramdef>struct v4l2_cropcap | |
19 | *<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_CROPCAP</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 | <para>Applications use this function to query the cropping | |
53 | limits, the pixel aspect of images and to calculate scale factors. | |
54 | They set the <structfield>type</structfield> field of a v4l2_cropcap | |
55 | structure to the respective buffer (stream) type and call the | |
56 | <constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this | |
57 | structure. Drivers fill the rest of the structure. The results are | |
58 | constant except when switching the video standard. Remember this | |
59 | switch can occur implicit when switching the video input or | |
60 | output.</para> | |
61 | ||
3c828ff8 HV |
62 | <para>Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> |
63 | instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> | |
64 | and use <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of | |
65 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>.</para> | |
66 | ||
06fce286 HV |
67 | <para>This ioctl must be implemented for video capture or output devices that |
68 | support cropping and/or scaling and/or have non-square pixels, and for overlay devices.</para> | |
69 | ||
8e080c2e MCC |
70 | <table pgwide="1" frame="none" id="v4l2-cropcap"> |
71 | <title>struct <structname>v4l2_cropcap</structname></title> | |
72 | <tgroup cols="3"> | |
73 | &cs-str; | |
74 | <tbody valign="top"> | |
75 | <row> | |
6016af82 | 76 | <entry>__u32</entry> |
8e080c2e MCC |
77 | <entry><structfield>type</structfield></entry> |
78 | <entry>Type of the data stream, set by the application. | |
79 | Only these types are valid here: | |
80 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | |
3c828ff8 | 81 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and |
9495356f | 82 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> |
8e080c2e MCC |
83 | </row> |
84 | <row> | |
85 | <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> | |
86 | <entry><structfield>bounds</structfield></entry> | |
87 | <entry>Defines the window within capturing or output is | |
88 | possible, this may exclude for example the horizontal and vertical | |
89 | blanking areas. The cropping rectangle cannot exceed these limits. | |
90 | Width and height are defined in pixels, the driver writer is free to | |
91 | choose origin and units of the coordinate system in the analog | |
92 | domain.</entry> | |
93 | </row> | |
94 | <row> | |
95 | <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> | |
96 | <entry><structfield>defrect</structfield></entry> | |
97 | <entry>Default cropping rectangle, it shall cover the | |
98 | "whole picture". Assuming pixel aspect 1/1 this could be for example a | |
99 | 640 × 480 rectangle for NTSC, a | |
100 | 768 × 576 rectangle for PAL and SECAM centered over | |
101 | the active picture area. The same co-ordinate system as for | |
102 | <structfield>bounds</structfield> is used.</entry> | |
103 | </row> | |
104 | <row> | |
105 | <entry>&v4l2-fract;</entry> | |
106 | <entry><structfield>pixelaspect</structfield></entry> | |
107 | <entry><para>This is the pixel aspect (y / x) when no | |
108 | scaling is applied, the ratio of the actual sampling | |
109 | frequency and the frequency required to get square | |
110 | pixels.</para><para>When cropping coordinates refer to square pixels, | |
111 | the driver sets <structfield>pixelaspect</structfield> to 1/1. Other | |
112 | common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled | |
113 | according to [<xref linkend="itu601" />].</para></entry> | |
114 | </row> | |
115 | </tbody> | |
116 | </tgroup> | |
117 | </table> | |
118 | ||
119 | <!-- NB this table is duplicated in the overlay chapter. --> | |
120 | ||
121 | <table pgwide="1" frame="none" id="v4l2-rect-crop"> | |
122 | <title>struct <structname>v4l2_rect</structname></title> | |
123 | <tgroup cols="3"> | |
124 | &cs-str; | |
125 | <tbody valign="top"> | |
126 | <row> | |
127 | <entry>__s32</entry> | |
128 | <entry><structfield>left</structfield></entry> | |
129 | <entry>Horizontal offset of the top, left corner of the | |
130 | rectangle, in pixels.</entry> | |
131 | </row> | |
132 | <row> | |
133 | <entry>__s32</entry> | |
134 | <entry><structfield>top</structfield></entry> | |
135 | <entry>Vertical offset of the top, left corner of the | |
136 | rectangle, in pixels.</entry> | |
137 | </row> | |
138 | <row> | |
f90580ca | 139 | <entry>__u32</entry> |
8e080c2e MCC |
140 | <entry><structfield>width</structfield></entry> |
141 | <entry>Width of the rectangle, in pixels.</entry> | |
142 | </row> | |
143 | <row> | |
f90580ca | 144 | <entry>__u32</entry> |
8e080c2e | 145 | <entry><structfield>height</structfield></entry> |
f90580ca | 146 | <entry>Height of the rectangle, in pixels.</entry> |
8e080c2e MCC |
147 | </row> |
148 | </tbody> | |
149 | </tgroup> | |
150 | </table> | |
151 | </refsect1> | |
152 | ||
153 | <refsect1> | |
154 | &return-value; | |
155 | ||
156 | <variablelist> | |
157 | <varlistentry> | |
158 | <term><errorcode>EINVAL</errorcode></term> | |
159 | <listitem> | |
160 | <para>The &v4l2-cropcap; <structfield>type</structfield> is | |
06fce286 | 161 | invalid.</para> |
8e080c2e MCC |
162 | </listitem> |
163 | </varlistentry> | |
164 | </variablelist> | |
165 | </refsect1> | |
166 | </refentry> |