[init] Add clutter_gst_init_with_args()

A small convenient fonction that setup GOptionContext for you, adding to
the GOptionEntry array you provide the GStreamer's and Clutter's ones.

While at it, improved the documentation for the Utilities section.

3 files changed, 152 insertions, 18 deletions

diff --git a/clutter-gst/clutter-gst-util.c b/clutter-gst/clutter-gst-util.c
index 2880749..bead296 100644
--- a/clutter-gst/clutter-gst-util.c
+++ b/clutter-gst/clutter-gst-util.c
@@ -6,8 +6,10 @@
  * clutter-gst-util.c - Miscellaneous functions.
  *
  * Authored By Matthew Allum  <mallum@openedhand.com>
+ * Authored By Damien Lespiau <damien.lespiau@intel.com>
  *
  * Copyright (C) 2006 OpenedHand
+ * Copyright (C) 2009 Intel Corporation
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -25,42 +27,167 @@
  * Boston, MA 02111-1307, USA.
  */
 
-#include "clutter-gst-util.h"
-#include <gst/gst.h>
-
 /**
  * SECTION:clutter-gst-util
- * @short_description: Utility functions for ClutterGst.
+ * @short_description: Utility functions for Clutter-Gst.
+ *
+ * The <application>Clutter-Gst</application> library should be initialized
+ * with clutter_gst_init() before it can be used. You should pass pointers to
+ * the main argc and argv variables so that GStreamer, Clutter and Clutter-Gst
+ * gst can process their own command line options, as shown in the following
+ * example:
+ *
+ * <example>
+ * <title>Initializing the Clutter-Gst library</title>
+ * <programlisting language="c">
+ * int
+ * main (int argc, char *argv[])
+ * {
+ *   // initialize the Clutter-Gst library
+ *   clutter_gst_init (&amp;argc, &amp;argv);
+ *   ...
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * It's allowed to pass two NULL pointers to clutter_gst_init() in case you
+ * don't want to pass the command line arguments to GStreamer, Clutter and
+ * Clutter-Gst.
+ *
+ * You can also use a #GOptionEntry array to initialize your own parameters
+ * as shown in the next code fragment:
+ *
+ * <example>
+ * <title>Initializing the Clutter-Gst library with additional options</title>
+ * <programlisting language="c">
+ * static GOptionEntry options[] =
+ * {
+ *   { "framerate", 'f', 0, G_OPTION_ARG_INT, &opt_framerate,
+ *     "Number of frames per second", NULL },
+ *   { "fourcc", 'o', 0, G_OPTION_ARG_STRING,
+ *      &opt_fourcc, "Fourcc of the wanted YUV format", NULL },
+ *   { NULL }
+ * };
+ *
+ * int
+ * main (int argc, char *argv[])
+ * {
+ *    GError           *error = NULL;
+ *    gboolean          result;
  *
- * Various Utility functions for ClutterGst.
+ *    if (!g_thread_supported ())
+ *      g_thread_init (NULL);
+ *
+ *    result = clutter_gst_init_with_args (&argc, &argv,
+ *                                         " - Test YUV frames uploading",
+ *                                         options, NULL, &error);
+ *
+ *    if (error)
+ *      {
+ *        g_print ("%s\n", error->message);
+ *        g_error_free (error);
+ *        return EXIT_FAILURE;
+ *      }
+ *   ...
+ * }
+ * </programlisting>
+ * </example>
  */
 
+#include <gst/gst.h>
+#include <clutter/clutter.h>
+
+#include "clutter-gst-util.h"
+
+static gboolean clutter_gst_is_initialized = FALSE;
+
 /**
  * clutter_gst_init:
  * @argc: pointer to the argument list count
  * @argv: pointer to the argument list vector
  *
- * Utility function to call gst_init(), then clutter_init().
+ * Utility function to initialize both Clutter and GStreamer.
+ *
+ * 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.
  *
  * Return value: A #ClutterInitError.
  */
 ClutterInitError
 clutter_gst_init (int    *argc,
-		  char ***argv)
+                  char ***argv)
 {
-  static gboolean gst_is_initialized = FALSE;
   ClutterInitError retval;
 
-  if (!gst_is_initialized)
-    {
-      gst_init (argc, argv);
+  if (clutter_gst_is_initialized)
+    return CLUTTER_INIT_SUCCESS;
 
-      retval = clutter_init (argc, argv);
+  gst_init (argc, argv);
+  retval = clutter_init (argc, argv);
 
-      gst_is_initialized = TRUE;
-    }
-  else
-    retval = CLUTTER_INIT_SUCCESS;
+  clutter_gst_is_initialized = TRUE;
 
   return retval;
 }
