gstreamer/docs/manual/init-api.xml
Thomas Vander Stichele bba6ac4b74 docs/: restructure so that common stuff is shown first
Original commit message from CVS:
* docs/Makefile.am:
* docs/manual/elements-api.xml:
restructure so that common stuff is shown first
* docs/manual/init-api.xml:
convert to examples
* docs/manual/manual.xml:
* docs/manuals.mak:
* docs/url.entities:
link to API on the website, possibly override later in build
* examples/manual/.cvsignore:
ignore more
* examples/manual/Makefile.am:
add more examples
* examples/manual/extract.pl:
error out on failure
2004-09-08 23:18:55 +00:00

99 lines
3.1 KiB
XML

<chapter id="chapter-initialisation">
<title>Initializing <application>GStreamer</application></title>
<para>
When writing a <application>GStreamer</application> application, you can
simply include <filename class='headerfile'>gst/gst.h</filename> to get
access to the library functions.
</para>
<para>
Before the <application>GStreamer</application> 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>
<programlisting>
<![CDATA[
/* example-begin init.c */
#include <gst/gst.h>
int
main (int argc, char *argv[])
{
guint major, minor, micro;
gst_init (&amp;argc, &amp;argv);
gst_version (&amp;major, &amp;minor, &amp;micro);
printf ("This program is linked against GStreamer %d.%d.%d\n",
major, minor, micro);
return 0;
}
/* example-end init.c */
]]>
</programlisting>
<para>
Use the <symbol>GST_VERSION_MAJOR</symbol>,
<symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
macros to get the <application>GStreamer</application> version you are
building against, or use the function <function>gst_version</function>
to get the version your application is linked against.
<!-- FIXME: include an automatically generated list of these options. -->
</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>
<title>The popt interface</title>
<para>
You can also use a popt table to initialize your own parameters as shown in the
next example:
</para>
<programlisting>
/* example-begin popt.c */
#include &lt;gst/gst.h&gt;
int
main(int argc, char *argv[])
{
gboolean silent = FALSE;
gchar *savefile = NULL;
struct poptOption options[] = {
{"silent", 's', POPT_ARG_NONE|POPT_ARGFLAG_STRIP, &amp;silent, 0,
"do not output status information", NULL},
{"output", 'o', POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &amp;savefile, 0,
"save xml representation of pipeline to FILE and exit", "FILE"},
POPT_TABLEEND
};
gst_init_with_popt_table (&amp;argc, &amp;argv, options);
printf ("Run me with --help to see the Application options appended.\n");
return 0;
}
/* example-end popt.c */
</programlisting>
<para>
As shown in this fragment, you can use a <ulink
url="http://developer.gnome.org/doc/guides/popt/"
type="http">popt</ulink> table to define your application-specific
command line options, and pass this table to the
function <function>gst_init_with_popt_table</function>. Your
application options will be parsed in addition to the standard
<application>GStreamer</application> options.
</para>
</sect1>
</chapter>