What you are suggesting works -- but ONLY if Csound ITSELF is a DLL. In
other words, the scheme you suggest would work for CsoundVST or some other
DLL version of the Csound API, but it would NOT allow plugin opcodes to
automagically link with a statically linked Csound APPLICATION.

I would prefer, indeed, that the base object in the Csound world be a
Csound API DLL or shared library! And that the command-line version of
Csound link dynamically to the API library! But as long as that is not
ALWAYS the case, the function pointer scheme IS the lowest common
denominator method that WILL work in all cases.

Furthermore, linking directly with a DLL across versions, as we require, is
only possible on Windows through the use of a .def file to define ordinal
numbers, which introduces another unnecessary complication. So the function
table scheme is actually simpler (which is why Microsoft adopted it for
COM).

I considered all these issues when I designed the API, and I took into
consideration advice from other Csound developers. As far as I know, the
function table scheme is the simplest, most foolproof way to get plugin
opcodes that can talk back to Csound across version and across platforms.


Original Message:
-----------------
From: stevenyi stevenyi@csounds.com
Date: Tue, 18 Nov 2003 21:11:06 -0800
To: csound-dev@eartha.mills.edu
Subject: [CSOUND-DEV:3397] Re: Csound API Split, design


> As for linking with libcsound.a at run time, that sort of thing is
standard
> on Linux and Unix, but on Windows, you can't link at run time without
either
> (a) coding with LoadLibrary and GetProcAddress, or (b) linking with a
static
> import library. The Csound scheme should work on all platforms and
therefore
> must be a lowest common denominator, which means exporting only functions
> and having the host push the function table into the plugin so that these
> issues need not arise.

Yikes!  I didn't realize windows dll's were so nuts. I started reading
into static import libraries and DEF files and __declspec(dllexport) and
__declspec(dllimport) and it's quite a chore. I did find this though:

http://cygwin.com/ml/cygwin/2000-06/msg00688.html

and if I understand it correctly, we'd be able to get rid of the
function pointers in the GLOBAL struct and have all the symbols exported
and imported and linked correctly for windows.  Granted, for windows
opcode plugin developers they would have to add -DUSEDLL compiler flag,
but that's nothing compared to having to make the jump to using function
pointers.  

This seems like it would also be as future-proof as your function table
system, i.e. as long as none of the exported functions are removed,
you're fine.  It does have the advantage of not needing to rely on
maintaining the order of function pointers in the GLOBAL struct. 

I really hope this will work out as a possible solution.  I think the
study of building an Opcode Plugin, say, at a University electronic
music/programming course would be greatly eased if they didn't have to
deal with function pointers and the syntax that surrounds their use. 
Also, I think this will be much easier to generate doxygen documentation
for as we could do it per-function as opposed to one large doc that
would have to explain every entry in the whole GLOBAL struct. 

Thanks,
steven


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

Oh well, I guess it was all just wishful thinking on my part.  Thanks
very much for spending the time to explain all of this; it's probably
been the most I've learned in terms of programming in quite some time. 
(And a as a side effect, I think I'm finally beginning to understand
what my COM programmer friend from my last job was talking about!). 

I think I agree with the author of that email I found that "the MS
engineers were on crack when they designed Windows DLLs".  =)  

But now I'll move on to probably another annoying question: does parity
have to be maintained between the API functions and what function
pointers are in GLOBAL?  I still haven't shaken off that funny feeling
about opcode plugins getting access to csoundCompile, csoundReset, and
other functions that seem very much for host-use only.  

And in regards to pushing everything into csound.h, wouldn't that cause
all the trouble with linking against the host API functions and
requiring libcsound.a?  It seems that the API for hosts and plugins then
*would* have to be split into two files. (I noticed in
csound4/soundfonts the headers only include cs.h and not csound.h).

Thanks again!
steven


On Wed, 2003-11-19 at 06:38, gogins@pipeline.com wrote:
> What you are suggesting works -- but ONLY if Csound ITSELF is a DLL. In
> other words, the scheme you suggest would work for CsoundVST or some other
> DLL version of the Csound API, but it would NOT allow plugin opcodes to
> automagically link with a statically linked Csound APPLICATION.
> 
> I would prefer, indeed, that the base object in the Csound world be a
> Csound API DLL or shared library! And that the command-line version of
> Csound link dynamically to the API library! But as long as that is not
> ALWAYS the case, the function pointer scheme IS the lowest common
> denominator method that WILL work in all cases.
> 
> Furthermore, linking directly with a DLL across versions, as we require, is
> only possible on Windows through the use of a .def file to define ordinal
> numbers, which introduces another unnecessary complication. So the function
> table scheme is actually simpler (which is why Microsoft adopted it for
> COM).
> 
> I considered all these issues when I designed the API, and I took into
> consideration advice from other Csound developers. As far as I know, the
> function table scheme is the simplest, most foolproof way to get plugin
> opcodes that can talk back to Csound across version and across platforms.
> 

it probably is possible to create a file of macro definitions or simple
c functions we could distribute as part of an SDK to include in
plugins/hosts sources that wrap the function pointer stuff.

for instance, may a C++ class that would have functions like:

#include csound.h

int Csound::GetKsmps()
{
  return mCsound->csoundGetKsmps(mCsound);
}

and i guess a macro would be

#define GetKsmps(x) x->csoundGetKsmps(x);
???

-m

On Wed, 19 Nov 2003, gogins@pipeline.com wrote:

