gnomemm r1482 - in gstreamermm/trunk: . examples/optiongroup gstreamer/gstreamermm gstreamer/src

[jaalburqu svn gnome org]

Author: jaalburqu
Date: Tue Apr 29 20:36:12 2008
New Revision: 1482
URL: http://svn.gnome.org/viewvc/gnomemm?rev=1482&view=rev

Log:
2008-04-29  Josà Alburquerque  <jaalburqu svn gnome org>

	* gstreamer/gstreamermm/gst_wrap_init.h:
	* gstreamer/gstreamermm/wrap_init.h:
	* gstreamer/gstreamermm/version.h: Added gst_wrap_init(), wrap_init(),
	and version() method docs

	* gstreamer/gstreamermm/init.cc:
	* gstreamer/gstreamermm/init.h:
	* examples/optiongroup/optiongroup.cc: Renamed init_get_option_group()
	to get_option_group(); Added init(), init_check() and
	get_option_group() method docs; Modified init_check() to throw
	Glib::Error if GLIBMM_EXCEPTIONS_ENABLED

	* gstreamer/src/event.hg: Added get_name() and get_quark() function
	docs

	* gstreamer/src/plugin.hg:
	* gstreamer/src/gst_docs_override.xml: Wrapped PluginError as a
	GError (and not an Enum); Modified load_file() method docs (and added
	@throw directive to docs)

	* gstreamer/src/pluginfeature.hg: Removed unused blank line

Modified:
   gstreamermm/trunk/ChangeLog
   gstreamermm/trunk/examples/optiongroup/optiongroup.cc
   gstreamermm/trunk/gstreamer/gstreamermm/gst_wrap_init.h
   gstreamermm/trunk/gstreamer/gstreamermm/init.cc
   gstreamermm/trunk/gstreamer/gstreamermm/init.h
   gstreamermm/trunk/gstreamer/gstreamermm/version.h
   gstreamermm/trunk/gstreamer/gstreamermm/wrap_init.h
   gstreamermm/trunk/gstreamer/src/event.hg
   gstreamermm/trunk/gstreamer/src/gst_docs_override.xml
   gstreamermm/trunk/gstreamer/src/plugin.hg
   gstreamermm/trunk/gstreamer/src/pluginfeature.hg

Modified: gstreamermm/trunk/examples/optiongroup/optiongroup.cc
==============================================================================
--- gstreamermm/trunk/examples/optiongroup/optiongroup.cc	(original)
+++ gstreamermm/trunk/examples/optiongroup/optiongroup.cc	Tue Apr 29 20:36:12 2008
@@ -54,7 +54,7 @@
 
   m_OptionContext.set_main_group(m_OptionGroup);
 
-  Glib::OptionGroup m_GstOptiongroup = Gst::init_get_option_group();
+  Glib::OptionGroup m_GstOptiongroup = Gst::get_option_group();
   m_OptionContext.add_group(m_GstOptiongroup);
 
   try

Modified: gstreamermm/trunk/gstreamer/gstreamermm/gst_wrap_init.h
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/gst_wrap_init.h	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/gst_wrap_init.h	Tue Apr 29 20:36:12 2008
@@ -26,6 +26,10 @@
 
 namespace Gst
 {
+  /** Initializes wrapping system of Gst::MiniObject derrived classes.  There
+   * is no need to use this function directly; instead use Gst::init() or
+   * Gst::init_check().
+   */
   void gst_wrap_init();
 }
 

Modified: gstreamermm/trunk/gstreamer/gstreamermm/init.cc
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/init.cc	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/init.cc	Tue Apr 29 20:36:12 2008
@@ -50,17 +50,29 @@
   }
 }
 
