Is there a current tutorial/manual section/what have you for learning 
the internals of csound to start fiddling with opcodes? I know we have 
some articles on csounds.com, but I don't know how much has changed with 
csound5 and whether some are now obsolete, so just thought I'd check 
here first.

Thanks
Iain


-------------------------------------------------------
This SF.Net email is sponsored by the 'Do More With Dual!' webinar happening
July 14 at 8am PDT/11am EDT. We invite you to explore the latest in dual
core and dual graphics technology at this free one hour event hosted by HP,
AMD, and NVIDIA.  To register visit http://www.hp.com/go/dualwebinar
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

The basics have not changed, but the model is to write opcodes as
plugins.  If you look at the files in Opcodes you will see the system
in action.

Main changes:
     Opcode init and perform functions return a value -- OK is
     success, or a non-zero number if fails.

     Opcode init and perform functions take two arguments; the first
     is the instance environment, usually called csound

     The API is used to access many functions and data rather than
     directly

     Include the LINKAGE macro or equivalent to make opcodes known to
     system.

     There must be NO STATIC DATA in the implementation --  well no
     changing static data, but best is to have none.

There may be others I have forgotten.

==John ffitch


-------------------------------------------------------
This SF.Net email is sponsored by the 'Do More With Dual!' webinar happening
July 14 at 8am PDT/11am EDT. We invite you to explore the latest in dual
core and dual graphics technology at this free one hour event hosted by HP,
AMD, and NVIDIA.  To register visit http://www.hp.com/go/dualwebinar
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Thanks. I'll get reading. =)

Iain

jpff@codemist.co.uk wrote:
> The basics have not changed, but the model is to write opcodes as
> plugins.  If you look at the files in Opcodes you will see the system
> in action.
> 
> Main changes:
>      Opcode init and perform functions return a value -- OK is
>      success, or a non-zero number if fails.
> 
>      Opcode init and perform functions take two arguments; the first
>      is the instance environment, usually called csound
> 
>      The API is used to access many functions and data rather than
>      directly
> 
>      Include the LINKAGE macro or equivalent to make opcodes known to
>      system.
> 
>      There must be NO STATIC DATA in the implementation --  well no
>      changing static data, but best is to have none.
> 
> There may be others I have forgotten.
> 
> ==John ffitch
> 
> 
> -------------------------------------------------------
> This SF.Net email is sponsored by the 'Do More With Dual!' webinar happening
> July 14 at 8am PDT/11am EDT. We invite you to explore the latest in dual
> core and dual graphics technology at this free one hour event hosted by HP,
> AMD, and NVIDIA.  To register visit http://www.hp.com/go/dualwebinar
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
> 


-------------------------------------------------------
This SF.Net email is sponsored by the 'Do More With Dual!' webinar happening
July 14 at 8am PDT/11am EDT. We invite you to explore the latest in dual
core and dual graphics technology at this free one hour event hosted by HP,
AMD, and NVIDIA.  To register visit http://www.hp.com/go/dualwebinar
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Some simple questions for anyone who has time to explain it, no biggy if 
no one does ...

> Main changes:
>      Opcode init and perform functions return a value -- OK is
>      success, or a non-zero number if fails.

Is there a standard set of error code returns that I should look up?

>      Opcode init and perform functions take two arguments; the first
>      is the instance environment, usually called csound

The second being a pointer to user data for the functions?

>      The API is used to access many functions and data rather than
>      directly

Ok, I guess I should look thoroughly through there for stuff I shouldn't 
do on my own. Any particulars to watch out for?

>      Include the LINKAGE macro or equivalent to make opcodes known to
>      system.

Is this the equivalent of adding it to entry.c in the old example?

>      There must be NO STATIC DATA in the implementation --  well no
>      changing static data, but best is to have none.

I take it this is so that the opcode function is re-entrant and can 
exist many times in many threads?

Thanks
Iain


-------------------------------------------------------
This SF.Net email is sponsored by the 'Do More With Dual!' webinar happening
July 14 at 8am PDT/11am EDT. We invite you to explore the latest in dual
core and dual graphics technology at this free one hour event hosted by HP,
AMD, and NVIDIA.  To register visit http://www.hp.com/go/dualwebinar
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

>>>>> "Iain" == Iain Duncan  writes:

 Iain> Some simple questions for anyone who has time to explain it, no biggy if 
 Iain> no one does ...

 >> Main changes:
 >> Opcode init and perform functions return a value -- OK is
 >> success, or a non-zero number if fails.

 Iain> Is there a standard set of error code returns that I should look up?

