+2005-11-11 Wim Taymans <wim@fluendo.com>
+
+ * 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 <thomas at apestaart dot org>
* configure.ac: back to HEAD
<FILE>gstcollectpads</FILE>
<TITLE>GstCollectPads</TITLE>
<INCLUDE>gst/base/gstcollectpads.h</INCLUDE>
+GstCollectData
GstCollectPads
GstCollectPadsFunction
gst_collectpads_new
* 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);
* is given to the manager of this object when all pads have data.
* <itemizedlist>
* <listitem><para>
- * 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 ().
+ * </para></listitem>
+ * <listitem><para>
+ * 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.
* performing a pull_range.
* </para></listitem>
* <listitem><para>
- * When data is queued on all pads, a callback function is called.
+ * When data is queued on all pads, the callback function is called.
+ * </para></listitem>
+ * <listitem><para>
+ * 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.
+ * </para></listitem>
+ * <listitem><para>
+ * Data can also be dequeued in byte units using the gst_collectpads_available(),
+ * gst_collectpads_read() and gst_collectpads_flush() calls.
* </para></listitem>
* <listitem><para>
- * 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.
* </para></listitem>
* <listitem><para>
- * 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.
* </para></listitem>
* </itemizedlist>
*/
#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;
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)
#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;
gboolean started;
+ /*< private >*/
gpointer _gst_reserved[GST_PADDING];
};
* 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);
* is given to the manager of this object when all pads have data.
* <itemizedlist>
* <listitem><para>
- * 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 ().
+ * </para></listitem>
+ * <listitem><para>
+ * 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.
* performing a pull_range.
* </para></listitem>
* <listitem><para>
- * When data is queued on all pads, a callback function is called.
+ * When data is queued on all pads, the callback function is called.
+ * </para></listitem>
+ * <listitem><para>
+ * 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.
+ * </para></listitem>
+ * <listitem><para>
+ * Data can also be dequeued in byte units using the gst_collectpads_available(),
+ * gst_collectpads_read() and gst_collectpads_flush() calls.
* </para></listitem>
* <listitem><para>
- * 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.
* </para></listitem>
* <listitem><para>
- * 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.
* </para></listitem>
* </itemizedlist>
*/
#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;
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)
#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;
gboolean started;
+ /*< private >*/
gpointer _gst_reserved[GST_PADDING];
};
projects / platform / upstream / gstreamer.git / commitdiff