docs/manual/basics-init.xml

   1 <chapter id="chapter-init">
   2   <title>Initializing &GStreamer;</title>
   3   <para>
   4     When writing a &GStreamer; application, you can simply include
   5     <filename>gst/gst.h</filename> to get access to the library
   6     functions. Besides that, you will also need to initialize the
   7     &GStreamer; library.
   8   </para>
   9
  10   <sect1 id="section-init-c">
  11     <title>Simple initialization</title>
  12     <para>
  13       Before the &GStreamer; libraries can be used,
  14       <function>gst_init</function> has to be called from the main
  15       application. This call will perform the necessary initialization
  16       of the library as well as parse the &GStreamer;-specific command
  17       line options.
  18     </para>
  19     <para>
  20       A typical program &EXAFOOT; would have code to initialize
  21       &GStreamer; that looks like this:
  22     </para>
  23     <example id="ex-init-c">
  24       <title>Initializing GStreamer</title>
  25       <programlisting>
  26 <!-- example-begin init.c -->
  27 #include &lt;stdio.h&gt;
  28 #include &lt;gst/gst.h&gt;
  29
  30 int
  31 main (int   argc,
  32       char *argv[])
  33 {
  34   const gchar *nano_str;
  35   guint major, minor, micro, nano;
  36
  37   gst_init (&amp;argc, &amp;argv);
  38
  39   gst_version (&amp;major, &amp;minor, &amp;micro, &amp;nano);
  40
  41   if (nano == 1)
  42     nano_str = "(CVS)";
  43   else if (nano == 2)
  44     nano_str = "(Prerelease)";
  45   else
  46     nano_str = "";
  47
  48   printf ("This program is linked against GStreamer %d.%d.%d %s\n",
  49           major, minor, micro, nano_str);
  50
  51   return 0;
  52 }
  53 <!-- example-end init.c -->
  54       </programlisting>
  55     </example>
  56     <para>
  57       Use the <symbol>GST_VERSION_MAJOR</symbol>,
  58       <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
  59       macros to get the &GStreamer; version you are building against, or
  60       use the function <function>gst_version</function> to get the version
  61       your application is linked against. &GStreamer; currently uses a
  62       scheme where versions with the same major and minor versions are
  63       API-/ and ABI-compatible.
  64     </para>
  65     <para>
  66       It is also possible to call the <function>gst_init</function> function
  67       with two <symbol>NULL</symbol> arguments, in which case no command line
  68       options will be parsed by <application>GStreamer</application>.
  69     </para>
  70   </sect1>
  71
  72   <sect1>
  73     <title>The GOption interface</title>
  74     <para>
  75       You can also use a GOption table to initialize your own parameters as
  76       shown in the next example:
  77     </para>
  78     <example id="ex-goption-c">
  79       <title>Initialisation using the GOption interface</title>
  80       <programlisting>
  81 <!-- example-begin goption.c -->
  82 #include &lt;gst/gst.h&gt;
  83
  84 int
  85 main (int   argc,
  86       char *argv[])
  87 {
  88   gboolean silent = FALSE;
  89   gchar *savefile = NULL;
  90   GOptionContext *ctx;
  91   GError *err = NULL;
  92   GOptionEntry entries[] = {
  93     { "silent", 's', 0, G_OPTION_ARG_NONE, &amp;silent,
  94       "do not output status information", NULL },
  95     { "output", 'o', 0, G_OPTION_ARG_STRING, &amp;savefile,
  96       "save xml representation of pipeline to FILE and exit", "FILE" },
  97     { NULL }
  98   };
  99
 100   ctx = g_option_context_new ("- Your application");
 101   g_option_context_add_main_entries (ctx, entries, NULL);
 102   g_option_context_add_group (ctx, gst_init_get_option_group ());
 103   if (!g_option_context_parse (ctx, &amp;argc, &amp;argv, &amp;err)) {
 104     g_print ("Failed to initialize: %s\n", err->message);
 105     g_clear_error (&amp;err);
 106     g_option_context_free (ctx);
 107     return 1;
 108   }
 109   g_option_context_free (ctx);
 110
 111   printf ("Run me with --help to see the Application options appended.\n");
 112
 113   return 0;
 114 }
 115 <!-- example-end goption.c -->
 116       </programlisting>
 117     </example>
 118     <para>
 119       As shown in this fragment, you can use a <ulink
 120       url="http://developer.gnome.org/glib/stable/glib-Commandline-option-parser.html"
 121       type="http">GOption</ulink> table to define your application-specific
 122       command line options, and pass this table to the GLib initialization
 123       function along with the option group returned from the
 124       function <function>gst_init_get_option_group</function>. Your
 125       application options will be parsed in addition to the standard
 126       <application>GStreamer</application> options.
 127     </para>
 128   </sect1>
 129 </chapter>