Permalink
Browse files

add start of ugen metadata machinery doc

  • Loading branch information...
samaaron committed Jul 21, 2011
1 parent 9b9cf9e commit d5692c562062439e7656f7409c6802ebc752fb2b
Showing with 37 additions and 0 deletions.
  1. +37 −0 docs/ugen-metadata.md
View
@@ -0,0 +1,37 @@
+The ugen metadata is converted to a suite of functions which are called within the context of a synth definition. For example, consider the following synth design:
+
+ (defsynth foo [] (sin-osc 440))
+
+Here, we're explicitly calling one ugen fn - `sin-osc`. This function knows how to correctly handle and manipulate its param list so that the correct synthdef is created as part of the compilation process. What kinds of manipulation is necessary? Well, for starters, each ugen has a number of default params which can be omitted. Also, Overtone allows you to use ordered params, keyword params and even a mix of the two. So you could also create a basic sine wave at 440Hz with the following:
+
+ (defsynth foo [] (sin-osc :freq 440))
+
+Both the above synth designs are also equivalent to:
+
+ (defsynth foo [] (sin-osc :freq 440 :phase 0))
+
+As the default value for phase is 0. The ugen function clearly needs to know how to take these args and munge them about correctly so that a correct synthdef data structure can be created. This work takes place in the namespace overtone.sc.ugen.
+
+So, how are these functions created and what they do?
+
+The story starts with the ugen metadata. A set of namespaces describing the properties of each and every scsynth ugen. Here's the metadata for the sine wave we were using above:
+
+ {:name "SinOsc",
+ :args [{:name "freq", :default 440.0 :doc "frequency in Hertz"}
+ {:name "phase", :default 0.0 :doc "phase offset or modulator in radians"}],
+ :doc "sine table lookup oscillator
+
+ Note: This is the same as Osc except that the table has already been fixed as a sine table of 8192 entries."}
+
+Here we have three basic keys: `:name`, `:args` and `:doc`. The name `SinOsc` is the exact scsynth name in camelCase. This is the name we need to use within the synthdef. However, it's not necessarily very idiomatic clojure to use camelCase, so we convert it to the hyphenated `sin-osc`. The logic for this is in the fn `overtone-ugen-name`.
+
+The ugen spec metadata ens up in the var `UGEN-SPECS` which is polpulated by the fn `load-ugen-specs` which gathers the raw spec metadata found in the namespaces `overtone.sc.ugen.~@UGEN-NAMESPACES` and then passes these specs through the fn `derive-ugen-specs` which resolves the inheritence tree (which allows a given ugen to extend another thus inheriting its parent's information). Finally the derived specs are then individually passed through the fn `decorate-ugen-spec` which does all of the fancy work.
+
+* `with-rates`
+* `with-categories`
+* `with-expands`
+* `with-init-fn`
+* `with-default-rate`
+* `with-fn-names`
+* `doc/with-arg-defaults`
+* `doc/with-full-doc`

0 comments on commit d5692c5

Please sign in to comment.