Performance

Functions
PUBLIC TREE *	csoundParseOrc (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 int	csoundCompileTreeAsync (CSOUND *csound, TREE *root)
	Asynchronous version of csoundCompileTree() 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 int	csoundCompileOrcAsync (CSOUND *csound, const char *str)
	Async version of csoundCompileOrc(). 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, const 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. More...
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. More...
PUBLIC int	csoundCompileCsd (CSOUND *csound, const char *csd_filename)
	Compiles a Csound input file (CSD, .csd file), but does not perform it. More...
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. 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

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.

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())

csoundCompileArgs()

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

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

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);

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);

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.

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

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.

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.

csoundCompileTreeAsync()

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

Asynchronous version of csoundCompileTree()

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.

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

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.

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.

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.

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.

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.

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.

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.

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.