1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_G_CROP: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab********************************** 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_G_CROP, VIDIOC_S_CROP 854f38fcaSMauro Carvalho Chehab********************************** 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_G_CROP 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)`` 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_S_CROP 23407e84cdSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)`` 2554f38fcaSMauro Carvalho Chehab 2654f38fcaSMauro Carvalho ChehabArguments 2754f38fcaSMauro Carvalho Chehab========= 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho Chehab``fd`` 30407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho Chehab``argp`` 3354f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_crop`. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabDescription 3654f38fcaSMauro Carvalho Chehab=========== 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabTo query the cropping rectangle size and position applications set the 3954f38fcaSMauro Carvalho Chehab``type`` field of a struct :c:type:`v4l2_crop` structure to the 4054f38fcaSMauro Carvalho Chehabrespective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl 4154f38fcaSMauro Carvalho Chehabwith a pointer to this structure. The driver fills the rest of the 4254f38fcaSMauro Carvalho Chehabstructure or returns the ``EINVAL`` error code if cropping is not supported. 4354f38fcaSMauro Carvalho Chehab 4454f38fcaSMauro Carvalho ChehabTo change the cropping rectangle applications initialize the ``type`` 4554f38fcaSMauro Carvalho Chehaband struct :c:type:`v4l2_rect` substructure named ``c`` of a 4654f38fcaSMauro Carvalho Chehabv4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer 4754f38fcaSMauro Carvalho Chehabto this structure. 4854f38fcaSMauro Carvalho Chehab 4954f38fcaSMauro Carvalho ChehabThe driver first adjusts the requested dimensions against hardware 5054f38fcaSMauro Carvalho Chehablimits, i. e. the bounds given by the capture/output window, and it 5154f38fcaSMauro Carvalho Chehabrounds to the closest possible values of horizontal and vertical offset, 5254f38fcaSMauro Carvalho Chehabwidth and height. In particular the driver must round the vertical 5354f38fcaSMauro Carvalho Chehaboffset of the cropping rectangle to frame lines modulo two, such that 5454f38fcaSMauro Carvalho Chehabthe field order cannot be confused. 5554f38fcaSMauro Carvalho Chehab 5654f38fcaSMauro Carvalho ChehabSecond the driver adjusts the image size (the opposite rectangle of the 5754f38fcaSMauro Carvalho Chehabscaling process, source or target depending on the data direction) to 5854f38fcaSMauro Carvalho Chehabthe closest size possible while maintaining the current horizontal and 5954f38fcaSMauro Carvalho Chehabvertical scaling factor. 6054f38fcaSMauro Carvalho Chehab 6154f38fcaSMauro Carvalho ChehabFinally the driver programs the hardware with the actual cropping and 6254f38fcaSMauro Carvalho Chehabimage parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not 6354f38fcaSMauro Carvalho Chehabreturn the actual parameters. To query them applications must call 6454f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the 6554f38fcaSMauro Carvalho Chehabparameters are unsuitable the application may modify the cropping or 6654f38fcaSMauro Carvalho Chehabimage parameters and repeat the cycle until satisfactory parameters have 6754f38fcaSMauro Carvalho Chehabbeen negotiated. 6854f38fcaSMauro Carvalho Chehab 6954f38fcaSMauro Carvalho ChehabWhen cropping is not supported then no parameters are changed and 7054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. 7154f38fcaSMauro Carvalho Chehab 7254f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_crop 7354f38fcaSMauro Carvalho Chehab 74*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 7554f38fcaSMauro Carvalho Chehab 7654f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_crop 7754f38fcaSMauro Carvalho Chehab :header-rows: 0 7854f38fcaSMauro Carvalho Chehab :stub-columns: 0 7954f38fcaSMauro Carvalho Chehab :widths: 1 1 2 8054f38fcaSMauro Carvalho Chehab 8154f38fcaSMauro Carvalho Chehab * - __u32 8254f38fcaSMauro Carvalho Chehab - ``type`` 8354f38fcaSMauro Carvalho Chehab - Type of the data stream, set by the application. Only these types 8454f38fcaSMauro Carvalho Chehab are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, 8554f38fcaSMauro Carvalho Chehab ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and 8654f38fcaSMauro Carvalho Chehab ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below. 8754f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_rect` 8854f38fcaSMauro Carvalho Chehab - ``c`` 8954f38fcaSMauro Carvalho Chehab - Cropping rectangle. The same co-ordinate system as for struct 9054f38fcaSMauro Carvalho Chehab :c:type:`v4l2_cropcap` ``bounds`` is used. 9154f38fcaSMauro Carvalho Chehab 9254f38fcaSMauro Carvalho Chehab.. note:: 9354f38fcaSMauro Carvalho Chehab Unfortunately in the case of multiplanar buffer types 9454f38fcaSMauro Carvalho Chehab (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) 9554f38fcaSMauro Carvalho Chehab this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field 9654f38fcaSMauro Carvalho Chehab should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while 9754f38fcaSMauro Carvalho Chehab other drivers only accepted a non-multiplanar buffer type (i.e. without the 9854f38fcaSMauro Carvalho Chehab ``_MPLANE`` at the end). 9954f38fcaSMauro Carvalho Chehab 10054f38fcaSMauro Carvalho Chehab Starting with kernel 4.13 both variations are allowed. 10154f38fcaSMauro Carvalho Chehab 10254f38fcaSMauro Carvalho ChehabReturn Value 10354f38fcaSMauro Carvalho Chehab============ 10454f38fcaSMauro Carvalho Chehab 10554f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 10654f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 10754f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 10854f38fcaSMauro Carvalho Chehab 10954f38fcaSMauro Carvalho ChehabENODATA 11054f38fcaSMauro Carvalho Chehab Cropping is not supported for this input or output. 111