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 .. 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 :ref:`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 :ref:`v4l2_fract <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 .. flat-table:: struct v4l2_rect
 118     :header-rows:  0
 119     :stub-columns: 0
 120     :widths:       1 1 2
 121
 122
 123     -  .. row 1
 124
 125        -  __s32
 126
 127        -  ``left``
 128
 129        -  Horizontal offset of the top, left corner of the rectangle, in
 130           pixels.
 131
 132     -  .. row 2
 133
 134        -  __s32
 135
 136        -  ``top``
 137
 138        -  Vertical offset of the top, left corner of the rectangle, in
 139           pixels.
 140
 141     -  .. row 3
 142
 143        -  __u32
 144
 145        -  ``width``
 146
 147        -  Width of the rectangle, in pixels.
 148
 149     -  .. row 4
 150
 151        -  __u32
 152
 153        -  ``height``
 154
 155        -  Height of the rectangle, in pixels.
 156
 157
 158 Return Value
 159 ============
 160
 161 On success 0 is returned, on error -1 and the ``errno`` variable is set
 162 appropriately. The generic error codes are described at the
 163 :ref:`Generic Error Codes <gen-errors>` chapter.
 164
 165 EINVAL
 166     The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
 167     invalid.