docs/manual/basics-init.xml

   1 <chapter id="chapter-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
  16     &EXAFOOT;
  17     would have code to initialize GStreamer that
  18     looks like this:
  19   </para>
  20
  21   <programlisting>
  22 <![CDATA[
  23 /* example-begin init.c */
  24
  25 #include <gst/gst.h>
  26
  27 int
  28 main (int argc, 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 /* example-end init.c */
  41 ]]>
  42   </programlisting>
  43   <para>
  44     Use the <symbol>GST_VERSION_MAJOR</symbol>,
  45     <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
  46     macros to get the <application>GStreamer</application> version you are
  47     building against, or use the function <function>gst_version</function>
  48     to get the version your application is linked against.
  49 <!--    FIXME: include an automatically generated list of these options. -->
  50   </para>
  51   <para>
  52     It is also possible to call the <function>gst_init</function> function
  53     with two <symbol>NULL</symbol> arguments, in which case no command line
  54     options will be parsed by <application>GStreamer</application>.
  55   </para>
  56   <sect1>
  57     <title>The popt interface</title>
  58     <para>
  59 You can also use a popt table to initialize your own parameters as shown in the
  60 next example:
  61     </para>
  62     <programlisting>
  63 /* example-begin popt.c */
  64
  65 #include &lt;gst/gst.h&gt;
  66
  67 int
  68 main(int argc, 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 /* example-end popt.c */
  87     </programlisting>
  88     <para>
  89       As shown in this fragment, you can use a <ulink
  90       url="http://developer.gnome.org/doc/guides/popt/"
  91       type="http">popt</ulink> table to define your application-specific
  92       command line options, and pass this table to the
  93       function <function>gst_init_with_popt_table</function>. Your
  94       application options will be parsed in addition to the standard
  95       <application>GStreamer</application> options.
  96     </para>
  97   </sect1>
  98
  99 </chapter>