Gamma: synth1 deconstructed
Disclaimer
The official website for Gamma is http://mat.ucsb.edu/gamma.
This is NOT an official gamma website. Everything HERE is just random scribblings by people trying to understand gamma--and might be inaccurate, out of date, or just plain wrong. You have been warned.
In S12 MAT276AI, JoAnn Kuchera-Morin provided the following example file for doing synthesis with basic sine waves:
This page is an attempt to deconstruct and understand the code in this file.
First, let's examine the main. I've omitted many of the similar s.add lines—the ones I've left are enough to explain this part of the code.
int main(){
Scheduler s;
s.add<SineEnv>( 0 ).set(6.5, 260, 0.3, 1, 2);
s.add<SineEnv>( 0 ).set(3.5, 510, 0.3, 1, 2);
s.add<SineEnv>( 3.5).set(3.0, 233, 0.3, 1, 2);
s.add<SineEnv>( 3.5).set(4.5, 340, 0.3, 1, 2);
// ...
s.add<SineEnv>( 60.0).set(3.5, 230, 0.3, 1, 2);
AudioIO io(256, 44100., s.audioCB, &s);
Sync::master().spu(io.fps());
io.start();
printf("\nPress 'enter' to quit...\n"); getchar();
}
First, the line:
Scheduler s;
Simple enough: this creates an object of type Scheduler. A deeper look reveals that a Scheduler is a special case of a more general object called a Process. The type Scheduler is defined in Gamma/Scheduler.h as a subclass of Process:
class Scheduler : public Process{
...
And a Process is defined earlier in that same file as inheriting from Node3<Process> (a node that has a parent, a child, and right sibling of type <Process>:
// This defines a block-rate processing node in the audio graph
class Process : public Node3<Process>{
...
What do we do with a Schedule object? In this example, we do two things:
- we use the add<T> method on it (which, in practice, at least in this example, adds notes that are going to be played)
- we pass its
audioCBmember to the constructor of anAudioIOobject, which is going to be used to playback the sound.
Let's take a closer look at both of those methods.
Contents
[hide]The add() method of Scheduler
Inside the file Gamma/Scheduler.h, we find this curious definition for add():
template <class AProcess, class A>
AProcess& add(const A& a){
AProcess * v = new AProcess(a);
cmdAdd(v); return *v;
}
This method has two template parameters, class AProcess, and class A. Compare this with the concrete invocation of this method in synth1.cpp:
s.add<SineEnv>( 0 ).set(6.5, 260, 0.3, 1, 2);
What we see is that the actual value of AProcess is SineEnv, and the actual value of A is the integer literal 0. Thus, inside the invocation of add, three things happen:
- we create a new instance of AProcess (in this case SineEnv), passing in the parameter that is the integer literal 0
- in this case, that represents the point on the timeline at which the note should be played).
- A pointer to that new instance of SineEnv is passed to the method cmdAdd
- A reference to that new object is returned as the result of the function call, which allows chaining of additional methods, such as the set() method we see in the line of code from synth1.cpp.
In fact, inside Gamma/Scheduler.h, we see that there are many similar templates for the add method, each with a different number of parameters. Thus, add is a very general function of the scheduler that can be used to add anything that is a Process, and any number of parameters can be passed into that Process objects constructor:
template <class AProcess, class A, class B, class C>
AProcess& add(const A& a, const B& b, const C& c){
AProcess * v = new AProcess(a,b,c);
cmdAdd(v); return *v;
}
template <class AProcess, class A, class B, class C, class D>
AProcess& add(const A& a, const B& b, const C& c, const D& d){
AProcess * v = new AProcess(a,b,c,d);
cmdAdd(v); return *v;
}
template <class AProcess, class A, class B, class C, class D, class E>
AProcess& add(const A& a, const B& b, const C& c, const D& d, const E& e){
AProcess * v = new AProcess(a,b,c,d,e);
cmdAdd(v); return *v;
}
...
What does cmdAdd(v) do?
But what about this cmdAdd(v) line of code? What does it do? Well, the answer lies in src/Scheduler.cpp... and what seems to be happening is some kind of "deferred add" into a data structure.
void Scheduler::cmdAdd(Process * v){
pushCommand(Command::ADD_FIRST_CHILD, this, v);
}
void Scheduler::pushCommand(Command::Type type, Process * object, Process * oth\
er){
other->mDeletable=true;
Command c = { type, object, other };
mAddCommands.push(c);
}
mAddCommands is a queue of add operations that can either be ADD_FIRST_CHILD or ADD_LAST_CHILD, and which add operations into a linked data structure. From the comments, it appears that the reason that the operations are deferred like this has to do with threading priorities: the operations are enqueued in a low priority thread, and are acted on (i.e. the nodes really get added into the tree) in a high priority thread by the method updateTree().
But, we're getting a little lost in the weeds. Some of this will turn out to be important later, but for now, let's pop back up and look at another part of our synth1.cpp main code: the AudioIO object.
The AudioIO object
The definition of the AudioIO object is defined in Gamma/AudioIO.h this way:
/// Audio input/output streaming.
/// This is a wrapper around the PortAudio v1.9 library.
class AudioIO : public AudioIOData {
public:
...
So, AudioIO inherits from AudioIOData, which is also defined in the same file, and is a base class:
/// Audio data to be sent to callback
class AudioIOData {
public:
One of the overloaded operators defined on AudioIOData is the () operator—this is a rather ideosyncratic C++ idiom that, if you are not accustomed to it, can seem quite odd. That is, you see an instance of an object followed by () and you say, "what the heck does that mean?"
And the answer is, someone Alice In Wonderland-like, "It means whatever we want it to mean", or more precisely, it means whatever the () operators was overloaded to mean. For example, for class AudioIOData, the () operator means:
/// Iterate frame counter, returning true while more frames
bool operator()() const { return (++mFrame)<framesPerBuffer(); }
This operator is overloaded, however, in AudioIO, and the definition is in src/AudioIO.cpp
void AudioIO::operator()(){ frame(0); if(callback) callback(*this); }
So, now that we know that AudioIO is an abstraction of an Audio Device, a wrapper around PortAudio, and inherits from AudioIOData, what are the parameters to the constructor invocation we see in synth1.cpp?
AudioIO io(256, 44100., s.audioCB, &s);
Here's the constructor:
AudioIO(
int framesPerBuf=64, double framesPerSec=44100.0,
void (* callback)(AudioIOData &) = 0, void * userData = 0,
int outChans = 2, int inChans = 0 );
Thus we see that the 256 is the framesPerBuf (whatever that means), the 44100 is the framesPerSec (though we coudl have guessed that, the callback is a function (more on this in a minute) and we are passing in a pointer to our Scheduler through a void * (probably to be passed to that callback function.)
And, we see that we are accepting the default of 2 output channels, and 0 input channels.
So, now what about this callback? Well what we are passing in is the audioCB function of our scheduler object. What does that function do?
Well, first of all, note that it is a static function. So it has no this object. Here's the definition in Gamma/Scheduler.h:
static void audioCB(AudioIOData& io){
Scheduler& s = io.user<Scheduler>();
s.update(io);
}
Ah, so now (sigh) we need to see what the "user" method of an AudioIOData is (and a templated method at that!) Why here it is, from Gamma/AudioIO.h:
template<class UserDataType>
UserDataType& user() const { return *(static_cast<UserDataType *>(mUser)); }
My best guess as to what that's doing is: return us the value of the mUser attribute of this AudioIOData object (which is, by the way, a void *), but cast it to whatever type we pass into the Template. (So, one would assume, it has BETTER BE the type we're assuming.)
So, in short, the first line of code grabs a reference to the Scheduler that the AudioIOData object happens to be storing a pointer to inside its mUser private data member. Then, it calls the update() method of that scheduler object, passing in the very same AudioIOData object.
And what does s.update(io) do?
The update() method of the scheduler (called from inside the audioCB() function
Here's the declaration of the update() method in Gamma/Scheduler.h:
template<class UserDataType>
UserDataType& user() const { return *(static_cast<UserDataType *>(mUser\
)); }
And here is the definition from inside src/Scheduler.cpp:
void Scheduler::update(AudioIOData& io){
updateTree();
updateControlFuncs(io.secondsPerBuffer());
// traverse tree
Process * v = this;
do{
v = v->update(this, io);
} while(v);
// put nodes marked as 'done' into free list
updateFreeList();
}
So updateTree() is the function that moves all of the deferred adds into the tree (see our earlier discussion of the Low Priority Thread and the High Priority Thread).
Then updateControlFuncs() is called to update a list of Func objects (we'll save that for another time, since it doesn't appear any of those are playing any visible role in the synth1.cpp file.)
Then, we are traversing the tree, calling another function called update, but this time one with two parameters. Presumably, each time that function is called, v gets updated until it is eventually null:
The version of update with two parameters is declared in Gamma/AudioIO.h:
/// Call processing algorithm, onProcessAudio()
Process * update(const Process * top, AudioIOData& io);
And defined in src/AudioIO.cpp:
Process * Process::update(const Process * top, AudioIOData& io){
double dt = io.secondsPerBuffer();
int frame = 0;
if(mDelay >= dt){
mDelay-=dt;
return nextBreadth(top);
}
else if(mDelay > 0){ // 0 < delay <= delta
frame = mDelay * io.framesPerSecond();
mDelay=0;
if(frame >= io.framesPerBuffer()) return nextBreadth(top);
}
return process(top, io, frame);
}
And here's why I stop and say---it's all sort of mystery from here. Clearly something important is happening here.. and clearly all of the processes are getting traversed and computations are happening, but I've gotten lost in the weeds, and will probably need to come back before I can understand more. So, let's pop WAY back up to the very top, back into the main of our synth1.cpp, and see where we left off..
Meanwhile, back in main
Remember back when we were looking at this line of code?
AudioIO io(256, 44100., s.audioCB, &s);
So, that was the constuctor for an AudioIO object. We stored the callback function in callback, and we kept a pointer to a scheduler associated with that AudioIO object in userdata.
The callback gets called when you invoke the () operator, for example:
io(); // call callback
because of this code:
void AudioIO::operator()(){ frame(0); if(callback) callback(*this); }
The mUser parameter of the parent AudioIOCallback object does indeed get filled in with the value of the userdata passed into the AudioIO constructor (you'll find that code in src/AudioIO.cpp in the constructor, if you really want to go looking for it.)
Now that this io variable is set up as an instance of AudioIO, and has a deep relationship with our Scheduler object by means of various entangling alliances (void pointers, callback functions and the like) what's left to do?
Three lines of code:
Sync::master().spu(io.fps());
io.start();
printf("\nPress 'enter' to quit...\n"); getchar();\
Ok, let's unravel that first one. In Gamma/Sync.h we find a Sync class, with a static method that instantiates a Sync object and returns it.
/// Master sync. By default, Synceds will be synced to this.
static Sync& master(){
static Sync * s = new Sync;
return *s;
}
The spu() method sets samples per unit, and it seems reasonable to get those from io.fps(). Finally, io.start(); sets the whole thing in motion, apparently, and we wait just so all our threads don't die when the end of main is reached. A look inside the start() method reveals that it does indeed call the Pa_StartStream() method, which is a method of the underlying Port Audio library, rather than a method of Gamma.
But still, what does any of this have to do with the rest of the code in the file? Let's take a closer look.
The SineEnv class from synth1.cpp
Having unraveled the main from synth1.cpp---admittedly, only a little bit, but patience Grasshopper--let's now turn to the rest of the file.
The first few lines of the class SineEnv are these:
class SineEnv : public Process {
public:
SineEnv(double dt=0)
: Process(dt)
...
These tell us that SineEnv is a process, and that whatever parameter we pass in will be that processes "delay". Compare:
// This defines a block-rate processing node in the audio graph
class Process : public Node3<Process>{
public:
Process(double delay=0.);
...
Before we continue with the methods of SineEnv, let's take a look at the instance variables:
protected:
float mAmp;
float mDur;
Pan<> mPan;
Sine<> mOsc;
Env<3> mAmpEnv;
};
mAmp and mDur are straightforward: they are just simple floating point values for the Amplitude, and the Duration. They get their initial values via the set() call in the constructor, and then can be altered only by calls to amp() and dur() respectively.
The rest are a bit more subtle and involve some tricky C++.
Env<3> mAmpEnv
Let's start with Env<3> mAmpEnv; The Env class is defined in Gamma/Envelope.h
/// Envelope with a fixed number of exponential segments and a sustain point
/// The envelope consists of N exponential curve 'segments' and N+1 break-point
/// levels. The curvature and length of each segment and the break-point levels
/// can be controlled independently.
/// This class can be used to construct many specialized envelopes such as an AD
/// (Attack Decay), an ADSR (Attack Decay Sustain Release), and an ADSHR (Attack
/// Decay Sustain Hold Release). The number of envelope segments is fixed to
/// ensure better memory locality.
///
/// param N number of segments
/// param Tv value (sample) type
/// param Tp parameter type
template <int N, class Tv=real, class Tp=real, class Ts=Synced>
class Env : public Ts{
public:
Env()
...
So, an Env<3> has three segments. What do we do with this mAmpEnv inside of the SineEnv class?
Well, first the method calls inside the constructor set some parameters for the envelope:
mAmpEnv.curve(0); // make segments lines
We learn in the comments of Gamma/Envelope.h that the value 0 here means "straight line". Other choices:
/// c > 0 approaches slowly (accelerates), /// c < 0 approaches rapidly (decelerates), and /// c = 0 approaches linearly
Now, what about this?
mAmpEnv.levels(0,1,1,0);
That just sets the levels for the four breakpoints (three segments means four breakpoints). There are various methods for doing this, and those methods can be found in Gamma/Envelope.h, e.g.
/// Set first two break-point levels
Env& levels(Tv a, Tv b){ Tv v[]={a,b}; return levels(v,2); }
/// Set first three break-point levels
Env& levels(Tv a, Tv b, Tv c){ Tv v[]={a,b,c}; return levels(v,3); }
/// Set first four break-point levels
Env& levels(Tv a, Tv b, Tv c, Tv d){ Tv v[]={a,b,c,d}; return levels(v,4); }
Setting the attack and decay time works like this:
SineEnv& attack(float v){
mAmpEnv.lengths()[0] = v;
return *this;
}
SineEnv& decay(float v){
mAmpEnv.lengths()[2] = v;
return *this;
}
And apparently, it is also necessary to do this with the envelope at the top of the onProcess method of the SineEnv object so that the middle leg of the envelope has its length adjusted properly:
mAmpEnv.totalLength(mDur, 1);
Here's the code for that method. There is a different method there if you want to scale all of the segments proportionally.
/// Set total length of envelope by adjusting one segment length
/// @param[in] length desired length
/// @param[in] modSegment segment whose length is modified to match desired length
Env& totalLength(Tp length, int modSegment){
mLengths[modSegment] = Tp(0);
mLengths[modSegment] = length - totalLength();
return *this;
}
Now, the most "interesting" part of all is the operator() function, which is the one that may return a different value each time it is called, because it moves the envelope one "tick" of the clock through the various levels. It returns the current amplitude level of the envelope, and the call looks like this: mAmpEnv(), as in:
float s1 = mOsc() * mAmpEnv() * mAmp;
Pan<> mPan
The Pan object is an odd duck--and its the () operator that makes it a bit weird. Here's a portion of the class code, from Gamma/Effects.h (some parts omitted):
/// Equal-power 2-channel panner
template <class T=gam::real>
class Pan{
public:
/// @param[in] pos Signed unit position in [-1, 1]
Pan(T pos=0){ this->pos(pos); }
/// Filter sample (mono-to-stereo)
Vec<2,T> operator()(T in){
return Vec<2,T>(in*w1, in*w2);
}
/// Filter sample (mono-to-stereo)
template <class V>
void operator()(T in, V& out1, V& out2){
out1 = in*w1; out2 = in*w2;
}
So, when you see this in the code of the onProcess method, it's actually a call to the () operator of the Pan object called mPan, and the second and third paramters (s1 and s2) are being passed by reference, and CHANGED. (So much for side-effect free functional programming.) There are versions for stereo-to-stereo as well.
mPan(s1, s1,s2);
Also, the Pan object has a pos method (think "setPos") to set the position of the pan between -1 and 1.
SineEnv& pan(float v){ mPan.pos(v); return *this; }
Finally, the Osc<>
The code for the Osc<> is found in Gamma/Oscillators.h.
This is some of the hairiest code of all, involving multiple inheritance, templates, and all kinds of beasties:
Let's just hope it works, and move on for now. The crucial part is to know that that () operator is what gives us the current value, and that apparently, the onProcess() function is where the samples get computed.
