1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.03 [en] (X11; I; IRIX 6.3 IP32) [Netscape]">
<TITLE>ADDING_CMODULES_TO_CSOUND</TITLE>
</HEAD>
<BODY>
<CENTER><A NAME="Adding_Cmodules_to_Csound"></A>
<HR><B><A HREF="../REFER.html">QUICK-REF</A></B> - <B><A HREF="../TITLE.html"><FONT SIZE=+1>C</FONT>soundManual</A></B>
- <A HREF="CSCORE.html">Top of this section</A> - <A HREF="compiling.html">Previous</A>
- <A HREF="../CONTENTS.html">Contents</A> - <A HREF="../INDEX.html">Index</A>
- <B><A HREF="../Command/CSCOMM.html">Next Section</A></B>
<HR></CENTER>
<H2>
<BR>
Adding your own Cmodules to Csound</H2>
If the existing Csound generators do not suit your needs, you can write
your own modules in C and add them to the run-time system. When you invoke
Csound on an orchestra and score file, the orchestra is first read by a
table-driven translator 'otran' and the instrument blocks converted to
coded templates ready for loading into memory by 'oload' on request by
the score reader. To use your own C-modules within a standard orchestra
you need only add an entry in otran's table and relink Csound with your
own code.
<P>The translator, loader, and run-time monitor will treat your module
just like any other provided you follow some conventions. You need a <I>structure</I>
defining the inputs, outputs and workspace, plus some <I>initialization
code</I> and some <I>perf-time code</I>. Let's put an example of these
in two new files, <B>newgen.h</B> and <B>newgen.c</B>:
<PRE><TT> typedef struct { /* newgen.h - define a structure */
OPDS
h; /* required header */
float *result, *istrt, *incr, *itime, *icontin; /* addr outarg, inargs */
float curval, vincr; /* private dataspace */
long countdown; /* ditto */
} RMP;
#include "cs.h" /* newgen.c - init and perf code */
#include "newgen.h"
void rampset(RMP *p) /* at note initialization: */
{
if (*p->icontin == 0.)
p->curval = *p->istrt; /* optionally get new start value */
p->vincr = *p->incr / esr; /* set s-rate increment per sec. */
p->countdown = *p->itime * esr; /* counter for itime seconds */
}
void ramp(RMP *p) /* during note performance: */
{
float *rsltp = p->result; /* init an output array pointer */
int nn = ksmps; /* array size from orchestra */
do {
*rsltp++ = p->curval; /* copy current value to ouput */
if (--p->countdown >= 0) /* for the first itime seconds, */
p->curval += p->vincr; /* ramp the value */
} while (--nn);
}</TT></PRE>
Now we add this module to the translator table <B>entry.c</B>, under the
opcode name <B>rampt</B>:
<PRE><TT> #include "newgen.h"
void rampset(), ramp();
/* opcode dspace thread outarg inargs isub ksub asub */
{ "rampt", S(RMP), 5, "a", "iiio", rampset, NULL, ramp },</TT></PRE>
Finally we relink Csound to include the new module. If your Csound
installation has created a libcsound.a, you can do this by typing
<BR>
<BR><TT>cc -o mycsound newgen.c entry.c -lcsound
-lX11 -lm (X11 if included at installation)</TT>
<P>Else copy <I>*.c, *.h </I>and Makefile from the <B>Csound</B> sources,
add <B>newgen.o </B>to the Makefile list OBJS, add <B>newgen.h</B> as a
dependency for entry.o, and a new dependency '<B>newgen.o: newgen.h'</B>,
then run '<I>make csound</I>'. If your host is a Macintosh,
simply add <B>newgen.h and newgen.c</B> to one of the segments in the <B>Csound</B>
Project, and invoke the <B>C</B> compiler.
<BR>
<P>The above actions have added a new generator to the Csound language.
It is an audio-rate linear ramp function which modifies an input value
at a user-defined slope for some period. A ramp can optionally continue
from the previous note's last value. The Csound manual entry would look
like:
<PRE><TT> ar <B>rampt</B> istart, islope, itime [, icontin]</TT></PRE>
<I>istart</I> - beginning value of an audio-rate linear ramp. Optionally
overridden by a continue flag.
<P><I>islope</I> - slope of ramp, expressed as the y-interval change per
second.
<P><I>itime</I> - ramp time in seconds, after which the value is held for
the remainder of the note.
<P><I>icontin</I> (optional) - continue flag. If zero, ramping will proceed
from input <I>istart</I> . If non-zero, ramping will proceed from the last
value of the previous note. The default value is zero.
<P>The file <I>newgen.h</I> includes a one-line list of output and input
parameters. These are the ports through which the new generator will communicate
with the other generators in an instrument. Communication is by <I>address</I>,
not <I>value</I>, and this is a list of pointers to floats. There are no
restrictions on names, but the input-output argument types are further
defined by character strings in entry.c (inargs, outargs). Inarg types
are commonly <B>x</B>, <B>a</B>, <B>k</B>, and <B>i</B>, in the normal
Csound manual conventions; also available are o (optional, defaulting to
0), p (optional, defaulting to 1). Outarg types include <B>a</B>, <B>k</B>,
<B>i</B> and <B>s</B> (asig or ksig). It is important that all listed argument
names be assigned a corresponding argument type in entry.c. Also, i-type
args are valid only at initialization time, and other-type args are available
only at perf time. Subsequent lines in the RMP structure declare the work
space needed to keep the code re-entrant. These enable the module to be
used multiple times in multiple instrument copies while preserving all
data.
<P>The file <I>newgen.c</I> contains two subroutines, each called with
a pointer to the uniquely allocated RMP structure and its data. The subroutines
can be of three types: note initialization, k-rate signal generation, a-rate
signal generation. A module normally requires two of theseinitialization,
and either k-rate or a-rate subroutineswhich become inserted in various
threaded lists of runnable tasks when an instrument is activated. The thread-types
appear in entry.c in two forms: <I>isub</I>, <I>ksub</I> and <I>asub</I>
names; and a threading index which is the sum of isub=1, ksub=2, asub=4.
The code itself may reference global variables defined in <B>cs.h</B> and
<B>oload.c</B>, the most useful of which are:
<BR><TT> </TT>
<BR><TT> extern OPARMS O ;
float esr</TT>
<BR><TT> user-defined sampling rate
float ekr</TT>
<BR><TT> user-defined control rate
float ensmps</TT>
<BR><TT> user-defined ksmps
int ksmps</TT>
<BR><TT> user-defined ksmps
int nchnls</TT>
<BR><TT> user-defined nchnls
int O.odebug</TT>
<BR><TT> command-line -v flag
int O.msglevel</TT>
<BR><TT> command-line -m level
float pi, twopi obvious</TT>
<BR><TT> constants
float tpidsr twopi / esr float</TT>
<BR><TT> sstrcod
special code for string arguments</TT>
<H4>
<U>Function tables</U></H4>
To access stored function tables, special help is available. The newly
defined structure should include a pointer
<PRE><TT> FUNC *ftp;</TT></PRE>
initialized by the statement
<PRE><TT> ftp = ftpfind(p->ifuncno);</TT></PRE>
where float *ifuncno is an i-type input argument containing the ftable
number. The stored table is then at ftp->ftable, and other data such as
length, phase masks, cps-to-incr converters, are also accessed from this
pointer. See the FUNC structure in cs.h, the ftfind() code in fgens.c,
and the code for oscset() and koscil() in ugens2.c.
<H4>
<U>Additional space</U></H4>
Sometimes the space requirement of a module is too large to be part of
a structure (upper limit 65535 bytes), or it is dependent on an i-arg value
which is not known until initialization. Additional space can be dynamically
allocated and properly managed by including the line
<PRE><TT> AUXCH auxch;</TT></PRE>
in the defined structure (*p), then using the following style of code in
the init module:
<PRE><TT> if (p->auxch.auxp == NULL)
auxalloc(npoints * sizeof(float), &p->auxch);</TT></PRE>
The address of this auxilliary space is kept in a chain of such spaces
belonging to this instrument, and is automatically managed while the instrument
is being duplicated or garbage-collected during performance. The assignment
<PRE><TT> char *auxp = p->auxch.auxp;</TT></PRE>
will find the allocated space for init-time and perf-time use. See the
LINSEG structure in ugens1.h and the code for lsgset() and klnseg() in
ugens1.c.
<H4>
<U>File sharing</U></H4>
When accessing an external file often, or doing it from multiple places,
it is often efficient to read the entire file into memory. This is accomplished
by including the line
<PRE><TT> MEMFIL *mfp;</TT></PRE>
in the defined structure (*p), then using the following style of code in
the init module:
<PRE><TT> if (p->mfp == NULL)
p->mfp = ldmemfile(filname);</TT></PRE>
where char *filname is a string name of the file requested. The data read
will be found between
<PRE><TT> (char *) p->mfp->beginp; and (char *) p->mfp->endp;</TT></PRE>
Loaded files do not belong to a particular instrument, but are automatically
shared for multiple access. See the ADSYN structure in ugens3.h and the
code for adset() and adsyn() in ugens3.c.
<H4>
<U>String arguments</U></H4>
To permit a quoted string input argument (float *ifilnam, say) in our defined
structure (*p), assign it the argtype <B>S</B> in entry.c, include another
member char *strarg in the structure, insert a line
<PRE><TT> TSTRARG( "rampt", RMP) \</TT></PRE>
in the file <B>oload.h</B>, and include the following code in the init
module:
<PRE><TT> if (*p->ifilnam == sstrcod)
strcpy(filename, unquote(p->strarg));</TT></PRE>
See the code for adset() in ugens3.c, lprdset() in ugens5.c, and pvset()
in ugens8.c.
</BODY>
<CENTER><P>
<HR><B><A HREF="../REFER.html">QUICK-REF</A></B> - <B><A HREF="../TITLE.html"><FONT SIZE=+1>C</FONT>soundManual</A></B>
- <A HREF="CSCORE.html">Top of this section</A> - <A HREF="compiling.html">Previous</A>
- <A HREF="../CONTENTS.html">Contents</A> - <A HREF="../INDEX.html">Index</A>
- <B><A HREF="../Command/CSCOMM.html">Next Section</A></B>
<HR></CENTER>
<P><CENTER>
<B><I><FONT COLOR="#006600">HTML Csound Manual - <FONT SIZE=-1>©
Jean Piché & Peter J. Nix, 1994-97</FONT></FONT></I></B>
</CENTER>
</HTML>
|
