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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_CROPCAP:
  11
  12 ********************
  13 ioctl VIDIOC_CROPCAP
  14 ********************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp )
  26     :name: VIDIOC_CROPCAP
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`v4l2_cropcap`.
  37
  38
  39 Description
  40 ===========
  41
  42 Applications use this function to query the cropping limits, the pixel
  43 aspect of images and to calculate scale factors. They set the ``type``
  44 field of a v4l2_cropcap structure to the respective buffer (stream)
  45 type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
  46 structure. Drivers fill the rest of the structure. The results are
  47 constant except when switching the video standard. Remember this switch
  48 can occur implicit when switching the video input or output.
  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 .. c:type:: v4l2_cropcap
  55
  56 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  57
  58 .. flat-table:: struct v4l2_cropcap
  59     :header-rows:  0
  60     :stub-columns: 0
  61     :widths:       1 1 2
  62
  63     * - __u32
  64       - ``type``
  65       - Type of the data stream, set by the application. Only these types
  66         are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
  67         ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
  68         ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
  69     * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
  70       - ``bounds``
  71       - Defines the window within capturing or output is possible, this
  72         may exclude for example the horizontal and vertical blanking
  73         areas. The cropping rectangle cannot exceed these limits. Width
  74         and height are defined in pixels, the driver writer is free to
  75         choose origin and units of the coordinate system in the analog
  76         domain.
  77     * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
  78       - ``defrect``
  79       - Default cropping rectangle, it shall cover the "whole picture".
  80         Assuming pixel aspect 1/1 this could be for example a 640 × 480
  81         rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
  82         centered over the active picture area. The same co-ordinate system
  83         as for ``bounds`` is used.
  84     * - struct :c:type:`v4l2_fract`
  85       - ``pixelaspect``
  86       - This is the pixel aspect (y / x) when no scaling is applied, the
  87         ratio of the actual sampling frequency and the frequency required
  88         to get square pixels.
  89
  90         When cropping coordinates refer to square pixels, the driver sets
  91         ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
  92         SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
  93
  94 .. note::
  95    Unfortunately in the case of multiplanar buffer types
  96    (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
  97    this API was messed up with regards to how the :c:type:`v4l2_cropcap` ``type`` field
  98    should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
  99    other drivers only accepted a non-multiplanar buffer type (i.e. without the
 100    ``_MPLANE`` at the end).
 101
 102    Starting with kernel 4.13 both variations are allowed.
 103
 104
 105
 106 .. _v4l2-rect-crop:
 107
 108 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 109
 110 .. flat-table:: struct v4l2_rect
 111     :header-rows:  0
 112     :stub-columns: 0
 113     :widths:       1 1 2
 114
 115     * - __s32
 116       - ``left``
 117       - Horizontal offset of the top, left corner of the rectangle, in
 118         pixels.
 119     * - __s32
 120       - ``top``
 121       - Vertical offset of the top, left corner of the rectangle, in
 122         pixels.
 123     * - __u32
 124       - ``width``
 125       - Width of the rectangle, in pixels.
 126     * - __u32
 127       - ``height``
 128       - Height of the rectangle, in pixels.
 129
 130
 131 Return Value
 132 ============
 133
 134 On success 0 is returned, on error -1 and the ``errno`` variable is set
 135 appropriately. The generic error codes are described at the
 136 :ref:`Generic Error Codes <gen-errors>` chapter.
 137
 138 EINVAL
 139     The struct :c:type:`v4l2_cropcap` ``type`` is
 140     invalid.
 141
 142 ENODATA
 143     Cropping is not supported for this input or output.