|
|
|
|
An event in Cscore is equivalent to one statement of a standard numeric score or time-warped score (see any score.srt), stored internally in time-warped format. It is either created in-line, or read in from an existing score file (either format). Its main components are an opcode and an array of pfield values. It is stored somewhere in memory, organized by a structure that starts as follows:
typedef struct {
CSHDR h; /* space-managing header */
long op; /* opcode-t, w, f, i, a, s or e */
long pcnt; /* number of pfields p1, p2, p3 ... */
long strlen; /* length of optional string argument */
char *strarg; /* address of optional string argument */
float p2orig; /* unwarped p2, p3 */
float p3orig;
float offtim; /* storage used during performance */
float p[1]; /* array of pfields p0, p1, p2 ... */
} EVENT;
Any function subprogram that creates, reads, or copies an event will return a pointer to the storage structure holding the event data. The event pointer can be used to access any component of the structure, in the form of e-op or e-p[n]. Each newly stored event will give rise to a new pointer, and a sequence of new events will generate a sequence of distinct pointers that must themselves be stored. Groups of event pointers are stored in an event list, which has its own structure:
typedef struct {
CSHDR h;
int nslots; /* max events in this event list */
int nevents; /* number of events present */
EVENT *e[1]; /* array of event pointers e0, e1, e2.. */
} EVLIST;
Any function that creates or modifies a list will return a pointer to the new list. The list pointer can be used to access any of its component event pointers, in the form of a-e[n]. Event pointers and list pointers are thus primary tools for manipulating the data of a score file. Pointers and lists of pointers can be copied and reordered without modifying the data values they refer to. This means that notes and phrases can be copied and manipulated from a high level of control. Alternatively, the data within an event or group of events can be modified without changing the event or list pointers. The Cscore function subprograms enable scores to be created and manipulated in this way.
In the following summary of Cscore function calls, some simple naming conventions are used:
the symbols e, f are pointers to events (notes);
the symbols a, b are pointers to lists (arrays) of such events;
the letters ev at the end of a function name signify operation on an event;
the letter l at the start of a function name signifies operation on a list.
the symbol fp is a score input stream file pointer (FILE *);
calling syntax description
e = createv(n); create a blank event with n pfields
int n;
e = defev("..."); defines an event as per the character string ...
e = copyev(f); make a new copy of event f
e = getev(); read the next event in the score input file
putev(e); write event e to the score output file
putstr("..."); write the string-defined event to score output
a = lcreat(n); create an empty event list with n slots
int n;
a = lappev(a,e); append event e to list a
a = lappstrev(a,"..."); append a string-defined event to list a;
a = lcopy(b); copy the list b (but not the events)
a = lcopyev(b); copy the events of b, making a new list
a = lget(); read all events from score input, up to next s or e
a = lgetnext(nbeats); read next nbeats beats from score input
float nbeats;
a = lgetuntil(beatno); read all events from score input up to beat beatno
float beatno;
a = lsepf(b); separate the f statements from list b into list a
a = lseptwf(b); separate the t,w & f statements from list b into list a
a = lcat(a,b); concatenate (append) the list b onto the list a
lsort(a); sort the list a into chronological order by p[2]
a = lxins(b,"..."); extract notes of instruments ... (no new events)
a = lxtimev(b,from,to); extract notes of time-span, creating new events
float from, to;
lput(a); write the events of list a to the score output file
lplay(a); send events of list a to the Csound orchestra for
immediate performance (or print events if no orchestra)
relev(e); release the space of event e
lrel(a); release the space of list a (but not the events)
lrelev(a); release the events of list a, and the list space
fp = getcurfp(); get the currently active input scorefile pointer
(initially finds the command-line input scorefile pointer)
fp = filopen("filename"); open another input scorefile (maximum of 5)
setcurfp(fp); make fp the currently active scorefile pointer
filclose(fp); close the scorefile relating to FILE *fp
|
|
|
|