UGen (LOCI Javadocs 0-SNAPSHOT API)

java.lang.Object
- de.sciss.jcollider.UGen

All Implemented Interfaces:

Constants, GraphElem

Direct Known Subclasses:

Control
```
public class UGen
extends Object
implements Constants, GraphElem
```
The client side represenation of a unit generator. Unlike SClang, there are no subclasses for all the different ugens (few exceptions, such as Control), therefore to construct a ugen graph requires you to make successive calls to the static constructor methods provided by this class. See SynthDef and JColliderDemo for examples of how to construct a graph.
When you use the static constructor methods of UGen, the class relies on the UGen database to be loaded into UGenInfo. Please see the UGenInfo doc for details about this database.
While some methods like array( ... ) would better fit into the GraphElemArray class, they have been included here, simply because it's shorter to write UGen.array( ... ) and it gives your code a more homogeneous and pathological look.
To access a single output of a multi-output UGen, use either the getOutput or getChannel method. To create controls, use the separate Control class.

Version:

0.35, 19-Sep-09

Author:

Hanns Holger Rutz

Field Summary
- Fields inherited from interface de.sciss.jcollider.Constants
  kAddAfter, kAddBefore, kAddReplace, kAddToHead, kAddToTail, kAudioRate, kControlRate, kDemandRate, kDoneFree, kDoneFreeAll, kDoneFreeAllPred, kDoneFreeAllSucc, kDoneFreeGroup, kDoneFreePausePred, kDoneFreePauseSucc, kDoneFreePred, kDoneFreePredGroup, kDoneFreePredGroupDeep, kDoneFreeSucc, kDoneFreeSuccGroup, kDoneFreeSuccGroupDeep, kDoneNothing, kDonePause, kDumpBoth, kDumpHex, kDumpOff, kDumpText, kHeaderAIFF, kHeaderIRCAM, kHeaderNeXT, kHeaderRaw, kHeaderWAVE, kSampleALaw, kSampleDouble, kSampleFloat, kSampleInt16, kSampleInt24, kSampleInt32, kSampleInt8, kSampleMuLaw, kScalarRate

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`UGen(String name, Object rate, Object[] outputRates, UGenInput[] inputs, int specialIndex)` This constructor is used by `SynthDef` when building the UGen from a def file.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static GraphElem`	`ar(String name)` Constructs a new audio rate UGen with zero arguments.
`static GraphElem`	`ar(String name, GraphElem in1)` Constructs a new audio rate UGen with one given argument
`static GraphElem`	`ar(String name, GraphElem in1, GraphElem in2)`
`static GraphElem`	`ar(String name, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`ar(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`ar(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`static GraphElem`	`ar(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5, GraphElem in6)`
`static GraphElem`	`ar(String name, int numChannels)` Constructs a new audio rate UGen with zero arguments and a required explict output channel number.
`static GraphElem`	`ar(String name, int numChannels, GraphElem in1)` Constructs a new audio rate UGen with one given argument and an explicit number of output channels.
`static GraphElem`	`ar(String name, int numChannels, GraphElem in1, GraphElem in2)`
`static GraphElem`	`ar(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`ar(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`ar(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`static GraphElem`	`array(GraphElem g1, GraphElem g2)` Assembles two graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods
`static GraphElem`	`array(GraphElem g1, GraphElem g2, GraphElem g3)` Assembles three graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods
`static GraphElem`	`array(GraphElem g1, GraphElem g2, GraphElem g3, GraphElem g4)` Assembles four graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods
`static GraphElem`	`array(GraphElem g1, GraphElem g2, GraphElem g3, GraphElem g4, GraphElem g5)` Assembles five graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods
`UGenInput[]`	`asUGenInputs()`
`static GraphElem`	`dr(String name)`
`static GraphElem`	`dr(String name, GraphElem in1)`
`static GraphElem`	`dr(String name, GraphElem in1, GraphElem in2)`
`static GraphElem`	`dr(String name, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`dr(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`dr(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`static GraphElem`	`dr(String name, int numChannels)` "dr" stands for demand-rate
`static GraphElem`	`dr(String name, int numChannels, GraphElem in1)`
`static GraphElem`	`dr(String name, int numChannels, GraphElem in1, GraphElem in2)`
`static GraphElem`	`dr(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`dr(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`dr(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`String`	`dumpName()` Returns a string representation of the UGen.
`UGenChannel`	`getChannel(int ch)`
`UGenInput`	`getInput(int index)` Returns the UGen's input at the given index.
`UGenInput[]`	`getInputs()` Returns an array of the UGen's inputs.
`String`	`getName()` Returns the class name of the UGen.
`int`	`getNumInputs()` Returns the number of input arguments.
`int`	`getNumOutputs()`
`GraphElem`	`getOutput(int idx)`
`Object`	`getOutputRate(int channel)` Returns the rate of one of the UGens output channels.
`Object[]`	`getOutputRates()` Returns an array of the rates at which the individual output channels run.
`Object`	`getRate()` Returns the rate at which this UGen is running
`int`	`getSpecialIndex()` Returns the so-called special index of the UGen.
`static GraphElem`	`ir(float value)` A shorthand method for creating a constant in the ugen graph.
`static GraphElem`	`ir(String name)`
`static GraphElem`	`ir(String name, GraphElem in1)`
`static GraphElem`	`ir(String name, GraphElem in1, GraphElem in2)`
`static GraphElem`	`ir(String name, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`ir(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`ir(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`static GraphElem`	`ir(String name, int numChannels)`
`static GraphElem`	`ir(String name, int numChannels, GraphElem in1)`
`static GraphElem`	`ir(String name, int numChannels, GraphElem in1, GraphElem in2)`
`static GraphElem`	`ir(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`ir(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`ir(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`static GraphElem`	`kr(String name)`
`static GraphElem`	`kr(String name, GraphElem in1)`
`static GraphElem`	`kr(String name, GraphElem in1, GraphElem in2)`
`static GraphElem`	`kr(String name, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`kr(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`kr(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`static GraphElem`	`kr(String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5, GraphElem in6)`
`static GraphElem`	`kr(String name, int numChannels)`
`static GraphElem`	`kr(String name, int numChannels, GraphElem in1)`
`static GraphElem`	`kr(String name, int numChannels, GraphElem in1, GraphElem in2)`
`static GraphElem`	`kr(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)`
`static GraphElem`	`kr(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)`
`static GraphElem`	`kr(String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)`
`protected void`	`setSpecialIndex(int idx)` This is called by `SynthDef` when assembling controls.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UGen

protected UGen(String name,
               Object rate,
               Object[] outputRates,
               UGenInput[] inputs,
               int specialIndex)

This constructor is used by SynthDef when building the UGen from a def file. Do not use this method yourself.

Method Detail

getRate
```
public Object getRate()
```
Returns the rate at which this UGen is running

Returns:

either of kAudioRate, kControlRate, kDemandRate or kScalarRate

getOutputRates
```
public Object[] getOutputRates()
```
Returns an array of the rates at which the individual output channels run. I know of no UGen any of whose outputs have a rate different from the UGen rate.

getOutputRate
```
public Object getOutputRate(int channel)
```
Returns the rate of one of the UGens output channels. I know of no UGen any of whose outputs have a rate different from the UGen rate.

getInputs
```
public UGenInput[] getInputs()
```
Returns an array of the UGen's inputs.

getInput
```
public UGenInput getInput(int index)
```
Returns the UGen's input at the given index. Note that for UGens constructed with a variable length array argument, this argument is expanded to separate individual arguments. For example for Out, each element of the channelsArray argument is a separate input with a separate index (as you would expect from the binary compiled synth def format).

getSpecialIndex
```
public int getSpecialIndex()
```
Returns the so-called special index of the UGen. This is kind of an extra internal static parameter. Special indices are used by BinaryOpUGen and UnaryOpUGen to specify the mathematical operator, and by Control to specify the index in the control name table. Note that this index is invalid for Control until the graph has been constructed by SynthDef.

setSpecialIndex
```
protected void setSpecialIndex(int idx)
```
This is called by SynthDef when assembling controls. Do not call this method directly. To create unary and binary operator ugens, simply construct them with their operator name and the ugen factory will set the right index itself. So to create a multiplying binary ugen, you will call:
```
        UGen.ar( "*", firstUGen, secondUGen );
        
```
and not
```
        UGen myBin = UGen.ar( "BinaryOpUGen", firstUGen, secondUGen );
        myBin.setSpecialIndex(  2 );
        
```

getNumInputs
```
public int getNumInputs()
```
Returns the number of input arguments. Arrays are expanded, so an Out UGen with three input channels will report 4 (three inputs plus bus parameter).

getNumOutputs
```
public int getNumOutputs()
```
Specified by:

getNumOutputs in interface GraphElem

getOutput
```
public GraphElem getOutput(int idx)
```
Specified by:

getOutput in interface GraphElem

asUGenInputs
```
public UGenInput[] asUGenInputs()
```
Specified by:

asUGenInputs in interface GraphElem

getChannel

public UGenChannel getChannel(int ch)

getName
```
public String getName()
```
Returns the class name of the UGen. In the case of unary and binary op ugens, this will report "UnaryOpUGen" and "BinaryOpUGen" and not their operators. To get the operator names look up the UGen in the UGenInfo dictionary.

See Also:

UGenInfo.infos

dumpName
```
public String dumpName()
```
Returns a string representation of the UGen.

ar
```
public static GraphElem ar(String name,
                           int numChannels)
```
Constructs a new audio rate UGen with zero arguments and a required explict output channel number. This method should only be used for UGens that require the explicit setting of the number of output channels, such as LocalIn.ar.
This method can also be used for UGens with more than zero arguments, if the info dictionary contains default values for the missing arguments. An example is BufRd which actually has four arguments for bufNum, phase, loop and interolation, but specifies defaults for all of them (bufNum 0, phase zero, loop 1, interpolation 2).

Parameters:

name - either ugen class name or alias name (for unary/binary op)

numChannels - number of output channels to create

Throws:

IllegalArgumentException - if the UGen cannot be found in the info dictionary, if the rate is not allowed for the ugen

IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar
```
public static GraphElem ar(String name)
```
Constructs a new audio rate UGen with zero arguments.
This method can also be used for UGens with more than zero arguments, if the info dictionary contains default values for the missing arguments. An example is SinOsc which actually has two arguments for frequency and phase, but both of them have default values (440 hertz, zero degrees phase).

Parameters:

name - either ugen class name or alias name (for unary/binary op)

Throws:

IllegalArgumentException - if the UGen cannot be found in the info dictionary, if the rate is not allowed for the ugen, or if the UGen requires the explicit specification of the number of output channels

IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar
```
public static GraphElem ar(String name,
                           int numChannels,
                           GraphElem in1)
```
Constructs a new audio rate UGen with one given argument and an explicit number of output channels. This method should only be used for UGens that require the explicit setting of the number of output channels, such as PanAz.ar.
This method can also be used for UGens with more than one argument (e.g. PanAz), if the info dictionary contains default values for the missing arguments. For example, PanAz has five arguments, the first one being the input signal which needs to specified, but the other ones having default values (pos 0.0, level 1.0, width 2.0, orientation 0.5).

Parameters:

name - either ugen class name or alias name (for unary/binary op)

numChannels - number of output channels to create

in1 - first input argument

Throws:

IllegalArgumentException - if the UGen cannot be found in the info dictionary, if the rate is not allowed for the ugen

IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar
```
public static GraphElem ar(String name,
                           GraphElem in1)
```
Constructs a new audio rate UGen with one given argument
This method can also be used for UGens with more than one argument (e.g. Osc), if the info dictionary contains default values for the missing arguments.

Parameters:

name - either ugen class name or alias name (for unary/binary op)

in1 - first input argument

Throws:

IllegalArgumentException - if the UGen cannot be found in the info dictionary, if the rate is not allowed for the ugen, or if the UGen requires the explicit specification of the number of output channels

IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar

public static GraphElem ar(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2)

ar

public static GraphElem ar(String name,
                           GraphElem in1,
                           GraphElem in2)

ar

public static GraphElem ar(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

ar

public static GraphElem ar(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

ar

public static GraphElem ar(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

ar

public static GraphElem ar(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

ar

public static GraphElem ar(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

ar

public static GraphElem ar(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

ar

public static GraphElem ar(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5,
                           GraphElem in6)

kr

public static GraphElem kr(String name,
                           int numChannels)

kr

public static GraphElem kr(String name)

kr

public static GraphElem kr(String name,
                           int numChannels,
                           GraphElem in1)

kr

public static GraphElem kr(String name,
                           GraphElem in1)

kr

public static GraphElem kr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2)

kr

public static GraphElem kr(String name,
                           GraphElem in1,
                           GraphElem in2)

kr

public static GraphElem kr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

kr

public static GraphElem kr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

kr

public static GraphElem kr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

kr

public static GraphElem kr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

kr

public static GraphElem kr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

kr

public static GraphElem kr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

kr

public static GraphElem kr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5,
                           GraphElem in6)

dr

public static GraphElem dr(String name,
                           int numChannels)

"dr" stands for demand-rate

dr

public static GraphElem dr(String name)

dr

public static GraphElem dr(String name,
                           int numChannels,
                           GraphElem in1)

dr

public static GraphElem dr(String name,
                           GraphElem in1)

dr

public static GraphElem dr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2)

dr

public static GraphElem dr(String name,
                           GraphElem in1,
                           GraphElem in2)

dr

public static GraphElem dr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

dr

public static GraphElem dr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

dr

public static GraphElem dr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

dr

public static GraphElem dr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

dr

public static GraphElem dr(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

dr

public static GraphElem dr(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

ir
```
public static GraphElem ir(float value)
```
A shorthand method for creating a constant in the ugen graph. This is equivalent to new Constant( value ).

ir

public static GraphElem ir(String name,
                           int numChannels)

ir

public static GraphElem ir(String name)

ir

public static GraphElem ir(String name,
                           int numChannels,
                           GraphElem in1)

ir

public static GraphElem ir(String name,
                           GraphElem in1)

ir

public static GraphElem ir(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2)

ir

public static GraphElem ir(String name,
                           GraphElem in1,
                           GraphElem in2)

ir

public static GraphElem ir(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

ir

public static GraphElem ir(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3)

ir

public static GraphElem ir(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

ir

public static GraphElem ir(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4)

ir

public static GraphElem ir(String name,
                           int numChannels,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

ir

public static GraphElem ir(String name,
                           GraphElem in1,
                           GraphElem in2,
                           GraphElem in3,
                           GraphElem in4,
                           GraphElem in5)

array
```
public static GraphElem array(GraphElem g1,
                              GraphElem g2)
```
Assembles two graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods

Parameters:

g1 - first graph element such as a UGen, Constant, UGenChannel or GraphElemArray

g2 - second graph element

Returns:

array'ed elements

array
```
public static GraphElem array(GraphElem g1,
                              GraphElem g2,
                              GraphElem g3)
```
Assembles three graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods

Parameters:

g1 - first graph element

g2 - second graph element

g3 - third graph element

Returns:

array'ed elements

array
```
public static GraphElem array(GraphElem g1,
                              GraphElem g2,
                              GraphElem g3,
                              GraphElem g4)
```
Assembles four graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods

Parameters:

g1 - first graph element

g2 - second graph element

g3 - third graph element

g4 - fourth graph element

Returns:

array'ed elements

array
```
public static GraphElem array(GraphElem g1,
                              GraphElem g2,
                              GraphElem g3,
                              GraphElem g4,
                              GraphElem g5)
```
Assembles five graph elements (such as UGens, or Constants) into one array which in turn can be used for multichannel expansion when passed as an argument to one of the UGen constructor methods

Parameters:

g1 - first graph element

g2 - second graph element

g3 - third graph element

g4 - fourth graph element

g5 - fifth graph element

Returns:

array'ed elements

Class UGen

Field Summary

Fields inherited from interface de.sciss.jcollider.Constants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

UGen

Method Detail

getRate

getOutputRates

getOutputRate

getInputs

getInput

getSpecialIndex

setSpecialIndex

getNumInputs

getNumOutputs

getOutput

asUGenInputs

getChannel

getName

dumpName

ar

ar

ar

ar

ar

ar

ar

ar

ar

ar

ar

ar

ar

kr

kr

kr

kr

kr

kr

kr

kr

kr

kr

kr

kr

kr

dr

dr

dr

dr

dr

dr

dr

dr

dr

dr

dr

dr

ir

ir

ir

ir

ir

ir

ir

ir

ir

ir

ir

ir

ir

array

array

array

array