update

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)
int update(double p[], int nvalues, unsigned fields)


p[] is an array of doubles that will be filled with values coming from a PField variable or table-handle. For example, if the following scorefile invoked an Instrument note:

handle = maketable(...)
INSTRUMENT(0.0, 1.0, 2.0, handle, 4.0, ...)

then any data being changed through the variable handle when the note was being executed would appear as element 4 (p[3]) in the p[] array.
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.


double update(int index)
double update(int index, int totframes)


index is the index of the p-field to retrieve. If index is 2, for example, then the current value for p[2] will be returned as a double.
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

• Instrument