1 <chapter id="chapter-init">
2 <title>Initializing &GStreamer;</title>
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
10 <sect1 id="section-init-c">
11 <title>Simple initialization</title>
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
20 A typical program &EXAFOOT; would have code to initialize
21 &GStreamer; that looks like this:
23 <example id="ex-init-c">
24 <title>Initializing GStreamer</title>
26 <!-- example-begin init.c -->
27 #include <stdio.h>
28 #include <gst/gst.h>
34 const gchar *nano_str;
35 guint major, minor, micro, nano;
37 gst_init (&argc, &argv);
39 gst_version (&major, &minor, &micro, &nano);
44 nano_str = "(Prerelease)";
48 printf ("This program is linked against GStreamer %d.%d.%d %s\n",
49 major, minor, micro, nano_str);
53 <!-- example-end init.c -->
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.
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>.
73 <title>The GOption interface</title>
75 You can also use a GOption table to initialize your own parameters as
76 shown in the next example:
78 <example id="ex-goption-c">
79 <title>Initialisation using the GOption interface</title>
81 <!-- example-begin goption.c -->
82 #include <gst/gst.h>
88 gboolean silent = FALSE;
89 gchar *savefile = NULL;
92 GOptionEntry entries[] = {
93 { "silent", 's', 0, G_OPTION_ARG_NONE, &silent,
94 "do not output status information", NULL },
95 { "output", 'o', 0, G_OPTION_ARG_STRING, &savefile,
96 "save xml representation of pipeline to FILE and exit", "FILE" },
100 /* we must initialise the threading system before using any
101 * other GLib funtion, such as g_option_context_new() */
102 if (!g_thread_supported ())
103 g_thread_init (NULL);
105 ctx = g_option_context_new ("- Your application");
106 g_option_context_add_main_entries (ctx, entries, NULL);
107 g_option_context_add_group (ctx, gst_init_get_option_group ());
108 if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
109 g_print ("Failed to initialize: %s\n", err->message);
114 printf ("Run me with --help to see the Application options appended.\n");
118 <!-- example-end goption.c -->
122 As shown in this fragment, you can use a <ulink
123 url="http://developer.gnome.org/doc/API/2.0/glib/glib-Commandline-option-parser.html"
124 type="http">GOption</ulink> table to define your application-specific
125 command line options, and pass this table to the GLib initialization
126 function along with the option group returned from the
127 function <function>gst_init_get_option_group</function>. Your
128 application options will be parsed in addition to the standard
129 <application>GStreamer</application> options.