2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstelement.c: The base element, all elements derive from this
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 //#define GST_DEBUG_ENABLED
26 #include "gst_private.h"
28 #include "gstelement.h"
29 #include "gstextratypes.h"
31 #include "gstscheduler.h"
34 /* Element signals and args */
50 static void gst_element_class_init (GstElementClass *klass);
51 static void gst_element_init (GstElement *element);
52 static void gst_element_base_class_init (GstElementClass *klass);
54 static void gst_element_set_property (GObject *object, guint prop_id,
55 const GValue *value, GParamSpec *pspec);
56 static void gst_element_get_property (GObject *object, guint prop_id, GValue *value,
59 static void gst_element_dispose (GObject *object);
61 static GstElementStateReturn gst_element_change_state (GstElement *element);
63 #ifndef GST_DISABLE_LOADSAVE
64 static xmlNodePtr gst_element_save_thyself (GstObject *object, xmlNodePtr parent);
65 GstElement* gst_element_restore_thyself (xmlNodePtr self, GstObject *parent);
68 GType _gst_element_type = 0;
70 static GstObjectClass *parent_class = NULL;
71 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
73 GType gst_element_get_type (void)
75 if (!_gst_element_type) {
76 static const GTypeInfo element_info = {
77 sizeof(GstElementClass),
78 (GBaseInitFunc)gst_element_base_class_init,
80 (GClassInitFunc)gst_element_class_init,
85 (GInstanceInitFunc)gst_element_init,
88 _gst_element_type = g_type_register_static(GST_TYPE_OBJECT, "GstElement", &element_info, G_TYPE_FLAG_ABSTRACT);
90 return _gst_element_type;
94 gst_element_class_init (GstElementClass *klass)
96 GObjectClass *gobject_class;
97 GstObjectClass *gstobject_class;
99 gobject_class = (GObjectClass*) klass;
100 gstobject_class = (GstObjectClass*) klass;
102 parent_class = g_type_class_ref(GST_TYPE_OBJECT);
104 gst_element_signals[STATE_CHANGE] =
105 g_signal_new ("state_change", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
106 G_STRUCT_OFFSET (GstElementClass, state_change), NULL, NULL,
107 gst_marshal_VOID__INT_INT, G_TYPE_NONE, 2,
108 G_TYPE_INT, G_TYPE_INT);
109 gst_element_signals[NEW_PAD] =
110 g_signal_new ("new_pad", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
111 G_STRUCT_OFFSET (GstElementClass, new_pad), NULL, NULL,
112 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
114 gst_element_signals[PAD_REMOVED] =
115 g_signal_new ("pad_removed", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
116 G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
117 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
119 gst_element_signals[ERROR] =
120 g_signal_new ("error", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
121 G_STRUCT_OFFSET (GstElementClass, error), NULL, NULL,
122 gst_marshal_VOID__STRING, G_TYPE_NONE,1,
124 gst_element_signals[EOS] =
125 g_signal_new ("eos", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
126 G_STRUCT_OFFSET (GstElementClass,eos), NULL, NULL,
127 gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
131 gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_element_set_property);
132 gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_element_get_property);
133 gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_element_dispose);
135 #ifndef GST_DISABLE_LOADSAVE
136 gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_element_save_thyself);
137 gstobject_class->restore_thyself = GST_DEBUG_FUNCPTR (gst_element_restore_thyself);
140 klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state);
141 klass->elementfactory = NULL;
142 klass->padtemplates = NULL;
143 klass->numpadtemplates = 0;
147 gst_element_base_class_init (GstElementClass *klass)
149 GObjectClass *gobject_class;
151 gobject_class = (GObjectClass*) klass;
153 gobject_class->set_property = GST_DEBUG_FUNCPTR(gst_element_set_property);
154 gobject_class->get_property = GST_DEBUG_FUNCPTR(gst_element_get_property);
158 gst_element_init (GstElement *element)
160 element->current_state = GST_STATE_NULL;
161 element->pending_state = -1;
162 element->numpads = 0;
163 element->numsrcpads = 0;
164 element->numsinkpads = 0;
165 element->pads = NULL;
166 element->loopfunc = NULL;
167 element->threadstate = NULL;
168 element->sched = NULL;
173 gst_element_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec)
175 GstElementClass *oclass = (GstElementClass *)G_OBJECT_GET_CLASS(object);
177 if (oclass->set_property)
178 (oclass->set_property)(object,prop_id,value,pspec);
183 gst_element_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec)
185 GstElementClass *oclass = (GstElementClass *)G_OBJECT_GET_CLASS(object);
187 if (oclass->get_property)
188 (oclass->get_property)(object,prop_id,value,pspec);
193 * gst_element_set_name:
194 * @element: GstElement to set name of
195 * @name: new name of element
197 * Set the name of the element, getting rid of the old name if there was
201 gst_element_set_name (GstElement *element, const gchar *name)
203 g_return_if_fail (element != NULL);
204 g_return_if_fail (GST_IS_ELEMENT (element));
205 g_return_if_fail (name != NULL);
207 gst_object_set_name (GST_OBJECT (element), name);
211 * gst_element_get_name:
212 * @element: GstElement to get name of
214 * Get the name of the element.
216 * Returns: name of the element
219 gst_element_get_name (GstElement *element)
221 g_return_val_if_fail (element != NULL, NULL);
222 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
224 return GST_OBJECT_NAME (element);
228 * gst_element_set_parent:
229 * @element: GstElement to set parent of
230 * @parent: new parent of the object
232 * Set the parent of the element.
235 gst_element_set_parent (GstElement *element, GstObject *parent)
237 g_return_if_fail (element != NULL);
238 g_return_if_fail (GST_IS_ELEMENT (element));
239 g_return_if_fail (GST_OBJECT_PARENT (element) == NULL);
240 g_return_if_fail (parent != NULL);
241 g_return_if_fail (GST_IS_OBJECT (parent));
242 g_return_if_fail ((gpointer)element != (gpointer)parent);
244 gst_object_set_parent (GST_OBJECT (element), parent);
248 * gst_element_get_parent:
249 * @element: GstElement to get the parent of
251 * Get the parent of the element.
253 * Returns: parent of the element
256 gst_element_get_parent (GstElement *element)
258 g_return_val_if_fail (element != NULL, NULL);
259 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
261 return GST_OBJECT_PARENT (element);
265 * gst_element_add_pad:
266 * @element: element to add pad to
269 * Add a pad (connection point) to the element, setting the parent of the
270 * pad to the element (and thus adding a reference).
273 gst_element_add_pad (GstElement *element, GstPad *pad)
275 g_return_if_fail (element != NULL);
276 g_return_if_fail (GST_IS_ELEMENT (element));
277 g_return_if_fail (pad != NULL);
278 g_return_if_fail (GST_IS_PAD (pad));
280 // first check to make sure the pad's parent is already set
281 g_return_if_fail (GST_PAD_PARENT (pad) == NULL);
283 // then check to see if there's already a pad by that name here
284 g_return_if_fail (gst_object_check_uniqueness (element->pads, GST_PAD_NAME(pad)) == TRUE);
286 /* set the pad's parent */
287 GST_DEBUG (GST_CAT_ELEMENT_PADS,"setting parent of pad '%s' to '%s'\n",
288 GST_PAD_NAME (pad), GST_ELEMENT_NAME (element));
289 gst_object_set_parent (GST_OBJECT (pad), GST_OBJECT (element));
291 /* add it to the list */
292 element->pads = g_list_append (element->pads, pad);
294 if (gst_pad_get_direction (pad) == GST_PAD_SRC)
295 element->numsrcpads++;
297 element->numsinkpads++;
299 /* emit the NEW_PAD signal */
300 g_signal_emit (G_OBJECT (element), gst_element_signals[NEW_PAD], 0, pad);
304 * gst_element_remove_pad:
305 * @element: element to remove pad from
306 * @pad: pad to remove
308 * Remove a pad (connection point) from the element,
311 gst_element_remove_pad (GstElement *element, GstPad *pad)
313 g_return_if_fail (element != NULL);
314 g_return_if_fail (GST_IS_ELEMENT (element));
315 g_return_if_fail (pad != NULL);
316 g_return_if_fail (GST_IS_PAD (pad));
318 g_return_if_fail (GST_PAD_PARENT (pad) == element);
320 /* add it to the list */
321 element->pads = g_list_remove (element->pads, pad);
323 if (gst_pad_get_direction (pad) == GST_PAD_SRC)
324 element->numsrcpads--;
326 element->numsinkpads--;
328 g_signal_emit (G_OBJECT (element), gst_element_signals[PAD_REMOVED], 0, pad);
330 gst_object_unparent (GST_OBJECT (pad));
334 * gst_element_add_ghost_pad:
335 * @element: element to add ghost pad to
336 * @pad: pad from which the new ghost pad will be created
337 * @name: name of the new ghost pad
339 * Create a ghost pad from the given pad, and add it to the list of pads
343 gst_element_add_ghost_pad (GstElement *element, GstPad *pad, gchar *name)
347 g_return_if_fail (element != NULL);
348 g_return_if_fail (GST_IS_ELEMENT (element));
349 g_return_if_fail (pad != NULL);
350 g_return_if_fail (GST_IS_PAD (pad));
352 // then check to see if there's already a pad by that name here
353 g_return_if_fail (gst_object_check_uniqueness (element->pads, name) == TRUE);
355 GST_DEBUG(GST_CAT_ELEMENT_PADS,"creating new ghost pad called %s, from pad %s:%s\n",
356 name,GST_DEBUG_PAD_NAME(pad));
357 ghostpad = gst_ghost_pad_new (name, pad);
359 /* add it to the list */
360 GST_DEBUG(GST_CAT_ELEMENT_PADS,"adding ghost pad %s to element %s\n",
361 name, GST_ELEMENT_NAME (element));
362 element->pads = g_list_append (element->pads, ghostpad);
364 // set the parent of the ghostpad
365 gst_object_set_parent (GST_OBJECT (ghostpad), GST_OBJECT (element));
367 GST_DEBUG(GST_CAT_ELEMENT_PADS,"added ghostpad %s:%s\n",GST_DEBUG_PAD_NAME(ghostpad));
369 /* emit the NEW_GHOST_PAD signal */
370 g_signal_emit (G_OBJECT (element), gst_element_signals[NEW_PAD], 0, ghostpad);
374 * gst_element_remove_ghost_pad:
375 * @element: element to remove the ghost pad from
376 * @pad: ghost pad to remove
378 * removes a ghost pad from an element
382 gst_element_remove_ghost_pad (GstElement *element, GstPad *pad)
384 g_return_if_fail (element != NULL);
385 g_return_if_fail (GST_IS_ELEMENT (element));
386 g_return_if_fail (pad != NULL);
387 g_return_if_fail (GST_IS_GHOST_PAD (pad));
389 // FIXME this is redundant?
390 // wingo 10-july-2001: I don't think so, you have to actually remove the pad
391 // from the element. gst_pad_remove_ghost_pad just removes the ghostpad from
392 // the real pad's ghost pad list
393 gst_pad_remove_ghost_pad (GST_PAD (GST_PAD_REALIZE (pad)), pad);
394 gst_element_remove_pad (element, pad);
399 * gst_element_get_pad:
400 * @element: element to find pad of
401 * @name: name of pad to retrieve
403 * Retrieve a pad from the element by name.
405 * Returns: requested pad if found, otherwise NULL.
408 gst_element_get_pad (GstElement *element, const gchar *name)
412 g_return_val_if_fail (element != NULL, NULL);
413 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
414 g_return_val_if_fail (name != NULL, NULL);
416 // if there aren't any pads, well, we're not likely to find one
417 if (!element->numpads)
420 // look through the list, matching by name
421 walk = element->pads;
423 GstPad *pad = GST_PAD(walk->data);
424 if (!strcmp (GST_PAD_NAME(pad), name)) {
425 GST_INFO(GST_CAT_ELEMENT_PADS,"found pad %s:%s",GST_DEBUG_PAD_NAME(pad));
428 walk = g_list_next (walk);
431 GST_INFO(GST_CAT_ELEMENT_PADS,"no such pad '%s' in element \"%s\"",name,GST_ELEMENT_NAME(element));
436 * gst_element_get_pad_list:
437 * @element: element to get pads of
439 * Retrieve a list of the pads associated with the element.
441 * Returns: GList of pads
444 gst_element_get_pad_list (GstElement *element)
446 g_return_val_if_fail (element != NULL, NULL);
447 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
449 /* return the list of pads */
450 return element->pads;
454 * gst_element_class_add_padtemplate:
455 * @klass: element class to add padtemplate to
456 * @templ: padtemplate to add
458 * Add a padtemplate to an element class. This is useful if you have derived a custom
459 * bin and wish to provide an on-request pad at runtime. Plugin writers should use
460 * gst_elementfactory_add_padtemplate instead.
463 gst_element_class_add_padtemplate (GstElementClass *klass, GstPadTemplate *templ)
465 g_return_if_fail (klass != NULL);
466 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
467 g_return_if_fail (templ != NULL);
468 g_return_if_fail (GST_IS_PADTEMPLATE (templ));
470 klass->padtemplates = g_list_append (klass->padtemplates, templ);
471 klass->numpadtemplates++;
475 * gst_element_get_padtemplate_list:
476 * @element: element to get padtemplates of
478 * Retrieve a list of the padtemplates associated with the element.
480 * Returns: GList of padtemplates
483 gst_element_get_padtemplate_list (GstElement *element)
485 GstElementClass *oclass;
487 g_return_val_if_fail (element != NULL, NULL);
488 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
490 oclass = GST_ELEMENT_CLASS (G_OBJECT_GET_CLASS(element));
492 return oclass->padtemplates;
496 * gst_element_get_padtemplate_by_name:
497 * @element: element to get padtemplate of
498 * @name: the name of the padtemplate to get.
500 * Retrieve a padtemplate from this element with the
503 * Returns: the padtemplate with the given name
506 gst_element_get_padtemplate_by_name (GstElement *element, const guchar *name)
510 g_return_val_if_fail (element != NULL, NULL);
511 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
512 g_return_val_if_fail (name != NULL, NULL);
514 padlist = gst_element_get_padtemplate_list (element);
517 GstPadTemplate *padtempl = (GstPadTemplate*) padlist->data;
519 if (!strcmp (padtempl->name_template, name))
522 padlist = g_list_next (padlist);
529 * gst_element_get_padtemplate_by_compatible:
530 * @element: element to get padtemplate of
531 * @templ: a template to find a compatible template for
533 * Generate a padtemplate for this element compatible with the given
534 * template, ie able to link to it.
536 * Returns: the padtemplate
538 static GstPadTemplate*
539 gst_element_get_padtemplate_by_compatible (GstElement *element, GstPadTemplate *compattempl)
541 GstPadTemplate *newtempl = NULL;
544 GST_DEBUG(GST_CAT_ELEMENT_PADS,"gst_element_get_padtemplate_by_compatible()\n");
546 g_return_val_if_fail (element != NULL, NULL);
547 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
548 g_return_val_if_fail (compattempl != NULL, NULL);
550 padlist = gst_element_get_padtemplate_list (element);
553 GstPadTemplate *padtempl = (GstPadTemplate*) padlist->data;
554 gboolean compat = FALSE;
558 // Check direction (must be opposite)
561 GST_DEBUG(GST_CAT_CAPS,"checking direction and caps\n");
562 if (padtempl->direction == GST_PAD_SRC &&
563 compattempl->direction == GST_PAD_SINK) {
564 GST_DEBUG(GST_CAT_CAPS,"compatible direction: found src pad template\n");
565 compat = gst_caps_check_compatibility(GST_PADTEMPLATE_CAPS (padtempl),
566 GST_PADTEMPLATE_CAPS (compattempl));
567 GST_DEBUG(GST_CAT_CAPS,"caps are %scompatible\n", (compat?"":"not "));
568 } else if (padtempl->direction == GST_PAD_SINK &&
569 compattempl->direction == GST_PAD_SRC) {
570 GST_DEBUG(GST_CAT_CAPS,"compatible direction: found sink pad template\n");
571 compat = gst_caps_check_compatibility(GST_PADTEMPLATE_CAPS (compattempl),
572 GST_PADTEMPLATE_CAPS (padtempl));
573 GST_DEBUG(GST_CAT_CAPS,"caps are %scompatible\n", (compat?"":"not "));
581 padlist = g_list_next (padlist);
588 gst_element_request_pad (GstElement *element, GstPadTemplate *templ, const gchar* name)
590 GstPad *newpad = NULL;
591 GstElementClass *oclass;
593 oclass = GST_ELEMENT_CLASS (G_OBJECT_GET_CLASS(element));
594 if (oclass->request_new_pad)
595 newpad = (oclass->request_new_pad)(element, templ, name);
601 * gst_element_request_compatible_pad:
602 * @element: element to request a new pad from
603 * @templ: a pad template to which the new pad should be able to connect
605 * Request a new pad from the element. The template will
606 * be used to decide what type of pad to create. This function
607 * is typically used for elements with a padtemplate with presence
610 * Returns: the new pad that was created.
613 gst_element_request_compatible_pad (GstElement *element, GstPadTemplate *templ)
615 GstPadTemplate *templ_new;
618 g_return_val_if_fail (element != NULL, NULL);
619 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
620 g_return_val_if_fail (templ != NULL, NULL);
622 templ_new = gst_element_get_padtemplate_by_compatible (element, templ);
623 if (templ_new != NULL)
624 pad = gst_element_request_pad (element, templ_new, NULL);
630 * gst_element_request_pad_by_name:
631 * @element: element to request a new pad from
632 * @name: the name of the padtemplate to use.
634 * Request a new pad from the element. The name argument will
635 * be used to decide what padtemplate to use. This function
636 * is typically used for elements with a padtemplate with presence
639 * Returns: the new pad that was created.
642 gst_element_request_pad_by_name (GstElement *element, const gchar *name)
644 GstPadTemplate *templ = NULL;
646 const gchar *req_name = NULL;
647 gboolean templ_found = FALSE;
651 g_return_val_if_fail (element != NULL, NULL);
652 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
653 g_return_val_if_fail (name != NULL, NULL);
655 if (strstr (name, "%d")) {
656 templ = gst_element_get_padtemplate_by_name (element, name);
659 list = gst_element_get_padtemplate_list(element);
660 while (!templ_found && list) {
661 templ = (GstPadTemplate*) list->data;
662 if (strstr (templ->name_template, "%d")) {
663 if (sscanf(name, templ->name_template, &n)) {
676 pad = gst_element_request_pad (element, templ, req_name);
682 * gst_element_connect:
683 * @src: element containing source pad
684 * @srcpadname: name of pad in source element
685 * @dest: element containing destination pad
686 * @destpadname: name of pad in destination element
688 * Connect the two named pads of the source and destination elements.
689 * Side effect is that if one of the pads has no parent, it becomes a
690 * child of the parent of the other element. If they have different
691 * parents, the connection fails.
694 gst_element_connect (GstElement *src, const gchar *srcpadname,
695 GstElement *dest, const gchar *destpadname)
697 GstPad *srcpad,*destpad;
699 g_return_if_fail (src != NULL);
700 g_return_if_fail (GST_IS_ELEMENT(src));
701 g_return_if_fail (srcpadname != NULL);
702 g_return_if_fail (dest != NULL);
703 g_return_if_fail (GST_IS_ELEMENT(dest));
704 g_return_if_fail (destpadname != NULL);
706 /* obtain the pads requested */
707 srcpad = gst_element_get_pad (src, srcpadname);
708 if (srcpad == NULL) {
709 GST_ERROR(src,"source element has no pad \"%s\"",srcpadname);
712 destpad = gst_element_get_pad (dest, destpadname);
713 if (srcpad == NULL) {
714 GST_ERROR(dest,"destination element has no pad \"%s\"",destpadname);
718 /* we're satisified they can be connected, let's do it */
719 gst_pad_connect(srcpad,destpad);
723 * gst_element_disconnect:
724 * @src: element containing source pad
725 * @srcpadname: name of pad in source element
726 * @dest: element containing destination pad
727 * @destpadname: name of pad in destination element
729 * Disconnect the two named pads of the source and destination elements.
732 gst_element_disconnect (GstElement *src, const gchar *srcpadname,
733 GstElement *dest, const gchar *destpadname)
735 GstPad *srcpad,*destpad;
737 g_return_if_fail (src != NULL);
738 g_return_if_fail (GST_IS_ELEMENT(src));
739 g_return_if_fail (srcpadname != NULL);
740 g_return_if_fail (dest != NULL);
741 g_return_if_fail (GST_IS_ELEMENT(dest));
742 g_return_if_fail (destpadname != NULL);
744 /* obtain the pads requested */
745 srcpad = gst_element_get_pad (src, srcpadname);
746 if (srcpad == NULL) {
747 GST_ERROR(src,"source element has no pad \"%s\"",srcpadname);
750 destpad = gst_element_get_pad (dest, destpadname);
751 if (srcpad == NULL) {
752 GST_ERROR(dest,"destination element has no pad \"%s\"",destpadname);
756 /* we're satisified they can be disconnected, let's do it */
757 gst_pad_disconnect(srcpad,destpad);
762 * @element: Element with the error
763 * @error: String describing the error
765 * This function is used internally by elements to signal an error
766 * condition. It results in the "error" signal.
769 gst_element_error (GstElement *element, const gchar *error)
771 g_error("GstElement: error in element '%s': %s\n", GST_ELEMENT_NAME(element), error);
773 /* FIXME: this is not finished!!! */
775 g_signal_emit (G_OBJECT (element), gst_element_signals[ERROR], 0, error);
780 * gst_element_get_state:
781 * @element: element to get state of
783 * Gets the state of the element.
785 * Returns: The element state
788 gst_element_get_state (GstElement *element)
790 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_VOID_PENDING);
792 return GST_STATE (element);
796 gst_element_wait_done (GstElement *element, GstElementState old, GstElementState new, GCond *cond)
798 g_signal_handlers_disconnect_by_func (G_OBJECT (element), gst_element_wait_done, cond);
799 g_cond_signal (cond);
803 * gst_element_wait_state_change:
804 * @element: element wait for
806 * Wait and block until the element changed its state.
809 gst_element_wait_state_change (GstElement *element)
811 GCond *cond = g_cond_new ();
812 GMutex *mutex = g_mutex_new ();
814 g_mutex_lock (mutex);
815 g_signal_connect (G_OBJECT (element), "state_change",
816 G_CALLBACK (gst_element_wait_done), cond);
817 g_cond_wait (cond, mutex);
818 g_mutex_unlock (mutex);
820 g_mutex_free (mutex);
824 * gst_element_set_state:
825 * @element: element to change state of
826 * @state: new element state
828 * Sets the state of the element. This function will only set
829 * the elements pending state.
831 * Returns: whether or not the state was successfully set.
834 gst_element_set_state (GstElement *element, GstElementState state)
836 GstElementClass *oclass;
837 GstElementState curpending;
838 GstElementStateReturn return_val = GST_STATE_SUCCESS;
840 // g_print("gst_element_set_state(\"%s\",%08lx)\n",
841 // element->name,state);
843 g_return_val_if_fail (element != NULL, GST_STATE_FAILURE);
844 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_FAILURE);
845 g_return_val_if_fail (element->sched != NULL, GST_STATE_FAILURE);
847 GST_DEBUG_ELEMENT (GST_CAT_STATES,element, "setting state from %s to %s\n",
848 gst_element_statename(GST_STATE(element)),
849 gst_element_statename(state));
851 /* start with the current state */
852 curpending = GST_STATE(element);
854 /* loop until the final requested state is set */
855 while (GST_STATE(element) != state && GST_STATE (element) != GST_STATE_VOID_PENDING) {
856 /* move the curpending state in the correct direction */
857 if (curpending < state) curpending<<=1;
860 /* set the pending state variable */
861 // FIXME: should probably check to see that we don't already have one
862 GST_STATE_PENDING (element) = curpending;
863 if (curpending != state)
864 GST_DEBUG_ELEMENT (GST_CAT_STATES,element,"intermediate: setting state to %s\n",
865 gst_element_statename(curpending));
867 /* call the state change function so it can set the state */
868 oclass = GST_ELEMENT_CLASS (G_OBJECT_GET_CLASS(element));
869 if (oclass->change_state)
870 return_val = (oclass->change_state)(element);
872 switch (return_val) {
873 case GST_STATE_FAILURE:
874 GST_DEBUG_ELEMENT (GST_CAT_STATES,element,"have failed change_state return\n");
876 case GST_STATE_ASYNC:
877 GST_DEBUG_ELEMENT (GST_CAT_STATES,element,"element will change state async\n");
880 /* Last thing we do is verify that a successful state change really
881 * did change the state... */
882 if (GST_STATE(element) != curpending) {
883 GST_DEBUG_ELEMENT (GST_CAT_STATES, element, "element claimed state-change success, but state didn't change\n");
884 return GST_STATE_FAILURE;
893 static GstElementStateReturn
894 gst_element_change_state (GstElement *element)
896 GstElementState old_state;
898 g_return_val_if_fail (element != NULL, GST_STATE_FAILURE);
899 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_FAILURE);
901 old_state = GST_STATE (element);
903 if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING || old_state == GST_STATE_PENDING (element)) {
904 g_warning ("no state change needed for element %s (VOID_PENDING)\n", GST_ELEMENT_NAME (element));
905 return GST_STATE_SUCCESS;
908 GST_INFO (GST_CAT_STATES, "%s default handler sets state from %s to %s %d", GST_ELEMENT_NAME (element),
909 gst_element_statename (old_state),
910 gst_element_statename (GST_STATE_PENDING (element)),
911 GST_STATE_TRANSITION (element));
913 if (GST_STATE_TRANSITION (element) == GST_STATE_PAUSED_TO_PLAYING) {
914 g_return_val_if_fail (GST_ELEMENT_SCHED (element), GST_STATE_FAILURE);
916 if (GST_ELEMENT_PARENT (element)) {
917 GST_DEBUG (GST_CAT_STATES, "PAUSED->PLAYING: element \"%s\" has parent \"%s\" and sched %p\n",
918 GST_ELEMENT_NAME (element), GST_ELEMENT_NAME (GST_ELEMENT_PARENT (element)),
919 GST_ELEMENT_SCHED (element));
921 gst_scheduler_enable_element (element->sched, element);
923 else if (GST_STATE_TRANSITION (element) == GST_STATE_PLAYING_TO_PAUSED) {
924 if (GST_ELEMENT_PARENT (element)) {
925 GST_DEBUG (GST_CAT_STATES, "PLAYING->PAUSED: element \"%s\" has parent \"%s\" and sched %p\n",
926 GST_ELEMENT_NAME (element), GST_ELEMENT_NAME (GST_ELEMENT_PARENT (element)),
927 GST_ELEMENT_SCHED (element));
929 gst_scheduler_disable_element (element->sched, element);
932 GST_STATE (element) = GST_STATE_PENDING (element);
933 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
935 // note: queues' state_change is a special case because it needs to lock
936 // for synchronization (from another thread). since this signal may block
937 // or (worse) make another state change, the queue needs to unlock before
938 // calling. thus, gstqueue.c::gst_queue_state_change() blocks, unblocks,
939 // unlocks, then emits this.
940 g_signal_emit (G_OBJECT (element), gst_element_signals[STATE_CHANGE], 0,
941 old_state, GST_STATE (element));
943 return GST_STATE_SUCCESS;
947 * gst_element_get_factory:
948 * @element: element to request the factory
950 * Retrieves the factory that was used to create this element
952 * Returns: the factory used for creating this element
955 gst_element_get_factory (GstElement *element)
957 GstElementClass *oclass;
959 g_return_val_if_fail (element != NULL, NULL);
960 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
962 oclass = GST_ELEMENT_CLASS (G_OBJECT_GET_CLASS(element));
964 return oclass->elementfactory;
968 gst_element_dispose (GObject *object)
970 GstElement *element = GST_ELEMENT (object);
974 GST_DEBUG_ELEMENT (GST_CAT_REFCOUNTING, element, "dispose\n");
976 if (GST_IS_BIN (GST_OBJECT_PARENT (element)))
977 gst_bin_remove (GST_BIN (GST_OBJECT_PARENT (element)), element);
982 orig = pads = g_list_copy (element->pads);
984 pad = GST_PAD (pads->data);
985 // the gst_object_unparent will do the unreffing
986 gst_element_remove_pad(element, pad);
987 pads = g_list_next (pads);
990 g_list_free (element->pads);
991 element->pads = NULL;
994 element->numsrcpads = 0;
995 element->numsinkpads = 0;
997 G_OBJECT_CLASS (parent_class)->dispose (object);
1000 #ifndef GST_DISABLE_LOADSAVE
1002 * gst_element_save_thyself:
1003 * @element: GstElement to save
1004 * @parent: the xml parent node
1006 * Saves the element as part of the given XML structure
1008 * Returns: the new xml node
1011 gst_element_save_thyself (GstObject *object,
1015 GstElementClass *oclass;
1017 GstElement *element;
1019 g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
1021 element = GST_ELEMENT (object);
1023 oclass = GST_ELEMENT_CLASS (G_OBJECT_GET_CLASS(element));
1025 xmlNewChild(parent, NULL, "name", GST_ELEMENT_NAME(element));
1027 if (oclass->elementfactory != NULL) {
1028 GstElementFactory *factory = (GstElementFactory *)oclass->elementfactory;
1030 xmlNewChild (parent, NULL, "type", GST_OBJECT_NAME (factory));
1031 xmlNewChild (parent, NULL, "version", factory->details->version);
1034 // if (element->manager)
1035 // xmlNewChild(parent, NULL, "manager", GST_ELEMENT_NAME(element->manager));
1037 /* FIXME FIXME FIXME!
1038 // output all args to the element
1039 type = G_OBJECT_TYPE (element);
1040 while (type != G_TYPE_INVALID) {
1045 args = gtk_object_query_args (type, &flags, &num_args);
1047 for (i=0; i<num_args; i++) {
1048 if ((args[i].type > G_TYPE_NONE) &&
1049 (flags[i] & GTK_ARG_READABLE)) {
1051 gtk_object_getv (G_OBJECT (element), 1, &args[i]);
1052 arg = xmlNewChild (parent, NULL, "arg", NULL);
1053 xmlNewChild (arg, NULL, "name", args[i].name);
1054 switch (args[i].type) {
1056 xmlNewChild (arg, NULL, "value",
1057 g_strdup_printf ("%c", G_VALUE_CHAR (args[i])));
1060 xmlNewChild (arg, NULL, "value",
1061 g_strdup_printf ("%d", G_VALUE_UCHAR (args[i])));
1064 xmlNewChild (arg, NULL, "value",
1065 G_VALUE_BOOL (args[i]) ? "true" : "false");
1068 xmlNewChild (arg, NULL, "value",
1069 g_strdup_printf ("%d", G_VALUE_INT (args[i])));
1072 xmlNewChild (arg, NULL, "value",
1073 g_strdup_printf ("%ld", G_VALUE_LONG (args[i])));
1076 xmlNewChild (arg, NULL, "value",
1077 g_strdup_printf ("%lu", G_VALUE_ULONG (args[i])));
1080 xmlNewChild (arg, NULL, "value",
1081 g_strdup_printf ("%f", G_VALUE_FLOAT (args[i])));
1084 xmlNewChild (arg, NULL, "value",
1085 g_strdup_printf ("%g", G_VALUE_DOUBLE (args[i])));
1088 xmlNewChild (arg, NULL, "value", G_VALUE_STRING (args[i]));
1091 if (args[i].type == GST_TYPE_FILENAME) {
1092 xmlNewChild (arg, NULL, "value", G_VALUE_STRING (args[i]));
1098 type = gtk_type_parent (type);
1102 pads = GST_ELEMENT_PADS (element);
1105 GstPad *pad = GST_PAD (pads->data);
1106 // figure out if it's a direct pad or a ghostpad
1107 if (GST_ELEMENT (GST_OBJECT_PARENT (pad)) == element) {
1108 xmlNodePtr padtag = xmlNewChild (parent, NULL, "pad", NULL);
1109 gst_object_save_thyself (GST_OBJECT (pad), padtag);
1111 pads = g_list_next (pads);
1118 * gst_element_restore_thyself:
1119 * @self: the xml node
1120 * @parent: the parent of this object when it's loaded
1122 * Load the element from the XML description
1124 * Returns: the new element
1127 gst_element_restore_thyself (xmlNodePtr self, GstObject *parent)
1129 xmlNodePtr children = self->xmlChildrenNode;
1130 GstElement *element;
1131 GstObjectClass *oclass;
1132 guchar *name = NULL;
1133 guchar *value = NULL;
1134 guchar *type = NULL;
1136 // first get the needed tags to construct the element
1138 if (!strcmp (children->name, "name")) {
1139 name = xmlNodeGetContent (children);
1140 } else if (!strcmp (children->name, "type")) {
1141 type = xmlNodeGetContent (children);
1143 children = children->next;
1145 g_return_val_if_fail (name != NULL, NULL);
1146 g_return_val_if_fail (type != NULL, NULL);
1148 GST_INFO (GST_CAT_XML,"loading \"%s\" of type \"%s\"", name, type);
1150 element = gst_elementfactory_make (type, name);
1152 g_return_val_if_fail (element != NULL, NULL);
1154 // ne need to set the parent on this object bacause the pads
1155 // will go through the hierarchy to connect to thier peers
1157 gst_object_set_parent (GST_OBJECT (element), parent);
1159 // we have the element now, set the arguments
1160 children = self->xmlChildrenNode;
1163 if (!strcmp (children->name, "arg")) {
1164 xmlNodePtr child = children->xmlChildrenNode;
1167 if (!strcmp (child->name, "name")) {
1168 name = xmlNodeGetContent (child);
1170 else if (!strcmp (child->name, "value")) {
1171 value = xmlNodeGetContent (child);
1173 child = child->next;
1175 gst_util_set_object_arg ((GObject *)G_OBJECT (element), name, value);
1177 children = children->next;
1179 // we have the element now, set the pads
1180 children = self->xmlChildrenNode;
1183 if (!strcmp (children->name, "pad")) {
1184 gst_pad_load_and_connect (children, GST_OBJECT (element));
1186 children = children->next;
1189 oclass = GST_OBJECT_CLASS (G_OBJECT_GET_CLASS(element));
1190 if (oclass->restore_thyself)
1191 (oclass->restore_thyself) (GST_OBJECT (element), self);
1194 gst_object_unparent (GST_OBJECT (element));
1196 gst_class_signal_emit_by_name (GST_OBJECT (element), "object_loaded", self);
1200 #endif /* GST_DISABLE_LOADSAVE */
1203 * gst_element_set_sched:
1204 * @element: Element to set manager of.
1205 * @sched: @GstScheduler to set.
1207 * Sets the scheduler of the element. For internal use only, unless you're
1208 * writing a new bin subclass.
1211 gst_element_set_sched (GstElement *element,
1212 GstScheduler *sched)
1214 GST_INFO_ELEMENT (GST_CAT_PARENTAGE, element, "setting scheduler to %p",sched);
1215 element->sched = sched;
1219 * gst_element_get_sched:
1220 * @element: Element to get manager of.
1222 * Returns the scheduler of the element.
1224 * Returns: Element's scheduler
1227 gst_element_get_sched (GstElement *element)
1229 return element->sched;
1233 * gst_element_set_loop_function:
1234 * @element: Element to set loop function of.
1235 * @loop: Pointer to loop function.
1237 * This sets the loop function for the element. The function pointed to
1238 * can deviate from the GstElementLoopFunction definition in type of
1241 * NOTE: in order for this to take effect, the current loop function *must*
1242 * exit. Assuming the loop function itself is the only one who will cause
1243 * a new loopfunc to be assigned, this should be no problem.
1246 gst_element_set_loop_function(GstElement *element,
1247 GstElementLoopFunction loop)
1249 /* set the loop function */
1250 element->loopfunc = loop;
1252 /* set the NEW_LOOPFUNC flag so everyone knows to go try again */
1253 GST_FLAG_SET(element,GST_ELEMENT_NEW_LOOPFUNC);
1257 * gst_element_signal_eos:
1258 * @element: element to trigger the eos signal of
1260 * Throws the eos signal to indicate that the end of the stream is reached.
1263 gst_element_signal_eos (GstElement *element)
1265 g_return_if_fail (element != NULL);
1266 g_return_if_fail (GST_IS_ELEMENT (element));
1268 GST_DEBUG(GST_CAT_EVENT, "signaling EOS on element %s\n",GST_OBJECT_NAME(element));
1269 g_signal_emit (G_OBJECT (element), gst_element_signals[EOS], 0);
1270 GST_FLAG_SET(element,GST_ELEMENT_COTHREAD_STOPPING);
1275 * gst_element_statename:
1276 * @state: The state to get the name of
1278 * Gets a string representing the given state.
1280 * Returns: a string with the statename.
1283 gst_element_statename (GstElementState state)
1286 #ifdef GST_DEBUG_COLOR
1287 case GST_STATE_VOID_PENDING: return "NONE_PENDING";break;
1288 case GST_STATE_NULL: return "\033[01;37mNULL\033[00m";break;
1289 case GST_STATE_READY: return "\033[01;31mREADY\033[00m";break;
1290 case GST_STATE_PLAYING: return "\033[01;32mPLAYING\033[00m";break;
1291 case GST_STATE_PAUSED: return "\033[01;33mPAUSED\033[00m";break;
1292 default: return g_strdup_printf ("\033[01;37;41mUNKNOWN!\033[00m(%d)", state);
1294 case GST_STATE_VOID_PENDING: return "NONE_PENDING";break;
1295 case GST_STATE_NULL: return "NULL";break;
1296 case GST_STATE_READY: return "READY";break;
1297 case GST_STATE_PLAYING: return "PLAYING";break;
1298 case GST_STATE_PAUSED: return "PAUSED";break;
1299 default: return "UNKNOWN!";
1306 gst_element_populate_std_props (GObjectClass * klass,
1307 const char *prop_name, guint arg_id, GParamFlags flags)
1309 GQuark prop_id = g_quark_from_string (prop_name);
1312 static GQuark fd_id = 0;
1313 static GQuark blocksize_id;
1314 static GQuark bytesperread_id;
1315 static GQuark dump_id;
1316 static GQuark filesize_id;
1317 static GQuark mmapsize_id;
1318 static GQuark location_id;
1319 static GQuark offset_id;
1320 static GQuark silent_id;
1321 static GQuark touch_id;
1324 fd_id = g_quark_from_static_string ("fd");
1325 blocksize_id = g_quark_from_static_string ("blocksize");
1326 bytesperread_id = g_quark_from_static_string ("bytesperread");
1327 dump_id = g_quark_from_static_string ("dump");
1328 filesize_id = g_quark_from_static_string ("filesize");
1329 mmapsize_id = g_quark_from_static_string ("mmapsize");
1330 location_id = g_quark_from_static_string ("location");
1331 offset_id = g_quark_from_static_string ("offset");
1332 silent_id = g_quark_from_static_string ("silent");
1333 touch_id = g_quark_from_static_string ("touch");
1336 if (prop_id == fd_id) {
1337 pspec = g_param_spec_int ("fd", "File-descriptor",
1338 "File-descriptor for the file being read", 0, G_MAXINT, 0, flags);
1341 else if (prop_id == blocksize_id) {
1342 pspec = g_param_spec_ulong ("blocksize", "Block Size",
1343 "Block size to read per buffer", 0, G_MAXULONG, 4096, flags);
1346 else if (prop_id == bytesperread_id) {
1347 pspec = g_param_spec_int ("bytesperread", "bytesperread", "bytesperread",
1348 G_MININT, G_MAXINT, 0, flags);
1351 else if (prop_id == dump_id) {
1352 pspec = g_param_spec_boolean ("dump", "dump", "dump", FALSE, flags);
1355 else if (prop_id == filesize_id) {
1356 pspec = g_param_spec_int64 ("filesize", "File Size",
1357 "Size of the file being read", 0, G_MAXINT64, 0, flags);
1360 else if (prop_id == mmapsize_id) {
1361 pspec = g_param_spec_ulong ("mmapsize", "mmap() Block Size",
1362 "Size in bytes of mmap()d regions",
1363 0, G_MAXULONG, 4 * 1048576, flags);
1366 else if (prop_id == location_id) {
1367 pspec = g_param_spec_string ("location", "File Location",
1368 "Location of the file to read", NULL, flags);
1371 else if (prop_id == offset_id) {
1372 pspec = g_param_spec_int64 ("offset", "File Offset",
1373 "Byte offset of current read pointer", 0, G_MAXINT64, 0, flags);
1376 else if (prop_id == silent_id) {
1377 pspec = g_param_spec_boolean ("silent", "silent", "silent", FALSE, flags);
1380 else if (prop_id == touch_id) {
1381 pspec = g_param_spec_boolean ("touch", "Touch read data",
1382 "Touch data to force disk read before push ()", TRUE, flags);
1385 g_warning ("Unknown - 'standard' property '%s' id %d on class %s",
1387 g_type_name_from_class ((GTypeClass *) klass));
1392 g_object_class_install_property (klass, arg_id, pspec);
1397 * gst_element_install_std_props:
1398 * @klass: the class to add the properties to
1399 * @first_name: the first in a NULL terminated
1400 * 'name', 'id', 'flags' triplet list.
1402 * Add a list of standardized properties with types to the @klass.
1403 * the id is for the property switch in your get_prop method, and
1404 * the flags determine readability / writeability.
1407 gst_element_install_std_props (GstElementClass * klass, const char *first_name, ...)
1413 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1415 va_start (args, first_name);
1420 int arg_id = va_arg (args, int);
1421 int flags = va_arg (args, int);
1423 gst_element_populate_std_props ((GObjectClass *) klass, name, arg_id, flags);
1425 name = va_arg (args, char *);