Merge branch 'master' of github.com:snappizz/plugin-example

Author: Nathan Ho

01-BoringMixer/BoringMixer.cpp

@@ -1,30 +1,52 @@
 #include "SC_PlugIn.h"
 
+// InterfaceTable contains pointers to functions in the host (server).
 static InterfaceTable *ft;
 
+// declare struct to hold unit generator state
 struct BoringMixer : public Unit {
+    // in later examples, we will declare state variables here.
 };
 
-static void BoringMixer_next(BoringMixer *unit, int inNumSamples);
+// older plugins wrap these function declarations in 'extern "C" { ... }'
+// no need to do that these days.
+static void BoringMixer_next(BoringMixer* unit, int inNumSamples);
 static void BoringMixer_Ctor(BoringMixer* unit);
 
+// the constructor function is called when a Synth containing this ugen is played.
+// it MUST be named "PluginName_Ctor", and the argument must be "unit."
 void BoringMixer_Ctor(BoringMixer* unit) {
+    // in later examples, we will initialize state variables here.
+    
+    // set a calculation function. for now, we only have one calculation function.
     SETCALC(BoringMixer_next);
+    // calculate one sample of output.
+    // this allows plugging into other ugens with initial-rate inputs 
     BoringMixer_next(unit, 1);
 }
 
+// the calculation function can have any name, but this is conventional. the first argument must be "unit."
+// this function is called every control period (64 samples is typical)
+// Don't change the names of the arguments, or the helper macros won't work.
 void BoringMixer_next(BoringMixer* unit, int inNumSamples) {
 
-    float *left = IN(0);
-    float *right = IN(1);
-    float *out = OUT(0);
+    // IN and OUT are helper macros that return audio-rate input and output buffers.
+    // In old ugens you'll see ZIN and ZOUT, which are not recommended.
+    float *left = IN(0); // first input
+    float *right = IN(1); // second input
+    float *out = OUT(0); // first output
 
+    // Loop through samples and do the computation.
     for (int i = 0; i < inNumSamples; i++) {
         out[i] = (left[i] + right[i]) * 0.5;
     }
 }
 
+// the entry point is called by the host when the plug-in is loaded
 PluginLoad(BoringMixerUGens) {
-    ft = inTable;
+    // InterfaceTable *inTable implicitly given as argument to the load function
+    ft = inTable; // store pointer to InterfaceTable
+    // DefineSimpleUnit is one of four macros defining different kinds of ugens.
+    // In later examples involving memory allocation, we'll see DefineDtorUnit.
     DefineSimpleUnit(BoringMixer);
-}
+}

README.md

@@ -1,4 +1,6 @@
-This is a series of examples demonstrating how to write SuperCollider plugins.
+This repository a series of examples demonstrating how to write server plugins for [SuperCollider](https://github.com/supercollider/supercollider) (not to be confused with quarks, which are libraries for the language).
+
+Beyond this repository, the reader is encouraged to look at [sc3-plugins](https://github.com/supercollider/sc3-plugins) for more complex, real-world examples.
 
 ## Compiling