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