de.sciss.jcollider
Class UGenInfo

java.lang.Object
  extended by de.sciss.jcollider.UGenInfo
All Implemented Interfaces:
Constants, java.lang.Comparable

public class UGenInfo
extends java.lang.Object
implements Constants, java.lang.Comparable

As stated elsewhere, it was decided to not implement separate classes for the different unit generators in JCollider. Instead there is one monolithic UGen class. To facilitate the visual represenation of UGens and to allow syntax checking and automatic default value assignment, the UGenInfo class was created which keeps records of all known ugen "classes". The database needs to be read in once explictly, usually you will do this once your programme launches. The database is merged with the JCollider library .jar file (ugendefs.xml, along with the document type descriptor ugendefs.dtd), and can be easily edited as to provide more ugens newly added to the supercollider application. This database file would also naturally be the place to put new attributes such as icon files if you want to build a graphic synthesis system, or links to help file and such.

Once you have initialized the database, using the readDefinitions method, you don't deal with UGenInfo any more, since the UGen constructor methods will query the database automatically. This in turn means, you cannot use UGen.ar( ... ) for example, unless the database has been initialized. However there is nothing wrong with using JCollider without the UGen constructors (for example using only pre-stored synth defs), and in this case you may skip the database initialization, saving some startup time.

Version:
0.32, 25-Feb-08
Author:
Hanns Holger Rutz
See Also:
readDefinitions(), UGen.ar( String )

Nested Class Summary
static class UGenInfo.Arg
          Descriptor for a ugen input argument.
 
Field Summary
 UGenInfo.Arg[] args
          Array of the input argument definitions
 java.lang.String className
          Name of the ugen class
static java.util.Map infos
          This field contains a read-only map which maps String (ugen class names and alias names such as the unary/binary operator names) to UGenInfo elements).
static int OUTPUT_ARG
          Value for outputType : the ugen has a variable number which needs to be specified explictly when constructing the ugen (example : PanAz)
static int OUTPUT_ARRAYSIZE
          Value for outputType : the ugen has a variable number of outputs depending on the length of it's array argument (example : Demand)
static int OUTPUT_FIXED
          Value for outputType : the ugen has a fixed number of outputs
 float outputMul
          A tricky workaround invented for LagControl until i recognized that this isn't a real ugen.
 int outputType
          Defines how the number of outputs is determined.
 int outputVal
          For fixed output ugens, the number of outputs.
 java.util.Set rates
          Set of all allowed rates at which the ugen can run
 java.util.Map specials
          Maps special names (Strings) to specialIndex values (Integers).
 
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
 
Method Summary
 int compareTo(java.lang.Object o)
           
 java.lang.String getArgNameForInput(UGen ugen, int argIdx)
          Returns the name for one of the ugens inputs.
 java.lang.String getDisplayName(UGen ugen)
          Returns a string ready to display to the user.
 int getNumOutputs(int numArgs, int pre)
          Given the number of instantiating arguments, returns the number of output channels the ugen will have.
 void printOn(java.io.PrintStream out)
          Prints a textual representation of this dataset onto the given stream
static void readBinaryDefinitions()
          Reads in the ugen definition database from a binary resource inside the libraries jar file (ugendefs.bin).
static void readDefinitions()
          Reads in the ugen definition database from a text resource inside the libraries jar file (ugendefs.xml).
static void writeBinaryDefinitions(java.io.File path)
          Writes the infos out as a binary file that can be read in again using the readBinaryDefinitions method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

infos

public static java.util.Map infos
This field contains a read-only map which maps String (ugen class names and alias names such as the unary/binary operator names) to UGenInfo elements).

For example UGenInfo.infos.get( "PlayBuf" ) will return the dataset for the PlayBuf ugen, UGenInfo.infos.get( "reciprocal" ) will return the dataset for the UnaryOpUGen ugen (there is only one dataset for all the operators).


OUTPUT_FIXED

public static final int OUTPUT_FIXED
Value for outputType : the ugen has a fixed number of outputs

See Also:
Constant Field Values

OUTPUT_ARG

public static final int OUTPUT_ARG
Value for outputType : the ugen has a variable number which needs to be specified explictly when constructing the ugen (example : PanAz)

See Also:
Constant Field Values

OUTPUT_ARRAYSIZE

public static final int OUTPUT_ARRAYSIZE
Value for outputType : the ugen has a variable number of outputs depending on the length of it's array argument (example : Demand)

See Also:
Constant Field Values

