Miscellaneous functions

Functions
PUBLIC long	csoundRunCommand (const char *const *argv, int noWait)
	Runs an external command with the arguments specified in 'argv'. More...
PUBLIC void	csoundInitTimerStruct (RTCLOCK *)
	Initialise a timer structure. More...
PUBLIC double	csoundGetRealTime (RTCLOCK *)
	Return the elapsed real time (in seconds) since the specified timer structure was initialised. More...
PUBLIC double	csoundGetCPUTime (RTCLOCK *)
	Return the elapsed CPU time (in seconds) since the specified timer structure was initialised. More...
PUBLIC uint32_t	csoundGetRandomSeedFromTime (void)
	Return a 32-bit unsigned integer to be used as seed from current time. More...
PUBLIC void	csoundSetLanguage (cslanguage_t lang_code)
	Set language to 'lang_code' (lang_code can be for example CSLANGUAGE_ENGLISH_UK or CSLANGUAGE_FRENCH or many others, see n_getstr.h for the list of languages). More...
PUBLIC const char *	csoundGetEnv (CSOUND *csound, const char *name)
	Get pointer to the value of environment variable 'name', searching in this order: local environment of 'csound' (if not NULL), variables set with csoundSetGlobalEnv(), and system environment variables. More...
PUBLIC int	csoundSetGlobalEnv (const char *name, const char *value)
	Set the global value of environment variable 'name' to 'value', or delete variable if 'value' is NULL. More...
PUBLIC int	csoundCreateGlobalVariable (CSOUND *, const char *name, size_t nbytes)
	Allocate nbytes bytes of memory that can be accessed later by calling csoundQueryGlobalVariable() with the specified name; the space is cleared to zero. More...
PUBLIC void *	csoundQueryGlobalVariable (CSOUND *, const char *name)
	Get pointer to space allocated with the name "name". More...
PUBLIC void *	csoundQueryGlobalVariableNoCheck (CSOUND *, const char *name)
	This function is the same as csoundQueryGlobalVariable(), except the variable is assumed to exist and no error checking is done. More...
PUBLIC int	csoundDestroyGlobalVariable (CSOUND *, const char *name)
	Free memory allocated for "name" and remove "name" from the database. More...
PUBLIC int	csoundRunUtility (CSOUND *, const char *name, int argc, char **argv)
	Run utility with the specified name and command line arguments. More...
PUBLIC char **	csoundListUtilities (CSOUND *)
	Returns a NULL terminated list of registered utility names. More...
PUBLIC void	csoundDeleteUtilityList (CSOUND *, char **lst)
	Releases an utility list previously returned by csoundListUtilities(). More...
PUBLIC const char *	csoundGetUtilityDescription (CSOUND *, const char *utilName)
	Get utility description. More...
PUBLIC int	csoundRand31 (int *seedVal)
	Simple linear congruential random number generator: (*seedVal) = (*seedVal) * 742938285 % 2147483647 the initial value of *seedVal must be in the range 1 to 2147483646. More...
PUBLIC void	csoundSeedRandMT (CsoundRandMTState *p, const uint32_t *initKey, uint32_t keyLength)
	Initialise Mersenne Twister (MT19937) random number generator, using 'keyLength' unsigned 32 bit values from 'initKey' as seed. More...
PUBLIC uint32_t	csoundRandMT (CsoundRandMTState *p)
	Returns next random number from MT19937 generator. More...
PUBLIC void *	csoundCreateCircularBuffer (CSOUND *csound, int numelem, int elemsize)
	Create circular buffer with numelem number of elements. More...
PUBLIC int	csoundReadCircularBuffer (CSOUND *csound, void *circular_buffer, void *out, int items)
	Read from circular buffer. More...
PUBLIC int	csoundPeekCircularBuffer (CSOUND *csound, void *circular_buffer, void *out, int items)
	Read from circular buffer without removing them from the buffer. More...
PUBLIC int	csoundWriteCircularBuffer (CSOUND *csound, void *p, const void *inp, int items)
	Write to circular buffer. More...
PUBLIC void	csoundFlushCircularBuffer (CSOUND *csound, void *p)
	Empty circular buffer of any remaining data. More...
PUBLIC void	csoundDestroyCircularBuffer (CSOUND *csound, void *circularbuffer)
	Free circular buffer. More...
PUBLIC int	csoundOpenLibrary (void **library, const char *libraryPath)
	Platform-independent function to load a shared library. More...
