diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml | 36 |
1 files changed, 29 insertions, 7 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index 039a9694fd1..25471e8e5da 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml | |||
@@ -114,25 +114,28 @@ | |||
114 | <row> | 114 | <row> |
115 | <entry><constant>V4L2_EVENT_CTRL</constant></entry> | 115 | <entry><constant>V4L2_EVENT_CTRL</constant></entry> |
116 | <entry>3</entry> | 116 | <entry>3</entry> |
117 | <entry>This event requires that the <structfield>id</structfield> | 117 | <entry><para>This event requires that the <structfield>id</structfield> |
118 | matches the control ID from which you want to receive events. | 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 | 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. | 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 | 121 | This event has a &v4l2-event-ctrl; associated with it. This struct |
122 | contains much of the same information as &v4l2-queryctrl; and | 122 | contains much of the same information as &v4l2-queryctrl; and |
123 | &v4l2-control;. | 123 | &v4l2-control;.</para> |
124 | 124 | ||
125 | If the event is generated due to a call to &VIDIOC-S-CTRL; or | 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 not be sent to | 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 | 127 | the file handle that called the ioctl function. This prevents |
128 | nasty feedback loops. | 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> | ||
129 | 132 | ||
130 | This event type will ensure that no information is lost when | 133 | <para>This event type will ensure that no information is lost when |
131 | more events are raised than there is room internally. In that | 134 | more events are raised than there is room internally. In that |
132 | case the &v4l2-event-ctrl; of the second-oldest event is kept, | 135 | case the &v4l2-event-ctrl; of the second-oldest event is kept, |
133 | but the <structfield>changes</structfield> field of the | 136 | but the <structfield>changes</structfield> field of the |
134 | second-oldest event is ORed with the <structfield>changes</structfield> | 137 | second-oldest event is ORed with the <structfield>changes</structfield> |
135 | field of the oldest event. | 138 | field of the oldest event.</para> |
136 | </entry> | 139 | </entry> |
137 | </row> | 140 | </row> |
138 | <row> | 141 | <row> |
@@ -157,6 +160,25 @@ | |||
157 | that are triggered by a status change such as <constant>V4L2_EVENT_CTRL</constant>. | 160 | that are triggered by a status change such as <constant>V4L2_EVENT_CTRL</constant>. |
158 | Other events will ignore this flag.</entry> | 161 | Other events will ignore this flag.</entry> |
159 | </row> | 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> | ||
160 | </tbody> | 182 | </tbody> |
161 | </tgroup> | 183 | </tgroup> |
162 | </table> | 184 | </table> |