net.beadsproject.beads.core
Class UGen

java.lang.Object
  extended by net.beadsproject.beads.core.Bead
      extended by net.beadsproject.beads.core.UGen
Direct Known Subclasses:
Add, AudioSegmenter, Change, Clicker, Clip, Clock, Compressor, CrossFade, CrossoverFilter, DelayEvent, Delta, Drain, Envelope, Function, Gain, Glide, IIRFilter, Maximum, Minimum, MonoPlug, MouseResponder, Mult, NBitsConverter, Noise, OscillatorBank, Panner, Phasor, Plug, PolyLimit, RandomPWM, RangeLimiter, RecordToSample, RMS, SamplePlayer, ScalingMixer, SignalReporter, Spatial, Static, TapIn, TapOut, Throughput, TrapezoidWave, UGenChain, WavePlayer, WaveShaper, ZeroCross, ZMap

public abstract class UGen
extends Bead

A UGen is the main base class for implementing signal generation and processing units (unit generators). UGens can have any number of audio input and output channels, which adopt the audio format of the AudioContext used to construct the UGen. Any UGen output can be connected to any other UGen input, using addInput(int, UGen, int) (or use addInput(UGen) to connect all outputs of one UGen to all inputs of another). UGens are constructed using an AudioContext to determine the correct buffer size for audio processing. By connecting a UGen's output to another UGen's input the source UGen is automatically added to a call chain that propagates through subsequent UGens from the root UGen of the AudioContext. UGens that do not have outputs (such as Clock) can be added manually to the call chain using addDependent(UGen) from any UGen that is part of the call chain (such as the root UGen of the AudioContext).

UGen inherits the Bead.start(), Bead.kill() and Bead.pause(boolean) behaviour, and messaging system from Bead. Importantly, when UGens are paused, they cease audio processing, and when they are killed, they are automatically removed from any audio chains. This allows for very easy removal of elements from the call chain.

The method calculateBuffer() must be implemented by subclasses of UGen that actually do something. Each UGen has two 2D arrays of floats, bufIn, bufOut, holding the current input and output audio buffers (this is stored in the form float[numChannels][bufferSize]). The goal of a calculateBuffer() method, therefore, is to fill bufOut with appropriate data for the current audio frame. Examples can be found in the source code of classes in the net.beadsproject.beads.ugens package.

Author:
ollie

Nested Class Summary
protected static class UGen.OutputInitializationRegime
          Used to determine how a UGen sets its outputs up before calculateBuffer() is called.
protected static class UGen.OutputPauseRegime
           
 
Field Summary
protected  int bufferSize
          The buffer size.
protected  float[][] bufIn
          The buffer used internally to store input data.
protected  float[][] bufOut
          The buffer that will be grabbed by other UGens connected to this one.
protected  AudioContext context
          The AudioContext used by this buffer.
protected  int ins
          The number of inputs.
protected  UGen.OutputInitializationRegime outputInitializationRegime
           
protected  UGen.OutputPauseRegime outputPauseRegime
           
protected  int outs
          The number of outputs.
 
Constructor Summary
UGen(AudioContext context)
          Create a new UGen from the given AudioContext but with no inputs or outputs.
UGen(AudioContext context, int outs)
          Create a new UGen from the given AudioContext with no inputs and the given number of outputs.
UGen(AudioContext context, int ins, int outs)
          Create a new UGen from the given AudioContext with the given number of inputs and outputs.
 
Method Summary
 void addDependent(UGen dependent)
          Adds a UGen to this UGen's dependency list, causing the dependent UGen to get updated when this one does.
 void addInput(int inputIndex, UGen sourceUGen, int sourceOutputIndex)
          Connect a specific output from another UGen to a specific input of this UGen.
 void addInput(UGen sourceUGen)
          Connect another UGen's outputs to the inputs of this UGen.
