docs/manual/basics-init.xml

<chapter id="chapter-init">
  <title>Initializing &GStreamer;</title>
  <para> 
    When writing a &GStreamer; application, you can simply include
    <filename>gst/gst.h</filename> to get access to the library
    functions. Besides that, you will also need to initialize the
    &GStreamer; library.
  </para>

  <sect1 id="section-init-c">
    <title>Simple initialization</title>
    <para>
      Before the &GStreamer; libraries can be used,
      <function>gst_init</function> has to be called from the main
      application. This call will perform the necessary initialization
      of the library as well as parse the &GStreamer;-specific command
      line options.
    </para>
    <para> 
      A typical program &EXAFOOT; would have code to initialize
      &GStreamer; that looks like this:
    </para>
    <example id="ex-init-c">
      <title>Initializing GStreamer</title>
      <programlisting>
<!-- example-begin init.c -->
#include &lt;stdio.h&gt;
#include &lt;gst/gst.h&gt;

int
main (int   argc,
      char *argv[])
{
  const gchar *nano_str;
  guint major, minor, micro, nano;

  gst_init (&amp;argc, &amp;argv);

  gst_version (&amp;major, &amp;minor, &amp;micro, &amp;nano);

  if (nano == 1)
    nano_str = "(CVS)";
  else if (nano == 2)
    nano_str = "(Prerelease)";
  else
    nano_str = "";

  printf ("This program is linked against GStreamer %d.%d.%d %s\n",
          major, minor, micro, nano_str);

  return 0;
}
<!-- example-end init.c -->
      </programlisting>
    </example>
    <para>
      Use the <symbol>GST_VERSION_MAJOR</symbol>,
      <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
      macros to get the &GStreamer; version you are building against, or
      use the function <function>gst_version</function> to get the version
      your application is linked against. &GStreamer; currently uses a
      scheme where versions with the same major and minor versions are
      API-/ and ABI-compatible.
    </para>
    <para>
      It is also possible to call the <function>gst_init</function> function
      with two <symbol>NULL</symbol> arguments, in which case no command line
      options will be parsed by <application>GStreamer</application>.
    </para>
  </sect1>

  <sect1>
    <title>The GOption interface</title>
    <para>
      You can also use a GOption table to initialize your own parameters as
      shown in the next example:
    </para>
    <example id="ex-goption-c">
      <title>Initialisation using the GOption interface</title>
      <programlisting>
<!-- example-begin goption.c -->
#include &lt;gst/gst.h&gt;

int
main (int   argc,
      char *argv[])
{
  gboolean silent = FALSE;
  gchar *savefile = NULL;
  GOptionContext *ctx;
  GError *err = NULL;
  GOptionEntry entries[] = {
    { "silent", 's', 0, G_OPTION_ARG_NONE, &amp;silent,
      "do not output status information", NULL },
    { "output", 'o', 0, G_OPTION_ARG_STRING, &amp;savefile,
      "save xml representation of pipeline to FILE and exit", "FILE" },
    { NULL }
  };

  ctx = g_option_context_new ("- Your application");
  g_option_context_add_main_entries (ctx, entries, NULL);
  g_option_context_add_group (ctx, gst_init_get_option_group ());
  if (!g_option_context_parse (ctx, &amp;argc, &amp;argv, &amp;err)) {
    g_print ("Failed to initialize: %s\n", err->message);
    g_error_free (err);
    return 1;
  }

  printf ("Run me with --help to see the Application options appended.\n");

  return 0;
}
<!-- example-end goption.c -->
      </programlisting>
    </example>
    <para>
      As shown in this fragment, you can use a <ulink
      url="http://developer.gnome.org/glib/stable/glib-Commandline-option-parser.html"
      type="http">GOption</ulink> table to define your application-specific
      command line options, and pass this table to the GLib initialization
      function along with the option group returned from the
      function <function>gst_init_get_option_group</function>. Your
      application options will be parsed in addition to the standard
      <application>GStreamer</application> options.
    </para>
  </sect1>
</chapter>