mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-18 14:26:43 +00:00
Code Issues 1 Projects Releases Wiki Activity

inlined remaining docs, added missing doc comments

Browse source 
Original commit message from CVS:
* docs/gst/tmpl/gstevent.sgml:
* gst/gstevent.c:
* gst/gstevent.h:
inlined remaining docs, added missing doc comments
This commit is contained in:
Stefan Kost 2005-08-22 10:37:02 +00:00
parent d961ea4c93
commit 33e36f56a4
4 changed files with 141 additions and 313 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
ChangeLog
View file

@ -1,3 +1,10 @@
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> 2005-08-22 Thomas Vander Stichele <thomas at apestaart dot org>
* check/gst/gstbin.c: (GST_START_TEST): * check/gst/gstbin.c: (GST_START_TEST):

312
docs/gst/tmpl/gstevent.sgml
View file

@ -1,312 +0,0 @@
<!-- ##### 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:

59
gst/gstevent.c
View file

@ -19,6 +19,22 @@
* Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA. * 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 */ #include <string.h> /* memcpy */
@ -330,6 +346,14 @@ gst_event_parse_newsegment (GstEvent * event, gdouble * rate,
} }
/* tag event */ /* tag event */
/**
* gst_event_new_tag:
* @taglist: metadata list
*
* Generates a metadata tag event from the given @taglist.
*
* Returns: a new #GstEvent
*/
GstEvent * GstEvent *
gst_event_new_tag (GstTagList * taglist) 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); 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 void
gst_event_parse_tag (GstEvent * event, GstTagList ** taglist) gst_event_parse_tag (GstEvent * event, GstTagList ** taglist)
{ {
@ -349,6 +380,13 @@ gst_event_parse_tag (GstEvent * event, GstTagList ** taglist)
} }
/* filler event */ /* filler event */
/**
* gst_event_new_filler:
*
* Create a new dummy event that should be ignored.
*
* Returns: a new #GstEvent
*/
GstEvent * GstEvent *
gst_event_new_filler (void) 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)); "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 void
gst_event_parse_seek (GstEvent * event, gdouble * rate, GstFormat * format, gst_event_parse_seek (GstEvent * event, gdouble * rate, GstFormat * format,
GstSeekFlags * flags, GstSeekFlags * flags,
@ -489,6 +540,14 @@ gst_event_parse_seek (GstEvent * event, gdouble * rate, GstFormat * format,
} }
/* navigation event */ /* 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 * GstEvent *
gst_event_new_navigation (GstStructure * structure) gst_event_new_navigation (GstStructure * structure)
{ {

76
gst/gstevent.h
View file

@ -97,7 +97,8 @@ typedef enum {
} GstEventType; } 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_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(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)) #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) #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) #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_SRC(event) (GST_EVENT(event)->src)
#define GST_EVENT_IS_UPSTREAM(ev) !!(GST_EVENT_TYPE (ev) & GST_EVDIR_US) #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_CUR: change relative to current position
* @GST_SEEK_TYPE_SET: absolute position is requested * @GST_SEEK_TYPE_SET: absolute position is requested
* @GST_SEEK_TYPE_END: relative position to duration 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 { typedef enum {
/* one of these */ /* one of these */
@ -145,6 +196,7 @@ typedef enum {
* @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback * @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback
* of the segment completes, no EOS will be emmited but a * of the segment completes, no EOS will be emmited but a
* SEGMENT_DONE message will be posted on the bus. * SEGMENT_DONE message will be posted on the bus.
*
*/ */
typedef enum { typedef enum {
GST_SEEK_FLAG_NONE = 0, GST_SEEK_FLAG_NONE = 0,
@ -178,10 +230,32 @@ struct _GstEventClass {
void _gst_event_initialize (void); void _gst_event_initialize (void);
GType gst_event_get_type (void); GType gst_event_get_type (void);
/* refcounting */ /* 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))) #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)) #define gst_event_unref(ev) gst_mini_object_unref (GST_MINI_OBJECT (ev))
/* copy event */ /* 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))) #define gst_event_copy(ev) GST_EVENT (gst_mini_object_copy (GST_MINI_OBJECT (ev)))
/* custom event */ /* custom event */