ddf.minim

Class UGen

java.lang.Object

ddf.minim.UGen

Direct Known Subclasses:

Abs, ADSR, Balance, BitCrush, Bypass, Constant, Damp, Delay, EnvelopeFollower, FilePlayer, Flanger, Gain, GranulateRandom, GranulateSteady, Line, LiveInput, Midi2Hz, MoogFilter, Multiplier, Noise, Oscil, Pan, Reciprocal, Sampler, Summer, TickRate, Vocoder, WaveShaper

public abstract class UGen
extends java.lang.Object

The UGen class is an abstract class which provides the basis for all UGens in Minim. UGen is short for Unit Generator, which is simply something that either generates a sample value, or transforms the sample value produced by another UGen. Since everything is a UGen, there is a common interface for patching things together. For instance, you might have a line of code that looks like this:

osc.patch( filter ).patch( adsr ).patch( output );

You can read this code left to right. It says that the output of an Oscil should be sent through a filter (perhaps a LowPass) and the output of the filter should be sent through an ADSR envelope, which should then be sent to an AudioOutput. It's incredibly clear what the signal path is and it can be stated concisely.

UGens might also have UGenInputs. Oscil, for example, has a UGenInput called frequency. UGenInputs can be patched to, just like UGens, which means you might have a line of code like this:

line.patch( osc.frequency );

This says that a Line UGen should control the value of the Oscil's frequency. You may have created a Line that changes it's value from 440 to 880 over 2 seconds. The audible result, when you call activate() on the Line, is that the Oscil will sweep upwards in frequency and then hold there until you activate the Line again. All of this control happens on a sample-by-sample basis, which means (hopefully) no clicks and pops. For a list of all UGens included with Minim, see the UGens package doc.

Author:

Damien Di Fede, Anderson Mills

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UGen.InputType This enum is used to specify the InputType of the UGenInput.
class	UGen.UGenInput A UGenInput represents parameter of the UGen that can be controlled by other UGens by patching to it.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	UGen() Constructor for a UGen.

Method Summary

Modifier and Type	Method and Description
protected UGen.UGenInput	addAudio()
protected UGen.UGenInput	addControl()
protected UGen.UGenInput	addControl(float initialValue)
protected void	addInput(UGen input) If you want to do something other than the default behavior when your UGen is patched to, you can override this method in your derived class.
int	channelCount() Returns the number of channels this UGen has been configured to generate.
protected void	channelCountChanged() This method is only called when setChannelCount results in the channel count of this UGen actually changing.
float[]	getLastValues() Return the last values generated by this UGen.
void	patch(AudioOutput audioOutput) Patch the output of this UGen to the provided AudioOuput.
UGen	patch(UGen.UGenInput connectToInput) Connect the output of this UGen to a specific UGenInput of a UGen.
UGen	patch(UGen connectToUGen) Send the output of this UGen to another UGen, UGenInput, or AudioOutput.
void	printInputs() Prints all inputs connected to this UGen (for debugging)
protected void	removeInput(UGen input) When a UGen is unpatched from this UGen, removeInput is called.
float	sampleRate() Returns the sample rate of this UGen.
protected void	sampleRateChanged() Override this method in your derived class to receive a notification when the sample rate of your UGen has changed.
void	setChannelCount(int numberOfChannels) Let this UGen know how many channels of audio you will be asking it for.
void	setSampleRate(float newSampleRate) Set the sample rate for this UGen.
void	tick(float[] channels) Generates one sample frame for this UGen.
protected abstract void	uGenerate(float[] channels) Implement this method when you extend UGen.
void	unpatch(AudioOutput audioOutput) Unpatch this UGen from an AudioOutput or other UGen.
void	unpatch(UGen fromUGen) Remove this UGen as an input of fromUGen.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UGen

protected UGen()

Constructor for a UGen.

Method Detail

patch

public final UGen patch(UGen connectToUGen)

Send the output of this UGen to another UGen, UGenInput, or AudioOutput. For instance, if an Oscil is patched to an AudioOutput, you will hear the sound it generates. If a FilePlayer is patched to a Delay, then the delay effect will be applied to the sound generated by the FilePlayer.

Parameters:

connectToUGen - The UGen to patch to.