No; that never happened.  At present OK and NOTOK are all there are

 >> Opcode init and perform functions take two arguments; the first
 >> is the instance environment, usually called csound

 Iain> The second being a pointer to user data for the functions?

Yes, the second argument is the pointer to the opcode structure

 >> The API is used to access many functions and data rather than
 >> directly

 Iain> Ok, I guess I should look thoroughly through there for stuff I shouldn't 
 Iain> do on my own. Any particulars to watch out for?

I have not seen the full API documentation, but looking at other
opcodes should help.  Values like sr and kr are accessed via the
csound structure, and messages use csound->Message(csound,
"format",...) instead of printf

 >> Include the LINKAGE macro or equivalent to make opcodes known to
 >> system.

 Iain> Is this the equivalent of adding it to entry.c in the old example?

Yes.  There is a structure to be equivalent to entry, and the LINKAGE
macro declares a couple of simple functions to effect the linkage.  In
more complex cases it may be necessary to write this code explicitly.

Note that fgens can be done in a similar way, and also I/O drivers
(but I have not looked at them).

 >> There must be NO STATIC DATA in the implementation --  well no
 >> changing static data, but best is to have none.

 Iain> I take it this is so that the opcode function is re-entrant and can 
 Iain> exist many times in many threads?

Exactly.

Last thought; if you write a new file then it deeds to be added to the
SConstruct file.  Rather easy; find the comment
# Plugin opcodes.
about line 265, and add the lines

pluginLibraries.append(pluginEnvironment.SharedLibrary('myop',
    ['Opcodes/myop.c']))

in the correct alphabetical place -- not necessary but it is tidy that
way.

==John ffitch


-------------------------------------------------------
This SF.Net email is sponsored by the 'Do More With Dual!' webinar happening
July 14 at 8am PDT/11am EDT. We invite you to explore the latest in dual
core and dual graphics technology at this free one hour event hosted by HP,
AMD, and NVIDIA.  To register visit http://www.hp.com/go/dualwebinar
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Thanks again John. With your help, most of what I encountered in reading 
the beginning of ugens1.c is making sense.

>  >> The API is used to access many functions and data rather than
>  >> directly
> 
>  Iain> Ok, I guess I should look thoroughly through there for stuff I shouldn't 
>  Iain> do on my own. Any particulars to watch out for?
> 
> I have not seen the full API documentation, but looking at other
> opcodes should help.  Values like sr and kr are accessed via the
> csound structure, and messages use csound->Message(csound,
> "format",...) instead of printf

Right, so any querying of csound should, if possible, be done inside the 
opcode code block with:

csound->somethingIwannaknow or csound->somethingIwannadoAPIfunction();

It's safe to call API functions as much as I want in an opcode then? ( 
Well, if it makes sense to do so I mean. )

Looking at LINE, I see both of these:
csound->ksmps
csound->ensmps
What are the differences between these two? And where ( if it is ) would 
all the components of the ENVIRON structure be documented? I found it's 
declaration but no comments.

Also, am I correct in thinking csound->onedkr is the duration of of one 
kperiod?

> Last thought; if you write a new file then it deeds to be added to the
> SConstruct file.  Rather easy; find the comment
> # Plugin opcodes.
> about line 265, and add the lines
> 
> pluginLibraries.append(pluginEnvironment.SharedLibrary('myop',
>     ['Opcodes/myop.c']))
> 
> in the correct alphabetical place -- not necessary but it is tidy that
> way.

Does this need to be done if it's a dynamically loaded plug in? I got 
the impression from Victor's paper that csound will go look in the 
OPCODEDIR and load everything it finds anyway.

Thanks again
Iain


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Also forgot to ask:

I guess MYFLT is defined somewhere as being a platform and version 
independent kind of float that we should always use to hold data?

And does FL() convert values to proper ranges/format for MYFLT? So if we 
use numbers for data anywhere it should always be in the format of:

MYFLT	my_num;
my_num = FL( 2.6 );

Thanks
Iain



-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

MYFLT is a macro that expands to either 'float' or 'double', depending
on whether USE_DOUBLE is set (in other words, this is the default floating
point type that depends on whether you build a "single precision" or
"double precision" Csound). Of course, you can still use float or double
explicitly, should there be a reason for doing so.
The FL() macro is used to define floating point constants; if MYFLT is float,
it appends a 'f' to the argument, while if MYFLT is double, it does nothing.

