About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-cropcap.xml




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:04 EST.

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	
62	    <para>This ioctl must be implemented for video capture or output devices that
63	support cropping and/or scaling and/or have non-square pixels, and for overlay devices.</para>
64	
65	    <table pgwide="1" frame="none" id="v4l2-cropcap">
66	      <title>struct <structname>v4l2_cropcap</structname></title>
67	      <tgroup cols="3">
68		&cs-str;
69		<tbody valign="top">
70		  <row>
71		    <entry>__u32</entry>
72		    <entry><structfield>type</structfield></entry>
73		    <entry>Type of the data stream, set by the application.
74	Only these types are valid here:
75	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
76	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
77	<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
78	<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and
79	<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry>
80		  </row>
81		  <row>
82		    <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
83		    <entry><structfield>bounds</structfield></entry>
84		    <entry>Defines the window within capturing or output is
85	possible, this may exclude for example the horizontal and vertical
86	blanking areas. The cropping rectangle cannot exceed these limits.
87	Width and height are defined in pixels, the driver writer is free to
88	choose origin and units of the coordinate system in the analog
89	domain.</entry>
90		  </row>
91		  <row>
92		    <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
93		    <entry><structfield>defrect</structfield></entry>
94		    <entry>Default cropping rectangle, it shall cover the
95	"whole picture". Assuming pixel aspect 1/1 this could be for example a
96	640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
97	768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
98	the active picture area. The same co-ordinate system as for
99		    <structfield>bounds</structfield> is used.</entry>
100		  </row>
101		  <row>
102		    <entry>&v4l2-fract;</entry>
103		    <entry><structfield>pixelaspect</structfield></entry>
104		    <entry><para>This is the pixel aspect (y / x) when no
105	scaling is applied, the ratio of the actual sampling
106	frequency and the frequency required to get square
107	pixels.</para><para>When cropping coordinates refer to square pixels,
108	the driver sets <structfield>pixelaspect</structfield> to 1/1. Other
109	common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
110	according to [<xref linkend="itu601" />].</para></entry>
111		  </row>
112		</tbody>
113	      </tgroup>
114	    </table>
115	
116	    <!-- NB this table is duplicated in the overlay chapter. -->
117	
118	    <table pgwide="1" frame="none" id="v4l2-rect-crop">
119	      <title>struct <structname>v4l2_rect</structname></title>
120	      <tgroup cols="3">
121		&cs-str;
122		<tbody valign="top">
123		  <row>
124		    <entry>__s32</entry>
125		    <entry><structfield>left</structfield></entry>
126		    <entry>Horizontal offset of the top, left corner of the
127	rectangle, in pixels.</entry>
128		  </row>
129		  <row>
130		    <entry>__s32</entry>
131		    <entry><structfield>top</structfield></entry>
132		    <entry>Vertical offset of the top, left corner of the
133	rectangle, in pixels.</entry>
134		  </row>
135		  <row>
136		    <entry>__s32</entry>
137		    <entry><structfield>width</structfield></entry>
138		    <entry>Width of the rectangle, in pixels.</entry>
139		  </row>
140		  <row>
141		    <entry>__s32</entry>
142		    <entry><structfield>height</structfield></entry>
143		    <entry>Height of the rectangle, in pixels. Width
144	and height cannot be negative, the fields are signed for
145	hysterical reasons. <!-- video4linux-list@redhat.com
146	on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" -->
147	</entry>
148		  </row>
149		</tbody>
150	      </tgroup>
151	    </table>
152	  </refsect1>
153	
154	  <refsect1>
155	    &return-value;
156	
157	    <variablelist>
158	      <varlistentry>
159		<term><errorcode>EINVAL</errorcode></term>
160		<listitem>
161		  <para>The &v4l2-cropcap; <structfield>type</structfield> is
162	invalid.</para>
163		</listitem>
164	      </varlistentry>
165	    </variablelist>
166	  </refsect1>
167	</refentry>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.