summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml')
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml206
1 files changed, 0 insertions, 206 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
deleted file mode 100644
index 5c70b61..0000000
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ /dev/null
@@ -1,206 +0,0 @@
-<refentry id="vidioc-subscribe-event">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refname>
- <refpurpose>Subscribe or unsubscribe event</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_event_subscription
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Subscribe or unsubscribe V4L2 event. Subscribed events are
- dequeued by using the &VIDIOC-DQEVENT; ioctl.</para>
-
- <table frame="none" pgwide="1" id="v4l2-event-subscription">
- <title>struct <structname>v4l2_event_subscription</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the event.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>ID of the event source. If there is no ID associated with
- the event source, then set this to 0. Whether or not an event
- needs an ID depends on the event type.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Event flags, see <xref linkend="event-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[5]</entry>
- <entry>Reserved for future extensions. Drivers and applications
- must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="event-type">
- <title>Event Types</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EVENT_ALL</constant></entry>
- <entry>0</entry>
- <entry>All events. V4L2_EVENT_ALL is valid only for
- VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_VSYNC</constant></entry>
- <entry>1</entry>
- <entry>This event is triggered on the vertical sync.
- This event has a &v4l2-event-vsync; associated with it.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_EOS</constant></entry>
- <entry>2</entry>
- <entry>This event is triggered when the end of a stream is reached.
- This is typically used with MPEG decoders to report to the application
- when the last of the MPEG stream has been decoded.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_CTRL</constant></entry>
- <entry>3</entry>
- <entry><para>This event requires that the <structfield>id</structfield>
- matches the control ID from which you want to receive events.
- This event is triggered if the control's value changes, if a
- button control is pressed or if the control's flags change.
- This event has a &v4l2-event-ctrl; associated with it. This struct
- contains much of the same information as &v4l2-queryctrl; and
- &v4l2-control;.</para>
-
- <para>If the event is generated due to a call to &VIDIOC-S-CTRL; or
- &VIDIOC-S-EXT-CTRLS;, then the event will <emphasis>not</emphasis> be sent to
- the file handle that called the ioctl function. This prevents
- nasty feedback loops. If you <emphasis>do</emphasis> want to get the
- event, then set the <constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant>
- flag.
- </para>
-
- <para>This event type will ensure that no information is lost when
- more events are raised than there is room internally. In that
- case the &v4l2-event-ctrl; of the second-oldest event is kept,
- but the <structfield>changes</structfield> field of the
- second-oldest event is ORed with the <structfield>changes</structfield>
- field of the oldest event.</para>
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
- <entry>4</entry>
- <entry>
- <para>Triggered immediately when the reception of a
- frame has begun. This event has a
- &v4l2-event-frame-sync; associated with it.</para>
-
- <para>If the hardware needs to be stopped in the case of a
- buffer underrun it might not be able to generate this event.
- In such cases the <structfield>frame_sequence</structfield>
- field in &v4l2-event-frame-sync; will not be incremented. This
- causes two consecutive frame sequence numbers to have n times
- frame interval in between them.</para>
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
- <entry>0x08000000</entry>
- <entry>Base event number for driver-private events.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="event-flags">
- <title>Event Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EVENT_SUB_FL_SEND_INITIAL</constant></entry>
- <entry>0x0001</entry>
- <entry>When this event is subscribed an initial event will be sent
- containing the current status. This only makes sense for events
- that are triggered by a status change such as <constant>V4L2_EVENT_CTRL</constant>.
- Other events will ignore this flag.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant></entry>
- <entry>0x0002</entry>
- <entry><para>If set, then events directly caused by an ioctl will also be sent to
- the filehandle that called that ioctl. For example, changing a control using
- &VIDIOC-S-CTRL; will cause a V4L2_EVENT_CTRL to be sent back to that same
- filehandle. Normally such events are suppressed to prevent feedback loops
- where an application changes a control to a one value and then another, and
- then receives an event telling it that that control has changed to the first
- value.</para>
-
- <para>Since it can't tell whether that event was caused by another application
- or by the &VIDIOC-S-CTRL; call it is hard to decide whether to set the
- control to the value in the event, or ignore it.</para>
-
- <para>Think carefully when you set this flag so you won't get into situations
- like that.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>