home *** CD-ROM | disk | FTP | other *** search
/ ftp.4front-tech.com / ftp.4front-tech.com.tar / ftp.4front-tech.com / ossfree / snd-util-3.8.tar.gz / snd-util-3.8.tar / sndkit / OSSlib / Readme < prev    next >
Text File  |  1997-12-08  |  4KB  |  124 lines
  1. About OSSlib (freeware version)
  2. ===============================
  3.  
  4. NOTICE! This version of OSSlib is just an incomplete preview version.
  5.  
  6.  
  7. This is a prototype version of OSSlib which supports patch caching
  8. for cards like GUS, OPL3 and AWE32 (currently just GUS and OPL3 are supported).
  9.  
  10. This library version is intended to be used with OSS/Free
  11. (version 3.8a or later is required). There will be another version
  12. of this library for the commercial OSS versions so don't install this
  13. one blindly without checking if the library is already installed.
  14.  
  15. Copying conditions
  16. ------------------
  17.  
  18. This freeware version of OSSlib is distributed under terms
  19. and conditions defined by GNU Library General Public License (LGPL).
  20. See COPYING for more info.
  21.  
  22. Note that this is a "freeware" version of OSSlib which is _not_
  23. supported by 4Front Technologies. Please send any bug reports
  24. fixes or suggestions directly to Hannu Savolainen 
  25. (hannu@opensound.com).
  26.  
  27. Installing OSSlib
  28. -----------------
  29.  
  30. Execute make. If your operating system is recognized you will get
  31. libOSSlib.so or libOSSlib.a depending on operating system.
  32. If make complains about unknown operating system you should use
  33. make libOSSlib.so or make libOSSlib.a to build it. 
  34.  
  35. Finally copy libOSSlib.* to /usr/lib
  36.  
  37. Using OSSlib in programs
  38. ------------------------
  39.  
  40. OSSlib is intended to be used in programs using /dev/music but
  41. it also works with /dev/sequencer too. This version of the library
  42. contains only some basic patch caching functions to be used with
  43. OPL3 and GUS (and SoftOSS as well). Support for other cards is still 
  44. missing.
  45.  
  46. There are steps to be done when using OSSlib in a program:
  47.  
  48. 1) Change Makefile to use -DOSSLIB and -lOSSlib
  49.  
  50. Version 3.8 of <sys/soundcard.h> has been designed to be compatible
  51. with OSSlib when this OSSLIB is defined. You can also use 
  52. #ifdef OSSLIB in programs to cover the minor differences between
  53. the OSSlib and non OSSlib versions.
  54.  
  55. 2) If the program defines segbuf_dump() routine, put it inside
  56. #ifndef OSSLIB/#endif pair. This routine is included in OSSlib
  57. and having the same routine inside the program conflicts with it.
  58.  
  59. 3) Add the following call to the program after /dev/music is opened.
  60.  
  61. #ifdef OSSLIB
  62.     OSS_init(seqfd, 1024);
  63. #endif
  64.  
  65. In the above seqfd is the file descriptor of /dev/music and 1024
  66. is the size of the local buffer used for output events (1024 is
  67. a good value).
  68.  
  69. 4) Add patch caching calls to the program. Patch caching should
  70. be called as early as possible. It's recommended to load all
  71. _required_ patches before starting the actual playback since
  72. loading large patches from disk may introduce significant delays
  73. to playback.
  74.  
  75. There are two macros (in soundcard.h) to be used when loading 
  76. instruments:
  77.  
  78. SEQ_LOAD_GMINSTR(dev#, instr#) loads an instrument (melodic) patch.
  79. The first parameter is the synthesizer/device number (0 to N) and
  80. the second parameter is the General MIDI instrument number (0 to 127).
  81. Note that the numbering starts from #0 while many GM instrument
  82. tables start from #1.
  83.  
  84. SEQ_LOAD_GMDRUM(dev#, drum#) is similar than the above but it loads
  85. an General MIDI percussive instrument.
  86.  
  87. 5) After the above steps your program is ready to start playing.
  88.  
  89. Examples for using OSSlib and for playing MIDI data can be found
  90. in ../mplay/* and ../gustest/midithru.c
  91.  
  92. GUS support in OSSlib
  93. ---------------------
  94.  
  95. You will need the full GM patch set distributed with the Ultrasound
  96. drivers for DOS. The default location where the library tries to
  97. find the patches is /dos/ultrasnd/midi but you can change it by
  98. editing guslib.c (the second line). Alternative patch sets
  99. (such as midia) are available from the net.
  100.  
  101. Since non PnP GUS has only 1M of
  102. RAM (at most) it's not possible to load the full patch set. When playing
  103. lot of MIDI files in sequence it's possible that the menory becomes
  104. full if the program doesn't reset the samples between files.
  105.  
  106. OPL3 support in OSSlib
  107. ----------------------
  108.  
  109. OSSlib supports patch loading to OPL3 FM synth cards (older OPL2 cards
  110. are not supported). The patch set is included in the std.o3 and drums.o3
  111. files distributed with this package. These files should be copied to /etc
  112. (will be done by "make install"). These patch files are the same ones
  113. included in Adagio/glib package by Greg Lee. They are also distributed
  114. with playmidi.
  115.  
  116. Using OSSlib with SoftOSS
  117. -------------------------
  118.  
  119. For instructions about using OSSLib with SoftOSS see the instructions
  120. for GUS (above).
  121.  
  122.  
  123. For more info about using OSSlib contact hannu@opensound.com
  124.