flucoma-sc/release-packaging/HelpSource/Classes/FluidBufCompose.schelp

TITLE:: FluidBufCompose
SUMMARY:: Buffer Compositing Utility
CATEGORIES:: Libraries>FluidDecomposition, UGens>Buffer
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition, Guides/FluidBufMultiThreading, Classes/Buffer

DESCRIPTION::
A FluidBufCompose object provides a flexible utility for combining the contents of buffers on the server. It can be used for thing like mixing down multichannel buffers, or converting from left-right stereo to mid-side. It is used extensively in all the example code of LINK::Guides/FluidDecomposition:: as part of the FluCoMa project. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/

At its most simple, the object copies the content of a source buffer into a destination buffer. The flexibility comes from the various flags controlling which portions and channels of the source to use, and by applying gains (which can be positive or negative) to the source data and the portion of the destination that would be overwritten.

The algorithm takes a srcBuf, and writes the information at the provided dstBuf. These buffer arguments can all point to the same buffer, which gives great flexibility in transforming and reshaping.

CLASSMETHODS::

METHOD:: process, processBlocking
	This method triggers the compositing.

ARGUMENT:: server
	The server on which the buffers to be processed are allocated.

ARGUMENT:: source
	The bufNum of the source buffer.

ARGUMENT:: startFrame
	The starting point (in samples) from which to copy in the source buffer.

ARGUMENT:: numFrames
	The duration (in samples) to copy from the source buffer. The default (-1) copies the full lenght of the buffer.

ARGUMENT:: startChan
	The first channel from which to copy in the source buffer.

ARGUMENT:: numChans
	The number of channels from which to copy in the source buffer. This parameter will wrap around the number of channels in the source buffer. The default (-1) copies all of the buffer's channel.

ARGUMENT:: gain
	The gain applied to the samples to be copied from the source buffer.

ARGUMENT:: destination
	The bufNum of the destination buffer.

ARGUMENT:: destStartFrame
	The time offset (in samples) in the destination buffer to start writing the source at. The destination buffer will be resized if the portion to copy is overflowing.

ARGUMENT:: destStartChan
	The channel offest in the destination buffer to start writing the source at. The destination buffer will be resized if the number of channels to copy is overflowing.

ARGUMENT:: destGain
	The gain applied to the samples in the region of the destination buffer over which the source is to be copied. The default value (0) will overwrite that section of the destination buffer, and a value of 1.0 would sum the source to the material that was present.

ARGUMENT:: freeWhenDone
Free the server instance when processing complete. Default true

ARGUMENT:: action
		A Function to be evaluated once the offline process has finished and destination instance variables have been updated on the client side. The function will be passed destination as an argument.

returns:: an instance of the processor

DISCUSSION::
	It is important to understand the rules used for determining the final desintinaiton buffer dimensions to get the most out of this object. If needs be, the destination buffer will be resized to the maxima of the requsted source numFrames and numChannels. Frames will be written up to the limit of actually available samples (meaning you can create zero padding); channels  will be written modulo the available channels, taking into account the channel offsets, meaning you can have channels repeat or loop into the source buffer's channels. See the examples below.

EXAMPLES::

code::
// load some buffers
(
b = Buffer.read(s,File.realpath(FluidBufCompose.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-AaS-SynthTwoVoices-M.wav");
c = Buffer.read(s,File.realpath(FluidBufCompose.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SA-UprightPianoPedalWide.wav");
d = Buffer.new(s);
)

// with basic params (basic summing of each full buffer in all dimensions)
(
Routine{
    FluidBufCompose.process(s, source: b,  destination: d);
    FluidBufCompose.process(s, source: c,  destination: d, destGain: 1.0);
	s.sync;
    d.query;
    d.play;
}.play;
)
//constructing a mono buffer, with a quiet punch from the synth, with a choked piano resonance from the left channel
(
Routine{
    d.free; d = Buffer.new(s);
    FluidBufCompose.process(s, source: b, numFrames: 9000, gain: 0.5, destination: d).wait;
    FluidBufCompose.process(s, source: c, startFrame:30000, numFrames:44100, numChans:1, gain:0.9, destination: d, destGain: 1.0).wait;
    d.query;
    d.play;
}.play
)
//constructing a stereo buffer, with the end of the mono synth in both channels, with a piano resonance in swapped stereo
(
Routine{
    d.free; d = Buffer.new(s);
    FluidBufCompose.process(s, source: b, startFrame: 441000, numChans: 2, gain: 0.6, destination: d).wait;
    FluidBufCompose.process(s, source: c, numFrames: 78000, startChan: 1, numChans: 2, gain: 0.5, destStartFrame: 22050, destination: d,  destGain: 1.0).wait;
    d.query;
    d.play;
}.play
)
//constructing a one second buffer: the first second of each buffer, the mono synth on the right, the piano on the left
(
Routine{
    d.free; d = Buffer.new(s);
    FluidBufCompose.process(s, source: b, numFrames: 44100, numChans: 1, destStartChan: 1, destination: d).wait;
    FluidBufCompose.process(s, source: c, numFrames:44100, numChans:1, destination: d,  destGain: 1.0).wait;
    d.query;
    d.play;
}.play
)
::