TITLE:: FluidBufCompose
SUMMARY:: Buffer Compositing Utility
CATEGORIES:: Libraries>FluidDecomposition, UGens>Buffer
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition, 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. We use it extensively in our example code.

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

It is part of the Fluid Decomposition Toolkit of the FluCoMa project. footnote::
This  was made possible thanks to the FluCoMa project ( http://www.flucoma.org/ ) funded by the European Research Council ( https://erc.europa.eu/ ) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 725899).::

The algorithm takes two buffers in, and writes the composited 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
	This method triggers the compositing.

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

ARGUMENT:: srcBufNumA
	The bufNum of the first source buffer.

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

ARGUMENT:: nFramesA
	The duration (in samples) to copy from the first source buffer.

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

ARGUMENT:: nChansA
	The number of channels from which to copy in the first source buffer. This parameter will wrap around the number of channels in the source buffer.

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

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

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

ARGUMENT:: srcBufNumB
	The bufNum of the second source buffer.

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

ARGUMENT:: nFramesB
	The duration (in samples) to copy from the second source buffer.

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

ARGUMENT:: nChansB
	The number of channels from which to copy in the second source buffer. This parameter will wrap around the number of channels in the source buffer.

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

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

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

ARGUMENT:: dstBufNum
	The bufNum of the destination buffer.

RETURNS::
	Nothing, as the various destination buffers are declared in the function call.

DISCUSSION::
	It is important to understand the rules used for determining the final desintinaiton buffer dimensions to get the most out of this object. The destination buffer will be resized to the maxima of the requsted source numFrames and numChannels, independently of whether the source buffers are that big or not. 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 desintation 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)
FluidBufCompose.process(s, srcBufNumA: b.bufnum, srcBufNumB: c.bufnum, dstBufNum: d.bufnum);
d.query;
d.play;

//constructing a mono buffer, with a quiet punch from the synth, with a choked piano resonance from the left channel
FluidBufCompose.process(s, srcBufNumA: b.bufnum, nFramesA: 9000, srcGainA: 0.5, srcBufNumB: c.bufnum, startAtB:30000, nFramesB:44100, nChansB:1, srcGainB:0.9, dstBufNum: d.bufnum);
d.query;
d.play;

//constructing a stereo buffer, with the end of the mono synth in both channels, with a piano resonance in swapped stereo
FluidBufCompose.process(s, srcBufNumA: b.bufnum, startAtA: 441000, nChansA: 2, srcGainA: 0.6, srcBufNumB: c.bufnum, nFramesB: 80000, startChanB: 1, nChansB: 2, srcGainB: 0.5, dstStartAtB: 22050, dstStartChanB: 0, dstBufNum: d.bufnum);
d.query;
d.play;

//constructing a one second buffer: the first second of each buffer, the mono synth on the right, the piano on the left
FluidBufCompose.process(s, srcBufNumA: b.bufnum, nFramesA: 44100, nChansA: 1, dstStartChanA: 1, srcBufNumB: c.bufnum, nFramesB:44100, nChansB:1, dstBufNum: d.bufnum);
d.query;
d.play;

// growing a buffer on itself
e = Buffer.alloc(s,1,1);
FluidBufCompose.process(s,srcBufNumA: b.bufnum, srcBufNumB: e.bufnum, dstBufNum: e.bufnum);
FluidBufCompose.process(s,srcBufNumA: c.bufnum,  nChansA: 1, srcBufNumB: e.bufnum, dstBufNum: e.bufnum);
e.plot;
e.play;
::

	STRONG::A more complex example: using composition as an Mid-Side filtering process::

	CODE::
// load a stereo buffer and initialise the many destinations
(
b = Buffer.read(s,File.realpath(FluidBufCompose.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SA-UprightPianoPedalWide.wav");
c = Buffer.new(s);
d = Buffer.new(s);
e = Buffer.alloc(s,1,1);
f = Buffer.new(s);
)

// encode the mid (in c) and the side (in d)
(
FluidBufCompose.process(s,b.bufnum,nChansA: 1, srcGainA: -3.0.dbamp, srcBufNumB:b.bufnum,startChanB: 1, nChansB: 1, srcGainB: -3.0.dbamp, dstBufNum: c.bufnum);
FluidBufCompose.process(s,b.bufnum,nChansA: 1, srcGainA: -3.0.dbamp, srcBufNumB:b.bufnum,startChanB: 1, nChansB: 1, srcGainB: -3.0.dbamp * -1.0, dstBufNum: d.bufnum);
)

// (optional) compare auraly the stereo with the MS
c.query;d.query;
b.play;
{PlayBuf.ar(1,[c.bufnum,d.bufnum])}.play;

// The geeky bit: copy the side (buffer d) on itself with specific amplitudes and delays, in effect applying a FIR filter through expensive convolution

// Important: do either of the 3 options below

// option 1: apply a high pass on the side, with a cutoff of nyquist / 4
(
[1.0, -1.0].do({ arg x,y;
	FluidBufCompose.process(s,d.bufnum,srcGainA: x, dstStartAtA: y, srcBufNumB: e.bufnum, dstBufNum: e.bufnum);
});
)

// option 2: apply a high pass on the side, with a cutoff of nyquist / 10
(
[0.8, -0.32, -0.24, -0.16, -0.08].do({ arg x,y;
	FluidBufCompose.process(s,d.bufnum,srcGainA: x, dstStartAtA: y, srcBufNumB: e.bufnum, dstBufNum: e.bufnum);
});
)

// option 3: apply a high pass on the side, with a cutoff of nyquist / 100
(
[0.982494, -0.066859, -0.064358, -0.061897, -0.059477, -0.057098, -0.054761, -0.052466, -0.050215, -0.048007, -0.045843, -0.043724, -0.041649, -0.03962, -0.037636, -0.035697, -0.033805, -0.031959, -0.030159, -0.028406, -0.026699, -0.025038, -0.023425, -0.021857, -0.020337].do({ arg x,y;
	FluidBufCompose.process(s,d.bufnum,srcGainA: x, dstStartAtA: y, srcBufNumB: e.bufnum, dstBufNum: e.bufnum);
});
)

// play the high-passed side buffer
e.play;
// if you want to try the other filters, do not forget to clear the destination buffer since it will add programmatically onto itself and would not create the expected frequency response

// decode the MS back to stereo
(
FluidBufCompose.process(s,c.bufnum, srcGainA: -3.0.dbamp, srcBufNumB:e.bufnum, srcGainB: -3.0.dbamp, dstBufNum: f.bufnum);
FluidBufCompose.process(s,c.bufnum, srcGainA: -3.0.dbamp, dstStartChanA: 1, srcBufNumB:f.bufnum, dstBufNum: f.bufnum);
FluidBufCompose.process(s,e.bufnum, srcGainA: -3.0.dbamp * -1.0,dstStartChanA: 1, srcBufNumB:f.bufnum, dstBufNum: f.bufnum);
)

// query and play
f.query;
f.play;

// compare with the original
b.play;
::