diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml')
-rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml new file mode 100644 index 00000000000..69c0d8a2a3d --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml | |||
@@ -0,0 +1,297 @@ | |||
1 | <refentry id="vidioc-subscribe-event"> | ||
2 | <refmeta> | ||
3 | <refentrytitle>ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refentrytitle> | ||
4 | &manvol; | ||
5 | </refmeta> | ||
6 | |||
7 | <refnamediv> | ||
8 | <refname>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refname> | ||
9 | <refpurpose>Subscribe or unsubscribe event</refpurpose> | ||
10 | </refnamediv> | ||
11 | |||
12 | <refsynopsisdiv> | ||
13 | <funcsynopsis> | ||
14 | <funcprototype> | ||
15 | <funcdef>int <function>ioctl</function></funcdef> | ||
16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
18 | <paramdef>struct v4l2_event_subscription | ||
19 | *<parameter>argp</parameter></paramdef> | ||
20 | </funcprototype> | ||
21 | </funcsynopsis> | ||
22 | </refsynopsisdiv> | ||
23 | |||
24 | <refsect1> | ||
25 | <title>Arguments</title> | ||
26 | |||
27 | <variablelist> | ||
28 | <varlistentry> | ||
29 | <term><parameter>fd</parameter></term> | ||
30 | <listitem> | ||
31 | <para>&fd;</para> | ||
32 | </listitem> | ||
33 | </varlistentry> | ||
34 | <varlistentry> | ||
35 | <term><parameter>request</parameter></term> | ||
36 | <listitem> | ||
37 | <para>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</para> | ||
38 | </listitem> | ||
39 | </varlistentry> | ||
40 | <varlistentry> | ||
41 | <term><parameter>argp</parameter></term> | ||
42 | <listitem> | ||
43 | <para></para> | ||
44 | </listitem> | ||
45 | </varlistentry> | ||
46 | </variablelist> | ||
47 | </refsect1> | ||
48 | |||
49 | <refsect1> | ||
50 | <title>Description</title> | ||
51 | |||
52 | <para>Subscribe or unsubscribe V4L2 event. Subscribed events are | ||
53 | dequeued by using the &VIDIOC-DQEVENT; ioctl.</para> | ||
54 | |||
55 | <table frame="none" pgwide="1" id="v4l2-event-subscription"> | ||
56 | <title>struct <structname>v4l2_event_subscription</structname></title> | ||
57 | <tgroup cols="3"> | ||
58 | &cs-str; | ||
59 | <tbody valign="top"> | ||
60 | <row> | ||
61 | <entry>__u32</entry> | ||
62 | <entry><structfield>type</structfield></entry> | ||
63 | <entry>Type of the event.</entry> | ||
64 | </row> | ||
65 | <row> | ||
66 | <entry>__u32</entry> | ||
67 | <entry><structfield>id</structfield></entry> | ||
68 | <entry>ID of the event source. If there is no ID associated with | ||
69 | the event source, then set this to 0. Whether or not an event | ||
70 | needs an ID depends on the event type.</entry> | ||
71 | </row> | ||
72 | <row> | ||
73 | <entry>__u32</entry> | ||
74 | <entry><structfield>flags</structfield></entry> | ||
75 | <entry>Event flags, see <xref linkend="event-flags" />.</entry> | ||
76 | </row> | ||
77 | <row> | ||
78 | <entry>__u32</entry> | ||
79 | <entry><structfield>reserved</structfield>[5]</entry> | ||
80 | <entry>Reserved for future extensions. Drivers and applications | ||
81 | must set the array to zero.</entry> | ||
82 | </row> | ||
83 | </tbody> | ||
84 | </tgroup> | ||
85 | </table> | ||
86 | |||
87 | <table frame="none" pgwide="1" id="event-type"> | ||
88 | <title>Event Types</title> | ||
89 | <tgroup cols="3"> | ||
90 | &cs-def; | ||
91 | <tbody valign="top"> | ||
92 | <row> | ||
93 | <entry><constant>V4L2_EVENT_ALL</constant></entry> | ||
94 | <entry>0</entry> | ||
95 | <entry>All events. V4L2_EVENT_ALL is valid only for | ||
96 | VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. | ||
97 | </entry> | ||
98 | </row> | ||
99 | <row> | ||
100 | <entry><constant>V4L2_EVENT_VSYNC</constant></entry> | ||
101 | <entry>1</entry> | ||
102 | <entry>This event is triggered on the vertical sync. | ||
103 | This event has a &v4l2-event-vsync; associated with it. | ||
104 | </entry> | ||
105 | </row> | ||
106 | <row> | ||
107 | <entry><constant>V4L2_EVENT_EOS</constant></entry> | ||
108 | <entry>2</entry> | ||
109 | <entry>This event is triggered when the end of a stream is reached. | ||
110 | This is typically used with MPEG decoders to report to the application | ||
111 | when the last of the MPEG stream has been decoded. | ||
112 | </entry> | ||
113 | </row> | ||
114 | <row> | ||
115 | <entry><constant>V4L2_EVENT_CTRL</constant></entry> | ||
116 | <entry>3</entry> | ||
117 | <entry><para>This event requires that the <structfield>id</structfield> | ||
118 | matches the control ID from which you want to receive events. | ||
119 | This event is triggered if the control's value changes, if a | ||
120 | button control is pressed or if the control's flags change. | ||
121 | This event has a &v4l2-event-ctrl; associated with it. This struct | ||
122 | contains much of the same information as &v4l2-queryctrl; and | ||
123 | &v4l2-control;.</para> | ||
124 | |||
125 | <para>If the event is generated due to a call to &VIDIOC-S-CTRL; or | ||
126 | &VIDIOC-S-EXT-CTRLS;, then the event will <emphasis>not</emphasis> be sent to | ||
127 | the file handle that called the ioctl function. This prevents | ||
128 | nasty feedback loops. If you <emphasis>do</emphasis> want to get the | ||
129 | event, then set the <constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant> | ||
130 | flag. | ||
131 | </para> | ||
132 | |||
133 | <para>This event type will ensure that no information is lost when | ||
134 | more events are raised than there is room internally. In that | ||
135 | case the &v4l2-event-ctrl; of the second-oldest event is kept, | ||
136 | but the <structfield>changes</structfield> field of the | ||
137 | second-oldest event is ORed with the <structfield>changes</structfield> | ||
138 | field of the oldest event.</para> | ||
139 | </entry> | ||
140 | </row> | ||
141 | <row> | ||
142 | <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> | ||
143 | <entry>0x08000000</entry> | ||
144 | <entry>Base event number for driver-private events.</entry> | ||
145 | </row> | ||
146 | </tbody> | ||
147 | </tgroup> | ||
148 | </table> | ||
149 | |||
150 | <table pgwide="1" frame="none" id="event-flags"> | ||
151 | <title>Event Flags</title> | ||
152 | <tgroup cols="3"> | ||
153 | &cs-def; | ||
154 | <tbody valign="top"> | ||
155 | <row> | ||
156 | <entry><constant>V4L2_EVENT_SUB_FL_SEND_INITIAL</constant></entry> | ||
157 | <entry>0x0001</entry> | ||
158 | <entry>When this event is subscribed an initial event will be sent | ||
159 | containing the current status. This only makes sense for events | ||
160 | that are triggered by a status change such as <constant>V4L2_EVENT_CTRL</constant>. | ||
161 | Other events will ignore this flag.</entry> | ||
162 | </row> | ||
163 | <row> | ||
164 | <entry><constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant></entry> | ||
165 | <entry>0x0002</entry> | ||
166 | <entry><para>If set, then events directly caused by an ioctl will also be sent to | ||
167 | the filehandle that called that ioctl. For example, changing a control using | ||
168 | &VIDIOC-S-CTRL; will cause a V4L2_EVENT_CTRL to be sent back to that same | ||
169 | filehandle. Normally such events are suppressed to prevent feedback loops | ||
170 | where an application changes a control to a one value and then another, and | ||
171 | then receives an event telling it that that control has changed to the first | ||
172 | value.</para> | ||
173 | |||
174 | <para>Since it can't tell whether that event was caused by another application | ||
175 | or by the &VIDIOC-S-CTRL; call it is hard to decide whether to set the | ||
176 | control to the value in the event, or ignore it.</para> | ||
177 | |||
178 | <para>Think carefully when you set this flag so you won't get into situations | ||
179 | like that.</para> | ||
180 | </entry> | ||
181 | </row> | ||
182 | </tbody> | ||
183 | </tgroup> | ||
184 | </table> | ||
185 | |||
186 | <table frame="none" pgwide="1" id="v4l2-event-vsync"> | ||
187 | <title>struct <structname>v4l2_event_vsync</structname></title> | ||
188 | <tgroup cols="3"> | ||
189 | &cs-str; | ||
190 | <tbody valign="top"> | ||
191 | <row> | ||
192 | <entry>__u8</entry> | ||
193 | <entry><structfield>field</structfield></entry> | ||
194 | <entry>The upcoming field. See &v4l2-field;.</entry> | ||
195 | </row> | ||
196 | </tbody> | ||
197 | </tgroup> | ||
198 | </table> | ||
199 | |||
200 | <table frame="none" pgwide="1" id="v4l2-event-ctrl"> | ||
201 | <title>struct <structname>v4l2_event_ctrl</structname></title> | ||
202 | <tgroup cols="4"> | ||
203 | &cs-str; | ||
204 | <tbody valign="top"> | ||
205 | <row> | ||
206 | <entry>__u32</entry> | ||
207 | <entry><structfield>changes</structfield></entry> | ||
208 | <entry></entry> | ||
209 | <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry> | ||
210 | </row> | ||
211 | <row> | ||
212 | <entry>__u32</entry> | ||
213 | <entry><structfield>type</structfield></entry> | ||
214 | <entry></entry> | ||
215 | <entry>The type of the control. See &v4l2-ctrl-type;.</entry> | ||
216 | </row> | ||
217 | <row> | ||
218 | <entry>union (anonymous)</entry> | ||
219 | <entry></entry> | ||
220 | <entry></entry> | ||
221 | <entry></entry> | ||
222 | </row> | ||
223 | <row> | ||
224 | <entry></entry> | ||
225 | <entry>__s32</entry> | ||
226 | <entry><structfield>value</structfield></entry> | ||
227 | <entry>The 32-bit value of the control for 32-bit control types. | ||
228 | This is 0 for string controls since the value of a string | ||
229 | cannot be passed using &VIDIOC-DQEVENT;.</entry> | ||
230 | </row> | ||
231 | <row> | ||
232 | <entry></entry> | ||
233 | <entry>__s64</entry> | ||
234 | <entry><structfield>value64</structfield></entry> | ||
235 | <entry>The 64-bit value of the control for 64-bit control types.</entry> | ||
236 | </row> | ||
237 | <row> | ||
238 | <entry>__u32</entry> | ||
239 | <entry><structfield>flags</structfield></entry> | ||
240 | <entry></entry> | ||
241 | <entry>The control flags. See <xref linkend="control-flags" />.</entry> | ||
242 | </row> | ||
243 | <row> | ||
244 | <entry>__s32</entry> | ||
245 | <entry><structfield>minimum</structfield></entry> | ||
246 | <entry></entry> | ||
247 | <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry> | ||
248 | </row> | ||
249 | <row> | ||
250 | <entry>__s32</entry> | ||
251 | <entry><structfield>maximum</structfield></entry> | ||
252 | <entry></entry> | ||
253 | <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry> | ||
254 | </row> | ||
255 | <row> | ||
256 | <entry>__s32</entry> | ||
257 | <entry><structfield>step</structfield></entry> | ||
258 | <entry></entry> | ||
259 | <entry>The step value of the control. See &v4l2-queryctrl;.</entry> | ||
260 | </row> | ||
261 | <row> | ||
262 | <entry>__s32</entry> | ||
263 | <entry><structfield>default_value</structfield></entry> | ||
264 | <entry></entry> | ||
265 | <entry>The default value value of the control. See &v4l2-queryctrl;.</entry> | ||
266 | </row> | ||
267 | </tbody> | ||
268 | </tgroup> | ||
269 | </table> | ||
270 | |||
271 | <table pgwide="1" frame="none" id="changes-flags"> | ||
272 | <title>Changes</title> | ||
273 | <tgroup cols="3"> | ||
274 | &cs-def; | ||
275 | <tbody valign="top"> | ||
276 | <row> | ||
277 | <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry> | ||
278 | <entry>0x0001</entry> | ||
279 | <entry>This control event was triggered because the value of the control | ||
280 | changed. Special case: if a button control is pressed, then this | ||
281 | event is sent as well, even though there is not explicit value | ||
282 | associated with a button control.</entry> | ||
283 | </row> | ||
284 | <row> | ||
285 | <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry> | ||
286 | <entry>0x0002</entry> | ||
287 | <entry>This control event was triggered because the control flags | ||
288 | changed.</entry> | ||
289 | </row> | ||
290 | </tbody> | ||
291 | </tgroup> | ||
292 | </table> | ||
293 | </refsect1> | ||
294 | <refsect1> | ||
295 | &return-value; | ||
296 | </refsect1> | ||
297 | </refentry> | ||