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