docs/gst/tmpl/gst.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GStreamer
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Media library supporting arbitrary formats and filter graphs.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GStreamer is a framework for constructing graphs of various filters
  10 (termed elements here) that will handle streaming media.  Any discreet
  11 (packetizable) media type is supported, with provisions for automatically
  12 determining source type.  Formatting/framing information is provided with
  13 a powerful negotiation framework.  Plugins are heavily used to provide for
  14 all elements, allowing one to construct plugins outside of the GST
  15 library, even released binary-only if license require (please don't).
  16 </para>
  17
  18 <para>
  19 GStreamer borrows heavily from both the <ulink
  20 url="http://www.cse.ogi.edu/sysl/">OGI media pipeline</ulink> and
  21 Microsoft's DirectShow, hopefully taking the best of both and leaving the
  22 cruft behind.  Its interface is still very fluid and thus can be changed
  23 to increase the sanity/noise ratio.
  24 </para>
  25
  26 <para>
  27 The <application>GStreamer</application> library should be initialized with gst_init() before
  28 it can be used. You should pass a pointer to the main argc and argv variables so that GStreamer can
  29 process its own command line options, as shown in the following example.
  30
  31 <example>
  32 <title>Initializing the gstreamer library</title>
  33   <programlisting>
  34   int
  35   main (int argc, char *argv[])
  36   {
  37     /* initialize the GStreamer library */
  38     gst_init (&amp;argc, &amp;argv);
  39     ...
  40   }
  41   </programlisting>
  42 </example>
  43 </para>
  44 <para>
  45 It's allowed to pass two NULL pointers to gst_init() in case you don't want to pass the command
  46 line args to GStreamer.
  47 </para>
  48
  49 <para>
  50 You can also use a popt table to initialize your own parameters as shown in the next code
  51 fragment:
  52 <example>
  53 <title>Initializing own parameters when initializing gstreamer</title>
  54   <programlisting>
  55   static gboolean stats = FALSE;
  56   ...
  57
  58   int
  59   main (int argc, char *argv[])
  60   {
  61     struct poptOption options[] = {
  62       { "stats",  's',  POPT_ARG_NONE|POPT_ARGFLAG_STRIP,   &amp;stats,   0,
  63           "Show pad stats", NULL},
  64         POPT_TABLEEND
  65       };
  66
  67     /* initialize the GStreamer library */
  68     gst_init_with_popt_table (&amp;argc, &amp;argv, options);
  69
  70     ...
  71   }
  72   </programlisting>
  73 </example>
  74 </para>
  75 <para>
  76   Use gst_version() to query the library version at runtime or use the GST_VERSION_* macros
  77   to find the version at compile time.
  78 </para>
  79 <para>
  80 gst_main() and gst_main_quit() enter and exit the main loop. GStreamer doesn't currently require
  81 you to us a mainloop but can intergrate with it without problems.
  82 </para>
  83
  84 <!-- ##### SECTION See_Also ##### -->
  85 <para>
  86 Check out both <ulink url="http://www.cse.ogi.edu/sysl/">OGI's
  87 pipeline</ulink> and Microsoft's DirectShow for some background.
  88 </para>
  89
  90 <!-- ##### FUNCTION gst_init ##### -->
  91 <para>
  92
  93 </para>
  94
  95 @argc:
  96 @argv:
  97
  98
  99 <!-- ##### FUNCTION gst_init_check ##### -->
 100 <para>
 101
 102 </para>
 103
 104 @argc:
 105 @argv:
 106 @Returns:
 107
 108
 109 <!-- ##### FUNCTION gst_init_with_popt_table ##### -->
 110 <para>
 111
 112 </para>
 113
 114 @argc:
 115 @argv:
 116 @popt_options:
 117 <!-- # Unused Parameters # -->
 118 @Param3:
 119 @Returns:
 120
 121
 122 <!-- ##### FUNCTION gst_init_check_with_popt_table ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @argc:
 128 @argv:
 129 @popt_options:
 130 @Returns:
 131 <!-- # Unused Parameters # -->
 132 @Param3:
 133
 134
 135 <!-- ##### FUNCTION gst_init_get_popt_table ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @Returns:
 141
 142