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. More...
typedef t_object	t_buffer_obj
	A buffer~ object. More...

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. More...
void	buffer_ref_set (t_buffer_ref *x, t_symbol *name)
	Change a buffer reference to refer to a different buffer~ object by name. More...
t_atom_long	buffer_ref_exists (t_buffer_ref *x)
	Query to find out if a buffer~ with the referenced name actually exists. More...
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. More...
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. More...
void	buffer_view (t_buffer_obj *buffer_object)
	Open a viewer window to display the contents of the buffer~. More...
float *	buffer_locksamples (t_buffer_obj *buffer_object)
	Claim the buffer~ and get a pointer to the first sample in memory. More...
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~. More...
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. More...
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. More...
t_atom_float	buffer_getsamplerate (t_buffer_obj *buffer_object)
	Query a buffer~ to find out its native sample rate in samples per second. More...
t_atom_float	buffer_getmillisamplerate (t_buffer_obj *buffer_object)
	Query a buffer~ to find out its native sample rate in samples per millisecond. More...
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. More...
t_max_err	buffer_setdirty (t_buffer_obj *buffer_object)
	Set the buffer's dirty flag, indicating that changes have been made. More...
t_symbol *	buffer_getfilename (t_buffer_obj *buffer_object)
	Retrieve the name of the last file to be read by a buffer~. More...

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

t_buffer_obj

typedef t_object t_buffer_obj

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.

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

buffer_getchannelcount()

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_object

the buffer object

Returns

the number of channels in the buffer

buffer_getfilename()

t_symbol* buffer_getfilename

(

t_buffer_obj *

buffer_object

)

Retrieve the name of the last file to be read by a buffer~.

(Not the last file written).

Parameters

buffer_object

the buffer object

Returns

The name of the file last read, or gensym("") if no files have been read.

Version

Introduced in Max 7.0.1

buffer_getframecount()

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_object

the buffer object

Returns

the number of frames in the buffer

buffer_getmillisamplerate()

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_object

the buffer object

Returns

the sample rate in samples per millisecond

buffer_getsamplerate()

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_object

the buffer object

Returns

the sample rate in samples per second

buffer_locksamples()

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_object

the buffer object

Returns

a pointer to the first sample in memory, or NULL if the buffer doesn't exist.

buffer_ref_exists()

t_atom_long buffer_ref_exists

(

t_buffer_ref *

x

)

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

Parameters

x	the buffer reference

Returns

non-zero if the buffer~ exists, otherwise zero

buffer_ref_getobject()

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

x	the buffer reference

Returns

the buffer object if exists, otherwise NULL

buffer_ref_new()

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

self	pointer to your object
name	the name of the buffer~

Returns

a pointer to your new buffer reference

buffer_ref_notify()

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

x	the buffer reference
s	the registered name of the sending object
msg	then name of the notification/message sent
sender	the pointer to the sending object
data	optional argument sent with the notification/message

Returns

a max error code

buffer_ref_set()

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

x	the buffer reference
name	the name of a different buffer~ to reference

buffer_setdirty()

t_max_err buffer_setdirty

(

t_buffer_obj *

buffer_object

)

Set the buffer's dirty flag, indicating that changes have been made.

Parameters

buffer_object

the buffer object

Returns

an error code

buffer_setpadding()

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_object	the buffer object
samplecount	the number of sample to pad the buffer with on each side of the contents

Returns

an error code

buffer_unlocksamples()

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_object

the buffer object

buffer_view()

void buffer_view

(

t_buffer_obj *

buffer_object

)

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

Parameters

buffer_object

the buffer object