Commit | Line | Data |
---|---|---|
f6a5cb1b AK |
1 | <refentry id="vidioc-subdev-g-crop"> |
2 | <refmeta> | |
3 | <refentrytitle>ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</refentrytitle> | |
4 | &manvol; | |
5 | </refmeta> | |
6 | ||
7 | <refnamediv> | |
8 | <refname>VIDIOC_SUBDEV_G_CROP</refname> | |
9 | <refname>VIDIOC_SUBDEV_S_CROP</refname> | |
10 | <refpurpose>Get or set the crop rectangle on a subdev pad</refpurpose> | |
11 | </refnamediv> | |
12 | ||
13 | <refsynopsisdiv> | |
14 | <funcsynopsis> | |
15 | <funcprototype> | |
16 | <funcdef>int <function>ioctl</function></funcdef> | |
17 | <paramdef>int <parameter>fd</parameter></paramdef> | |
18 | <paramdef>int <parameter>request</parameter></paramdef> | |
19 | <paramdef>struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef> | |
20 | </funcprototype> | |
21 | </funcsynopsis> | |
22 | <funcsynopsis> | |
23 | <funcprototype> | |
24 | <funcdef>int <function>ioctl</function></funcdef> | |
25 | <paramdef>int <parameter>fd</parameter></paramdef> | |
26 | <paramdef>int <parameter>request</parameter></paramdef> | |
27 | <paramdef>const struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef> | |
28 | </funcprototype> | |
29 | </funcsynopsis> | |
30 | </refsynopsisdiv> | |
31 | ||
32 | <refsect1> | |
33 | <title>Arguments</title> | |
34 | ||
35 | <variablelist> | |
36 | <varlistentry> | |
37 | <term><parameter>fd</parameter></term> | |
38 | <listitem> | |
39 | <para>&fd;</para> | |
40 | </listitem> | |
41 | </varlistentry> | |
42 | <varlistentry> | |
43 | <term><parameter>request</parameter></term> | |
44 | <listitem> | |
45 | <para>VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</para> | |
46 | </listitem> | |
47 | </varlistentry> | |
48 | <varlistentry> | |
49 | <term><parameter>argp</parameter></term> | |
50 | <listitem> | |
51 | <para></para> | |
52 | </listitem> | |
53 | </varlistentry> | |
54 | </variablelist> | |
55 | </refsect1> | |
56 | ||
57 | <refsect1> | |
58 | <title>Description</title> | |
59 | ||
60 | <note> | |
61 | <title>Experimental</title> | |
62 | <para>This is an <link linkend="experimental">experimental</link> | |
63 | interface and may change in the future.</para> | |
64 | </note> | |
65 | ||
66 | <para>To retrieve the current crop rectangle applications set the | |
67 | <structfield>pad</structfield> field of a &v4l2-subdev-crop; to the | |
68 | desired pad number as reported by the media API and the | |
69 | <structfield>which</structfield> field to | |
70 | <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. They then call the | |
71 | <constant>VIDIOC_SUBDEV_G_CROP</constant> ioctl with a pointer to this | |
72 | structure. The driver fills the members of the <structfield>rect</structfield> | |
73 | field or returns &EINVAL; if the input arguments are invalid, or if cropping | |
74 | is not supported on the given pad.</para> | |
75 | ||
76 | <para>To change the current crop rectangle applications set both the | |
77 | <structfield>pad</structfield> and <structfield>which</structfield> fields | |
78 | and all members of the <structfield>rect</structfield> field. They then call | |
79 | the <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctl with a pointer to this | |
80 | structure. The driver verifies the requested crop rectangle, adjusts it | |
81 | based on the hardware capabilities and configures the device. Upon return | |
82 | the &v4l2-subdev-crop; contains the current format as would be returned | |
83 | by a <constant>VIDIOC_SUBDEV_G_CROP</constant> call.</para> | |
84 | ||
85 | <para>Applications can query the device capabilities by setting the | |
86 | <structfield>which</structfield> to | |
87 | <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' crop | |
88 | rectangles are not applied to the device by the driver, but are mangled | |
89 | exactly as active crop rectangles and stored in the sub-device file handle. | |
90 | Two applications querying the same sub-device would thus not interact with | |
91 | each other.</para> | |
92 | ||
93 | <para>Drivers must not return an error solely because the requested crop | |
94 | rectangle doesn't match the device capabilities. They must instead modify | |
95 | the rectangle to match what the hardware can provide. The modified format | |
96 | should be as close as possible to the original request.</para> | |
97 | ||
98 | <table pgwide="1" frame="none" id="v4l2-subdev-crop"> | |
99 | <title>struct <structname>v4l2_subdev_crop</structname></title> | |
100 | <tgroup cols="3"> | |
101 | &cs-str; | |
102 | <tbody valign="top"> | |
103 | <row> | |
104 | <entry>__u32</entry> | |
105 | <entry><structfield>pad</structfield></entry> | |
106 | <entry>Pad number as reported by the media framework.</entry> | |
107 | </row> | |
108 | <row> | |
109 | <entry>__u32</entry> | |
110 | <entry><structfield>which</structfield></entry> | |
111 | <entry>Crop rectangle to get or set, from | |
112 | &v4l2-subdev-format-whence;.</entry> | |
113 | </row> | |
114 | <row> | |
115 | <entry>&v4l2-rect;</entry> | |
116 | <entry><structfield>rect</structfield></entry> | |
117 | <entry>Crop rectangle boundaries, in pixels.</entry> | |
118 | </row> | |
119 | <row> | |
120 | <entry>__u32</entry> | |
121 | <entry><structfield>reserved</structfield>[8]</entry> | |
122 | <entry>Reserved for future extensions. Applications and drivers must | |
123 | set the array to zero.</entry> | |
124 | </row> | |
125 | </tbody> | |
126 | </tgroup> | |
127 | </table> | |
128 | </refsect1> | |
129 | ||
130 | <refsect1> | |
131 | &return-value; | |
132 | ||
133 | <variablelist> | |
134 | <varlistentry> | |
135 | <term><errorcode>EBUSY</errorcode></term> | |
136 | <listitem> | |
137 | <para>The crop rectangle can't be changed because the pad is currently | |
138 | busy. This can be caused, for instance, by an active video stream on | |
139 | the pad. The ioctl must not be retried without performing another | |
140 | action to fix the problem first. Only returned by | |
141 | <constant>VIDIOC_SUBDEV_S_CROP</constant></para> | |
142 | </listitem> | |
143 | </varlistentry> | |
144 | <varlistentry> | |
145 | <term><errorcode>EINVAL</errorcode></term> | |
146 | <listitem> | |
147 | <para>The &v4l2-subdev-crop; <structfield>pad</structfield> | |
148 | references a non-existing pad, the <structfield>which</structfield> | |
149 | field references a non-existing format, or cropping is not supported | |
150 | on the given subdev pad.</para> | |
151 | </listitem> | |
152 | </varlistentry> | |
153 | </variablelist> | |
154 | </refsect1> | |
155 | </refentry> |