manual-init.md

   1 ---
   2 title: Initializing GStreamer
   3 ...
   4
   5 # Initializing GStreamer
   6
   7 When writing a GStreamer application, you can simply include `gst/gst.h`
   8 to get access to the library functions. Besides that, you will also need
   9 to initialize the GStreamer library.
  10
  11 ## Simple initialization
  12
  13 Before the GStreamer libraries can be used, `gst_init` has to be called
  14 from the main application. This call will perform the necessary
  15 initialization of the library as well as parse the GStreamer-specific
  16 command line options.
  17
  18 A typical program \[1\] would have code to initialize GStreamer that
  19 looks like this:
  20
  21 ``` c
  22
  23 #include <stdio.h>
  24 #include <gst/gst.h>
  25
  26 int
  27 main (int   argc,
  28       char *argv[])
  29 {
  30   const gchar *nano_str;
  31   guint major, minor, micro, nano;
  32
  33   gst_init (&argc, &argv);
  34
  35   gst_version (&major, &minor, &micro, &nano);
  36
  37   if (nano == 1)
  38     nano_str = "(CVS)";
  39   else if (nano == 2)
  40     nano_str = "(Prerelease)";
  41   else
  42     nano_str = "";
  43
  44   printf ("This program is linked against GStreamer %d.%d.%d %s\n",
  45           major, minor, micro, nano_str);
  46
  47   return 0;
  48 }
  49
  50
  51 ```
  52
  53 Use the `GST_VERSION_MAJOR`, `GST_VERSION_MINOR` and `GST_VERSION_MICRO`
  54 macros to get the GStreamer version you are building against, or use the
  55 function `gst_version` to get the version your application is linked
  56 against. GStreamer currently uses a scheme where versions with the same
  57 major and minor versions are API-/ and ABI-compatible.
  58
  59 It is also possible to call the `gst_init` function with two `NULL`
  60 arguments, in which case no command line options will be parsed by
  61 GStreamer.
  62
  63 ## The GOption interface
  64
  65 You can also use a GOption table to initialize your own parameters as
  66 shown in the next example:
  67
  68 ``` c
  69
  70 #include <gst/gst.h>
  71
  72 int
  73 main (int   argc,
  74       char *argv[])
  75 {
  76   gboolean silent = FALSE;
  77   gchar *savefile = NULL;
  78   GOptionContext *ctx;
  79   GError *err = NULL;
  80   GOptionEntry entries[] = {
  81     { "silent", 's', 0, G_OPTION_ARG_NONE, &silent,
  82       "do not output status information", NULL },
  83     { "output", 'o', 0, G_OPTION_ARG_STRING, &savefile,
  84       "save xml representation of pipeline to FILE and exit", "FILE" },
  85     { NULL }
  86   };
  87
  88   ctx = g_option_context_new ("- Your application");
  89   g_option_context_add_main_entries (ctx, entries, NULL);
  90   g_option_context_add_group (ctx, gst_init_get_option_group ());
  91   if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
  92     g_print ("Failed to initialize: %s\n", err->message);
  93     g_clear_error (&err);
  94     g_option_context_free (ctx);
  95     return 1;
  96   }
  97   g_option_context_free (ctx);
  98
  99   printf ("Run me with --help to see the Application options appended.\n");
 100
 101   return 0;
 102 }
 103
 104
 105 ```
 106
 107 As shown in this fragment, you can use a
 108 [GOption](http://developer.gnome.org/glib/stable/glib-Commandline-option-parser.html)
 109 table to define your application-specific command line options, and pass
 110 this table to the GLib initialization function along with the option
 111 group returned from the function `gst_init_get_option_group`. Your
 112 application options will be parsed in addition to the standard GStreamer
 113 options.
 114
 115 1.  The code for this example is automatically extracted from the
 116     documentation and built under `tests/examples/manual` in the
 117     GStreamer tarball.
 118