I agree with Steven that there should be one header file usable by hosts and clients.

I agree with Istvan that there should be an API (high-level) that hides internals of the CSOUND structure, and that there should be another (low-level) API that exposes details of the CSOUND structure.

I suggest a compromise whereby there are 2 header files. The high level API would declare CSOUND as opaque and the low level API would declare all details of Csound internals. 

The compromise is that it should be possible to include either, or both, of these headers from any project. 

The vital point is that it is not wise to decide in advance what users of the API need to see or call. 

For example, I think if I were to write a composition environment in C using the Csound API, my program would need to reference all parts of the API to enumerate opcodes, create function tables, manage VST plugins, create lists of notes using cscore facilities, allocate memory, create threads, intercept opcode function calls, etc., etc.

Except for the plugin opcode header files, there is probably no need for any other header files in the Csound build. All the existing ones could be combined into the "complete" header.

Best,
Mike

-----Original Message-----
From: Steven Yi 
Sent: Aug 17, 2005 1:44 AM
To: Csound-dev 
Subject: [Cs-dev] csound.h

Hi All,

Regarding CS5 and a release, I think one thing that should be
addressed is the csound.h file.  I know with Matt's MacCsound, all
things necessary for either a plugin or host is contained in csound.h.
 I think this would be ideal.  Currently there's a split between
csound.h and csoundCore.h.  Any thoughts?

Also, at the moment with the current SConstruct files, all .h files
seem to be installed into /usr/local/include/csound which seems a bit
overkill.  I think it'd be great if we could start putting together a
separate opcode SDK package that has a very simple plugin opcode with
Makefile--which I think is plenty enough for an opcode plugin--that
can compile using just what will be installed, to help encourse
external opcode building.

Thanks,
steven


-------------------------------------------------------
SF.Net email is Sponsored by the Better Software Conference & EXPO
September 19-22, 2005 * San Francisco, CA * Development Lifecycle Practices
Agile & Plan-Driven Development * Managing Projects & Teams * Testing & QA
Security * Process Improvement & Measurement * http://www.sqe.com/bsce5sf
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/csound-devel





-------------------------------------------------------
SF.Net email is Sponsored by the Better Software Conference & EXPO
September 19-22, 2005 * San Francisco, CA * Development Lifecycle Practices
Agile & Plan-Driven Development * Managing Projects & Teams * Testing & QA
Security * Process Improvement & Measurement * http://www.sqe.com/bsce5sf
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Michael Gogins wrote:

> I suggest a compromise whereby there are 2 header files. The high
> level API would declare CSOUND as opaque and the low level API would
> declare all details of Csound internals.

A completely opaque CSOUND, while preferred for hosts, is not suitable
for plugins, because dynamically loaded libraries need access to at
least the function pointers, but preferably also to some variables.
Of course, one could just drop support for a static Csound library, and
then the plugins may simply link against the DLL file, but a plugin
still runs at a lower level (as a subroutine of csoundPreCompile,
csoundCompile, csoundPerformKsmps (and related), or csoundRunUtility)
than a host application.

> The compromise is that it should be possible to include either, or
> both, of these headers from any project.

I assume you do not want to include the low level csoundCore.h
interface in your project that is not part of the Csound library ?

> The vital point is that it is not wise to decide in advance what
> users of the API need to see or call.

Users of the API generally should not see anything that is either
not expected to work correctly if not run in the right context
(examples include many of the function pointers in CSOUND, intended
for use in plugin libraries only), or is subject to frequent
incompatible changes.

> For example, I think if I were to write a composition environment in
> C using the Csound API, my program would need to reference all parts
> of the API to enumerate opcodes, create function tables, manage VST
> plugins, create lists of notes using cscore facilities, allocate
> memory, create threads, intercept opcode function calls, etc., etc.

Then those facilities can be added to the API, with a well defined and
stable interface. However, just using some random low level internals
can be dangerous, even if it may often appear to work.



-------------------------------------------------------
SF.Net email is Sponsored by the Better Software Conference & EXPO
September 19-22, 2005 * San Francisco, CA * Development Lifecycle Practices
Agile & Plan-Driven Development * Managing Projects & Teams * Testing & QA
Security * Process Improvement & Measurement * http://www.sqe.com/bsce5sf
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net