Documentation/userspace-api/media/v4l/vidioc-cropcap.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_CROPCAP:
   5
   6 ********************
   7 ioctl VIDIOC_CROPCAP
   8 ********************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_CROPCAP
  19
  20 ``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_cropcap`.
  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 This ioctl must be implemented for video capture or output devices that
  43 support cropping and/or scaling and/or have non-square pixels, and for
  44 overlay devices.
  45
  46 .. c:type:: v4l2_cropcap
  47
  48 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  49
  50 .. flat-table:: struct v4l2_cropcap
  51     :header-rows:  0
  52     :stub-columns: 0
  53     :widths:       1 1 2
  54
  55     * - __u32
  56       - ``type``
  57       - Type of the data stream, set by the application. Only these types
  58         are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
  59         ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
  60         ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
  61     * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
  62       - ``bounds``
  63       - Defines the window within capturing or output is possible, this
  64         may exclude for example the horizontal and vertical blanking
  65         areas. The cropping rectangle cannot exceed these limits. Width
  66         and height are defined in pixels, the driver writer is free to
  67         choose origin and units of the coordinate system in the analog
  68         domain.
  69     * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
  70       - ``defrect``
  71       - Default cropping rectangle, it shall cover the "whole picture".
  72         Assuming pixel aspect 1/1 this could be for example a 640 × 480
  73         rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
  74         centered over the active picture area. The same co-ordinate system
  75         as for ``bounds`` is used.
  76     * - struct :c:type:`v4l2_fract`
  77       - ``pixelaspect``
  78       - This is the pixel aspect (y / x) when no scaling is applied, the
  79         ratio of the actual sampling frequency and the frequency required
  80         to get square pixels.
  81
  82         When cropping coordinates refer to square pixels, the driver sets
  83         ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
  84         SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
  85
  86 .. note::
  87    Unfortunately in the case of multiplanar buffer types
  88    (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
  89    this API was messed up with regards to how the :c:type:`v4l2_cropcap` ``type`` field
  90    should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
  91    other drivers only accepted a non-multiplanar buffer type (i.e. without the
  92    ``_MPLANE`` at the end).
  93
  94    Starting with kernel 4.13 both variations are allowed.
  95
  96
  97 .. _v4l2-rect-crop:
  98
  99 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 100
 101 .. flat-table:: struct v4l2_rect
 102     :header-rows:  0
 103     :stub-columns: 0
 104     :widths:       1 1 2
 105
 106     * - __s32
 107       - ``left``
 108       - Horizontal offset of the top, left corner of the rectangle, in
 109         pixels.
 110     * - __s32
 111       - ``top``
 112       - Vertical offset of the top, left corner of the rectangle, in
 113         pixels.
 114     * - __u32
 115       - ``width``
 116       - Width of the rectangle, in pixels.
 117     * - __u32
 118       - ``height``
 119       - Height of the rectangle, in pixels.
 120
 121 Return Value
 122 ============
 123
 124 On success 0 is returned, on error -1 and the ``errno`` variable is set
 125 appropriately. The generic error codes are described at the
 126 :ref:`Generic Error Codes <gen-errors>` chapter.
 127
 128 EINVAL
 129     The struct :c:type:`v4l2_cropcap` ``type`` is
 130     invalid.
 131
 132 ENODATA
 133     Cropping is not supported for this input or output.