Updated Psound.txt

[The Greene Family <topcoder@mindspring.com>]

Thanks to some criticism by Mr. Smith I changed it.  Thank you for your 2
cents Mr. Smith.

At the end of each point, I've listed what version I would like to have it
finished by. By version, i mean  (for the most part there are a couple of
exceptions in there...) major release version like 1.0 or 2.0.

Derek
          PSound API - The PenguinPlay Sound Application Programming Interface

	First thing that I will state is obviously the language(s) used in PSound:
All of the lower-level functions will be in C.  At a later time it is possible that for
some systems, some functions will be rewritten in assembly, but C is the main language.
Higher-level wrappers will be written in C++, because the use of classes can/will make
API access much simpler and all-around easier.

	Now that, that part is out of the way, I will lsit the goals of the API, and how
they will, quite obviously, tentatively be accomplished.  The way they are accomplished
could be done a number of ways, obviously, on some of them, so anything in here could and
will change as time passes.

1) Provide a shared library "driver" structure. 1.0
  Basically, ELF shared Libraries, with the same function in each of them, except, they
are for different sound cards.  This makes things simple, so the end user knows what card
he or she has, and puts the PSound.so (or whatever the name may be) in his or her library
path and the game or other program may automatically access it, the only pre-requesite may
be that the user has a file in his or her /etc directory, which could be used by all of
Penguin Play, that holds information on the ports the card needs for access.  A simple
installation program could take care of that. This would make it simpler for sound
hardware manufacturers to write drivers for Linux. Of course, if this is unacceptable
a static library route could be taken, or, both could be done.

2) Provide flexible low-level sound access. 2.0
  This one is simple.  The sound team takes information on hardware,which is usually
available to the public domain on the internet.  We then test, debug, and retest.

3) Write a wrapper driver for OSS and ALSA. 1.0
      Most users will have OSS or ALSA as there actual driver and both have a card access API.
While I think the PSound team could do a better job of accessing the card
(Efficiency...Speed) A wrapper driver would be a nice feature for for users who own a
card supported by OSS and/or ALSA, but PSound does not have a card specific driver for
yet.

4) After the OSS and ALSA wrapper create C++ wrapper classes.1.0
   Perhaps actually, though we could do a lay-out of the low-level API, and then a
lay-out of the C++ wrappers.  I'm more inclined not to though, to be honest.  I'd prefer
to make sure of the API as a final on the low-level first.  So until further
notification, that is how it will be done.

5) CD Audio access. 1.0
   This is quite simple actually, and is done via IOCTL usually.

6) Provide functions to play MIDI files. 1.x
  This can be done through the OSS/ALSA wrapper driver.  This is of mediocre importance, but
as it is not extremely complicated, I'd like it done in the first version if possible, however
sound is first priority, I think.  (In other words, if you have time to do this, then do it!)

7) Provide functions to play MOD (XM,MOD, etc.) files. 2.0
  Can be done very much similarly to the MIDI files, except  to sound decent, it almost requires
wavetable-synthesis. However is can be done without it.

8) Provide functions to play WAVE, Creative Voice, and other common sound files. 1.0
  If you don't know how to do this, then go to www.wotsit.org and get information on it. :-)

9) Provide mixer functionality to allow for 3D sound, such as distance and location panning
(such as to the left or right.) 2.0
  This can get kind of complicated, but for the people who want to help out on it, I know of a
place that shows you how to do it.  Although, when I've done it, I've implemented it rather
differently.

10) Surround sound functionality. 2.0
  This I've never implemented, but since you need a card which supports more than two speakers
to use it, most hardware manufacturer's docs will tell you how to do it on their card...plus ALSA
I'm sure does or will support it. ( I have not actually looked.)

11) Access to sound and music files of all types via PenguinPlay PAK files. 1.0
   This is a must. Period.

12) Code that is portable across systems, and OSes. 0.01
 Portability is important obviously due to the very nature of Penguin Play.  In other words,
if you are on this project and producing non-portable code, you WILL, be asked to go back and
rewrite the code.

13) Provide functions to record. 1.0
 Very useful!  Most programmers will use this, because a new "fad" in gaming is
real-time voice communications.

14) Provide functions to compress sound so that  it may be sent across the network/internet in
smaller form,to make more efficient use of bandwidth. 2.0
  Any number of compression algorithms could be used...several should be due tot he fact that
some will use the CPU more than others.  This would be useful to users who have higher or lower
speed CPUs and higher or lower speed access to the network.


Derek Greene
Sound Team Lead
28 March 1999