About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:12 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>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	
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	
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.
79	Only 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
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&nbsp;&times;&nbsp;480 rectangle for NTSC, a
100	768&nbsp;&times;&nbsp;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>
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
161	invalid.</para>
162		</listitem>
163	      </varlistentry>
164	    </variablelist>
165	  </refsect1>
166	</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.