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_CROPCAP</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="V4L2 ioctl()"
     17 HREF="r7667.htm"><LINK
     18 REL="NEXT"
     19 TITLE="ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER"
     20 HREF="r7900.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="r7667.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="r7900.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-CROPCAP"
     74 ></A
     75 >ioctl VIDIOC_CROPCAP</H1
     76 ><DIV
     77 CLASS="REFNAMEDIV"
     78 ><A
     79 NAME="AEN7775"
     80 ></A
     81 ><H2
     82 >Name</H2
     83 >VIDIOC_CROPCAP&nbsp;--&nbsp;Information about the video cropping and scaling abilities</DIV
     84 ><DIV
     85 CLASS="REFSYNOPSISDIV"
     86 ><A
     87 NAME="AEN7778"
     88 ></A
     89 ><H2
     90 >Synopsis</H2
     91 ><DIV
     92 CLASS="FUNCSYNOPSIS"
     93 ><P
     94 ></P
     95 ><A
     96 NAME="AEN7779"
     97 ></A
     98 ><P
     99 ><CODE
    100 ><CODE
    101 CLASS="FUNCDEF"
    102 >int ioctl</CODE
    103 >(int fd, int request, struct v4l2_cropcap
    104 *argp);</CODE
    105 ></P
    106 ><P
    107 ></P
    108 ></DIV
    109 ></DIV
    110 ><DIV
    111 CLASS="REFSECT1"
    112 ><A
    113 NAME="AEN7789"
    114 ></A
    115 ><H2
    116 >Arguments</H2
    117 ><P
    118 ></P
    119 ><DIV
    120 CLASS="VARIABLELIST"
    121 ><DL
    122 ><DT
    123 ><CODE
    124 CLASS="PARAMETER"
    125 >fd</CODE
    126 ></DT
    127 ><DD
    128 ><P
    129 >File descriptor returned by <A
    130 HREF="r14090.htm"
    131 ><CODE
    132 CLASS="FUNCTION"
    133 >open()</CODE
    134 ></A
    135 >.</P
    136 ></DD
    137 ><DT
    138 ><CODE
    139 CLASS="PARAMETER"
    140 >request</CODE
    141 ></DT
    142 ><DD
    143 ><P
    144 >VIDIOC_CROPCAP</P
    145 ></DD
    146 ><DT
    147 ><CODE
    148 CLASS="PARAMETER"
    149 >argp</CODE
    150 ></DT
    151 ><DD
    152 ><P
    153 ></P
    154 ></DD
    155 ></DL
    156 ></DIV
    157 ></DIV
    158 ><DIV
    159 CLASS="REFSECT1"
    160 ><A
    161 NAME="AEN7809"
    162 ></A
    163 ><H2
    164 >Description</H2
    165 ><P
    166 >Applications use this function to query the cropping
    167 limits, the pixel aspect of images and to calculate scale factors.
    168 They set the <CODE
    169 CLASS="STRUCTFIELD"
    170 >type</CODE
    171 > field of a v4l2_cropcap
    172 structure to the respective buffer (stream) type and call the
    173 <CODE
    174 CLASS="CONSTANT"
    175 >VIDIOC_CROPCAP</CODE
    176 > ioctl with a pointer to this
    177 structure. Drivers fill the rest of the structure. The results are
    178 constant except when switching the video standard. Remember this
    179 switch can occur implicit when switching the video input or
    180 output.</P
    181 ><DIV
    182 CLASS="TABLE"
    183 ><A
    184 NAME="V4L2-CROPCAP"
    185 ></A
    186 ><P
    187 ><B
    188 >Table 1. struct <CODE
    189 CLASS="STRUCTNAME"
    190 >v4l2_cropcap</CODE
    191 ></B
    192 ></P
    193 ><TABLE
    194 BORDER="0"
    195 FRAME="void"
    196 WIDTH="100%"
    197 CLASS="CALSTABLE"
    198 ><COL
    199 WIDTH="25%"
    200 TITLE="C1"><COL
    201 WIDTH="25%"
    202 TITLE="C2"><COL
    203 WIDTH="50%"
    204 TITLE="C3"><TBODY
    205 VALIGN="TOP"
    206 ><TR
    207 ><TD
    208 >enum&nbsp;<A
    209 HREF="x5953.htm#V4L2-BUF-TYPE"
    210 >v4l2_buf_type</A
    211 ></TD
    212 ><TD
    213 ><CODE
    214 CLASS="STRUCTFIELD"
    215 >type</CODE
    216 ></TD
    217 ><TD
    218 >Type of the data stream, set by the application.
    219 Only these types are valid here:
    220 <CODE
    221 CLASS="CONSTANT"
    222 >V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
    223 >,
    224 <CODE
    225 CLASS="CONSTANT"
    226 >V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
    227 >,
    228 <CODE
    229 CLASS="CONSTANT"
    230 >V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
    231 >, and custom (driver
    232 defined) types with code <CODE
    233 CLASS="CONSTANT"
    234 >V4L2_BUF_TYPE_PRIVATE</CODE
    235 >
    236 and higher.</TD
    237 ></TR
    238 ><TR
    239 ><TD
    240 >struct <A
    241 HREF="r7771.htm#V4L2-RECT-CROP"
    242 >v4l2_rect</A
    243 ></TD
    244 ><TD
    245 ><CODE
    246 CLASS="STRUCTFIELD"
    247 >bounds</CODE
    248 ></TD
    249 ><TD
    250 >Defines the window within capturing or output is
    251 possible, this may exclude for example the horizontal and vertical
    252 blanking areas. The cropping rectangle cannot exceed these limits.
    253 Width and height are defined in pixels, the driver writer is free to
    254 choose origin and units of the coordinate system in the analog
    255 domain.</TD
    256 ></TR
    257 ><TR
    258 ><TD
    259 >struct <A
    260 HREF="r7771.htm#V4L2-RECT-CROP"
    261 >v4l2_rect</A
    262 ></TD
    263 ><TD
    264 ><CODE
    265 CLASS="STRUCTFIELD"
    266 >defrect</CODE
    267 ></TD
    268 ><TD
    269 >Default cropping rectangle, it shall cover the
    270 "whole picture". Assuming pixel aspect 1/1 this could be for example a
    271 640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
    272 768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
    273 the active picture area. The same co-ordinate system as for
    274             <CODE
    275 CLASS="STRUCTFIELD"
    276 >bounds</CODE
    277 > is used.</TD
    278 ></TR
    279 ><TR
    280 ><TD
    281 >struct&nbsp;<A
    282 HREF="r9288.htm#V4L2-FRACT"
    283 >v4l2_fract</A
    284 ></TD
    285 ><TD
    286 ><CODE
    287 CLASS="STRUCTFIELD"
    288 >pixelaspect</CODE
    289 ></TD
    290 ><TD
    291 ><P
    292 >This is the pixel aspect (y / x) when no
    293 scaling is applied, the ratio of the actual sampling
    294 frequency and the frequency required to get square
    295 pixels.</P
    296 ><P
    297 >When cropping coordinates refer to square pixels,
    298 the driver sets <CODE
    299 CLASS="STRUCTFIELD"
    300 >pixelaspect</CODE
    301 > to 1/1. Other
    302 common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
    303 according to [<A
    304 HREF="b17127.htm#ITU601"
    305 ><ABBR
    306 CLASS="ABBREV"
    307 >ITU&nbsp;BT.601</ABBR
    308 ></A
    309 >].</P
    310 ></TD
    311 ></TR
    312 ></TBODY
    313 ></TABLE
    314 ></DIV
    315 ><DIV
    316 CLASS="TABLE"
    317 ><A
    318 NAME="V4L2-RECT-CROP"
    319 ></A
    320 ><P
    321 ><B
    322 >Table 2. struct <CODE
    323 CLASS="STRUCTNAME"
    324 >v4l2_rect</CODE
    325 ></B
    326 ></P
    327 ><TABLE
    328 BORDER="0"
    329 FRAME="void"
    330 WIDTH="100%"
    331 CLASS="CALSTABLE"
    332 ><COL
    333 WIDTH="25%"
    334 TITLE="C1"><COL
    335 WIDTH="25%"
    336 TITLE="C2"><COL
    337 WIDTH="50%"
    338 TITLE="C3"><TBODY
    339 VALIGN="TOP"
    340 ><TR
    341 ><TD
    342 >__s32</TD
    343 ><TD
    344 ><CODE
    345 CLASS="STRUCTFIELD"
    346 >left</CODE
    347 ></TD
    348 ><TD
    349 >Horizontal offset of the top, left corner of the
    350 rectangle, in pixels.</TD
    351 ></TR
    352 ><TR
    353 ><TD
    354 >__s32</TD
    355 ><TD
    356 ><CODE
    357 CLASS="STRUCTFIELD"
    358 >top</CODE
    359 ></TD
    360 ><TD
    361 >Vertical offset of the top, left corner of the
    362 rectangle, in pixels.</TD
    363 ></TR
    364 ><TR
    365 ><TD
    366 >__s32</TD
    367 ><TD
    368 ><CODE
    369 CLASS="STRUCTFIELD"
    370 >width</CODE
    371 ></TD
    372 ><TD
    373 >Width of the rectangle, in pixels.</TD
    374 ></TR
    375 ><TR
    376 ><TD
    377 >__s32</TD
    378 ><TD
    379 ><CODE
    380 CLASS="STRUCTFIELD"
    381 >height</CODE
    382 ></TD
    383 ><TD
    384 >Height of the rectangle, in pixels. Width
    385 and height cannot be negative, the fields are signed for
    386 hysterical reasons. </TD
    387 ></TR
    388 ></TBODY
    389 ></TABLE
    390 ></DIV
    391 ></DIV
    392 ><DIV
    393 CLASS="REFSECT1"
    394 ><A
    395 NAME="AEN7885"
    396 ></A
    397 ><H2
    398 >Return Value</H2
    399 ><P
    400 >On success <SPAN
    401 CLASS="RETURNVALUE"
    402 >0</SPAN
    403 > is returned, on error <SPAN
    404 CLASS="RETURNVALUE"
    405 >-1</SPAN
    406 > and the <CODE
    407 CLASS="VARNAME"
    408 >errno</CODE
    409 > variable is set appropriately:</P
    410 ><P
    411 ></P
    412 ><DIV
    413 CLASS="VARIABLELIST"
    414 ><DL
    415 ><DT
    416 ><SPAN
    417 CLASS="ERRORCODE"
    418 >EINVAL</SPAN
    419 ></DT
    420 ><DD
    421 ><P
    422 >The struct&nbsp;<A
    423 HREF="r7771.htm#V4L2-CROPCAP"
    424 >v4l2_cropcap</A
    425 > <CODE
    426 CLASS="STRUCTFIELD"
    427 >type</CODE
    428 > is
    429 invalid or the ioctl is not supported. This is not permitted for
    430 video capture, output and overlay devices, which must support
    431 <CODE
    432 CLASS="CONSTANT"
    433 >VIDIOC_CROPCAP</CODE
    434 >.</P
    435 ></DD
    436 ></DL
    437 ></DIV
    438 ></DIV
    439 ><DIV
    440 CLASS="NAVFOOTER"
    441 ><HR
    442 ALIGN="LEFT"
    443 WIDTH="100%"><TABLE
    444 SUMMARY="Footer navigation table"
    445 WIDTH="100%"
    446 BORDER="0"
    447 CELLPADDING="0"
    448 CELLSPACING="0"
    449 ><TR
    450 ><TD
    451 WIDTH="33%"
    452 ALIGN="left"
    453 VALIGN="top"
    454 ><A
    455 HREF="r7667.htm"
    456 ACCESSKEY="P"
    457 >Prev</A
    458 ></TD
    459 ><TD
    460 WIDTH="34%"
    461 ALIGN="center"
    462 VALIGN="top"
    463 ><A
    464 HREF="book1.htm"
    465 ACCESSKEY="H"
    466 >Home</A
    467 ></TD
    468 ><TD
    469 WIDTH="33%"
    470 ALIGN="right"
    471 VALIGN="top"
    472 ><A
    473 HREF="r7900.htm"
    474 ACCESSKEY="N"
    475 >Next</A
    476 ></TD
    477 ></TR
    478 ><TR
    479 ><TD
    480 WIDTH="33%"
    481 ALIGN="left"
    482 VALIGN="top"
    483 >V4L2 ioctl()</TD
    484 ><TD
    485 WIDTH="34%"
    486 ALIGN="center"
    487 VALIGN="top"
    488 ><A
    489 HREF="r7624.htm"
    490 ACCESSKEY="U"
    491 >Up</A
    492 ></TD
    493 ><TD
    494 WIDTH="33%"
    495 ALIGN="right"
    496 VALIGN="top"
    497 >ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</TD
    498 ></TR
    499 ></TABLE
    500 ></DIV
    501 ></BODY
    502 ></HTML
    503 >
    504