docs/manual/init.xml

   1 <chapter id="cha-initialisation">
   2   <title>Initializing <application>GStreamer</application></title>
   3   <para>
   4     When writing a <application>GStreamer</application> application, you can
   5     simply include <filename class='headerfile'>gst/gst.h</filename> to get
   6     access to the library functions.
   7   </para>
   8   <para>
   9     Before the <application>GStreamer</application> libraries can be used
  10     <function>gst_init</function> has to be called from the main application.
  11     This call will perform the necessary initialization of the library as
  12     well as parse the GStreamer-specific command line options.
  13   </para>
  14   <para>
  15     A typical program would start like this:
  16   </para>
  17
  18   <programlisting>
  19 #include &lt;gst/gst.h&gt;
  20
  21 ...
  22
  23 int
  24 main (int argc, char *argv[])
  25 {
  26   ...
  27   gst_init (&amp;argc, &amp;argv);
  28   ...
  29 }
  30   </programlisting>
  31   <para>
  32     Use the <symbol>GST_VERSION_MAJOR</symbol>,
  33     <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
  34     macros to get the <application>GStreamer</application> version you are
  35     building against, or use the function <function>gst_version</function>
  36     to get the version your application is linked against.
  37 <!--    FIXME: include an automatically generated list of these options. -->
  38   </para>
  39   <para>
  40     It is also possible to call the <function>gst_init</function> function
  41     with two <symbol>NULL</symbol> arguments, in which case no command line
  42     options will parsed by <application>GStreamer</application>.
  43   </para>
  44   <para>
  45     Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to
  46     get the <application>GStreamer</application> version you are building against or
  47     use gst_version() to get the version you are linked against.
  48   </para>
  49   <sect1>
  50     <title>The popt interface</title>
  51     <para>
  52       You can also use a popt table to initialize your own parameters as shown in the next code fragment:
  53     </para>
  54     <programlisting>
  55 int
  56 main(int argc, char *argv[])
  57 {
  58   gboolean silent = FALSE;
  59   gchar *savefile = NULL;
  60   struct poptOption options[] = {
  61     {"silent",  's',  POPT_ARG_NONE|POPT_ARGFLAG_STRIP,   &amp;silent,   0,
  62      "do not output status information", NULL},
  63     {"output",  'o',  POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &amp;savefile, 0,
  64      "save xml representation of pipeline to FILE and exit", "FILE"},
  65     POPT_TABLEEND
  66   };
  67
  68   gst_init_with_popt_table (&amp;argc, &amp;argv, options);
  69
  70   ...
  71     </programlisting>
  72     <para>
  73       As shown in this fragment, you can use a <ulink
  74       url="http://developer.gnome.org/doc/guides/popt/"
  75       type="http">popt</ulink> table to define your application-specific
  76       command line options, and pass this table to the
  77       function <function>gst_init_with_popt_table</function>. Your
  78       application options will be parsed in addition to the standard
  79       <application>GStreamer</application> options.
  80     </para>
  81   </sect1>
  82
  83 </chapter>