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
53limits, the pixel aspect of images and to calculate scale factors.
54They set the <structfield>type</structfield> field of a v4l2_cropcap
55structure to the respective buffer (stream) type and call the
56<constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this
57structure. Drivers fill the rest of the structure. The results are
58constant except when switching the video standard. Remember this
59switch can occur implicit when switching the video input or
60output.</para>
61
62<para>Do not use the multiplanar buffer types.  Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
63instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
64and use <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
65<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>.</para>
66
67    <para>This ioctl must be implemented for video capture or output devices that
68support cropping and/or scaling and/or have non-square pixels, and for overlay devices.</para>
69
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>
76	    <entry>__u32</entry>
77	    <entry><structfield>type</structfield></entry>
78	    <entry>Type of the data stream, set by the application.
79Only these types are valid here:
80<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
81<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and
82<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry>
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
88possible, this may exclude for example the horizontal and vertical
89blanking areas. The cropping rectangle cannot exceed these limits.
90Width and height are defined in pixels, the driver writer is free to
91choose origin and units of the coordinate system in the analog
92domain.</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
99640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
100768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
101the 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
108scaling is applied, the ratio of the actual sampling
109frequency and the frequency required to get square
110pixels.</para><para>When cropping coordinates refer to square pixels,
111the driver sets <structfield>pixelaspect</structfield> to 1/1. Other
112common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
113according 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
130rectangle, 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
136rectangle, in pixels.</entry>
137	  </row>
138	  <row>
139	    <entry>__u32</entry>
140	    <entry><structfield>width</structfield></entry>
141	    <entry>Width of the rectangle, in pixels.</entry>
142	  </row>
143	  <row>
144	    <entry>__u32</entry>
145	    <entry><structfield>height</structfield></entry>
146	    <entry>Height of the rectangle, in pixels.</entry>
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
161invalid.</para>
162	</listitem>
163      </varlistentry>
164    </variablelist>
165  </refsect1>
166</refentry>
167