net.beadsproject.beads.ugens
Class ZMap

java.lang.Object
  extended by net.beadsproject.beads.core.Bead
      extended by net.beadsproject.beads.core.UGen
          extended by net.beadsproject.beads.ugens.ZMap
All Implemented Interfaces:
DataBeadReceiver

public class ZMap
extends UGen
implements DataBeadReceiver

Performs a simple linear map from one range of values to another. Can be controlled by specifying the ranges from and to which to map, or by specifying a multiplier and shift (addition) value. Optionally, the signal can be clipped to the specified range.

Version:
0.9.5
Author:
Benito Crawford

Nested Class Summary
 
Nested classes/interfaces inherited from class net.beadsproject.beads.core.UGen
UGen.OutputInitializationRegime, UGen.OutputPauseRegime
 
Field Summary
 
Fields inherited from class net.beadsproject.beads.core.UGen
bufferSize, bufIn, bufOut, context, ins, outputInitializationRegime, outputPauseRegime, outs
 
Constructor Summary
ZMap(AudioContext context)
          Constructor for a 1-channel mapping object with default parameters (mapping [0,1] to [0,1] with no clipping, or multiplying by 1 and adding 0).
ZMap(AudioContext context, int channels)
          Constructor for a mapping object with the specified number of channels and the default parameters (mapping [0,1] to [0,1] with no clipping, or multiplying by 1 and adding 0).
 
Method Summary
 ZMap addThenMultiply(float preshift, float multiplier)
          A convenience method; specifies a linear map by adding first, then multiplying.
 void calculateBuffer()
          Called by the signal chain to update this UGen's ouput data.
 ZMap clear()
          Returns ZMap to its default setting: multiply by 1, add 0 (mapping [0,1] to [0,1] with no clipping).
 int getChannels()
          Gets the number of channels for this ZMap instance.
 boolean getClipping()
          Gets whether ZMap clips the incoming values to lie within the specified range.
 float getMultiplier()
          Gets the value that is multiplied by the signal.
 DataBead getParams()
          Gets a new DataBead filled with current parameter values.
 float getShift()
          Gets the value that is added to the signal after it has been multiplied by the multiplier.
 float getSourceMaximum()
          Gets the "maximum" expected value for the incoming signal.
 float getSourceMinimum()
          Gets the "minimum" expected value for the incoming signal.
 DataBead getStaticParams()
          Gets a new DataBead filled with current parameter values.
 float getTargetMaximum()
          Gets the "maximum" target value for the outgoing signal.
 float getTargetMinimum()
          Gets the "minimum" target value for the outgoing signal.
 ZMap multiplyThenAdd(float multiplier, float shift)
          Sets the multiplier and the shift.
 DataBeadReceiver sendData(DataBead db)
          Sets the ZMap parameters with a DataBead, using the following properties: "sourceMinimum", "sourceMaximum", "targetMinimum", "targetMaximum", "multiplier", "shift", "clipping".
 ZMap setClipping(boolean clip)
          Specifies whether ZMap clips the incoming values to lie within the specified range.
 ZMap setMultiplier(float multiplier)
          Sets the value that is multiplied by the signal.
 ZMap setRanges(float sourceMin, float sourceMax, float targetMin, float targetMax)
          Sets the source and target ranges for the signal mapping.
 ZMap setShift(float shift)
          Sets the value to add to the signal after it has been multiplied by the multiplier.
 ZMap setSourceMaximun(float sourceMax)
          Sets the "maximum" expected value for the incoming signal.
 ZMap setSourceMinimum(float sourceMin)
          Sets the "minimum" expected value for the incoming signal.
 ZMap setTargetMaximum(float targetMax)
          Sets the "maximum" value for the output signal.
 ZMap setTargetMinimum(float targetMin)
          Sets the "minimum" value for the output signal.
 
Methods inherited from class net.beadsproject.beads.core.UGen
addDependent, addInput, addInput, clearDependents, clearInputConnections, containsInput, crossfadeInput, getConnectedInputs, getContext, getEnvelopes, getIns, getNumberOfConnectedUGens, getNumberOfDependents, getOutBuffer, getOuts, getTimeTakenLastUpdate, getValue, getValue, getValueDouble, getValueDouble, initializeOuts, isTimerMode, isUpdated, noInputs, pause, printInBuffers, printInputList, printOutBuffers, removeAllConnections, removeConnection, removeDependent, setOutsToPause, setTimerMode, setValue, update, zeroIns, zeroOuts
 
Methods inherited from class net.beadsproject.beads.core.Bead
getKillListener, getName, isDeleted, isPaused, kill, message, messageReceived, setKillListener, setName, start, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ZMap

public ZMap(AudioContext context)
Constructor for a 1-channel mapping object with default parameters (mapping [0,1] to [0,1] with no clipping, or multiplying by 1 and adding 0).

Parameters:
context - The audio context.

ZMap

public ZMap(AudioContext context,
            int channels)
Constructor for a mapping object with the specified number of channels and the default parameters (mapping [0,1] to [0,1] with no clipping, or multiplying by 1 and adding 0).

