Loading...
Searching...
No Matches
Performance

## Functions

PUBLIC TREE * | csoundParseOrc (CSOUND *csound, const char *str)
| Parse the given orchestra from an ASCII string into a TREE.
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 int | csoundCompileTreeAsync (CSOUND *csound, TREE *root)
| Asynchronous version of csoundCompileTree().
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 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.
PUBLIC int | csoundCompileOrcAsync (CSOUND *csound, const char *str)
| Async version of csoundCompileOrc().
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).
PUBLIC int | csoundInitializeCscore (CSOUND *, FILE *insco, FILE *outsco)
| Prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e.
PUBLIC int | csoundCompileArgs (CSOUND *, int argc, const char **argv)
| Read arguments, parse and compile an orchestra, read, process and load a score.
PUBLIC int | csoundStart (CSOUND *csound)
| Prepares Csound for performance.
PUBLIC int | csoundCompile (CSOUND *, int argc, const 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.
PUBLIC int | csoundCompileCsd (CSOUND *csound, const char *csd_filename)
| Compiles a Csound input file (CSD, .csd file), but does not perform it.
PUBLIC int | csoundCompileCsdText (CSOUND *csound, const char *csd_text)
| Behaves the same way as csoundCompileCsd, except that the content of the CSD is read from the csd_text string rather than from a file.
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).
PUBLIC int | csoundPerformKsmps (CSOUND *)
| Senses input events, and performs one control sample worth (ksmps) of audio output.
PUBLIC int | csoundPerformBuffer (CSOUND *)
| Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio.
PUBLIC void | csoundStop (CSOUND *)
| Stops a csoundPerform() running in another thread.
PUBLIC int | csoundCleanup (CSOUND *)
| Prints information about the end of a performance, and closes audio and MIDI devices.
PUBLIC void | csoundReset (CSOUND *)
| Resets all internal memory and state in preparation for a new performance.

## Detailed Description

## Function Documentation

## csoundCleanup()

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.

References PUBLIC.

## csoundCompile()

PUBLIC int csoundCompile | ( | CSOUND * | ,
|  | int | argc,
|  | const 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())

References PUBLIC.

## csoundCompileArgs()

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

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

References PUBLIC.

## csoundCompileCsd()

PUBLIC int csoundCompileCsd | ( | CSOUND * | csound,
|  | const char * | csd_filename )

Compiles a Csound input file (CSD, .csd file), but does not perform it.

Returns a non-zero error code on failure.

If csoundStart is called before csoundCompileCsd, the <CsOptions> element is ignored (but csoundSetOption can be called any number of times), the <CsScore> element is not pre-processed, but dispatched as real-time events; and performance continues indefinitely, or until ended by calling csoundStop or some other logic. In this "real-time" mode, the sequence of calls should be:

csoundSetOption("-an_option");
csoundSetOption("-another_option");
csoundStart(csound);
csoundCompileCsd(csound, csd_filename);
while (1) {
csoundPerformBuffer(csound);
// Something to break out of the loop
// when finished here...
}
csoundCleanup(csound);
csoundReset(csound);
csoundSetOption
PUBLIC int csoundSetOption(CSOUND *csound, const char *option)
Set a single csound option (flag).
csoundReset
PUBLIC void csoundReset(CSOUND *)
Resets all internal memory and state in preparation for a new performance.
csoundPerformBuffer
PUBLIC int csoundPerformBuffer(CSOUND *)
Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of ...
csoundCleanup
PUBLIC int csoundCleanup(CSOUND *)
Prints information about the end of a performance, and closes audio and MIDI devices.
csoundCompileCsd
PUBLIC int csoundCompileCsd(CSOUND *csound, const char *csd_filename)
Compiles a Csound input file (CSD, .csd file), but does not perform it.
csoundStart
PUBLIC int csoundStart(CSOUND *csound)
Prepares Csound for performance.

NB: this function can be called repeatedly during performance to replace or add new instruments and events.

But if csoundCompileCsd is called before csoundStart, the <CsOptions> element is used, the <CsScore> section is pre-processed and dispatched normally, and performance terminates when the score terminates, or csoundStop is called. In this "non-real-time" mode (which can still output real-time audio and handle real-time events), the sequence of calls should be:

csoundCompileCsd(csound, csd_filename);
csoundStart(csound);
while (1) {
int finished = csoundPerformBuffer(csound);
if (finished) break;
}
csoundCleanup(csound);
csoundReset(csound);

References PUBLIC.

## csoundCompileCsdText()

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

Behaves the same way as csoundCompileCsd, except that the content of the CSD is read from the csd_text string rather than from a file.

This is convenient when it is desirable to package the csd as part of an application or a multi-language piece.

References PUBLIC.

## csoundCompileOrc()

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

References PUBLIC.

## csoundCompileOrcAsync()

PUBLIC int csoundCompileOrcAsync | ( | CSOUND * | csound,
|  | const char * | str )

Async version of csoundCompileOrc().

The code is parsed and compiled, then placed on a queue for asynchronous merge into the running engine, and evaluation. The function returns following parsing and compilation.

References PUBLIC.

## csoundCompileTree()

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.

References PUBLIC.

## csoundCompileTreeAsync()

PUBLIC int csoundCompileTreeAsync | ( | CSOUND * | csound,
|  | TREE * | root )

Asynchronous version of csoundCompileTree().

References PUBLIC.

## csoundDeleteTree()

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.

References PUBLIC.

## csoundEvalCode()

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

References PUBLIC.

## csoundInitializeCscore()

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.

References PUBLIC.

## csoundParseOrc()

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.

References PUBLIC.

## csoundPerform()

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.

References PUBLIC.

## csoundPerformBuffer()

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.

References PUBLIC.

## csoundPerformKsmps()

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.

References PUBLIC.

## csoundReset()

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.

References PUBLIC.

## csoundStart()

PUBLIC int csoundStart | ( | CSOUND * | csound | ) |

Prepares Csound for performance.

Normally called after compiling a csd file or an orc file, in which case score preprocessing is performed and performance terminates when the score terminates.

However, if called before compiling a csd file or an orc file, score preprocessing is not performed and "i" statements are dispatched as real-time events, the <CsOptions> tag is ignored, and performance continues indefinitely or until ended using the API.

References PUBLIC.

## csoundStop()

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.

References PUBLIC.