abstract  void calculateBuffer()
          Called by the signal chain to update this UGen's ouput data.
 void clearDependents()
          Clears the list of dependent UGens.
 void clearInputConnections()
          Clear all of this UGen's input connections.
 boolean containsInput(UGen ugen)
          Checks if this UGen has the given UGen plugged into it.
 void crossfadeInput(UGen source, UGen destination, float crossoverTime)
          Performs a crossfade from one UGen (which must already be connected) to another.
 java.util.Set<UGen> getConnectedInputs()
          Returns a flat Set (i.e.
 AudioContext getContext()
          Gets the AudioContext used by this UGen.
 java.util.Map<java.lang.String,UGen> getEnvelopes()
          Gets the envelopes controlling this UGen (using Reflection).
 int getIns()
          Gets the number of inputs.
 int getNumberOfConnectedUGens(int index)
          Gets the number of UGens connected at the specified input index of this UGen.
 int getNumberOfDependents()
          Gets the number of dependent UGens.
 float[] getOutBuffer(int i)
          Gets an entire output buffer from a specific channel at a given time step.
 int getOuts()
          Gets the number of outputs.
 long getTimeTakenLastUpdate()
           
 float getValue()
          Gets the value of the buffer, assuming that the buffer only has one value.
 float getValue(int i, int j)
          Gets a specific specified value from the output buffer, with indices i (channel) and j (offset into buffer).
 double getValueDouble()
          Gets the value as a double.
 double getValueDouble(int i, int j)
          Gets the value as a double.
protected  void initializeOuts()
           
 boolean isTimerMode()
           
 boolean isUpdated()
          Checks if this UGen has been updated in the current timeStep.
 boolean noInputs()
          Determines whether this UGen has no UGens connected to its inputs.
 void pause(boolean paused)
          Pauses/un-pauses the current UGen.
 void printInBuffers()
          Prints the contents of the input buffers to System.out.
 void printInputList()
          Prints a list of UGens connected to this UGen's inputs to System.out.
 void printOutBuffers()
          Prints the contents of the output buffers to System.out.
 void removeAllConnections(UGen sourceUGen)
          Disconnects the specified UGen from this UGen at all inputs.
 boolean removeConnection(int inputChannel, UGen sourceUGen, int sourceOutputChannel)
          Disconnects the connection from the specified UGen to this one.
 void removeDependent(UGen dependent)
          Removes the specified UGen from this UGen's dependency list.
protected  void setOutsToPause()
           
 void setTimerMode(boolean timerMode)
           
 void setValue(float value)
          Sets the value of bufOut.
 void update()
          Updates the UGen.
 void zeroIns()
          Sets the input buffers to zero.
 void zeroOuts()
          Sets the output buffers to zero.
 
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
 

Field Detail

context

protected AudioContext context
The AudioContext used by this buffer.


ins

protected int ins
The number of inputs.


outs

protected int outs
The number of outputs.


bufIn

protected float[][] bufIn
The buffer used internally to store input data. Array has dimensions [channels][bufferSize].


bufOut

protected float[][] bufOut
The buffer that will be grabbed by other UGens connected to this one. Array has dimensions [channels][bufferSize].


bufferSize

protected int bufferSize
The buffer size. This is specified by AudioContext.


outputInitializationRegime

protected UGen.OutputInitializationRegime outputInitializationRegime

outputPauseRegime

protected UGen.OutputPauseRegime outputPauseRegime
Constructor Detail

UGen

public UGen(AudioContext context)
Create a new UGen from the given AudioContext but with no inputs or outputs.

Parameters:
context - AudioContext to use.

UGen

public UGen(AudioContext context,
            int outs)
Create a new UGen from the given AudioContext with no inputs and the given number of outputs.

Parameters:
context - AudioContext to use.
outs - number of outputs.

UGen

public UGen(AudioContext context,
            int ins,
            int outs)
Create a new UGen from the given AudioContext with the given number of inputs and outputs.

Parameters:
context - AudioContext to use.
ins - number of inputs.
outs - number of outputs.
Method Detail

getContext

public AudioContext getContext()
Gets the AudioContext used by this UGen.

Returns:
the AudioContext.

getIns

public int getIns()
Gets the number of inputs.

Returns:
number of inputs.

getOuts

public int getOuts()
Gets the number of outputs.

Returns:
number of outputs.

zeroOuts

public void zeroOuts()
Sets the output buffers to zero.


zeroIns

public void zeroIns()
Sets the input buffers to zero.


setOutsToPause

protected void setOutsToPause()

initializeOuts

protected void initializeOuts()

update

public void update()
Updates the UGen. If the UGen is paused or has already been updated at this time step (according to the AudioContext) then this method does nothing. If the UGen does update, it will firstly propagate the update() call up the call chain using pullInputs(), and secondly, call its own calculateBuffer() method.


printInputList

public void printInputList()
Prints a list of UGens connected to this UGen's inputs to System.out.


addInput

public void addInput(UGen sourceUGen)
Connect another UGen's outputs to the inputs of this UGen. If the number of outputs is greater than the number of inputs then the extra outputs are not connected. If the number of inputs is greater than the number of outputs then the outputs are cycled to fill all inputs. If multiple UGens are connected to any one input then the outputs from those UGens are summed on their way into the input.

Parameters:
sourceUGen - the UGen to connect to this UGen.

addInput

public void addInput(int inputIndex,
                     UGen sourceUGen,
                     int sourceOutputIndex)
Connect a specific output from another UGen to a specific input of this UGen.

Parameters:
inputIndex - the input of this UGen to connect to.
sourceUGen - the UGen to connect to this UGen.
sourceOutputIndex - the output of the connecting UGen with which to make the connection.

crossfadeInput

public void crossfadeInput(UGen source,
                           UGen destination,
                           float crossoverTime)
Performs a crossfade from one UGen (which must already be connected) to another. Only works if you

Parameters:
source - the UGen to crossfade away from (assumed to already be connected), will be disconnected once cross-fade is over.
destination - the UGen to crossfade towards.
crossoverTime - the time taken.

addDependent

public void addDependent(UGen dependent)
Adds a UGen to this UGen's dependency list, causing the dependent UGen to get updated when this one does. This is used to add UGens without outputs (such as Clock to the call chain. As will UGens in the regular call chain, if a dependent UGen gets killed, this UGen will remove it from its dependency list.

Parameters:
dependent - the dependent UGen.

removeDependent

public void removeDependent(UGen dependent)
Removes the specified UGen from this UGen's dependency list.

Parameters:
dependent - UGen to remove.

clearDependents

public void clearDependents()
Clears the list of dependent UGens.


getNumberOfConnectedUGens

public int getNumberOfConnectedUGens(int index)
Gets the number of UGens connected at the specified input index of this UGen.

Parameters:
index - index of input to inspect.
Returns:
number of UGen outputs connected to that input.

getNumberOfDependents

public int getNumberOfDependents()
Gets the number of dependent UGens.

Returns:
number of dependent UGens.

containsInput

public boolean containsInput(UGen ugen)
Checks if this UGen has the given UGen plugged into it.

Parameters:
ugen - the UGen to test.
Returns:
true if the given UGen is plugged into this UGen.

getConnectedInputs

public java.util.Set<UGen> getConnectedInputs()
Returns a flat Set (i.e. no copies) of all the UGens connected to the inputs of this one.

Returns:
set of UGens

getEnvelopes

public java.util.Map<java.lang.String,UGen> getEnvelopes()
Gets the envelopes controlling this UGen (using Reflection).

Returns:
Map of envelope names to envelopes.

removeAllConnections

public void removeAllConnections(UGen sourceUGen)
Disconnects the specified UGen from this UGen at all inputs.

Parameters:
sourceUGen - the UGen to disconnect.

removeConnection

public boolean removeConnection(int inputChannel,
                                UGen sourceUGen,
                                int sourceOutputChannel)
Disconnects the connection from the specified UGen to this one.

Parameters:
inputChannel - The channel of this UGen to check.
sourceUGen - The UGen to disconnect.
sourceOutputChannel - The channel of the source UGen.
Returns:
True if a connection was removed; false otherwise.

clearInputConnections

public void clearInputConnections()
Clear all of this UGen's input connections.


printInBuffers

public void printInBuffers()
Prints the contents of the input buffers to System.out.


printOutBuffers

public void printOutBuffers()
Prints the contents of the output buffers to System.out.


noInputs

public boolean noInputs()
Determines whether this UGen has no UGens connected to its inputs.

Returns:
true if this UGen has no UGens connected to its inputs, false otherwise.

calculateBuffer

public abstract void calculateBuffer()
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 bufIn and putting data into bufOut in some way. bufIn and bufOut are 2D arrays of floats of the form float[numChannels][bufferSize]. The length of the buffers is given by bufferSize, and the number of channels of the input and output buffers are given by ins and outs respectively.


getValue

public float getValue(int i,
                      int j)
Gets a specific specified value from the output buffer, with indices i (channel) and j (offset into buffer).

Parameters:
i - channel index.
j - buffer frame index.
Returns:
value of specified sample.

getOutBuffer

public float[] getOutBuffer(int i)
Gets an entire output buffer from a specific channel at a given time step. Note that output buffers are swapped every time step, so this float[] will only be valid between the time this UGen in updated and the beginning of the next update cycle. It's your job to make sure you're calling this at a sensible time.

Parameters:
i - the output channel.
Returns:
a buffer of output data.

getValue

public float getValue()
Gets the value of the buffer, assuming that the buffer only has one value. This is mainly a convenience method for use with Static type UGens. It is equivalent to getValue(0, 0).

Returns:
the value.

getValueDouble

public double getValueDouble(int i,
                             int j)
Gets the value as a double. Only overridden by certain classes that generate info in doubles. Gets a specific specified value from the output buffer, with indices i (channel) and j (offset into buffer).

Parameters:
i - channel index.
j - buffer frame index.
Returns:
value of specified sample.

getValueDouble

public double getValueDouble()
Gets the value as a double. Only overridden by certain classes that generate info in doubles. Gets the value of the buffer, assuming that the buffer only has one value. This is mainly a convenience method for use with Static type UGens. It is equivalent to getValue(0, 0).

Returns:
the value.

setValue

public void setValue(float value)
Sets the value of bufOut. This is mainly a convenience method for use with Static and Envelope type UGens.

Parameters:
value - the new value.

isUpdated

public boolean isUpdated()
Checks if this UGen has been updated in the current timeStep.

Returns:
true if the UGen has been updated in the current timeStep.

pause

public void pause(boolean paused)
Pauses/un-pauses the current UGen. When paused, a UGen does not perform an audio calculations and does not respond to messages.

Overrides:
pause in class Bead
Parameters:
paused - is true if paused.
See Also:
Bead.pause(boolean)

isTimerMode

public boolean isTimerMode()

setTimerMode

public void setTimerMode(boolean timerMode)

getTimeTakenLastUpdate

public long getTimeTakenLastUpdate()