Max 5 API Reference

msp.h

/**
    
    @defgroup msp MSP
    
    
    @defgroup buffers Buffers
    @ingroup msp
    
    Your object can access shared data stored in an MSP buffer~ object.
    Similar to table and coll objects, buffer~ objects are bound to a #t_symbol from which you can gain access to the #t_buffer struct.
    Consider the following example.
    
    @code
    t_symbol *s;
    t_object *o;
    
    s = gensym("foo");
    o = s->s_thing;
    
    // if an object is bound to the symbol "foo", then o is that object.
    if (ob_sym(o) == gensym("buffer~")) {
        // that object is a buffer~, so we can use it
        x->x_buffer = (t_buffer*)o;
        
    }
    @endcode
    
    Having stored a pointer to the buffer~ is the first step toward working with its data.
    However, you must not go accessing the data directly without taking some precautions regarding thread-safety.
    
    To access the data in a buffer you first increment the b_inuse member of the #t_buffer's struct.  
    Then you perform the requisite operations on the data, which is stored in the b_samples member.
    When you are done you decrement the b_inuse member to return it to the state in which you found it.
    
    In the past you may have set the buffer's b_inuse flag directly and cleared it when you were done.
    This is no longer good enough, and you must instead use the threadsafe macros #ATOMIC_INCREMENT and #ATOMIC_DECREMENT
    for modifying the b_inuse flag.  
    The example below demonstrates what this might look like in an MSP object's perform routine.
    Notice that extra care has been taken to ensure that the #ATOMIC_INCREMENT is always balanced with an #ATOMIC_DECREMENT call.
    
    @code
    ATOMIC_INCREMENT(&x->w_buf->b_inuse);
    if (!x->w_buf->b_valid) {
        ATOMIC_DECREMENT(&x->w_buf->b_inuse);
        goto byebye;
    }
    
    // do something with the buffer
    
    ATOMIC_DECREMENT(&x->w_buf->b_inuse);
byebye:
    return (w + 7);
    @endcode
    
    A class that accesses buffer~ objects is the simpwave~ object that is included with Max 5 SDK example projects.
    
    
    
    
    
    
    @defgroup pfft PFFT
    @ingroup msp

    When an object is instantiated, it is possible to determine if it is being created in pfft~ context in the new method.  
    In the new method (and only at this time), you can check the s_thing member of the #t_symbol '__pfft~__'.
    If this is non-null, then you will have a pointer to a #t_pfftpub struct.

    @code
    t_pfftpub *pfft_parent = (t_pfftpub*) gensym("__pfft~__")->s_thing;

    if (pfft_parent) {
        // in a pfft~ context
    }
    else {
        // not in a pfft~
    }
    @endcode



    @defgroup poly Poly
    @ingroup msp
    
    If your object is instatiated as a voice of a poly~ object, it is possible both to determine this context 
    and to determine information about the specific voice.
    This is done by querying the patcher in which your object exists for an associated object, and then calling methods on that object.
    
    @code
    t_object *patcher = NULL;
    t_max_err err = MAX_ERR_NONE;
    t_object *assoc = NULL;
    method m = NULL;
    long voices = -1;
    long index = -1;

    err = object_obex_lookup(x, gensym("#P"), &patcher);
    if (err == MAX_ERR_NONE) {
        object_method(patcher, gensym("getassoc"), &assoc);
        if (assoc) {
            post("found %s", object_classname(assoc)->s_name);

            voices = object_attr_getlong(assoc, gensym("voices"));
            post("total amount of voices: %ld", voices);

            if(m = zgetfn(assoc, gensym("getindex"))) 
                index = (long)(*m)(assoc, patcher);
            post("index: %ld", index);
        }   
    }       

    @endcode
    
    
    
*/

Copyright © 2008, Cycling '74