Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_CROPCAP: |
5377d91f MH |
4 | |
5 | ******************** | |
6 | ioctl VIDIOC_CROPCAP | |
7 | ******************** | |
8 | ||
9 | *man VIDIOC_CROPCAP(2)* | |
10 | ||
11 | Information about the video cropping and scaling abilities | |
12 | ||
13 | ||
14 | Synopsis | |
15 | ======== | |
16 | ||
b7e67f6c | 17 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp ) |
5377d91f MH |
18 | |
19 | Arguments | |
20 | ========= | |
21 | ||
22 | ``fd`` | |
23 | File descriptor returned by :ref:`open() <func-open>`. | |
24 | ||
25 | ``request`` | |
26 | VIDIOC_CROPCAP | |
27 | ||
28 | ``argp`` | |
29 | ||
30 | ||
31 | Description | |
32 | =========== | |
33 | ||
34 | Applications use this function to query the cropping limits, the pixel | |
35 | aspect of images and to calculate scale factors. They set the ``type`` | |
36 | field of a v4l2_cropcap structure to the respective buffer (stream) | |
2212ff25 | 37 | type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this |
5377d91f MH |
38 | structure. Drivers fill the rest of the structure. The results are |
39 | constant except when switching the video standard. Remember this switch | |
40 | can occur implicit when switching the video input or output. | |
41 | ||
42 | Do not use the multiplanar buffer types. Use | |
43 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of | |
44 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use | |
45 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of | |
46 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. | |
47 | ||
48 | This ioctl must be implemented for video capture or output devices that | |
49 | support cropping and/or scaling and/or have non-square pixels, and for | |
50 | overlay devices. | |
51 | ||
52 | ||
53 | .. _v4l2-cropcap: | |
54 | ||
55 | .. flat-table:: struct v4l2_cropcap | |
56 | :header-rows: 0 | |
57 | :stub-columns: 0 | |
58 | :widths: 1 1 2 | |
59 | ||
60 | ||
61 | - .. row 1 | |
62 | ||
63 | - __u32 | |
64 | ||
65 | - ``type`` | |
66 | ||
67 | - Type of the data stream, set by the application. Only these types | |
0579e6e3 MCC |
68 | are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, |
69 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and | |
70 | ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`. | |
5377d91f MH |
71 | |
72 | - .. row 2 | |
73 | ||
74 | - struct :ref:`v4l2_rect <v4l2-rect-crop>` | |
75 | ||
76 | - ``bounds`` | |
77 | ||
78 | - Defines the window within capturing or output is possible, this | |
0579e6e3 MCC |
79 | may exclude for example the horizontal and vertical blanking |
80 | areas. The cropping rectangle cannot exceed these limits. Width | |
81 | and height are defined in pixels, the driver writer is free to | |
82 | choose origin and units of the coordinate system in the analog | |
83 | domain. | |
5377d91f MH |
84 | |
85 | - .. row 3 | |
86 | ||
87 | - struct :ref:`v4l2_rect <v4l2-rect-crop>` | |
88 | ||
89 | - ``defrect`` | |
90 | ||
91 | - Default cropping rectangle, it shall cover the "whole picture". | |
0579e6e3 MCC |
92 | Assuming pixel aspect 1/1 this could be for example a 640 × 480 |
93 | rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM | |
94 | centered over the active picture area. The same co-ordinate system | |
95 | as for ``bounds`` is used. | |
5377d91f MH |
96 | |
97 | - .. row 4 | |
98 | ||
99 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
100 | ||
101 | - ``pixelaspect`` | |
102 | ||
103 | - This is the pixel aspect (y / x) when no scaling is applied, the | |
0579e6e3 MCC |
104 | ratio of the actual sampling frequency and the frequency required |
105 | to get square pixels. | |
5377d91f | 106 | |
0579e6e3 MCC |
107 | When cropping coordinates refer to square pixels, the driver sets |
108 | ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and | |
109 | SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`]. | |
5377d91f MH |
110 | |
111 | ||
112 | ||
113 | .. _v4l2-rect-crop: | |
114 | ||
115 | .. flat-table:: struct v4l2_rect | |
116 | :header-rows: 0 | |
117 | :stub-columns: 0 | |
118 | :widths: 1 1 2 | |
119 | ||
120 | ||
121 | - .. row 1 | |
122 | ||
123 | - __s32 | |
124 | ||
125 | - ``left`` | |
126 | ||
127 | - Horizontal offset of the top, left corner of the rectangle, in | |
0579e6e3 | 128 | pixels. |
5377d91f MH |
129 | |
130 | - .. row 2 | |
131 | ||
132 | - __s32 | |
133 | ||
134 | - ``top`` | |
135 | ||
136 | - Vertical offset of the top, left corner of the rectangle, in | |
0579e6e3 | 137 | pixels. |
5377d91f MH |
138 | |
139 | - .. row 3 | |
140 | ||
141 | - __u32 | |
142 | ||
143 | - ``width`` | |
144 | ||
145 | - Width of the rectangle, in pixels. | |
146 | ||
147 | - .. row 4 | |
148 | ||
149 | - __u32 | |
150 | ||
151 | - ``height`` | |
152 | ||
153 | - Height of the rectangle, in pixels. | |
154 | ||
155 | ||
156 | ||
157 | Return Value | |
158 | ============ | |
159 | ||
160 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
161 | appropriately. The generic error codes are described at the | |
162 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
163 | ||
164 | EINVAL | |
165 | The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is | |
166 | invalid. |