Csound API  6.07
Performance

Functions

PUBLIC TREEcsoundParseOrc (CSOUND *csound, const char *str)
 Parse the given orchestra from an ASCII string into a TREE. More...
 
PUBLIC int csoundCompileTree (CSOUND *csound, TREE *root)
 Compile the given TREE node into structs for Csound to use this can be called during performance to compile a new TREE. More...
 
PUBLIC void csoundDeleteTree (CSOUND *csound, TREE *tree)
 Free the resources associated with the TREE *tree This function should be called whenever the TREE was created with csoundParseOrc and memory can be deallocated. More...
 
PUBLIC int csoundCompileOrc (CSOUND *csound, const char *str)
 Parse, and compile the given orchestra from an ASCII string, also evaluating any global space code (i-time only) this can be called during performance to compile a new orchestra. More...
 
PUBLIC MYFLT csoundEvalCode (CSOUND *csound, const char *str)
 Parse and compile an orchestra given on an string, evaluating any global space code (i-time only). More...
 
PUBLIC int csoundInitializeCscore (CSOUND *, FILE *insco, FILE *outsco)
 Prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e. More...
 
PUBLIC int csoundCompileArgs (CSOUND *, int argc, char **argv)
 Read arguments, parse and compile an orchestra, read, process and load a score. More...
 
PUBLIC int csoundStart (CSOUND *csound)
 Prepares Csound for performance after compilation using one or more of the above functions. More...
 
PUBLIC int csoundCompile (CSOUND *, int argc, char **argv)
 Compiles Csound input files (such as an orchestra and score, or CSD) as directed by the supplied command-line arguments, but does not perform them. More...
 
PUBLIC int csoundCompileCsd (CSOUND *csound, char *str)
 Compiles a Csound input file (CSD, .csd file) which includes command-line arguments, but does not perform the file. More...
 
PUBLIC int csoundCompileCsdText (CSOUND *csound, const char *csd_text)
 Compiles a Csound input file contained in a string of text, which includes command-line arguments, orchestra, score, etc., but does not perform the file. More...
 
PUBLIC int csoundPerform (CSOUND *)
 Senses input events and performs audio output until the end of score is reached (positive return value), an error occurs (negative return value), or performance is stopped by calling csoundStop() from another thread (zero return value). More...
 
PUBLIC int csoundPerformKsmps (CSOUND *)
 Senses input events, and performs one control sample worth (ksmps) of audio output. More...
 
PUBLIC int csoundPerformBuffer (CSOUND *)
 Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio. More...
 
PUBLIC void csoundStop (CSOUND *)
 Stops a csoundPerform() running in another thread. More...
 
PUBLIC int csoundCleanup (CSOUND *)
 Prints information about the end of a performance, and closes audio and MIDI devices. More...
 
PUBLIC void csoundReset (CSOUND *)
 Resets all internal memory and state in preparation for a new performance. More...
 

Detailed Description

Function Documentation

PUBLIC int csoundCleanup ( CSOUND )

Prints information about the end of a performance, and closes audio and MIDI devices.

Note: after calling csoundCleanup(), the operation of the perform functions is undefined.

PUBLIC int csoundCompile ( CSOUND ,
int  argc,
char **  argv 
)

Compiles Csound input files (such as an orchestra and score, or CSD) as directed by the supplied command-line arguments, but does not perform them.

Returns a non-zero error code on failure. This function cannot be called during performance, and before a repeated call, csoundReset() needs to be called. In this (host-driven) mode, the sequence of calls should be as follows: /code csoundCompile(csound, argc, argv); while (!csoundPerformBuffer(csound)); csoundCleanup(csound); csoundReset(csound); /endcode Calls csoundStart() internally. Can only be called again after reset (see csoundReset())

PUBLIC int csoundCompileArgs ( CSOUND ,
int  argc,
char **  argv 
)

Read arguments, parse and compile an orchestra, read, process and load a score.

PUBLIC int csoundCompileCsd ( CSOUND csound,
char *  str 
)

Compiles a Csound input file (CSD, .csd file) which includes command-line arguments, but does not perform the file.

