Documentation/media/uapi/v4l/vidioc-cropcap.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_CROPCAP:
   4
   5 ********************
   6 ioctl VIDIOC_CROPCAP
   7 ********************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_CROPCAP
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 Applications use this function to query the cropping limits, the pixel
  37 aspect of images and to calculate scale factors. They set the ``type``
  38 field of a v4l2_cropcap structure to the respective buffer (stream)
  39 type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
  40 structure. Drivers fill the rest of the structure. The results are
  41 constant except when switching the video standard. Remember this switch
  42 can occur implicit when switching the video input or output.
  43
  44 Do not use the multiplanar buffer types. Use
  45 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
  46 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
  47 ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
  48 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
  49
  50 This ioctl must be implemented for video capture or output devices that
  51 support cropping and/or scaling and/or have non-square pixels, and for
  52 overlay devices.
  53
  54
  55 .. _v4l2-cropcap:
  56
  57 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  58
  59 .. flat-table:: struct v4l2_cropcap
  60     :header-rows:  0
  61     :stub-columns: 0
  62     :widths:       1 1 2
  63
  64
  65     -  .. row 1
  66
  67        -  __u32
  68
  69        -  ``type``
  70
  71        -  Type of the data stream, set by the application. Only these types
  72           are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
  73           ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
  74           ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
  75
  76     -  .. row 2
  77
  78        -  struct :ref:`v4l2_rect <v4l2-rect-crop>`
  79
  80        -  ``bounds``
  81
  82        -  Defines the window within capturing or output is possible, this
  83           may exclude for example the horizontal and vertical blanking
  84           areas. The cropping rectangle cannot exceed these limits. Width
  85           and height are defined in pixels, the driver writer is free to
  86           choose origin and units of the coordinate system in the analog
  87           domain.
  88
  89     -  .. row 3
  90
  91        -  struct :ref:`v4l2_rect <v4l2-rect-crop>`
  92
  93        -  ``defrect``
  94
  95        -  Default cropping rectangle, it shall cover the "whole picture".
  96           Assuming pixel aspect 1/1 this could be for example a 640 × 480
  97           rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
  98           centered over the active picture area. The same co-ordinate system
  99           as for ``bounds`` is used.
 100
 101     -  .. row 4
 102
 103        -  struct :ref:`v4l2_fract <v4l2-fract>`
 104
 105        -  ``pixelaspect``
 106
 107        -  This is the pixel aspect (y / x) when no scaling is applied, the
 108           ratio of the actual sampling frequency and the frequency required
 109           to get square pixels.
 110
 111           When cropping coordinates refer to square pixels, the driver sets
 112           ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
 113           SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
 114
 115
 116
 117 .. _v4l2-rect-crop:
 118
 119 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 120
 121 .. flat-table:: struct v4l2_rect
 122     :header-rows:  0
 123     :stub-columns: 0
 124     :widths:       1 1 2
 125
 126
 127     -  .. row 1
 128
 129        -  __s32
 130
 131        -  ``left``
 132
 133        -  Horizontal offset of the top, left corner of the rectangle, in
 134           pixels.
 135
 136     -  .. row 2
 137
 138        -  __s32
 139
 140        -  ``top``
 141
 142        -  Vertical offset of the top, left corner of the rectangle, in
 143           pixels.
 144
 145     -  .. row 3
 146
 147        -  __u32
 148
 149        -  ``width``
 150
 151        -  Width of the rectangle, in pixels.
 152
 153     -  .. row 4
 154
 155        -  __u32
 156
 157        -  ``height``
 158
 159        -  Height of the rectangle, in pixels.
 160
 161
 162 Return Value
 163 ============
 164
 165 On success 0 is returned, on error -1 and the ``errno`` variable is set
 166 appropriately. The generic error codes are described at the
 167 :ref:`Generic Error Codes <gen-errors>` chapter.
 168
 169 EINVAL
 170     The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
 171     invalid.