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