home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume6 / glib / part06 / PORTING < prev   
Encoding:
Text File  |  1989-05-14  |  11.9 KB  |  300 lines
  1. $Id: PORTING,v 1.6 89/05/06 17:13:07 lee Exp $
  2. [Lee:]
  3.  
  4. The C source code for the various synth modules is generated by
  5. a program 'menutoc'.  Although C source for 'menutoc' is included,
  6. revising the program would require flex, the freely distributed "fast
  7. lex" to compile.  But if you happen not to have flex, lex will serve --
  8. see the note in the Makefile and notes at the beginning of file
  9. makemenu.l.
  10.  
  11.     ---------------------------------
  12. [Kesti:]
  13.  
  14. In order to adapt it to the D-10's rather large data set, I have used glib's
  15. ability to service multiple synths to instead service sub-sections of a single
  16. D-10.  These subsections are:
  17.  
  18.     Performance mode patches
  19.     Multi-timbral mode timbres
  20.  
  21.     Tone waveform generators
  22.     Tone time variant filters
  23.     Tone time variant amplifiers
  24.  
  25.     Rhythm setup
  26.     Rhythm patterns
  27.     Rhythm track
  28.  
  29. Because the memory requirement of a single program to service this much data
  30. is large enough to be cumbersome, I have broken the subsections into three
  31. separate programs.  These are d10patch, d10tone, and d10drum.
  32.  
  33. The tone services also require a separate program because, unlike all other
  34. services, they must operate on a single common data set.  This required
  35. changes to the data memory allocation and other functions in glib.c.  When
  36. compiling d10tone, be sure to #define SINGLEDATA in glib.c to enable these
  37. changes.
  38.  
  39. I believe that I have maintained glib's ability to be compiled for Un*x
  40. (using SysV curses), DOS, and the Atari ST.  The sources supplied have
  41. been succesfully compiled and run on an AT&T 3b1, running v3.51 software;
  42. and an AT&T 6300 (with a V30 in the cpu socket), running AT&T's version of
  43. DOS v3.20.  Borland Turbo C v1.0 was used to produce the executables and the
  44. machine was fitted with a CMS-401 interface.
  45.  
  46. The Makefile provided was used on the 3b1, and produces a single executable
  47. named glib that combines all services, but does not tie the tone data
  48. together as discussed above.  This is presumably no problem, as the Un*x
  49. version is intended to be for demo purposes.  If your Un*x machine has a
  50. midi interface, I'd like hear from you!
  51.  
  52. The Turbo C project files (*.prj) are used by the integrated environment to
  53. produce glib.exe, d10patch.exe, d10tone.exe, and d10drum.exe.  Be sure to
  54. use the large memory model.  It is not recommended that glib.exe be used, as
  55. it requires almost all the available memory of a 640K machine, and again,
  56. would not tie the tone data together (SINGLEDATA should not be #defined
  57. when compiling for glib.exe.).
  58.  
  59. [Lee:]
  60.  
  61. I did not include the .prj files mentioned above.  So many files
  62. already!  But below are the contents of those files.  The file machdep.c
  63. is a copy of pc-mach.c (and pc-mach.h should be copied to machdep.h);
  64. the d10*.c files except d10ton.c) must be constructed from the
  65. corresponding d10*.mnu files by the menutoc program; and the files
  66. listdrum.c, listpat.c, and listton.c are the same as file list.c, but
  67. with '#defines' removed for the unused modules.  That is to say, for the
  68. D10 '#defines', keep only
  69.     #define D10urp
  70.     #define D10rsu
  71.     #define D10tra
  72. for listdrum.c, keep only
  73.     #define D10pat
  74.     #define D10tim
  75. for listpat.c, and keep only
  76.     #define D10wfg
  77.     #define D10tvf
  78.     #define D10tva
  79. for listton.c.
  80. ::::::::::::::
  81. contents of file d10drum.prj
  82. ::::::::::::::
  83. d10urp.c
  84. d10rsu.c
  85. d10tra.c
  86. glib.c
  87. listdrum.c
  88. vis.c
  89. machdep.c
  90. ::::::::::::::
  91. contents of file d10patch.prj
  92. ::::::::::::::
  93. d10pat.c
  94. d10tim.c
  95. glib.c
  96. listpat.c
  97. vis.c
  98. machdep.c
  99. ::::::::::::::
  100. contents of file d10tone.prj
  101. ::::::::::::::
  102. d10ton.c
  103. d10wfg.c
  104. d10tvf.c
  105. d10tva.c
  106. glib.c
  107. listtone.c
  108. vis.c
  109. machdep.c
  110. ::::::::::::::
  111. contents of file glib.prj
  112. ::::::::::::::
  113. d10pat.c
  114. d10tim.c
  115. d10wfg.c
  116. d10ton.c
  117. d10tvf.c
  118. d10tva.c
  119. d10urp.c
  120. d10rsu.c
  121. d10tra.c
  122. glib.c
  123. list.c
  124. vis.c
  125. machdep.c
  126. ----------------------
  127.  
  128.  
  129. [Thompson:]
  130.  
  131. Compiling
  132. ---------
  133. machdep.c and machdep.h are machine-dependent parts.  The *-mach.h and
  134. *-mach.c files are the versions of these files for different machines,
  135. e.g. unix-mach.[ch] is for UNIX, st-mach.[ch] is for the Atari ST.
  136. Copy the proper files to machdep.c and machdep.h before compiling
  137. for a particular machine.   For example, on UNIX, do the following:
  138.  
  139.     cp unix-mach.c machdep.c
  140.     cp unix-mach.h machdep.h
  141.     make glib
  142.  
  143. The contents of list.c control which synths are supported; modify
  144. the defines at the beginning of that file appropriately.  When
  145. compiling, you need to include glib.c and the appropriate synth
  146. files (e.g. if you define DW8000 in list.c, then you need to compile
  147. with dw8000.c).  A single version of glib can support as many synths
  148. as you want, although some compilers may have size limitations or
  149. overlay schemes that get in the way.
  150.  
  151.  
  152. Hacking glib - Internals
  153. ------------------------
  154. The program is written so that support for a new synth can be added by
  155. adding an entry to the array in list.c, describing the various attributes
  156. of the synthesizer and the C functions to be called to control it.  And, of
  157. course, you have to write those C functions.  Adding a new synth, for a
  158. reasonable C programmer, might be described as mostly straightforward but
  159. tedious.  People other than the original author HAVE done it, with no help.
  160. Glib allows you to re-use the front-end interface of the librarian and
  161. editor, but it does not relieve you of having to write C code which
  162. interacts with the synth (which, depending on the synth, can of course be
  163. easy or maddening) and with the raw data formats.  Naturally, using one of
  164. the existing synth files as an example of how to do things is the best way
  165. to start on a new one.
  166.  
  167. The 'E' array in list.c has the following structure:
  168.  
  169. struct editinfo {
  170.     char *ed_name;        /* Synth name */
  171.     struct paraminfo *ed_params;    /* list of parameters */
  172.     struct labelinfo *ed_labels;    /* screen labels in edit mode */
  173.     int ed_nvoices;        /* number of voices */
  174.     int ed_vsize;        /* size of each voice data, in bytes */
  175.     int ed_nsize;        /* name size */
  176.     int ed_dataid;        /* data ID */
  177.     int (*ed_din)();    /* copy voice data into paraminfo array */
  178.     int (*ed_dout)();    /* copy voice data out of paraminfo array */
  179.     int (*ed_sedit)();    /* send 1 voice to synth edit buffer */
  180.     int (*ed_sone)();    /* send 1 voice to a synth (permanent) patch*/
  181.     int (*ed_sbulk)();    /* send bulk voice data */
  182.     int (*ed_gbulk)();    /* get bulk voice data */
  183.     char *(*ed_nof)();    /* get name of a voice out of data */
  184.     int (*ed_snof)();    /* set name of a voice in data */
  185.     char *(*ed_numof)();    /* convert voice number to on-screen text */
  186.     int (*ed_cvtnum)();    /* convert visable voice number to std. format */
  187. };
  188.  
  189. In glib, there are several relatively independent representations of the
  190. synth voice data.  First, there is the data that is stored in the
  191. library and synth banks (ie.  the data used and manipulated via the
  192. librarian screen).  This is the format of the data that is written to
  193. and read from files (a single byte, given as 'ed_dataid' above, is added
  194. to the beginning of the file, to identify it).  The size of a single
  195. voice in this data is 'ed_vsize'.  The number of voices in a bank is
  196. 'ed_nvoices', so the amount of space taken up by a library bank is
  197. ed_vsize * ed_nvoices.
  198.  
  199. When a voice is edited, the voice data is copied into the parameter
  200. array (see below), in p_val.  The 'ed_din' function is called to do this.
  201. After a voice is edited, 'ed_dout' takes the updated parameter values 
  202. and puts them back into the original data format.  Note that this means
  203. that the bytes in the 'raw' voice data and the values in the parameter
  204. array (ie. the values manipulated by the editor) need not be the same.
  205. There are utility functions 'getval' and 'setval' which should be used
  206. for getting and setting the values in the parameter array.  See dx100.c
  207. for usage.
  208.  
  209. The ed_sedit, ed_sone, ed_sbulk, and ed_gbulk functions are called to
  210. send voices to and get voices from the synthesizer.  Only one of ed_sone
  211. and ed_sbulk need be defined, although ed_sone should be preferred.
  212. (I had trouble getting the DX100 to accept a single permanent voice
  213. change, so it always does a bulk voice transfer.)  The data passed to
  214. these functions is in the library bank format.  The ed_gbulk function is
  215. optional, so that write-only MIDI devices (like the DEP-5) are allowed.
  216.  
  217. The ed_nof function is called to pull the voice name out of the raw
  218. voice data (as stored in the library banks), and it should return a
  219. C string containing the name.  The ed_snof function is called to
  220. stick a voice name into the raw voice data.  Note that the 'raw'
  221. library bank voice data does NOT have to match the data that is
  222. really sent to the synthesizer (by the ed_sedit and ed_sone functions).
  223. For example, the DEP-5 does not have names as part of the voice data,
  224. but that does not prevent glib from maintaining and storing (in the files)
  225. voice names.  This holds for the DW-8000 as well.
  226.  
  227. The ed_numof function is called to convert the voice number to the
  228. text that is displayed on the librarian screen.  This can handle
  229. the odd numbering convention of the DW-8000.  If ed_numof==NULL, the
  230. number is used as-is.  Otherwise, ed_numof is called with the voice
  231. number MINUS 1 (i.e. 0-based); ed_numof should return a string
  232. containing the desired display.  Likewise, the ed_cvtnum function is
  233. used to convert user input from an odd numbering system to the standard
  234. sequential internal representation (0 to whatever).
  235.  
  236. The editor screen is controlled by two arrays, ed_labels and ed_params.
  237. ed_labels contains arbitrary screen labels, in the following structure:
  238.  
  239. struct labelinfo {
  240.     int l_row;    /* 0-based */
  241.     int l_col;    /* 0-based */
  242.     char *l_text;
  243. };
  244.  
  245. The ed_params array is used to specify the parameters that the user can peruse
  246. and change in the edit screen, and looks like this (one for each parameter):
  247.  
  248. struct paraminfo {
  249.     char *p_name;        /* the parameter name */
  250.     char *p_label;        /* on-screen label (possibly NULL) */
  251.     int p_lrow;        /* position for printing label */
  252.     int p_lcol;
  253.     int p_vrow;        /* position for printing value */
  254.     int p_vcol;
  255.     char *((*p_tovis)());    /* function converts value to on-screen text*/
  256.     int p_min;        /* minimum parameter value */
  257.     int p_max;        /* maximum parameter value */
  258.     int p_val;        /* parameter value */
  259.     int p_flags;        /* flag to enable/disable parameter */
  260. };
  261.  
  262. The editor calls p_tovis with a parameter value, and expects that function
  263. to pass back a string which contains what should be displayed on the
  264. screen for that value.  Often, this is just an 'sprintf' of the value,
  265. or perhaps the value offset by something.  Or, it could be some text
  266. that represents the value (e.g. "on" for 1 and "off" for 0).  Or, it could
  267. be something more interesting, e.g. a picture of the voice algorithm.
  268. The parameter value strings can make use of cursor motion, by including the
  269. sequences ~d,~u,~l,~r to go down,up,left,right.  The dx100 and dep5 editors
  270. use this to handle the display of the algorithm drawings.
  271.  
  272. A parameter can be 'disabled' by setting p_flags to non-zero.  The p_tovis
  273. function can set the external variable 'Redraw' to 1 if it wants to force
  274. the entire editor screen to be redrawn (e.g. after a parameter has been
  275. disabled).
  276.  
  277. Support for a mouse has been added, although it is currently disabled
  278. for the Atari, since I was having various hassles getting it under control.
  279. It did work, but had various quirks.
  280.  
  281. Mouse support for the Amiga was added, and appears to work after fixing
  282. a few problems in glib.c, so it may be possible to enable the Atari mouse
  283. support now.
  284.  
  285.                              ...Tim Thompson...twitch!glimmer!tjt...
  286.  
  287. [notes from Ed Wilts, ewilts%Janus.MtRoyal.AB.CA@Ucnet.UCalgary.CA,
  288.  on the Amiga version for the D-10]
  289.  
  290. ...  The problem I had in getting it
  291. going was more in the execution than the compilation.  Without a sufficiently
  292. large stack, you will get highly intermittent results, and depending on the
  293. state of the moon and the time of day, gurus.  I was getting frequent timeouts
  294. reading from the D-10 and sometimes the data would be all read but not in the
  295. proper order.  I was getting quite frustrated for a while...
  296.  
  297. My stack was originally 4000 - the default.  I boosted it to 8192 with no
  298. greater results, and finally went to 32768 and now it seems to work.  At least
  299. I can read from the D-10 consistently. ...
  300.