From: Wim Taymans Date: Fri, 11 Nov 2005 20:12:42 +0000 (+0000) Subject: docs/gst/gstreamer-sections.txt: Added some docs for GstCollectData. X-Git-Tag: RELEASE-0_9_6~150 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b2ff4bd74759a1b48cefe55ef244c8d33a438d91;p=platform%2Fupstream%2Fgstreamer.git docs/gst/gstreamer-sections.txt: Added some docs for GstCollectData. Original commit message from CVS: * docs/gst/gstreamer-sections.txt: Added some docs for GstCollectData. * gst/base/gstadapter.c: Some small code example fix. * gst/base/gstcollectpads.c: * gst/base/gstcollectpads.h: Document some more. --- diff --git a/ChangeLog b/ChangeLog index 30e7918..d7f373c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2005-11-11 Wim Taymans + + * docs/gst/gstreamer-sections.txt: + Added some docs for GstCollectData. + + * gst/base/gstadapter.c: + Some small code example fix. + + * gst/base/gstcollectpads.c: + * gst/base/gstcollectpads.h: + Document some more. + 2005-11-11 Thomas Vander Stichele * configure.ac: back to HEAD diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index efded67..968dbfb 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -2308,6 +2308,7 @@ gst_base_transform_get_type gstcollectpads GstCollectPads gst/base/gstcollectpads.h +GstCollectData GstCollectPads GstCollectPadsFunction gst_collectpads_new diff --git a/gst/base/gstadapter.c b/gst/base/gstadapter.c index b6d7c10..6c8720a 100644 --- a/gst/base/gstadapter.c +++ b/gst/base/gstadapter.c @@ -42,14 +42,14 @@ * GstAdapter *adapter; * GstFlowReturn ret = GST_FLOW_OK; * - * // will give the element an extra ref; remember to drop it + * // will give the element an extra ref; remember to drop it * this = MY_ELEMENT (gst_pad_get_parent (pad)); * adapter = this->adapter; * * // put buffer into adapter * #gst_adapter_push (adapter, buffer); * // while we can read out 512 bytes, process them - * while (#gst_adapter_available (adapter) >= 512 && fret == GST_FLOW_OK) { + * while (#gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) { * // use flowreturn as an error value * ret = my_library_foo (#gst_adapter_peek (adapter, 512)); * #gst_adapter_flush (adapter, 512); diff --git a/gst/base/gstcollectpads.c b/gst/base/gstcollectpads.c index 0611b43..b67b94f 100644 --- a/gst/base/gstcollectpads.c +++ b/gst/base/gstcollectpads.c @@ -27,7 +27,12 @@ * is given to the manager of this object when all pads have data. * * - * Pads are added to the collection with add/remove_pad. The pad + * Collectpads are created with gst_collectpads_new(). A callback should then + * be installed with gst_collectpads_set_function (). + * + * + * Pads are added to the collection with gst_collectpads_add_pad()/ + * gst_collectpads_remove_pad(). The pad * has to be a sinkpad. The chain function of the pad is * overridden. The element_private of the pad is used to store * private information. @@ -37,14 +42,29 @@ * performing a pull_range. * * - * When data is queued on all pads, a callback function is called. + * When data is queued on all pads, the callback function is called. + * + * + * Data can be dequeued from the pad with the gst_collectpads_pop() method. + * One can peek at the data with the gst_collectpads_peek() function. + * These functions will return NULL if the pad received an EOS event. When all + * pads return NULL from a gst_collectpads_peek(), the element can emit an EOS + * event itself. + * + * + * Data can also be dequeued in byte units using the gst_collectpads_available(), + * gst_collectpads_read() and gst_collectpads_flush() calls. * * - * Data can be dequeued from the pad with the _pop() method. - * One can _peek() at the data with the peek function. + * Elements should call gst_collectpads_start() and gst_collectpads_stop() in + * their state change functions to start and stop the processing of the collecpads. + * The gst_collectpads_stop() call should be called before calling the parent + * element state change function in the PAUSED_TO_READY state change to ensure + * no pad is blocked and the element can finish streaming. * * - * Data can also be dequeued with the available/read/flush calls. + * gst_collectpads_collect() and gst_collectpads_collect_range() can be used by + * elements that start a #GstTask to drive the collectpads. * * */ diff --git a/gst/base/gstcollectpads.h b/gst/base/gstcollectpads.h index a14f0b8..f857de0 100644 --- a/gst/base/gstcollectpads.h +++ b/gst/base/gstcollectpads.h @@ -33,10 +33,23 @@ G_BEGIN_DECLS #define GST_IS_COLLECTPADS(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_COLLECTPADS)) #define GST_IS_COLLECTPADS_CLASS(obj) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_COLLECTPADS)) +typedef struct _GstCollectData GstCollectData; typedef struct _GstCollectPads GstCollectPads; typedef struct _GstCollectPadsClass GstCollectPadsClass; -typedef struct _GstCollectData +/** + * GstCollectData: + * @collect: owner #GstCollectPads + * @pad: #GstPad managed by this data + * @buffer: currently queued buffer. + * @pos: position in the buffer + * @segment_start: last segment start received. + * @segment_stop: last segment stop received. + * @stream_time: stream time of last segment. + * + * Structure used by the collectpads. + */ +struct _GstCollectData { GstCollectPads *collect; GstPad *pad; @@ -45,9 +58,17 @@ typedef struct _GstCollectData gint64 segment_start; gint64 segment_stop; gint64 stream_time; -} GstCollectData; +}; -/* function will be called when all pads have data */ +/** + * GstCollectPadsFunction: + * @pads: the #GstCollectPads that trigered the callback + * @user_data: user data passed to gst_collectpads_set_function() + * + * A function that will be called when all pads have received data. + * + * Returns: GST_FLOW_OK for success + */ typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer user_data); #define GST_COLLECTPADS_GET_COND(pads) (((GstCollectPads *)pads)->cond) @@ -55,16 +76,23 @@ typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer #define GST_COLLECTPADS_SIGNAL(pads) (g_cond_signal (GST_COLLECTPADS_GET_COND (pads))) #define GST_COLLECTPADS_BROADCAST(pads)(g_cond_broadcast (GST_COLLECTPADS_GET_COND (pads))) +/** + * GstCollectPads: + * @data: #GList of #GstCollectData managed by this #GstCollectPads. + * + * Collectpads object. + */ struct _GstCollectPads { GstObject object; /*< public >*/ /* with LOCK */ - GSList *data; /* GstCollectData in this collection */ + GSList *data; + + /*< private >*/ guint32 cookie; GCond *cond; /* to signal removal of data */ - /*< private >*/ GstCollectPadsFunction func; /* function and user_data for callback */ gpointer user_data; @@ -74,6 +102,7 @@ struct _GstCollectPads { gboolean started; + /*< private >*/ gpointer _gst_reserved[GST_PADDING]; }; diff --git a/libs/gst/base/gstadapter.c b/libs/gst/base/gstadapter.c index b6d7c10..6c8720a 100644 --- a/libs/gst/base/gstadapter.c +++ b/libs/gst/base/gstadapter.c @@ -42,14 +42,14 @@ * GstAdapter *adapter; * GstFlowReturn ret = GST_FLOW_OK; * - * // will give the element an extra ref; remember to drop it + * // will give the element an extra ref; remember to drop it * this = MY_ELEMENT (gst_pad_get_parent (pad)); * adapter = this->adapter; * * // put buffer into adapter * #gst_adapter_push (adapter, buffer); * // while we can read out 512 bytes, process them - * while (#gst_adapter_available (adapter) >= 512 && fret == GST_FLOW_OK) { + * while (#gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) { * // use flowreturn as an error value * ret = my_library_foo (#gst_adapter_peek (adapter, 512)); * #gst_adapter_flush (adapter, 512); diff --git a/libs/gst/base/gstcollectpads.c b/libs/gst/base/gstcollectpads.c index 0611b43..b67b94f 100644 --- a/libs/gst/base/gstcollectpads.c +++ b/libs/gst/base/gstcollectpads.c @@ -27,7 +27,12 @@ * is given to the manager of this object when all pads have data. * * - * Pads are added to the collection with add/remove_pad. The pad + * Collectpads are created with gst_collectpads_new(). A callback should then + * be installed with gst_collectpads_set_function (). + * + * + * Pads are added to the collection with gst_collectpads_add_pad()/ + * gst_collectpads_remove_pad(). The pad * has to be a sinkpad. The chain function of the pad is * overridden. The element_private of the pad is used to store * private information. @@ -37,14 +42,29 @@ * performing a pull_range. * * - * When data is queued on all pads, a callback function is called. + * When data is queued on all pads, the callback function is called. + * + * + * Data can be dequeued from the pad with the gst_collectpads_pop() method. + * One can peek at the data with the gst_collectpads_peek() function. + * These functions will return NULL if the pad received an EOS event. When all + * pads return NULL from a gst_collectpads_peek(), the element can emit an EOS + * event itself. + * + * + * Data can also be dequeued in byte units using the gst_collectpads_available(), + * gst_collectpads_read() and gst_collectpads_flush() calls. * * - * Data can be dequeued from the pad with the _pop() method. - * One can _peek() at the data with the peek function. + * Elements should call gst_collectpads_start() and gst_collectpads_stop() in + * their state change functions to start and stop the processing of the collecpads. + * The gst_collectpads_stop() call should be called before calling the parent + * element state change function in the PAUSED_TO_READY state change to ensure + * no pad is blocked and the element can finish streaming. * * - * Data can also be dequeued with the available/read/flush calls. + * gst_collectpads_collect() and gst_collectpads_collect_range() can be used by + * elements that start a #GstTask to drive the collectpads. * * */ diff --git a/libs/gst/base/gstcollectpads.h b/libs/gst/base/gstcollectpads.h index a14f0b8..f857de0 100644 --- a/libs/gst/base/gstcollectpads.h +++ b/libs/gst/base/gstcollectpads.h @@ -33,10 +33,23 @@ G_BEGIN_DECLS #define GST_IS_COLLECTPADS(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_COLLECTPADS)) #define GST_IS_COLLECTPADS_CLASS(obj) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_COLLECTPADS)) +typedef struct _GstCollectData GstCollectData; typedef struct _GstCollectPads GstCollectPads; typedef struct _GstCollectPadsClass GstCollectPadsClass; -typedef struct _GstCollectData +/** + * GstCollectData: + * @collect: owner #GstCollectPads + * @pad: #GstPad managed by this data + * @buffer: currently queued buffer. + * @pos: position in the buffer + * @segment_start: last segment start received. + * @segment_stop: last segment stop received. + * @stream_time: stream time of last segment. + * + * Structure used by the collectpads. + */ +struct _GstCollectData { GstCollectPads *collect; GstPad *pad; @@ -45,9 +58,17 @@ typedef struct _GstCollectData gint64 segment_start; gint64 segment_stop; gint64 stream_time; -} GstCollectData; +}; -/* function will be called when all pads have data */ +/** + * GstCollectPadsFunction: + * @pads: the #GstCollectPads that trigered the callback + * @user_data: user data passed to gst_collectpads_set_function() + * + * A function that will be called when all pads have received data. + * + * Returns: GST_FLOW_OK for success + */ typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer user_data); #define GST_COLLECTPADS_GET_COND(pads) (((GstCollectPads *)pads)->cond) @@ -55,16 +76,23 @@ typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer #define GST_COLLECTPADS_SIGNAL(pads) (g_cond_signal (GST_COLLECTPADS_GET_COND (pads))) #define GST_COLLECTPADS_BROADCAST(pads)(g_cond_broadcast (GST_COLLECTPADS_GET_COND (pads))) +/** + * GstCollectPads: + * @data: #GList of #GstCollectData managed by this #GstCollectPads. + * + * Collectpads object. + */ struct _GstCollectPads { GstObject object; /*< public >*/ /* with LOCK */ - GSList *data; /* GstCollectData in this collection */ + GSList *data; + + /*< private >*/ guint32 cookie; GCond *cond; /* to signal removal of data */ - /*< private >*/ GstCollectPadsFunction func; /* function and user_data for callback */ gpointer user_data; @@ -74,6 +102,7 @@ struct _GstCollectPads { gboolean started; + /*< private >*/ gpointer _gst_reserved[GST_PADDING]; };