Returns a non-zero error code on failure. In this (host-driven) mode, the sequence of calls should be as follows: /code csoundCompileCsd(csound, str); while (!csoundPerformBuffer(csound)); csoundCleanup(csound); csoundReset(csound); /endcode NB: this function can be called during performance to replace or add new instruments and events. On a first call and if called before csoundStart(), this function behaves similarly to csoundCompile()

PUBLIC int csoundCompileCsdText ( CSOUND csound,
const char *  csd_text 
)

Compiles a Csound input file contained in a string of text, which includes command-line arguments, orchestra, score, etc., but does not perform the file.

Returns a non-zero error code on failure. In this (host-driven) mode, the sequence of calls should be as follows: /code csoundCompileCsdText(csound, csd_text); while (!csoundPerformBuffer(csound)); csoundCleanup(csound); csoundReset(csound); /endcode NB: A temporary file is created, the csd_text is written to the temporary file, and csoundCompileCsd is called with the name of the temporary file, which is deleted after compilation. Behavior may vary by platform.

PUBLIC int csoundCompileOrc ( CSOUND csound,
const char *  str 
)

Parse, and compile the given orchestra from an ASCII string, also evaluating any global space code (i-time only) this can be called during performance to compile a new orchestra.

/code char *orc = "instr 1 \n a1 rand 0dbfs/4 \n out a1 \n"; csoundCompileOrc(csound, orc); /endcode

PUBLIC int csoundCompileTree ( CSOUND csound,
TREE root 
)

Compile the given TREE node into structs for Csound to use this can be called during performance to compile a new TREE.

PUBLIC void csoundDeleteTree ( CSOUND csound,
TREE tree 
)

Free the resources associated with the TREE *tree This function should be called whenever the TREE was created with csoundParseOrc and memory can be deallocated.

PUBLIC MYFLT csoundEvalCode ( CSOUND csound,
const char *  str 
)

Parse and compile an orchestra given on an string, evaluating any global space code (i-time only).

On SUCCESS it returns a value passed to the 'return' opcode in global space /code char *code = "i1 = 2 + 2 \n return i1 \n"; MYFLT retval = csoundEvalCode(csound, code); /endcode

PUBLIC int csoundInitializeCscore ( CSOUND ,
FILE *  insco,
FILE *  outsco 
)

Prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e.

"standalone Cscore"). It is an alternative to csoundCompile(), and csoundPerform*() and should not be used with these functions. You must call this function before using the interface in "cscore.h" when you do not wish to compile an orchestra. Pass it the already open FILE* pointers to the input and output score files. It returns CSOUND_SUCCESS on success and CSOUND_INITIALIZATION or other error code if it fails.

PUBLIC TREE* csoundParseOrc ( CSOUND csound,
const char *  str 
)

Parse the given orchestra from an ASCII string into a TREE.

This can be called during performance to parse new code.

PUBLIC int csoundPerform ( CSOUND )

Senses input events and performs audio output until the end of score is reached (positive return value), an error occurs (negative return value), or performance is stopped by calling csoundStop() from another thread (zero return value).

Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), csoundStart() must be called first. In the case of zero return value, csoundPerform() can be called again to continue the stopped performance. Otherwise, csoundReset() should be called to clean up after the finished or failed performance.

PUBLIC int csoundPerformBuffer ( CSOUND )

Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio.

Note that csoundCompile must be called first, then call csoundGetOutputBuffer() and csoundGetInputBuffer() to get the pointer to csound's I/O buffers. Returns false during performance, and true when performance is finished.

PUBLIC int csoundPerformKsmps ( CSOUND )

Senses input events, and performs one control sample worth (ksmps) of audio output.

Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), csoundStart() must be called first. Returns false during performance, and true when performance is finished. If called until it returns true, will perform an entire score. Enables external software to control the execution of Csound, and to synchronize performance with audio input and output.

PUBLIC void csoundReset ( CSOUND )

Resets all internal memory and state in preparation for a new performance.

Enables external software to run successive Csound performances without reloading Csound. Implies csoundCleanup(), unless already called.

PUBLIC int csoundStart ( CSOUND csound)

Prepares Csound for performance after compilation using one or more of the above functions.

NB: this is called internally by csoundCompile(), therefore it is only required if performance is started without a call to that function

PUBLIC void csoundStop ( CSOUND )

Stops a csoundPerform() running in another thread.

Note that it is not guaranteed that csoundPerform() has already stopped when this function returns.