info - function generators available in cmusic

DESCRIPTION:
Cmusic functions are stored arrays of values which can be referenced by
cmusic unit generators.  The gen routines described below allow these
values to be set in various ways. The general form of a function
generating statement in a cmusic score is

	gen T G F D ;

where: T is an action time (normally 0), G is the name of a function
generator (such as "1" or "gen1"), F is the name of the function being
defined (such as "2", "f2", or "f2[256]"), and D is a valid definition
for the selected generator.  The definition may consist of constant
numbers, expressions (which may include note parameters or variables),
or string variable names.  String variable names are replaced by the
string contents before the definition is evaluated.  (This is
especially useful for passing flag arguments to gen routines - see
below).

The default function length in cmusic is currently 1024.  To change the
default function length, use "set funclength = N;" in the cmusic score,
where N is the desired default function length.  Functions defined with
cmusic gen statements will be the default length unless the function
name has a different function length appended to it in square
brackets.  Functions are no longer normalized to lie within the range
-1.0 to +1.0! They must be normalized using gen0, if normalization is
required.  Other ranges are also possible via mult and gliss unit
generators, etc.  Examples:

	gen 0 gen1 f2 . . . ;	(uses generator 1 to define function 2)
	gen 0 gen2 f1 . . . ;	(uses generator 2 to define function 1)
	gen 0 gen1 f2[256] . . . ; (uses generator 1 to define function 2
				    which has length 256 instead of default)

Functions may be redefined simply by supplying multiple definitions
with different action times.  The values are determined by the most
recent definition.  In a function definition, points on the horizontal
axis are described in arbitrary units, which are scaled to fit the
actual function length.  It is generally convenient to describe all
function as having  a length of 1.0.  Arithmetic expressions may be
used freely in the function definitions.

All functions are either open or closed on the right, i.e., they either
reach their final value (closed) or they stop just short of it (open).
Open functions are suitable for periodic use as waveforms, while closed
functions are suitable for use as envelopes, for example.  A single
"-o" or "-c" flag may be given (optionally) at the beginning of the
definition of the function to change the default action of each gen.

Information on a particular gen routine may be obtained with

	help genN

where "N" is the number of the gen routine.

GEN IMPLEMENTATION:

The gen routines are implemented as executable files which have the
same name as the gen routine.  For example, gen1 is implemented as a
program called "gen1", which accepts command line arguments identical
to those described under gen1, above, after the first argument, which
specifies the number of points to generate in the function after a "-L"
flag.  For example, the following statement generates a ramp function
1024 values in length which run from 0 to 1:

    % gen1 -L1024 0 0 1 1

The gen routines write ASCII numbers on their standard output if it is
a terminal, so it is possible to experiment with (a typically shortened
versions of) function values at the terminal.  For example, the command:

    % gen2 -L8 1 1

produces the terminal output:

    0.00000000
    .707106769
    1.00000000
    .707106709
    0.00000000
    -.707106829
    -1.00000000
    -.707106650

A user may implement and utilize his own gen routine simply by writing
a routine which follows these conventions using putfloat (see frmlib),
and compiling and loading the routine onto a file with a new name.
Cmusic will translate the statements:

    set funclength = 8K;
    var 0 s1 "-c";
    gen 0 ./newgen f3 s1 0 1,4/2 ;

into a system call to the newgen routine:

    % ./newgen -L8192 -c 0 1 2

The numbers generated by newgen and stored into cmusic function f3.
