Loading...
Searching...
No Matches
Miscellaneous functions

## Functions

PUBLIC long | csoundRunCommand (const char *const *argv, int noWait)
| Runs an external command with the arguments specified in 'argv'.
PUBLIC void | csoundInitTimerStruct (RTCLOCK *)
| Initialise a timer structure.
PUBLIC double | csoundGetRealTime (RTCLOCK *)
| Return the elapsed real time (in seconds) since the specified timer structure was initialised.
PUBLIC double | csoundGetCPUTime (RTCLOCK *)
| Return the elapsed CPU time (in seconds) since the specified timer structure was initialised.
PUBLIC uint32_t | csoundGetRandomSeedFromTime (void)
| Return a 32-bit unsigned integer to be used as seed from current time.
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).
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.
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.
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.
PUBLIC void * | csoundQueryGlobalVariable (CSOUND *, const char *name)
| Get pointer to space allocated with the name "name".
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.
PUBLIC int | csoundDestroyGlobalVariable (CSOUND *, const char *name)
| Free memory allocated for "name" and remove "name" from the database.
PUBLIC int | csoundRunUtility (CSOUND *, const char *name, int argc, char **argv)
| Run utility with the specified name and command line arguments.
PUBLIC char ** | csoundListUtilities (CSOUND *)
| Returns a NULL terminated list of registered utility names.
PUBLIC void | csoundDeleteUtilityList (CSOUND *, char **lst)
| Releases an utility list previously returned by csoundListUtilities().
PUBLIC const char * | csoundGetUtilityDescription (CSOUND *, const char *utilName)
| Get utility description.
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.
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.
PUBLIC uint32_t | csoundRandMT (CsoundRandMTState *p)
| Returns next random number from MT19937 generator.
PUBLIC void * | csoundCreateCircularBuffer (CSOUND *csound, int numelem, int elemsize)
| Create circular buffer with numelem number of elements.
PUBLIC int | csoundReadCircularBuffer (CSOUND *csound, void *circular_buffer, void *out, int items)
| Read from circular buffer.
PUBLIC int | csoundPeekCircularBuffer (CSOUND *csound, void *circular_buffer, void *out, int items)
| Read from circular buffer without removing them from the buffer.
PUBLIC int | csoundWriteCircularBuffer (CSOUND *csound, void *p, const void *inp, int items)
| Write to circular buffer.
PUBLIC void | csoundFlushCircularBuffer (CSOUND *csound, void *p)
| Empty circular buffer of any remaining data.
PUBLIC void | csoundDestroyCircularBuffer (CSOUND *csound, void *circularbuffer)
| Free circular buffer.
PUBLIC int | csoundOpenLibrary (void **library, const char *libraryPath)
| Platform-independent function to load a shared library.
PUBLIC int | csoundCloseLibrary (void *library)
| Platform-independent function to unload a shared library.
PUBLIC void * | csoundGetLibrarySymbol (void *library, const char *symbolName)
| Platform-independent function to get a symbol address in a shared library.

## Detailed Description

## Function Documentation

## csoundCloseLibrary()

PUBLIC int csoundCloseLibrary | ( | void * | library | ) |

Platform-independent function to unload a shared library.

References PUBLIC.

## 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));
csoundCreateCircularBuffer
PUBLIC void * csoundCreateCircularBuffer(CSOUND *csound, int numelem, int elemsize)
Create circular buffer with numelem number of elements.

References PUBLIC.

## 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.

References PUBLIC.

## csoundDeleteUtilityList()

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

Releases an utility list previously returned by csoundListUtilities().

References PUBLIC.

## csoundDestroyCircularBuffer()

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

Free circular buffer.

References PUBLIC.

## 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.

References PUBLIC.

## 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

References PUBLIC.

## csoundGetCPUTime()

PUBLIC double csoundGetCPUTime | ( | RTCLOCK * |  | ) |

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

References PUBLIC.

## 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.

References PUBLIC.

## csoundGetLibrarySymbol()

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

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

References PUBLIC.

## csoundGetRandomSeedFromTime()

PUBLIC uint32_t csoundGetRandomSeedFromTime | ( | void |  | ) |

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

References PUBLIC.

## csoundGetRealTime()

PUBLIC double csoundGetRealTime | ( | RTCLOCK * |  | ) |

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

References PUBLIC.

## 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.

References PUBLIC.

## csoundInitTimerStruct()

PUBLIC void csoundInitTimerStruct | ( | RTCLOCK * |  | ) |

Initialise a timer structure.

References PUBLIC.

## 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.

References PUBLIC.

## csoundOpenLibrary()

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

Platform-independent function to load a shared library.

References PUBLIC.

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

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

## csoundRandMT()

PUBLIC uint32_t csoundRandMT | ( | CsoundRandMTState * | p | ) |

Returns next random number from MT19937 generator.

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

References PUBLIC.

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

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

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

References PUBLIC.