TITLE:: FluidBufScale
SUMMARY:: A Scaling Processor for Buffers
CATEGORIES:: Libraries>FluidCorpusManipulation
RELATED::  Guides/FluidCorpusManipulation, Guides/FluidBufMultiThreading

This class implements a simple Buffer preprocessor, by scaling its values. It draws a simple translation from inputLow to outputLow, and from inputHigh to outputHigh. It is part of the LINK:: Guides/FluidCorpusManipulation##Fluid Corpus Manipulation Toolkit::. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/

The process will return a buffer with the same size and shape than the requested range.

STRONG::Threading::

By default, this UGen spawns a new thread to avoid blocking the server command queue, so it is free to go about with its business. For a more detailed discussion of the available threading and monitoring options, including the two undocumented Class Methods below (.processBlocking and .kr) please read the guide LINK::Guides/FluidBufMultiThreading::.

CLASSMETHODS::

METHOD:: process, processBlocking
	This is the method that calls for the scaling to be calculated on a given source buffer.

ARGUMENT:: server
	The server on which the buffer to be processed is allocated.

ARGUMENT:: source
The index of the buffer to use as the source material to be processed.

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:: destination
The index of the buffer to use as the destination for the processed material.

ARGUMENT:: inputLow
The low reference point of the input. it will be scaled to yield outputLow at the output

ARGUMENT:: inputHigh
The high reference point of the input. it will be scaled to yield outputHigh at the output

ARGUMENT:: outputLow
The output value when the input is inputLow

ARGUMENT:: outputHigh
The output value when the input is inputHigh

ARGUMENT:: clipping
Optional clipping of the input (and therefore of the output). 0 is none. 1 caps the lowest input at inputLow. 2 caps the highest input at inputHigh, 3 caps both input low and high value within the described range.

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 indices instance variables have been updated on the client side. The metric will be passed indices as an argument.

returns:: an instance of the processor


EXAMPLES::

code::
(
Routine{
    // make a buffer of known qualities
    b = Buffer.sendCollection(s,1.0.series(1.1,2.0));
    // and a destination buffer
    c = Buffer(s);
    // play with the scaling
    FluidBufScale.process(s, b, destination: c, inputLow: 0, inputHigh: 1, outputLow: 20, outputHigh:10).wait;
    // retrieve the buffer and enjoy the results.
	c.getn(0,10,{|x|x.round(0.000001).postln;})
}.play
)

// also works in multichannel - explore the following buffer

//process
(
Routine{
    b = Buffer.sendCollection(s,-10.0.series(-9,10.0).scramble,2);
    c = Buffer(s);
    s.sync;
    defer{b.plot(bounds:Rect(400,400,400,400)).plotMode_(\points).bounds};
    FluidBufScale.process(s, b, destination: c, inputLow: -20, inputHigh: 20, outputLow: 0, outputHigh:1).wait;
    //enjoy - same shape, different range
    defer{c.plot(bounds:Rect(800,400,400,400)).plotMode_(\points)};
}.play;
)

//also works with a subset of the input, resizing the output
(
Routine{
    b = Buffer.sendCollection(s,0.0.series(0.1,3.0).reshape(3,10).flop.flat,3);
    c = Buffer(s);
    s.sync;
    defer{b.plot(separately: true,bounds:Rect(400,400,400,400)).plotMode_(\points)};
    //process
    FluidBufScale.process(s, b, startFrame: 3,numFrames: 4,startChan: 1,numChans: 1, destination: c, inputLow: 0, inputHigh: 3, outputLow: 0, outputHigh:1).wait;
    //enjoy
    c.query;
    c.getn(0,4,{|x|x.postln;});
    defer{c.plot(separately: true,bounds:Rect(800,400,400,400)).plotMode_(\points)};
}.play
)
::