Csound API  6.07
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

PUBLIC int csoundCloseLibrary ( void *  library)

Platform-independent function to unload a shared library.

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:

1 void *rb = csoundCreateCircularBuffer(csound, 1024, sizeof(MYFLT));
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.

PUBLIC void csoundDeleteUtilityList ( CSOUND ,
char **  lst 
)

Releases an utility list previously returned by csoundListUtilities().

PUBLIC void csoundDestroyCircularBuffer ( CSOUND csound,
void *  circularbuffer 
)

Free circular buffer.

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.

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
csoundThis value is currently ignored.
ppointer to an existing circular buffer
PUBLIC double csoundGetCPUTime ( RTCLOCK )

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

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.

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

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

PUBLIC uint32_t csoundGetRandomSeedFromTime ( void  )

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

PUBLIC double csoundGetRealTime ( RTCLOCK )

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

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.

PUBLIC void csoundInitTimerStruct ( RTCLOCK )

Initialise a timer structure.

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.

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

Platform-independent function to load a shared library.

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

Read from circular buffer without removing them from the buffer.

Parameters
circular_bufferpointer to an existing circular buffer
outpreallocated buffer with at least items number of elements, where buffer contents will be read into
itemsnumber of samples to be read
Returns
the actual number of items read (0 <= n <= items)
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.

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.

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.

PUBLIC uint32_t csoundRandMT ( CsoundRandMTState p)

Returns next random number from MT19937 generator.

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

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

Read from circular buffer.

Parameters
csoundThis value is currently ignored.
circular_bufferpointer to an existing circular buffer
outpreallocated buffer with at least items number of elements, where buffer contents will be read into
itemsnumber of samples to be read
Returns
the actual number of items read (0 <= n <= items)
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.

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.

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.

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.

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.

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

Write to circular buffer.

Parameters
csoundThis value is currently ignored.
ppointer to an existing circular buffer
inpbuffer with at least items number of elements to be written into circular buffer
itemsnumber of samples to write
Returns
the actual number of items written (0 <= n <= items)