-bool init_check(int& argc, char**& argv, Glib::Error& error)
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+bool init_check(int& argc, char**& argv)
+#else
+bool init_check(int& argc, char**& argv, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
 {
   Glib::init();
-  GError* c_error;
-  bool result = gst_init_check(&argc, &argv, &c_error);
-  error = Glib::Error(c_error);
+  GError* gerror = 0;
+  bool result = gst_init_check(&argc, &argv, &gerror);
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+#else
+  if(gerror)
+    error = ::Glib::Error::throw_exception(gerror);
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+
   Gst::wrap_init();
   return result;
 }
 
-Glib::OptionGroup init_get_option_group()
+Glib::OptionGroup get_option_group()
 {
   return Glib::OptionGroup(gst_init_get_option_group());
 }

Modified: gstreamermm/trunk/gstreamer/gstreamermm/init.h
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/init.h	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/init.h	Tue Apr 29 20:36:12 2008
@@ -28,9 +28,62 @@
 namespace Gst
 {
 
+/** Initializes the GStreamer library, setting up internal path lists,
+ * registering built-in elements, and loading standard plugins.
+ *
+ * This function should be called before calling any other GLib functions. If
+ * this is not an option, your program must initialise the GLib thread system
+ * using g_thread_init() before any other GLib functions are called.
+ *
+ * Note: This function will terminate your program if it was unable to
+ * initialize GStreamer for some reason. If you want your program to fall back,
+ * use Gst::init_check() instead.
+ *
+ * WARNING: This function does not work in the same way as corresponding
+ * functions in other glib-style libraries, such as gtk_init(). In particular,
+ * unknown command line options cause this function to abort program execution.
+ *
+ * @param argc pointer to application's argc
+ * @param argv pointer to application's argv
+ */
 void init(int& argc, char**& argv);
-bool init_check(int& argc, char**& argv, Glib::Error& error);
-Glib::OptionGroup init_get_option_group();
+
+/** Initializes the GStreamer library, setting up internal path lists,
+ * registering built-in elements, and loading standard plugins.
+ *
+ * This function will return FALSE if GStreamer could not be initialized for
+ * some reason. If you want your program to fail fatally, use Gst::init()
+ * instead.
+ *
+ * This function should be called before calling any other GLib functions. If
+ * this is not an option, your program must initialise the GLib thread system
+ * using g_thread_init() before any other GLib functions are called.
+ *
+ * @param argc pointer to application's argc
+ * @param argv pointer to application's argv
+ * @return TRUE if GStreamer could be initialized.
+ * @throw Glib::Error
+ */
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool init_check(int& argc, char**& argv);
+#else
+  bool init_check(int& argc, char**& argv, std::auto_ptr<Glib::Error>& error);
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+
+/** Returns a Glib::OptionGroup with GStreamer's argument specifications. The
+ * group is set up to use standard GOption callbacks, so when using this group
+ * in combination with GOption parsing methods, all argument parsing and
+ * initialization is automated.
+ *
+ * This function is useful if you want to integrate GStreamer with other
+ * libraries that use GOption (see g_option_context_add_group() ).
+ *
+ * If you use this function, you should make sure you initialise the GLib
+ * threading system as one of the very first things in your program.
+ *
+ * @return a pointer to GStreamer's option group.
+ */
+Glib::OptionGroup get_option_group();
   
 }//end namespace Gst
 

Modified: gstreamermm/trunk/gstreamer/gstreamermm/version.h
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/version.h	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/version.h	Tue Apr 29 20:36:12 2008
@@ -24,7 +24,15 @@
 
 namespace Gst
 {
+
+  /** Gets the version number of the gstreamermm library.
+   *
+   * @param major pointer to a guint to store the major version number
+   * @param minor pointer to a guint to store the minor version number
+   * @param micro pointer to a guint to store the micro version number
+   */
   void version(guint& major, guint& minor, guint& micro);
+
 }//end namespace Gst
 
 #endif //_GSTREAMERMM_VERSION_H

Modified: gstreamermm/trunk/gstreamer/gstreamermm/wrap_init.h
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/wrap_init.h	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/wrap_init.h	Tue Apr 29 20:36:12 2008
@@ -26,6 +26,9 @@
 
 namespace Gst
 {
+  /** Initializes the main gstreamermm wrapping system.  There's no need to use
+   * this function directly; instead use Gst::init() or Gst::init_check().
+   */
   void wrap_init();
 }
 

Modified: gstreamermm/trunk/gstreamer/src/event.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/event.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/event.hg	Tue Apr 29 20:36:12 2008
@@ -59,7 +59,18 @@
 _WRAP_ENUM(SeekFlags, GstSeekFlags)
 _WRAP_ENUM(EventTypeFlags, GstEventTypeFlags)
 
+/** Get a printable name for the given event type.
+ *
+ * @param type the event type
+ * @return a reference to the static name of the event.
+ */
 Glib::ustring get_name(EventType t);
+
+/** Get the unique quark for the given event type.
+ *
+ * @param type the event type
+ * @return the quark associated with the event type 
+ */
 Glib::QueryQuark get_quark(EventType t);
 
 /** Gst::Event â A structure describing events that are passed up and down a

Modified: gstreamermm/trunk/gstreamer/src/gst_docs_override.xml
==============================================================================
--- gstreamermm/trunk/gstreamer/src/gst_docs_override.xml	(original)
+++ gstreamermm/trunk/gstreamer/src/gst_docs_override.xml	Tue Apr 29 20:36:12 2008
@@ -1,2 +1,21 @@
 <root>
+<function name="gst_plugin_load_file">
+<description>
+Loads a plugin from file.
+</description>
+<parameters>
+<parameter name="filename">
+<parameter_description> the plugin filename to load
+</parameter_description>
+</parameter>
+<parameter name="error">
+<parameter_description> pointer to a NULL-valued GError
+</parameter_description>
+</parameter>
+</parameters>
+<return> a reference to the existing loaded GstPlugin, a reference to the
+newly-loaded GstPlugin, or NULL if an error occurred.
+</return>
+</function>
+
 </root>

Modified: gstreamermm/trunk/gstreamer/src/plugin.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/plugin.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/plugin.hg	Tue Apr 29 20:36:12 2008
@@ -27,7 +27,13 @@
 namespace Gst
 {
 
-_WRAP_ENUM(PluginError, GstPluginError)
+/** The plugin loading errors
+ *
+ * - MODULE - The plugin could not be loaded
+ * - DEPENDENCIES - The plugin has unresolved dependencies
+ * - NAME_MISMATCH - The plugin has already be loaded from a different file
+ */
+_WRAP_GERROR(PluginError, GstPluginError, GST_PLUGIN_ERROR)
 
 //TODO: Edit references below to use gstreamermm classes/methods
 
@@ -79,7 +85,9 @@
 
   _WRAP_METHOD(bool is_loaded() const, gst_plugin_is_loaded)
 
-  _WRAP_METHOD(static Glib::RefPtr<Plugin> load_file(const Glib::ustring& name), gst_plugin_load_file, errthrow)
+  /** @throw Gst::PluginError
+   */
+  _WRAP_METHOD(static Glib::RefPtr<Plugin> load_file(const Glib::ustring& filename), gst_plugin_load_file, errthrow)
 
   _WRAP_METHOD(Glib::RefPtr<Plugin> load(), gst_plugin_load)
   _WRAP_METHOD(static Glib::RefPtr<Plugin> load_by_name(const Glib::ustring& name), gst_plugin_load_by_name)

Modified: gstreamermm/trunk/gstreamer/src/pluginfeature.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/pluginfeature.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/pluginfeature.hg	Tue Apr 29 20:36:12 2008
@@ -53,7 +53,6 @@
   _WRAP_METHOD(bool check_version(guint min_major, guint min_minor, guint min_micro) const, gst_plugin_feature_check_version)
 
   _IGNORE(gst_plugin_feature_type_name_filter)
-
 };
 
 } // namespace Gst