PUBLIC int	csoundCloseLibrary (void *library)
	Platform-independent function to unload a shared library. More...
PUBLIC void *	csoundGetLibrarySymbol (void *library, const char *symbolName)
	Platform-independent function to get a symbol address in a shared library. More...

Detailed Description

Function Documentation

csoundCloseLibrary()

PUBLIC int csoundCloseLibrary

(

void *

library

)

Platform-independent function to unload a shared library.

csoundCreateCircularBuffer()

PUBLIC void* csoundCreateCircularBuffer	(	CSOUND *	csound,
		int	numelem,
		int	elemsize
	)

Create circular buffer with numelem number of elements.

The element's size is set from elemsize. It should be used like:

void *rb = csoundCreateCircularBuffer(csound, 1024, sizeof(MYFLT));

csoundCreateGlobalVariable()

PUBLIC int csoundCreateGlobalVariable	(	CSOUND *	,
		const char *	name,
		size_t	nbytes
	)

Allocate nbytes bytes of memory that can be accessed later by calling csoundQueryGlobalVariable() with the specified name; the space is cleared to zero.

Returns CSOUND_SUCCESS on success, CSOUND_ERROR in case of invalid parameters (zero nbytes, invalid or already used name), or CSOUND_MEMORY if there is not enough memory.

csoundDeleteUtilityList()

PUBLIC void csoundDeleteUtilityList	(	CSOUND *	,
		char **	lst
	)

Releases an utility list previously returned by csoundListUtilities().

csoundDestroyCircularBuffer()

PUBLIC void csoundDestroyCircularBuffer	(	CSOUND *	csound,
		void *	circularbuffer
	)

Free circular buffer.

csoundDestroyGlobalVariable()

PUBLIC int csoundDestroyGlobalVariable	(	CSOUND *	,
		const char *	name
	)

Free memory allocated for "name" and remove "name" from the database.

Return value is CSOUND_SUCCESS on success, or CSOUND_ERROR if the name is not defined.

csoundFlushCircularBuffer()

PUBLIC void csoundFlushCircularBuffer	(	CSOUND *	csound,
		void *	p
	)

Empty circular buffer of any remaining data.

This function should only be used if there is no reader actively getting data from the buffer.

Parameters

csound	This value is currently ignored.
p	pointer to an existing circular buffer

csoundGetCPUTime()

PUBLIC double csoundGetCPUTime

(

RTCLOCK *

)

Return the elapsed CPU time (in seconds) since the specified timer structure was initialised.

csoundGetEnv()

PUBLIC const char* csoundGetEnv	(	CSOUND *	csound,
		const char *	name
	)

Get pointer to the value of environment variable 'name', searching in this order: local environment of 'csound' (if not NULL), variables set with csoundSetGlobalEnv(), and system environment variables.

If 'csound' is not NULL, should be called after csoundCompile(). Return value is NULL if the variable is not set.

csoundGetLibrarySymbol()

PUBLIC void* csoundGetLibrarySymbol	(	void *	library,
		const char *	symbolName
	)

Platform-independent function to get a symbol address in a shared library.

csoundGetRandomSeedFromTime()

PUBLIC uint32_t csoundGetRandomSeedFromTime

(

void

)

Return a 32-bit unsigned integer to be used as seed from current time.

csoundGetRealTime()

PUBLIC double csoundGetRealTime

(

RTCLOCK *

)

Return the elapsed real time (in seconds) since the specified timer structure was initialised.

csoundGetUtilityDescription()

PUBLIC const char* csoundGetUtilityDescription	(	CSOUND *	,
		const char *	utilName
	)

Get utility description.

Returns NULL if the utility was not found, or it has no description, or an error occured.

csoundInitTimerStruct()

PUBLIC void csoundInitTimerStruct

(

RTCLOCK *

)

Initialise a timer structure.

csoundListUtilities()

PUBLIC char** csoundListUtilities

(

CSOUND *

)

Returns a NULL terminated list of registered utility names.

The caller is responsible for freeing the returned array with csoundDeleteUtilityList(), however, the names should not be changed or freed. The return value may be NULL in case of an error.

csoundOpenLibrary()

PUBLIC int csoundOpenLibrary	(	void **	library,
		const char *	libraryPath
	)

Platform-independent function to load a shared library.

csoundPeekCircularBuffer()

PUBLIC int csoundPeekCircularBuffer	(	CSOUND *	csound,
		void *	circular_buffer,
		void *	out,
		int	items
	)

