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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_CROPCAP:
   4
   5 ********************
   6 ioctl VIDIOC_CROPCAP
   7 ********************
   8
   9 *man VIDIOC_CROPCAP(2)*
  10
  11 Information about the video cropping and scaling abilities
  12
  13
  14 Synopsis
  15 ========
  16
  17 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp )
  18
  19 Arguments
  20 =========
  21
  22 ``fd``
  23     File descriptor returned by :ref:`open() <func-open>`.
  24
  25 ``request``
  26     VIDIOC_CROPCAP
  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 .. _v4l2-cropcap:
  54
  55 .. flat-table:: struct v4l2_cropcap
  56     :header-rows:  0
  57     :stub-columns: 0
  58     :widths:       1 1 2
  59
  60
  61     -  .. row 1
  62
  63        -  __u32
  64
  65        -  ``type``
  66
  67        -  Type of the data stream, set by the application. Only these types
  68           are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
  69           ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
  70           ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
  71
  72     -  .. row 2
  73
  74        -  struct :ref:`v4l2_rect <v4l2-rect-crop>`
  75
  76        -  ``bounds``
  77
  78        -  Defines the window within capturing or output is possible, this
  79           may exclude for example the horizontal and vertical blanking
  80           areas. The cropping rectangle cannot exceed these limits. Width
  81           and height are defined in pixels, the driver writer is free to
  82           choose origin and units of the coordinate system in the analog
  83           domain.
  84
  85     -  .. row 3
  86
  87        -  struct :ref:`v4l2_rect <v4l2-rect-crop>`
  88
  89        -  ``defrect``
  90
  91        -  Default cropping rectangle, it shall cover the "whole picture".
  92           Assuming pixel aspect 1/1 this could be for example a 640 × 480
  93           rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
  94           centered over the active picture area. The same co-ordinate system
  95           as for ``bounds`` is used.
  96
  97     -  .. row 4
  98
  99        -  struct :ref:`v4l2_fract <v4l2-fract>`
 100
 101        -  ``pixelaspect``
 102
 103        -  This is the pixel aspect (y / x) when no scaling is applied, the
 104           ratio of the actual sampling frequency and the frequency required
 105           to get square pixels.
 106
 107           When cropping coordinates refer to square pixels, the driver sets
 108           ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
 109           SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
 110
 111
 112
 113 .. _v4l2-rect-crop:
 114
 115 .. flat-table:: struct v4l2_rect
 116     :header-rows:  0
 117     :stub-columns: 0
 118     :widths:       1 1 2
 119
 120
 121     -  .. row 1
 122
 123        -  __s32
 124
 125        -  ``left``
 126
 127        -  Horizontal offset of the top, left corner of the rectangle, in
 128           pixels.
 129
 130     -  .. row 2
 131
 132        -  __s32
 133
 134        -  ``top``
 135
 136        -  Vertical offset of the top, left corner of the rectangle, in
 137           pixels.
 138
 139     -  .. row 3
 140
 141        -  __u32
 142
 143        -  ``width``
 144
 145        -  Width of the rectangle, in pixels.
 146
 147     -  .. row 4
 148
 149        -  __u32
 150
 151        -  ``height``
 152
 153        -  Height of the rectangle, in pixels.
 154
 155
 156
 157 Return Value
 158 ============
 159
 160 On success 0 is returned, on error -1 and the ``errno`` variable is set
 161 appropriately. The generic error codes are described at the
 162 :ref:`Generic Error Codes <gen-errors>` chapter.
 163
 164 EINVAL
 165     The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
 166     invalid.