From 33e36f56a422c0fbe4b7c6e594e86547965011cf Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Mon, 22 Aug 2005 10:37:02 +0000 Subject: [PATCH] inlined remaining docs, added missing doc comments Original commit message from CVS: * docs/gst/tmpl/gstevent.sgml: * gst/gstevent.c: * gst/gstevent.h: inlined remaining docs, added missing doc comments --- ChangeLog | 7 + docs/gst/tmpl/gstevent.sgml | 312 ------------------------------------ gst/gstevent.c | 59 +++++++ gst/gstevent.h | 76 ++++++++- 4 files changed, 141 insertions(+), 313 deletions(-) delete mode 100644 docs/gst/tmpl/gstevent.sgml diff --git a/ChangeLog b/ChangeLog index 6e1cae2da8..594f7e255d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2005-08-22 Stefan Kost + + * docs/gst/tmpl/gstevent.sgml: + * gst/gstevent.c: + * gst/gstevent.h: + inlined remaining docs, added missing doc comments + 2005-08-22 Thomas Vander Stichele * check/gst/gstbin.c: (GST_START_TEST): diff --git a/docs/gst/tmpl/gstevent.sgml b/docs/gst/tmpl/gstevent.sgml deleted file mode 100644 index 42061fce1c..0000000000 --- a/docs/gst/tmpl/gstevent.sgml +++ /dev/null @@ -1,312 +0,0 @@ - -GstEvent - - -Structure describing events that are passed up and down a pipeline - - - -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. - - - - -#GstPad, #GstElement - - - - - - - - - - -@mini_object: -@type: -@timestamp: -@src: -@structure: - - - - - - -@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: - - - -The name used for memory allocation tracing - - - - - - -Get the event type. - - -@event: The event to query. - - - - -Get the timestamp of the event. - - -@event: The event to query. - - - - -The source object that generated this event - - -@event: The event to query - - - - -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. - -Insertion of a seek event into a pipeline - - 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"); - } - - - - -@GST_SEEK_TYPE_NONE: -@GST_SEEK_TYPE_CUR: -@GST_SEEK_TYPE_SET: -@GST_SEEK_TYPE_END: - - - -Increase the refcount of this event - - -@ev: The event to refcount - - - - -Decrease the refcount of an event, freeing it if the refcount reaches 0 - - -@ev: The event to unref - - - - -Copy the event using the event specific copy function - - -@ev: The event to copy -@Returns: A new event that is a copy of the given input event - - - - - - - -@type: -@structure: -@Returns: - - - - - - - -@event: -@Returns: - - - - - - - -@Returns: - - - - - - - -@Returns: - - - - - - - -@Returns: - - - - - - - -@rate: -@format: -@start_value: -@stop_value: -@base: -@Returns: - - - - - - - -@event: -@rate: -@format: -@start_value: -@end_value: -@base: - - - - - - - -@taglist: -@Returns: - - - - - - - -@event: -@taglist: - - - - -Create a new dummy event that should be ignored - - -@Returns: - - - - - - - -@proportion: -@diff: -@timestamp: -@Returns: - - - - - - - -@event: -@proportion: -@diff: -@timestamp: - - - - - - - -@rate: -@format: -@flags: -@cur_type: -@cur: -@stop_type: -@stop: -@Returns: - -@type: -@offset: - - - - - - - -@event: -@rate: -@format: -@flags: -@cur_type: -@cur: -@stop_type: -@stop: - - - - - - - -@structure: -@Returns: - - diff --git a/gst/gstevent.c b/gst/gstevent.c index fd5571d653..39632a5ac0 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -19,6 +19,22 @@ * 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 /* memcpy */ @@ -330,6 +346,14 @@ gst_event_parse_newsegment (GstEvent * event, gdouble * rate, } /* 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) { @@ -338,6 +362,13 @@ 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) { @@ -349,6 +380,13 @@ 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) { @@ -458,6 +496,19 @@ gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags, "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, @@ -489,6 +540,14 @@ gst_event_parse_seek (GstEvent * event, gdouble * rate, GstFormat * format, } /* 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) { diff --git a/gst/gstevent.h b/gst/gstevent.h index ca7331c7ae..f4e98998f2 100644 --- a/gst/gstevent.h +++ b/gst/gstevent.h @@ -97,7 +97,8 @@ typedef enum { } 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" @@ -111,8 +112,32 @@ typedef struct _GstEventClass GstEventClass; #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) @@ -125,6 +150,32 @@ typedef struct _GstEventClass GstEventClass; * @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. + * + * Insertion of a seek event into a pipeline + * + * 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"); + * } + * + * */ typedef enum { /* one of these */ @@ -145,6 +196,7 @@ typedef enum { * @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, @@ -178,10 +230,32 @@ struct _GstEventClass { 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 */