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_SUBDEV_G_CROP: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************************************************ 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP 854f38fcaSMauro Carvalho Chehab************************************************ 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_SUBDEV_G_CROP 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)`` 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_SUBDEV_S_CROP 23407e84cdSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_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_subdev_crop`. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabDescription 3654f38fcaSMauro Carvalho Chehab=========== 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho Chehab.. note:: 3954f38fcaSMauro Carvalho Chehab 4054f38fcaSMauro Carvalho Chehab This is an :ref:`obsolete` interface and may be removed 4154f38fcaSMauro Carvalho Chehab in the future. It is superseded by 4254f38fcaSMauro Carvalho Chehab :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. 4354f38fcaSMauro Carvalho Chehab 4454f38fcaSMauro Carvalho ChehabTo retrieve the current crop rectangle applications set the ``pad`` 4554f38fcaSMauro Carvalho Chehabfield of a struct :c:type:`v4l2_subdev_crop` to the 4654f38fcaSMauro Carvalho Chehabdesired pad number as reported by the media API and the ``which`` field 4754f38fcaSMauro Carvalho Chehabto ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the 4854f38fcaSMauro Carvalho Chehab``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The 4954f38fcaSMauro Carvalho Chehabdriver fills the members of the ``rect`` field or returns ``EINVAL`` error 5054f38fcaSMauro Carvalho Chehabcode if the input arguments are invalid, or if cropping is not supported 5154f38fcaSMauro Carvalho Chehabon the given pad. 5254f38fcaSMauro Carvalho Chehab 5354f38fcaSMauro Carvalho ChehabTo change the current crop rectangle applications set both the ``pad`` 5454f38fcaSMauro Carvalho Chehaband ``which`` fields and all members of the ``rect`` field. They then 5554f38fcaSMauro Carvalho Chehabcall the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this 5654f38fcaSMauro Carvalho Chehabstructure. The driver verifies the requested crop rectangle, adjusts it 5754f38fcaSMauro Carvalho Chehabbased on the hardware capabilities and configures the device. Upon 5854f38fcaSMauro Carvalho Chehabreturn the struct :c:type:`v4l2_subdev_crop` 5954f38fcaSMauro Carvalho Chehabcontains the current format as would be returned by a 6054f38fcaSMauro Carvalho Chehab``VIDIOC_SUBDEV_G_CROP`` call. 6154f38fcaSMauro Carvalho Chehab 6254f38fcaSMauro Carvalho ChehabApplications can query the device capabilities by setting the ``which`` 6354f38fcaSMauro Carvalho Chehabto ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not 6454f38fcaSMauro Carvalho Chehabapplied to the device by the driver, but are mangled exactly as active 6554f38fcaSMauro Carvalho Chehabcrop rectangles and stored in the sub-device file handle. Two 6654f38fcaSMauro Carvalho Chehabapplications querying the same sub-device would thus not interact with 6754f38fcaSMauro Carvalho Chehabeach other. 6854f38fcaSMauro Carvalho Chehab 693fb0ee8bSJacopo MondiIf the subdev device node has been registered in read-only mode, calls to 703fb0ee8bSJacopo Mondi``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to 713fb0ee8bSJacopo Mondi``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno 723fb0ee8bSJacopo Mondivariable is set to ``-EPERM``. 733fb0ee8bSJacopo Mondi 7454f38fcaSMauro Carvalho ChehabDrivers must not return an error solely because the requested crop 7554f38fcaSMauro Carvalho Chehabrectangle doesn't match the device capabilities. They must instead 7654f38fcaSMauro Carvalho Chehabmodify the rectangle to match what the hardware can provide. The 7754f38fcaSMauro Carvalho Chehabmodified format should be as close as possible to the original request. 7854f38fcaSMauro Carvalho Chehab 7954f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_subdev_crop 8054f38fcaSMauro Carvalho Chehab 81fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 8254f38fcaSMauro Carvalho Chehab 8354f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_subdev_crop 8454f38fcaSMauro Carvalho Chehab :header-rows: 0 8554f38fcaSMauro Carvalho Chehab :stub-columns: 0 8654f38fcaSMauro Carvalho Chehab :widths: 1 1 2 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab * - __u32 8954f38fcaSMauro Carvalho Chehab - ``pad`` 9054f38fcaSMauro Carvalho Chehab - Pad number as reported by the media framework. 9154f38fcaSMauro Carvalho Chehab * - __u32 9254f38fcaSMauro Carvalho Chehab - ``which`` 9354f38fcaSMauro Carvalho Chehab - Crop rectangle to get or set, from enum 9454f38fcaSMauro Carvalho Chehab :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. 9554f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_rect` 9654f38fcaSMauro Carvalho Chehab - ``rect`` 9754f38fcaSMauro Carvalho Chehab - Crop rectangle boundaries, in pixels. 9854f38fcaSMauro Carvalho Chehab * - __u32 99*2f91e10eSTomi Valkeinen - ``stream`` 100*2f91e10eSTomi Valkeinen - Stream identifier. 101*2f91e10eSTomi Valkeinen * - __u32 102*2f91e10eSTomi Valkeinen - ``reserved``\ [7] 10354f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Applications and drivers must set 10454f38fcaSMauro Carvalho Chehab the array to zero. 10554f38fcaSMauro Carvalho Chehab 10654f38fcaSMauro Carvalho ChehabReturn Value 10754f38fcaSMauro Carvalho Chehab============ 10854f38fcaSMauro Carvalho Chehab 10954f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 11054f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 11154f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 11254f38fcaSMauro Carvalho Chehab 11354f38fcaSMauro Carvalho ChehabEBUSY 11454f38fcaSMauro Carvalho Chehab The crop rectangle can't be changed because the pad is currently 11554f38fcaSMauro Carvalho Chehab busy. This can be caused, for instance, by an active video stream on 11654f38fcaSMauro Carvalho Chehab the pad. The ioctl must not be retried without performing another 11754f38fcaSMauro Carvalho Chehab action to fix the problem first. Only returned by 11854f38fcaSMauro Carvalho Chehab ``VIDIOC_SUBDEV_S_CROP`` 11954f38fcaSMauro Carvalho Chehab 12054f38fcaSMauro Carvalho ChehabEINVAL 12154f38fcaSMauro Carvalho Chehab The struct :c:type:`v4l2_subdev_crop` ``pad`` 12254f38fcaSMauro Carvalho Chehab references a non-existing pad, the ``which`` field references a 12354f38fcaSMauro Carvalho Chehab non-existing format, or cropping is not supported on the given 12454f38fcaSMauro Carvalho Chehab subdev pad. 1253fb0ee8bSJacopo Mondi 1263fb0ee8bSJacopo MondiEPERM 1273fb0ee8bSJacopo Mondi The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice 1283fb0ee8bSJacopo Mondi and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``. 129