I have updated csound.h in CVS for 4.23 with Doxygen-style comments at the
top of the file briefly documenting the purposes, usage, and TODOs of the
Csound API in its present form.

The generated documentation reads:

Detailed Description
Declares the public Csound application programming interface (API). 

Author: 
Michael Gogins

Purposes 

The purposes of the Csound API are as follows: 

Declare a stable public application programming interface (API) for Csound
in csound.h. This is the only header file that needs to be included by
users of the Csound API.

Hide the internal implementation details of Csound from users of the API,
so that development of Csound can proceed without affecting code that uses
the API.

Users 

Users of the Csound API fall into two main categories: hosts, and plugins: 

Hosts are applications that use Csound as a software synthesis engine.
Hosts can link with the Csound API either statically or dynamically. On
UNIX or Linux, the static library for the CsoundAPI is libcsound.a, and the
dynamic link library is libcsound.so. On Windows, the static library is
csound.lib, and the dynamic link library is csound.dll.
Plugins are shared libraries loaded by Csound at run time to implement
external opcodes and/or drivers for audio or MIDI input and output.
Hosts using the Csound API must include , and link with
libcsound.a or libcsound.so on UNIX or Linux, or csound.lib or csound.dll
on Windows. 

Hosts must first create an instance of Csound using the csoundCreate API
function. When hosts are finished using Csound, they must destroy the
instance of csound using the csoundDestroy API function. Most of the other
Csound API functions take the Csound instance as their first argument.
Hosts can call either the standalone API functions defined in csound.h,
e.g. csoundGetSr(csound), or the function pointers in the Csound instance
structure, e.g. csound->GetSr(csound). Each function in the Csound API has
a corresponding function pointer in the Csound instance structure. 

Here is the complete code for the simplest possible Csound API host, a
command-line Csound application: 

 #include 
 
 int main(int argc, char **argv)
 {
                void *csound = csoundCreate(0);
                int result = csoundPerform(csound, argc, argv);
                csoundCleanup(csound);
                csoundReset(csound);
                csoundDestroy(csound);
                return result;
 }

All opcodes, including plugins, receive a pointer to their host instance of
Csound in the opcode structure itself. Therefore, plugins MUST NOT create
an instance of Csound, and MUST call the Csound API function pointers off
the Csound instance pointer in the insdshead member of the OPDS structure,
for example: 

 MYFLT sr =
MyOpcodeStructure->h.insdshead->csound->GetSr(MyOpcodeStructure->h.insdshead
->csound);

In general, plugins should ONLY access Csound functionality through the API
function pointers. 

TODO 

The Csound API is not finished. At this time, Csound does not support
creating multiple instances of Csound in a single process, and the Csound
API functions do not all take a pointer to the Csound instance as their
first argument. This needs to be changed. 

In addition, some new functions need to be added to the API for various
purposes: 

Create and destroy function tables, get and set function table data.
Support for plugin audio, MIDI, and control drivers.
Support for configurating and accessing realtime audio busses.


--------------------------------------------------------------------
mail2web - Check your email from the web at
http://mail2web.com/ .

Michael,

What a wonderful idea to document the Csound API in this way.  I have
one comment for you to ponder.

"gogins@pipeline.com"  writes:

> On Windows, the static library is csound.lib, and the dynamic link
> library is csound.dll.

I'm not sure it is a good idea to specify the names of these libraries
as I think the build system determines the names.  On Cygwin, for
example, it appears the name selected is cygcsound-0.dll and it is
placed in the bin directory along with the binaries that use it.  I
suspect renaming the library will break the executables.

John