From 63245ea1bbe619105c6974d68118a15bcff02eda Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Tue, 14 Feb 2006 18:26:19 +0000 Subject: [PATCH] Fix padtemplate docs, fixes #328805. Original commit message from CVS: * docs/gst/gstreamer-sections.txt: * gst/gstpadtemplate.c: * gst/gstpadtemplate.h: Fix padtemplate docs, fixes #328805. --- ChangeLog | 7 +++++ docs/gst/gstreamer-sections.txt | 12 ++++---- gst/gstpadtemplate.c | 50 ++++++++++++++++++++++----------- gst/gstpadtemplate.h | 10 +++++++ 4 files changed, 56 insertions(+), 23 deletions(-) diff --git a/ChangeLog b/ChangeLog index d2ede39b77..53d4ae7d2a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2006-02-14 Wim Taymans + + * docs/gst/gstreamer-sections.txt: + * gst/gstpadtemplate.c: + * gst/gstpadtemplate.h: + Fix padtemplate docs, fixes #328805. + 2006-02-14 Wim Taymans * tools/gst-launch.c: (main): diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index a33f603759..30ccb7b92a 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -1344,18 +1344,19 @@ GST_PAD_PREROLL_WAIT
gstpadtemplate GstPadTemplate -GstPadTemplate GstStaticPadTemplate +GST_STATIC_PAD_TEMPLATE +gst_static_pad_template_get +gst_static_pad_template_get_caps +GstPadTemplate +GstPadTemplateFlags +GstPadPresence GST_PAD_TEMPLATE_NAME_TEMPLATE GST_PAD_TEMPLATE_DIRECTION GST_PAD_TEMPLATE_PRESENCE GST_PAD_TEMPLATE_CAPS GST_PAD_TEMPLATE_IS_FIXED -GstPadTemplateFlags -GstPadPresence gst_pad_template_new -gst_static_pad_template_get -gst_static_pad_template_get_caps gst_pad_template_get_caps @@ -1364,7 +1365,6 @@ GST_PAD_TEMPLATE GST_IS_PAD_TEMPLATE GST_PAD_TEMPLATE_CLASS GST_IS_PAD_TEMPLATE_CLASS -GST_STATIC_PAD_TEMPLATE GST_TYPE_PAD_TEMPLATE GST_TYPE_PAD_TEMPLATE_FLAGS GST_TYPE_STATIC_CAPS diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c index dc87156a5e..348107b3b8 100644 --- a/gst/gstpadtemplate.c +++ b/gst/gstpadtemplate.c @@ -26,16 +26,32 @@ * @see_also: #GstPad, #GstElementFactory * * Padtemplates describe the possible media types a pad or an elementfactory can - * handle. + * handle. This allows for both inspection of handled types before loading the + * element plugin as well as identifying pads on elements that are not yet + * created (request or sometimes pads). * * Pad and PadTemplates have #GstCaps attached to it to describe the media type - * they are capable of dealing with. gst_pad_template_get_caps() is used to get - * the caps of a padtemplate. It's not possible to modify the caps of a - * padtemplate after creation. + * they are capable of dealing with. gst_pad_template_get_caps() or + * GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not + * possible to modify the caps of a padtemplate after creation. * - * Padtemplates can be created with gst_pad_template_new() or with the - * convenient GST_PAD_TEMPLATE_FACTORY() macro. A padtemplate can be used to - * create a pad or to add to an elementfactory. + * PadTemplates have a #GstPadPresence property which identifies the lifetime + * of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also + * the direction of the pad can be retrieved from the #GstPadTemplate with + * GST_PAD_TEMPLATE_DIRECTION(). + * + * The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads + * because it has to be used as the name in the gst_element_request_pad_by_name() + * call to instantiate a pad from this template. + * + * Padtemplates can be created with gst_pad_template_new() or with + * gst_static_pad_template_get (), which creates a #GstPadTemplate from a + * #GstStaticPadTemplate that can be filled with the + * convenient GST_STATIC_PAD_TEMPLATE() macro. + * + * A padtemplate can be used to create a pad (see gst_pad_new_from_template() + * or gst_pad_new_from_static_template ()) or to add to an element class + * (see gst_element_class_add_pad_template ()). * * The following code example shows the code to create a pad from a padtemplate. * @@ -55,28 +71,28 @@ * my_method (void) * { * GstPad *pad; - * pad = gst_pad_new_from_template (GST_PAD_TEMPLATE_GET (my_template_factory), "sink"); + * pad = gst_pad_new_from_static_template (&my_template, "sink"); * ... * } * * * * The following example shows you how to add the padtemplate to an - * elementfactory: + * element class, this is usually done in the base_init of the class: * * - * gboolean - * my_factory_init (GstPlugin *plugin) + * static void + * my_element_base_init (gpointer g_class) * { - * GstElementFactory *factory; - * factory = gst_element_factory_new ("my_factory", GST_TYPE_MYFACTORY, &gst_myfactory_details); - * g_return_val_if_fail (factory != NULL, FALSE); - * gst_element_factory_add_pad_template (factory, GST_PAD_TEMPLATE_GET (my_template_factory)); - * gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory)); - * return TRUE; + * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class); + * + * gst_element_class_add_pad_template (gstelement_class, + * gst_static_pad_template_get (&my_template)); * } * * + * + * Last reviewed on 2006-02-14 (0.10.3) */ #include "gst_private.h" diff --git a/gst/gstpadtemplate.h b/gst/gstpadtemplate.h index 1422a59403..ac455a8918 100644 --- a/gst/gstpadtemplate.h +++ b/gst/gstpadtemplate.h @@ -157,6 +157,16 @@ struct _GstStaticPadTemplate { GstStaticCaps static_caps; }; +/** + * GST_STATIC_PAD_TEMPLATE: + * @padname: the name template of pad + * @dir: the GstPadDirection of the pad + * @pres: the GstPadPresence of the pad + * @caps: the GstStaticCaps of the pad + * + * Convenience macro to fill the values of a GstStaticPadTemplate + * structure. + */ #define GST_STATIC_PAD_TEMPLATE(padname, dir, pres, caps) \ { \ /* name_template */ padname, \