About OSSlib (freeware version)
===============================

NOTICE! This version of OSSlib is just an incomplete preview version.


This is a prototype version of OSSlib which supports patch caching
for cards like GUS, OPL3 and AWE32 (currently just GUS and OPL3 are supported).

This library version is intended to be used with OSS/Free
(version 3.8a or later is required). There will be another version
of this library for the commercial OSS versions so don't install this
one blindly without checking if the library is already installed.

Copying conditions
------------------

This freeware version of OSSlib is distributed under terms
and conditions defined by GNU Library General Public License (LGPL).
See COPYING for more info.

Note that this is a "freeware" version of OSSlib which is _not_
supported by 4Front Technologies. Please send any bug reports
fixes or suggestions directly to Hannu Savolainen 
(hannu@opensound.com).

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.

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
