Also, could everybody who has contributed to the Csound API let me know who
they are so that I can credit them? That includes at least Matt Ingalls and
John Ramsdell in addition to myself. 

Original Message:
-----------------
From: gogins@pipeline.com gogins@pipeline.com
Date: Thu, 1 Jan 2004 17:14:05 -0500
To: csound-dev@eartha.mills.edu
Subject: [CSOUND-DEV:3862] API Documenation


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/ .


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

For flCsound, I built a version of FLTK on Cygwin using the
-mno-cygwin option.  I then built Csound version 4.23.1 with the same
option and configured to use the Cygwin disabled version of FLTK.  I
fully expected to finally be able to generate a GUI for Csound on
Windows that can render multiple times, but no, the new programs fails
in oload as does wxCsound.

Previously, I verified that the Csound driver program, the one that
repeats a rendering twenty times, works on Cygwin both when compiled
with and without -mno-cygwin.  The Csound library used in these tests
were compiled without window support, in other words, WINDOW is not
defined.  Linking the driver with the Csound library configured to use
FLTK exhibits the memory error.  On windows, it appears there is
something preventing multiple rendering, but only when the library is
built with WINDOW defined.

John

"gogins@pipeline.com"  writes:

> Also, could everybody who has contributed to the Csound API let me know who
> they are so that I can credit them? That includes at least Matt Ingalls and
> John Ramsdell in addition to myself. 

If you have a good set of words on this subject, please use them to
replace what is in the file AUTHORS in the csound module.  I didn't
know what else to do, so it is currently silly.

John

My bug report on the memory error was incorrect.  The bug is present
when Csound is compiled with MinGW and Cygwin with -mno-cygwin, and
absent on Cygwin without -mno-cygwin and Linux.  Compiling with WINDOW
defined makes no difference.  Sorry for any confusion I caused.  Thus
wxCsound or flCsound work fine on Windows as long as they are compiled
using the Cygwin libraries.

John

ramsdell@mitre.org (John D. Ramsdell) writes:

> For flCsound, I built a version of FLTK on Cygwin using the
> -mno-cygwin option.  I then built Csound version 4.23.1 with the same
> option and configured to use the Cygwin disabled version of FLTK.  I
> fully expected to finally be able to generate a GUI for Csound on
> Windows that can render multiple times, but no, the new programs fails
> in oload as does wxCsound.
> 
> Previously, I verified that the Csound driver program, the one that
> repeats a rendering twenty times, works on Cygwin both when compiled
> with and without -mno-cygwin.  The Csound library used in these tests
> were compiled without window support, in other words, WINDOW is not
> defined.  Linking the driver with the Csound library configured to use
> FLTK exhibits the memory error.  On windows, it appears there is
> something preventing multiple rendering, but only when the library is
> built with WINDOW defined.
> 
> John