Home · Standalone · rtcmix~ · iRTcmix · Tutorials · Reference |
RTcmix an open-source digital signal processing and sound synthesis language |
about · links · contact |
updateINSTRUMENT design -- retrieve PField values during sample computationThe update() function is used to read data coming from a PField variable or a table-handle (see the maketable scorefile command) into an instrument. Typically update() is called in the INSTRUMENT::run() member function inside the sample-computation loop. It is usually placed within a conditional structure so that it gets called at the reset rate set by the reset scorefile command. update() is new in RTcmix4.0, and is the mechanism that allows Instrument parameters to be altered as a note is being played. See the source code for various instruments for examples of how this function is employed. Usage
int update(double p[], int nvalues, unsigned fields) nvalues is the total number of values that will be scanned into the p[] array. Note that p[] has to be dimensioned large enough to accommodate nvalues. fields is an optional parameter (actually set to "0" if it isn't present) that represents a bitmask to retrieve only specific values into the p[] array. In the example above, if the call to update() in the Instrument was: double p[5]; kp3 = 1 << 3; update(p[], 5, kp3);then only p[3] would be updated. This results in an increase in Instrument efficiency. Note that only 31 bits are possible with this scheme, however, so that the bitmask only supports the first 31 p-fields.
These versions of update() always returns 0 for some reason.
totframes is an optional argument representing the total number of sample frames over which this update will operate. This is useful for tables (control envelopes) that are intended only to span a portion of an executing note. An example of this might be a table to perform a fade-out during the 'ring-down' portion of an Instrument employing a feedback delay line. To put it another way, calling this version of update with the optional totframes argument makes the pfield span the duration corresponding to totframes instead of nSamps(). Note that it's much more efficient to grab all the pfields using the first update method than to use this update method multiple times, so try to avoid this method when you can use the other one. Examples#include <Instrument.h> int MYINSTRUMENT::init(float p[], int n_args) { // assumes p[4] can be updated dynamically through a PField variable ... branch = 0; // a MYINSTRUMENT class variable ... } int MYINSTRUMENT::run() { ... for (int i = 0; i < framesToRun(); i++) { if(--branch <= 0) { double p[7]; update(p, 7); // 7 total values we're retrieving theparameter = p[4]; // possibly a new value branch = getSkip(); // so that we don't get called every sample // getSkip() returns the number of samples // for one cycle of the control rate } ... } ... } See Also |