2007-10-09 Mario Torre <neugens@limasoftware.net>

	* README.gstreamer: new file.

1 files changed, 120 insertions, 0 deletions

diff --git a/README.gstreamer b/README.gstreamer
new file mode 100644
index 000000000..963bd98b1
--- /dev/null
+++ b/README.gstreamer
@@ -0,0 +1,120 @@
+GNU Classpath GStreamer Sound Backend README - Last updated: October 8, 2007
+(for release 0.96)
+
+* Introduction
+
+  From 0.96, GNU Classpath has a preliminary backend implementation for the
+  Java Sound API based on the GStreamer framework.
+
+  The backend is considered unstable and is currently disabled by default. To
+  enable it, you should pass "--enable-gstreamer-peer" to configure.
+
+  We suggest that you leave this option to the default on production systems,
+  but enable it for testing. The backend has been only tested on Linux i386 and
+  amd64, problems where reported on powerPC64 (see bug:
+  http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33701)
+
+  The peer supports any kind of stream you have a gstreamer plugin for (modulo
+  the eventual bugs of course!!), no special steps are needed to enable them,
+  the only requirement is a working installation of at least gstreamer,
+  gstreamer-base, gstreamer-plugins-base, all with a version number of at least
+  0.10.10.
+
+  The minor version number could eventually be lowered but the peer were
+  developed on a Fedora 7 machine with GStreamer 0.10.10, so they may rely on
+  new functions introduced during the GStreamer 0.10 timeline. GStreamer 0.8
+  will most lickely not work due to API changes, but porting to the old system
+  should not be too hard, as the backend only uses a small subset of all the
+  API.
+
+  Currently, most methods in the backend are missings or are just stubbed.
+  Especially the lack of event handling routines prevent this backend to be
+  useful other than for simple examples.
+
+  We have included in the example directory a simple implementation for an audio
+  player. To run the example just type on the command line:
+  
+  $ java -cp examples/examples.zip \
+    gnu.classpath.examples.sound.AudioPlayerSample audio_file
+
+  Where "java" is a GNU Classpath based VM and audio_file can be any type of
+  audio file that can be read by your GStreamer installation (i.e. ogg and wav).
+
+* Implementation details
+
+  Currently the backend relies on filesystem named pipes to pass data from the
+  java layer to the native gstreamer layer. This is because GStreamer is heavily
+  multi-threaded and reading requests are asynchronous and performed by the
+  framework. While it's possible to control this flow, we have experimented
+  that the best performance are when the framework itself handles all	the
+  buffering, reading and streaming of audio data.
+  
+  The file detection routines instead read directly from an InputStream with a
+  special GStreamer plugin. This will change in the next few release to also use
+  filesystem named pipes as a more reliable way to pass data from one side of
+  the peer to the other as we have experimented that currently reading from a
+  java InputStream has few drawbacks, like sometimes data is not handled
+  correctly, or even introduces the risk of deadlocks (see below).
+	
+* Know Bugs and Limitations
+
+  * Not all the methods described by the API are implemented.
+  
+  * The peer is not currently tested on all the architectures.
+  
+  *	There is a bug in the file detection code (native code) that deadlocks the
+    application. This is usually triggered when you obtain both an
+    AudioInputStream and AudioFileFormat from the same file, in (bad) code
+    like the following:
+
+    AudioInputStream is = AudioSystem.getAudioInputStream(new File(file));
+
+    AudioFileFormat ff = AudioSystem.getAudioFileFormat(new File(file));
+    
+    [... use ff or is at your need ...]
+    
+    This is a corner case, but indeed may happen and may also trigger the bug.
+
+  * No event handling is implemented. We will add that in the next release.
+  
+  * The backend relies on filesystem named pipes to stream audio data and will
+    not work if the system is not allowed to create named pipes (for example,
+    when GNU Classpath is built for systems without a filesystem).
+
+  * To allow correct behaviour of the "available" method (return the free space
+    in the pipeline) we misure the number of bytes currently in the pipeline for
+    processing and substract that to the size of the pipeline.
+
+    Few OS allow to know in advance the size of a pipeline (usually you can
+    retrieve the number of bytes waiting for processing or tell if the next
+    write will block, but not the number of bytes you can write before
+    blocking), so we perform a detection of the size of the pipeline when the
+    backend is first used. This operation can be time consuming and so the
+    result is stored as a preference and then used anytime instead of detection.
+
+    If you use the MemoryBasedPreferences preference backend, no data is
+    actually written in a persistent storage, so the detection routine is called
+    again each time the class is initialized (and that means, currently, in the
+    constructor! A better approach is to move this in the static initializer,
+    but this will be fixed in the next releases).
+
+    The preference node for this value is:
+      
+      * gnu.javax.sound.sampled.gstreamer.lines.GStreamer
+
+    and the key:
+
+      * Capacity
+
+    If you use the GConf preference backend, it's easy to edit this node, just
+    search for this key (assuming all the default values are used, otherwise,
+    pay attention to the defined root node if it's different than
+    "/apps/classpath"):
+
+      * /apps/classpath/gnu/javax/sound/sampled/gstreamer/lines/GStreamer
+
+    and edit the key Capacity. Do this only if you know the correct size of the
+    pipe and you think the detection code will not work reliably on your system
+    (for example, if you have tweaked the kernel to allow very large named pipes
+    the operation may require a lot of time to complete, as all that the code
+    does, is to write bytes on the pipe until it's full).