Csound and CsoundAC API
5.17
|
Declares the public Csound application programming interface (API). More...
#include "sysdep.h"
#include "text.h"
#include <stdarg.h>
#include "cfgvar.h"
#include "msg_attr.h"
#include "version.h"
Data Structures | |
struct | CsoundChannelListEntry_ |
struct | CsoundRandMTState_ |
struct | csRtAudioParams |
Real-time audio parameters structure. More... | |
struct | opcodeListEntry |
struct | pvsdat_ext |
struct | RTCLOCK_S |
struct | TABDAT |
Macros | |
#define | CSOUND_AUDIO_CHANNEL 2 |
#define | CSOUND_CALLBACK_KBD_EVENT (0x00000001U) |
#define | CSOUND_CALLBACK_KBD_TEXT (0x00000002U) |
#define | CSOUND_CHANNEL_TYPE_MASK 15 |
#define | CSOUND_CONTROL_CHANNEL 1 |
Constants used by the bus interface (csoundGetChannelPtr() etc.). | |
#define | CSOUND_CONTROL_CHANNEL_EXP 3 |
#define | CSOUND_CONTROL_CHANNEL_INT 1 |
#define | CSOUND_CONTROL_CHANNEL_LIN 2 |
#define | CSOUND_EXITJMP_SUCCESS (256) |
#define | CSOUND_INPUT_CHANNEL 16 |
#define | CSOUND_OUTPUT_CHANNEL 32 |
#define | CSOUND_SPIN_LOCK |
#define | CSOUND_SPIN_UNLOCK |
#define | CSOUND_STRING_CHANNEL 3 |
#define | CSOUNDINIT_NO_ATEXIT 2 |
#define | CSOUNDINIT_NO_SIGNAL_HANDLER 1 |
Flags for csoundInitialize(). | |
#define | csoundSpinLock(spinlock) |
If the spinlock is not locked, lock it and return; if is is locked, wait until it is unlocked, then lock it and return. | |
#define | csoundSpinUnLock(spinlock) |
#define | PUBLIC |
Typedefs | |
typedef struct CSOUND_ | CSOUND |
typedef void(* | CsoundChannelIOCallback_t )(CSOUND *csound, const char *channelName, MYFLT *channelValuePtr, int channelType) |
typedef struct CsoundChannelListEntry_ | CsoundChannelListEntry |
typedef struct CsoundRandMTState_ | CsoundRandMTState |
typedef struct pvsdat_ext | PVSDATEXT |
typedef struct RTCLOCK_S | RTCLOCK |
typedef struct windat_ | WINDAT |
typedef struct xyindat_ | XYINDAT |
Functions | |
PUBLIC void | csoundAddSpinSample (CSOUND *csound, int frame, int channel, MYFLT sample) |
Adds the indicated sample into the audio input woriing buffer (spin); this only ever makes sense before calling csoundPerformKsmps(). | |
PUBLIC int | csoundAppendOpcode (CSOUND *, const char *opname, int dsblksiz, int thread, const char *outypes, const char *intypes, int(*iopadr)(CSOUND *, void *), int(*kopadr)(CSOUND *, void *), int(*aopadr)(CSOUND *, void *)) |
Appends an opcode implemented by external software to Csound's internal opcode list. | |
PUBLIC int | csoundChanIASet (CSOUND *, const MYFLT *value, int n) |
Sends ksmps MYFLT values to the chani opcode (a-rate) at index 'n'. | |
PUBLIC int | csoundChanIASetSample (CSOUND *, int channel, int frame, MYFLT sample) |
Sets the chani opcode MYFLT a-rate value for the indicated frame of the indicated channel. | |
PUBLIC int | csoundChanIKSet (CSOUND *, MYFLT value, int n) |
Sends a MYFLT value to the chani opcode (k-rate) at index 'n'. | |
PUBLIC int | csoundChanIKSetValue (CSOUND *, int channel, MYFLT value) |
Sets the chani opcode MYFLT k-rate value for the indicated channel. | |
PUBLIC int | csoundChanOAGet (CSOUND *, MYFLT *value, int n) |
Receives ksmps MYFLT values from the chano opcode (a-rate) at index 'n'. | |
PUBLIC MYFLT | csoundChanOAGetSample (CSOUND *, int channel, int frame) |
Sets the chani opcode MYFLT a-rate value for the indicated frame for the indicated channel. | |
PUBLIC int | csoundChanOKGet (CSOUND *, MYFLT *value, int n) |
Receives a MYFLT value from the chano opcode (k-rate) at index 'n'. | |
PUBLIC MYFLT | csoundChanOKGetValue (CSOUND *, int channel) |
Returns the chani opcode MYFLT k-rate value for the indicated channel. | |
PUBLIC int | csoundCleanup (CSOUND *) |
Prints information about the end of a performance, and closes audio and MIDI devices. | |
PUBLIC int | csoundCloseLibrary (void *library) |
Platform-independent function to unload a shared library. | |
PUBLIC int | csoundCompile (CSOUND *, int argc, char **argv) |
Compiles Csound input files (such as an orchestra and score) as directed by the supplied command-line arguments, but does not perform them. | |
PUBLIC CSOUND * | csoundCreate (void *hostData) |
Creates an instance of Csound. | |
PUBLIC void * | csoundCreateBarrier (unsigned int max) |
Create a Thread Barrier. | |
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 * | csoundCreateMutex (int isRecursive) |
Creates and returns a mutex object, or NULL if not successful. | |
PUBLIC void * | csoundCreateThread (uintptr_t(*threadRoutine)(void *), void *userdata) |
Creates and starts a new thread of execution. | |
PUBLIC void * | csoundCreateThreadLock (void) |
Creates and returns a monitor object, or NULL if not successful. | |
PUBLIC void | csoundDeleteChannelList (CSOUND *, CsoundChannelListEntry *lst) |
Releases a channel list previously returned by csoundListChannels(). | |
PUBLIC void | csoundDeleteUtilityList (CSOUND *, char **lst) |
Releases an utility list previously returned by csoundListUtilities(). | |
PUBLIC void | csoundDestroy (CSOUND *) |
Destroys an instance of Csound. | |
PUBLIC int | csoundDestroyBarrier (void *barrier) |
Destroy a Thread Barrier. | |
PUBLIC int | csoundDestroyGlobalVariable (CSOUND *, const char *name) |
Free memory allocated for "name" and remove "name" from the database. | |
void PUBLIC | csoundDestroyMessageBuffer (CSOUND *csound) |
Releases all memory used by the message buffer. | |
PUBLIC void | csoundDestroyMutex (void *mutex_) |
Destroys the indicated mutex object. | |
PUBLIC void | csoundDestroyThreadLock (void *lock) |
Destroys the indicated monitor object. | |
PUBLIC void | csoundDisposeOpcodeList (CSOUND *, opcodeListEntry *opcodelist) |
Releases an opcode list. | |
void PUBLIC | csoundEnableMessageBuffer (CSOUND *csound, int toStdOut) |
Creates a buffer for storing messages printed by Csound. | |
PUBLIC MYFLT | csoundGet0dBFS (CSOUND *) |
Returns the 0dBFS level of the spin/spout buffers. | |
PUBLIC int | csoundGetAPIVersion (void) |
Returns the API version number times 100 (1.00 = 100). | |
PUBLIC int * | csoundGetChannelLock (CSOUND *, const char *name, int type) |
Recovers a pointer to a lock for the specified channel of the bus in *p which must exist. | |
PUBLIC int | csoundGetChannelPtr (CSOUND *, MYFLT **p, const char *name, int type) |
Stores a pointer to the specified channel of the bus in *p, creating the channel first if it does not exist yet. | |
PUBLIC int | csoundGetControlChannelParams (CSOUND *, const char *name, MYFLT *dflt, MYFLT *min, MYFLT *max) |
Returns special parameters (assuming there are any) of a control channel, previously set with csoundSetControlChannelParams(). | |
PUBLIC double | csoundGetCPUTime (RTCLOCK *) |
Return the elapsed CPU time (in seconds) since the specified timer structure was initialised. | |
PUBLIC void * | csoundGetCurrentThreadId (void) |
Returns the ID of the currently executing thread, or NULL for failure. | |
PUBLIC int | csoundGetDebug (CSOUND *) |
Returns whether Csound is in debug mode. | |
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 const char * | csoundGetFirstMessage (CSOUND *csound) |
Returns the first message from the buffer. | |
int PUBLIC | csoundGetFirstMessageAttr (CSOUND *csound) |
Returns the attribute parameter (see msg_attr.h) of the first message in the buffer. | |
PUBLIC void * | csoundGetHostData (CSOUND *) |
Returns host data. | |
PUBLIC MYFLT * | csoundGetInputBuffer (CSOUND *) |
Returns the address of the Csound audio input buffer. | |
PUBLIC long | csoundGetInputBufferSize (CSOUND *) |
Returns the number of samples in Csound's input buffer. | |
PUBLIC MYFLT | csoundGetKr (CSOUND *) |
Returns the number of control samples per second. | |
PUBLIC int | csoundGetKsmps (CSOUND *) |
Returns the number of audio sample frames per control sample. | |
PUBLIC void * | csoundGetLibrarySymbol (void *library, const char *symbolName) |
Platform-independent function to get a symbol address in a shared library. | |
int PUBLIC | csoundGetMessageCnt (CSOUND *csound) |
Returns the number of pending messages in the buffer. | |
PUBLIC int | csoundGetMessageLevel (CSOUND *) |
Returns the Csound message level (from 0 to 231). | |
PUBLIC void * | csoundGetNamedGens (CSOUND *) |
Finds th elist of named gens. | |
PUBLIC int | csoundGetNchnls (CSOUND *) |
Returns the number of audio output channels. | |
PUBLIC MYFLT * | csoundGetOutputBuffer (CSOUND *) |
Returns the address of the Csound audio output buffer. | |
PUBLIC long | csoundGetOutputBufferSize (CSOUND *) |
Returns the number of samples in Csound's output buffer. | |
PUBLIC const char * | csoundGetOutputFileName (CSOUND *) |
Returns the output sound file name (-o). | |
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 void ** | csoundGetRtPlayUserData (CSOUND *) |
Return pointer to user data pointer for real time audio output. | |
PUBLIC void ** | csoundGetRtRecordUserData (CSOUND *) |
Return pointer to user data pointer for real time audio input. | |
PUBLIC int | csoundGetSampleFormat (CSOUND *) |
Returns the sample format. | |
PUBLIC int | csoundGetSampleSize (CSOUND *) |
Returns the size in bytes of a single sample. | |
PUBLIC MYFLT | csoundGetScoreOffsetSeconds (CSOUND *) |
Returns the score time beginning at which score events will actually immediately be performed (see csoundSetScoreOffsetSeconds()). | |
PUBLIC double | csoundGetScoreTime (CSOUND *) |
Returns the current score time in seconds since the beginning of performance. | |
PUBLIC int | csoundGetSizeOfMYFLT (void) |
Return the size of MYFLT in bytes. | |
PUBLIC MYFLT * | csoundGetSpin (CSOUND *) |
Returns the address of the Csound audio input working buffer (spin). | |
PUBLIC MYFLT * | csoundGetSpout (CSOUND *csound) |
Returns the address of the Csound audio output working buffer (spout). | |
PUBLIC MYFLT | csoundGetSpoutSample (CSOUND *csound, int frame, int channel) |
Returns the indicated sample from the Csound audio output working buffer (spout); only ever makes sense after calling csoundPerformKsmps(). | |
PUBLIC MYFLT | csoundGetSr (CSOUND *) |
Returns the number of audio sample frames per second. | |
PUBLIC int | csoundGetStrVarMaxLen (CSOUND *) |
Returns the number of bytes allocated for a string variable (the actual length is one less because of the null character at the end of the string). | |
PUBLIC int | csoundGetTable (CSOUND *, MYFLT **tablePtr, int tableNum) |
Stores pointer to function table 'tableNum' in *tablePtr, and returns the table length (not including the guard point). | |
PUBLIC const char * | csoundGetUtilityDescription (CSOUND *, const char *utilName) |
Get utility description. | |
PUBLIC int | csoundGetVersion (void) |
Returns the version number times 1000 (5.00.0 = 5000). | |
PUBLIC int | csoundInitialize (int *argc, char ***argv, int flags) |
Initialise Csound library; should be called once before creating any Csound instances. | |
PUBLIC int | csoundInitializeCscore (CSOUND *, FILE *insco, FILE *outsco) |
csoundInitializeCscore() prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e. | |
PUBLIC void | csoundInitTimerStruct (RTCLOCK *) |
Initialise a timer structure. | |
PUBLIC void | csoundInputMessage (CSOUND *, const char *message) |
Input a NULL-terminated string (as if from a console), used for line events. | |
PUBLIC int | csoundIsScorePending (CSOUND *) |
Sets whether Csound score events are performed or not, independently of real-time MIDI events (see csoundSetScorePending()). | |
PUBLIC uintptr_t | csoundJoinThread (void *thread) |
Waits until the indicated thread's routine has finished. | |
PUBLIC void | csoundKeyPress (CSOUND *, char c) |
Set the ASCII code of the most recent key pressed. | |
PUBLIC int | csoundListChannels (CSOUND *, CsoundChannelListEntry **lst) |
Returns a list of allocated channels in *lst. | |
PUBLIC char ** | csoundListUtilities (CSOUND *) |
Returns a NULL terminated list of registered utility names. | |
PUBLIC char * | csoundLocalizeString (const char *s) |
Translate string 's' to the current language, and return pointer to the translated message. | |
PUBLIC void | csoundLockMutex (void *mutex_) |
Acquires the indicated mutex object; if it is already in use by another thread, the function waits until the mutex is released by the other thread. | |
PUBLIC int | csoundLockMutexNoWait (void *mutex_) |
Acquires the indicated mutex object and returns zero, unless it is already in use by another thread, in which case a non-zero value is returned immediately, rather than waiting until the mutex becomes available. | |
PUBLIC CS_PRINTF2 void | csoundMessage (CSOUND *, const char *format,...) |
Displays an informational message. | |
PUBLIC CS_PRINTF3 void | csoundMessageS (CSOUND *, int attr, const char *format,...) |
Print message with special attributes (see msg_attr.h for the list of available attributes). | |
PUBLIC void | csoundMessageV (CSOUND *, int attr, const char *format, va_list args) |
PUBLIC int | csoundNewOpcodeList (CSOUND *, opcodeListEntry **opcodelist) |
Gets an alphabetically sorted list of all opcodes. | |
PUBLIC void | csoundNotifyThreadLock (void *lock) |
Notifies the indicated monitor object. | |
PUBLIC int | csoundOpenLibrary (void **library, const char *libraryPath) |
Platform-independent function to load a shared library. | |
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 | csoundPerformBuffer (CSOUND *) |
Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio. | |
PUBLIC int | csoundPerformKsmps (CSOUND *) |
Senses input events, and performs one control sample worth (ksmps) of audio output. | |
PUBLIC int | csoundPerformKsmpsAbsolute (CSOUND *) |
Senses input events, and performs one control sample worth (ksmps) of audio output. | |
void PUBLIC | csoundPopFirstMessage (CSOUND *csound) |
Removes the first message from the buffer. | |
PUBLIC int | csoundPreCompile (CSOUND *) |
Reset and prepare an instance of Csound for compilation. | |
PUBLIC int | csoundPvsinSet (CSOUND *, const PVSDATEXT *fin, int n) |
Sends a PVSDATEX fin to the pvsin opcode (f-rate) at index 'n'. | |
PUBLIC int | csoundPvsoutGet (CSOUND *csound, PVSDATEXT *fout, int n) |
Receives a PVSDAT fout from the pvsout opcode (f-rate) at index 'n'. | |
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 | csoundQueryInterface (const char *name, void **iface, int *version) |
Returns a pointer to the requested interface, if available, in the interface argument, and its version number, in the version argument. | |
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 uint32_t | csoundRandMT (CsoundRandMTState *p) |
Returns next random number from MT19937 generator. | |
PUBLIC int | csoundRegisterSenseEventCallback (CSOUND *, void(*func)(CSOUND *, void *), void *userData) |
Register a function to be called once in every control period by sensevents(). | |
PUBLIC void | csoundRemoveCallback (CSOUND *, int(*func)(void *, void *, unsigned int)) |
Removes a callback previously set with csoundSetCallback(). | |
PUBLIC void | csoundReset (CSOUND *) |
Resets all internal memory and state in preparation for a new performance. | |
PUBLIC void | csoundRewindScore (CSOUND *) |
Rewinds a compiled Csound score to the time specified with csoundSetScoreOffsetSeconds(). | |
PUBLIC long | csoundRunCommand (const char *const *argv, int noWait) |
Runs an external command with the arguments specified in 'argv'. | |
PUBLIC int | csoundRunUtility (CSOUND *, const char *name, int argc, char **argv) |
Run utility with the specified name and command line arguments. | |
PUBLIC int | csoundScoreEvent (CSOUND *, char type, const MYFLT *pFields, long numFields) |
Send a new score event. | |
PUBLIC int | csoundScoreEventAbsolute (CSOUND *, char type, const MYFLT *pfields, long numFields, double time_ofs) |
PUBLIC int | csoundScoreExtract (CSOUND *, FILE *inFile, FILE *outFile, FILE *extractFile) |
Extracts from 'inFile', controlled by 'extractFile', and writes the result to 'outFile'. | |
PUBLIC int | csoundScoreSort (CSOUND *, FILE *inFile, FILE *outFile) |
Sorts score file 'inFile' and writes the result to 'outFile'. | |
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 int | csoundSetCallback (CSOUND *, int(*func)(void *userData, void *p, unsigned int type), void *userData, unsigned int typeMask) |
Sets general purpose callback function that will be called on various events. | |
PUBLIC void | csoundSetChannelIOCallback (CSOUND *, CsoundChannelIOCallback_t func) |
Sets callback function to be called by the opcodes 'chnsend' and 'chnrecv'. | |
PUBLIC int | csoundSetControlChannelParams (CSOUND *, const char *name, int type, MYFLT dflt, MYFLT min, MYFLT max) |
Sets special parameters for a control channel. | |
PUBLIC void | csoundSetCscoreCallback (CSOUND *, void(*cscoreCallback_)(CSOUND *)) |
Sets an external callback for Cscore processing. | |
PUBLIC void | csoundSetDebug (CSOUND *, int debug) |
Sets whether Csound is in debug mode. | |
PUBLIC void | csoundSetDrawGraphCallback (CSOUND *, void(*drawGraphCallback_)(CSOUND *, WINDAT *windat)) |
Called by external software to set Csound's DrawGraph function. | |
PUBLIC void | csoundSetExitGraphCallback (CSOUND *, int(*exitGraphCallback_)(CSOUND *)) |
Called by external software to set Csound's ExitGraph function. | |
PUBLIC void | csoundSetExternalMidiErrorStringCallback (CSOUND *, const char *(*func)(int)) |
Sets callback for converting MIDI error codes to strings. | |
PUBLIC void | csoundSetExternalMidiInCloseCallback (CSOUND *, int(*func)(CSOUND *, void *userData)) |
Sets callback for closing real time MIDI input. | |
PUBLIC void | csoundSetExternalMidiInOpenCallback (CSOUND *, int(*func)(CSOUND *, void **userData, const char *devName)) |
Sets callback for opening real time MIDI input. | |
PUBLIC void | csoundSetExternalMidiOutCloseCallback (CSOUND *, int(*func)(CSOUND *, void *userData)) |
Sets callback for closing real time MIDI output. | |
PUBLIC void | csoundSetExternalMidiOutOpenCallback (CSOUND *, int(*func)(CSOUND *, void **userData, const char *devName)) |
Sets callback for opening real time MIDI output. | |
PUBLIC void | csoundSetExternalMidiReadCallback (CSOUND *, int(*func)(CSOUND *, void *userData, unsigned char *buf, int nBytes)) |
Sets callback for reading from real time MIDI input. | |
PUBLIC void | csoundSetExternalMidiWriteCallback (CSOUND *, int(*func)(CSOUND *, void *userData, const unsigned char *buf, int nBytes)) |
Sets callback for writing to real time MIDI output. | |
PUBLIC void | csoundSetFileOpenCallback (CSOUND *p, void(*func)(CSOUND *, const char *, int, int, int)) |
Sets an external callback for receiving notices whenever Csound opens a file. | |
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 void | csoundSetHostData (CSOUND *, void *hostData) |
Sets host data. | |
PUBLIC void | csoundSetHostImplementedAudioIO (CSOUND *, int state, int bufSize) |
Calling this function with a non-zero 'state' value between csoundPreCompile() and csoundCompile() will disable all default handling of sound I/O by the Csound library, allowing the host application to use the spin/spout/input/output buffers directly. | |
PUBLIC void | csoundSetInputValueCallback (CSOUND *, void(*inputValueCalback_)(CSOUND *, const char *channelName, MYFLT *value)) |
Control values are specified by a 'channelName' string. | |
PUBLIC int | csoundSetIsGraphable (CSOUND *, int isGraphable) |
Tells Csound whether external graphic table display is supported. | |
PUBLIC void | csoundSetKillGraphCallback (CSOUND *, void(*killGraphCallback_)(CSOUND *, WINDAT *windat)) |
Called by external software to set Csound's KillGraph function. | |
PUBLIC void | csoundSetKillXYinCallback (CSOUND *, void(*killXYinCallback_)(CSOUND *, XYINDAT *)) |
Called by external software to set Csound's KillXYin function. | |
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 void | csoundSetMakeGraphCallback (CSOUND *, void(*makeGraphCallback_)(CSOUND *, WINDAT *windat, const char *name)) |
Called by external software to set Csound's MakeGraph function. | |
PUBLIC void | csoundSetMakeXYinCallback (CSOUND *, void(*makeXYinCallback_)(CSOUND *, XYINDAT *, MYFLT x, MYFLT y)) |
Called by external software to set Csound's MakeXYin function. | |
PUBLIC void | csoundSetMessageCallback (CSOUND *, void(*csoundMessageCallback_)(CSOUND *, int attr, const char *format, va_list valist)) |
Sets a function to be called by Csound to print an informational message. | |
PUBLIC void | csoundSetMessageLevel (CSOUND *, int messageLevel) |
Sets the Csound message level (from 0 to 231). | |
PUBLIC void | csoundSetOutputValueCallback (CSOUND *, void(*outputValueCalback_)(CSOUND *, const char *channelName, MYFLT value)) |
Called by external software to set a function for Csound to send output control values. | |
PUBLIC void | csoundSetPlayopenCallback (CSOUND *, int(*playopen__)(CSOUND *, const csRtAudioParams *parm)) |
Sets a function to be called by Csound for opening real-time audio playback. | |
PUBLIC void | csoundSetReadXYinCallback (CSOUND *, void(*readXYinCallback_)(CSOUND *, XYINDAT *)) |
Called by external software to set Csound's ReadXYin function. | |
PUBLIC void | csoundSetRecopenCallback (CSOUND *, int(*recopen_)(CSOUND *, const csRtAudioParams *parm)) |
Sets a function to be called by Csound for opening real-time audio recording. | |
PUBLIC void | csoundSetRtcloseCallback (CSOUND *, void(*rtclose__)(CSOUND *)) |
Sets a function to be called by Csound for closing real-time audio playback and recording. | |
PUBLIC void | csoundSetRtplayCallback (CSOUND *, void(*rtplay__)(CSOUND *, const MYFLT *outBuf, int nbytes)) |
Sets a function to be called by Csound for performing real-time audio playback. | |
PUBLIC void | csoundSetRtrecordCallback (CSOUND *, int(*rtrecord__)(CSOUND *, MYFLT *inBuf, int nbytes)) |
Sets a function to be called by Csound for performing real-time audio recording. | |
PUBLIC void | csoundSetScoreOffsetSeconds (CSOUND *, MYFLT time) |
Csound score events prior to the specified time are not performed, and performance begins immediately at the specified time (real-time events will continue to be performed as they are received). | |
PUBLIC void | csoundSetScorePending (CSOUND *, int pending) |
Sets whether Csound score events are performed or not (real-time events will continue to be performed). | |
PUBLIC void | csoundSetYieldCallback (CSOUND *, int(*yieldCallback_)(CSOUND *)) |
Called by external software to set a function for checking system events, yielding cpu time for coopertative multitasking, etc. | |
PUBLIC void | csoundSleep (size_t milliseconds) |
Waits for at least the specified number of milliseconds, yielding the CPU to other threads. | |
PUBLIC void | csoundStop (CSOUND *) |
Stops a csoundPerform() running in another thread. | |
PUBLIC MYFLT | csoundTableGet (CSOUND *, int table, int index) |
Returns the value of a slot in a function table. | |
PUBLIC int | csoundTableLength (CSOUND *, int table) |
Returns the length of a function table (not including the guard point), or -1 if the table does not exist. | |
PUBLIC void | csoundTableSet (CSOUND *, int table, int index, MYFLT value) |
Sets the value of a slot in a function table. | |
PUBLIC void | csoundUnlockMutex (void *mutex_) |
Releases the indicated mutex object, which should be owned by the current thread, otherwise the operation of this function is undefined. | |
PUBLIC int | csoundWaitBarrier (void *barrier) |
Wait on the thread barrier. | |
PUBLIC int | csoundWaitThreadLock (void *lock, size_t milliseconds) |
Waits on the indicated monitor object for the indicated period. | |
PUBLIC void | csoundWaitThreadLockNoTimeout (void *lock) |
Waits on the indicated monitor object until it is notified. | |
void PUBLIC | sigcpy (MYFLT *dest, MYFLT *src, int size) |
Declares the public Csound application programming interface (API).
Purposes
The purposes of the Csound API are as follows:
Users
Users of the Csound API fall into two main categories: hosts, and plugins.
Hosts using the Csound API must #include <csound.h>, and link with the Csound API library. Plugin libraries should #include <csdl.h> to get access to the API function pointers in the CSOUND structure, and do not need to link with the Csound API library. Only one of csound.h and csdl.h may be included by a compilation unit.
Hosts must first create an instance of Csound using the csoundCreate
API function. When hosts are finished using Csound, they must destroy the instance of csound using the csoundDestroy
API function. Most of the other Csound API functions take the Csound instance as their first argument. Hosts can only call the standalone API functions declared in csound.h.
Here is the complete code for the simplest possible Csound API host, a command-line Csound application:
All opcodes, including plugins, receive a pointer to their host instance of Csound as the first argument. Therefore, plugins MUST NOT compile, perform, or destroy the host instance of Csound, and MUST call the Csound API function pointers off the Csound instance pointer.
In general, plugins should ONLY access Csound functionality through the API function pointers and public members of the CSOUND structure.
#define CSOUND_AUDIO_CHANNEL 2 |
#define CSOUND_CALLBACK_KBD_EVENT (0x00000001U) |
#define CSOUND_CALLBACK_KBD_TEXT (0x00000002U) |
#define CSOUND_CHANNEL_TYPE_MASK 15 |
#define CSOUND_CONTROL_CHANNEL 1 |
Constants used by the bus interface (csoundGetChannelPtr() etc.).
#define CSOUND_CONTROL_CHANNEL_EXP 3 |
#define CSOUND_CONTROL_CHANNEL_INT 1 |
#define CSOUND_CONTROL_CHANNEL_LIN 2 |
#define CSOUND_EXITJMP_SUCCESS (256) |
#define CSOUND_INPUT_CHANNEL 16 |
#define CSOUND_OUTPUT_CHANNEL 32 |
#define CSOUND_SPIN_LOCK |
#define CSOUND_SPIN_UNLOCK |
#define CSOUND_STRING_CHANNEL 3 |
#define CSOUNDINIT_NO_ATEXIT 2 |
#define CSOUNDINIT_NO_SIGNAL_HANDLER 1 |
Flags for csoundInitialize().
#define csoundSpinLock | ( | spinlock | ) |
If the spinlock is not locked, lock it and return; if is is locked, wait until it is unlocked, then lock it and return.
Uses atomic compare and swap operations that are safe across processors and safe for out of order operations, and which are more efficient than operating system locks. Use spinlocks to protect access to shared data, especially in functions that do little more than read or write such data, for example:
void write(size_t frames, int* signal) { static int lock = 0; csoundSpinLock(&lock); for (size_t frame = 0; i < frames; frame++) { global_buffer[frame] += signal[frame]; } csoundSpinUnlock(&lock); }
#define csoundSpinUnLock | ( | spinlock | ) |
#define PUBLIC |
typedef void(* CsoundChannelIOCallback_t)(CSOUND *csound, const char *channelName, MYFLT *channelValuePtr, int channelType) |
typedef struct CsoundChannelListEntry_ CsoundChannelListEntry |
typedef struct CsoundRandMTState_ CsoundRandMTState |
typedef struct pvsdat_ext PVSDATEXT |
enum CSOUND_FILETYPES |
The following constants are used with csound->FileOpen2() and csound->ldmemfile2() to specify the format of a file that is being opened.
This information is passed by Csound to a host's FileOpen callback and does not influence the opening operation in any other way. Conversion from Csound's TYP_XXX macros for audio formats to CSOUND_FILETYPES values can be done with csound->type2csfiletype().
enum CSOUND_STATUS |
Adds the indicated sample into the audio input woriing buffer (spin); this only ever makes sense before calling csoundPerformKsmps().
The frame and channel must be in bounds relative to ksmps and nchnls.
PUBLIC int csoundAppendOpcode | ( | CSOUND * | , |
const char * | opname, | ||
int | dsblksiz, | ||
int | thread, | ||
const char * | outypes, | ||
const char * | intypes, | ||
int(*)(CSOUND *, void *) | iopadr, | ||
int(*)(CSOUND *, void *) | kopadr, | ||
int(*)(CSOUND *, void *) | aopadr | ||
) |
Appends an opcode implemented by external software to Csound's internal opcode list.
The opcode list is extended by one slot, and the parameters are copied into the new slot. Returns zero on success.
Sends ksmps MYFLT values to the chani opcode (a-rate) at index 'n'.
The bus is automatically extended if 'n' exceeds any previously used index value, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to extend the bus.
Sets the chani opcode MYFLT a-rate value for the indicated frame of the indicated channel.
Sends a PVSDATEX fin to the pvsin opcode (f-rate) at index 'n'.
The bus is automatically extended if the channel is greater than previously used, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to estend the bus.
The bus is automatically extended if 'n' exceeds any previously used index value, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid or fsig framesizes are incompatible CSOUND_MEMORY if there is not enough memory to extend the bus.
Sends a MYFLT value to the chani opcode (k-rate) at index 'n'.
The bus is automatically extended if 'n' exceeds any previously used index value, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to extend the bus.
Sets the chani opcode MYFLT k-rate value for the indicated channel.
The bus is automatically extended if the channel is greater than previously used, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to estend the bus.
Receives ksmps MYFLT values from the chano opcode (a-rate) at index 'n'.
The bus is automatically extended if 'n' exceeds any previously used index value, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to extend the bus.
Sets the chani opcode MYFLT a-rate value for the indicated frame for the indicated channel.
The bus is automatically extended if the channel is greater than previously used, clearing new locations to zero. Returns the sample value on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to estend the bus.
Receives a MYFLT value from the chano opcode (k-rate) at index 'n'.
The bus is automatically extended if 'n' exceeds any previously used index value, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to extend the bus.
Returns the chani opcode MYFLT k-rate value for the indicated channel.
The bus is automatically extended if the channel is greater than previously used, clearing new locations to zero. Returns the sample value on success, CSOUND_ERROR if the index is invalid, and CSOUND_MEMORY if there is not enough memory to estend the bus
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.
PUBLIC int csoundCloseLibrary | ( | void * | library | ) |
Platform-independent function to unload a shared library.
Compiles Csound input files (such as an orchestra and score) as directed by the supplied command-line arguments, but does not perform them.
Returns a non-zero error code on failure. 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
Creates an instance of Csound.
Returns an opaque pointer that must be passed to most Csound API functions. The hostData parameter can be NULL, or it can be a pointer to any sort of data; this pointer can be accessed from the Csound instance that is passed to callback routines.
PUBLIC void* csoundCreateBarrier | ( | unsigned int | max | ) |
Create a Thread Barrier.
Max value parameter should be equal to number of child threads using the barrier plus one for the master thread
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* csoundCreateMutex | ( | int | isRecursive | ) |
Creates and returns a mutex object, or NULL if not successful.
Mutexes can be faster than the more general purpose monitor objects returned by csoundCreateThreadLock() on some platforms, and can also be recursive, but the result of unlocking a mutex that is owned by another thread or is not locked is undefined. If 'isRecursive' is non-zero, the mutex can be re-locked multiple times by the same thread, requiring an equal number of unlock calls; otherwise, attempting to re-lock the mutex results in undefined behavior. Note: the handles returned by csoundCreateThreadLock() and csoundCreateMutex() are not compatible.
Creates and starts a new thread of execution.
Returns an opaque pointer that represents the thread on success, or NULL for failure. The userdata pointer is passed to the thread routine.
PUBLIC void* csoundCreateThreadLock | ( | void | ) |
Creates and returns a monitor object, or NULL if not successful.
The object is initially in signaled (notified) state.
PUBLIC void csoundDeleteChannelList | ( | CSOUND * | , |
CsoundChannelListEntry * | lst | ||
) |
Releases a channel list previously returned by csoundListChannels().
Releases an utility list previously returned by csoundListUtilities().
PUBLIC int csoundDestroyBarrier | ( | void * | barrier | ) |
Destroy a Thread Barrier.
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.
Releases all memory used by the message buffer.
PUBLIC void csoundDestroyMutex | ( | void * | mutex_ | ) |
Destroys the indicated mutex object.
Destroying a mutex that is currently owned by a thread results in undefined behavior.
PUBLIC void csoundDestroyThreadLock | ( | void * | lock | ) |
Destroys the indicated monitor object.
PUBLIC void csoundDisposeOpcodeList | ( | CSOUND * | , |
opcodeListEntry * | opcodelist | ||
) |
Releases an opcode list.
Creates a buffer for storing messages printed by Csound.
Should be called after creating a Csound instance; note that the message buffer uses the host data pointer, and the buffer should be freed by calling csoundDestroyMessageBuffer() before deleting the Csound instance. If 'toStdOut' is non-zero, the messages are also printed to stdout and stderr (depending on the type of the message), in addition to being stored in the buffer.
PUBLIC int csoundGetAPIVersion | ( | void | ) |
Returns the API version number times 100 (1.00 = 100).
Recovers a pointer to a lock for the specified channel of the bus in *p which must exist.
'type' must be the bitwise OR of exactly one of the following values, CSOUND_CONTROL_CHANNEL control data (one MYFLT value) CSOUND_AUDIO_CHANNEL audio data (csoundGetKsmps(csound) MYFLT values) CSOUND_STRING_CHANNEL string data (MYFLT values with enough space to store csoundGetStrVarMaxLen(csound) characters, including the NULL character at the end of the string) and at least one of these: CSOUND_INPUT_CHANNEL CSOUND_OUTPUT_CHANNEL Return value is the address of the lock
Stores a pointer to the specified channel of the bus in *p, creating the channel first if it does not exist yet.
'type' must be the bitwise OR of exactly one of the following values, CSOUND_CONTROL_CHANNEL control data (one MYFLT value) CSOUND_AUDIO_CHANNEL audio data (csoundGetKsmps(csound) MYFLT values) CSOUND_STRING_CHANNEL string data (MYFLT values with enough space to store csoundGetStrVarMaxLen(csound) characters, including the NULL character at the end of the string) and at least one of these: CSOUND_INPUT_CHANNEL CSOUND_OUTPUT_CHANNEL If the channel already exists, it must match the data type (control, audio, or string), however, the input/output bits are OR'd with the new value. Note that audio and string channels can only be created after calling csoundCompile(), because the storage size is not known until then. Return value is zero on success, or a negative error code, CSOUND_MEMORY there is not enough memory for allocating the channel CSOUND_ERROR the specified name or type is invalid or, if a channel with the same name but incompatible type already exists, the type of the existing channel. In the case of any non-zero return value, *p is set to NULL. Note: to find out the type of a channel without actually creating or changing it, set 'type' to zero, so that the return value will be either the type of the channel, or CSOUND_ERROR if it does not exist.
PUBLIC int csoundGetControlChannelParams | ( | CSOUND * | , |
const char * | name, | ||
MYFLT * | dflt, | ||
MYFLT * | min, | ||
MYFLT * | max | ||
) |
Returns special parameters (assuming there are any) of a control channel, previously set with csoundSetControlChannelParams().
If the channel exists, is a control channel, and has the special parameters assigned, then the default, minimum, and maximum value is stored in *dflt, *min, and *max, respectively, and a positive value that is one of CSOUND_CONTROL_CHANNEL_INT, CSOUND_CONTROL_CHANNEL_LIN, and CSOUND_CONTROL_CHANNEL_EXP is returned. In any other case, *dflt, *min, and *max are not changed, and the return value is zero if the channel exists, is a control channel, but has no special parameters set; otherwise, a negative error code is returned.
Return the elapsed CPU time (in seconds) since the specified timer structure was initialised.
PUBLIC void* csoundGetCurrentThreadId | ( | void | ) |
Returns the ID of the currently executing thread, or NULL for failure.
NOTE: The return value can be used as a pointer to a thread object, but it should not be compared as a pointer. The pointed to values should be compared, and the user must free the pointer after use.
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 csoundPreCompile() or csoundCompile(). Return value is NULL if the variable is not set.
Returns the first message from the buffer.
Returns the attribute parameter (see msg_attr.h) of the first message in the buffer.
Returns the address of the Csound audio input buffer.
Enables external software to write audio into Csound before calling csoundPerformBuffer.
Returns the number of samples in Csound's input buffer.
Returns the number of audio sample frames per control sample.
PUBLIC void* csoundGetLibrarySymbol | ( | void * | library, |
const char * | symbolName | ||
) |
Platform-independent function to get a symbol address in a shared library.
Returns the number of pending messages in the buffer.
Returns the address of the Csound audio output buffer.
Enables external software to read audio from Csound after calling csoundPerformBuffer.
Returns the number of samples in Csound's output buffer.
Return a 32-bit unsigned integer to be used as seed from current time.
Return the elapsed real time (in seconds) since the specified timer structure was initialised.
Return pointer to user data pointer for real time audio output.
Return pointer to user data pointer for real time audio input.
Returns the score time beginning at which score events will actually immediately be performed (see csoundSetScoreOffsetSeconds()).
Returns the current score time in seconds since the beginning of performance.
PUBLIC int csoundGetSizeOfMYFLT | ( | void | ) |
Return the size of MYFLT in bytes.
Returns the address of the Csound audio input working buffer (spin).
Enables external software to write audio into Csound before calling csoundPerformKsmps.
Returns the address of the Csound audio output working buffer (spout).
Enables external software to read audio from Csound after calling csoundPerformKsmps.
Returns the indicated sample from the Csound audio output working buffer (spout); only ever makes sense after calling csoundPerformKsmps().
The frame and channel must be in bounds relative to ksmps and nchnls.
Returns the number of bytes allocated for a string variable (the actual length is one less because of the null character at the end of the string).
Should be called after csoundCompile().
Stores pointer to function table 'tableNum' in *tablePtr, and returns the table length (not including the guard point).
If the table does not exist, *tablePtr is set to NULL and -1 is returned.
Get utility description.
Returns NULL if the utility was not found, or it has no description, or an error occured.
PUBLIC int csoundGetVersion | ( | void | ) |
Returns the version number times 1000 (5.00.0 = 5000).
PUBLIC int csoundInitialize | ( | int * | argc, |
char *** | argv, | ||
int | flags | ||
) |
Initialise Csound library; should be called once before creating any Csound instances.
Return value is zero on success, positive if initialisation was done already, and negative on error.
csoundInitializeCscore() prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e.
"standalone Cscore"). It is an alternative to csoundPreCompile(), 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.
Input a NULL-terminated string (as if from a console), used for line events.
Sets whether Csound score events are performed or not, independently of real-time MIDI events (see csoundSetScorePending()).
Waits until the indicated thread's routine has finished.
Returns the value returned by the thread routine.
Set the ASCII code of the most recent key pressed.
This value is used by the 'sensekey' opcode if a callback for returning keyboard events is not set (see csoundSetCallback()).
PUBLIC int csoundListChannels | ( | CSOUND * | , |
CsoundChannelListEntry ** | lst | ||
) |
Returns a list of allocated channels in *lst.
A CsoundChannelListEntry structure contains the name and type of a channel, with the type having the same format as in the case of csoundGetChannelPtr(). The return value is the number of channels, which may be zero if there are none, or CSOUND_MEMORY if there is not enough memory for allocating the list. In the case of no channels or an error, *lst is set to NULL. Notes: the caller is responsible for freeing the list returned in *lst with csoundDeleteChannelList(). The name pointers may become invalid after calling csoundReset().
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 char* csoundLocalizeString | ( | const char * | s | ) |
Translate string 's' to the current language, and return pointer to the translated message.
This may be the same as 's' if language was set to CSLANGUAGE_DEFAULT.
PUBLIC void csoundLockMutex | ( | void * | mutex_ | ) |
Acquires the indicated mutex object; if it is already in use by another thread, the function waits until the mutex is released by the other thread.
PUBLIC int csoundLockMutexNoWait | ( | void * | mutex_ | ) |
Acquires the indicated mutex object and returns zero, unless it is already in use by another thread, in which case a non-zero value is returned immediately, rather than waiting until the mutex becomes available.
Note: this function may be unimplemented on Windows.
PUBLIC CS_PRINTF2 void csoundMessage | ( | CSOUND * | , |
const char * | format, | ||
... | |||
) |
Displays an informational message.
PUBLIC CS_PRINTF3 void csoundMessageS | ( | CSOUND * | , |
int | attr, | ||
const char * | format, | ||
... | |||
) |
Print message with special attributes (see msg_attr.h for the list of available attributes).
With attr=0, csoundMessageS() is identical to csoundMessage().
PUBLIC int csoundNewOpcodeList | ( | CSOUND * | , |
opcodeListEntry ** | opcodelist | ||
) |
Gets an alphabetically sorted list of all opcodes.
Should be called after externals are loaded by csoundCompile(). Returns the number of opcodes, or a negative error code on failure. Make sure to call csoundDisposeOpcodeList() when done with the list.
PUBLIC void csoundNotifyThreadLock | ( | void * | lock | ) |
Notifies the indicated monitor object.
PUBLIC int csoundOpenLibrary | ( | void ** | library, |
const char * | libraryPath | ||
) |
Platform-independent function to load a shared library.
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 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.
Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio.
Returns a pointer to the new output audio in 'outputAudio' 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.
Senses input events, and performs one control sample worth (ksmps) of audio output.
Note that csoundCompile 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.
Senses input events, and performs one control sample worth (ksmps) of audio output.
Note that csoundCompile must be called first. Performs audio whether or not the Csound score has finished. Enables external software to control the execution of Csound, and to synchronize performance with audio input and output.
Reset and prepare an instance of Csound for compilation.
Returns CSOUND_SUCCESS on success, and CSOUND_ERROR or CSOUND_MEMORY if an error occured.
Sends a PVSDATEX fin to the pvsin opcode (f-rate) at index 'n'.
The bus is automatically extended if 'n' exceeds any previously used index value, clearing new locations to zero. Returns zero on success, CSOUND_ERROR if the index is invalid or fsig framesizes are incompatible CSOUND_MEMORY if there is not enough memory to extend the bus.
Receives a PVSDAT fout from the pvsout opcode (f-rate) at index 'n'.
The bus is extended if 'n' exceeds any previous value. Returns zero on success, CSOUND_ERROR if the index is invalid or if fsig framesizes are incompatible CSOUND_MEMORY if there is not enough memory to extend the bus
Get pointer to space allocated with the name "name".
Returns NULL if the specified name is not defined.
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 csoundQueryInterface | ( | const char * | name, |
void ** | iface, | ||
int * | version | ||
) |
Returns a pointer to the requested interface, if available, in the interface argument, and its version number, in the version argument.
Returns 0 for success.
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 csoundRegisterSenseEventCallback | ( | CSOUND * | , |
void(*)(CSOUND *, void *) | func, | ||
void * | userData | ||
) |
Register a function to be called once in every control period by sensevents().
Any number of functions may be registered, and will be called in the order of registration. The callback function takes two arguments: the Csound instance pointer, and the userData pointer as passed to this function. Returns zero on success.
Removes a callback previously set with csoundSetCallback().
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.
Rewinds a compiled Csound score to the time specified with csoundSetScoreOffsetSeconds().
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.
Run utility with the specified name and command line arguments.
Should be called after loading utility plugins with csoundPreCompile(); use csoundReset() to clean up after calling this function. Returns zero if the utility was run successfully.
Send a new score event.
'type' is the score event type ('a', 'i', 'q', 'f', or 'e'). 'numFields' is the size of the pFields array. 'pFields' is an array of floats with all the pfields for this event, starting with the p1 value specified in pFields[0].
PUBLIC int csoundScoreEventAbsolute | ( | CSOUND * | , |
char | type, | ||
const MYFLT * | pfields, | ||
long | numFields, | ||
double | time_ofs | ||
) |
Extracts from 'inFile', controlled by 'extractFile', and writes the result to 'outFile'.
The Csound instance should be initialised with csoundPreCompile() before calling this function, and csoundReset() should be called after score extraction to clean up. The return value is zero on success.
Sorts score file 'inFile' and writes the result to 'outFile'.
The Csound instance should be initialised with csoundPreCompile() before calling this function, and csoundReset() should be called after sorting the score to clean up. On success, zero is returned.
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 csoundSetCallback | ( | CSOUND * | , |
int(*)(void *userData, void *p, unsigned int type) | func, | ||
void * | userData, | ||
unsigned int | typeMask | ||
) |
Sets general purpose callback function that will be called on various events.
The callback is preserved on csoundReset(), and multiple callbacks may be set and will be called in reverse order of registration. If the same function is set again, it is only moved in the list of callbacks so that it will be called first, and the user data and type mask parameters are updated. 'typeMask' can be the bitwise OR of callback types for which the function should be called, or zero for all types. Returns zero on success, CSOUND_ERROR if the specified function pointer or type mask is invalid, and CSOUND_MEMORY if there is not enough memory.
The callback function takes the following arguments: void *userData the "user data" pointer, as specified when setting the callback void *p data pointer, depending on the callback type unsigned int type callback type, can be one of the following (more may be added in future versions of Csound): CSOUND_CALLBACK_KBD_EVENT CSOUND_CALLBACK_KBD_TEXT called by the sensekey opcode to fetch key codes. The data pointer is a pointer to a single value of type 'int', for returning the key code, which can be in the range 1 to 65535, or 0 if there is no keyboard event. For CSOUND_CALLBACK_KBD_EVENT, both key press and release events should be returned (with 65536 (0x10000) added to the key code in the latter case) as unshifted ASCII codes. CSOUND_CALLBACK_KBD_TEXT expects key press events only as the actual text that is typed. The return value should be zero on success, negative on error, and positive if the callback was ignored (for example because the type is not known).
PUBLIC void csoundSetChannelIOCallback | ( | CSOUND * | , |
CsoundChannelIOCallback_t | func | ||
) |
Sets callback function to be called by the opcodes 'chnsend' and 'chnrecv'.
Should be called between csoundPreCompile() and csoundCompile(). The callback function takes the following arguments: CSOUND *csound Csound instance pointer const char *channelName the channel name MYFLT *channelValuePtr pointer to the channel value. Control channels are a single MYFLT value, while audio channels are an array of csoundGetKsmps(csound) MYFLT values. In the case of string channels, the pointer should be cast to char *, and points to a buffer of csoundGetStrVarMaxLen(csound) bytes int channelType bitwise OR of the channel type (CSOUND_CONTROL_CHANNEL, CSOUND_AUDIO_CHANNEL, or CSOUND_STRING_CHANNEL; use channelType & CSOUND_CHANNEL_TYPE_MASK to extract the channel type), and either CSOUND_INPUT_CHANNEL or CSOUND_OUTPUT_CHANNEL to indicate the direction of the data transfer The callback is not preserved on csoundReset().
PUBLIC int csoundSetControlChannelParams | ( | CSOUND * | , |
const char * | name, | ||
int | type, | ||
MYFLT | dflt, | ||
MYFLT | min, | ||
MYFLT | max | ||
) |
Sets special parameters for a control channel.
The parameters are: type: must be one of CSOUND_CONTROL_CHANNEL_INT, CSOUND_CONTROL_CHANNEL_LIN, or CSOUND_CONTROL_CHANNEL_EXP for integer, linear, or exponential channel data, respectively, or zero to delete any previously assigned parameter information dflt: the control value that is assumed to be the default, should be greater than or equal to 'min', and less than or equal to 'max' min: the minimum value expected; if the control type is exponential, it must be non-zero max: the maximum value expected, should be greater than 'min'; if the control type is exponential, it must be non-zero and match the sign of 'min' Returns zero on success, or a non-zero error code on failure: CSOUND_ERROR: the channel does not exist, is not a control channel, or the specified parameters are invalid CSOUND_MEMORY: could not allocate memory
Sets an external callback for Cscore processing.
Pass NULL to reset to the internal cscore() function (which does nothing). This callback is retained after a csoundReset() call.
PUBLIC void csoundSetDrawGraphCallback | ( | CSOUND * | , |
void(*)(CSOUND *, WINDAT *windat) | drawGraphCallback_ | ||
) |
Called by external software to set Csound's DrawGraph function.
Called by external software to set Csound's ExitGraph function.
Sets callback for converting MIDI error codes to strings.
PUBLIC void csoundSetExternalMidiInCloseCallback | ( | CSOUND * | , |
int(*)(CSOUND *, void *userData) | func | ||
) |
Sets callback for closing real time MIDI input.
PUBLIC void csoundSetExternalMidiInOpenCallback | ( | CSOUND * | , |
int(*)(CSOUND *, void **userData, const char *devName) | func | ||
) |
Sets callback for opening real time MIDI input.
PUBLIC void csoundSetExternalMidiOutCloseCallback | ( | CSOUND * | , |
int(*)(CSOUND *, void *userData) | func | ||
) |
Sets callback for closing real time MIDI output.
PUBLIC void csoundSetExternalMidiOutOpenCallback | ( | CSOUND * | , |
int(*)(CSOUND *, void **userData, const char *devName) | func | ||
) |
Sets callback for opening real time MIDI output.
PUBLIC void csoundSetExternalMidiReadCallback | ( | CSOUND * | , |
int(*)(CSOUND *, void *userData, unsigned char *buf, int nBytes) | func | ||
) |
Sets callback for reading from real time MIDI input.
PUBLIC void csoundSetExternalMidiWriteCallback | ( | CSOUND * | , |
int(*)(CSOUND *, void *userData, const unsigned char *buf, int nBytes) | func | ||
) |
Sets callback for writing to real time MIDI output.
PUBLIC void csoundSetFileOpenCallback | ( | CSOUND * | p, |
void(*)(CSOUND *, const char *, int, int, int) | func | ||
) |
Sets an external callback for receiving notices whenever Csound opens a file.
The callback is made after the file is successfully opened. The following information is passed to the callback: char* pathname of the file; either full or relative to current dir int a file type code from the enumeration CSOUND_FILETYPES int 1 if Csound is writing the file, 0 if reading int 1 if a temporary file that Csound will delete; 0 if not
Pass NULL to disable the callback. This callback is retained after a csoundReset() call.
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.
Calling this function with a non-zero 'state' value between csoundPreCompile() and csoundCompile() will disable all default handling of sound I/O by the Csound library, allowing the host application to use the spin/spout/input/output buffers directly.
If 'bufSize' is greater than zero, the buffer size (-b) will be set to the integer multiple of ksmps that is nearest to the value specified.
PUBLIC void csoundSetInputValueCallback | ( | CSOUND * | , |
void(*)(CSOUND *, const char *channelName, MYFLT *value) | inputValueCalback_ | ||
) |
Control values are specified by a 'channelName' string.
Note that the 'invalue' & 'outvalue' channels can be specified by either a string or a number. If a number is specified, it will be converted to a string before making the callbacks to the external software. Called by external software to set a function for Csound to fetch input control values. The 'invalue' opcodes will directly call this function. If 'channelName' starts with a '$', then 'invalue' opcode is expecting a C string, to be copied to 'value', with maximum size csoundGetStrVarMaxLen().
Tells Csound whether external graphic table display is supported.
Returns the previously set value (initially zero).
PUBLIC void csoundSetKillGraphCallback | ( | CSOUND * | , |
void(*)(CSOUND *, WINDAT *windat) | killGraphCallback_ | ||
) |
Called by external software to set Csound's KillGraph function.
Called by external software to set Csound's KillXYin function.
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 void csoundSetMakeGraphCallback | ( | CSOUND * | , |
void(*)(CSOUND *, WINDAT *windat, const char *name) | makeGraphCallback_ | ||
) |
Called by external software to set Csound's MakeGraph function.
PUBLIC void csoundSetMakeXYinCallback | ( | CSOUND * | , |
void(*)(CSOUND *, XYINDAT *, MYFLT x, MYFLT y) | makeXYinCallback_ | ||
) |
Called by external software to set Csound's MakeXYin function.
PUBLIC void csoundSetMessageCallback | ( | CSOUND * | , |
void(*)(CSOUND *, int attr, const char *format, va_list valist) | csoundMessageCallback_ | ||
) |
Sets a function to be called by Csound to print an informational message.
Sets the Csound message level (from 0 to 231).
PUBLIC void csoundSetOutputValueCallback | ( | CSOUND * | , |
void(*)(CSOUND *, const char *channelName, MYFLT value) | outputValueCalback_ | ||
) |
Called by external software to set a function for Csound to send output control values.
The 'outvalue' opcodes will directly call this function. If 'channelName' starts with a '$', then the 'outvalue' opcode is sending a string appended to channelName in the format: "$channelName$stringOutput". and 'value' will be the index number into 'channelName' where the stringOutput begins.
PUBLIC void csoundSetPlayopenCallback | ( | CSOUND * | , |
int(*)(CSOUND *, const csRtAudioParams *parm) | playopen__ | ||
) |
Sets a function to be called by Csound for opening real-time audio playback.
Called by external software to set Csound's ReadXYin function.
PUBLIC void csoundSetRecopenCallback | ( | CSOUND * | , |
int(*)(CSOUND *, const csRtAudioParams *parm) | recopen_ | ||
) |
Sets a function to be called by Csound for opening real-time audio recording.
Sets a function to be called by Csound for closing real-time audio playback and recording.
PUBLIC void csoundSetRtplayCallback | ( | CSOUND * | , |
void(*)(CSOUND *, const MYFLT *outBuf, int nbytes) | rtplay__ | ||
) |
Sets a function to be called by Csound for performing real-time audio playback.
PUBLIC void csoundSetRtrecordCallback | ( | CSOUND * | , |
int(*)(CSOUND *, MYFLT *inBuf, int nbytes) | rtrecord__ | ||
) |
Sets a function to be called by Csound for performing real-time audio recording.
Csound score events prior to the specified time are not performed, and performance begins immediately at the specified time (real-time events will continue to be performed as they are received).
Can be used by external software, such as a VST host, to begin score performance midway through a Csound score, for example to repeat a loop in a sequencer, or to synchronize other events with the Csound score.
Sets whether Csound score events are performed or not (real-time events will continue to be performed).
Can be used by external software, such as a VST host, to turn off performance of score events (while continuing to perform real-time events), for example to mute a Csound score while working on other tracks of a piece, or to play the Csound instruments live.
Called by external software to set a function for checking system events, yielding cpu time for coopertative multitasking, etc.
This function is optional. It is often used as a way to 'turn off' Csound, allowing it to exit gracefully. In addition, some operations like utility analysis routines are not reentrant and you should use this function to do any kind of updating during the operation. Returns an 'OK to continue' boolean.
PUBLIC void csoundSleep | ( | size_t | milliseconds | ) |
Waits for at least the specified number of milliseconds, yielding the CPU to other threads.
Stops a csoundPerform() running in another thread.
Note that it is not guaranteed that csoundPerform() has already stopped when this function returns.
Returns the value of a slot in a function table.
The table number and index are assumed to be valid.
Returns the length of a function table (not including the guard point), or -1 if the table does not exist.
Sets the value of a slot in a function table.
The table number and index are assumed to be valid.
PUBLIC void csoundUnlockMutex | ( | void * | mutex_ | ) |
Releases the indicated mutex object, which should be owned by the current thread, otherwise the operation of this function is undefined.
A recursive mutex needs to be unlocked as many times as it was locked previously.
PUBLIC int csoundWaitBarrier | ( | void * | barrier | ) |
Wait on the thread barrier.
PUBLIC int csoundWaitThreadLock | ( | void * | lock, |
size_t | milliseconds | ||
) |
Waits on the indicated monitor object for the indicated period.
The function returns either when the monitor object is notified, or when the period has elapsed, whichever is sooner; in the first case, zero is returned. If 'milliseconds' is zero and the object is not notified, the function will return immediately with a non-zero status.
PUBLIC void csoundWaitThreadLockNoTimeout | ( | void * | lock | ) |
Waits on the indicated monitor object until it is notified.
This function is similar to csoundWaitThreadLock() with an infinite wait time, but may be more efficient.