+
+/**
+ * clutter_gst_init_with_args:
+ * @argc: a pointer to the number of command line arguments.
+ * @argv: a pointer to the array of command line arguments.
+ * @parameter_string: a string which is displayed in
+ *    the first line of <option>--help</option> output, after
+ *    <literal><replaceable>programname</replaceable> [OPTION...]</literal>
+ * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ *    describing the options of your program
+ * @translation_domain: a translation domain to use for translating
+ *    the <option>--help</option> output for the options in @entries
+ *    with gettext(), or %NULL
+ * @error: a return location for errors
+ *
+ * This function does the same work as clutter_gst_init(). Additionally, it
+ * allows you to add your own command line options, and it automatically
+ * generates nicely formatted --help output. Clutter's and GStreamer's
+ * #GOptionGroup<!-- -->s are added to the set of available options.
+ *
+ * Your program must initialise the GLib thread system using g_thread_init()
+ * before any other GLib functions are called.
+ *
+ * Return value: %CLUTTER_INIT_SUCCESS on success, a negative integer
+ *   on failure.
+ *
+ * Since: 1.0
+ */
+ClutterInitError
+clutter_gst_init_with_args (int            *argc,
+                            char         ***argv,
+                            const char     *parameter_string,
+                            GOptionEntry   *entries,
+                            const char     *translation_domain,
+                            GError        **error)
+{
+  GOptionContext *context;
+  gboolean res;
+
+  if (clutter_gst_is_initialized)
+    return CLUTTER_INIT_SUCCESS;
+
+  context = g_option_context_new (parameter_string);
+
+  g_option_context_add_group (context, gst_init_get_option_group ());
+  g_option_context_add_group (context, clutter_get_option_group ());
+
+  if (entries)
+    g_option_context_add_main_entries (context, entries, translation_domain);
+
+  res = g_option_context_parse (context, argc, argv, error);
+  g_option_context_free (context);
+
+  if (!res)
+        return CLUTTER_INIT_ERROR_INTERNAL;
+
+  clutter_gst_is_initialized = TRUE;
+
+  return CLUTTER_INIT_SUCCESS;
+}
+
diff --git a/clutter-gst/clutter-gst-util.h b/clutter-gst/clutter-gst-util.h
index af63d68..338d58d 100644
--- a/clutter-gst/clutter-gst-util.h
+++ b/clutter-gst/clutter-gst-util.h
@@ -32,8 +32,14 @@
 
 G_BEGIN_DECLS
 
-ClutterInitError clutter_gst_init (int     *argc,
-                                   char  ***argv);
+ClutterInitError clutter_gst_init           (int     *argc,
+                                             char  ***argv);
+ClutterInitError clutter_gst_init_with_args (int            *argc,
+                                             char         ***argv,
+                                             const char     *parameter_string,
+                                             GOptionEntry   *entries,
+                                             const char     *translation_domain,
+                                             GError        **error);
 
 G_END_DECLS
 
diff --git a/doc/reference/clutter-gst-sections.txt b/doc/reference/clutter-gst-sections.txt
index 5a49fe8..ae602cb 100644
--- a/doc/reference/clutter-gst-sections.txt
+++ b/doc/reference/clutter-gst-sections.txt
@@ -58,6 +58,7 @@ ClutterGstAudioPrivate
 <FILE>clutter-gst-util</FILE>
 <TITLE>Utilities</TITLE>
 clutter_gst_init
+clutter_gst_init_with_args
 </SECTION>
 
 <SECTION>