Both macros are defined in H/sysdep.h.

Iain Duncan wrote:

> I guess MYFLT is defined somewhere as being a platform and version 
> independent kind of float that we should always use to hold data?
> 
> And does FL() convert values to proper ranges/format for MYFLT? So if we 
> use numbers for data anywhere it should always be in the format of:
> 
> MYFLT    my_num;
> my_num = FL( 2.6 );


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Iain Duncan wrote:

> Looking at LINE, I see both of these:
> csound->ksmps
> csound->ensmps
> What are the differences between these two? And where ( if it is ) would 
> all the components of the ENVIRON structure be documented? I found it's 
> declaration but no comments.

csound->ksmps (of type 'int') is, well, ksmps (more precisely, local ksmps
which can be overridden by UDOs; the global setting from the orchestra header
is csound->global_ksmps).
csound->ensmps (which has been removed recently, by the way, so you may want
to update from CVS to get a more up to date version of the ENVIRON structure)
is the same as csound->ksmps, just cast to MYFLT.

> Also, am I correct in thinking csound->onedkr is the duration of of one 
> kperiod?

Yes, in seconds. Note that if your opcode is called from a UDO, then
it will be the duration of a local k-period. The global value is
FL(1.0) / csound->global_ekr.

> Does this need to be done if it's a dynamically loaded plug in? I got 
> the impression from Victor's paper that csound will go look in the 
> OPCODEDIR and load everything it finds anyway.

That's correct, but you do want to compile the opcode with scons
first, so that it can be used.


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Iain Duncan wrote:

> And where ( if it is ) would all the components of the ENVIRON structure
 > be documented? I found it's declaration but no comments.

Here is a list of some of the commonly used public variables in ENVIRON.
It is by no means complete, but can be useful to get started:

     OPDS          *ids, *pds;           /* used by init and perf loops */

The currently performed opcode at init and perf time, respectively.

     int           ksmps, global_ksmps, nchnls, spoutactive;

global_ksmps:  the global ksmps value as defined in the orchestra header
ksmps:         the current (local) ksmps which can be overridden by UDOs
nchnls:        number of channels (header statement)

     long          kcounter, global_kcounter;

kcounter:        number of k-periods (in local ksmps units) elapsed since
                  the beginning of performance
global_kcounter: same as above, but in global k-periods (thus not affected
                  by UDOs, if any)

     int           reinitflag;

At init time, non-zero if a reinit is currently being done.
Undefined (i.e. can be any garbage) at performance time.

     int           tieflag;

At init time, non-zero if the current note is a tied note.
Undefined (i.e. can be any garbage) at performance time.

     MYFLT         esr, onedsr, sicvt;

esr:      orchestra sample rate (header statement)
onedsr:   1 / esr
sicvt:    16777216 / esr (or something like that, it is used by oscillators)

     MYFLT         tpidsr, pidsr, mpidsr, mtpdsr;

2*PI/esr, PI/esr, -(PI/esr), -(2*PI/esr), in this order.

     MYFLT         onedksmps;

1 / ksmps

     MYFLT         ekr, global_ekr;

global_ekr: global control rate (kr), as defined in orchestra header
ekr:        local control rate, usually same as above, but UDOs can
             change it

     MYFLT         onedkr;

1 / ekr

     MYFLT         kicvt;

16777216 / ekr (or something like that, it is used by oscillators)

     MYFLT         e0dbfs, dbfs_to_float;

e0dbfs:        0dbfs header setting (or 32768.0 by default)
dbfs_to_float: 1 / e0dbfs

     double        timeOffs, beatOffs;   /* start time of current section    */

timeOffs: start time of current section in seconds
beatOffs: start time of current section in beats - may or may not be correct

     double        curTime, curTime_inc; /* cur. time in secs, inc. per kprd */
     double        curBeat, curBeat_inc; /* cur. time in beats, inc per kprd */

curTime: current score time (measured from the beginning of performance)
          in seconds
curBeat: similar to curTime, just in beats; only expect it to work reliably
          in "beat mode", with a single section score

curTime_inc: 1 / global_ekr
curBeat_inc: for beat mode: curBeat is advanced by this value per global k-period

     double        beatTime;             /* beat time = 60 / tempo           */

For beat mode: the duration of a beat, in seconds.

     MYFLT         *zkstart;
     MYFLT         *zastart;

