Here it is!

[The Greene Family <colskywalker@thepentagon.com>]

	Constructive criticism is welcome, all out negativity is too. :-)  Feel
free to call me an idiot and tell me I will never work on a Linux project
again, that i need to rewrite, tha is rocks, or whatever.  I'll call this plan
draft 0.01 pre-alpha. :-)

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.
  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.
  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) After low-level sound access has been completed for a few "drivers," create
C++ wrapper classes.
   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.

4) Write a wrapper driver for OSS and ALSA.
      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.

	Ultimately, goals would have to include PSound3D, which will be apart of this
project, however in a seperate library, basing it's access off of PSound - and I will
write up seperate plans for it.  Hardware functions are another issue.  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.

        The API will include functions for accessing common and popular sound files
and playing them, mixing sound, and of course accessing sounds from PAK style formats.


Derek Greene
Sound Team Lead
26 March 1999