ddf.minim.ugens
Class UGen

java.lang.Object
  ddf.minim.ugens.UGen

Direct Known Subclasses:

ADSR, Balance, BitCrush, Constant, Damp, Delay, FilePlayer, Gain, GranulateRandom, GranulateSteady, IIRFilter, Line, LiveInput, Midi2Hz, Multiplier, Noise, Oscil, Pan, Reciprocal, Summer, WaveShaper

public abstract class UGen
extends java.lang.Object

The UGen class is an abstract class which is intended to be the basis for all UGens in Minim. UGen is short for Unit Generator, which is simply something either generates a sample value, or transforms the sample value produced by another UGen. Because 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 you signal path is and you can state it 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 activate() 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.

Author:

Damien Di Fede, Anderson Mills

Nested Class Summary

static class	UGen.InputType This enum is used to specify the InputType of the UGenInput
class	UGen.UGenInput This inner class, UGenInput, is used to connect the output of other UGens to this UGen

Constructor Summary

UGen()
Constructor for a UGen.

Method Summary

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.
float[]	getLastValues() Return the last values generated by this UGen.
void	patch(AudioOutput output) Patch the output of this UGen to the provided AudioOuput.
UGen	patch(UGen.UGenInput connectToInput) Connect the output of this UGen to a specific input of connecToUGen.
UGen	patch(UGen connectToUGen) Connect the output of this UGen to the first input of connectToUGen.
void	printInputs() Prints all inputs connected to this UGen (for debugging)
protected void	removeInput(UGen input) If you need to do something specific when something is unpatched from your UGen, you can override this method.
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	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 output) Unpatch the output of this output from the provided AudioOutput.
void	unpatch(UGen connectToUGen) Remove this UGen as the input to the connectToUGen.

Methods inherited from class java.lang.Object

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

Constructor Detail

UGen

public UGen()

Constructor for a UGen.

Method Detail

patch

public final UGen patch(UGen connectToUGen)

Connect the output of this UGen to the first input of connectToUGen. Doing so will chain these two UGens together, causing them to generate sound at the same time when the end of chain is patched to an AudioOutput.

Parameters:

connectToUGen - The UGen to connect to.

Returns:

connectToUGen 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 input of connecToUGen.

Parameters:

connectToInput -

Returns:

cennectToInput.getOuterUGen()

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 -

patch

public final void patch(AudioOutput output)

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:

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

unpatch

public final void unpatch(AudioOutput output)

Unpatch the output of this output from the provided AudioOutput. This causes this UGen and all UGens patched into it to stop generation audio if AudioOutput is not potched somewhere else in this chain.

Parameters:

output - The AudioOutput this UGen should be disconnected from.

unpatch

public final void unpatch(UGen connectToUGen)

Remove this UGen as the input to the connectToUGen.

Parameters:

connectToUGen -

removeInput

protected void removeInput(UGen input)

If you need to do something specific when something is unpatched from your UGen, you can override this method.

Parameters:

input -

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.

sampleRate

public final float sampleRate()

Returns the 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 - the sample rate this UGen should generate at.

printInputs

public void printInputs()

Prints all inputs connected to this UGen (for debugging)