+2005-08-22 Stefan Kost <ensonic@users.sf.net>
+
+ * docs/gst/tmpl/gstevent.sgml:
+ * gst/gstevent.c:
+ * gst/gstevent.h:
+ inlined remaining docs, added missing doc comments
+
2005-08-22 Thomas Vander Stichele <thomas at apestaart dot org>
* check/gst/gstbin.c: (GST_START_TEST):
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GstEvent
-
-<!-- ##### SECTION Short_Description ##### -->
-Structure describing events that are passed up and down a pipeline
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The event classes are used to construct and query events.
-</para>
-
-<para>
-Events are usually created with gst_event_new() which takes the event type as an argument.
-properties specific to the event can be set afterwards with the provided macros.
-The event should be unreferenced with gst_event_unref().
-</para>
-<para>
-gst_event_new_seek() is a usually used to create a seek event and it takes the
-needed parameters for a seek event.
-</para>
-<para>
-gst_event_new_flush() creates a new flush event.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GstPad, #GstElement
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstEvent ##### -->
-<para>
-
-</para>
-
-@mini_object:
-@type:
-@timestamp:
-@src:
-@structure:
-
-<!-- ##### ENUM GstEventType ##### -->
-<para>
-
-</para>
-
-@GST_EVENT_UNKNOWN:
-@GST_EVENT_FLUSH_START:
-@GST_EVENT_FLUSH_STOP:
-@GST_EVENT_EOS:
-@GST_EVENT_NEWSEGMENT:
-@GST_EVENT_TAG:
-@GST_EVENT_FILLER:
-@GST_EVENT_QOS:
-@GST_EVENT_SEEK:
-@GST_EVENT_NAVIGATION:
-@GST_EVENT_CUSTOM_UP:
-@GST_EVENT_CUSTOM_DS:
-@GST_EVENT_CUSTOM_DS_OOB:
-@GST_EVENT_CUSTOM_BOTH:
-@GST_EVENT_CUSTOM_BOTH_OOB:
-
-<!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
-<para>
-The name used for memory allocation tracing
-</para>
-
-
-
-<!-- ##### MACRO GST_EVENT_TYPE ##### -->
-<para>
-Get the event type.
-</para>
-
-@event: The event to query.
-
-
-<!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
-<para>
-Get the timestamp of the event.
-</para>
-
-@event: The event to query.
-
-
-<!-- ##### MACRO GST_EVENT_SRC ##### -->
-<para>
-The source object that generated this event
-</para>
-
-@event: The event to query
-
-
-<!-- ##### ENUM GstSeekType ##### -->
-<para>
-The different types of seek events. When constructing a seek event a format,
-a seek method and optional flags are OR-ed together. The seek event is then
-inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
-
-Following example illustrates how to insert a seek event (1 second in the stream)
-in a pipeline.
-<example>
-<title>Insertion of a seek event into a pipeline</title>
- <programlisting>
- gboolean res;
- GstEvent *event;
-
- event = gst_event_new_seek (
- GST_FORMAT_TIME | /* seek on time */
- GST_SEEK_METHOD_SET | /* set the absolute position */
- GST_SEEK_FLAG_FLUSH, /* flush any pending data */
- 1 * GST_SECOND); /* the seek offset (1 second) */
-
- res = gst_element_send_event (GST_ELEMENT (osssink), event);
- if (!res) {
- g_warning ("seek failed");
- }
- </programlisting>
-</example>
-</para>
-
-@GST_SEEK_TYPE_NONE:
-@GST_SEEK_TYPE_CUR:
-@GST_SEEK_TYPE_SET:
-@GST_SEEK_TYPE_END:
-
-<!-- ##### MACRO gst_event_ref ##### -->
-<para>
-Increase the refcount of this event
-</para>
-
-@ev: The event to refcount
-
-
-<!-- ##### MACRO gst_event_unref ##### -->
-<para>
-Decrease the refcount of an event, freeing it if the refcount reaches 0
-</para>
-
-@ev: The event to unref
-
-
-<!-- ##### MACRO gst_event_copy ##### -->
-<para>
-Copy the event using the event specific copy function
-</para>
-
-@ev: The event to copy
-@Returns: A new event that is a copy of the given input event
-
-
-<!-- ##### FUNCTION gst_event_new_custom ##### -->
-<para>
-
-</para>
-
-@type:
-@structure:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_get_structure ##### -->
-<para>
-
-</para>
-
-@event:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_new_flush_start ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_new_flush_stop ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_new_eos ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_new_newsegment ##### -->
-<para>
-
-</para>
-
-@rate:
-@format:
-@start_value:
-@stop_value:
-@base:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_parse_newsegment ##### -->
-<para>
-
-</para>
-
-@event:
-@rate:
-@format:
-@start_value:
-@end_value:
-@base:
-
-
-<!-- ##### FUNCTION gst_event_new_tag ##### -->
-<para>
-
-</para>
-
-@taglist:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_parse_tag ##### -->
-<para>
-
-</para>
-
-@event:
-@taglist:
-
-
-<!-- ##### FUNCTION gst_event_new_filler ##### -->
-<para>
-Create a new dummy event that should be ignored
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_new_qos ##### -->
-<para>
-
-</para>
-
-@proportion:
-@diff:
-@timestamp:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_event_parse_qos ##### -->
-<para>
-
-</para>
-
-@event:
-@proportion:
-@diff:
-@timestamp:
-
-
-<!-- ##### FUNCTION gst_event_new_seek ##### -->
-<para>
-
-</para>
-
-@rate:
-@format:
-@flags:
-@cur_type:
-@cur:
-@stop_type:
-@stop:
-@Returns:
-<!-- # Unused Parameters # -->
-@type:
-@offset:
-
-
-<!-- ##### FUNCTION gst_event_parse_seek ##### -->
-<para>
-
-</para>
-
-@event:
-@rate:
-@format:
-@flags:
-@cur_type:
-@cur:
-@stop_type:
-@stop:
-
-
-<!-- ##### FUNCTION gst_event_new_navigation ##### -->
-<para>
-
-</para>
-
-@structure:
-@Returns:
-
-
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gstevent
+ * @short_description: Structure describing events that are passed up and down a pipeline
+ * @see_also: #GstPad, #GstElement
+ *
+ * The event classes are used to construct and query events.
+ *
+ * Events are usually created with gst_event_new() which takes the event type as
+ * an argument. Properties specific to the event can be set afterwards with the
+ * provided macros. The event should be unreferenced with gst_event_unref().
+ *
+ * gst_event_new_seek() is a usually used to create a seek event and it takes
+ * the needed parameters for a seek event.
+ *
+ * gst_event_new_flush() creates a new flush event.
+ */
#include <string.h> /* memcpy */
}
/* tag event */
+/**
+ * gst_event_new_tag:
+ * @taglist: metadata list
+ *
+ * Generates a metadata tag event from the given @taglist.
+ *
+ * Returns: a new #GstEvent
+ */
GstEvent *
gst_event_new_tag (GstTagList * taglist)
{
return gst_event_new_custom (GST_EVENT_TAG, (GstStructure *) taglist);
}
+/**
+ * gst_event_parse_tag:
+ * @event: a tag event
+ * @taglist: pointer to metadata list
+ *
+ * Parses a tag @event and stores the results in the given @taglist location.
+ */
void
gst_event_parse_tag (GstEvent * event, GstTagList ** taglist)
{
}
/* filler event */
+/**
+ * gst_event_new_filler:
+ *
+ * Create a new dummy event that should be ignored.
+ *
+ * Returns: a new #GstEvent
+ */
GstEvent *
gst_event_new_filler (void)
{
"stop", G_TYPE_INT64, stop, NULL));
}
+/**
+ * gst_event_parse_seek:
+ * @event: a seek event
+ * @rate: result location for the rate
+ * @format: result location for the stream format
+ * @flags: result location for the #GstSeekFlags
+ * @cur_type: result location for the #GstSeekType of the current position
+ * @cur: result location for the current postion expressed in @format
+ * @stop_type: result location for the #GstSeekType of the stop position
+ * @stop: result location for the stop postion expressed in @format
+ *
+ * Parses a seek @event and stores the results in the given result locations.
+ */
void
gst_event_parse_seek (GstEvent * event, gdouble * rate, GstFormat * format,
GstSeekFlags * flags,
}
/* navigation event */
+/**
+ * gst_event_new_navigation:
+ * @structure: description of the event
+ *
+ * Create a new navigation event from the given description.
+ *
+ * Returns: a new #GstEvent
+ */
GstEvent *
gst_event_new_navigation (GstStructure * structure)
{
} GstEventType;
/**
- * @The name used for memory allocation tracing
+ * GST_EVENT_TRACE_NAME:
+ * The name used for memory allocation tracing
*/
#define GST_EVENT_TRACE_NAME "GstEvent"
#define GST_EVENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_EVENT, GstEvent))
#define GST_EVENT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_EVENT, GstEventClass))
+/**
+ * GST_EVENT_TYPE:
+ * @event: the event to query
+ *
+ * Get the event type.
+ *
+ * Returns: the #GstEventType of the given event
+ */
#define GST_EVENT_TYPE(event) (GST_EVENT(event)->type)
+/**
+ * GST_EVENT_TIMESTAMP:
+ * @event: the event to query
+ *
+ * Get the timestamp of the event.
+ *
+ * Returns: the timestamp of the given event
+ */
#define GST_EVENT_TIMESTAMP(event) (GST_EVENT(event)->timestamp)
+/**
+ * GST_EVENT_SRC:
+ * @event: the event to query
+ *
+ * The source object that generated this event.
+ *
+ * Returns: the source #GstObject for the given event
+ */
#define GST_EVENT_SRC(event) (GST_EVENT(event)->src)
#define GST_EVENT_IS_UPSTREAM(ev) !!(GST_EVENT_TYPE (ev) & GST_EVDIR_US)
* @GST_SEEK_TYPE_CUR: change relative to current position
* @GST_SEEK_TYPE_SET: absolute position is requested
* @GST_SEEK_TYPE_END: relative position to duration is requested
+ *
+ * The different types of seek events. When constructing a seek event a format,
+ * a seek method and optional flags are OR-ed together. The seek event is then
+ * inserted into the graph with #gst_pad_send_event() or
+ * #gst_element_send_event().
+
+ * Following example illustrates how to insert a seek event (1 second in the stream)
+ * in a pipeline.
+ * <example>
+ * <title>Insertion of a seek event into a pipeline</title>
+ * <programlisting>
+ * gboolean res;
+ * GstEvent *event;
+ *
+ * event = gst_event_new_seek (
+ * GST_FORMAT_TIME | // seek on time
+ * GST_SEEK_METHOD_SET | // set the absolute position
+ * GST_SEEK_FLAG_FLUSH, // flush any pending data
+ * 1 * GST_SECOND); // the seek offset (1 second)
+ *
+ * res = gst_element_send_event (GST_ELEMENT (osssink), event);
+ * if (!res) {
+ * g_warning ("seek failed");
+ * }
+ * </programlisting>
+ * </example>
*/
typedef enum {
/* one of these */
* @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback
* of the segment completes, no EOS will be emmited but a
* SEGMENT_DONE message will be posted on the bus.
+ *
*/
typedef enum {
GST_SEEK_FLAG_NONE = 0,
void _gst_event_initialize (void);
GType gst_event_get_type (void);
+
/* refcounting */
+/**
+ * gst_event_ref:
+ * @ev: The event to refcount
+ *
+ * Increase the refcount of this event.
+ */
#define gst_event_ref(ev) GST_EVENT (gst_mini_object_ref (GST_MINI_OBJECT (ev)))
+/**
+ * gst_event_ref:
+ * @ev: The event to refcount
+ *
+ * Decrease the refcount of an event, freeing it if the refcount reaches 0.
+ */
#define gst_event_unref(ev) gst_mini_object_unref (GST_MINI_OBJECT (ev))
+
/* copy event */
+/**
+ * gst_event_copy:
+ * @ev: The event to copy
+ *
+ * Copy the event using the event specific copy function.
+ *
+ * Returns: A new event that is a copy of the given input event
+ */
#define gst_event_copy(ev) GST_EVENT (gst_mini_object_copy (GST_MINI_OBJECT (ev)))
/* custom event */
projects / platform / upstream / gstreamer.git / commitdiff