home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.6 / ffcollection-1-6-1993-02.iso / ff_disks / 211-240 / ff_228 / glib / readme < prev    next >
Text File  |  1989-06-26  |  12KB  |  255 lines
  1. glib (one syllable) - a Generic LIBrarian and editor for synths
  2.  
  3. Originally written by Tim Thompson, including the basic structure
  4. and support for the TX81Z (patches and performance), DX100, and DEP5.  
  5. Macintosh and DW8000 support by Steve Falco.  Amiga and minimal K-5
  6. support by Alan Bland.
  7.  
  8. Intro
  9. -----
  10. glib (one syllable) is a text-screen-oriented librarian AND editor.
  11. It is structured in an attempt to make it easy to add support for new
  12. synthesizers.  Info on how to do this can be found later on in this README.
  13. The librarian part of the program manipulates 1 synth bank of voices
  14. (which can be uploaded to or downloaded from the synth), and 3
  15. banks of library voices (which can be read/written to disk).  All synths
  16. are supported simultaneously; you can switch back and forth and the
  17. library banks and other settings (e.g. MIDI channel) for each are retained. 
  18.  
  19. You can run glib on UNIX (it uses curses), although obviously most UNIX
  20. machines don't have MIDI I/O.  Trying it out on UNIX will give you a
  21. feel for what the program does, so you can decide whether or not it's
  22. worth the trouble to port it to your MIDI-capable PC.
  23.  
  24. Included is at least 1 bank of voices for each synth type that glib supports.
  25. The bank files (ending in .uu) are uuencoded.  You need to run uudecode to
  26. produce the real binary file for each.  The suffix conventions:
  27.  
  28.     .dx1 == dx100
  29.     .tx8 == tx81z
  30.     .t8p == tx81performance
  31.     .dw8 == dw8000
  32.     .k5s == K-5 single patches
  33.     .k5m == K-5 multi patches
  34.  
  35. Compiling
  36. ---------
  37. machdep.c and machdep.h are machine-dependent parts.  The *-mach.h and
  38. *-mach.c files are the versions of these files for different machines,
  39. e.g. unix-mach.[ch] is for UNIX, st-mach.[ch] is for the Atari ST.
  40. Copy the proper files to machdep.c and machdep.h before compiling
  41. for a particular machine.   For example, on UNIX, do the following:
  42.  
  43.     cp unix-mach.c machdep.c
  44.     cp unix-mach.h machdep.h
  45.     make glib
  46.  
  47. The contents of list.c control which synths are supported; modify
  48. the defines at the beginning of that file appropriately.  When
  49. compiling, you need to include glib.c and the appropriate synth
  50. files (e.g. if you define DW8000 in list.c, then you need to compile
  51. with dw8000.c).  A single version of glib can support as many synths
  52. as you want, although some compilers may have size limitations or
  53. overlay schemes that get in the way.
  54.  
  55. Using glib - Moving around
  56. --------------------------
  57. Both the librarian and editor parts of glib make use of h/j/k/l
  58. to move the cursor around.  Control-l redraws the screen.  These
  59. keys are #defined in glib.h, so you can change them if you want.
  60. To quit from any mode, use 'q'.  In the librarian screen, '?' gives
  61. a command summary.  'Esc' sends an all-notes-off.
  62.  
  63. Using glib - The librarian
  64. --------------------------
  65. The screen shows the synth bank on the left, and the current (1 of 3)
  66. library bank on the right.  A '*' identifies the 'current' voice, and
  67. you use h/j/k/l to move it around.  As soon as you move to a different
  68. voice, it is sent to the 'edit buffer' of the synth, so it is very
  69. easy to roam around and see what each voice sounds like.  Commands:
  70.  
  71.      b - Cycle through the (3) library banks, displayed on the
  72.          right side of the screen.
  73.      c - Set the MIDI channel for sending/receiving voices.
  74.      d - Download from the (real) synthesizer, replacing the current
  75.          contents of the synth bank.
  76.      e - Edit the current voice (see editor description below).
  77.      f - List the files on the disk.
  78.      p - Put the yank buffer, replacing the contents of the current voice.
  79.      q - Quit, going back to 'choose a synth'.
  80.      r - Read a bank of voices from a file, replacing entirely
  81.          the current library bank.
  82.      s - Swap the current voice with the yank buffer.  2 swaps is a no-op.
  83.      t - Transfer all voices, either from the current library bank to
  84.          the synth bank, or vice versa.
  85.      u - Upload the current contents of the synth bank to the synth.
  86.          You are given a choice of sending the entire bank or just
  87.          the current voice.
  88.      w - Write the current library bank to a file.
  89.      y - Yank the current voice into the yank buffer, shown
  90.          in the middle of the screen.
  91.  
  92. Using glib - The editor
  93. -----------------------
  94. In the editor part, h/j/k/l move the cursor among the parameter
  95. values.  The cursor will only land on parameter values.  Once on
  96. a parameter value, the following keys will affect it:
  97.  
  98.      K - increase value by 1
  99.      J - decrease value by 1
  100.      I - increase value by 4
  101.      M - decrease value by 4
  102.      < - decrease value to its minimum
  103.      > - increase value to its maximum
  104.  
  105. These keys are also defined in glib.h, and should be changed to
  106. suit your own tastes.  I'm not thrilled with these choices, myself,
  107. but I had to use something, and at least the hand stays in one place.
  108.  
  109. The 'auto-note' is played whenever you press the space bar.  This is
  110. a convenient way of playing a note as soon as you make a change (ie.
  111. you can do everything from the computer keyboard).  You can change the
  112. auto-note parameters (pitch, duration, volume, channel) the same way as all
  113. the other parameters.
  114.  
  115. Hacking glib - Internals
  116. ------------------------
  117. The program is written so that support for a new synth can be added by
  118. adding an entry to the array in list.c, describing the various attributes
  119. of the synthesizer and the C functions to be called to control it.  And, of
  120. course, you have to write those C functions.  Adding a new synth, for a
  121. reasonable C programmer, might be described as mostly straightforward but
  122. tedious.  People other than the original author HAVE done it, with no help.
  123. Glib allows you to re-use the front-end interface of the librarian and
  124. editor, but it does not relieve you of having to write C code which
  125. interacts with the synth (which, depending on the synth, can of course be
  126. easy or maddening) and with the raw data formats.  Naturally, using one of
  127. the existing synth files as an example of how to do things is the best way
  128. to start on a new one.
  129.  
  130. The 'E' array in list.c has the following structure:
  131.  
  132. struct editinfo {
  133.     char *ed_name;        /* Synth name */
  134.     struct paraminfo *ed_params;    /* list of parameters */
  135.     struct labelinfo *ed_labels;    /* screen labels in edit mode */
  136.     int ed_nvoices;        /* number of voices */
  137.     int ed_vsize;        /* size of each voice data, in bytes */
  138.     int ed_nsize;        /* name size */
  139.     int (*ed_din)();    /* copy voice data into paraminfo array */
  140.     int (*ed_dout)();    /* copy voice data out of paraminfo array */
  141.     int (*ed_sedit)();    /* send 1 voice to synth edit buffer */
  142.     int (*ed_sone)();    /* send 1 voice to a synth (permanent) patch*/
  143.     int (*ed_sbulk)();    /* send bulk voice data */
  144.     int (*ed_gbulk)();    /* get bulk voice data */
  145.     char *(*ed_nof)();    /* get name of a voice out of data */
  146.     int (*ed_snof)();    /* set name of a voice in data */
  147.     char *(*ed_numof)();    /* convert voice number to on-screen text */
  148.     int (*ed_cvtnum)();    /* convert visable voice number to std. format */
  149.     int (*ed_cvtanum)();    /* convert alphanumeric voice number to std. format */
  150. };
  151.  
  152. In glib, there are several relatively independent representations of
  153. the synth voice data.  First, there is the data that is stored in the
  154. library and synth banks (ie. the data used and manipulated via the
  155. librarian screen).  This is the format of the data that is written to
  156. and read from files (a single byte, '0xdd', is added to the beginning
  157. of the file, to identify it).  The size of a single voice in this data
  158. is 'ed_vsize'.  The number of voices in a bank is 'ed_nvoices', so the
  159. amount of space taken up by a library bank is ed_vsize * ed_nvoices.
  160.  
  161. When a voice is edited, the voice data is copied into the parameter
  162. array (see below), in p_val.  The 'ed_din' function is called to do this.
  163. After a voice is edited, 'ed_dout' takes the updated parameter values 
  164. and puts them back into the original data format.  Note that this means
  165. that the bytes in the 'raw' voice data and the values in the parameter
  166. array (ie. the values manipulated by the editor) need not be the same.
  167. There are utility functions 'getval' and 'setval' which should be used
  168. for getting and setting the values in the parameter array.  See dx100.c
  169. for usage.
  170.  
  171. The ed_sedit, ed_sone, ed_sbulk, and ed_gbulk functions are called to
  172. send voices to and get voices from the synthesizer.  Only one of ed_sone
  173. and ed_sbulk need be defined, although ed_sone should be preferred.
  174. (I had trouble getting the DX100 to accept a single permanent voice
  175. change, so it always does a bulk voice transfer.)  The data passed to
  176. these functions is in the library bank format.  The ed_gbulk function is
  177. optional, so that write-only MIDI devices (like the DEP-5) are allowed.
  178.  
  179. The ed_nof function is called to pull the voice name out of the raw
  180. voice data (as stored in the library banks), and it should return a
  181. C string containing the name.  The ed_snof function is called to
  182. stick a voice name into the raw voice data.  Note that the 'raw'
  183. library bank voice data does NOT have to match the data that is
  184. really sent to the synthesizer (by the ed_sedit and ed_sone functions).
  185. For example, the DEP-5 does not have names as part of the voice data,
  186. but that does not prevent glib from maintaining and storing (in the files)
  187. voice names.  This holds for the DW-8000 as well.
  188.  
  189. The ed_numof function is called to convert the voice number to the
  190. text that is displayed on the librarian screen.  This can handle
  191. the odd numbering convention of the DW-8000.  If ed_numof==NULL, the
  192. number is used as-is.  Otherwise, ed_numof is called with the voice
  193. number MINUS 1 (i.e. 0-based); ed_numof should return a string
  194. containing the desired display.  Likewise, the ed_cvtnum function is
  195. used to convert user input from an odd numbering system to the standard
  196. sequential internal representation (0 to whatever).
  197.  
  198. The ed_cvtanum function is an alternative to ed_cvtnum for synths that
  199. use an alphanumeric represenation for patch number (e.g. the K-5 numbers
  200. its patches A1 through D12).  The ed_cvtanum function takes a string
  201. typed by the user and converts it to the standard sequential internal
  202. representation.  You should not define both ed_cvtnum and ed_cvtanum
  203. for the same synth.
  204.  
  205. The editor screen is controlled by two arrays, ed_labels and ed_params.
  206. ed_labels contains arbitrary screen labels, in the following structure:
  207.  
  208. struct labelinfo {
  209.     int l_row;    /* 0-based */
  210.     int l_col;    /* 0-based */
  211.     char *l_text;
  212. };
  213.  
  214. The ed_params array is used to specify the parameters that the user can peruse
  215. and change in the edit screen, and looks like this (one for each parameter):
  216.  
  217. struct paraminfo {
  218.     char *p_name;        /* the parameter name */
  219.     char *p_label;        /* on-screen label (possibly NULL) */
  220.     int p_lrow;        /* position for printing label */
  221.     int p_lcol;
  222.     int p_vrow;        /* position for printing value */
  223.     int p_vcol;
  224.     char *((*p_tovis)());    /* function converts value to on-screen text*/
  225.     int p_min;        /* minimum parameter value */
  226.     int p_max;        /* maximum parameter value */
  227.     int p_val;        /* parameter value */
  228.     int p_flags;        /* flag to enable/disable parameter */
  229. };
  230.  
  231. The editor calls p_tovis with a parameter value, and expects that function
  232. to pass back a string which contains what should be displayed on the
  233. screen for that value.  Often, this is just an 'sprintf' of the value,
  234. or perhaps the value offset by something.  Or, it could be some text
  235. that represents the value (e.g. "on" for 1 and "off" for 0).  Or, it could
  236. be something more interesting, e.g. a picture of the voice algorithm.
  237. The parameter value strings can make use of cursor motion, by including the
  238. sequences ~d,~u,~l,~r to go down,up,left,right.  The dx100 and dep5 editors
  239. use this to handle the display of the algorithm drawings.
  240.  
  241. A parameter can be 'disabled' by setting p_flags to non-zero.  The p_tovis
  242. function can set the external variable 'Redraw' to 1 if it wants to force
  243. the entire editor screen to be redrawn (e.g. after a parameter has been
  244. disabled).
  245.  
  246. Support for a mouse has been added, although it is currently disabled
  247. for the Atari, since I was having various hassles getting it under control.
  248. It did work, but had various quirks.
  249.  
  250. Mouse support for the Amiga was added, and appears to work after fixing
  251. a few problems in glib.c, so it may be possible to enable the Atari mouse
  252. support now.
  253.  
  254.                              ...Tim Thompson...twitch!glimmer!tjt...
  255.