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 intialize 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     <programlisting>
  24 #include &lt;gst/gst.h&gt;
  25
  26 int
  27 main (int   argc,
  28       char *argv[])
  29 {
  30   guint major, minor, micro;
  31
  32   gst_init (&amp;argc, &amp;argv);
  33
  34   gst_version (&amp;major, &amp;minor, &amp;micro);
  35   printf ("This program is linked against GStreamer %d.%d.%d\n",
  36           major, minor, micro);
  37
  38   return 0;
  39 }
  40     </programlisting>
  41     <para>
  42       Use the <symbol>GST_VERSION_MAJOR</symbol>,
  43       <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
  44       macros to get the &GStreamer; version you are building against, or
  45       use the function <function>gst_version</function> to get the version
  46       your application is linked against. &GStreamer; currently uses a
  47       scheme where versions with the same major and minor versions are
  48       API-/ and ABI-compatible.
  49     </para>
  50     <para>
  51       It is also possible to call the <function>gst_init</function> function
  52       with two <symbol>NULL</symbol> arguments, in which case no command line
  53       options will be parsed by <application>GStreamer</application>.
  54     </para>
  55   </sect1>
  56
  57   <sect1>
  58     <title>The popt interface</title>
  59     <para>
  60       You can also use a popt table to initialize your own parameters as
  61       shown in the next example:
  62     </para>
  63     <programlisting>
  64 #include &lt;gst/gst.h&gt;
  65
  66 int
  67 main (int   argc,
  68       char *argv[])
  69 {
  70   gboolean silent = FALSE;
  71   gchar *savefile = NULL;
  72   struct poptOption options[] = {
  73     {"silent",  's',  POPT_ARG_NONE|POPT_ARGFLAG_STRIP,   &amp;silent,   0,
  74      "do not output status information", NULL},
  75     {"output",  'o',  POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &amp;savefile, 0,
  76      "save xml representation of pipeline to FILE and exit", "FILE"},
  77     POPT_TABLEEND
  78   };
  79
  80   gst_init_with_popt_table (&amp;argc, &amp;argv, options);
  81
  82   printf ("Run me with --help to see the Application options appended.\n");
  83
  84   return 0;
  85 }
  86     </programlisting>
  87     <para>
  88       As shown in this fragment, you can use a <ulink
  89       url="http://developer.gnome.org/doc/guides/popt/"
  90       type="http">popt</ulink> table to define your application-specific
  91       command line options, and pass this table to the
  92       function <function>gst_init_with_popt_table</function>. Your
  93       application options will be parsed in addition to the standard
  94       <application>GStreamer</application> options.
  95     </para>
  96   </sect1>
  97 </chapter>