net.beadsproject.beads.core

Class UGen

java.lang.Object

net.beadsproject.beads.core.Bead

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

Nested Classes

Modifier and Type	Class and Description
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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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()