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, Clicker, Clock, DelayLine, DelayTrigger, Envelope, Filter, Function, Gain, MonoPlug, Mult, Noise, OscillatorBank, PanMonoToStereo, PanStereoToStereo, RangeLimiter, Recorder, RTInput, SamplePlayer, ScalingMixer, Segmenter, Static, WavePlayer

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

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  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 clearInputConnections()
          Clear all of this UGen's input connections.
 AudioContext getContext()
          Gets the AudioContext used by this UGen.
 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 getOuts()
          Gets the number of outputs.
 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).
 boolean noInputs()
          Determines whether this UGen has no UGens connected to its inputs.
 void pause(boolean paused)
          Pauses/un-pauses the current UGen.
 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.
 void removeDependent(UGen dependent)
          Removes the specified UGen from this UGen's dependency list.
 void setValue(float value)
          Sets the value of #bufOut[0][0].
 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.


bufOut

protected float[][] bufOut
The buffer that will be grabbed by other UGens connected to this one.


bufferSize

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

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.


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.

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.

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.

removeAllConnections

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

Parameters:
sourceUGen - the UGen to disconnect.

clearInputConnections

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


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.

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.

setValue

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

Parameters:
value - the new value.

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:
true - if paused.
See Also:
Bead.pause(boolean)