• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2<HTML
3><HEAD
4><TITLE
5>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</TITLE
6><META
7NAME="GENERATOR"
8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9REL="HOME"
10TITLE="Video for Linux Two API Specification"
11HREF="book1.htm"><LINK
12REL="UP"
13TITLE="Function Reference"
14HREF="r7624.htm"><LINK
15REL="PREVIOUS"
16TITLE="ioctl VIDIOC_G_CHIP_IDENT"
17HREF="r9804.htm"><LINK
18REL="NEXT"
19TITLE="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"
20HREF="r10104.htm"></HEAD
21><BODY
22CLASS="REFENTRY"
23BGCOLOR="#FFFFFF"
24TEXT="#000000"
25LINK="#0000FF"
26VLINK="#840084"
27ALINK="#0000FF"
28><DIV
29CLASS="NAVHEADER"
30><TABLE
31SUMMARY="Header navigation table"
32WIDTH="100%"
33BORDER="0"
34CELLPADDING="0"
35CELLSPACING="0"
36><TR
37><TH
38COLSPAN="3"
39ALIGN="center"
40>Video for Linux Two API Specification: Revision 0.24</TH
41></TR
42><TR
43><TD
44WIDTH="10%"
45ALIGN="left"
46VALIGN="bottom"
47><A
48HREF="r9804.htm"
49ACCESSKEY="P"
50>Prev</A
51></TD
52><TD
53WIDTH="80%"
54ALIGN="center"
55VALIGN="bottom"
56></TD
57><TD
58WIDTH="10%"
59ALIGN="right"
60VALIGN="bottom"
61><A
62HREF="r10104.htm"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><H1
72><A
73NAME="VIDIOC-G-CROP"
74></A
75>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</H1
76><DIV
77CLASS="REFNAMEDIV"
78><A
79NAME="AEN9998"
80></A
81><H2
82>Name</H2
83>VIDIOC_G_CROP, VIDIOC_S_CROP&nbsp;--&nbsp;Get or set the current cropping rectangle</DIV
84><DIV
85CLASS="REFSYNOPSISDIV"
86><A
87NAME="AEN10002"
88></A
89><H2
90>Synopsis</H2
91><DIV
92CLASS="FUNCSYNOPSIS"
93><P
94></P
95><A
96NAME="AEN10003"
97></A
98><P
99><CODE
100><CODE
101CLASS="FUNCDEF"
102>int ioctl</CODE
103>(int fd, int request, struct v4l2_crop *argp);</CODE
104></P
105><P
106></P
107></DIV
108><DIV
109CLASS="FUNCSYNOPSIS"
110><P
111></P
112><A
113NAME="AEN10013"
114></A
115><P
116><CODE
117><CODE
118CLASS="FUNCDEF"
119>int ioctl</CODE
120>(int fd, int request, const struct v4l2_crop *argp);</CODE
121></P
122><P
123></P
124></DIV
125></DIV
126><DIV
127CLASS="REFSECT1"
128><A
129NAME="AEN10023"
130></A
131><H2
132>Arguments</H2
133><P
134></P
135><DIV
136CLASS="VARIABLELIST"
137><DL
138><DT
139><CODE
140CLASS="PARAMETER"
141>fd</CODE
142></DT
143><DD
144><P
145>File descriptor returned by <A
146HREF="r14090.htm"
147><CODE
148CLASS="FUNCTION"
149>open()</CODE
150></A
151>.</P
152></DD
153><DT
154><CODE
155CLASS="PARAMETER"
156>request</CODE
157></DT
158><DD
159><P
160>VIDIOC_G_CROP, VIDIOC_S_CROP</P
161></DD
162><DT
163><CODE
164CLASS="PARAMETER"
165>argp</CODE
166></DT
167><DD
168><P
169></P
170></DD
171></DL
172></DIV
173></DIV
174><DIV
175CLASS="REFSECT1"
176><A
177NAME="AEN10043"
178></A
179><H2
180>Description</H2
181><P
182>To query the cropping rectangle size and position
183applications set the <CODE
184CLASS="STRUCTFIELD"
185>type</CODE
186> field of a
187<CODE
188CLASS="STRUCTNAME"
189>v4l2_crop</CODE
190> structure to the respective buffer
191(stream) type and call the <CODE
192CLASS="CONSTANT"
193>VIDIOC_G_CROP</CODE
194> ioctl
195with a pointer to this structure. The driver fills the rest of the
196structure or returns the <SPAN
197CLASS="ERRORCODE"
198>EINVAL</SPAN
199> error code if cropping is not supported.</P
200><P
201>To change the cropping rectangle applications initialize the
202<CODE
203CLASS="STRUCTFIELD"
204>type</CODE
205> and struct&nbsp;<A
206HREF="x6570.htm#V4L2-RECT"
207>v4l2_rect</A
208> substructure named
209<CODE
210CLASS="STRUCTFIELD"
211>c</CODE
212> of a v4l2_crop structure and call the
213<CODE
214CLASS="CONSTANT"
215>VIDIOC_S_CROP</CODE
216> ioctl with a pointer to this
217structure.</P
218><P
219>The driver first adjusts the requested dimensions against
220hardware limits, i.&nbsp;e. the bounds given by the capture/output window,
221and it rounds to the closest possible values of horizontal and
222vertical offset, width and height. In particular the driver must round
223the vertical offset of the cropping rectangle to frame lines modulo
224two, such that the field order cannot be confused.</P
225><P
226>Second the driver adjusts the image size (the opposite
227rectangle of the scaling process, source or target depending on the
228data direction) to the closest size possible while maintaining the
229current horizontal and vertical scaling factor.</P
230><P
231>Finally the driver programs the hardware with the actual
232cropping and image parameters. <CODE
233CLASS="CONSTANT"
234>VIDIOC_S_CROP</CODE
235> is a
236write-only ioctl, it does not return the actual parameters. To query
237them applications must call <CODE
238CLASS="CONSTANT"
239>VIDIOC_G_CROP</CODE
240> and
241<A
242HREF="r10944.htm"
243><CODE
244CLASS="CONSTANT"
245>VIDIOC_G_FMT</CODE
246></A
247>. When the parameters are unsuitable the application may
248modify the cropping or image parameters and repeat the cycle until
249satisfactory parameters have been negotiated.</P
250><P
251>When cropping is not supported then no parameters are
252changed and <CODE
253CLASS="CONSTANT"
254>VIDIOC_S_CROP</CODE
255> returns the
256<SPAN
257CLASS="ERRORCODE"
258>EINVAL</SPAN
259> error code.</P
260><DIV
261CLASS="TABLE"
262><A
263NAME="V4L2-CROP"
264></A
265><P
266><B
267>Table 1. struct <CODE
268CLASS="STRUCTNAME"
269>v4l2_crop</CODE
270></B
271></P
272><TABLE
273BORDER="0"
274FRAME="void"
275WIDTH="100%"
276CLASS="CALSTABLE"
277><COL
278WIDTH="25%"
279TITLE="C1"><COL
280WIDTH="25%"
281TITLE="C2"><COL
282WIDTH="50%"
283TITLE="C3"><TBODY
284VALIGN="TOP"
285><TR
286><TD
287>enum&nbsp;<A
288HREF="x5953.htm#V4L2-BUF-TYPE"
289>v4l2_buf_type</A
290></TD
291><TD
292><CODE
293CLASS="STRUCTFIELD"
294>type</CODE
295></TD
296><TD
297>Type of the data stream, set by the application.
298Only these types are valid here: <CODE
299CLASS="CONSTANT"
300>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
301>,
302<CODE
303CLASS="CONSTANT"
304>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
305>,
306<CODE
307CLASS="CONSTANT"
308>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
309>, and custom (driver
310defined) types with code <CODE
311CLASS="CONSTANT"
312>V4L2_BUF_TYPE_PRIVATE</CODE
313>
314and higher.</TD
315></TR
316><TR
317><TD
318>struct&nbsp;<A
319HREF="x6570.htm#V4L2-RECT"
320>v4l2_rect</A
321></TD
322><TD
323><CODE
324CLASS="STRUCTFIELD"
325>c</CODE
326></TD
327><TD
328>Cropping rectangle. The same co-ordinate system as
329for struct&nbsp;<A
330HREF="r7771.htm#V4L2-CROPCAP"
331>v4l2_cropcap</A
332> <CODE
333CLASS="STRUCTFIELD"
334>bounds</CODE
335> is used.</TD
336></TR
337></TBODY
338></TABLE
339></DIV
340></DIV
341><DIV
342CLASS="REFSECT1"
343><A
344NAME="AEN10092"
345></A
346><H2
347>Return Value</H2
348><P
349>On success <SPAN
350CLASS="RETURNVALUE"
351>0</SPAN
352> is returned, on error <SPAN
353CLASS="RETURNVALUE"
354>-1</SPAN
355> and the <CODE
356CLASS="VARNAME"
357>errno</CODE
358> variable is set appropriately:</P
359><P
360></P
361><DIV
362CLASS="VARIABLELIST"
363><DL
364><DT
365><SPAN
366CLASS="ERRORCODE"
367>EINVAL</SPAN
368></DT
369><DD
370><P
371>Cropping is not supported.</P
372></DD
373></DL
374></DIV
375></DIV
376><DIV
377CLASS="NAVFOOTER"
378><HR
379ALIGN="LEFT"
380WIDTH="100%"><TABLE
381SUMMARY="Footer navigation table"
382WIDTH="100%"
383BORDER="0"
384CELLPADDING="0"
385CELLSPACING="0"
386><TR
387><TD
388WIDTH="33%"
389ALIGN="left"
390VALIGN="top"
391><A
392HREF="r9804.htm"
393ACCESSKEY="P"
394>Prev</A
395></TD
396><TD
397WIDTH="34%"
398ALIGN="center"
399VALIGN="top"
400><A
401HREF="book1.htm"
402ACCESSKEY="H"
403>Home</A
404></TD
405><TD
406WIDTH="33%"
407ALIGN="right"
408VALIGN="top"
409><A
410HREF="r10104.htm"
411ACCESSKEY="N"
412>Next</A
413></TD
414></TR
415><TR
416><TD
417WIDTH="33%"
418ALIGN="left"
419VALIGN="top"
420>ioctl VIDIOC_G_CHIP_IDENT</TD
421><TD
422WIDTH="34%"
423ALIGN="center"
424VALIGN="top"
425><A
426HREF="r7624.htm"
427ACCESSKEY="U"
428>Up</A
429></TD
430><TD
431WIDTH="33%"
432ALIGN="right"
433VALIGN="top"
434>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</TD
435></TR
436></TABLE
437></DIV
438></BODY
439></HTML
440>
441