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