Imported Upstream version 4.2-build2006upstream/4.2-build2006upstream

1 files changed, 120 insertions, 0 deletions

diff --git a/lib/libOSSlib/Readme b/lib/libOSSlib/Readme
new file mode 100644
index 0000000..b975b78
--- /dev/null
+++ b/lib/libOSSlib/Readme
@@ -0,0 +1,120 @@
+About OSSlib
+============
+
+This version of OSSlib which supports patch caching for cards like GUS, OPL3
+and SoftOSS. This part of the library is only used by some older synthesizer
+chips that are no longer available. Also the SoftOSS virtual synth is
+compatible with it.
+
+Another part is the midiparser library. It's a simple callback based
+system that translates a stream of MIDI bytes (for example from MIDI 
+keyboard) to events.
+
+This library is compatible with all OSS implementations including the freeware
+implementations.
+
+Copying conditions
+------------------
+
+This library can be freely used in ANY applications that is compatible
+with the OSS API. No parts of the code can be borroved to other purposes
+without written permission by 4Front Technologies.
+
+Installing OSSlib
+-----------------
+
+Execute make. If your operating system is recognized you will get
+libOSSlib.so or libOSSlib.a depending on operating system.
+If make complains about unknown operating system you should use
+make libOSSlib.so or make libOSSlib.a to build it. 
+
+Finally copy libOSSlib.* to /usr/lib
+
+Using OSSlib in programs
+------------------------
+
+OSSlib is intended to be used in programs using /dev/music but
+it also works with /dev/sequencer too. This version of the library
+contains only some basic patch caching functions to be used with
+OPL3 and GUS (and SoftOSS as well). Support for other cards is still 
+missing.
+
+There are steps to be done when using OSSlib in a program:
+
+1) Change Makefile to use -DOSSLIB and -lOSSlib
+
+Version 3.8 of <sys/soundcard.h> has been designed to be compatible
+with OSSlib when this OSSLIB is defined. You can also use 
+#ifdef OSSLIB in programs to cover the minor differences between
+the OSSlib and non OSSlib versions.
+
+2) If the program defines segbuf_dump() routine, put it inside
+#ifndef OSSLIB/#endif pair. This routine is included in OSSlib
+and having the same routine inside the program conflicts with it.
+
+3) Add the following call to the program after /dev/music is opened.
+
+#ifdef OSSLIB
+	OSS_init(seqfd, 1024);
+#endif
+
+In the above seqfd is the file descriptor of /dev/music and 1024
+is the size of the local buffer used for output events (1024 is
+a good value).
+
+4) Add patch caching calls to the program. Patch caching should
+be called as early as possible. It's recommended to load all
+_required_ patches before starting the actual playback since
+loading large patches from disk may introduce significant delays
+to playback.
+
+There are two macros (in soundcard.h) to be used when loading 
+instruments:
+
+SEQ_LOAD_GMINSTR(dev#, instr#) loads an instrument (melodic) patch.
+The first parameter is the synthesizer/device number (0 to N) and
+the second parameter is the General MIDI instrument number (0 to 127).
+Note that the numbering starts from #0 while many GM instrument
+tables start from #1.
+
+SEQ_LOAD_GMDRUM(dev#, drum#) is similar than the above but it loads
+an General MIDI percussive instrument.
+
+5) After the above steps your program is ready to start playing.
+
+Examples for using OSSlib and for playing MIDI data can be found
+in ../mplay/* and ../gustest/midithru.c
+
+GUS support in OSSlib
+---------------------
+
+You will need the full GM patch set distributed with the Ultrasound
+drivers for DOS. The default location where the library tries to
+find the patches is /dos/ultrasnd/midi but you can change it by
+editing guslib.c (the second line). Alternative patch sets
+(such as midia) are available from the net. Another source is the MIDIA
+library.
+
+Since non PnP GUS has only 1M of
+RAM (at most) it's not possible to load the full patch set. When playing
+lot of MIDI files in sequence it's possible that the menory becomes
+full if the program doesn't reset the samples between files.
+
+OPL3 support in OSSlib
+----------------------
+
+OSSlib supports patch loading to OPL3 FM synth cards (older OPL2 cards
+are not supported). The patch set is included in the std.o3 and drums.o3
+files distributed with this package. These files should be copied to /etc
+(will be done by "make install"). These patch files are the same ones
+included in Adagio/glib package by Greg Lee. They are also distributed
+with playmidi.
+
+Using OSSlib with SoftOSS
+-------------------------
+
+For instructions about using OSSLib with SoftOSS see the instructions
+for GUS (above).
+
+
+For more info about using OSSlib contact hannu@opensound.com