diff --git a/ChangeLog b/ChangeLog index df773dde93..ee93a9936f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2005-09-25 Stefan Kost + + * docs/gst/.cvsignore: + * docs/gst/tmpl/.cvsignore: + * docs/gst/tmpl/gstpipeline.sgml: + * docs/gst/tmpl/gstplugin.sgml: + * gst/gstpipeline.c: + * gst/gstplugin.c: + * gst/gstplugin.h: + inlined the last two docs files + removed the tmpl directory from cvs (no more conflicts here!) + 2005-09-25 Stefan Kost * docs/gst/gstreamer-sections.txt: diff --git a/docs/gst/.gitignore b/docs/gst/.gitignore index b932cdf15e..9d2ca3c01a 100644 --- a/docs/gst/.gitignore +++ b/docs/gst/.gitignore @@ -13,6 +13,7 @@ gstreamer.signals html sgml +tmpl *.stamp gstreamer.html diff --git a/docs/gst/tmpl/.gitignore b/docs/gst/tmpl/.gitignore deleted file mode 100644 index af468c14c1..0000000000 --- a/docs/gst/tmpl/.gitignore +++ /dev/null @@ -1,67 +0,0 @@ -*.bak -unused-build.stamp -gst.sgml -gstadapter.sgml -gstbasesink.sgml -gstbasesrc.sgml -gstbasetransform.sgml -gstbin.sgml -gstbuffer.sgml -gstbus.sgml -gstcaps.sgml -gstcheck.sgml -gstclock.sgml -gstchildproxy.sgml -gstcollectpads.sgml -gstcompat.sgml -gstconfig.sgml -gstelement.sgml -gstelementdetails.sgml -gstelementfactory.sgml -gstenumtypes.sgml -gstevent.sgml -gsterror.sgml -gstfakesrc.sgml -gstfakesink.sgml -gstfilesrc.sgml -gstfilesink.sgml -gstfilter.sgml -gstformat.sgml -gstghostpad.sgml -gstimplementsinterface.sgml -gstindex.sgml -gstindexfactory.sgml -gstinfo.sgml -gstiterator.sgml -gstmacros.sgml -gstmemchunk.sgml -gstmessage.sgml -gstminiobject.sgml -gstobject.sgml -gstpad.sgml -gstpadtemplate.sgml -gstparse.sgml -gstpluginfeature.sgml -gstpushsrc.sgml -gstqueue.sgml -gstquery.sgml -gstreamer-unused.sgml -gstregistry.sgml -gstregistrypool.sgml -gststructure.sgml -gstsystemclock.sgml -gsttaglist.sgml -gsttagsetter.sgml -gsttask.sgml -gsttrace.sgml -gsttrashstack.sgml -gsttypefind.sgml -gsttypefindfactory.sgml -gsttypes.sgml -gsturihandler.sgml -gsturitype.sgml -gstutils.sgml -gstvalue.sgml -gstversion.sgml -gstxml.sgml -gstxmlregistry.sgml diff --git a/docs/gst/tmpl/gstpipeline.sgml b/docs/gst/tmpl/gstpipeline.sgml deleted file mode 100644 index a5010b823f..0000000000 --- a/docs/gst/tmpl/gstpipeline.sgml +++ /dev/null @@ -1,125 +0,0 @@ - -GstPipeline - - -Top-level bin with scheduling and pipeline management functionality. - - - -In almost all cases, you'll want to use a GstPipeline when creating a -filter graph. The GstPipeline will manage all the scheduling issues, -including threading, as well as provide simple interfaces to common -functions, like 'Play'. - - -gst_pipeline_new() is used to create a pipeline. when you are done with -the pipeline, use gst_object_unref() to free its resources. - - - - -#GstBin - - - - - - - - - - -@fixed_clock: -@stream_time: -@delay: -@play_timeout: - - - - - - - - - - - - - - - - -@GST_PIPELINE_FLAG_FIXED_CLOCK: -@GST_PIPELINE_FLAG_LAST: - - - - - - -@name: -@Returns: - - - - - - - -@pipeline: - - - - - - - -@pipeline: -@Returns: - - - - - - - -@pipeline: -@Returns: - - - - - - - -@pipeline: -@Returns: - - - - - - - -@pipeline: -@clock: - - - - - - - -@pipeline: -@time: - - - - - - - -@pipeline: -@clock: - - diff --git a/docs/gst/tmpl/gstplugin.sgml b/docs/gst/tmpl/gstplugin.sgml deleted file mode 100644 index 3e1cf62291..0000000000 --- a/docs/gst/tmpl/gstplugin.sgml +++ /dev/null @@ -1,304 +0,0 @@ - -GstPlugin - - -Container for features loaded from a shared object module - - - -GStreamer is extensible, so GstElements can be loaded at runtime. -A plugin system can provide one or more of the basic GStreamer -#GstPluginFeature subclasses. - - -A plugin should export a symbol plugin_desc that is a struct of type #GstPluginDesc. -the plugin loader will check the version of the core library the plugin was linked against -and will create a new #GstPlugin. It will then call the #GstPluginInitFunc function -that was provided in the plugin_desc. - - -Once you have a handle to a #GstPlugin (e.g. from the #GstRegistryPool), you can -add any object that subclasses #GstPluginFeature. - - -Use gst_plugin_find_feature() and gst_plugin_get_feature_list() to find features in a plugin. - - -Usually plugins are always automaticlly loaded so you don't need to call gst_plugin_load() explicitly -to bring it into memory. There are options to statically link plugins to an app or even -use GStreamer without a plugin repository in which case gst_plugin_load() can be needed -to bring the plugin into memory. - - - - -#GstPluginFeature, #GstType, #GstAutoplug, #GstElementFactory - - - - - - - -Get the error quark - - -@Returns: The error quark used in GError messages - - - - -The error quark - - - - - - -The plugin loading errors - - -@GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded -@GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies -@GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file - - - -The plugin object - - - - - -A plugins should export a variable of this type called plugin_desc. This plugin -loaded will use this variable to initialize the plugin. - - -@major_version: the major version number of core that plugin was compiled for -@minor_version: the minor version number of core that plugin was compiled for -@name: a unique name of the plugin -@description: -@plugin_init: The init function of this plugin. -@version: version of the plugin -@license: effective license of plugin -@source: -@package: package plugin belongs to -@origin: URL to provider of plugin -@_gst_reserved: - - - -A plugin should provide a pointer to a function of this type in the plugin_desc struct. -It will be called by the loader at statup. - - -@plugin: The plugin object that can be used to register stuff for this plugin. -@Returns: A boolean indicating success or failure. - -@module: The GModule it was loaded from - - - - -This macro needs to be used to define the entry point and meta data of a plugin. -One would use this macro to export a plugin, so that it can be used by other applications - - -@major: major version number of the gstreamer-core that plugin was compiled for -@minor: minor version number of the gstreamer-core that plugin was compiled for -@name: short, but unique name of the plugin -@description: information about the purpose of the plugin -@init: function pointer to the plugin_init method with the signature of static gboolean plugin_init (GstPlugin * plugin). -@version: full version string (e.g. VERSION from config.h) -@license: under which licence the package has been released, e.g. GPL, LGPL. -@package: the package-name (e.g. PACKAGE_NAME from config.h) -@origin: a description from where the package comes from (e.g. the homepage URL) - -@domain: - - - - -This macro needs to be used to define the entry point and meta data of a local plugin. -One would use this macro to define a local plugin that can only be used by the own application. - - -@major: major version number of the gstreamer-core that plugin was compiled for -@minor: minor version number of the gstreamer-core that plugin was compiled for -@name: short, but unique name of the plugin -@description: information about the purpose of the plugin -@init: function pointer to the plugin_init method with the signature of static gboolean plugin_init (GstPlugin * plugin). -@version: full version string (e.g. VERSION from config.h) -@license: under which licence the package has been released, e.g. GPL, LGPL. -@package: the package-name (e.g. PACKAGE_NAME from config.h) -@origin: a description from where the package comes from (e.g. the homepage URL) - -@domain: - - - - - - - - - - - -A function that can be used with e.g. gst_registry_plugin_filter() -to get a list of plugins that match certain criteria. - - -@plugin: the plugin to check -@user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter() -@Returns: TRUE for a positive match, FALSE otherwise - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@Returns: - - - - - - - -@plugin: -@name: -@Returns: - - - - - - - -@filename: -@error: -@Returns: - - - - - - - -@filename: -@error: -@Returns: - - - - - - - -@plugin: -@Returns: - -@name: - - - - - - - -@name: -@Returns: - - - - - - - -@list: - - diff --git a/gst/gstpipeline.c b/gst/gstpipeline.c index 5364fee42a..92d80d3581 100644 --- a/gst/gstpipeline.c +++ b/gst/gstpipeline.c @@ -19,6 +19,20 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstpipeline + * @short_description: Top-level bin with scheduling and pipeline management functionality. + * @see_also: #GstBin + * + * In almost all cases, you'll want to use a GstPipeline when creating a filter + * graph. The GstPipeline will manage all the scheduling issues, including + * threading, as well as provide simple interfaces to common functions, like + * 'Play'. + * + * gst_pipeline_new() is used to create a pipeline. when you are done with + * the pipeline, use gst_object_unref() to free its resources including all + * added #GstElement objects (if not otherwiese referenced). + */ #include "gst_private.h" diff --git a/gst/gstplugin.c b/gst/gstplugin.c index cfbc53b9e4..1a9dde4d1b 100644 --- a/gst/gstplugin.c +++ b/gst/gstplugin.c @@ -19,6 +19,30 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstplugin + * @short_description: Container for features loaded from a shared object module + * @see_also: #GstPluginFeature, #GstElementFactory + * + * GStreamer is extensible, so #GstElement instances can be loaded at runtime. + * A plugin system can provide one or more of the basic GStreamer + * #GstPluginFeature subclasses. + * + * A plugin should export a symbol plugin_desc that is a struct of type #GstPluginDesc. + * the plugin loader will check the version of the core library the plugin was linked against + * and will create a new #GstPlugin. It will then call the #GstPluginInitFunc function + * that was provided in the plugin_desc. + * + * Once you have a handle to a #GstPlugin (e.g. from the #GstRegistryPool), you can + * add any object that subclasses #GstPluginFeature. + * + * Use gst_plugin_find_feature() and gst_plugin_get_feature_list() to find features in a plugin. + * + * Usually plugins are always automaticlly loaded so you don't need to call gst_plugin_load() explicitly + * to bring it into memory. There are options to statically link plugins to an app or even + * use GStreamer without a plugin repository in which case gst_plugin_load() can be needed + * to bring the plugin into memory. + */ #ifdef HAVE_CONFIG_H #include "config.h" diff --git a/gst/gstplugin.h b/gst/gstplugin.h index 08cacc6ea0..9213af64fc 100644 --- a/gst/gstplugin.h +++ b/gst/gstplugin.h @@ -37,9 +37,29 @@ typedef struct _GstPlugin GstPlugin; typedef struct _GstPluginClass GstPluginClass; typedef struct _GstPluginDesc GstPluginDesc; +/** + * gst_plugin_error_quark: + * + * Get the error quark. + * + * Returns: The error quark used in GError messages + */ GQuark gst_plugin_error_quark (void); +/** + * GST_PLUGIN_ERROR: + * + * The error message category quark + */ #define GST_PLUGIN_ERROR gst_plugin_error_quark () +/** + * GstPluginError: + * @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded + * @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies + * @GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file + * + * The plugin loading errors + */ typedef enum { GST_PLUGIN_ERROR_MODULE, @@ -47,25 +67,53 @@ typedef enum GST_PLUGIN_ERROR_NAME_MISMATCH } GstPluginError; + typedef enum { GST_PLUGIN_FLAG_CACHED = (1<<0), } GstPluginFlags; -/* Initialiser function: returns TRUE if plugin initialised successfully */ +/** + * GstPluginInitFunc: + * @plugin: The plugin object that can be used to register #GstPluginFeatures for this plugin. + * + * A plugin should provide a pointer to a function of this type in the + * plugin_desc struct. + * This function will be called by the loader at startup. + * + * Returns: %TRUE if plugin initialised successfully + */ typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin); +/** + * GstPluginDesc: + * @major_version: the major version number of core that plugin was compiled for + * @minor_version: the minor version number of core that plugin was compiled for + * @name: a unique name of the plugin + * @description: description of plugin + * @plugin_init: pointer to the init function of this plugin. + * @version: version of the plugin + * @license: effective license of plugin + * @source: source module plugin belongs to + * @package: shipped package plugin belongs to + * @origin: URL to provider of plugin + * @_gst_reserved: private, for later expansion + * + * + * A plugins should export a variable of this type called plugin_desc. This plugin + * loaded will use this variable to initialize the plugin. + */ struct _GstPluginDesc { - gint major_version; /* major version of core that plugin was compiled for */ - gint minor_version; /* minor version of core that plugin was compiled for */ - gchar *name; /* unique name of plugin */ - gchar *description; /* description of plugin */ - GstPluginInitFunc plugin_init; /* pointer to plugin_init function */ - gchar *version; /* version of the plugin */ - gchar *license; /* effective license of plugin */ - gchar *source; /* source module plugin belongs to */ - gchar *package; /* shipped package plugin belongs to */ - gchar *origin; /* URL to provider of plugin */ + gint major_version; + gint minor_version; + gchar *name; + gchar *description; + GstPluginInitFunc plugin_init; + gchar *version; + gchar *license; + gchar *source; + gchar *package; + gchar *origin; gpointer _gst_reserved[GST_PADDING]; }; @@ -78,7 +126,11 @@ struct _GstPluginDesc { #define GST_PLUGIN(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin)) #define GST_PLUGIN_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass)) - +/** + * GstPlugin: + * + * The plugin object + */ struct _GstPlugin { GstObject object; @@ -105,7 +157,22 @@ struct _GstPluginClass { /*< private >*/ }; - +/** + * GST_PLUGIN_DEFINE: + * @major: major version number of the gstreamer-core that plugin was compiled for + * @minor: minor version number of the gstreamer-core that plugin was compiled for + * @name: short, but unique name of the plugin + * @description: information about the purpose of the plugin + * @init: function pointer to the plugin_init method with the signature of static gboolean plugin_init (GstPlugin * plugin). + * @version: full version string (e.g. VERSION from config.h) + * @license: under which licence the package has been released, e.g. GPL, LGPL. + * @package: the package-name (e.g. PACKAGE_NAME from config.h) + * @origin: a description from where the package comes from (e.g. the homepage URL) + * + * This macro needs to be used to define the entry point and meta data of a + * plugin. One would use this macro to export a plugin, so that it can be used + * by other applications + */ #define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin) \ GST_PLUGIN_EXPORT GstPluginDesc gst_plugin_desc = { \ major, \ @@ -121,6 +188,22 @@ GST_PLUGIN_EXPORT GstPluginDesc gst_plugin_desc = { \ GST_PADDING_INIT \ }; +/** + * GST_PLUGIN_DEFINE_STATIC: + * @major: major version number of the gstreamer-core that plugin was compiled for + * @minor: minor version number of the gstreamer-core that plugin was compiled for + * @name: short, but unique name of the plugin + * @description: information about the purpose of the plugin + * @init: function pointer to the plugin_init method with the signature of static gboolean plugin_init (GstPlugin * plugin). + * @version: full version string (e.g. VERSION from config.h) + * @license: under which licence the package has been released, e.g. GPL, LGPL. + * @package: the package-name (e.g. PACKAGE_NAME from config.h) + * @origin: a description from where the package comes from (e.g. the homepage URL) + * + * This macro needs to be used to define the entry point and meta data of a + * local plugin. One would use this macro to define a local plugin that can only + * be used by the own application. + */ #define GST_PLUGIN_DEFINE_STATIC(major,minor,name,description,init,version,license,package,origin) \ static void GST_GNUC_CONSTRUCTOR \ _gst_plugin_static_init__ ##init (void) \ @@ -141,10 +224,26 @@ _gst_plugin_static_init__ ##init (void) \ _gst_plugin_register_static (&plugin_desc_); \ } +/** + * GST_LICENSE_UNKNOWN: + * + * To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about + * the licence. + */ #define GST_LICENSE_UNKNOWN "unknown" /* function for filters */ +/** + * GstPluginFilter: + * @plugin: the plugin to check + * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter() + * + * A function that can be used with e.g. gst_registry_plugin_filter() + * to get a list of plugins that match certain criteria. + * + * Returns: TRUE for a positive match, FALSE otherwise + */ typedef gboolean (*GstPluginFilter) (GstPlugin *plugin, gpointer user_data);