Read from circular buffer without removing them from the buffer.

Parameters

circular_buffer	pointer to an existing circular buffer
out	preallocated buffer with at least items number of elements, where buffer contents will be read into
items	number of samples to be read

Returns

the actual number of items read (0 <= n <= items)

csoundQueryGlobalVariable()

PUBLIC void* csoundQueryGlobalVariable	(	CSOUND *	,
		const char *	name
	)

Get pointer to space allocated with the name "name".

Returns NULL if the specified name is not defined.

csoundQueryGlobalVariableNoCheck()

PUBLIC void* csoundQueryGlobalVariableNoCheck	(	CSOUND *	,
		const char *	name
	)

This function is the same as csoundQueryGlobalVariable(), except the variable is assumed to exist and no error checking is done.

Faster, but may crash or return an invalid pointer if 'name' is not defined.

csoundRand31()

PUBLIC int csoundRand31

(

int *

seedVal

)

Simple linear congruential random number generator: (*seedVal) = (*seedVal) * 742938285 % 2147483647 the initial value of *seedVal must be in the range 1 to 2147483646.

Returns the next number from the pseudo-random sequence, in the range 1 to 2147483646.

csoundRandMT()

PUBLIC uint32_t csoundRandMT

(

CsoundRandMTState *

p

)

Returns next random number from MT19937 generator.

The PRNG must be initialised first by calling csoundSeedRandMT().

csoundReadCircularBuffer()

PUBLIC int csoundReadCircularBuffer	(	CSOUND *	csound,
		void *	circular_buffer,
		void *	out,
		int	items
	)

Read from circular buffer.

Parameters

csound	This value is currently ignored.
circular_buffer	pointer to an existing circular buffer
out	preallocated buffer with at least items number of elements, where buffer contents will be read into
items	number of samples to be read

Returns

the actual number of items read (0 <= n <= items)

csoundRunCommand()

PUBLIC long csoundRunCommand	(	const char *const *	argv,
		int	noWait
	)

Runs an external command with the arguments specified in 'argv'.

argv[0] is the name of the program to execute (if not a full path file name, it is searched in the directories defined by the PATH environment variable). The list of arguments should be terminated by a NULL pointer. If 'noWait' is zero, the function waits until the external program finishes, otherwise it returns immediately. In the first case, a non-negative return value is the exit status of the command (0 to 255), otherwise it is the PID of the newly created process. On error, a negative value is returned.

csoundRunUtility()

PUBLIC int csoundRunUtility	(	CSOUND *	,
		const char *	name,
		int	argc,
		char **	argv
	)

Run utility with the specified name and command line arguments.

Should be called after loading utility plugins. Use csoundReset() to clean up after calling this function. Returns zero if the utility was run successfully.

csoundSeedRandMT()

PUBLIC void csoundSeedRandMT	(	CsoundRandMTState *	p,
		const uint32_t *	initKey,
		uint32_t	keyLength
	)

Initialise Mersenne Twister (MT19937) random number generator, using 'keyLength' unsigned 32 bit values from 'initKey' as seed.

If the array is NULL, the length parameter is used for seeding.

csoundSetGlobalEnv()

PUBLIC int csoundSetGlobalEnv	(	const char *	name,
		const char *	value
	)

Set the global value of environment variable 'name' to 'value', or delete variable if 'value' is NULL.

It is not safe to call this function while any Csound instances are active. Returns zero on success.

csoundSetLanguage()

PUBLIC void csoundSetLanguage

(

cslanguage_t

lang_code

)

Set language to 'lang_code' (lang_code can be for example CSLANGUAGE_ENGLISH_UK or CSLANGUAGE_FRENCH or many others, see n_getstr.h for the list of languages).

This affects all Csound instances running in the address space of the current process. The special language code CSLANGUAGE_DEFAULT can be used to disable translation of messages and free all memory allocated by a previous call to csoundSetLanguage(). csoundSetLanguage() loads all files for the selected language from the directory specified by the CSSTRNGS environment variable.

csoundWriteCircularBuffer()

PUBLIC int csoundWriteCircularBuffer	(	CSOUND *	csound,
		void *	p,
		const void *	inp,
		int	items
	)

Write to circular buffer.

Parameters

csound	This value is currently ignored.
p	pointer to an existing circular buffer
inp	buffer with at least items number of elements to be written into circular buffer
items	number of samples to write

Returns

the actual number of items written (0 <= n <= items)