This directory contains an example of a user-created UnitGenerator
class.  The class corresponds to the DSP unit generator macro
oscw, which is included in this directory.  To make this example, 
type the following to a shell:

	make exampunitgenerator

There are three steps to creating a UnitGenerator class:

STEP 1 -- Create a unit generator macro and test it.

See /usr/local/lib/dsp/test/README for details on how to make your own DSP unit
generator macro, test it in "stand alone" mode (i.e. without using the
Music Kit), and debug it. The example, oscw.asm has already been created
and tested.  For convenience, test.asm and config_standalone.asm are
included so you can verify the oscw test using Bug56.  "make test" will
generate the file "test.lod" which you can load into Bug56 as described in
the comments at the beginning of test.asm.

STEP 2 -- Create UnitGenerator objects from your macro.

The next step is to generate Music Kit objects from corresponding to your 
DSP unit generator macro by running dspwrap. To do this, you would invoke
the utility "dspwrap". The Makefile on this directory does this for you.

Dspwrap assembles the unit generator and invokes a subsidiary utility,
"dsploadwrap", to produce an Objective-C class for every combination
of input and output spaces.  Since oscw.asm has only one memory-space
argument (its output signal) two classes are produced, one for x
output and for y output.  These classes are written by dspwrap:

	Class		Code file 	Header file

	OscwUGx	        OscwUGx.m   	OscwUGx.h
	OscwUGy		OscwUGy.m 	OscwUGy.h

An included source file oscwUGInclude.m is generated as well.  Here,
"UG" means UnitGenerator. These files should never be edited. They are
the classes you actually allocate from the Orchestra in the
application. In our example, we actually only use the OscwUGx version.

Additionally, a superclass for OscwUGx and OscwUGy is produced, but
only if it does not already exist:

	Class		Code file 	Header file

	OscwUG		OscwUG.m	OscwUG.h	

These files should be hand-edited to add methods to set the unit generator
arguments and to set its response to messages such as -idle, -run, -finish,
etc.  See comments in the files OscwUG.h and OscwUG.m for guidelines as
to what should be added.  The version generated by dspwrap should actually
work, but the argument-setting methods are low level.


STEP 3 -- Test the new UnitGenerator class.

We've provided a simple example that allocates an instance of OscwUGx
and patches it to an instance of Out2sum. This example is given in the
file exampunitgenerator.m. 

The program plays three one-second exponentially decaying sine waves.
To run the program, type the following to a shell:

      exampunitgenerator 

Note that this example does not use a Music Kit Conductor. Instead, the
timing is done with the primitive function MKSetTime(). (Note that
MKSetTime() has no effect if there is a Conductor.) For most applicatons,
is much more convenient to use a Conductor to do the timing. The file
exampunitgenerator2.m on this directory illustrates how to use a Conductor
to do the timing.

See also /NextDeveloper/Examples/MusicKit/exampsynthpatch for an example of
how to combine UnitGenerator objects into larger structures (SynthPatches)
that can be used in a Music Kit performance.
