|Home · Standalone · rtcmix~ · iRTcmix · Tutorials · Reference|
an open-source digital signal processing and sound synthesis language
|about · links · contact|
load - load an RTcmix instrument for use
load is an essential command for all RTcmix scorefiles. load is used to load in particular instrument executable-library files (DSOs) for the RTcmix instrument(s) that will be used during the run of the scorefile. One or more load commands usually follows the rtsetparams setup command.
The syntax for load is easy -- it will either take a string with the name of one of the distributued RTcmix instruments stored in the RTcmix-searched DSO library (usually "RTcmix/shlib"), or it can take an absolute or relative pathname string to a "libINSTRUMENT.so" instrument DSO directly (the second method is how a user-developed library would be loaded into RTcmix for use).
Here's an example from the original documentation by Doug Scott
for the load scorefile command:
rtsetparams(44100, 1); /* set output params */ rtinput("/snd/myfile.snd"); load("FMINST"); /* this loads the FMINST DSO */ FMINST(....); /* use FMINST */Then run the command:
CMIX < scorefileIf you have created a custom instrument DSO following the TEMPLATE example, you will end up with a file called libMYINSTRUMENT.so, where "MYINSTRUMENT" is whatever you named your instrument. To use it, just put a line:
load("./libMYINSTRUMENT.so");at the top of your score. Note that this is specified as a file name, where the FMINST was not. Any pre-existing RTcmix instrument which has a pre-installed DSO can use the first form; custom DSOs use the latter form.
How does this work? Most UNIX-like operating systems allow object code to be dynamically loaded, i.e., read from a file and added to a running program. They also include a feature for accessing the functions and other symbols which are in that dynamically loaded object. When you give a load("FOO") command, RTcmix looks in its default DSO location for a file called "libFOO.so". If it doesn't find it, it returns an error message. If it does find it, it loads it in. It then looks in that object to see if it has the magic "profile" and/or "rtprofile" functions. It it does, it calls them -- and this makes all the RTcmix functions in that DSO available to CMIX! The only instrument that does not require an explicit load command in the scorefile is MIX because it is the 'foundation' instrument for RTcmix.
Be aware that if you load the same DSO more than once in a scorefile, it will really get confused about the symbol-table entries (i.e. don't do this!).