Pointers to k- and a-rate ZAK space; may be NULL if not allocated.

     long          zklast;
     long          zalast;

The highest valid index to k- and a-rate ZAK space (assuming, of course,
that there is any ZAK space allocated in the first place).

     OPARMS        *oparms;

A structure containing various settings that can be controlled from the
command line, such as message level, buffer sizes, output file name, and
many others.

     EVTBLK        *currevent;

Pointer to the current score event (at i-time), or some random junk
if current note is MIDI or at performance time.

     INSDS         *curip;

Current instrument instance, valid only at i-time. At performance time,
it is undefined.

     void          *hostdata;

The "host data" pointer passed by the host application when calling
csoundCreate().

     void          *rtRecord_userdata;
     void          *rtPlay_userdata;

General purpose pointers reserved for the audio I/O driver (e.g. rtpa.c).
Not to be used anywhere else.

     char          *orchname, *scorename;

Orchestra and score name (likely to be temporary file names if performing
a CSD file).

     int           holdrand;

Current state of (some) random opcodes.

     int           strVarMaxLen;     /* maximum length of string variables + 1 */

Space allocated for string variables (of type 'S' or 'gS'), in bytes.

     int           maxinsno;

Highest allocated instrument number. Not all slots are actually used.

     int           strsmax;

Highest allocated strset index. Not all slots are actually used.

     char          **strsets;

Array of strset strings. May be NULL if there are none.

     INSTRTXT      **instrtxtp;

Array of instrument templates (highest valid index is maxinsno).

     MCHNBLK       *m_chnbp[64];     /* reserve space for up to 4 MIDI devices */

Array of MIDI channels - only the first 16 are actually used at this time.


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

The functions in ENVIRON are not documented in csoundCore.h, however, many
of them have documentation for the equivalent global function in the various
header files in H/. These files are particularly worth having a look at:

   H/cfgvar.h
   H/csound.h
   H/envvar.h
   H/fftlib.h
   H/msg_attr.h
   H/namedins.h
   H/pvfileio.h
   H/soundio.h
   H/sysdep.h

Some functions are declared in H/prototyp.h, however, these are mostly
equivalents of old Csound 4 functions, and are used in a similar way,
except for the ENVIRON* pointer as the first argument.
Here is a list of a few frequently used ones:

void    csound->AuxAlloc(void *csound, long nbytes, AUXCH *);

Same as Csound 4 auxalloc, documented in old tutorials.

void    csound->Die(void *csound, const char *format, ...);
int     csound->InitError(void *csound, const char *format, ...);
int     csound->PerfError(void *csound, const char *format, ...);
void    csound->Warning(void *csound, const char *format, ...);
void    csound->DebugMsg(void *csound, const char *format, ...);

Print fatal error, init error, perf error, warning, or debug message
with printf-style format string and variable arguments.
csound->Die() does not return.

MYFLT * csound->GetTable(void *csound, int tableNum, int *length);

Returns pointer to function table data for tableNum (or NULL if there
is no such table), and stores table length (not including guard point)
in *length.

Of course, it is also a good way to find out more about the use of a
particular function to have a look at an opcode (preferably not a buggy
one) that uses it.


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Istvan, thanks you so much for taking the time to do that. That is 
extremely helpful, I'll add it to the pile eventually bound for some wiki!

>     MCHNBLK       *m_chnbp[64];     /* reserve space for up to 4 MIDI 
> devices */
> 
> Array of MIDI channels - only the first 16 are actually used at this time.

May I humbly suggest that this be changed to something like 8 or 16 midi 
devices? When using midi loopbacks, you can go through that many easily. 
( ie I have 4 on hardware 4 on virmidi. Many hardware interfaces have 8 
by themselves. )

Thanks
Iain


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Iain Duncan wrote:

> May I humbly suggest that this be changed to something like 8 or 16 midi 
> devices?

Would not make much of a difference, as only the first 16 channels
are used anyway. You can only use one MIDI input device at once, but
that can be any of the available devices regardless of how many there
are.


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

>> May I humbly suggest that this be changed to something like 8 or 16 
>> midi devices?
> 
> Would not make much of a difference, as only the first 16 channels
> are used anyway. You can only use one MIDI input device at once, but
> that can be any of the available devices regardless of how many there
> are.

I just meant for the future. I assume multiple devices is still on the 
eventual agenda?

Iain


-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net