]>
Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_SUBDEV_G_CROP: |
5377d91f MH |
4 | |
5 | ************************************************ | |
6 | ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP | |
7 | ************************************************ | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp ) |
5377d91f | 19 | |
b7e67f6c | 20 | .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp ) |
5377d91f | 21 | |
586027ce | 22 | |
15e7d615 | 23 | Arguments |
5377d91f MH |
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 | ||
15e7d615 | 35 | Description |
5377d91f MH |
36 | =========== |
37 | ||
706f8a99 | 38 | .. note:: |
5377d91f | 39 | |
7347081e | 40 | This is an :ref:`obsolete` interface and may be removed |
5377d91f | 41 | in the future. It is superseded by |
af4a4d0d | 42 | :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. |
5377d91f MH |
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 | |
cdb4af0f | 49 | driver fills the members of the ``rect`` field or returns ``EINVAL`` error |
5377d91f MH |
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 | |
0579e6e3 | 98 | :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. |
5377d91f MH |
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 | ||
8968da9b | 112 | - ``reserved``\ [8] |
5377d91f MH |
113 | |
114 | - Reserved for future extensions. Applications and drivers must set | |
0579e6e3 | 115 | the array to zero. |
5377d91f MH |
116 | |
117 | ||
15e7d615 | 118 | Return Value |
5377d91f MH |
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. |