Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/242.lha/GenericLIBrarian/source/README

Text File | 1989-04-07 | 12.5 KB | 255 lines

glib (one syllable) - a Generic LIBrarian and editor for synths

Originally written by Tim Thompson, including the basic structure
and support for the TX81Z (patches and performance), DX100, and DEP5.
Macintosh and DW8000 support by Steve Falco.  Amiga and minimal K-5
support by Alan Bland.

Intro
-----
glib (one syllable) is a text-screen-oriented librarian AND editor.
It is structured in an attempt to make it easy to add support for new
synthesizers.  Info on how to do this can be found later on in this README.
The librarian part of the program manipulates 1 synth bank of voices
(which can be uploaded to or downloaded from the synth), and 3
banks of library voices (which can be read/written to disk).  All synths
are supported simultaneously; you can switch back and forth and the
library banks and other settings (e.g. MIDI channel) for each are retained.

You can run glib on UNIX (it uses curses), although obviously most UNIX
machines don't have MIDI I/O.  Trying it out on UNIX will give you a
feel for what the program does, so you can decide whether or not it's
worth the trouble to port it to your MIDI-capable PC.

Included is at least 1 bank of voices for each synth type that glib supports.
The bank files (ending in .uu) are uuencoded.  You need to run uudecode to
produce the real binary file for each.  The suffix conventions:

        .dx1 == dx100
        .tx8 == tx81z
        .t8p == tx81performance
        .dw8 == dw8000
        .k5s == K-5 single patches
        .k5m == K-5 multi patches

Compiling
---------
machdep.c and machdep.h are machine-dependent parts.  The *-mach.h and
*-mach.c files are the versions of these files for different machines,
e.g. unix-mach.[ch] is for UNIX, st-mach.[ch] is for the Atari ST.
Copy the proper files to machdep.c and machdep.h before compiling
for a particular machine.   For example, on UNIX, do the following:

        cp unix-mach.c machdep.c
        cp unix-mach.h machdep.h
        make glib

The contents of list.c control which synths are supported; modify
the defines at the beginning of that file appropriately.  When
compiling, you need to include glib.c and the appropriate synth
files (e.g. if you define DW8000 in list.c, then you need to compile
with dw8000.c).  A single version of glib can support as many synths
as you want, although some compilers may have size limitations or
overlay schemes that get in the way.

Using glib - Moving around
--------------------------
Both the librarian and editor parts of glib make use of h/j/k/l
to move the cursor around.  Control-l redraws the screen.  These
keys are #defined in glib.h, so you can change them if you want.
To quit from any mode, use 'q'.  In the librarian screen, '?' gives
a command summary.  'Esc' sends an all-notes-off.

Using glib - The librarian
--------------------------
The screen shows the synth bank on the left, and the current (1 of 3)
library bank on the right.  A '*' identifies the 'current' voice, and
you use h/j/k/l to move it around.  As soon as you move to a different
voice, it is sent to the 'edit buffer' of the synth, so it is very
easy to roam around and see what each voice sounds like.  Commands:

     b - Cycle through the (3) library banks, displayed on the
         right side of the screen.
     c - Set the MIDI channel for sending/receiving voices.
     d - Download from the (real) synthesizer, replacing the current
         contents of the synth bank.
     e - Edit the current voice (see editor description below).
     f - List the files on the disk.
     p - Put the yank buffer, replacing the contents of the current voice.
     q - Quit, going back to 'choose a synth'.
     r - Read a bank of voices from a file, replacing entirely
         the current library bank.
     s - Swap the current voice with the yank buffer.  2 swaps is a no-op.
     t - Transfer all voices, either from the current library bank to
         the synth bank, or vice versa.
     u - Upload the current contents of the synth bank to the synth.
         You are given a choice of sending the entire bank or just
         the current voice.
     w - Write the current library bank to a file.
     y - Yank the current voice into the yank buffer, shown
         in the middle of the screen.

Using glib - The editor
-----------------------
In the editor part, h/j/k/l move the cursor among the parameter
values.  The cursor will only land on parameter values.  Once on
a parameter value, the following keys will affect it:

     K - increase value by 1
     J - decrease value by 1
     I - increase value by 4
     M - decrease value by 4
     < - decrease value to its minimum
     > - increase value to its maximum

These keys are also defined in glib.h, and should be changed to
suit your own tastes.  I'm not thrilled with these choices, myself,
but I had to use something, and at least the hand stays in one place.

The 'auto-note' is played whenever you press the space bar.  This is
a convenient way of playing a note as soon as you make a change (ie.
you can do everything from the computer keyboard).  You can change the
auto-note parameters (pitch, duration, volume, channel) the same way as all
the other parameters.

Hacking glib - Internals
------------------------
The program is written so that support for a new synth can be added by
adding an entry to the array in list.c, describing the various attributes
of the synthesizer and the C functions to be called to control it.  And, of
course, you have to write those C functions.  Adding a new synth, for a
reasonable C programmer, might be described as mostly straightforward but
tedious.  People other than the original author HAVE done it, with no help.
Glib allows you to re-use the front-end interface of the librarian and
editor, but it does not relieve you of having to write C code which
interacts with the synth (which, depending on the synth, can of course be
easy or maddening) and with the raw data formats.  Naturally, using one of
the existing synth files as an example of how to do things is the best way
to start on a new one.

The 'E' array in list.c has the following structure:

struct editinfo {
        char *ed_name;          /* Synth name */
        struct paraminfo *ed_params;    /* list of parameters */
        struct labelinfo *ed_labels;    /* screen labels in edit mode */
        int ed_nvoices;         /* number of voices */
        int ed_vsize;           /* size of each voice data, in bytes */
        int ed_nsize;           /* name size */
        int (*ed_din)();        /* copy voice data into paraminfo array */
        int (*ed_dout)();       /* copy voice data out of paraminfo array */
        int (*ed_sedit)();      /* send 1 voice to synth edit buffer */
        int (*ed_sone)();       /* send 1 voice to a synth (permanent) patch*/
        int (*ed_sbulk)();      /* send bulk voice data */
        int (*ed_gbulk)();      /* get bulk voice data */
        char *(*ed_nof)();      /* get name of a voice out of data */
        int (*ed_snof)();       /* set name of a voice in data */
        char *(*ed_numof)();    /* convert voice number to on-screen text */
        int (*ed_cvtnum)();     /* convert visable voice number to std. format */
        int (*ed_cvtanum)();    /* convert alphanumeric voice number to std. format */
};

In glib, there are several relatively independent representations of
the synth voice data.  First, there is the data that is stored in the
library and synth banks (ie. the data used and manipulated via the
librarian screen).  This is the format of the data that is written to
and read from files (a single byte, '0xdd', is added to the beginning
of the file, to identify it).  The size of a single voice in this data
is 'ed_vsize'.  The number of voices in a bank is 'ed_nvoices', so the
amount of space taken up by a library bank is ed_vsize * ed_nvoices.

When a voice is edited, the voice data is copied into the parameter
array (see below), in p_val.  The 'ed_din' function is called to do this.
After a voice is edited, 'ed_dout' takes the updated parameter values
and puts them back into the original data format.  Note that this means
that the bytes in the 'raw' voice data and the values in the parameter
array (ie. the values manipulated by the editor) need not be the same.
There are utility functions 'getval' and 'setval' which should be used
for getting and setting the values in the parameter array.  See dx100.c
for usage.

The ed_sedit, ed_sone, ed_sbulk, and ed_gbulk functions are called to
send voices to and get voices from the synthesizer.  Only one of ed_sone
and ed_sbulk need be defined, although ed_sone should be preferred.
(I had trouble getting the DX100 to accept a single permanent voice
change, so it always does a bulk voice transfer.)  The data passed to
these functions is in the library bank format.  The ed_gbulk function is
optional, so that write-only MIDI devices (like the DEP-5) are allowed.

The ed_nof function is called to pull the voice name out of the raw
voice data (as stored in the library banks), and it should return a
C string containing the name.  The ed_snof function is called to
stick a voice name into the raw voice data.  Note that the 'raw'
library bank voice data does NOT have to match the data that is
really sent to the synthesizer (by the ed_sedit and ed_sone functions).
For example, the DEP-5 does not have names as part of the voice data,
but that does not prevent glib from maintaining and storing (in the files)
voice names.  This holds for the DW-8000 as well.

The ed_numof function is called to convert the voice number to the
text that is displayed on the librarian screen.  This can handle
the odd numbering convention of the DW-8000.  If ed_numof==NULL, the
number is used as-is.  Otherwise, ed_numof is called with the voice
number MINUS 1 (i.e. 0-based); ed_numof should return a string
containing the desired display.  Likewise, the ed_cvtnum function is
used to convert user input from an odd numbering system to the standard
sequential internal representation (0 to whatever).

The ed_cvtanum function is an alternative to ed_cvtnum for synths that
use an alphanumeric represenation for patch number (e.g. the K-5 numbers
its patches A1 through D12).  The ed_cvtanum function takes a string
typed by the user and converts it to the standard sequential internal
representation.  You should not define both ed_cvtnum and ed_cvtanum
for the same synth.

The editor screen is controlled by two arrays, ed_labels and ed_params.
ed_labels contains arbitrary screen labels, in the following structure:

struct labelinfo {
        int l_row;      /* 0-based */
        int l_col;      /* 0-based */
        char *l_text;
};

The ed_params array is used to specify the parameters that the user can peruse
and change in the edit screen, and looks like this (one for each parameter):

struct paraminfo {
        char *p_name;           /* the parameter name */
        char *p_label;          /* on-screen label (possibly NULL) */
        int p_lrow;             /* position for printing label */
        int p_lcol;
        int p_vrow;             /* position for printing value */
        int p_vcol;
        char *((*p_tovis)());   /* function converts value to on-screen text*/
        int p_min;              /* minimum parameter value */
        int p_max;              /* maximum parameter value */
        int p_val;              /* parameter value */
        int p_flags;            /* flag to enable/disable parameter */
};

The editor calls p_tovis with a parameter value, and expects that function
to pass back a string which contains what should be displayed on the
screen for that value.  Often, this is just an 'sprintf' of the value,
or perhaps the value offset by something.  Or, it could be some text
that represents the value (e.g. "on" for 1 and "off" for 0).  Or, it could
be something more interesting, e.g. a picture of the voice algorithm.
The parameter value strings can make use of cursor motion, by including the
sequences ~d,~u,~l,~r to go down,up,left,right.  The dx100 and dep5 editors
use this to handle the display of the algorithm drawings.

A parameter can be 'disabled' by setting p_flags to non-zero.  The p_tovis
function can set the external variable 'Redraw' to 1 if it wants to force
the entire editor screen to be redrawn (e.g. after a parameter has been
disabled).

Support for a mouse has been added, although it is currently disabled
for the Atari, since I was having various hassles getting it under control.
It did work, but had various quirks.

Mouse support for the Amiga was added, and appears to work after fixing
a few problems in glib.c, so it may be possible to enable the Atari mouse
support now.

                             ...Tim Thompson...twitch!glimmer!tjt...