Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 3 | .. _VIDIOC_SUBDEV_G_CROP: |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 4 | |
| 5 | ************************************************ |
| 6 | ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP |
| 7 | ************************************************ |
| 8 | |
Mauro Carvalho Chehab | 15e7d61 | 2016-07-05 15:14:35 -0300 | [diff] [blame] | 9 | Name |
Mauro Carvalho Chehab | 586027c | 2016-07-05 07:58:48 -0300 | [diff] [blame] | 10 | ==== |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 11 | |
Mauro Carvalho Chehab | 586027c | 2016-07-05 07:58:48 -0300 | [diff] [blame] | 12 | VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 13 | |
Mauro Carvalho Chehab | 15e7d61 | 2016-07-05 15:14:35 -0300 | [diff] [blame] | 14 | |
| 15 | Synopsis |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 16 | ======== |
| 17 | |
Mauro Carvalho Chehab | b7e67f6 | 2016-07-02 09:49:16 -0300 | [diff] [blame] | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp ) |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 19 | |
Mauro Carvalho Chehab | b7e67f6 | 2016-07-02 09:49:16 -0300 | [diff] [blame] | 20 | .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp ) |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 21 | |
Mauro Carvalho Chehab | 586027c | 2016-07-05 07:58:48 -0300 | [diff] [blame] | 22 | |
Mauro Carvalho Chehab | 15e7d61 | 2016-07-05 15:14:35 -0300 | [diff] [blame] | 23 | Arguments |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 24 | ========= |
| 25 | |
| 26 | ``fd`` |
| 27 | File descriptor returned by :ref:`open() <func-open>`. |
| 28 | |
| 29 | ``request`` |
| 30 | VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP |
| 31 | |
| 32 | ``argp`` |
| 33 | |
| 34 | |
Mauro Carvalho Chehab | 15e7d61 | 2016-07-05 15:14:35 -0300 | [diff] [blame] | 35 | Description |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 36 | =========== |
| 37 | |
Mauro Carvalho Chehab | 706f8a9 | 2016-07-10 11:57:43 -0300 | [diff] [blame] | 38 | .. note:: |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 39 | |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 40 | This is an :ref:`obsolete` interface and may be removed |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 41 | in the future. It is superseded by |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 42 | :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 43 | |
| 44 | To retrieve the current crop rectangle applications set the ``pad`` |
| 45 | field of a struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` to the |
| 46 | desired pad number as reported by the media API and the ``which`` field |
| 47 | to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the |
| 48 | ``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The |
Mauro Carvalho Chehab | cdb4af0 | 2016-07-03 11:53:09 -0300 | [diff] [blame] | 49 | driver fills the members of the ``rect`` field or returns ``EINVAL`` error |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 50 | code if the input arguments are invalid, or if cropping is not supported |
| 51 | on the given pad. |
| 52 | |
| 53 | To change the current crop rectangle applications set both the ``pad`` |
| 54 | and ``which`` fields and all members of the ``rect`` field. They then |
| 55 | call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this |
| 56 | structure. The driver verifies the requested crop rectangle, adjusts it |
| 57 | based on the hardware capabilities and configures the device. Upon |
| 58 | return the struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` |
| 59 | contains the current format as would be returned by a |
| 60 | ``VIDIOC_SUBDEV_G_CROP`` call. |
| 61 | |
| 62 | Applications can query the device capabilities by setting the ``which`` |
| 63 | to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not |
| 64 | applied to the device by the driver, but are mangled exactly as active |
| 65 | crop rectangles and stored in the sub-device file handle. Two |
| 66 | applications querying the same sub-device would thus not interact with |
| 67 | each other. |
| 68 | |
| 69 | Drivers must not return an error solely because the requested crop |
| 70 | rectangle doesn't match the device capabilities. They must instead |
| 71 | modify the rectangle to match what the hardware can provide. The |
| 72 | modified format should be as close as possible to the original request. |
| 73 | |
| 74 | |
| 75 | .. _v4l2-subdev-crop: |
| 76 | |
| 77 | .. flat-table:: struct v4l2_subdev_crop |
| 78 | :header-rows: 0 |
| 79 | :stub-columns: 0 |
| 80 | :widths: 1 1 2 |
| 81 | |
| 82 | |
| 83 | - .. row 1 |
| 84 | |
| 85 | - __u32 |
| 86 | |
| 87 | - ``pad`` |
| 88 | |
| 89 | - Pad number as reported by the media framework. |
| 90 | |
| 91 | - .. row 2 |
| 92 | |
| 93 | - __u32 |
| 94 | |
| 95 | - ``which`` |
| 96 | |
| 97 | - Crop rectangle to get or set, from enum |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame] | 98 | :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 99 | |
| 100 | - .. row 3 |
| 101 | |
| 102 | - struct :ref:`v4l2_rect <v4l2-rect>` |
| 103 | |
| 104 | - ``rect`` |
| 105 | |
| 106 | - Crop rectangle boundaries, in pixels. |
| 107 | |
| 108 | - .. row 4 |
| 109 | |
| 110 | - __u32 |
| 111 | |
Mauro Carvalho Chehab | 8968da9 | 2016-07-13 08:43:30 -0300 | [diff] [blame] | 112 | - ``reserved``\ [8] |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 113 | |
| 114 | - Reserved for future extensions. Applications and drivers must set |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame] | 115 | the array to zero. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 116 | |
| 117 | |
Mauro Carvalho Chehab | 15e7d61 | 2016-07-05 15:14:35 -0300 | [diff] [blame] | 118 | Return Value |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 119 | ============ |
| 120 | |
| 121 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 122 | appropriately. The generic error codes are described at the |
| 123 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 124 | |
| 125 | EBUSY |
| 126 | The crop rectangle can't be changed because the pad is currently |
| 127 | busy. This can be caused, for instance, by an active video stream on |
| 128 | the pad. The ioctl must not be retried without performing another |
| 129 | action to fix the problem first. Only returned by |
| 130 | ``VIDIOC_SUBDEV_S_CROP`` |
| 131 | |
| 132 | EINVAL |
| 133 | The struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` ``pad`` |
| 134 | references a non-existing pad, the ``which`` field references a |
| 135 | non-existing format, or cropping is not supported on the given |
| 136 | subdev pad. |