Returns:

When patching to a UGen or UGenInput, the UGen being patched to is returned so that you can chain patch calls. For example:

 sine.patch( gain ).patch( out );
 

patch

public final UGen patch(UGen.UGenInput connectToInput)

Connect the output of this UGen to a specific UGenInput of a UGen.

Parameters:

connectToInput - The UGenInput to patch to.

Returns:

the UGen that owns connectToInput

patch

public final void patch(AudioOutput audioOutput)

Patch the output of this UGen to the provided AudioOuput. Doing so will immediately result in this UGen and all UGens patched into it to begin generating audio.

Parameters:

audioOutput - The AudioOutput you want to connect this UGen to.

addInput

protected void addInput(UGen input)

If you want to do something other than the default behavior when your UGen is patched to, you can override this method in your derived class. Summer, for instance, keeps a list of all the UGens that have been patched to it, so that it can tick them and sum the results when it uGenerates.

Parameters:

input - the UGen to add as an input

unpatch

public final void unpatch(AudioOutput audioOutput)

Unpatch this UGen from an AudioOutput or other UGen. This causes this UGen and all UGens patched into it to stop generating audio if they are not patched to an AudioOuput somewhere else in the chain.

Parameters:

audioOutput - The AudioOutput this UGen should be disconnected from.

unpatch

public final void unpatch(UGen fromUGen)

Remove this UGen as an input of fromUGen.

Parameters:

fromUGen - The UGen to unpatch from.

removeInput

protected void removeInput(UGen input)

When a UGen is unpatched from this UGen, removeInput is called. If you've written an UGen subclass that needs to know when this happens or has special handling of input removal, you can override this method. See the implementation of Summer for an example of why you might need to do this.

Parameters:

input - the UGen to remove as an input to this UGen

tick

public final void tick(float[] channels)

Generates one sample frame for this UGen.

Parameters:

channels - An array that represents one sample frame. To generate a mono signal, pass an array of length 1, if stereo an array of length 2, and so on. How a UGen deals with multi-channel sound will be implementation dependent.

uGenerate

protected abstract void uGenerate(float[] channels)

Implement this method when you extend UGen. It will be called when your UGen needs to generate one sample frame of audio. It is expected that you will assign values to the array and not simply modify the existing values. In the case where you write a UGen that takes audio input and modifies it, the pattern to follow is to have the first UGenInput you create be your audio input and then in uGenerate you will use the getLastValues method of your audio UGenInput to retrieve the audio you want to modify, which you will then modify however you need to, assigning the result to the values in channels.

Parameters:

channels - an array representing one sample frame.

getLastValues

public final float[] getLastValues()

Return the last values generated by this UGen. This will most often be used by sub-classes when pulling data from their inputs.

Returns:

float[]: array containing the most recent sample frame this UGen generated

sampleRate

public final float sampleRate()

Returns the sample rate of this UGen.

Returns:

float: the current sample rate of this UGen

sampleRateChanged

protected void sampleRateChanged()

Override this method in your derived class to receive a notification when the sample rate of your UGen has changed. You might need to do this to recalculate sample rate dependent values, such as the step size for an oscillator.

setSampleRate

public final void setSampleRate(float newSampleRate)

Set the sample rate for this UGen.

Parameters:

newSampleRate - float, the sample rate this UGen should generate at.

setChannelCount

public void setChannelCount(int numberOfChannels)

Let this UGen know how many channels of audio you will be asking it for. This will be called automatically when a UGen is patched to an AudioOuput and propagated to all UGenInputs of type AUDIO.

Parameters:

numberOfChannels - how many channels of audio you will be generating with this UGen

channelCount

public int channelCount()

Returns the number of channels this UGen has been configured to generate.

Returns:

int: how many channels of audio this UGen will generate

channelCountChanged

protected void channelCountChanged()

This method is only called when setChannelCount results in the channel count of this UGen actually changing. Override this function in sub-classes of UGen if you need to reconfigure things when the channel count changes.

printInputs

public void printInputs()

Prints all inputs connected to this UGen (for debugging)

addControl

protected UGen.UGenInput addControl()

addControl

protected UGen.UGenInput addControl(float initialValue)

addAudio

protected UGen.UGenInput addAudio()