/**
* SECTION:gstelement
+ * @title: GstElement
* @short_description: Abstract base class for all pipeline elements
* @see_also: #GstElementFactory, #GstPad
*
* @element: a #GstElement to query
*
* Get the clock provided by the given element.
- * <note>An element is only required to provide a clock in the PAUSED
- * state. Some elements can provide a clock in other states.</note>
+ * > An element is only required to provide a clock in the PAUSED
+ * > state. Some elements can provide a clock in other states.
*
* Returns: (transfer full) (nullable): the GstClock provided by the
* element or %NULL if no clock could be provided. Unref after usage.
/**
* gst_element_set_clock:
* @element: a #GstElement to set the clock for.
- * @clock: the #GstClock to set for the element.
+ * @clock: (transfer none) (allow-none): the #GstClock to set for the element.
*
* Sets the clock for the element. This function increases the
* refcount on the clock. Any previously set clock on the object
* Elements in a pipeline will only have their clock set when the
* pipeline is in the PLAYING state.
*
- * Returns: (transfer full): the #GstClock of the element. unref after usage.
+ * Returns: (transfer full) (nullable): the #GstClock of the element. unref after usage.
*
* MT safe.
*/
/**
* gst_element_add_pad:
* @element: a #GstElement to add the pad to.
- * @pad: (transfer full): the #GstPad to add to the element.
+ * @pad: (transfer floating): the #GstPad to add to the element.
*
* Adds a pad (link point) to @element. @pad's parent will be set to @element;
* see gst_object_set_parent() for refcounting information.
*
- * Pads are not automatically activated so elements should perform the needed
- * steps to activate the pad in case this pad is added in the PAUSED or PLAYING
- * state. See gst_pad_set_active() for more information about activating pads.
+ * Pads are automatically activated when added in the PAUSED or PLAYING
+ * state.
*
* The pad and the element should be unlocked when calling this function.
*
/* check for active pads */
if (!active && (GST_STATE (element) > GST_STATE_READY ||
GST_STATE_NEXT (element) == GST_STATE_PAUSED)) {
- g_warning ("adding inactive pad '%s' to running element '%s', you need to "
- "use gst_pad_set_active(pad,TRUE) before adding it.",
- GST_STR_NULL (pad_name), GST_ELEMENT_NAME (element));
gst_pad_set_active (pad, TRUE);
}
pad_name, GST_ELEMENT_NAME (element));
GST_OBJECT_UNLOCK (element);
g_free (pad_name);
+ gst_object_ref_sink (pad);
+ gst_object_unref (pad);
return FALSE;
}
had_parent:
/**
* gst_element_remove_pad:
* @element: a #GstElement to remove pad from.
- * @pad: (transfer full): the #GstPad to remove from the element.
+ * @pad: (transfer none): the #GstPad to remove from the element.
*
* Removes @pad from @element. @pad will be destroyed if it has not been
* referenced elsewhere using gst_object_unparent().
return gst_element_iterate_pad_list (element, &element->sinkpads);
}
+static gboolean
+gst_element_do_foreach_pad (GstElement * element,
+ GstElementForeachPadFunc func, gpointer user_data,
+ GList ** p_pads, guint16 * p_npads)
+{
+ gboolean ret = TRUE;
+ GstPad **pads;
+ guint n_pads, i;
+ GList *l;
+
+ g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
+ g_return_val_if_fail (func != NULL, FALSE);
+
+ GST_OBJECT_LOCK (element);
+ n_pads = *p_npads;
+ pads = g_newa (GstPad *, n_pads + 1);
+ for (l = *p_pads, i = 0; l != NULL; l = l->next) {
+ g_assert (i < n_pads);
+ pads[i++] = gst_object_ref (l->data);
+ }
+ GST_OBJECT_UNLOCK (element);
+
+ if (n_pads == 0)
+ return FALSE;
+
+ for (i = 0; i < n_pads; ++i) {
+ ret = func (element, pads[i], user_data);
+ if (!ret)
+ break;
+ }
+
+ for (i = 0; i < n_pads; ++i)
+ gst_object_unref (pads[i]);
+
+ return ret;
+}
+
+/**
+ * gst_element_foreach_sink_pad:
+ * @element: a #GstElement to iterate sink pads of
+ * @func: (scope call): function to call for each sink pad
+ * @user_data: (closure): user data passed to @func
+ *
+ * Call @func with @user_data for each of @element's sink pads. @func will be
+ * called exactly once for each sink pad that exists at the time of this call,
+ * unless one of the calls to @func returns %FALSE in which case we will stop
+ * iterating pads and return early. If new sink pads are added or sink pads
+ * are removed while the sink pads are being iterated, this will not be taken
+ * into account until next time this function is used.
+ *
+ * Returns: %FALSE if @element had no sink pads or if one of the calls to @func
+ * returned %FALSE.
+ *
+ * Since: 1.14
+ */
+gboolean
+gst_element_foreach_sink_pad (GstElement * element,
+ GstElementForeachPadFunc func, gpointer user_data)
+{
+ return gst_element_do_foreach_pad (element, func, user_data,
+ &element->sinkpads, &element->numsinkpads);
+}
+
+/**
+ * gst_element_foreach_src_pad:
+ * @element: a #GstElement to iterate source pads of
+ * @func: (scope call): function to call for each source pad
+ * @user_data: (closure): user data passed to @func
+ *
+ * Call @func with @user_data for each of @element's source pads. @func will be
+ * called exactly once for each source pad that exists at the time of this call,
+ * unless one of the calls to @func returns %FALSE in which case we will stop
+ * iterating pads and return early. If new source pads are added or source pads
+ * are removed while the source pads are being iterated, this will not be taken
+ * into account until next time this function is used.
+ *
+ * Returns: %FALSE if @element had no source pads or if one of the calls
+ * to @func returned %FALSE.
+ *
+ * Since: 1.14
+ */
+gboolean
+gst_element_foreach_src_pad (GstElement * element,
+ GstElementForeachPadFunc func, gpointer user_data)
+{
+ return gst_element_do_foreach_pad (element, func, user_data,
+ &element->srcpads, &element->numsrcpads);
+}
+
+/**
+ * gst_element_foreach_pad:
+ * @element: a #GstElement to iterate pads of
+ * @func: (scope call): function to call for each pad
+ * @user_data: (closure): user data passed to @func
+ *
+ * Call @func with @user_data for each of @element's pads. @func will be called
+ * exactly once for each pad that exists at the time of this call, unless
+ * one of the calls to @func returns %FALSE in which case we will stop
+ * iterating pads and return early. If new pads are added or pads are removed
+ * while pads are being iterated, this will not be taken into account until
+ * next time this function is used.
+ *
+ * Returns: %FALSE if @element had no pads or if one of the calls to @func
+ * returned %FALSE.
+ *
+ * Since: 1.14
+ */
+gboolean
+gst_element_foreach_pad (GstElement * element, GstElementForeachPadFunc func,
+ gpointer user_data)
+{
+ return gst_element_do_foreach_pad (element, func, user_data,
+ &element->pads, &element->numpads);
+}
+
/**
* gst_element_class_add_pad_template:
* @klass: the #GstElementClass to add the pad template to.
- * @templ: (transfer full): a #GstPadTemplate to add to the element class.
+ * @templ: (transfer floating): a #GstPadTemplate to add to the element class.
*
* Adds a padtemplate to an element class. This is mainly used in the _class_init
* functions of classes. If a pad template with the same name as an already
* existing one is added the old one is replaced by the new one.
*
+ * @templ's reference count will be incremented, and any floating
+ * reference will be removed (see gst_object_ref_sink())
+ *
*/
void
gst_element_class_add_pad_template (GstElementClass * klass,
/* Found pad with the same name, replace and return */
if (strcmp (templ->name_template, padtempl->name_template) == 0) {
+ gst_object_ref_sink (padtempl);
gst_object_unref (padtempl);
template_list->data = templ;
return;
}
/**
+ * gst_element_class_add_static_pad_template_with_gtype:
+ * @klass: the #GstElementClass to add the pad template to.
+ * @static_templ: #GstStaticPadTemplate to add as pad template to the element class.
+ * @pad_type: The #GType of the pad to create
+ *
+ * Adds a pad template to an element class based on the static pad template
+ * @templ. This is mainly used in the _class_init functions of element
+ * implementations. If a pad template with the same name already exists,
+ * the old one is replaced by the new one.
+ *
+ * Since: 1.14
+ */
+void
+gst_element_class_add_static_pad_template_with_gtype (GstElementClass * klass,
+ GstStaticPadTemplate * static_templ, GType pad_type)
+{
+ gst_element_class_add_pad_template (klass,
+ gst_pad_template_new_from_static_pad_template_with_gtype (static_templ,
+ pad_type));
+}
+
+/**
* gst_element_class_add_metadata:
* @klass: class to set metadata for
* @key: the key to set
* multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
*
* Sets the detailed information for a #GstElementClass.
- * <note>This function is for use in _class_init functions only.</note>
+ * > This function is for use in _class_init functions only.
*/
void
gst_element_class_set_metadata (GstElementClass * klass,
* multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
*
* Sets the detailed information for a #GstElementClass.
- * <note>This function is for use in _class_init functions only.</note>
+ *
+ * > This function is for use in _class_init functions only.
*
* Same as gst_element_class_set_metadata(), but @longname, @classification,
* @description, and @author must be static strings or inlined strings, as
}
/**
+ * gst_element_get_metadata:
+ * @element: class to get metadata for
+ * @key: the key to get
+ *
+ * Get metadata with @key in @klass.
+ *
+ * Returns: the metadata for @key.
+ *
+ * Since: 1.14
+ */
+const gchar *
+gst_element_get_metadata (GstElement * element, const gchar * key)
+{
+ g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
+ g_return_val_if_fail (key != NULL, NULL);
+
+ return gst_element_class_get_metadata (GST_ELEMENT_GET_CLASS (element), key);
+}
+
+/**
* gst_element_class_get_pad_template_list:
* @element_class: a #GstElementClass to get pad templates of.
*
* Retrieves a list of the pad templates associated with @element_class. The
* list must not be modified by the calling code.
- * <note>If you use this function in the #GInstanceInitFunc of an object class
- * that has subclasses, make sure to pass the g_class parameter of the
- * #GInstanceInitFunc here.</note>
+ * > If you use this function in the #GInstanceInitFunc of an object class
+ * > that has subclasses, make sure to pass the g_class parameter of the
+ * > #GInstanceInitFunc here.
*
* Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
* pad templates.
}
/**
+ * gst_element_get_pad_template_list:
+ * @element: a #GstElement to get pad templates of.
+ *
+ * Retrieves a list of the pad templates associated with @element. The
+ * list must not be modified by the calling code.
+ *
+ * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
+ * pad templates.
+ *
+ * Since: 1.14
+ */
+GList *
+gst_element_get_pad_template_list (GstElement * element)
+{
+ g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
+
+ return
+ gst_element_class_get_pad_template_list (GST_ELEMENT_GET_CLASS (element));
+}
+
+/**
* gst_element_class_get_pad_template:
* @element_class: a #GstElementClass to get the pad template of.
* @name: the name of the #GstPadTemplate to get.
*
* Retrieves a padtemplate from @element_class with the given name.
- * <note>If you use this function in the #GInstanceInitFunc of an object class
- * that has subclasses, make sure to pass the g_class parameter of the
- * #GInstanceInitFunc here.</note>
+ * > If you use this function in the #GInstanceInitFunc of an object class
+ * > that has subclasses, make sure to pass the g_class parameter of the
+ * > #GInstanceInitFunc here.
*
* Returns: (transfer none) (nullable): the #GstPadTemplate with the
* given name, or %NULL if none was found. No unreferencing is
return NULL;
}
+/**
+ * gst_element_get_pad_template:
+ * @element: a #GstElement to get the pad template of.
+ * @name: the name of the #GstPadTemplate to get.
+ *
+ * Retrieves a padtemplate from @element with the given name.
+ *
+ * Returns: (transfer none) (nullable): the #GstPadTemplate with the
+ * given name, or %NULL if none was found. No unreferencing is
+ * necessary.
+ *
+ * Since: 1.14
+ */
+GstPadTemplate *
+gst_element_get_pad_template (GstElement * element, const gchar * name)
+{
+ g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
+ g_return_val_if_fail (name != NULL, NULL);
+
+ return gst_element_class_get_pad_template (GST_ELEMENT_GET_CLASS (element),
+ name);
+}
+
static GstPadTemplate *
gst_element_class_get_request_pad_template (GstElementClass *
element_class, const gchar * name)
}
/* get a random pad on element of the given direction.
- * The pad is random in a sense that it is the first pad that is (optionaly) linked.
+ * The pad is random in a sense that it is the first pad that is (optionally) linked.
*/
static GstPad *
gst_element_get_random_pad (GstElement * element,
if (pending)
*pending = GST_STATE_VOID_PENDING;
- GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
+ GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interrupted");
GST_OBJECT_UNLOCK (element);
* This method is used internally and should normally not be called by plugins
* or applications.
*
+ * This function must be called with STATE_LOCK held.
+ *
* Returns: The result of the commit state change.
*
* MT safe.
case GST_STATE_CHANGE_SUCCESS:
GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
"element changed state SUCCESS");
- /* we can commit the state now which will proceeed to
+ /* we can commit the state now which will proceed to
* the next state */
ret = gst_element_continue_state (element, ret);
break;
case GST_STATE_CHANGE_NO_PREROLL:
GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
"element changed state NO_PREROLL");
- /* we can commit the state now which will proceeed to
+ /* we can commit the state now which will proceed to
* the next state */
ret = gst_element_continue_state (element, ret);
break;
/**
* gst_element_set_bus:
* @element: a #GstElement to set the bus of.
- * @bus: (transfer none): the #GstBus to set.
+ * @bus: (transfer none) (allow-none): the #GstBus to set.
*
* Sets the bus of the element. Increases the refcount on the bus.
* For internal use only, unless you're testing elements.
* Returns the bus of the element. Note that only a #GstPipeline will provide a
* bus for the application.
*
- * Returns: (transfer full): the element's #GstBus. unref after usage.
+ * Returns: (transfer full) (nullable): the element's #GstBus. unref after
+ * usage.
*
* MT safe.
*/
*
* Gets the context with @context_type set on the element or NULL.
*
- * Returns: (transfer full): A #GstContext or NULL
+ * Returns: (transfer full) (nullable): A #GstContext or NULL
*
* Since: 1.8
*/