1*4882a593Smuzhiyun.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: V4L 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _VIDIOC_G_CROP: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun********************************** 7*4882a593Smuzhiyunioctl VIDIOC_G_CROP, VIDIOC_S_CROP 8*4882a593Smuzhiyun********************************** 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunName 11*4882a593Smuzhiyun==== 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunVIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunSynopsis 16*4882a593Smuzhiyun======== 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun.. c:macro:: VIDIOC_G_CROP 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)`` 21*4882a593Smuzhiyun 22*4882a593Smuzhiyun.. c:macro:: VIDIOC_S_CROP 23*4882a593Smuzhiyun 24*4882a593Smuzhiyun``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)`` 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunArguments 27*4882a593Smuzhiyun========= 28*4882a593Smuzhiyun 29*4882a593Smuzhiyun``fd`` 30*4882a593Smuzhiyun File descriptor returned by :c:func:`open()`. 31*4882a593Smuzhiyun 32*4882a593Smuzhiyun``argp`` 33*4882a593Smuzhiyun Pointer to struct :c:type:`v4l2_crop`. 34*4882a593Smuzhiyun 35*4882a593SmuzhiyunDescription 36*4882a593Smuzhiyun=========== 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunTo query the cropping rectangle size and position applications set the 39*4882a593Smuzhiyun``type`` field of a struct :c:type:`v4l2_crop` structure to the 40*4882a593Smuzhiyunrespective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl 41*4882a593Smuzhiyunwith a pointer to this structure. The driver fills the rest of the 42*4882a593Smuzhiyunstructure or returns the ``EINVAL`` error code if cropping is not supported. 43*4882a593Smuzhiyun 44*4882a593SmuzhiyunTo change the cropping rectangle applications initialize the ``type`` 45*4882a593Smuzhiyunand struct :c:type:`v4l2_rect` substructure named ``c`` of a 46*4882a593Smuzhiyunv4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer 47*4882a593Smuzhiyunto this structure. 48*4882a593Smuzhiyun 49*4882a593SmuzhiyunThe driver first adjusts the requested dimensions against hardware 50*4882a593Smuzhiyunlimits, i. e. the bounds given by the capture/output window, and it 51*4882a593Smuzhiyunrounds to the closest possible values of horizontal and vertical offset, 52*4882a593Smuzhiyunwidth and height. In particular the driver must round the vertical 53*4882a593Smuzhiyunoffset of the cropping rectangle to frame lines modulo two, such that 54*4882a593Smuzhiyunthe field order cannot be confused. 55*4882a593Smuzhiyun 56*4882a593SmuzhiyunSecond the driver adjusts the image size (the opposite rectangle of the 57*4882a593Smuzhiyunscaling process, source or target depending on the data direction) to 58*4882a593Smuzhiyunthe closest size possible while maintaining the current horizontal and 59*4882a593Smuzhiyunvertical scaling factor. 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunFinally the driver programs the hardware with the actual cropping and 62*4882a593Smuzhiyunimage parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not 63*4882a593Smuzhiyunreturn the actual parameters. To query them applications must call 64*4882a593Smuzhiyun:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the 65*4882a593Smuzhiyunparameters are unsuitable the application may modify the cropping or 66*4882a593Smuzhiyunimage parameters and repeat the cycle until satisfactory parameters have 67*4882a593Smuzhiyunbeen negotiated. 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunWhen cropping is not supported then no parameters are changed and 70*4882a593Smuzhiyun:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. 71*4882a593Smuzhiyun 72*4882a593Smuzhiyun.. c:type:: v4l2_crop 73*4882a593Smuzhiyun 74*4882a593Smuzhiyun.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 75*4882a593Smuzhiyun 76*4882a593Smuzhiyun.. flat-table:: struct v4l2_crop 77*4882a593Smuzhiyun :header-rows: 0 78*4882a593Smuzhiyun :stub-columns: 0 79*4882a593Smuzhiyun :widths: 1 1 2 80*4882a593Smuzhiyun 81*4882a593Smuzhiyun * - __u32 82*4882a593Smuzhiyun - ``type`` 83*4882a593Smuzhiyun - Type of the data stream, set by the application. Only these types 84*4882a593Smuzhiyun are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, 85*4882a593Smuzhiyun ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and 86*4882a593Smuzhiyun ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below. 87*4882a593Smuzhiyun * - struct :c:type:`v4l2_rect` 88*4882a593Smuzhiyun - ``c`` 89*4882a593Smuzhiyun - Cropping rectangle. The same co-ordinate system as for struct 90*4882a593Smuzhiyun :c:type:`v4l2_cropcap` ``bounds`` is used. 91*4882a593Smuzhiyun 92*4882a593Smuzhiyun.. note:: 93*4882a593Smuzhiyun Unfortunately in the case of multiplanar buffer types 94*4882a593Smuzhiyun (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) 95*4882a593Smuzhiyun this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field 96*4882a593Smuzhiyun should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while 97*4882a593Smuzhiyun other drivers only accepted a non-multiplanar buffer type (i.e. without the 98*4882a593Smuzhiyun ``_MPLANE`` at the end). 99*4882a593Smuzhiyun 100*4882a593Smuzhiyun Starting with kernel 4.13 both variations are allowed. 101*4882a593Smuzhiyun 102*4882a593SmuzhiyunReturn Value 103*4882a593Smuzhiyun============ 104*4882a593Smuzhiyun 105*4882a593SmuzhiyunOn success 0 is returned, on error -1 and the ``errno`` variable is set 106*4882a593Smuzhiyunappropriately. The generic error codes are described at the 107*4882a593Smuzhiyun:ref:`Generic Error Codes <gen-errors>` chapter. 108*4882a593Smuzhiyun 109*4882a593SmuzhiyunENODATA 110*4882a593Smuzhiyun Cropping is not supported for this input or output. 111