Max 5 API Reference

api_09_mspadvanced.h

/** 
    @page chapter_msp_advanced Advanced Signal Object Topics

    Here are some techniques for implementing additional features found in most signal objects.

    @section chapter_msp_advanced_internal_state Saving Internal State

    To implement unit generators such as filters and ramp generators, you need to save internal state between calls to your object's perform routine. Here is a very simple low-pass filter (it just averages successive samples) that saves the value of the last sample in a vector to be averaged with the first sample of the next vector. First we add a field to our data structure to hold the value:

@code
    typedef struct _myfilter
    {
        t_pxobject f_obj;
        t_float f_sample;
    } t_myfilter;
@endcode

    Then, in our dsp method (which has one input and one output), we pass a pointer to the object as one of the DSP chain arguments. The dsp method also initializes the value of the internal state, to avoid any noise when the audio starts.

@code
    void myfilter_dsp(t_myfilter *x, t_signal **sp, short *count)
    {
        dsp_add(myfilter_perform, 4, x, sp[0]->s_vec, sp[1]->s_vec, sp[0]->s_n);
    
        x->f_sample = 0;
    }
@endcode

    Here is the perform routine, which obtains the internal state before entering the processing loop, then stores the most recent value after the loop is finished.

@code
    t_int *myfilter_perform(t_int *w)
    {
        t_myfilter *x = (t_myfilter *)w[1];
        t_float *in = (t_float *)w[2];
        t_float *out = (t_float *)w[3];
        int n = (int)w[4];
        t_float samp = x->f_sample; // read from internal state
        t_float val;

        while (n--) {
            val = *in++;
            *out++ = (val + samp) * 0.5;
            samp = val;
        }
        x->f_sample = samp;     // save to internal state

        return w + 5;
    }
@endcode


    @section chapter_msp_advanced_muting Observing Patcher Muting

    The enable message to the thispatcher object, as well as the MSP mute object~ can be used to disable a subpatcher. If your object is at all computationally expensive in its perform routine, it should check to see whether it has been disabled. To do this, you'll need to pass a pointer to your object as one of the DSP chain arguments when calling dsp_add(). Here is a simple modification of our filter object's perform routine that checks to see if the object has been disabled.

@code
    t_int *myfilter_perform(t_int *w)
    {
        t_myfilter *x = (t_myfilter *)w[1];
        t_float *in = (t_float *)w[2];
        t_float *out = (t_float *)w[3];
        int n = (int)w[4];
        t_float samp = x->f_sample; // read from internal state
        t_float val;

        if (x->f_obj.z_disabled)    // check for object being disabled
            return w + 5;
 
        while (n--) {
            val = *in++;
            *out++ = (val + samp) * 0.5;
            samp = val;
        }
        x->f_sample = samp;     // save to internal state

        return w + 5;
    }
@endcode
 

    @section chapter_msp_advanced_connections Using Connection Information

    The third argument to the dsp method is an array of numbers that enumerate the number of objects connected to each of your objects inputs and outputs. More advanced dsp methods can use this information for optimization purposes. For example, if you find that your object has no inputs or outputs, you could avoid calling dsp_add() altogether. The MSP signal operator objects (such as +~ and *~) to implement a basic polymorphism: they look at the connections count to determine whether the perform routine should use scalar or signal inputs. For example, if the right input has no connected signals, the user can add a scalar value sent to the right inlet.
 
    To implement this behavior, you have a few different options. The first option is to write two different perform methods, one which handles the two-signal case, and one which handles the scalar case. The dsp method looks at the count array and passes a different function to dsp_add(). The example below assumes that the second element in the signal and count arrays (sp[1]) is the right input:

@code
        if (count[1])   // signal connected
            dsp_add(mydspobject_twosigperform, 5, x, sp[0]->s_vec, sp[1]->s_vec, sp[2]->s_vec, sp[0]->s_n);
        else
            dsp_add(mydspobject_scalarperform, 4, x, sp[0]->s_vec, sp[2]->s_vec, sp[0]->s_n);
@endcode


    The second option is to pass the value of the count array for a particular signal to the perform method, which can make the decision whether to use the signal value or a scalar value that has been stored inside the object. In this case, many objects use a single sample value from the signal as a substitute for the scalar. Using the first sample (i.e., the value at index 0) is a technique that works for any vector size, since vector sizes could be as small as a single sample. Here is an example of this technique for an object that has two inputs and one output. The connection count for the right input signal is passed as the second argument on the DSP chain, and the right input signal vector is passed even if it not connected:

@code
        dsp_add(mydspobject_perform, 6, x, count[1], sp[0]->s_vec, sp[1]->s_vec, sp[2]->s_vec, sp[0]->s_n);
@endcode

    Here is a perform routine that uses the connection count information as passed in format shown above:

@code
    t_int mydspobject_perform(t_int *w)
    {
        t_mydspobject *x = (t_mydspobject *)w[1];
        int connected = (int)w[2];
        t_float *in = (t_float *)w[3];
        t_float *in2 = (t_float *)w[4];
        t_float *out = (t_float *)w[5];
        int n = (int)w[6];

        double in2value;

        // get scalar sample or use signal depending on whether signal is connected

        in2value = connected? *in2 : x->m_scalarvalue;

        // do calculation here

        return w + 7;
    }
@endcode

*/

Copyright © 2008, Cycling '74