2 * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
22 * SECTION:gstcollectpads
23 * @short_description: manages a set of pads that operate in collect mode
26 * Manages a set of pads that operate in collect mode. This means that control
27 * is given to the manager of this object when all pads have data.
30 * Collectpads are created with gst_collect_pads_new(). A callback should then
31 * be installed with gst_collect_pads_set_function ().
34 * Pads are added to the collection with gst_collect_pads_add_pad()/
35 * gst_collect_pads_remove_pad(). The pad
36 * has to be a sinkpad. The chain and event functions of the pad are
37 * overridden. The element_private of the pad is used to store
38 * private information for the collectpads.
41 * For each pad, data is queued in the _chain function or by
42 * performing a pull_range.
45 * When data is queued on all pads, the callback function is called.
48 * Data can be dequeued from the pad with the gst_collect_pads_pop() method.
49 * One can peek at the data with the gst_collect_pads_peek() function.
50 * These functions will return NULL if the pad received an EOS event. When all
51 * pads return NULL from a gst_collect_pads_peek(), the element can emit an EOS
55 * Data can also be dequeued in byte units using the gst_collect_pads_available(),
56 * gst_collect_pads_read() and gst_collect_pads_flush() calls.
59 * Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in
60 * their state change functions to start and stop the processing of the collecpads.
61 * The gst_collect_pads_stop() call should be called before calling the parent
62 * element state change function in the PAUSED_TO_READY state change to ensure
63 * no pad is blocked and the element can finish streaming.
66 * gst_collect_pads_collect() and gst_collect_pads_collect_range() can be used by
67 * elements that start a #GstTask to drive the collect_pads. This feature is however
68 * not yet implemented.
72 * Last reviewed on 2006-05-10 (0.10.6)
75 #include "gstcollectpads.h"
76 #include "gst/glib-compat-private.h"
78 GST_DEBUG_CATEGORY_STATIC (collect_pads_debug);
79 #define GST_CAT_DEFAULT collect_pads_debug
81 #define GST_COLLECT_PADS_GET_PRIVATE(obj) \
82 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_COLLECT_PADS, GstCollectPadsPrivate))
84 struct _GstCollectPadsPrivate
86 GstCollectPadsClipFunction clipfunc;
87 gpointer clipfunc_user_data;
90 #define gst_collect_pads_parent_class parent_class
91 G_DEFINE_TYPE (GstCollectPads, gst_collect_pads, GST_TYPE_OBJECT);
93 static void gst_collect_pads_clear (GstCollectPads * pads,
94 GstCollectData * data);
95 static GstFlowReturn gst_collect_pads_chain (GstPad * pad, GstObject * parent,
97 static gboolean gst_collect_pads_event (GstPad * pad, GstObject * parent,
99 static void gst_collect_pads_finalize (GObject * object);
100 static void ref_data (GstCollectData * data);
101 static void unref_data (GstCollectData * data);
102 static void gst_collect_pads_check_pads_unlocked (GstCollectPads * pads);
105 gst_collect_pads_class_init (GstCollectPadsClass * klass)
107 GObjectClass *gobject_class = (GObjectClass *) klass;
109 g_type_class_add_private (klass, sizeof (GstCollectPadsPrivate));
111 GST_DEBUG_CATEGORY_INIT (collect_pads_debug, "collectpads", 0,
114 gobject_class->finalize = gst_collect_pads_finalize;
118 gst_collect_pads_init (GstCollectPads * pads)
120 pads->priv = GST_COLLECT_PADS_GET_PRIVATE (pads);
122 g_cond_init (&pads->cond);
126 pads->queuedpads = 0;
128 pads->started = FALSE;
130 /* members to manage the pad list */
131 g_mutex_init (&pads->pad_lock);
132 pads->pad_cookie = 0;
133 pads->pad_list = NULL;
137 gst_collect_pads_finalize (GObject * object)
140 GstCollectPads *pads = GST_COLLECT_PADS (object);
142 GST_DEBUG ("finalize");
144 g_cond_clear (&pads->cond);
145 g_mutex_clear (&pads->pad_lock);
148 collected = pads->pad_list;
149 for (; collected; collected = g_slist_next (collected)) {
150 GstCollectData *pdata = (GstCollectData *) collected->data;
155 g_slist_foreach (pads->data, (GFunc) unref_data, NULL);
156 g_slist_free (pads->data);
157 g_slist_free (pads->pad_list);
159 G_OBJECT_CLASS (parent_class)->finalize (object);
163 * gst_collect_pads_new:
165 * Create a new instance of #GstCollectPads.
169 * Returns: (transfer full): a new #GstCollectPads, or NULL in case of an error.
172 gst_collect_pads_new (void)
174 GstCollectPads *newcoll;
176 newcoll = g_object_newv (GST_TYPE_COLLECT_PADS, 0, NULL);
182 * gst_collect_pads_set_function:
183 * @pads: the collectspads to use
184 * @func: the function to set
185 * @user_data: (closure): user data passed to the function
187 * Set the callback function and user data that will be called when
188 * all the pads added to the collection have buffers queued.
193 gst_collect_pads_set_function (GstCollectPads * pads,
194 GstCollectPadsFunction func, gpointer user_data)
196 g_return_if_fail (pads != NULL);
197 g_return_if_fail (GST_IS_COLLECT_PADS (pads));
199 GST_OBJECT_LOCK (pads);
201 pads->user_data = user_data;
202 GST_OBJECT_UNLOCK (pads);
206 ref_data (GstCollectData * data)
208 g_assert (data != NULL);
210 g_atomic_int_inc (&(data->refcount));
214 unref_data (GstCollectData * data)
216 g_assert (data != NULL);
217 g_assert (data->refcount > 0);
219 if (!g_atomic_int_dec_and_test (&(data->refcount)))
222 if (data->destroy_notify)
223 data->destroy_notify (data);
224 g_object_unref (data->pad);
226 gst_buffer_unref (data->buffer);
231 * gst_collect_pads_add_pad:
232 * @pads: the collectspads to use
233 * @pad: (transfer none): the pad to add
234 * @size: the size of the returned #GstCollectData structure
235 * @destroy_notify: function to be called before the returned #GstCollectData
238 * Add a pad to the collection of collect pads. The pad has to be
239 * a sinkpad. The refcount of the pad is incremented. Use
240 * gst_collect_pads_remove_pad() to remove the pad from the collection
243 * You specify a size for the returned #GstCollectData structure
244 * so that you can use it to store additional information.
246 * You can also specify a #GstCollectDataDestroyNotify that will be called
247 * just before the #GstCollectData structure is freed. It is passed the
248 * pointer to the structure and should free any custom memory and resources
251 * The pad will be automatically activated in push mode when @pads is
256 * Returns: a new #GstCollectData to identify the new pad. Or NULL
257 * if wrong parameters are supplied.
260 gst_collect_pads_add_pad (GstCollectPads * pads, GstPad * pad, guint size,
261 GstCollectDataDestroyNotify destroy_notify)
263 GstCollectData *data;
265 g_return_val_if_fail (pads != NULL, NULL);
266 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), NULL);
267 g_return_val_if_fail (pad != NULL, NULL);
268 g_return_val_if_fail (GST_PAD_IS_SINK (pad), NULL);
269 g_return_val_if_fail (size >= sizeof (GstCollectData), NULL);
271 GST_DEBUG ("adding pad %s:%s", GST_DEBUG_PAD_NAME (pad));
273 data = g_malloc0 (size);
274 data->collect = pads;
275 data->pad = gst_object_ref (pad);
278 gst_segment_init (&data->segment, GST_FORMAT_UNDEFINED);
279 data->flushing = FALSE;
280 data->new_segment = FALSE;
283 data->destroy_notify = destroy_notify;
285 GST_COLLECT_PADS_PAD_LOCK (pads);
286 GST_OBJECT_LOCK (pad);
287 gst_pad_set_element_private (pad, data);
288 GST_OBJECT_UNLOCK (pad);
289 pads->pad_list = g_slist_append (pads->pad_list, data);
290 gst_pad_set_chain_function (pad, GST_DEBUG_FUNCPTR (gst_collect_pads_chain));
291 gst_pad_set_event_function (pad, GST_DEBUG_FUNCPTR (gst_collect_pads_event));
292 /* activate the pad when needed */
294 gst_pad_set_active (pad, TRUE);
296 GST_COLLECT_PADS_PAD_UNLOCK (pads);
302 find_pad (GstCollectData * data, GstPad * pad)
304 if (data->pad == pad)
310 * gst_collect_pads_set_clip_function:
311 * @pads: the collectspads to use
312 * @clipfunc: clip function to install
313 * @user_data: (closure): user data to pass to @clip_func
315 * Install a clipping function that is called right after a buffer is received
316 * on a pad managed by @pads. See #GstCollectPadsClipFunction for more info.
321 gst_collect_pads_set_clip_function (GstCollectPads * pads,
322 GstCollectPadsClipFunction clipfunc, gpointer user_data)
324 GstCollectPadsPrivate *priv;
326 g_return_if_fail (pads != NULL);
327 g_return_if_fail (GST_IS_COLLECT_PADS (pads));
331 priv->clipfunc = clipfunc;
332 priv->clipfunc_user_data = user_data;
336 * gst_collect_pads_remove_pad:
337 * @pads: the collectspads to use
338 * @pad: (transfer none): the pad to remove
340 * Remove a pad from the collection of collect pads. This function will also
341 * free the #GstCollectData and all the resources that were allocated with
342 * gst_collect_pads_add_pad().
344 * The pad will be deactivated automatically when @pads is stopped.
348 * Returns: %TRUE if the pad could be removed.
351 gst_collect_pads_remove_pad (GstCollectPads * pads, GstPad * pad)
353 GstCollectData *data;
356 g_return_val_if_fail (pads != NULL, FALSE);
357 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), FALSE);
358 g_return_val_if_fail (pad != NULL, FALSE);
359 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
361 GST_DEBUG ("removing pad %s:%s", GST_DEBUG_PAD_NAME (pad));
363 GST_COLLECT_PADS_PAD_LOCK (pads);
364 list = g_slist_find_custom (pads->pad_list, pad, (GCompareFunc) find_pad);
368 data = (GstCollectData *) list->data;
370 GST_DEBUG ("found pad %s:%s at %p", GST_DEBUG_PAD_NAME (pad), data);
372 /* clear the stuff we configured */
373 gst_pad_set_chain_function (pad, NULL);
374 gst_pad_set_event_function (pad, NULL);
375 GST_OBJECT_LOCK (pad);
376 gst_pad_set_element_private (pad, NULL);
377 GST_OBJECT_UNLOCK (pad);
379 /* backward compat, also remove from data if stopped, note that this function
380 * can only be called when we are stopped because we don't take the LOCK to
381 * protect the pads->data list. */
382 if (!pads->started) {
385 dlist = g_slist_find_custom (pads->data, pad, (GCompareFunc) find_pad);
387 GstCollectData *pdata = dlist->data;
389 pads->data = g_slist_delete_link (pads->data, dlist);
393 /* remove from the pad list */
394 pads->pad_list = g_slist_delete_link (pads->pad_list, list);
397 /* signal waiters because something changed */
398 GST_COLLECT_PADS_BROADCAST (pads);
400 /* deactivate the pad when needed */
402 gst_pad_set_active (pad, FALSE);
404 /* clean and free the collect data */
407 GST_COLLECT_PADS_PAD_UNLOCK (pads);
413 GST_WARNING ("cannot remove unknown pad %s:%s", GST_DEBUG_PAD_NAME (pad));
414 GST_COLLECT_PADS_PAD_UNLOCK (pads);
420 * gst_collect_pads_is_active:
421 * @pads: (transfer none): the collectspads to use
422 * @pad: the pad to check
424 * Check if a pad is active.
426 * This function is currently not implemented.
430 * Returns: %TRUE if the pad is active.
433 gst_collect_pads_is_active (GstCollectPads * pads, GstPad * pad)
435 g_return_val_if_fail (pads != NULL, FALSE);
436 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), FALSE);
437 g_return_val_if_fail (pad != NULL, FALSE);
438 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
440 g_warning ("gst_collect_pads_is_active() is not implemented");
446 * gst_collect_pads_collect:
447 * @pads: the collectspads to use
449 * Collect data on all pads. This function is usually called
450 * from a #GstTask function in an element.
452 * This function is currently not implemented.
456 * Returns: #GstFlowReturn of the operation.
459 gst_collect_pads_collect (GstCollectPads * pads)
461 g_return_val_if_fail (pads != NULL, GST_FLOW_ERROR);
462 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), GST_FLOW_ERROR);
464 g_warning ("gst_collect_pads_collect() is not implemented");
466 return GST_FLOW_NOT_SUPPORTED;
470 * gst_collect_pads_collect_range:
471 * @pads: the collectspads to use
472 * @offset: the offset to collect
473 * @length: the length to collect
475 * Collect data with @offset and @length on all pads. This function
476 * is typically called in the getrange function of an element.
478 * This function is currently not implemented.
482 * Returns: #GstFlowReturn of the operation.
485 gst_collect_pads_collect_range (GstCollectPads * pads, guint64 offset,
488 g_return_val_if_fail (pads != NULL, GST_FLOW_ERROR);
489 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), GST_FLOW_ERROR);
491 g_warning ("gst_collect_pads_collect_range() is not implemented");
493 return GST_FLOW_NOT_SUPPORTED;
497 gst_collect_pads_is_flushing (GstCollectPads * pads)
502 GST_COLLECT_PADS_PAD_LOCK (pads);
504 /* Ensure pads->data state */
505 gst_collect_pads_check_pads_unlocked (pads);
507 GST_DEBUG ("Getting flushing state (pads:%p, pads->data:%p)",
510 for (walk = pads->data; walk; walk = g_slist_next (walk)) {
511 GstCollectData *cdata = walk->data;
513 GST_DEBUG_OBJECT (cdata->pad, "flushing:%d", cdata->flushing);
515 if (cdata->flushing) {
522 GST_COLLECT_PADS_PAD_UNLOCK (pads);
526 /* FIXME, I think this function is used to work around bad behaviour
527 * of elements that add pads to themselves without activating them.
529 * Must be called with PAD_LOCK.
532 gst_collect_pads_set_flushing_unlocked (GstCollectPads * pads,
537 GST_DEBUG ("Setting flushing (%d)", flushing);
539 /* Update the pads flushing flag */
540 for (walk = pads->data; walk; walk = g_slist_next (walk)) {
541 GstCollectData *cdata = walk->data;
543 if (GST_IS_PAD (cdata->pad)) {
544 GST_OBJECT_LOCK (cdata->pad);
546 GST_PAD_SET_FLUSHING (cdata->pad);
548 GST_PAD_UNSET_FLUSHING (cdata->pad);
549 cdata->flushing = flushing;
550 gst_collect_pads_clear (pads, cdata);
551 GST_OBJECT_UNLOCK (cdata->pad);
554 /* Setting the pads to flushing means that we changed the values which
555 * are 'protected' by the cookie. We therefore update it to force a
556 * recalculation of the current pad status. */
561 * gst_collect_pads_set_flushing:
562 * @pads: the collectspads to use
563 * @flushing: desired state of the pads
565 * Change the flushing state of all the pads in the collection. No pad
566 * is able to accept anymore data when @flushing is %TRUE. Calling this
567 * function with @flushing %FALSE makes @pads accept data again.
574 gst_collect_pads_set_flushing (GstCollectPads * pads, gboolean flushing)
576 g_return_if_fail (pads != NULL);
577 g_return_if_fail (GST_IS_COLLECT_PADS (pads));
579 GST_COLLECT_PADS_PAD_LOCK (pads);
580 /* Ensure pads->data state */
581 gst_collect_pads_check_pads_unlocked (pads);
582 gst_collect_pads_set_flushing_unlocked (pads, flushing);
583 GST_COLLECT_PADS_PAD_UNLOCK (pads);
587 * gst_collect_pads_start:
588 * @pads: the collectspads to use
590 * Starts the processing of data in the collect_pads.
595 gst_collect_pads_start (GstCollectPads * pads)
599 g_return_if_fail (pads != NULL);
600 g_return_if_fail (GST_IS_COLLECT_PADS (pads));
602 GST_DEBUG_OBJECT (pads, "starting collect pads");
604 /* make sure stop and collect cannot be called anymore */
605 GST_OBJECT_LOCK (pads);
607 /* make pads streamable */
608 GST_COLLECT_PADS_PAD_LOCK (pads);
610 /* loop over the master pad list and reset the segment */
611 collected = pads->pad_list;
612 for (; collected; collected = g_slist_next (collected)) {
613 GstCollectData *data;
615 data = collected->data;
616 gst_segment_init (&data->segment, GST_FORMAT_UNDEFINED);
619 gst_collect_pads_set_flushing_unlocked (pads, FALSE);
621 /* Start collect pads */
622 pads->started = TRUE;
623 GST_COLLECT_PADS_PAD_UNLOCK (pads);
624 GST_OBJECT_UNLOCK (pads);
628 * gst_collect_pads_stop:
629 * @pads: the collectspads to use
631 * Stops the processing of data in the collect_pads. this function
632 * will also unblock any blocking operations.
637 gst_collect_pads_stop (GstCollectPads * pads)
641 g_return_if_fail (pads != NULL);
642 g_return_if_fail (GST_IS_COLLECT_PADS (pads));
644 GST_DEBUG_OBJECT (pads, "stopping collect pads");
646 /* make sure collect and start cannot be called anymore */
647 GST_OBJECT_LOCK (pads);
649 /* make pads not accept data anymore */
650 GST_COLLECT_PADS_PAD_LOCK (pads);
651 gst_collect_pads_set_flushing_unlocked (pads, TRUE);
653 /* Stop collect pads */
654 pads->started = FALSE;
656 pads->queuedpads = 0;
658 /* loop over the master pad list and flush buffers */
659 collected = pads->pad_list;
660 for (; collected; collected = g_slist_next (collected)) {
661 GstCollectData *data;
662 GstBuffer **buffer_p;
664 data = collected->data;
666 buffer_p = &data->buffer;
667 gst_buffer_replace (buffer_p, NULL);
673 GST_COLLECT_PADS_PAD_UNLOCK (pads);
674 /* Wake them up so they can end the chain functions. */
675 GST_COLLECT_PADS_BROADCAST (pads);
677 GST_OBJECT_UNLOCK (pads);
681 * gst_collect_pads_peek:
682 * @pads: the collectspads to peek
683 * @data: the data to use
685 * Peek at the buffer currently queued in @data. This function
686 * should be called with the @pads LOCK held, such as in the callback
691 * Returns: (transfer full): The buffer in @data or NULL if no buffer is queued.
692 * should unref the buffer after usage.
695 gst_collect_pads_peek (GstCollectPads * pads, GstCollectData * data)
699 g_return_val_if_fail (pads != NULL, NULL);
700 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), NULL);
701 g_return_val_if_fail (data != NULL, NULL);
703 if ((result = data->buffer))
704 gst_buffer_ref (result);
706 GST_DEBUG ("Peeking at pad %s:%s: buffer=%p",
707 GST_DEBUG_PAD_NAME (data->pad), result);
713 * gst_collect_pads_pop:
714 * @pads: the collectspads to pop
715 * @data: the data to use
717 * Pop the buffer currently queued in @data. This function
718 * should be called with the @pads LOCK held, such as in the callback
721 * Free-function: gst_buffer_unref
725 * Returns: (transfer full): The buffer in @data or NULL if no buffer was
726 * queued. You should unref the buffer after usage.
729 gst_collect_pads_pop (GstCollectPads * pads, GstCollectData * data)
733 g_return_val_if_fail (pads != NULL, NULL);
734 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), NULL);
735 g_return_val_if_fail (data != NULL, NULL);
737 if ((result = data->buffer)) {
740 /* one less pad with queued data now */
744 GST_COLLECT_PADS_BROADCAST (pads);
746 GST_DEBUG ("Pop buffer on pad %s:%s: buffer=%p",
747 GST_DEBUG_PAD_NAME (data->pad), result);
752 /* pop and unref the currently queued buffer, should e called with the LOCK
755 gst_collect_pads_clear (GstCollectPads * pads, GstCollectData * data)
759 if ((buf = gst_collect_pads_pop (pads, data)))
760 gst_buffer_unref (buf);
764 * gst_collect_pads_available:
765 * @pads: the collectspads to query
767 * Query how much bytes can be read from each queued buffer. This means
768 * that the result of this call is the maximum number of bytes that can
769 * be read from each of the pads.
771 * This function should be called with @pads LOCK held, such as
776 * Returns: The maximum number of bytes queued on all pads. This function
777 * returns 0 if a pad has no queued buffer.
779 /* FIXME, we can do this in the _chain functions */
781 gst_collect_pads_available (GstCollectPads * pads)
784 guint result = G_MAXUINT;
786 g_return_val_if_fail (pads != NULL, 0);
787 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), 0);
789 for (collected = pads->data; collected; collected = g_slist_next (collected)) {
790 GstCollectData *pdata;
794 pdata = (GstCollectData *) collected->data;
796 /* ignore pad with EOS */
797 if (G_UNLIKELY (pdata->eos)) {
798 GST_DEBUG ("pad %s:%s is EOS", GST_DEBUG_PAD_NAME (pdata->pad));
802 /* an empty buffer without EOS is weird when we get here.. */
803 if (G_UNLIKELY ((buffer = pdata->buffer) == NULL)) {
804 GST_WARNING ("pad %s:%s has no buffer", GST_DEBUG_PAD_NAME (pdata->pad));
808 /* this is the size left of the buffer */
809 size = gst_buffer_get_size (buffer) - pdata->pos;
810 GST_DEBUG ("pad %s:%s has %d bytes left",
811 GST_DEBUG_PAD_NAME (pdata->pad), size);
813 /* need to return the min of all available data */
817 /* nothing changed, all must be EOS then, return 0 */
818 if (G_UNLIKELY (result == G_MAXUINT))
830 * gst_collect_pads_read_buffer:
831 * @pads: the collectspads to query
832 * @data: the data to use
833 * @size: the number of bytes to read
835 * Get a buffer of @size bytes from the given pad @data.
837 * This function should be called with @pads LOCK held, such as in the callback.
839 * Free-function: gst_buffer_unref
841 * Returns: (transfer full): a #GstBuffer. The size of the buffer can be less
842 * that requested. A return of NULL signals that the pad is end-of-stream.
843 * Unref the buffer with gst_buffer_unref() after use.
850 gst_collect_pads_read_buffer (GstCollectPads * pads, GstCollectData * data,
853 guint readsize, bufsize;
856 g_return_val_if_fail (pads != NULL, NULL);
857 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), NULL);
858 g_return_val_if_fail (data != NULL, NULL);
860 /* no buffer, must be EOS */
861 if ((buffer = data->buffer) == NULL)
864 bufsize = gst_buffer_get_size (buffer);
866 readsize = MIN (size, bufsize - data->pos);
868 if (data->pos == 0 && readsize == bufsize)
869 return gst_buffer_ref (buffer);
871 return gst_buffer_copy_region (buffer, GST_BUFFER_COPY_ALL, data->pos,
876 * gst_collect_pads_take_buffer:
877 * @pads: the collectspads to query
878 * @data: the data to use
879 * @size: the number of bytes to read
881 * Get a buffer of @size bytes from the given pad @data. Flushes the amount
884 * This function should be called with @pads LOCK held, such as in the callback.
886 * Free-function: gst_buffer_unref
890 * Returns: (transfer full): a #GstBuffer. The size of the buffer can be less
891 * that requested. A return of NULL signals that the pad is end-of-stream.
892 * Unref the buffer after use.
897 gst_collect_pads_take_buffer (GstCollectPads * pads, GstCollectData * data,
900 GstBuffer *buffer = gst_collect_pads_read_buffer (pads, data, size);
903 gst_collect_pads_flush (pads, data, gst_buffer_get_size (buffer));
909 * gst_collect_pads_flush:
910 * @pads: the collectspads to query
911 * @data: the data to use
912 * @size: the number of bytes to flush
914 * Flush @size bytes from the pad @data.
916 * This function should be called with @pads LOCK held, such as
921 * Returns: The number of bytes flushed. This can be less than @size and
922 * is 0 if the pad was end-of-stream.
925 gst_collect_pads_flush (GstCollectPads * pads, GstCollectData * data,
932 g_return_val_if_fail (pads != NULL, 0);
933 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), 0);
934 g_return_val_if_fail (data != NULL, 0);
936 /* no buffer, must be EOS */
937 if ((buffer = data->buffer) == NULL)
940 bsize = gst_buffer_get_size (buffer);
942 /* this is what we can flush at max */
943 flushsize = MIN (size, bsize - data->pos);
947 GST_LOG_OBJECT (pads, "Flushing %d bytes, requested %u", flushsize, size);
949 if (data->pos >= bsize)
950 /* _clear will also reset data->pos to 0 */
951 gst_collect_pads_clear (pads, data);
956 /* see if pads were added or removed and update our stats. Any pad
957 * added after releasing the PAD_LOCK will get collected in the next
960 * We can do a quick check by checking the cookies, that get changed
961 * whenever the pad list is updated.
963 * Must be called with LOCK.
966 gst_collect_pads_check_pads_unlocked (GstCollectPads * pads)
968 GST_DEBUG ("stored cookie : %d, used_cookie:%d",
969 pads->pad_cookie, pads->cookie);
970 if (G_UNLIKELY (pads->pad_cookie != pads->cookie)) {
973 /* clear list and stats */
974 g_slist_foreach (pads->data, (GFunc) unref_data, NULL);
975 g_slist_free (pads->data);
978 pads->queuedpads = 0;
981 /* loop over the master pad list */
982 collected = pads->pad_list;
983 for (; collected; collected = g_slist_next (collected)) {
984 GstCollectData *data;
986 /* update the stats */
988 data = collected->data;
990 if (G_LIKELY (!data->flushing)) {
997 /* add to the list of pads to collect */
999 pads->data = g_slist_prepend (pads->data, data);
1001 /* and update the cookie */
1002 pads->cookie = pads->pad_cookie;
1007 gst_collect_pads_check_pads (GstCollectPads * pads)
1009 /* the master list and cookie are protected with the PAD_LOCK */
1010 GST_COLLECT_PADS_PAD_LOCK (pads);
1011 gst_collect_pads_check_pads_unlocked (pads);
1012 GST_COLLECT_PADS_PAD_UNLOCK (pads);
1015 /* checks if all the pads are collected and call the collectfunction
1017 * Should be called with LOCK.
1019 * Returns: The #GstFlowReturn of collection.
1021 static GstFlowReturn
1022 gst_collect_pads_check_collected (GstCollectPads * pads)
1024 GstFlowReturn flow_ret = GST_FLOW_OK;
1026 g_return_val_if_fail (GST_IS_COLLECT_PADS (pads), GST_FLOW_ERROR);
1027 g_return_val_if_fail (pads->func != NULL, GST_FLOW_NOT_SUPPORTED);
1029 /* check for new pads, update stats etc.. */
1030 gst_collect_pads_check_pads (pads);
1032 if (G_UNLIKELY (pads->eospads == pads->numpads)) {
1033 /* If all our pads are EOS just collect once to let the element
1034 * do its final EOS handling. */
1035 GST_DEBUG ("All active pads (%d) are EOS, calling %s",
1036 pads->numpads, GST_DEBUG_FUNCPTR_NAME (pads->func));
1037 flow_ret = pads->func (pads, pads->user_data);
1039 gboolean collected = FALSE;
1041 /* We call the collected function as long as our condition matches.
1042 * FIXME: should we error out if the collect function did not pop anything ?
1043 * we can get a busy loop here if the element does not pop from the collect
1046 while (((pads->queuedpads + pads->eospads) >= pads->numpads)) {
1047 GST_DEBUG ("All active pads (%d + %d >= %d) have data, calling %s",
1048 pads->queuedpads, pads->eospads, pads->numpads,
1049 GST_DEBUG_FUNCPTR_NAME (pads->func));
1050 flow_ret = pads->func (pads, pads->user_data);
1053 /* break on error */
1054 if (flow_ret != GST_FLOW_OK)
1056 /* Don't keep looping after telling the element EOS or flushing */
1057 if (pads->queuedpads == 0)
1061 GST_DEBUG ("Not all active pads (%d) have data, continuing",
1068 gst_collect_pads_event (GstPad * pad, GstObject * parent, GstEvent * event)
1071 GstCollectData *data;
1072 GstCollectPads *pads;
1074 /* some magic to get the managing collect_pads */
1075 GST_OBJECT_LOCK (pad);
1076 data = (GstCollectData *) gst_pad_get_element_private (pad);
1077 if (G_UNLIKELY (data == NULL))
1080 GST_OBJECT_UNLOCK (pad);
1084 pads = data->collect;
1086 GST_DEBUG ("Got %s event on pad %s:%s", GST_EVENT_TYPE_NAME (event),
1087 GST_DEBUG_PAD_NAME (data->pad));
1089 switch (GST_EVENT_TYPE (event)) {
1090 case GST_EVENT_FLUSH_START:
1092 /* forward event to unblock check_collected */
1093 gst_pad_event_default (pad, parent, event);
1095 /* now unblock the chain function.
1096 * no cond per pad, so they all unblock,
1097 * non-flushing block again */
1098 GST_OBJECT_LOCK (pads);
1099 data->flushing = TRUE;
1100 gst_collect_pads_clear (pads, data);
1101 GST_OBJECT_UNLOCK (pads);
1103 /* event already cleaned up by forwarding */
1106 case GST_EVENT_FLUSH_STOP:
1108 /* flush the 1 buffer queue */
1109 GST_OBJECT_LOCK (pads);
1110 data->flushing = FALSE;
1111 gst_collect_pads_clear (pads, data);
1112 /* we need new segment info after the flush */
1113 gst_segment_init (&data->segment, GST_FORMAT_UNDEFINED);
1114 data->new_segment = FALSE;
1115 /* if the pad was EOS, remove the EOS flag and
1116 * decrement the number of eospads */
1117 if (G_UNLIKELY (data->eos == TRUE)) {
1122 if (!gst_collect_pads_is_flushing (pads)) {
1123 /* forward event if all pads are no longer flushing */
1124 GST_DEBUG ("No more pads are flushing, forwarding FLUSH_STOP");
1125 GST_OBJECT_UNLOCK (pads);
1128 gst_event_unref (event);
1129 GST_OBJECT_UNLOCK (pads);
1134 GST_OBJECT_LOCK (pads);
1135 /* if the pad was not EOS, make it EOS and so we
1136 * have one more eospad */
1137 if (G_LIKELY (data->eos == FALSE)) {
1141 /* check if we need collecting anything, we ignore the
1143 gst_collect_pads_check_collected (pads);
1144 GST_OBJECT_UNLOCK (pads);
1146 /* We eat this event, element should do something
1147 * in the collected callback. */
1148 gst_event_unref (event);
1151 case GST_EVENT_SEGMENT:
1153 gst_event_copy_segment (event, &data->segment);
1155 GST_DEBUG_OBJECT (data->pad, "got newsegment %" GST_SEGMENT_FORMAT,
1157 data->new_segment = TRUE;
1159 /* we must not forward this event since multiple segments will be
1160 * accumulated and this is certainly not what we want. */
1161 gst_event_unref (event);
1162 /* FIXME: collect-pads based elements need to create their own newsegment
1163 * event (and only one really)
1164 * (a) make the segment part of the GstCollectData structure of each pad,
1165 * so you can just check that once you have a buffer queued on that pad,
1166 * (b) you can override a pad's event function with your own,
1167 * catch the newsegment event and then pass it on to the original
1168 * gstcollectpads event function
1169 * (that's what avimux does for something IIRC)
1175 /* forward other events */
1180 GST_DEBUG_OBJECT (pads, "forward unhandled event: %s",
1181 GST_EVENT_TYPE_NAME (event));
1182 res = gst_pad_event_default (pad, parent, event);
1191 GST_DEBUG ("%s got removed from collectpads", GST_OBJECT_NAME (pad));
1192 GST_OBJECT_UNLOCK (pad);
1197 /* For each buffer we receive we check if our collected condition is reached
1198 * and if so we call the collected function. When this is done we check if
1199 * data has been unqueued. If data is still queued we wait holding the stream
1200 * lock to make sure no EOS event can happen while we are ready to be
1203 static GstFlowReturn
1204 gst_collect_pads_chain (GstPad * pad, GstObject * parent, GstBuffer * buffer)
1206 GstCollectData *data;
1207 GstCollectPads *pads;
1208 GstCollectPadsPrivate *priv;
1211 GST_DEBUG ("Got buffer for pad %s:%s", GST_DEBUG_PAD_NAME (pad));
1213 /* some magic to get the managing collect_pads */
1214 GST_OBJECT_LOCK (pad);
1215 data = (GstCollectData *) gst_pad_get_element_private (pad);
1216 if (G_UNLIKELY (data == NULL))
1219 GST_OBJECT_UNLOCK (pad);
1221 pads = data->collect;
1224 GST_OBJECT_LOCK (pads);
1225 /* if not started, bail out */
1226 if (G_UNLIKELY (!pads->started))
1228 /* check if this pad is flushing */
1229 if (G_UNLIKELY (data->flushing))
1231 /* pad was EOS, we can refuse this data */
1232 if (G_UNLIKELY (data->eos))
1235 /* see if we need to clip */
1236 if (priv->clipfunc) {
1237 buffer = priv->clipfunc (pads, data, buffer, priv->clipfunc_user_data);
1239 if (G_UNLIKELY (buffer == NULL))
1243 GST_DEBUG ("Queuing buffer %p for pad %s:%s", buffer,
1244 GST_DEBUG_PAD_NAME (pad));
1246 /* One more pad has data queued */
1248 /* take ownership of the buffer */
1250 gst_buffer_unref (data->buffer);
1251 data->buffer = buffer;
1254 /* update segment last position if in TIME */
1255 if (G_LIKELY (data->segment.format == GST_FORMAT_TIME)) {
1256 GstClockTime timestamp = GST_BUFFER_TIMESTAMP (data->buffer);
1258 if (GST_CLOCK_TIME_IS_VALID (timestamp))
1259 data->segment.position = timestamp;
1262 /* While we have data queued on this pad try to collect stuff */
1264 GST_DEBUG ("Pad %s:%s checking", GST_DEBUG_PAD_NAME (pad));
1265 /* Check if our collected condition is matched and call the collected function
1267 ret = gst_collect_pads_check_collected (pads);
1268 /* when an error occurs, we want to report this back to the caller ASAP
1269 * without having to block if the buffer was not popped */
1270 if (G_UNLIKELY (ret != GST_FLOW_OK))
1273 /* data was consumed, we can exit and accept new data */
1274 if (data->buffer == NULL)
1277 /* Check if we got removed in the mean time, FIXME, this is racy.
1278 * Between this check and the _WAIT, the pad could be removed which will
1279 * makes us hang in the _WAIT. */
1280 GST_OBJECT_LOCK (pad);
1281 if (G_UNLIKELY (gst_pad_get_element_private (pad) == NULL))
1283 GST_OBJECT_UNLOCK (pad);
1285 GST_DEBUG ("Pad %s:%s has a buffer queued, waiting",
1286 GST_DEBUG_PAD_NAME (pad));
1288 /* wait to be collected, this must happen from another thread triggered
1289 * by the _chain function of another pad. We release the lock so we
1290 * can get stopped or flushed as well. We can however not get EOS
1291 * because we still hold the STREAM_LOCK.
1293 GST_COLLECT_PADS_WAIT (pads);
1295 GST_DEBUG ("Pad %s:%s resuming", GST_DEBUG_PAD_NAME (pad));
1297 /* after a signal, we could be stopped */
1298 if (G_UNLIKELY (!pads->started))
1300 /* check if this pad is flushing */
1301 if (G_UNLIKELY (data->flushing))
1304 while (data->buffer != NULL);
1307 GST_DEBUG ("Pad %s:%s done", GST_DEBUG_PAD_NAME (pad));
1308 GST_OBJECT_UNLOCK (pads);
1311 gst_buffer_unref (buffer);
1316 GST_WARNING ("%s got removed from collectpads", GST_OBJECT_NAME (pad));
1317 GST_OBJECT_UNLOCK (pad);
1318 ret = GST_FLOW_NOT_LINKED;
1324 GST_DEBUG ("%s got removed from collectpads", GST_OBJECT_NAME (pad));
1325 GST_OBJECT_UNLOCK (pad);
1326 gst_buffer_unref (buffer);
1327 return GST_FLOW_NOT_LINKED;
1331 GST_DEBUG ("not started");
1332 gst_collect_pads_clear (pads, data);
1333 ret = GST_FLOW_WRONG_STATE;
1338 GST_DEBUG ("pad %s:%s is flushing", GST_DEBUG_PAD_NAME (pad));
1339 gst_collect_pads_clear (pads, data);
1340 ret = GST_FLOW_WRONG_STATE;
1345 /* we should not post an error for this, just inform upstream that
1346 * we don't expect anything anymore */
1347 GST_DEBUG ("pad %s:%s is eos", GST_DEBUG_PAD_NAME (pad));
1353 GST_DEBUG ("clipped buffer on pad %s:%s", GST_DEBUG_PAD_NAME (pad));
1359 /* we print the error, the element should post a reasonable error
1360 * message for fatal errors */
1361 GST_DEBUG ("collect failed, reason %d (%s)", ret, gst_flow_get_name (ret));
1362 gst_collect_pads_clear (pads, data);