Proposed API Changes
Group functions better by topic, and also showing first functions which beginners are more likely to use.
There is an API function (?) PUBLIC int csoundSetGlobalEnv(const char *name, const char *value); which does not take a CSOUND* argument. Actually this function sets a static variable which seems to me to break re-entrance. Clearly the static in question (globalEnvVars) can be moved to the CSOUND structure, but then csoundSetGlobalEnv cannot see it.
The "easiest" fix is to add a CSOUND* argument to csoundSetGlobalEnv, but that means a major API bump.
csoundGetVersion and csoundGetAPIVersion
These functions can be ambiguous, for example, is 5140 5.1.40 or 5.14.0? Maybe these should be broken into getMajorVersion/getMinorVersion/getRevision?
See RFC_2-Widget API.
Dynamic instrument and UDO creation API
An API should be provision for the creation, querying and deletion of processing graphs from the API. Since these changes can only be applied between block processing, this function should only return once the current block has been completed and the changes have been applied. To avoid locking the engine thread, a lock-free messaging system should be implemented. See some notes on how SuperCollider handles this: []. Also have a look at how other engines like PD handle this dynamic modification. See RFC_4-Dynamic_processing_graph for more details.
Messaging system for csPerfThread
Although not part of the API itself, many users will interact through this class. Would it be good to have a plain C equivalent? See RFC_3-Messaging-system for details.
Internal message buffer
The message buffer is very limited as it ties up the host data pointer. It can be useful however as it optionally prints the messages to std outs as well. Maybe this functionality can be added when setting a message callback.
1769 /** 1770 * Creates a buffer for storing messages printed by Csound. 1771 * Should be called after creating a Csound instance; note that 1772 * the message buffer uses the host data pointer, and the buffer 1773 * should be freed by calling csoundDestroyMessageBuffer() before 1774 * deleting the Csound instance. 1775 * If 'toStdOut' is non-zero, the messages are also printed to 1776 * stdout and stderr (depending on the type of the message), 1777 * in addition to being stored in the buffer. 1778 */ 1779 void PUBLIC csoundEnableMessageBuffer(CSOUND *csound, int toStdOut); 1780 1781 /** 1782 * Returns the first message from the buffer. 1783 */ 1784 PUBLIC const char* csoundGetFirstMessage(CSOUND *csound); 1785 1786 /** 1787 * Returns the attribute parameter (see msg_attr.h) of the first message 1788 * in the buffer. 1789 */ 1790 int PUBLIC csoundGetFirstMessageAttr(CSOUND *csound); 1791 1792 /** 1793 * Removes the first message from the buffer. 1794 */ 1795 void PUBLIC csoundPopFirstMessage(CSOUND *csound); 1796 1797 /** 1798 * Returns the number of pending messages in the buffer. 1799 */ 1800 int PUBLIC csoundGetMessageCnt(CSOUND *csound); 1801 1802 /** 1803 * Releases all memory used by the message buffer. 1804 */ 1805 void PUBLIC csoundDestroyMessageBuffer(CSOUND *csound);
- Is it necessary to have plugin related information in the header (e.g. CSFTYPE_VST_PLUGIN and CSFTYPE_LADSPA_PLUGIN)?
- Should these be part of the API?
1144 PUBLIC int csoundGetDebug(CSOUND *); 1145 1146 /** 1147 * Sets whether Csound is in debug mode. 1148 */ 1149 PUBLIC void csoundSetDebug(CSOUND *, int debug);
What exactly do they do?
1474 PUBLIC int csoundGetSizeOfMYFLT(void);
the same as:
702 PUBLIC int csoundGetSampleSize(CSOUND *);
Maybe one is for the internal buffer and the other is the output buffer (which can be a file). If they are different, then they should be documented better, even changin the name a bit to make them clearer.
Consolidate I/O Bus callbacks
There are currently three different ways to pass data to and from the API. Each has slightly different capabilities and interface. They should be unified in a single consistent interface. These data passing functions should incorporate the possibility of accessing other unspecified data types, e.g. RFC_1-Arrays
PUBLIC void csoundSetInputValueCallback(CSOUND *, 905 void (*inputValueCalback_)(CSOUND *, 906 const char *channelName, 907 MYFLT *value)); 918 PUBLIC void csoundSetOutputValueCallback(CSOUND *, 919 void (*outputValueCalback_)(CSOUND *, 920 const char *channelName, 921 MYFLT value));
1559 PUBLIC int csoundGetChannelPtr(CSOUND *, 1560 MYFLT **p, const char *name, int type); 1561 1562 /** 1563 * Returns a list of allocated channels in *lst. A CsoundChannelListEntry 1564 * structure contains the name and type of a channel, with the type having 1565 * the same format as in the case of csoundGetChannelPtr(). 1566 * The return value is the number of channels, which may be zero if there 1567 * are none, or CSOUND_MEMORY if there is not enough memory for allocating 1568 * the list. In the case of no channels or an error, *lst is set to NULL. 1569 * Notes: the caller is responsible for freeing the list returned in *lst 1570 * with csoundDeleteChannelList(). The name pointers may become invalid 1571 * after calling csoundReset(). 1572 */ 1573 PUBLIC int csoundListChannels(CSOUND *, CsoundChannelListEntry **lst); 1574 1575 /** 1576 * Releases a channel list previously returned by csoundListChannels(). 1577 */ 1578 PUBLIC void csoundDeleteChannelList(CSOUND *, CsoundChannelListEntry *lst); 1579 1580 /** 1581 * Sets special parameters for a control channel. The parameters are: 1582 * type: must be one of CSOUND_CONTROL_CHANNEL_INT, 1583 * CSOUND_CONTROL_CHANNEL_LIN, or CSOUND_CONTROL_CHANNEL_EXP for 1584 * integer, linear, or exponential channel data, respectively, 1585 * or zero to delete any previously assigned parameter information 1586 * dflt: the control value that is assumed to be the default, should be 1587 * greater than or equal to 'min', and less than or equal to 'max' 1588 * min: the minimum value expected; if the control type is exponential, 1589 * it must be non-zero 1590 * max: the maximum value expected, should be greater than 'min'; 1591 * if the control type is exponential, it must be non-zero and 1592 * match the sign of 'min' 1593 * Returns zero on success, or a non-zero error code on failure: 1594 * CSOUND_ERROR: the channel does not exist, is not a control channel, 1595 * or the specified parameters are invalid 1596 * CSOUND_MEMORY: could not allocate memory 1597 */ 1598 PUBLIC int csoundSetControlChannelParams(CSOUND *, const char *name, 1599 int type, MYFLT dflt, 1600 MYFLT min, MYFLT max); 1601 1602 /** 1603 * Returns special parameters (assuming there are any) of a control channel, 1604 * previously set with csoundSetControlChannelParams(). 1605 * If the channel exists, is a control channel, and has the special parameters 1606 * assigned, then the default, minimum, and maximum value is stored in *dflt, 1607 * *min, and *max, respectively, and a positive value that is one of 1608 * CSOUND_CONTROL_CHANNEL_INT, CSOUND_CONTROL_CHANNEL_LIN, and 1609 * CSOUND_CONTROL_CHANNEL_EXP is returned. 1610 * In any other case, *dflt, *min, and *max are not changed, and the return 1611 * value is zero if the channel exists, is a control channel, but has no 1612 * special parameters set; otherwise, a negative error code is returned. 1613 */ 1614 PUBLIC int csoundGetControlChannelParams(CSOUND *, const char *name, 1615 MYFLT *dflt, MYFLT *min, MYFLT *max); 1616 1617 /** 1618 * Sets callback function to be called by the opcodes 'chnsend' and 1619 * 'chnrecv'. Should be called between csoundPreCompile() and 1620 * csoundCompile(). 1621 * The callback function takes the following arguments: 1622 * CSOUND *csound 1623 * Csound instance pointer 1624 * const char *channelName 1625 * the channel name 1626 * MYFLT *channelValuePtr 1627 * pointer to the channel value. Control channels are a single MYFLT 1628 * value, while audio channels are an array of csoundGetKsmps(csound) 1629 * MYFLT values. In the case of string channels, the pointer should be 1630 * cast to char *, and points to a buffer of 1631 * csoundGetStrVarMaxLen(csound) bytes 1632 * int channelType 1633 * bitwise OR of the channel type (CSOUND_CONTROL_CHANNEL, 1634 * CSOUND_AUDIO_CHANNEL, or CSOUND_STRING_CHANNEL; use 1635 * channelType & CSOUND_CHANNEL_TYPE_MASK to extract the channel 1636 * type), and either CSOUND_INPUT_CHANNEL or CSOUND_OUTPUT_CHANNEL 1637 * to indicate the direction of the data transfer 1638 * The callback is not preserved on csoundReset(). 1639 */ 1640 PUBLIC void csoundSetChannelIOCallback(CSOUND *, 1641 CsoundChannelIOCallback_t func);
1673 PUBLIC int csoundChanIKSet(CSOUND *, MYFLT value, int n); 1674 1675 /** 1676 * Receives a MYFLT value from the chano opcode (k-rate) at index 'n'. 1677 * The bus is automatically extended if 'n' exceeds any previously used 1678 * index value, clearing new locations to zero. 1679 * Returns zero on success, CSOUND_ERROR if the index is invalid, and 1680 * CSOUND_MEMORY if there is not enough memory to extend the bus. 1681 */ 1682 PUBLIC int csoundChanOKGet(CSOUND *, MYFLT *value, int n); 1683 1684 /** 1685 * Sends ksmps MYFLT values to the chani opcode (a-rate) at index 'n'. 1686 * The bus is automatically extended if 'n' exceeds any previously used 1687 * index value, clearing new locations to zero. 1688 * Returns zero on success, CSOUND_ERROR if the index is invalid, and 1689 * CSOUND_MEMORY if there is not enough memory to extend the bus. 1690 */ 1691 PUBLIC int csoundChanIASet(CSOUND *, const MYFLT *value, int n); 1692 1693 /** 1694 * Receives ksmps MYFLT values from the chano opcode (a-rate) at index 'n'. 1695 * The bus is automatically extended if 'n' exceeds any previously used 1696 * index value, clearing new locations to zero. 1697 * Returns zero on success, CSOUND_ERROR if the index is invalid, and 1698 * CSOUND_MEMORY if there is not enough memory to extend the bus. 1699 */ 1700 PUBLIC int csoundChanOAGet(CSOUND *, MYFLT *value, int n); 1710 PUBLIC int csoundPvsinSet(CSOUND *, const PVSDATEXT *fin, int n); 1711 1712 /** 1713 * Receives a PVSDAT fout from the pvsout opcode (f-rate) at index 'n'. 1714 * The bus is extended if 'n' exceeds any previous value. 1715 * Returns zero on success, CSOUND_ERROR if the index is invalid or 1716 * if fsig framesizes are incompatible 1717 * CSOUND_MEMORY if there is not enough memory to extend the bus 1718 */ 1719 PUBLIC int csoundPvsoutGet(CSOUND *csound, PVSDATEXT *fout, int n);
This function sets:
796 * Sets whether Csound score events are performed or not, independently 797 * of real-time MIDI events (see csoundSetScorePending()). 798 */ 799 PUBLIC int csoundIsScorePending(CSOUND *);
Additionally, should these functions be renamed to csoundIsScoreEnabled or csoundIsScoreActive? The word pending seems to imply that the functions have to do with whether score has finished.