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 -- 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 <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. 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 <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 <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 <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