UGenInfo (LOCI Javadocs 0-SNAPSHOT API)

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

All Implemented Interfaces:

Constants, Comparable
```
public class UGenInfo
extends Object
implements Constants, 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 representation 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

Nested Classes
Modifier and Type Class and Description

static class UGenInfo.Arg
Descriptor for a ugen input argument.

Nested Classes
Modifier and Type	Class and Description
`static class`	`UGenInfo.Arg` Descriptor for a ugen input argument.

Field Summary

Fields
Modifier and Type	Field and Description
`UGenInfo.Arg[]`	`args` Array of the input argument definitions
`String`	`className` Name of the ugen class
`static 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.
`Set`	`rates` Set of all allowed rates at which the ugen can run
`Map`	`specials` Maps special names (`String`s) to specialIndex values (`Integer`s).

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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`compareTo(Object o)`
`String`	`getArgNameForInput(UGen ugen, int argIdx)` Returns the name for one of the ugens inputs.
`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(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(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 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 String className
```
    Name of the ugen class
  - args
```
public final UGenInfo.Arg[] args
```
    Array of the input argument definitions
  - rates
```
public final Set rates
```
    Set of all allowed rates at which the ugen can run
    
    See Also:
    
    Constants.kAudioRate, Constants.kControlRate
  - specials
```
public final 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. 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(Object o) Specified by: compareTo in interface Comparable getDisplayName public 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 getArgNameForInput public 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(PrintStream out) Prints a textual representation of this dataset onto the given stream readDefinitions public static void readDefinitions() throws 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: 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(File path) throws 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: IOException See Also: readDefinitions(), readBinaryDefinitions() readBinaryDefinitions public static void readBinaryDefinitions() throws 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: IOException - if the definitions file couldn't be read. See Also: infos, readDefinitions(), writeBinaryDefinitions( File )

Class UGenInfo

Nested Class Summary

Field Summary

Fields inherited from interface de.sciss.jcollider.Constants

Method Summary

Methods inherited from class java.lang.Object

Field Detail

infos

OUTPUT_FIXED

OUTPUT_ARG

OUTPUT_ARRAYSIZE

className

args

rates

specials

outputType

outputVal

outputMul

Method Detail

compareTo

getDisplayName

getArgNameForInput

getNumOutputs

printOn

readDefinitions

writeBinaryDefinitions

readBinaryDefinitions