0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_SUBDEV_G_CROP:
0005
0006 ************************************************
0007 ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
0008 ************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_SUBDEV_G_CROP
0019
0020 ``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)``
0021
0022 .. c:macro:: VIDIOC_SUBDEV_S_CROP
0023
0024 ``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_subdev_crop`.
0034
0035 Description
0036 ===========
0037
0038 .. note::
0039
0040 This is an :ref:`obsolete` interface and may be removed
0041 in the future. It is superseded by
0042 :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`.
0043
0044 To retrieve the current crop rectangle applications set the ``pad``
0045 field of a struct :c:type:`v4l2_subdev_crop` to the
0046 desired pad number as reported by the media API and the ``which`` field
0047 to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the
0048 ``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The
0049 driver fills the members of the ``rect`` field or returns ``EINVAL`` error
0050 code if the input arguments are invalid, or if cropping is not supported
0051 on the given pad.
0052
0053 To change the current crop rectangle applications set both the ``pad``
0054 and ``which`` fields and all members of the ``rect`` field. They then
0055 call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this
0056 structure. The driver verifies the requested crop rectangle, adjusts it
0057 based on the hardware capabilities and configures the device. Upon
0058 return the struct :c:type:`v4l2_subdev_crop`
0059 contains the current format as would be returned by a
0060 ``VIDIOC_SUBDEV_G_CROP`` call.
0061
0062 Applications can query the device capabilities by setting the ``which``
0063 to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not
0064 applied to the device by the driver, but are mangled exactly as active
0065 crop rectangles and stored in the sub-device file handle. Two
0066 applications querying the same sub-device would thus not interact with
0067 each other.
0068
0069 If the subdev device node has been registered in read-only mode, calls to
0070 ``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
0071 ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
0072 variable is set to ``-EPERM``.
0073
0074 Drivers must not return an error solely because the requested crop
0075 rectangle doesn't match the device capabilities. They must instead
0076 modify the rectangle to match what the hardware can provide. The
0077 modified format should be as close as possible to the original request.
0078
0079 .. c:type:: v4l2_subdev_crop
0080
0081 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0082
0083 .. flat-table:: struct v4l2_subdev_crop
0084 :header-rows: 0
0085 :stub-columns: 0
0086 :widths: 1 1 2
0087
0088 * - __u32
0089 - ``pad``
0090 - Pad number as reported by the media framework.
0091 * - __u32
0092 - ``which``
0093 - Crop rectangle to get or set, from enum
0094 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
0095 * - struct :c:type:`v4l2_rect`
0096 - ``rect``
0097 - Crop rectangle boundaries, in pixels.
0098 * - __u32
0099 - ``reserved``\ [8]
0100 - Reserved for future extensions. Applications and drivers must set
0101 the array to zero.
0102
0103 Return Value
0104 ============
0105
0106 On success 0 is returned, on error -1 and the ``errno`` variable is set
0107 appropriately. The generic error codes are described at the
0108 :ref:`Generic Error Codes <gen-errors>` chapter.
0109
0110 EBUSY
0111 The crop rectangle can't be changed because the pad is currently
0112 busy. This can be caused, for instance, by an active video stream on
0113 the pad. The ioctl must not be retried without performing another
0114 action to fix the problem first. Only returned by
0115 ``VIDIOC_SUBDEV_S_CROP``
0116
0117 EINVAL
0118 The struct :c:type:`v4l2_subdev_crop` ``pad``
0119 references a non-existing pad, the ``which`` field references a
0120 non-existing format, or cropping is not supported on the given
0121 subdev pad.
0122
0123 EPERM
0124 The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
0125 and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
