Buffers

Your object can access shared data stored in an MSP buffer~ object. More...

+ Collaboration diagram for Buffers:

Data Structures

struct  t_buffer_info
 Common buffer~ data/metadata. More...

Typedefs

typedef struct _buffer_ref t_buffer_ref
 A buffer~ reference.
typedef t_object t_buffer_obj
 A buffer~ object.

Functions

BEGIN_USING_C_LINKAGE
t_buffer_ref
buffer_ref_new (t_object *self, t_symbol *name)
 Create a reference to a buffer~ object by name.
void buffer_ref_set (t_buffer_ref *x, t_symbol *name)
 Change a buffer reference to refer to a different buffer~ object by name.
t_atom_long buffer_ref_getexists (t_buffer_ref *x)
 Query to find out if a buffer~ with the referenced name actually exists.
t_buffer_objbuffer_ref_getobject (t_buffer_ref *x)
 Query a buffer reference to get the actual buffer~ object being referenced, if it exists.
t_max_err buffer_ref_notify (t_buffer_ref *x, t_symbol *s, t_symbol *msg, void *sender, void *data)
 Your object needs to handle notifications issued by the buffer~ you reference.
void buffer_view (t_buffer_obj *buffer_object)
 Open a viewer window to display the contents of the buffer~.
float * buffer_locksamples (t_buffer_obj *buffer_object)
 Claim the buffer~ and get a pointer to the first sample in memory.
void buffer_unlocksamples (t_buffer_obj *buffer_object)
 Release your claim on the buffer~ contents so that other objects may read/write to the buffer~.
t_atom_long buffer_getchannelcount (t_buffer_obj *buffer_object)
 Query a buffer~ to find out how many channels are present in the buffer content.
t_atom_long buffer_getframecount (t_buffer_obj *buffer_object)
 Query a buffer~ to find out how many frames long the buffer content is in samples.
t_atom_float buffer_getsamplerate (t_buffer_obj *buffer_object)
 Query a buffer~ to find out its native sample rate in samples per second.
t_atom_float buffer_getmillisamplerate (t_buffer_obj *buffer_object)
 Query a buffer~ to find out its native sample rate in samples per millisecond.
t_max_err buffer_setpadding (t_buffer_obj *buffer_object, t_atom_long samplecount)
 Set the number of samples with which to zero-pad the buffer~'s contents.

Detailed Description

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 direct gain access to the t_buffer struct. This is potentially dangerous, and not guaranteed to be forward (or backward) compatible. Beginning with Max 6.1, developers accessing buffer~ objects are encouraged to use the t_buffer_ref API. The t_buffer_ref API provides many enhancements to improve thread-safety, simplify your perform routine, and manage the binding to the buffer~ object.

A class that accesses a buffer~ is the simpwave~ object included with Max SDK example projects.

While the Max 6 signal processing chain operates on 64-bit double-precision floats, the t_buffer_obj storage remains as 32-bit single-precision float format. This is essential to maintain backward compatibility with older third-party externals.

If you have written to the buffer~ and thus changed the values of its samples, you should now mark the buffer~ as dirty. This will ensure that objects such as waveform~ update their rendering of the contents of this buffer~. This can be accomplished with the following call:

    object_method(b, gensym("dirty"));

Typedef Documentation

A buffer~ object.

This represents the actual buffer~ object. You can use this to send messages, query attributes, etc. of the actual buffer object referenced by a t_buffer_ref.

typedef struct _buffer_ref t_buffer_ref

A buffer~ reference.

Use this struct to represent a reference to a buffer~ object in Max. Use the buffer_ref_getbuffer() call to return a pointer to the buffer. You can then make calls on the buffer itself.


Function Documentation

t_atom_long buffer_getchannelcount ( t_buffer_obj buffer_object)

Query a buffer~ to find out how many channels are present in the buffer content.

Parameters:
buffer_objectthe buffer object
Returns:
the number of channels in the buffer
t_atom_long buffer_getframecount ( t_buffer_obj buffer_object)

Query a buffer~ to find out how many frames long the buffer content is in samples.

Parameters:
buffer_objectthe buffer object
Returns:
the number of frames in the buffer
t_atom_float buffer_getmillisamplerate ( t_buffer_obj buffer_object)

Query a buffer~ to find out its native sample rate in samples per millisecond.

Parameters:
buffer_objectthe buffer object
Returns:
the sample rate in samples per millisecond
t_atom_float buffer_getsamplerate ( t_buffer_obj buffer_object)

Query a buffer~ to find out its native sample rate in samples per second.

Parameters:
buffer_objectthe buffer object
Returns:
the sample rate in samples per second
float* buffer_locksamples ( t_buffer_obj buffer_object)

Claim the buffer~ and get a pointer to the first sample in memory.

When you are done reading/writing to the buffer you must call buffer_unlocksamples(). If the attempt to claim the buffer~ fails the returned pointer will be NULL.

Parameters:
buffer_objectthe buffer object
Returns:
a pointer to the first sample in memory, or NULL if the buffer doesn't exist.
t_atom_long buffer_ref_getexists ( t_buffer_ref x)

Query to find out if a buffer~ with the referenced name actually exists.

Parameters:
xthe buffer reference
Returns:
non-zero if the buffer~ exists, otherwise zero
t_buffer_obj* buffer_ref_getobject ( t_buffer_ref x)

Query a buffer reference to get the actual buffer~ object being referenced, if it exists.

Parameters:
xthe buffer reference
Returns:
the buffer object if exists, otherwise NULL
BEGIN_USING_C_LINKAGE t_buffer_ref* buffer_ref_new ( t_object self,
t_symbol name 
)

Create a reference to a buffer~ object by name.

You must release the buffer reference using object_free() when you are finished using it.

Parameters:
selfpointer to your object
namethe name of the buffer~
Returns:
a pointer to your new buffer reference
t_max_err buffer_ref_notify ( t_buffer_ref x,
t_symbol s,
t_symbol msg,
void *  sender,
void *  data 
)

Your object needs to handle notifications issued by the buffer~ you reference.

You do this by defining a "notify" method. Your notify method should then call this notify method for the t_buffer_ref.

Parameters:
xthe buffer reference
sthe registered name of the sending object
msgthen name of the notification/message sent
senderthe pointer to the sending object
dataoptional argument sent with the notification/message
Returns:
a max error code
void buffer_ref_set ( t_buffer_ref x,
t_symbol name 
)

Change a buffer reference to refer to a different buffer~ object by name.

Parameters:
xthe buffer reference
namethe name of a different buffer~ to reference
t_max_err buffer_setpadding ( t_buffer_obj buffer_object,
t_atom_long  samplecount 
)

Set the number of samples with which to zero-pad the buffer~'s contents.

The typical application for this need is to pad a buffer with enough room to allow for the reach of a FIR kernel in convolution.

Parameters:
buffer_objectthe buffer object
samplecountthe number of sample to pad the buffer with on each side of the contents
Returns:
an error code
void buffer_unlocksamples ( t_buffer_obj buffer_object)

Release your claim on the buffer~ contents so that other objects may read/write to the buffer~.

Parameters:
buffer_objectthe buffer object
void buffer_view ( t_buffer_obj buffer_object)

Open a viewer window to display the contents of the buffer~.

Parameters:
buffer_objectthe buffer object