rtgetin

INSTRUMENT design -- sample input-reading function

The rtgetin() function is used in RTcmix instrument design to read a buffer of samples from the input stream. This will probably be a soundfile or a real-time input source, depending on how the rtinput score directive is set. The point where rtgetin() actually starts reading also depends on the rtsetinput function probably used in the INSTRUMENT::init() member function.

rtgetin() differs from rtaddout in that it reads a block of samples instead of a single "frame" (1-sample-step * number-of-output-channels) of samples. The buffer used by rtgetin() has to be dimensioned large enough to hold the number of samples that will be buffered by RTcmix. Since this depends on how the buffers were set in the rtsetparams score directive, this usually needs to be allocated dynamically.

Here's an example of how to do this:

float in[];

int MYINSTRUMENT::run()
{
	int rsamps;

	...

	if (in == NULL) // first time, we need to allocate the buffer memory
		in = new float[RTBUFSAMPS*inputChannels()]

	rsamps = framesToRun() * inputChannels();
	rtgetin(in, this, rsamps);

	...
}

Where does the variable RTBUFSAMPS come from? It is a class variables that is part of the general Instrument object, used as the base class to create user-written instruments. The framesToRun() and inputChannels are inline access functions, also part of the Instrument object, that return the Instrument class variables inputchans and chunksamps.

Because rtgetin() reads an entire buffer, this buffer needs to be 'stepped through' inside the INSTRUMENT::run() method. The step size depends on how many channels (inputChannels(), or inputchans) are in the input stream, as samples are interleaved in the buffer. This means, for example, that a stereo input stream will set up the buffer-array with left0, right0, left1, right1, left2, right2 ... leftN, rightN.

Generally rtgetin is used in the INSTRUMENT::run() member function, just before the sample-computing loop. It can also be used to read in a buffer of samples from an input file at any point inside an INSTRUMENT. rtgetin assumes that rtsetinput was called previously.

This function replaces the older GETIN macro used in disk-only cmix.

Usage

int rtgetin(

float buffer[], Instrument *inst, int real_samps

)

buffer is the name of a float array used to store the input samples. It needs to be at least as large as RTBUFSAMPS*inputChannels() -- these being the two factors that dictate how many actual sample values are read during each buffer-increment of the RTcmix scheduler.
*inst is a pointer to the INSTRUMENT object being run. Usually this is the token this (i.e. a pointer to the INSTRUMENT calling the rtgetin() function).
real_samps is the actual number of samples to be read into the buffer. Usually this is the length of the RTcmix "chunk" (RTBUFSAMPS) multipled by the number of samples for each from (the number of input channels).

The rtgetin() function returns the number of actual samples read into the buffer.

Examples

#include <Instrument.h>

float in[];

int MYINSTRUMENT::run()
{
	float out[2]; // stereo output array
	int rsamps; // rsamps is the "real" number of samples read

	...

	if (in == NULL) // first time, so allocate it
		in = new float [RTBUFSAMPS*inputChannels()];

	rsamps = framesToRun() * inputChannels();
	rtgetin(in, this, rsamps);

	// skip through the buffer a frame at a time, rather than a sample at a time
	for (i = 0; i < rsamps; i += inputChannels())
	{
		...

		out[0] = in[i];
		out[1] = in[i+1];

		rtaddout(out);

		...
	}
}

rtgetin

Usage

Examples

See Also