|
Csound API
6.03
|
|
Csound API
6.03
|
Functions | |
| 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. More... | |
| PUBLIC int | csoundListChannels (CSOUND *, controlChannelInfo_t **lst) |
| Returns a list of allocated channels in *lst. More... | |
| PUBLIC void | csoundDeleteChannelList (CSOUND *, controlChannelInfo_t *lst) |
| Releases a channel list previously returned by csoundListChannels(). More... | |
| PUBLIC int | csoundSetControlChannelHints (CSOUND *, const char *name, controlChannelHints_t hints) |
| Set parameters hints for a control channel. More... | |
| PUBLIC int | csoundGetControlChannelHints (CSOUND *, const char *name, controlChannelHints_t *hints) |
| Returns special parameters (assuming there are any) of a control channel, previously set with csoundSetControlChannelHints() or the chnparams opcode. More... | |
| PUBLIC int * | csoundGetChannelLock (CSOUND *, const char *name) |
| Recovers a pointer to a lock for the specified channel called 'name'. More... | |
| PUBLIC MYFLT | csoundGetControlChannel (CSOUND *csound, const char *name, int *err) |
| retrieves the value of control channel identified by *name. More... | |
| PUBLIC void | csoundSetControlChannel (CSOUND *csound, const char *name, MYFLT val) |
| sets the value of control channel identified by *name More... | |
| PUBLIC void | csoundGetAudioChannel (CSOUND *csound, const char *name, MYFLT *samples) |
| copies the audio channel identified by *name into array *samples which should contain enough memory for ksmps MYFLTs More... | |
| PUBLIC void | csoundSetAudioChannel (CSOUND *csound, const char *name, MYFLT *samples) |
| sets the audio channel identified by *name with data from array *samples which should contain at least ksmps MYFLTs More... | |
| PUBLIC void | csoundGetStringChannel (CSOUND *csound, const char *name, char *string) |
| copies the string channel identified by *name into *string which should contain enough memory for the string (see csoundGetChannelDatasize() below) More... | |
| PUBLIC void | csoundSetStringChannel (CSOUND *csound, const char *name, char *string) |
| sets the string channel identified by *name with *string More... | |
| PUBLIC int | csoundGetChannelDatasize (CSOUND *csound, const char *name) |
| returns the size of data stored in a channel; for string channels this might change if the channel space gets reallocated Since string variables use dynamic memory allocation in Csound6, this function can be called to get the space required for csoundGetStringChannel() More... | |
| PUBLIC void | csoundSetInputChannelCallback (CSOUND *csound, channelCallback_t inputChannelCalback) |
| Sets the function which will be called whenever the invalue opcode is used. More... | |
| PUBLIC void | csoundSetOutputChannelCallback (CSOUND *csound, channelCallback_t outputChannelCalback) |
| Sets the function which will be called whenever the outvalue opcode is used. More... | |
| PUBLIC int | csoundSetPvsChannel (CSOUND *, const PVSDATEXT *fin, const char *name) |
| Sends a PVSDATEX fin to the pvsin opcode (f-rate) for channel 'name'. More... | |
| PUBLIC int | csoundGetPvsChannel (CSOUND *csound, PVSDATEXT *fout, const char *name) |
| Receives a PVSDAT fout from the pvsout opcode (f-rate) at channel 'name' Returns zero on success, CSOUND_ERROR if the index is invalid or if fsig framesizes are incompatible. More... | |
| PUBLIC int | csoundScoreEvent (CSOUND *, char type, const MYFLT *pFields, long numFields) |
| Send a new score event. More... | |
| PUBLIC int | csoundScoreEventAbsolute (CSOUND *, char type, const MYFLT *pfields, long numFields, double time_ofs) |
| Like csoundScoreEvent(), this function inserts a score event, but at absolute time with respect to the start of performance, or from an offset set with time_ofs. More... | |
| PUBLIC void | csoundInputMessage (CSOUND *, const char *message) |
| Input a NULL-terminated string (as if from a console), used for line events. More... | |
| PUBLIC int | csoundKillInstance (CSOUND *csound, MYFLT instr, char *instrName, int mode, int allow_release) |
| Kills off one or more running instances of an instrument identified by instr (number) or instrName (name). More... | |
| PUBLIC int | csoundRegisterSenseEventCallback (CSOUND *, void(*func)(CSOUND *, void *), void *userData) |
| Register a function to be called once in every control period by sensevents(). More... | |
| PUBLIC void | csoundKeyPress (CSOUND *, char c) |
| Set the ASCII code of the most recent key pressed. More... | |
| PUBLIC int | csoundRegisterKeyboardCallback (CSOUND *, int(*func)(void *userData, void *p, unsigned int type), void *userData, unsigned int type) |
| Registers general purpose callback functions that will be called to query keyboard events. More... | |
| PUBLIC void | csoundRemoveKeyboardCallback (CSOUND *csound, int(*func)(void *, void *, unsigned int)) |
| Removes a callback previously set with csoundRegisterKeyboardCallback(). More... | |
| PUBLIC void csoundDeleteChannelList | ( | CSOUND * | , |
| controlChannelInfo_t * | lst | ||
| ) |
Releases a channel list previously returned by csoundListChannels().
copies the audio channel identified by *name into array *samples which should contain enough memory for ksmps MYFLTs
returns the size of data stored in a channel; for string channels this might change if the channel space gets reallocated Since string variables use dynamic memory allocation in Csound6, this function can be called to get the space required for csoundGetStringChannel()
Recovers a pointer to a lock for the specified channel called 'name'.
The returned lock can be locked/unlocked with the csoundSpinLock() and csoundSpinUnLock() functions.
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 csoundGetChannelDatasize() 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.
Operations on **p are not thread-safe by default. The host is required to take care of threadsafety by 1) with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available. 2) For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with csoundGetChannelLock() and use csoundSpinLock() and csoundSpinUnLock() to protect access to **p. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions provided below, which are threadsafe by default.
retrieves the value of control channel identified by *name.
If the err argument is not NULL, the error (or success) code finding or accessing the channel is stored in it.
| PUBLIC int csoundGetControlChannelHints | ( | CSOUND * | , |
| const char * | name, | ||
| controlChannelHints_t * | hints | ||
| ) |
Returns special parameters (assuming there are any) of a control channel, previously set with csoundSetControlChannelHints() or the chnparams opcode.
If the channel exists, is a control channel, the channel hints are stored in the preallocated controlChannelHints_t structure. The attributes member of the structure will be allocated inside this function so it is necessary to free it explicitly in the host.
The return value is zero if the channel exists and is a control channel, otherwise, an error code is returned.
Receives a PVSDAT fout from the pvsout opcode (f-rate) at channel 'name' 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
copies the string channel identified by *name into *string which should contain enough memory for the string (see csoundGetChannelDatasize() below)
Input a NULL-terminated string (as if from a console), used for line events.
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 csoundRegisterKeyboardCallback()).
| PUBLIC int csoundKillInstance | ( | CSOUND * | csound, |
| MYFLT | instr, | ||
| char * | instrName, | ||
| int | mode, | ||
| int | allow_release | ||
| ) |
Kills off one or more running instances of an instrument identified by instr (number) or instrName (name).
If instrName is NULL, the instrument number is used. Mode is a sum of the following values: 0,1,2: kill all instances (1), oldest only (1), or newest (2) 4: only turnoff notes with exactly matching (fractional) instr number 8: only turnoff notes with indefinite duration (p3 < 0 or MIDI) allow_release, if non-zero, the killed instances are allowed to release.
| PUBLIC int csoundListChannels | ( | CSOUND * | , |
| controlChannelInfo_t ** | lst | ||
| ) |
Returns a list of allocated channels in *lst.
A controlChannelInfo_t structure contains the channel characteristics. 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().
| PUBLIC int csoundRegisterKeyboardCallback | ( | CSOUND * | , |
| int(*)(void *userData, void *p, unsigned int type) | func, | ||
| void * | userData, | ||
| unsigned int | type | ||
| ) |
Registers general purpose callback functions that will be called to query keyboard events.
These callbacks are called on every control period by the sensekey opcode. 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 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. This facility can be used to ensure a function is called synchronously before every csound control buffer processing. It is important to make sure no blocking operations are performed in the callback. The callbacks are cleared on csoundCleanup(). Returns zero on success.
| PUBLIC void csoundRemoveKeyboardCallback | ( | CSOUND * | csound, |
| int(*)(void *, void *, unsigned int) | func | ||
| ) |
Removes a callback previously set with csoundRegisterKeyboardCallback().
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 | ||
| ) |
Like csoundScoreEvent(), this function inserts a score event, but at absolute time with respect to the start of performance, or from an offset set with time_ofs.
sets the audio channel identified by *name with data from array *samples which should contain at least ksmps MYFLTs
sets the value of control channel identified by *name
| PUBLIC int csoundSetControlChannelHints | ( | CSOUND * | , |
| const char * | name, | ||
| controlChannelHints_t | hints | ||
| ) |
Set parameters hints for a control channel.
These hints have no internal function but can be used by front ends to construct GUIs or to constrain values. See the controlChannelHints_t structure for details. 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
| PUBLIC void csoundSetInputChannelCallback | ( | CSOUND * | csound, |
| channelCallback_t | inputChannelCalback | ||
| ) |
Sets the function which will be called whenever the invalue opcode is used.
| PUBLIC void csoundSetOutputChannelCallback | ( | CSOUND * | csound, |
| channelCallback_t | outputChannelCalback | ||
| ) |
Sets the function which will be called whenever the outvalue opcode is used.
Sends a PVSDATEX fin to the pvsin opcode (f-rate) for channel 'name'.
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.
1.8.11 
