SuperCollider comes with a large collection of UGens, or unit generator functions. These are the building blocks of synthesizers, samplers, logical systems and everything else you can do with SC. In Overtone rather than having to define a function for each UGen, we have a large set of meta-data about all the UGens, and then we generate functions to create them. This file describes various aspects of the UGen meta-data system. If you want to add support for more UGens then you can probably just copy a similar type of UGen to get a sense for how the meta-data works, and then look here for details. Let us know if you run into any problems.
The ugen metadata can be found in the overtone.sc.ugen.metadata.* namespaces.
First all specs are loaded, and any spec that derives from another using the :extends property is merged with it's parent, the child properties overwriting the parent's.
Then comes mode initialization. All args are assigned a mode. If the arg does not have an explicitly statetd mode, then the arg-name-mode-map is searched. If there is no mode in the name map, then the default mode is :standard. At this time a boolean :expands? property is also added to each arg entry, depending on the mode of the arg.
Then an expansion spec is derived from the :expanded properties. It is just a vector of booleans and is assigned to the :expansion-spec property. This is later used during MCE
for each rate of each initilized ugen spec, a ugen function is defined.
Ugen functions have multiple versions to support different processing rates. For example, sin-osc:ar and sin-osc:kr product audio-rate and control-rate ugens. Using just sin-osc will also create an audio-rate ugen, except for ugens that only support :kr or :ir, in which case that is the default rate for the unqualified version.
when a ugen function is called. The args and the expansion-spec are passed to the expand function. Which then calls the ugen function potentially multiple times.
if a :check function with args [rate num-outs inputs spec] is defined, then it is called last before the ugen is added to the synth graph. If the check function returns a string then it is considered an error and an exception is thrown.
:name mandatory string; containing the sc lang UGen name
:derived optional string; containing the name of a spec to merge
with. Note that properties marked mandatory can also be
specified through derive. Properties in the spec
containing the derived statement take precedence over
properties in the "parent"
:args mandatory vector; containing the argument spec maps each of
which has the following form:
:name mandatorty string; the arg's name
:default optional; the default value if none given at synthdef time
note that there must not ever be any args with
defaults followed by args without them
:map a map that the arg will be looked up in
if a value exists for key arg then that
is used, else the arg is used
:mode optional symbol;
:not-expanded stops multi channel expansion on
thearg
:append-sequence the arg will not be expanded
and will be removed from it's position
in the inputs and concatenated to their
tail end. If there are several args in
this mode then they will be appended
in argument order.
:Append-sequence-set-num-outs
same as above, but also sets num-outs
via (count arg)
:num-outs will not be expanded & will be
removed from the input sequence,
and will determine the number
of output channels. SC arguments with
the name "numChannels" typically
use this mode
:done-action will not be expanded and will be
mapped to the integer code for the
action. Args named "doneAction" are
implicitly in this mode
:as-ar the argument is converted to audio rate
using the k2a ugen, if it is not already
audio rate. This is only done if the rate
of the ugen is :ar
:num-outs optional, the number of fixed outputs, defaults to 1 if
unspecified. It is unneeded if there is a :mode :num-outs
or if a :num-outs is defined in a map returned from :init
:init optional, a function which must take the args [rate args spec]
it should return a sequence of the new modified args or a
map with keys :args and :num-outs if they need to be manually
determined
:check optional, a function which takes the args
[rate num-outs inputs spec]
this is called after init (if specified) and should
return an error string or nil if no error
Can you improve this documentation? These fine people already did:
Jeff Rose, Dave Ray & Sam AaronEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close