de.sciss.jcollider
Class UGen

java.lang.Object
  extended by de.sciss.jcollider.UGen
All Implemented Interfaces:
Constants, GraphElem
Direct Known Subclasses:
Control

public class UGen
extends java.lang.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
Todo:
a keyword constructor variant has been removed because it wasn't too convincing (well, keywords is just a concept totally unknown to java). however to make constructor calls shorter and more readable, some sort of keyword constructor should be re-invented.
Warning:
no rate checking is performed along the inputs

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
protected UGen(java.lang.String name, java.lang.Object rate, java.lang.Object[] outputRates, UGenInput[] inputs, int specialIndex)
          This constructor is used by SynthDef when building the UGen from a def file.
 
Method Summary
static GraphElem ar(java.lang.String name)
          Constructs a new audio rate UGen with zero arguments.
static GraphElem ar(java.lang.String name, GraphElem in1)
          Constructs a new audio rate UGen with one given argument
static GraphElem ar(java.lang.String name, GraphElem in1, GraphElem in2)
           
static GraphElem ar(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem ar(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem ar(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)
           
static GraphElem ar(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5, GraphElem in6)
           
static GraphElem ar(java.lang.String name, int numChannels)
          Constructs a new audio rate UGen with zero arguments and a required explict output channel number.
static GraphElem ar(java.lang.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(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2)
           
static GraphElem ar(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem ar(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem ar(java.lang.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(java.lang.String name)
           
static GraphElem dr(java.lang.String name, GraphElem in1)
           
static GraphElem dr(java.lang.String name, GraphElem in1, GraphElem in2)
           
static GraphElem dr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem dr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem dr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)
           
static GraphElem dr(java.lang.String name, int numChannels)
          "dr" stands for demand-rate
static GraphElem dr(java.lang.String name, int numChannels, GraphElem in1)
           
static GraphElem dr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2)
           
static GraphElem dr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem dr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem dr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)
           
 java.lang.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.
 java.lang.String getName()
          Returns the class name of the UGen.
 int getNumInputs()
          Returns the number of input arguments.
 int getNumOutputs()
           
 GraphElem getOutput(int idx)
           
 java.lang.Object getOutputRate(int channel)
          Returns the rate of one of the UGens output channels.
 java.lang.Object[] getOutputRates()
          Returns an array of the rates at which the individual output channels run.
 java.lang.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(java.lang.String name)
           
static GraphElem ir(java.lang.String name, GraphElem in1)
           
static GraphElem ir(java.lang.String name, GraphElem in1, GraphElem in2)
           
static GraphElem ir(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem ir(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem ir(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)
           
static GraphElem ir(java.lang.String name, int numChannels)
           
static GraphElem ir(java.lang.String name, int numChannels, GraphElem in1)
           
static GraphElem ir(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2)
           
static GraphElem ir(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem ir(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem ir(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)
           
static GraphElem kr(java.lang.String name)
           
static GraphElem kr(java.lang.String name, GraphElem in1)
           
static GraphElem kr(java.lang.String name, GraphElem in1, GraphElem in2)
           
static GraphElem kr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem kr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem kr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5)
           
static GraphElem kr(java.lang.String name, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4, GraphElem in5, GraphElem in6)
           
static GraphElem kr(java.lang.String name, int numChannels)
           
static GraphElem kr(java.lang.String name, int numChannels, GraphElem in1)
           
static GraphElem kr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2)
           
static GraphElem kr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3)
           
static GraphElem kr(java.lang.String name, int numChannels, GraphElem in1, GraphElem in2, GraphElem in3, GraphElem in4)
           
static GraphElem kr(java.lang.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(java.lang.String name,
               java.lang.Object rate,
               java.lang.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 java.lang.Object getRate()
Returns the rate at which this UGen is running

Returns:
either of kAudioRate, kControlRate, kDemandRate or kScalarRate

getOutputRates

public java.lang.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 java.lang.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 java.lang.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 java.lang.String dumpName()
Returns a string representation of the UGen.

Todo:
should report the operator name or unary/binary op

ar

public static GraphElem ar(java.lang.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:
java.lang.IllegalArgumentException - if the UGen cannot be found in the info dictionary, if the rate is not allowed for the ugen
java.lang.IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar

public static GraphElem ar(java.lang.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:
java.lang.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
java.lang.IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar

public static GraphElem ar(java.lang.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:
java.lang.IllegalArgumentException - if the UGen cannot be found in the info dictionary, if the rate is not allowed for the ugen
java.lang.IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar

public static GraphElem ar(java.lang.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:
java.lang.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
java.lang.IllegalStateException - if the UGens requires arguments which have not been provided and have no default values

ar

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

ar

public static GraphElem ar(java.lang.String name,
                           GraphElem in1,
                           GraphElem in2)

ar

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

ar

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

ar

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

ar

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

ar

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

ar

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

ar

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

kr

public static GraphElem kr(java.lang.String name,
                           int numChannels)

kr

public static GraphElem kr(java.lang.String name)

kr

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

kr

public static GraphElem kr(java.lang.String name,
                           GraphElem in1)

kr

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

kr

public static GraphElem kr(java.lang.String name,
                           GraphElem in1,
                           GraphElem in2)

kr

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

kr

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

kr

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

kr

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

kr

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

kr

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

kr

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

dr

public static GraphElem dr(java.lang.String name,
                           int numChannels)
"dr" stands for demand-rate


dr

public static GraphElem dr(java.lang.String name)

dr

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

dr

public static GraphElem dr(java.lang.String name,
                           GraphElem in1)

dr

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

dr

public static GraphElem dr(java.lang.String name,
                           GraphElem in1,
                           GraphElem in2)

dr

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

dr

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

dr

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

dr

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

dr

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

dr

public static GraphElem dr(java.lang.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(java.lang.String name,
                           int numChannels)

ir

public static GraphElem ir(java.lang.String name)

ir

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

ir

public static GraphElem ir(java.lang.String name,
                           GraphElem in1)

ir

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

ir

public static GraphElem ir(java.lang.String name,
                           GraphElem in1,
                           GraphElem in2)

ir

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

ir

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

ir

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

ir

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

ir

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

ir

public static GraphElem ir(java.lang.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