docs/manual/appendix-integration.xml

   1 <chapter id="chapter-intgration">
   2   <title>Integration</title>
   3   <para>
   4     &GStreamer; tries to integrate closely with operating systems (such
   5     as Linux and UNIX-like operating systems, OS X or Windows) and desktop
   6     environments (such as GNOME or KDE). In this chapter, we'll mention
   7     some specific techniques to integrate your application with your
   8     operating system or desktop environment of choice.
   9   </para>
  10
  11 <!-- ####################################################################### -->
  12 <!-- ####################################################################### -->
  13 <!-- ####################################################################### -->
  14
  15   <sect1 id="section-integration-nix">
  16     <title>Linux and UNIX-like operating systems</title>
  17     <para>
  18       &GStreamer; provides a basic set of elements that are useful when
  19       integrating with Linux or a UNIX-like operating system.
  20     </para>
  21     <itemizedlist>
  22       <listitem>
  23         <para>
  24           For audio input and output, &GStreamer; provides input and
  25           output elements for several audio subsystems. Amongst others,
  26           &GStreamer; includes elements for ALSA (alsasrc, alsamixer,
  27           alsasink), OSS (osssrc, ossmixer, osssink) and Sun audio
  28           (sunaudiosrc, sunaudiomixer, sunaudiosink).
  29         </para>
  30       </listitem>
  31       <listitem>
  32         <para>
  33           For video input, &GStreamer; contains source elements for
  34           Video4linux (v4lsrc, v4lmjpegsrc, v4lelement and v4lmjpegisnk)
  35           and Video4linux2 (v4l2src, v4l2element).
  36         </para>
  37       </listitem>
  38       <listitem>
  39         <para>
  40           For video output, &GStreamer; provides elements for output
  41           to X-windows (ximagesink), Xv-windows (xvimagesink; for
  42           hardware-accelerated video), direct-framebuffer (dfbimagesink)
  43           and openGL image contexts (glsink).
  44         </para>
  45       </listitem>
  46     </itemizedlist>
  47   </sect1>
  48
  49 <!-- ####################################################################### -->
  50 <!-- ####################################################################### -->
  51 <!-- ####################################################################### -->
  52
  53   <sect1 id="section-integration-gnome">
  54     <title>GNOME desktop</title>
  55     <para>
  56       &GStreamer; has been the media backend of the <ulink type="http"
  57       url="http://www.gnome.org/">GNOME</ulink> desktop since GNOME-2.2
  58       onwards. Nowadays, a whole bunch of GNOME applications make use of
  59       &GStreamer; for media-processing, including (but not limited to)
  60       <ulink type="http" url="http://www.rhythmbox.org/">Rhythmbox</ulink>,
  61       <ulink type="http" url="http://www.hadess.net/totem.php3">Totem</ulink>
  62       and <ulink type="http"
  63       url="http://www.burtonini.com/blog/computers/sound-juicer">Sound
  64       Juicer</ulink>.
  65     </para>
  66     <para>
  67       Most of these GNOME applications make use of some specific techniques
  68       to integrate as closely as possible with the GNOME desktop:
  69     </para>
  70     <itemizedlist>
  71       <listitem>
  72         <para>
  73           GNOME applications usually call <function>gtk_init ()</function>
  74           to parse command-line options and initialize GTK. &GStreamer;
  75           applications would normally call <function>gst_init ()</function>
  76           to do the same for GStreamer.
  77           This would mean that only one of the two can parse command-line
  78           options. To work around this issue, &GStreamer; can provide a
  79           GLib <classname>GOptionGroup</classname> which can be passed to
  80           <function>gnome_program_init ()</function>. The following
  81           example requires GTK 2.6 or newer (previous GTK versions
  82           do not support command line parsing via GOption yet)
  83         </para>
  84         <programlisting><!-- example-begin gnome.c a -->
  85 #include &lt;gtk/gtk.h&gt;
  86 #include &lt;gst/gst.h&gt;
  87
  88 static gchar **cmd_filenames = NULL;
  89
  90 static GOptionEntries cmd_options[] = {
  91   /* here you can add command line options for your application. Check
  92    * the GOption section in the GLib API reference for a more elaborate
  93    * example of how to add your own command line options here */
  94
  95   /* at the end we have a special option that collects all remaining
  96    * command line arguments (like filenames) for us. If you don&apos;t
  97    * need this, you can safely remove it */
  98   { G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &amp;cmd_filenames,
  99     "Special option that collects any remaining arguments for us" },
 100
 101   /* mark the end of the options array with a NULL option */
 102   { NULL, }
 103 };
 104
 105 /* this should usually be defined in your config.h */
 106 #define VERSION "0.0.1"
 107
 108 gint
 109 main (gint argc, gchar **argv)
 110 {
 111   GOptionContext *context;
 112   GOptionGroup *gstreamer_group, *gtk_group;
 113   GError *err = NULL;
 114
 115   /* we must initialise the threading system before using any
 116    * other GLib funtion, such as g_option_context_new() */
 117   if (!g_thread_supported ())
 118     g_thread_init (NULL);
 119
 120   context = g_option_context_new ("gtk-demo-app");
 121
 122   /* get command line options from GStreamer and add them to the group */
 123   gstreamer_group = gst_init_get_option_group ();
 124   g_option_context_add_group (context, gstreamer_group);
 125   gtk_group = gtk_get_option_group (TRUE);
 126   g_option_context_add_group (context, gtk_group);
 127
 128   /* add our own options. If you are using gettext for translation of your
 129    * strings, use GETTEXT_PACKAGE here instead of NULL */
 130   g_option_context_add_main_entries (context, cmd_options, NULL);
 131
 132   /* now parse the commandline options, note that this already
 133    * calls gtk_init() and gst_init() */
 134   if (!g_option_context_parse (ctx, &amp;argc, &amp;argv, &amp;err)) {
 135     g_print ("Error initializing: %s\n", err->message);
 136     exit (1);
 137   }
 138
 139   /* any filenames we got passed on the command line? parse them! */
 140   if (cmd_filenames != NULL) {
 141     guint i, num;
 142
 143     num = g_strv_length (cmd_filenames);
 144     for (i = 0; i &lt; num; ++i) {
 145       /* do something with the filename ... */
 146       g_print ("Adding to play queue: %s\n", cmd_filenames[i]);
 147     }
 148
 149     g_strfreev (cmd_filenames);
 150     cmd_filenames = NULL;
 151   }
 152 <!-- example-end gnome.c a -->
 153 [..]<!-- example-begin gnome.c b --><!--
 154   return 0;
 155 --><!-- example-end gnome.c b -->
 156 <!-- example-begin gnome.c c -->
 157 }
 158         <!-- example-end gnome.c c --></programlisting>
 159       </listitem>
 160       <listitem>
 161         <para>
 162           GNOME stores the default video and audio sources and sinks in GConf.
 163           &GStreamer; provides a number of elements that create audio and
 164           video sources and sinks directly based on those GConf settings.
 165           Those elements are: gconfaudiosink, gconfvideosink, gconfaudiosrc
 166           and gconfvideosrc. You can create them with
 167           <function>gst_element_factory_make ()</function> and use them
 168           directly just like you would use any other source or sink element.
 169           All GNOME applications are recommended to use those elements.
 170         </para>
 171       </listitem>
 172       <listitem>
 173         <para>
 174           &GStreamer; provides data input/output elements for use with the
 175           GIO VFS system. These elements are called <quote>giosrc</quote>
 176           and <quote>giosink</quote>.
 177           The deprecated GNOME-VFS system is supported too but shouldn't be
 178           used for any new applications.
 179         </para>
 180       </listitem>
 181     </itemizedlist>
 182   </sect1>
 183
 184 <!-- ####################################################################### -->
 185 <!-- ####################################################################### -->
 186 <!-- ####################################################################### -->
 187
 188
 189
 190   <sect1 id="section-integration-kde">
 191     <title>KDE desktop</title>
 192     <para>
 193       &GStreamer; has been proposed for inclusion in KDE-4.0. Currently,
 194       &GStreamer; is included as an optional component, and it's used by
 195       several KDE applications, including <ulink type="http"
 196       url="http://amarok.kde.org/">AmaroK</ulink>, <ulink type="http"
 197       url="http://developer.kde.org/~wheeler/juk.html">JuK</ulink>,
 198       <ulink type="http"
 199       url="http://www.xs4all.nl/~jjvrieze/kmplayer.html">KMPlayer</ulink> and
 200       <ulink type="http"
 201       url="http://kaffeine.sourceforge.net/">Kaffeine</ulink>.
 202     </para>
 203     <para>
 204       Although not yet as complete as the GNOME integration bits, there
 205       are already some KDE integration specifics available. This list will
 206       probably grow as &GStreamer; starts to be used in KDE-4.0:
 207     </para>
 208     <itemizedlist>
 209       <listitem>
 210         <para>
 211           AmaroK contains a kiosrc element, which is a source element that
 212           integrates with the KDE VFS subsystem KIO.
 213         </para>
 214       </listitem>
 215     </itemizedlist>
 216   </sect1>
 217
 218 <!-- ####################################################################### -->
 219 <!-- ####################################################################### -->
 220 <!-- ####################################################################### -->
 221
 222   <sect1 id="section-integration-osx">
 223     <title>OS X</title>
 224     <para>
 225       &GStreamer; provides native video and audio output elements for OS X.
 226       It builds using the standard development tools for OS X.
 227     </para>
 228   </sect1>
 229
 230 <!-- ####################################################################### -->
 231 <!-- ####################################################################### -->
 232 <!-- ####################################################################### -->
 233
 234   <sect1 id="section-integration-win32">
 235     <title>Windows</title>
 236
 237     <warning>
 238 <para>
 239 Note: this section is out of date. GStreamer-0.10 has much better
 240 support for win32 than previous versions though and should usually compile
 241 and work out-of-the-box both using MSYS/MinGW or Microsoft compilers. The
 242 <ulink url="http://gstreamer.freedesktop.org">GStreamer web site</ulink> and the
 243 <ulink url="http://news.gmane.org/gmane.comp.video.gstreamer.devel">mailing list
 244 archives</ulink> are a good place to check the latest win32-related news.
 245 </para>
 246     </warning>
 247
 248
 249     <para>
 250       &GStreamer; builds using Microsoft Visual C .NET 2003 and using Cygwin.
 251     </para>
 252
 253   <sect2 id="section-win32-build">
 254   <title>Building <application>GStreamer</application> under Win32</title>
 255
 256 <para>There are different makefiles that can be used to build GStreamer with the usual Microsoft
 257 compiling tools.</para>
 258
 259 <para>The Makefile is meant to be used with the GNU make program and the free
 260 version of the Microsoft compiler (<ulink url="http://msdn.microsoft.com/visualc/vctoolkit2003/">http://msdn.microsoft.com/visualc/vctoolkit2003/</ulink>). You also
 261 have to modify your system environment variables to use it from the command-line. You will also
 262 need a working Platform SDK for Windows that is available for free from Microsoft.</para>
 263
 264 <para>The projects/makefiles will generate automatically some source files needed to compile
 265 GStreamer. That requires that you have installed on your system some GNU tools and that they are
 266 available in your system PATH.</para>
 267
 268 <para>The GStreamer project depends on other libraries, namely :</para>
 269 <itemizedlist>
 270 <listitem><para>GLib</para></listitem>
 271 <listitem><para>libxml2</para></listitem>
 272 <listitem><para>libintl</para></listitem>
 273 <listitem><para>libiconv</para></listitem>
 274 </itemizedlist>
 275
 276 <para>Work is being done to provide pre-compiled GStreamer-0.10 libraries as
 277 a packages for win32. Check the <ulink url="http://gstreamer.freedesktop.org">
 278 GStreamer web site</ulink> and check our
 279 <ulink url="http://news.gmane.org/gmane.comp.video.gstreamer.devel">mailing list
 280 </ulink> for the latest developments in this respect.</para>
 281
 282 <note>
 283 <title>Notes</title>
 284
 285 <para>GNU tools needed that you can find on <ulink url="http://gnuwin32.sourceforge.net/">http://gnuwin32.sourceforge.net/</ulink></para>
 286 <itemizedlist>
 287 <listitem><para>GNU flex      (tested with 2.5.4)</para></listitem>
 288 <listitem><para>GNU bison     (tested with 1.35)</para></listitem>
 289 </itemizedlist>
 290
 291 <para>and <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink></para>
 292 <itemizedlist>
 293 <listitem><para>GNU make      (tested with 3.80)</para></listitem>
 294 </itemizedlist>
 295
 296 <para>the generated files from the -auto makefiles will be available soon separately on the net
 297 for convenience (people who don't want to install GNU tools).</para>
 298 </note>
 299 </sect2>
 300
 301   <sect2 id="section-win32-install">
 302 <title>Installation on the system</title>
 303
 304 <para>FIXME: This section needs be updated for GStreamer-0.10.</para>
 305
 306 <!--
 307 <para>By default, GStreamer needs a registry. You have to generate it using "gst-register.exe". It will create
 308 the file in c:\gstreamer\registry.xml that will hold all the plugins you can use.</para>
 309
 310 <para>You should install the GStreamer core in c:\gstreamer\bin and the plugins in c:\gstreamer\plugins.  Both
 311 directories should be added to your system PATH. The library dependencies should be installed in c:\usr</para>
 312
 313 <para>For example, my current setup is :</para>
 314
 315 <itemizedlist>
 316 <listitem><para><filename>c:\gstreamer\registry.xml</filename></para></listitem>
 317 <listitem><para><filename>c:\gstreamer\bin\gst-inspect.exe</filename></para></listitem>
 318 <listitem><para><filename>c:\gstreamer\bin\gst-launch.exe</filename></para></listitem>
 319 <listitem><para><filename>c:\gstreamer\bin\gst-register.exe</filename></para></listitem>
 320 <listitem><para><filename>c:\gstreamer\bin\gstbytestream.dll</filename></para></listitem>
 321 <listitem><para><filename>c:\gstreamer\bin\gstelements.dll</filename></para></listitem>
 322 <listitem><para><filename>c:\gstreamer\bin\gstoptimalscheduler.dll</filename></para></listitem>
 323 <listitem><para><filename>c:\gstreamer\bin\gstspider.dll</filename></para></listitem>
 324 <listitem><para><filename>c:\gstreamer\bin\libgtreamer-0.8.dll</filename></para></listitem>
 325 <listitem><para><filename>c:\gstreamer\plugins\gst-libs.dll</filename></para></listitem>
 326 <listitem><para><filename>c:\gstreamer\plugins\gstmatroska.dll</filename></para></listitem>
 327 <listitem><para><filename>c:\usr\bin\iconv.dll</filename></para></listitem>
 328 <listitem><para><filename>c:\usr\bin\intl.dll</filename></para></listitem>
 329 <listitem><para><filename>c:\usr\bin\libglib-2.0-0.dll</filename></para></listitem>
 330 <listitem><para><filename>c:\usr\bin\libgmodule-2.0-0.dll</filename></para></listitem>
 331 <listitem><para><filename>c:\usr\bin\libgobject-2.0-0.dll</filename></para></listitem>
 332 <listitem><para><filename>c:\usr\bin\libgthread-2.0-0.dll</filename></para></listitem>
 333 <listitem><para><filename>c:\usr\bin\libxml2.dll</filename></para></listitem>
 334 </itemizedlist>
 335 -->
 336
 337   </sect2>
 338
 339   </sect1>
 340
 341 </chapter>