Parameters:
context - The audio context.
channels - The number of channels.
Method Detail

calculateBuffer

public void calculateBuffer()
Description copied from class: UGen
Called by the signal chain to update this UGen's ouput data. Subclassses of UGen should implement the UGen's DSP perform routine here. In general this involves grabbing data from UGen.bufIn and putting data into UGen.bufOut in some way. UGen.bufIn and UGen.bufOut are 2D arrays of floats of the form float[numChannels][bufferSize]. The length of the buffers is given by UGen.bufferSize, and the number of channels of the input and output buffers are given by UGen.ins and UGen.outs respectively.

Specified by:
calculateBuffer in class UGen

getSourceMinimum

public float getSourceMinimum()
Gets the "minimum" expected value for the incoming signal.

Returns:
The "minimum" expected value.

setSourceMinimum

public ZMap setSourceMinimum(float sourceMin)
Sets the "minimum" expected value for the incoming signal.

Parameters:
sourceMin - The "minimum" expected value.
Returns:
This ZMap instance.

getSourceMaximum

public float getSourceMaximum()
Gets the "maximum" expected value for the incoming signal.

Returns:
The "maximum" expected value.

setSourceMaximun

public ZMap setSourceMaximun(float sourceMax)
Sets the "maximum" expected value for the incoming signal.

Parameters:
sourceMax - The "maximum" expected value.
Returns:
This ZMap instance.

getTargetMinimum

public float getTargetMinimum()
Gets the "minimum" target value for the outgoing signal.

Returns:
The "minimum" target value.

setTargetMinimum

public ZMap setTargetMinimum(float targetMin)
Sets the "minimum" value for the output signal.

Parameters:
targetMin - The "minimum" output value.
Returns:
This ZMap instance.

getTargetMaximum

public float getTargetMaximum()
Gets the "maximum" target value for the outgoing signal.

Returns:
The "maximum" target value.

setTargetMaximum

public ZMap setTargetMaximum(float targetMax)
Sets the "maximum" value for the output signal.

Parameters:
targetMax - The "maximum" output value.
Returns:
This ZMap instance.

setRanges

public ZMap setRanges(float sourceMin,
                      float sourceMax,
                      float targetMin,
                      float targetMax)
Sets the source and target ranges for the signal mapping.

Parameters:
sourceMin - The "minimum" incoming value.
sourceMax - The "maximum" incoming value.
targetMin - The "minimum" outgoing value.
targetMax - The "maximum" outgoing value.
Returns:
This ZMap instance.

clear

public ZMap clear()
Returns ZMap to its default setting: multiply by 1, add 0 (mapping [0,1] to [0,1] with no clipping).

Returns:
This ZMap instance.

multiplyThenAdd

public ZMap multiplyThenAdd(float multiplier,
                            float shift)
Sets the multiplier and the shift.

Parameters:
multiplier - The value to multiply by the incoming signal.
shift - The value to then add to the result.
Returns:
This ZMap instance.

addThenMultiply

public ZMap addThenMultiply(float preshift,
                            float multiplier)
A convenience method; specifies a linear map by adding first, then multiplying.

Parameters:
preshift - The value to first add to the signal.
multiplier - The value then multiplied by the result.
Returns:
This ZMap instance.

getMultiplier

public float getMultiplier()
Gets the value that is multiplied by the signal.

Returns:
The multiplier.

setMultiplier

public ZMap setMultiplier(float multiplier)
Sets the value that is multiplied by the signal.

Parameters:
multiplier - The multiplier
Returns:
This ZMap instance.

getShift

public float getShift()
Gets the value that is added to the signal after it has been multiplied by the multiplier.

Returns:
The shift value.

setShift

public ZMap setShift(float shift)
Sets the value to add to the signal after it has been multiplied by the multiplier.

Parameters:
shift - The amount to add.
Returns:
This ZMap instance.

getClipping

public boolean getClipping()
Gets whether ZMap clips the incoming values to lie within the specified range.

Returns:
Whether ZMap clips.

setClipping

public ZMap setClipping(boolean clip)
Specifies whether ZMap clips the incoming values to lie within the specified range.

Parameters:
clip - Whether to clip.
Returns:
This ZMap instance.

getChannels

public int getChannels()
Gets the number of channels for this ZMap instance.

Returns:
The number of channels.

sendData

public DataBeadReceiver sendData(DataBead db)
Sets the ZMap parameters with a DataBead, using the following properties: "sourceMinimum", "sourceMaximum", "targetMinimum", "targetMaximum", "multiplier", "shift", "clipping".

Specified by:
sendData in interface DataBeadReceiver
Parameters:
db - The parameter DataBead.
Returns:
This ZMap instance.

getParams

public DataBead getParams()
Gets a new DataBead filled with current parameter values.

Returns:
The new parameter DataBead.

getStaticParams

public DataBead getStaticParams()
Gets a new DataBead filled with current parameter values.

Returns:
The new parameter DataBead.