Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _vidioc-subdev-g-selection: | |
4 | ||
5 | ********************************************************** | |
6 | ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION | |
7 | ********************************************************** | |
8 | ||
9 | *man VIDIOC_SUBDEV_G_SELECTION(2)* | |
10 | ||
11 | VIDIOC_SUBDEV_S_SELECTION | |
12 | Get or set selection rectangles on a subdev pad | |
13 | ||
14 | ||
15 | Synopsis | |
16 | ======== | |
17 | ||
18 | .. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp ) | |
19 | ||
20 | Arguments | |
21 | ========= | |
22 | ||
23 | ``fd`` | |
24 | File descriptor returned by :ref:`open() <func-open>`. | |
25 | ||
26 | ``request`` | |
27 | VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION | |
28 | ||
29 | ``argp`` | |
30 | ||
31 | ||
32 | Description | |
33 | =========== | |
34 | ||
35 | The selections are used to configure various image processing | |
36 | functionality performed by the subdevs which affect the image size. This | |
37 | currently includes cropping, scaling and composition. | |
38 | ||
39 | The selection API replaces | |
40 | :ref:`the old subdev crop API <vidioc-subdev-g-crop>`. All the | |
41 | function of the crop API, and more, are supported by the selections API. | |
42 | ||
43 | See :ref:`subdev` for more information on how each selection target | |
44 | affects the image processing pipeline inside the subdevice. | |
45 | ||
46 | ||
47 | Types of selection targets | |
48 | -------------------------- | |
49 | ||
50 | There are two types of selection targets: actual and bounds. The actual | |
51 | targets are the targets which configure the hardware. The BOUNDS target | |
52 | will return a rectangle that contain all possible actual rectangles. | |
53 | ||
54 | ||
55 | Discovering supported features | |
56 | ------------------------------ | |
57 | ||
58 | To discover which targets are supported, the user can perform | |
59 | ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will | |
60 | return ``EINVAL``. | |
61 | ||
62 | Selection targets and flags are documented in | |
63 | :ref:`v4l2-selections-common`. | |
64 | ||
65 | ||
66 | .. _v4l2-subdev-selection: | |
67 | ||
68 | .. flat-table:: struct v4l2_subdev_selection | |
69 | :header-rows: 0 | |
70 | :stub-columns: 0 | |
71 | :widths: 1 1 2 | |
72 | ||
73 | ||
74 | - .. row 1 | |
75 | ||
76 | - __u32 | |
77 | ||
78 | - ``which`` | |
79 | ||
80 | - Active or try selection, from enum | |
81 | :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. | |
82 | ||
83 | - .. row 2 | |
84 | ||
85 | - __u32 | |
86 | ||
87 | - ``pad`` | |
88 | ||
89 | - Pad number as reported by the media framework. | |
90 | ||
91 | - .. row 3 | |
92 | ||
93 | - __u32 | |
94 | ||
95 | - ``target`` | |
96 | ||
97 | - Target selection rectangle. See :ref:`v4l2-selections-common`. | |
98 | ||
99 | - .. row 4 | |
100 | ||
101 | - __u32 | |
102 | ||
103 | - ``flags`` | |
104 | ||
105 | - Flags. See :ref:`v4l2-selection-flags`. | |
106 | ||
107 | - .. row 5 | |
108 | ||
109 | - struct :ref:`v4l2_rect <v4l2-rect>` | |
110 | ||
111 | - ``r`` | |
112 | ||
113 | - Selection rectangle, in pixels. | |
114 | ||
115 | - .. row 6 | |
116 | ||
117 | - __u32 | |
118 | ||
119 | - ``reserved``\ [8] | |
120 | ||
121 | - Reserved for future extensions. Applications and drivers must set | |
122 | the array to zero. | |
123 | ||
124 | ||
125 | ||
126 | Return Value | |
127 | ============ | |
128 | ||
129 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
130 | appropriately. The generic error codes are described at the | |
131 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
132 | ||
133 | EBUSY | |
134 | The selection rectangle can't be changed because the pad is | |
135 | currently busy. This can be caused, for instance, by an active video | |
136 | stream on the pad. The ioctl must not be retried without performing | |
137 | another action to fix the problem first. Only returned by | |
138 | ``VIDIOC_SUBDEV_S_SELECTION`` | |
139 | ||
140 | EINVAL | |
141 | The struct :ref:`v4l2_subdev_selection <v4l2-subdev-selection>` | |
142 | ``pad`` references a non-existing pad, the ``which`` field | |
143 | references a non-existing format, or the selection target is not | |
144 | supported on the given subdev pad. | |
145 | ||
146 | ||
147 | .. ------------------------------------------------------------------------------ | |
148 | .. This file was automatically converted from DocBook-XML with the dbxml | |
149 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
150 | .. from the linux kernel, refer to: | |
151 | .. | |
152 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
153 | .. ------------------------------------------------------------------------------ |