134 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_CROPCAP:5 6********************7ioctl VIDIOC_CROPCAP8********************9 10Name11====12 13VIDIOC_CROPCAP - Information about the video cropping and scaling abilities14 15Synopsis16========17 18.. c:macro:: VIDIOC_CROPCAP19 20``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)``21 22Arguments23=========24 25``fd``26 File descriptor returned by :c:func:`open()`.27 28``argp``29 Pointer to struct :c:type:`v4l2_cropcap`.30 31Description32===========33 34Applications use this function to query the cropping limits, the pixel35aspect of images and to calculate scale factors. They set the ``type``36field of a v4l2_cropcap structure to the respective buffer (stream)37type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this38structure. Drivers fill the rest of the structure. The results are39constant except when switching the video standard. Remember this switch40can occur implicit when switching the video input or output.41 42This ioctl must be implemented for video capture or output devices that43support cropping and/or scaling and/or have non-square pixels, and for44overlay devices.45 46.. c:type:: v4l2_cropcap47 48.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|49 50.. flat-table:: struct v4l2_cropcap51 :header-rows: 052 :stub-columns: 053 :widths: 1 1 254 55 * - __u3256 - ``type``57 - Type of the data stream, set by the application. Only these types58 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`` and60 ``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, this64 may exclude for example the horizontal and vertical blanking65 areas. The cropping rectangle cannot exceed these limits. Width66 and height are defined in pixels, the driver writer is free to67 choose origin and units of the coordinate system in the analog68 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 × 48073 rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM74 centered over the active picture area. The same coordinate system75 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, the79 ratio of the actual sampling frequency and the frequency required80 to get square pixels.81 82 When cropping coordinates refer to square pixels, the driver sets83 ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and84 SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].85 86.. note::87 Unfortunately in the case of multiplanar buffer types88 (``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`` field90 should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while91 other drivers only accepted a non-multiplanar buffer type (i.e. without the92 ``_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.5cm}|100 101.. flat-table:: struct v4l2_rect102 :header-rows: 0103 :stub-columns: 0104 :widths: 1 1 2105 106 * - __s32107 - ``left``108 - Horizontal offset of the top, left corner of the rectangle, in109 pixels.110 * - __s32111 - ``top``112 - Vertical offset of the top, left corner of the rectangle, in113 pixels.114 * - __u32115 - ``width``116 - Width of the rectangle, in pixels.117 * - __u32118 - ``height``119 - Height of the rectangle, in pixels.120 121Return Value122============123 124On success 0 is returned, on error -1 and the ``errno`` variable is set125appropriately. The generic error codes are described at the126:ref:`Generic Error Codes <gen-errors>` chapter.127 128EINVAL129 The struct :c:type:`v4l2_cropcap` ``type`` is130 invalid.131 132ENODATA133 Cropping is not supported for this input or output.134