home *** CD-ROM | disk | FTP | other *** search
/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / msdos / edit / modobj / obj_tech.doc < prev    next >
Encoding:
Text File  |  1992-04-15  |  8.9 KB  |  239 lines
  1. Technical Documentation for MODOBJ.  
  2. Revision 0.03
  3.  
  4. To simply playback a module from a program
  5.  
  6.     Call MODINIT
  7.     Call MODDEVICE and remember the device is returns
  8.     Call MODVOLUME to set the volume to maximum
  9.     Call MODSETUP to load and start playback of the module
  10.     Do your programme here
  11.     Call MODSTOP to stop the module
  12.  
  13. Turbo C notes:
  14.  
  15.     Works with all memory models (as long as you declare
  16.     the procedures to be FAR - see example program).  Note that
  17.         the parameters are the other way around to the Pascal ones.
  18.  
  19.     Playback through the speaker is more 'grainy' than under
  20.     turbo pascal.
  21.  
  22.  
  23. Turbo Pascal Notes:
  24.  
  25.     The default is for Turbo Pascal to eat all available memory
  26.     for itself.   You must limit the heap-size otherwise there 
  27.         will be no room for the module.  Look in your Turbo Pascal
  28.         documentation and at the example program for details.
  29.  
  30.  
  31.  
  32. ────────────────────────────────────────────────────────────────────────
  33. Initialize Devices
  34.  
  35. P: procedure modinit;
  36. C: modinit ( void );
  37. ────────────────────────────────────────────────────────────────────────
  38.  
  39.     The first thing you must call before any of these other
  40.     routines.  It intialises internal variables and checks for
  41.     soundblasters and the like.  
  42.  
  43. ────────────────────────────────────────────────────────────────────────
  44. Ask for a Device
  45.  
  46. P: procedure moddevice( var device:integer);
  47. C: moddevice ( int *device );
  48. ────────────────────────────────────────────────────────────────────────
  49.  
  50.     Asks the user to select an output device.  Returns a device number
  51.     in the range 0-255.  (0 is valid, the speaker and 255 is no-sound).
  52.     You need not call this routine as the numeric values it returns
  53.     will be constant for the particular version of MOD-OBJ.  So you
  54.     could ask the user once, then save their preference in a file.
  55.  
  56.     For this version of mod-obj    (other values not used)
  57.  
  58.     0    PC Speaker
  59.     1    D/A converter on LPT1
  60.     2    D/A converter on LPT2
  61.     3    D/A converter on LPT3
  62.     4    D/A converters on LPT1 and LPT2 (stereo)
  63.     5    D/A converters on LPT1 and LPT2 (mono)
  64.     7    Soundblaster card
  65.     10    Stereo-on-1 card
  66.     11    Disney Sound Source on LPT1
  67.     12    Disney Sound Source on LPT2
  68.     13    Disney Sound Source on LPT3
  69.     255    No sound
  70.  
  71.     Note that there is no need for 'user defined' adaptors.  If you
  72.     have two D/A converters on ports 0300 and 0301 say, then simply
  73.     patch the LPT table using debug, and use devices 4 or 5
  74.  
  75.     C:\>debug
  76.     -e 40:8 00 03 01 03            * Enters 0300 0301 as LPT1/2
  77.     -q
  78.  
  79. ────────────────────────────────────────────────────────────────────────
  80. Set the playback volume
  81.  
  82. P: procedure modvolume( v1,v2,v3,v4:integer);
  83. C: modvolume ( int v4, int v3, int v2, int v1 );
  84. ────────────────────────────────────────────────────────────────────────
  85.  
  86.     Sets the module volume for each channel to 'volume'.  Must be
  87.     called before modsetup.   255 is normal, maximum volume.  0 is
  88.     minimum (off).  You can call this routine to change the volume
  89.     whilst a module is playing.  (4 different channels, one volume
  90.         byte for each!)
  91.  
  92. ────────────────────────────────────────────────────────────────────────
  93. Load and Play module
  94.  
  95. P:  procedure modsetup( var status: integer; device, mixspeed:integer; 
  96.             protrack, looping: integer, var filename:string )
  97. C:  modsetup ( char *filename, int looping, int protracker
  98.                 int mixspeed, int device, int *status )
  99. ────────────────────────────────────────────────────────────────────────
  100.  
  101.     Pass this procedure the following data
  102.  
  103.     o The device number found above
  104.     o The mixing speed in Hz (10000 is a good one, 14000 is better
  105.         for the speaker... see what works on your machine).
  106.     o A string giving the filename of the module.
  107.     o Set to 1 if your mod sounds odd when run in protracker mode
  108.       (converts volume slide commands only, might as well leave it
  109.        on 0 )
  110.     o Data on looping    (Normally set this to 4)
  111.         looping = 0    - Stop at end of module
  112.         looping = 1    - Play the first pattern only
  113.         looping = 2     - Play normally but disallow backward jumps
  114.         looping = 4    - At end of module start again
  115.  
  116.     It will return
  117.  
  118.     o Status = 0           with the module playing
  119.     o Status = 1           if there was an error loading/ not a mod
  120.     o Status = 2        if already playing a mod
  121.     o Status = 4        out of memory.
  122.  
  123. ────────────────────────────────────────────────────────────────────────
  124. Stop the module - free memory
  125.  
  126. P:  procedure modstop;
  127. C:  modstop ();
  128. ────────────────────────────────────────────────────────────────────────
  129.     
  130.     Stops the module playback and free's the memory that was
  131.     allocated to it.  MUST stop the mod before exiting to DOS.
  132.     Can call this routine even if there is no module playing
  133.  
  134.  
  135.  
  136. The REGISTERED version also has these functions:
  137. > 
  138. > ────────────────────────────────────────────────────────────────────────
  139. > P: procedure getinsdetails ( ins:integer, var str:string, var len:length )
  140. > C: getinsdetails ( int *length, char *insname, int insnumber );
  141. > ────────────────────────────────────────────────────────────────────────
  142. > 
  143. >     Pass the sample number (1-31) as ins.   It will return with
  144. >     a string giving the name of that instrument, and the length
  145. >     (a length of 0 means no instrument available).
  146. > 
  147.  
  148. > ────────────────────────────────────────────────────────────────────────
  149. > Get values for drawing bars
  150. >
  151. > P:  procedure modbar ( var bar1, bar2, bar3, bar4:integer)
  152. > C:  modbar ( int *bar4, int *bar3, int *bar2, int *bar1);
  153. > ────────────────────────────────────────────────────────────────────────
  154. >
  155. >    Returns four values from 0-63 representing the 'level' of each
  156. >    of the four channels.  Look at Modplay's display to see how
  157. >    this works.
  158. > 
  159. > 
  160. > ────────────────────────────────────────────────────────────────────────
  161. > Find out where you are in the module
  162. >
  163. > P:  procedure modwhereami( var finished, speed, pattpos, songpos:integer)
  164. > C:  modwhereami ( int *songpos, int *pattpos, int *speed, int *finished);
  165. > ────────────────────────────────────────────────────────────────────────
  166. >
  167. >    Gets the current status and postion of the module
  168. > 
  169. >    o Playing    Set to 1 if there is a module playing
  170. >     o Speed        Not useful
  171. >     o Songpos    Position within the song (0 = first pattern, 1 etc
  172. >             keeps adding 1 each time pattpos reaches 1024).
  173. >     o Pattpos    The current pattern (0 - 1024 in steps of 16). 
  174. >             See the MODEDIT docs for details of patterns and
  175. >             songs.
  176. > 
  177. > ────────────────────────────────────────────────────────────────────────
  178. > Set position within the module
  179. >
  180. > P:  procedure modsetpos ( var pattpos, songpos:integer); 
  181. > C:  modsetpos ( int songpos, int pattpos );
  182. > ────────────────────────────────────────────────────────────────────────
  183. > 
  184. >     Sets the current module position to be the values given
  185. >     to this call.  Pattpos gets rounded to nearest 16 bytes.
  186. > 
  187. >
  188.  
  189. > ────────────────────────────────────────────────────────────────────────
  190. > Outputting Samples.
  191. > ────────────────────────────────────────────────────────────────────────
  192. > 
  193. > There are three ways of playing samples whilst a module is playing in
  194. > the background.  (The routine returns, and the sample continues playing).
  195. > 
  196. > Spotsample:  The first will play one of the samples that is contained
  197. >          within the module
  198. > 
  199. > Spotsample3: The next will load a sample and play it - when the sample
  200. >          has ended the memory it took up will be free-d straight
  201. >          automatically.
  202. > 
  203. > ────────────────────────────────────────────────────────────────────────
  204. > P:  procedure spotsample ( sample,frequency:integer );
  205. > C:  spotsample ( int frequency, int sample );
  206. > ────────────────────────────────────────────────────────────────────────
  207. > 
  208. >     This command lets you play a sample over the top of the mod.
  209. >     The main module volume is halved and the sample is mixed in
  210. >     with the playback.  As soon as the sample has finished playing
  211. >     the original module volume is restored.
  212. >     In stereo mode, the sample is output to both the left and
  213. >     right channels.  Looping samples don't loop.
  214. > 
  215. >     Pass this procedure the sample number (1 to 31) from the module
  216. >     and the 'frequency'.  Actually this number corresponds similar
  217. >     to the mod notes, so to play back at C-1 use 856.  Similarly
  218. >     C2 - 428,  C3 - 214 etc.  Any value 1-1000 can be used.
  219. > 
  220. > 
  221. > ────────────────────────────────────────────────────────────────────────
  222. > P:  procedure spotsample3 ( var status: integer
  223. >                frequency:integer, filename:string );
  224. > C:  spotsample3 ( int *status, int frequenct, char *filename );
  225. > ────────────────────────────────────────────────────────────────────────
  226. > 
  227. >     Similar to spotsample in operation.  Plays a sample that isn't
  228. >     in the module over the top.  Give the filename of the sample.
  229. >    The sample is loaded, played and then the space free'd  all in
  230. >    the background.
  231. >
  232. >    Status     = 0     Okay
  233. >        = 1    Loading error (file not found)
  234. >        = 2    Out of memory
  235. >
  236. >    If a sample was already playing, then the old sample is stopped and
  237. >    free'd before the new sample is loaded/played.
  238.  
  239.