> What you are suggesting works -- but ONLY if Csound ITSELF is a DLL. In
> other words, the scheme you suggest would work for CsoundVST or some other
> DLL version of the Csound API, but it would NOT allow plugin opcodes to
> automagically link with a statically linked Csound APPLICATION.
>
> I would prefer, indeed, that the base object in the Csound world be a
> Csound API DLL or shared library! And that the command-line version of
> Csound link dynamically to the API library! But as long as that is not
> ALWAYS the case, the function pointer scheme IS the lowest common
> denominator method that WILL work in all cases.
>
> Furthermore, linking directly with a DLL across versions, as we require, is
> only possible on Windows through the use of a .def file to define ordinal
> numbers, which introduces another unnecessary complication. So the function
> table scheme is actually simpler (which is why Microsoft adopted it for
> COM).
>
> I considered all these issues when I designed the API, and I took into
> consideration advice from other Csound developers. As far as I know, the
> function table scheme is the simplest, most foolproof way to get plugin
> opcodes that can talk back to Csound across version and across platforms.
>
>
> Original Message:
> -----------------
> From: stevenyi stevenyi@csounds.com
> Date: Tue, 18 Nov 2003 21:11:06 -0800
> To: csound-dev@eartha.mills.edu
> Subject: [CSOUND-DEV:3397] Re: Csound API Split, design
>
>
> > As for linking with libcsound.a at run time, that sort of thing is
> standard
> > on Linux and Unix, but on Windows, you can't link at run time without
> either
> > (a) coding with LoadLibrary and GetProcAddress, or (b) linking with a
> static
> > import library. The Csound scheme should work on all platforms and
> therefore
> > must be a lowest common denominator, which means exporting only functions
> > and having the host push the function table into the plugin so that these
> > issues need not arise.
>
> Yikes!  I didn't realize windows dll's were so nuts. I started reading
> into static import libraries and DEF files and __declspec(dllexport) and
> __declspec(dllimport) and it's quite a chore. I did find this though:
>
> http://cygwin.com/ml/cygwin/2000-06/msg00688.html
>
> and if I understand it correctly, we'd be able to get rid of the
> function pointers in the GLOBAL struct and have all the symbols exported
> and imported and linked correctly for windows.  Granted, for windows
> opcode plugin developers they would have to add -DUSEDLL compiler flag,
> but that's nothing compared to having to make the jump to using function
> pointers.
>
> This seems like it would also be as future-proof as your function table
> system, i.e. as long as none of the exported functions are removed,
> you're fine.  It does have the advantage of not needing to rely on
> maintaining the order of function pointers in the GLOBAL struct.
>
> I really hope this will work out as a possible solution.  I think the
> study of building an Opcode Plugin, say, at a University electronic
> music/programming course would be greatly eased if they didn't have to
> deal with function pointers and the syntax that surrounds their use.
> Also, I think this will be much easier to generate doxygen documentation
> for as we could do it per-function as opposed to one large doc that
> would have to explain every entry in the whole GLOBAL struct.
>
> Thanks,
> steven
>
>
> --------------------------------------------------------------------
> mail2web - Check your email from the web at
> http://mail2web.com/ .
>
>

> And in regards to pushing everything into csound.h, wouldn't that cause
> all the trouble with linking against the host API functions and
> requiring libcsound.a?  It seems that the API for hosts and plugins then

but all the functions you call from csound.h are via a pointer, so you
have no linking issues, or am i not understanding what you are saying?
-m
>
> On Wed, 2003-11-19 at 06:38, gogins@pipeline.com wrote:
> > What you are suggesting works -- but ONLY if Csound ITSELF is a DLL. In
> > other words, the scheme you suggest would work for CsoundVST or some other
> > DLL version of the Csound API, but it would NOT allow plugin opcodes to
> > automagically link with a statically linked Csound APPLICATION.
> >
> > I would prefer, indeed, that the base object in the Csound world be a
> > Csound API DLL or shared library! And that the command-line version of
> > Csound link dynamically to the API library! But as long as that is not
> > ALWAYS the case, the function pointer scheme IS the lowest common
> > denominator method that WILL work in all cases.
> >
> > Furthermore, linking directly with a DLL across versions, as we require, is
> > only possible on Windows through the use of a .def file to define ordinal
> > numbers, which introduces another unnecessary complication. So the function
> > table scheme is actually simpler (which is why Microsoft adopted it for
> > COM).
> >
> > I considered all these issues when I designed the API, and I took into
> > consideration advice from other Csound developers. As far as I know, the
> > function table scheme is the simplest, most foolproof way to get plugin
> > opcodes that can talk back to Csound across version and across platforms.
> >
>
>

Have you looked at csdl.h ?

ha! nope...





On Wed, 19 Nov 2003, John ffitch wrote:

> Have you looked at csdl.h ?
>
>

Matt J. Ingalls wrote:

>>And in regards to pushing everything into csound.h, wouldn't that cause
>>all the trouble with linking against the host API functions and
>>requiring libcsound.a?  It seems that the API for hosts and plugins then
>>    
>>
>
>but all the functions you call from csound.h are via a pointer, so you
>have no linking issues, or am i not understanding what you are saying?
>-m
>
[probably a rudimentary question]
Maybe this is where my inexperience shows through, but if the 
csoundXXX(...) function prototypes in csound.h are used when compiling 
an opcode plugin, won't the runtime linker then expect to link up 
csoundXXX(...) functions to the opcode plugin, considering that csound.c 
implementation of the functions are compiled with csound and not with 
the plugin?  It's not the function pointers in the GLOBAL I was worried 
about, but the csoundXXX(...) prototypes. 

thanks for any clarifications!
steven

Forget my last post and my I think I'm cleared up on up on why csound.h 
won't have any problems with csoundXXX(...) functions and opcode 
plugins.  (Did a simple test to realize as long as you don't call the 
csoundXXX(...) functions you're fine...)

Thanks everyone and sorry for all the grief over this misunderstanding 
of mine!
steven