Obucket

INSTRUMENT design -- arbitrary buffering object

The Obucket object keeps a private buffer of floating-point numbers, and a 'call-back' function can be registered that will be invoked when the buffer is filled. One floating-point number at a time can be added to the internal buffer, and when Obucket sees that the buffer is full, it calls the 'call-back' function with the buffer, its length and a user-supplied context as arguments. This is useful for instruments that must process in blocks whose size has no clear and predictable relationship to the RTcmix buffer size (for example, instruments that do FFT-based processing).

Constructors

Obucket(

int len, ProcessFunction callback, void *context

)

len is the length of the buffer used by Obucket.
callback is the function to be called when the buffer is filled. ProcessFunction is defined as follows:

   typedef void (*ProcessFunction)(const float *buf, const int len,
                                                     void *context);

context is a pointer to any user-created data that the callback needs to function properly.

Access Methods

bool Obucket::drop(

float item

)

puts item into the internal private buffer. If the buffer is then made full, it invokes the ProcessFunction callback defined in the constructor and returns TRUE, otherwise it store the item and returns FALSE. It will also reset the internal pointer to the beginning of the buffer so that the whole process of filling may be repeated. Typically item will be a sound sample.

void Obucket::flush(

float defaultval

)

fills the entire internal private buffer with defaultval and resets the internal buffer pointer to the beginning of the buffer. If defaultval is not given, then 0.0 is used.

void Obucket::clear(

float defaultval

)

fills the entire internal private buffer with defaultval but does not reset the internal buffer pointer to the beginning of the buffer. If defaultval is not given, then 0.0 is used.

Examples

#include <Ougens.h>

Obucket *theBucket;

// the following function would be defined to operate on the buffer
// passed in by theBucket.
// It's best to do this as a member function of the MYINSTRUMENT
// object, but in that case it needs a static member function
// wrapper.  See the source code for CONVOLVE1.cpp (in RTcmix/insts/jg)
// for how this works.
void dostuff(const float buf[], const int len, void *obj);

int MYINSTRUMENT::init(float p[], int n_args)
{

	...

	theBucket = new Obucket(nelements, dostuff, (void *) this);

	...

}

int MYINSTRUMENT::run()
{
	float out[2];
	float sample;

	...

	for (i = 0; i < framesToRun(); i++)
	{
		sample = someSampleGeneratingProcess();
		theBucket->drop(sample);
	}

	...

}