className

public final java.lang.String className
Name of the ugen class


args

public final UGenInfo.Arg[] args
Array of the input argument definitions


rates

public final java.util.Set rates
Set of all allowed rates at which the ugen can run

See Also:
Constants.kAudioRate, Constants.kControlRate

specials

public final java.util.Map specials
Maps special names (Strings) to specialIndex values (Integers). For example, the BinaryOpUGen will have mappings like "absdif" -> Integer( 38 ) etc. For UGens which do not deal with special indices, this field is null


outputType

public final int outputType
Defines how the number of outputs is determined. One of FIXED, ARG or ARRAYSIZE


outputVal

public final int outputVal
For fixed output ugens, the number of outputs. For ARG type ugens, the default number of outputs (-1 if no defaults exist). For ARRAYSIZE type ugens, the argument index of the array argument to use.

Warning:
for now, arrays are only allowed as the last argument of the ugen. no more than one array is allowed per ugen. as of september 2005, all known supercollider ugens fulfill this requirement

outputMul

public final float outputMul
A tricky workaround invented for LagControl until i recognized that this isn't a real ugen. This could be used to multiply the array size for ARRAYSIZE output type ugens by a constant, say two or one half. So for now, ignore it, it will have the value of one for all ugens. This field may be deleted in one of the next versions

Method Detail

compareTo

public int compareTo(java.lang.Object o)
Specified by:
compareTo in interface java.lang.Comparable

getDisplayName

public java.lang.String getDisplayName(UGen ugen)
Returns a string ready to display to the user. This will return the ugens class name or the operator name for unary/binary ops

Todo:
should find a way to present controls better to the user with the different control names accessible

getArgNameForInput

public java.lang.String getArgNameForInput(UGen ugen,
                                           int argIdx)
Returns the name for one of the ugens inputs. This can be used to visualize the ugen, and furthermore to create a keyword constructor for the ugen (to be done).


getNumOutputs

public int getNumOutputs(int numArgs,
                         int pre)
Given the number of instantiating arguments, returns the number of output channels the ugen will have. For fixed type ugens, returns simply the outputVal, for array type ugens, calculates the number of outputs from numArgs, for ugens that require an explicit number-of-channels argument, returns pre (if given) or the default value outputVal) (if specified).

Parameters:
numArgs - the number of arguments which will be used to instantiate the ugen
pre - pre-specified number of outputs (or -1)
Returns:
the number of output channels or -1 if this method is unable to determine the number of channels (missing pre argument)

printOn

public void printOn(java.io.PrintStream out)
Prints a textual representation of this dataset onto the given stream


readDefinitions

public static void readDefinitions()
                            throws java.io.IOException
Reads in the ugen definition database from a text resource inside the libraries jar file (ugendefs.xml). Call this method once before using the database, i.e. before constructing UGens or showing a synth def diagram.

When this method returns, the database is available from the static infos field.

A much faster (around 20 times) way is to convert the xml file int a binary file, by calling writeBinaryDefinitions afterwards (or run JCollider with the --bindefs option).

The binary variant of this method is readBinaryDefinitions.

Throws:
java.io.IOException - if the definitions file couldn't be read. this should never happen if you don't touch the library. however, if you modify the xml file as to include new ugens, this error may occur if the xml file is malformed
See Also:
infos, readBinaryDefinitions(), writeBinaryDefinitions( File )

writeBinaryDefinitions

public static void writeBinaryDefinitions(java.io.File path)
                                   throws java.io.IOException
Writes the infos out as a binary file that can be read in again using the readBinaryDefinitions method. You will need to move the resulting file into the resources folder and re-jar the library in order to use readBinaryDefinitions.

Throws:
java.io.IOException
See Also:
readDefinitions(), readBinaryDefinitions()

readBinaryDefinitions

public static void readBinaryDefinitions()
                                  throws java.io.IOException
Reads in the ugen definition database from a binary resource inside the libraries jar file (ugendefs.bin). Call this method once before using the database, i.e. before constructing UGens or showing a synth def diagram.

When this method returns, the database is available from the static infos field.

To update the ugen definitions, edit the ugendefs.xml file and run JCollider with the --bindefs option. Move the resulting binary file into the resources folder and re-jar the library.

Reading the binary file instead of the xml file is a lot faster (around 20 times).

Throws:
java.io.IOException - if the definitions file couldn't be read.
See Also:
infos, readDefinitions(), writeBinaryDefinitions( File )